Smoke test packaged Linux AppImage in release CI

Prepare Frame Control v0.4.35

.github/workflows/release.yml

@@ -10,7 +10,7 @@ on:
   push:
     tags: ["v*"]
   pull_request:
-    paths: ["app/**", "desktop/**", "mac/frame-mac-view/**", ".github/workflows/release.yml"]
+    paths: ["app/**", "desktop/**", "mac/frame-mac-view/**", "scripts/check-appimage-launch.py", ".github/workflows/release.yml"]
   workflow_dispatch:
 
 # A newer push to the same pull request supersedes a build still in progress.
@@ -110,6 +110,9 @@ jobs:
         run: npm ci && npm run ${{ matrix.script }}
         env:
           CSC_IDENTITY_AUTO_DISCOVERY: "false"
+      - name: Launch the built Linux AppImage
+        if: matrix.os == 'ubuntu-latest'
+        run: python3 scripts/check-appimage-launch.py app/dist/Frame-Control-linux-x86_64.AppImage
       # The installer, not just the unpacked build: its 7-Zip payload once dropped
       # the OpenXR layer's arm64 library without any error. Install it silently
       # and compare every installed file with the unpacked build.

app/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "frame-control",
-  "version": "0.4.34",
+  "version": "0.4.35",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "frame-control",
-      "version": "0.4.34",
+      "version": "0.4.35",
       "license": "MIT",
       "devDependencies": {
         "electron": "^44.4.5",

app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frame-control",
   "productName": "Frame Control",
-  "version": "0.4.34",
+  "version": "0.4.35",
   "description": "Desktop app for managing a Valve Steam Frame over SSH",
   "private": true,
   "main": "main.js",

docs/current-support-matrix.md

@@ -1,6 +1,6 @@
 # What we have tested
 
-Current for Frame Control **v0.4.34**, 25 October 2026. “Real Frame + physical PC” means an actual headset and a non-virtual computer. “VM only” means a Windows virtual machine, sometimes connected to the real Frame. A CI test or a simulated device is **not** a physical hardware test. The date/version column is the last relevant check, not a promise that every new release was retested on that platform. See each link for the exact procedure and limits.
+Current for Frame Control **v0.4.35**, 25 October 2026. “Real Frame + physical PC” means an actual headset and a non-virtual computer. “VM only” means a Windows virtual machine, sometimes connected to the real Frame. A CI test or a simulated device is **not** a physical hardware test. The date/version column is the last relevant check, not a promise that every new release was retested on that platform. See each link for the exact procedure and limits.
 
 | Feature | Real Frame + physical PC tested | VM only | Untested or limited | Last check and proof |
 |---|---|---|---|---|
@@ -23,7 +23,7 @@ Current for Frame Control **v0.4.34**, 25 October 2026. “Real Frame + physical
 | Open at login | No Frame needed; Linux autostart file toggled on a physical Linux host with an isolated config directory | No | A full login session and physical Windows/macOS host login have not been checked; OS API calls were unit tested | 25 Oct, v0.4.26: [PR #189](https://github.com/saphid/frame-control/pull/189) |
 | Local Frame Control extensions | Example panel displayed live Frame status in a browser preview; the real Frame served a read-only example in the experimental headset panel | No | No wearer-visible extension view; third-party extensions and physical Windows/macOS extension folders untested | 25 Oct, v0.4.29: [PR #194](https://github.com/saphid/frame-control/pull/194), [PR #201](https://github.com/saphid/frame-control/pull/201), [extension guide](extensions.md) |
 | Experimental Frame Control SteamVR panel | Real Frame OS 0.5.6 installed its user service, registered an overlay, served authenticated live status and a read-only extension, saved a screenshot and short MP4, and removed owned resources | No | Headset was unworn in standby: overlay reported `not_visible`, stereo capture was dark; wearer-visible pixels and controller input are unverified. The new large read-only status screen has browser layout and packaging checks only | 25 Oct, v0.4.29 device check and v0.4.31 status screen: [PR #198](https://github.com/saphid/frame-control/pull/198), [PR #201](https://github.com/saphid/frame-control/pull/201), [PR #220](https://github.com/saphid/frame-control/pull/220), [panel guide](headset-app.md) |
-| Experimental Decky Loader manager | Real Frame OS 0.5.6 ARM64 user-service install, status, update and remove completed; seven official-store plugin backends loaded, and ProtonDB Badges completed managed store install/update/remove | No | v0.4.33 shared transaction lock and stopped-loader plugin removal have Linux and CI tests, but no live recovery test on the Frame. Plugin pages, settings, routes, toasts and controller input in VR remain unverified; some plugins need root, x86_64 binaries or Deck-specific hardware | 25 Oct, v0.4.31 hardware and v0.4.33 tests: [PR #208](https://github.com/saphid/frame-control/pull/208), [PR #230](https://github.com/saphid/frame-control/pull/230), [PR #234](https://github.com/saphid/frame-control/pull/234), [compatibility table](decky-frame.md) |
-| Experimental Framey VR plugin panels and store | No live real-Frame panel test | No | ProtonDB Badges settings rendered and sent a setting call in local Chromium. Fake Frame tests cover setting read/write through update and reinstall and install/remove two pinned official API v2 archives. Page tests cover the official JSX runtime, disabled controls, text fields, sliders, grouped dropdowns and an author sample bundle. The sample is not published in the store. The 11-archive manifest audit found only ProtonDB Badges API v2 in that set; a hash match and fake Frame install do not prove VR use. Wearer-visible pixels, controller input and live settings persistence remain unverified | 25 Oct, v0.4.32–0.4.34: [#223](https://github.com/saphid/frame-control/pull/223), [#224](https://github.com/saphid/frame-control/pull/224), [#225](https://github.com/saphid/frame-control/pull/225), [#226](https://github.com/saphid/frame-control/pull/226), [#227](https://github.com/saphid/frame-control/pull/227), [#229](https://github.com/saphid/frame-control/pull/229), [#231](https://github.com/saphid/frame-control/pull/231), [#232](https://github.com/saphid/frame-control/pull/232), [#233](https://github.com/saphid/frame-control/pull/233), [#236](https://github.com/saphid/frame-control/pull/236), [#237](https://github.com/saphid/frame-control/pull/237), [#238](https://github.com/saphid/frame-control/pull/238), [#239](https://github.com/saphid/frame-control/pull/239), [#240](https://github.com/saphid/frame-control/pull/240), [#241](https://github.com/saphid/frame-control/pull/241), [browser/fake Frame evidence](evidence/framey-browser-2026-10-25.md), [guide](framey-loader.md) |
+| Experimental Decky Loader manager | Real Frame OS 0.5.6 ARM64 user-service install, status, update and remove completed; seven official-store plugin backends loaded, and ProtonDB Badges completed managed store install/update/remove | No | v0.4.33 shared transaction lock and stopped-loader plugin removal have Linux and CI tests, but no live recovery test on the Frame. v0.4.35 treats `_root` store tags as root-required and hides duplicate IDs; this has test coverage, not a live store check. Plugin pages, settings, routes, toasts and controller input in VR remain unverified; some plugins need root, x86_64 binaries or Deck-specific hardware | 25 Oct, v0.4.31 hardware and v0.4.35 tests: [PR #208](https://github.com/saphid/frame-control/pull/208), [PR #230](https://github.com/saphid/frame-control/pull/230), [PR #234](https://github.com/saphid/frame-control/pull/234), [PR #246](https://github.com/saphid/frame-control/pull/246), [compatibility table](decky-frame.md) |
+| Experimental Framey VR plugin panels and store | No live real-Frame panel test | No | ProtonDB Badges settings rendered and sent a setting call in local Chromium. Official Steam Status rendered in local Chromium; a session-only cache avoided its earlier storage errors. A later local browser check restored a bounded per-plugin cache after panel reopen; live Decky and offline behavior were not tested. Fake Frame tests cover setting read/write through update and reinstall and install/remove two pinned official API v2 archives plus the modern API v1 Storage Cleaner archive. Page tests cover the official JSX runtime, disabled controls, text fields, sliders, grouped dropdowns and an author sample bundle with a settings tab and read-only backend quick action. The sample is not published in the store. The 11-archive manifest audit found only ProtonDB Badges API v2 in that set. Storage Cleaner 1.4.0 showed an empty-data panel and four disabled cleanup buttons in local Chromium with a stub backend; no cleanup action was tested. A hash match, local panel and fake Frame install do not prove VR use. Wearer-visible pixels, controller input and live settings persistence remain unverified | 25 Oct, v0.4.32–0.4.35: [#223](https://github.com/saphid/frame-control/pull/223), [#224](https://github.com/saphid/frame-control/pull/224), [#225](https://github.com/saphid/frame-control/pull/225), [#226](https://github.com/saphid/frame-control/pull/226), [#227](https://github.com/saphid/frame-control/pull/227), [#229](https://github.com/saphid/frame-control/pull/229), [#231](https://github.com/saphid/frame-control/pull/231), [#232](https://github.com/saphid/frame-control/pull/232), [#233](https://github.com/saphid/frame-control/pull/233), [#236](https://github.com/saphid/frame-control/pull/236), [#237](https://github.com/saphid/frame-control/pull/237), [#238](https://github.com/saphid/frame-control/pull/238), [#239](https://github.com/saphid/frame-control/pull/239), [#240](https://github.com/saphid/frame-control/pull/240), [#241](https://github.com/saphid/frame-control/pull/241), [#243](https://github.com/saphid/frame-control/pull/243), [#244](https://github.com/saphid/frame-control/pull/244), [#245](https://github.com/saphid/frame-control/pull/245), [#247](https://github.com/saphid/frame-control/pull/247), [#248](https://github.com/saphid/frame-control/pull/248), [browser/fake Frame evidence](evidence/framey-browser-2026-10-25.md), [guide](framey-loader.md) |
 
 Release notes must preserve these limits until a newer recorded check changes them. When a feature is retested, add its date, exact app/Frame version, host type and proof here. The older [v0.3.1 matrix](support-matrix.html) is a historical snapshot and does not describe current coverage.

docs/releasing.md

@@ -20,6 +20,10 @@ count. So a build reaches people only when you publish it, after testing it.
    GitHub temporarily show its tag as `untagged-…`. The workflow finds that
    draft by its exact version title, restores the tag association and retries
    the affected upload; it refuses ambiguous matches.
+   The Linux build runs `scripts/check-appimage-launch.py` before upload. It
+   starts the built x86_64 AppImage on an isolated Xvfb display, checks that
+   its bundled server answers, and checks that the server stops on exit. This
+   CI test does not test a physical display, FUSE mount or a headset.
 
 2. Download the draft's installers and test them. An installed copy of the
    previous version won't offer the draft, so install it directly.

scripts/check-appimage-launch.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Launch a built Linux AppImage on Xvfb and check its bundled server.
+
+This checks the packaged app without a headset or a desktop login session.
+The profile and display are temporary, and every process started by this check
+is stopped before it exits.
+"""
+
+import hashlib
+import os
+from pathlib import Path
+import re
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+
+
+def server_port(profile):
+    for log in (profile / "config").rglob("server.log"):
+        ports = re.findall(r"--port (\d+)", log.read_text(errors="replace"))
+        if ports:
+            return int(ports[-1])
+    return None
+
+
+def port_closed(port):
+    try:
+        with socket.create_connection(("127.0.0.1", port), timeout=1):
+            return False
+    except OSError:
+        return True
+
+
+def check(appimage):
+    if not appimage.is_file() or not os.access(appimage, os.X_OK):
+        raise RuntimeError(f"AppImage is missing or cannot run: {appimage}")
+    if not shutil.which("xvfb-run"):
+        raise RuntimeError("xvfb-run is required for the AppImage smoke check")
+    digest = hashlib.sha256(appimage.read_bytes()).hexdigest()
+    with tempfile.TemporaryDirectory(prefix="frame-appimage-smoke-") as directory:
+        profile = Path(directory)
+        env = dict(os.environ)
+        env.update(
+            APPIMAGE_EXTRACT_AND_RUN="1", ELECTRON_DISABLE_SANDBOX="1",
+            XDG_CONFIG_HOME=str(profile / "config"),
+            XDG_CACHE_HOME=str(profile / "cache"),
+            XDG_DATA_HOME=str(profile / "data"),
+            FRAME_ALIAS="frame-control-appimage-smoke-no-headset",
+        )
+        output = profile / "app.log"
+        port = None
+        passed = False
+        with output.open("w") as log:
+            proc = subprocess.Popen(
+                ["xvfb-run", "-a", "-s", "-screen 0 1280x800x24 -nolisten tcp",
+                 str(appimage), "--no-sandbox"],
+                cwd=profile, env=env, stdout=log, stderr=subprocess.STDOUT,
+                start_new_session=True,
+            )
+            try:
+                deadline = time.monotonic() + 60
+                while time.monotonic() < deadline:
+                    if proc.poll() is not None:
+                        raise RuntimeError(f"AppImage exited {proc.returncode} before its server answered")
+                    port = server_port(profile)
+                    if port is not None:
+                        try:
+                            with urllib.request.urlopen(f"http://127.0.0.1:{port}/", timeout=2) as response:
+                                if response.status == 200 and response.headers.get("Server", "").startswith("FrameControl/1"):
+                                    passed = True
+                                    break
+                        except (OSError, urllib.error.URLError):
+                            pass
+                    time.sleep(0.5)
+                if not passed:
+                    raise RuntimeError("AppImage server did not answer within 60 seconds")
+            except BaseException:
+                log.flush()
+                print(output.read_text(errors="replace")[-1500:], file=sys.stderr)
+                raise
+            finally:
+                try:
+                    os.killpg(proc.pid, signal.SIGTERM)
+                except ProcessLookupError:
+                    pass
+                try:
+                    proc.wait(timeout=15)
+                except subprocess.TimeoutExpired:
+                    os.killpg(proc.pid, signal.SIGKILL)
+                    proc.wait(timeout=10)
+        if port is not None:
+            for _ in range(20):
+                if port_closed(port):
+                    break
+                time.sleep(0.5)
+            else:
+                raise RuntimeError(f"AppImage server stayed on port {port} after shutdown")
+    print(f"AppImage SHA-256 {digest}: HTTP 200, FrameControl/1, server stopped")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        raise SystemExit("usage: check-appimage-launch.py path/to/AppImage")
+    check(Path(sys.argv[1]).resolve())