feat(flathub): finalize Flathub manifest against the v1.9.4 .deb

.github/workflows/flathub-validate.yml

@@ -0,0 +1,135 @@
+name: Flathub Validate
+
+# Validates the Flathub submission assets the same way Flathub CI does:
+# flatpak-builder-lint on the manifest + AppStream metadata, then a real
+# build + install of the extra-data manifest, which downloads the published
+# .deb and runs apply_extra.sh — an end-to-end test of the install path.
+on:
+  pull_request:
+    paths:
+      - 'flathub/**'
+      - '.github/workflows/flathub-validate.yml'
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out Git repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: 🐧 Install flatpak
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y flatpak dbus
+
+      # Ubuntu 24.04 runners restrict unprivileged user namespaces via AppArmor,
+      # which breaks bwrap (used by flatpak to run apply_extra at install time).
+      - name: 🐧 Allow unprivileged user namespaces (bwrap)
+        run: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+
+      # Pre-install the build deps here: host-level `flatpak install` works without
+      # a session bus, whereas flatpak-builder's internal install calls need D-Bus
+      # (hence dbus-run-session on the build step below).
+      - name: 🐧 Install org.flatpak.Builder + runtimes
+        run: |
+          flatpak remote-add --if-not-exists --user flathub https://dl.flathub.org/repo/flathub.flatpakrepo
+          flatpak install -y --user flathub \
+            org.flatpak.Builder \
+            org.freedesktop.Platform//25.08 \
+            org.freedesktop.Sdk//25.08 \
+            org.electronjs.Electron2.BaseApp//25.08
+
+      # appid-url-not-reachable is tolerated (with a warning): wcpos.com's bot
+      # protection returns 403 to the linter's HTTP client. It must still be
+      # resolved before the Flathub submission — either allow the linter through
+      # the WAF or request a linter exception from Flathub reviewers.
+      - name: 🔍 Lint manifest
+        working-directory: flathub
+        run: |
+          out=$(flatpak run --command=flatpak-builder-lint org.flatpak.Builder manifest com.wcpos.main.yml) || true
+          echo "$out"
+          remaining=$(echo "$out" | jq '[.errors[]? | select(. != "appid-url-not-reachable")] | length')
+          if [ "$remaining" -gt 0 ]; then
+            echo "::error::flatpak-builder-lint reported blocking manifest errors"
+            exit 1
+          fi
+          if echo "$out" | jq -e '.errors[]? | select(. == "appid-url-not-reachable")' > /dev/null; then
+            echo "::warning title=appid-url-not-reachable::wcpos.com returns 403 to flatpak-builder-lint (bot protection). Allow the linter through the WAF or request a Flathub linter exception before submitting."
+          fi
+
+      - name: 🔍 Lint AppStream metadata
+        working-directory: flathub
+        run: flatpak run --command=flatpak-builder-lint org.flatpak.Builder appstream com.wcpos.main.metainfo.xml
+
+      # Build WITHOUT --install: flatpak-builder would otherwise run the install
+      # (and apply_extra's bwrap) inside the org.flatpak.Builder sandbox, where
+      # nested user namespaces are blocked. Export to a local OSTree repo instead
+      # and install from the host — the same split Flathub's CI uses.
+      - name: 🏗 Build (exports to local OSTree repo)
+        working-directory: flathub
+        run: |
+          dbus-run-session -- flatpak run org.flatpak.Builder --user --force-clean \
+            --repo=repo --install-deps-from=flathub build-dir com.wcpos.main.yml
+
+      - name: 🏗 Install from local repo (exercises extra-data / apply_extra.sh)
+        working-directory: flathub
+        run: |
+          flatpak remote-add --user --no-gpg-verify local-repo repo
+          flatpak install -y --user local-repo com.wcpos.main
+
+      - name: ✅ Verify installed app layout
+        run: |
+          flatpak info --user com.wcpos.main
+          # apply_extra runs at install time; confirm the unpacked Electron binary landed in /app/extra.
+          if ! find "$HOME/.local/share/flatpak/app/com.wcpos.main" -name WooCommercePOS -type f | grep -q .; then
+            echo "::error::WooCommercePOS binary missing from the installed app — apply_extra.sh failed"
+            exit 1
+          fi
+
+      # StartupWMClass in the .desktop must match the running app's WM_CLASS or the
+      # window won't associate with the launcher. Install the same published .deb the
+      # manifest references, run it under Xvfb, and read the class off the real window.
+      - name: 🔍 Verify StartupWMClass matches the running app
+        run: |
+          sudo apt-get install -y xvfb xdotool x11-utils
+          deb_url=$(grep -oE 'https://[^ ]+\.deb' flathub/com.wcpos.main.yml | head -1)
+          curl -sLo /tmp/wcpos.deb "$deb_url"
+          sudo apt-get install -y /tmp/wcpos.deb
+          Xvfb :99 -screen 0 1280x800x24 &
+          export DISPLAY=:99
+          sleep 2
+          /usr/lib/woocommerce-pos/WooCommercePOS --no-sandbox --disable-gpu > /tmp/wcpos-app.log 2>&1 &
+          expected=$(sed -n 's/^StartupWMClass=//p' flathub/com.wcpos.main.desktop)
+          echo "Expected StartupWMClass: $expected"
+          found=""
+          visible_classes=""
+          for _attempt in $(seq 1 60); do
+            wids=$( (xdotool search --name '.*' 2>/dev/null; xdotool search --class '.*' 2>/dev/null) | sort -u)
+            visible_classes=""
+            for wid in $wids; do
+              wmclass=$(xprop -id "$wid" WM_CLASS 2>/dev/null | sed -n 's/.*= //p')
+              [ -z "$wmclass" ] && continue
+              info=$(xwininfo -id "$wid" 2>/dev/null || true)
+              state=$(echo "$info" | sed -n 's/.*Map State: //p')
+              geom=$(echo "$info" | sed -n 's/^  -geometry //p')
+              echo "window $wid: class=$wmclass state=$state geometry=$geom"
+              if [ "$state" = "IsViewable" ]; then
+                visible_classes="$visible_classes $wmclass"
+                if echo "$wmclass" | grep -q "\"$expected\""; then
+                  found="yes"
+                fi
+              fi
+            done
+            [ -n "$found" ] && break
+            sleep 2
+          done
+          if [ -z "$found" ]; then
+            echo "--- app log ---"; tail -50 /tmp/wcpos-app.log || true
+            echo "::error::No VISIBLE window has WM_CLASS containing \"$expected\". Visible window classes:$visible_classes — set StartupWMClass in com.wcpos.main.desktop to the visible window's class."
+            exit 1
+          fi
+          echo "Visible window WM_CLASS matches StartupWMClass=$expected"

.github/workflows/tag-and-release.yml

@@ -262,9 +262,9 @@ jobs:
           sudo apt-get install -y flatpak flatpak-builder elfutils
           flatpak remote-add --if-not-exists --user flathub https://dl.flathub.org/repo/flathub.flatpakrepo
           flatpak install -y --user flathub \
-            org.freedesktop.Platform//24.08 \
-            org.freedesktop.Sdk//24.08 \
-            org.electronjs.Electron2.BaseApp//24.08
+            org.freedesktop.Platform//25.08 \
+            org.freedesktop.Sdk//25.08 \
+            org.electronjs.Electron2.BaseApp//25.08
 
       - name: 📦 Make Flatpak bundle (non-blocking)
         id: make-flatpak

flathub/apply_extra.sh

@@ -2,17 +2,18 @@
 # Runs at install time with the working directory set to /app/extra.
 # Unpacks the prebuilt .deb and flattens the app payload into /app/extra so the
 # launcher can exec /app/extra/WooCommercePOS.
+#
+# bsdtar reads the .deb (ar) container and the nested data tarball regardless of
+# compression (.xz/.gz/.zst). GNU ar (binutils) is NOT in the Freedesktop
+# *Platform* runtime that apply_extra runs against — only the Sdk — so `ar x`
+# would fail at install time. This mirrors other extra-data .deb manifests on
+# Flathub (e.g. com.google.Chrome).
 set -e
 
-ar x woocommerce-pos.deb
-rm -f debian-binary control.tar.* woocommerce-pos.deb
+bsdtar -Oxf woocommerce-pos.deb 'data.tar.*' | bsdtar -xf -
+rm -f woocommerce-pos.deb
 
-# data.tar may be .xz, .gz or .zst depending on the dpkg version that built it.
-tar xf data.tar.*
-rm -f data.tar.*
-
-# electron-installer-deb lays the app down under /usr/lib/<package-name>/.
-# Confirm this path against a real .deb (`dpkg -c <file>.deb`) before submitting —
-# the package name is derived from the productName ("woocommerce-pos").
+# electron-installer-deb lays the app down under /usr/lib/<package-name>/
+# (verified against woocommerce-pos_1.9.4_amd64.deb).
 mv usr/lib/woocommerce-pos/* .
 rm -rf usr

flathub/com.wcpos.main.desktop

@@ -10,5 +10,7 @@ Categories=Office;Finance;
 MimeType=x-scheme-handler/wcpos;
 StartupNotify=true
 # Must match the Electron app's WM class so the window maps to this .desktop file.
-# Confirm with `xprop WM_CLASS` on a running build; usually the productName (WCPOS).
-StartupWMClass=WCPOS
+# Measured via xprop under Xvfb in CI (flathub-validate.yml): the app's windows
+# report classes "wcpos" (app-name derived) and "WooCommercePOS" (binary derived);
+# the visible main window uses "wcpos".
+StartupWMClass=wcpos

flathub/com.wcpos.main.metainfo.xml

@@ -30,18 +30,33 @@
   <url type="help">https://docs.wcpos.com</url>
 
   <!-- Flathub REQUIRES at least one screenshot with a publicly reachable image URL.
-       Replace these placeholders with real hosted screenshots before submitting. -->
+       This is the WordPress.org plugin-directory asset (stable, 2048x1536). -->
   <screenshots>
     <screenshot type="default">
-      <caption>The WCPOS checkout</caption>
-      <image>https://wcpos.com/screenshots/pos-checkout.png</image>
+      <caption>The WCPOS main screen</caption>
+      <image>https://ps.w.org/woocommerce-pos/assets/screenshot-1.png</image>
     </screenshot>
   </screenshots>
 
   <content_rating type="oars-1.1" />
 
   <!-- Keep the newest release first. Update each time a new version is published. -->
   <releases>
+    <release version="1.9.4" date="2026-06-12">
+      <description>
+        <p>Windows raw USB printing routed through the print spooler; improved web printer setup with Local Network Access support; receipt tax breakdown fixes; expanded product sorting; updated translations.</p>
+      </description>
+    </release>
+    <release version="1.9.3" date="2026-06-09">
+      <description>
+        <p>Fixed a startup failure after updating from 1.9.2 caused by a missing packaged USB module.</p>
+      </description>
+    </release>
+    <release version="1.9.2" date="2026-06-09">
+      <description>
+        <p>Star Online cloud printing, redesigned printer settings, product sorting controls and server-side PDF receipts.</p>
+      </description>
+    </release>
     <release version="1.9.1" date="2026-05-19">
       <description>
         <p>Updated bundled translations.</p>

flathub/com.wcpos.main.yml

@@ -10,18 +10,19 @@
 # Electron Forge. See flathub/README.md for how to finalise and submit it.
 app-id: com.wcpos.main
 runtime: org.freedesktop.Platform
-runtime-version: '24.08' # TODO: confirm latest non-EOL Freedesktop runtime at submission time
+runtime-version: '25.08' # latest Freedesktop runtime branch (verified 2026-06: BaseApp branch/25.08 exists)
 sdk: org.freedesktop.Sdk
 base: org.electronjs.Electron2.BaseApp
-base-version: '24.08' # must match runtime-version
+base-version: '25.08' # must match runtime-version
 command: wcpos
 separate-locales: false
 
 # Keep in sync with `finishArgs` of MakerFlatpak in forge.config.ts.
 finish-args:
   - --share=ipc
   - --share=network # TCP / ESC-POS network printers + sync
-  - --socket=x11
+  # No plain --socket=x11: flatpak-builder-lint rejects x11 combined with
+  # wayland/fallback-x11; fallback-x11 grants X11 only when Wayland is absent.
   - --socket=fallback-x11
   - --socket=wayland
   - --socket=pulseaudio
@@ -41,14 +42,14 @@ modules:
       - install -Dm644 icon-256.png /app/share/icons/hicolor/256x256/apps/com.wcpos.main.png
     sources:
       # The prebuilt .deb (package name is woocommerce-pos), downloaded on the user's
-      # machine at install time. sha256/size MUST be regenerated against the real
-      # published artifact — flatpak-external-data-checker (x-checker-data) automates
-      # this per release.
+      # machine at install time. sha256/size are regenerated against the real
+      # published artifact on every release — flatpak-external-data-checker
+      # (x-checker-data) automates this per release.
       - type: extra-data
         filename: woocommerce-pos.deb
-        url: https://github.com/wcpos/electron/releases/download/v1.9.1/woocommerce-pos_1.9.1_amd64.deb # TODO: confirm exact asset name
-        sha256: 0000000000000000000000000000000000000000000000000000000000000000 # TODO
-        size: 0 # TODO: bytes of the .deb
+        url: https://github.com/wcpos/electron/releases/download/v1.9.4/woocommerce-pos_1.9.4_amd64.deb
+        sha256: 2b1c74dbb760a85dc9838f47657c36b74136aa5125f4cf8a093b0c45f8024b01
+        size: 95721396
         x-checker-data:
           type: html
           url: https://github.com/wcpos/electron/releases/latest

forge.config.ts

@@ -172,9 +172,9 @@ const config: ForgeConfig = {
 								// Electron BaseApp + Freedesktop runtime is the recommended pairing for Electron.
 								// NOTE: confirm these are still the latest non-EOL branches at release time.
 								base: 'org.electronjs.Electron2.BaseApp',
-								baseVersion: '24.08',
+								baseVersion: '25.08',
 								runtime: 'org.freedesktop.Platform',
-								runtimeVersion: '24.08',
+								runtimeVersion: '25.08',
 								sdk: 'org.freedesktop.Sdk',
 								icon: path.resolve(__dirname, 'icons/icon.png'),
 								categories: ['Office', 'Finance'],
@@ -185,7 +185,8 @@ const config: ForgeConfig = {
 								finishArgs: [
 									'--share=ipc',
 									'--share=network',
-									'--socket=x11',
+									// No plain --socket=x11: Flathub's linter rejects x11 combined with
+									// wayland/fallback-x11; fallback-x11 covers X11-only sessions.
 									'--socket=fallback-x11',
 									'--socket=wayland',
 									'--socket=pulseaudio',