Document packaged Return to Game Mode button verification

Document packaged desktop Steam clip Export verification (#156 )
Co-authored-by: SAPHID <saphid@users.noreply.github.com>
2026-10-24 14:01:46 +02:00 · 2026-10-24 09:29:56 +00:00 · 2026-10-24 09:19:46 +00:00 · 2026-10-24 09:17:14 +00:00 · 2026-10-24 09:05:12 +00:00 · 2026-10-24 08:43:00 +00:00
32 changed files with 1321 additions and 102 deletions
@@ -2,6 +2,20 @@

 ## Unreleased

+- Distinguish an unreadable gamescope panel list from a confirmed empty list in
+  Desktop Capture and Control (issue #73). Failed discovery now asks users to
+  check SteamVR and report the exact message and SteamOS version, rather than
+  claiming no panel is open. This does not establish a new capture fix.
+
+- Add an opt-in desktop low-battery alert without starting a family session.
+  Existing status reads confirm low charge and drain; recovery hysteresis and a
+  ten-minute cooldown limit repeat alerts. Off on page open/headset switch;
+  pauses with hidden-page status refreshes. No extra polling or headset changes.
+
+- Clarify first-time desktop downloads, installation and opening on the website
+  and README, including CPU choices, unsigned-app warnings, pairing fallback
+  and the source-only iOS build. Keep section navigation available on mobile.
+
 - Treat headset aliases and other CSV metadata as plain text in power and heat
  exports, so spreadsheet formula prefixes cannot run when a report is opened.

@@ -7,9 +7,9 @@
 **Manage your Valve Steam Frame from your computer.**<br>
 See what the headset sees, install games and Android apps, move files and text across, and check battery and status, all over SSH.

-[![Latest release](https://img.shields.io/github/v/release/saphid/steam-frame?label=release&color=1a9fff)](https://github.com/saphid/steam-frame/releases/latest)
+[![Latest release](https://img.shields.io/github/v/release/saphid/frame-control?label=release&color=1a9fff)](https://github.com/saphid/frame-control/releases/latest)
 [![Platforms](https://img.shields.io/badge/macOS%20%7C%20Windows%20%7C%20Linux-2a475e?label=runs%20on)](#install)
-[![Checks](https://img.shields.io/github/actions/workflow/status/saphid/steam-frame/checks.yml?branch=main&label=checks)](https://github.com/saphid/steam-frame/actions/workflows/checks.yml)
+[![Checks](https://img.shields.io/github/actions/workflow/status/saphid/frame-control/checks.yml?branch=main&label=checks)](https://github.com/saphid/frame-control/actions/workflows/checks.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-66c0f4)](LICENSE)

 [**Website**](https://frame-control.pages.dev) · [**Download**](#install) · [Trailer](#trailer) · [Features](#features) · [Set up the headset](#set-up-the-headset) · [Feedback](#feedback) · [Docs](#going-further)
@@ -19,7 +19,7 @@ See what the headset sees, install games and Android apps, move files and text a
 <img src="docs/img/frame-control.png" alt="Frame Control's Games tab: installed games, sideloaded titles, and your Steam library with Frame ratings" width="900">

 <a id="trailer"></a>
-<a href="https://github.com/saphid/steam-frame/releases/download/trailer/frame-control-trailer.mp4"><img src="docs/img/trailer.jpg" alt="Watch the Frame Control trailer" width="900"></a>
+<a href="https://github.com/saphid/frame-control/releases/download/trailer/frame-control-trailer.mp4"><img src="docs/img/trailer.jpg" alt="Watch the Frame Control trailer" width="900"></a>

 <sub>The trailer: 66 seconds, with sound. Downloads the MP4 from the trailer release.</sub>

@@ -116,17 +116,30 @@ already ships (sideloading a game copies Valve's own devkit scripts to

 ## Install

+**Install Frame Control on your computer, not on the headset.** The website is
+for downloads and instructions; it does not connect to your Frame in a browser.
+Choose the operating system and processor of the computer you will use.
+
 | | Download | Needs |
 |---|---|---|
-| **macOS** (Apple Silicon) | [Frame-Control-mac-arm64.dmg](https://github.com/saphid/steam-frame/releases/latest/download/Frame-Control-mac-arm64.dmg) | Nothing extra |
-| **Windows** 10 / 11 (x64) | [Frame-Control-Setup-x64.exe](https://github.com/saphid/steam-frame/releases/latest/download/Frame-Control-Setup-x64.exe) · [portable .zip](https://github.com/saphid/steam-frame/releases/latest/download/Frame-Control-win-x64.zip) | Nothing extra |
-| **Linux** (x64) | [AppImage](https://github.com/saphid/steam-frame/releases/latest/download/Frame-Control-linux-x86_64.AppImage) · [.deb](https://github.com/saphid/steam-frame/releases/latest/download/Frame-Control-linux-amd64.deb) | `ssh` (most desktops have it) |
-| **Linux** (arm64) | [AppImage](https://github.com/saphid/steam-frame/releases/latest/download/Frame-Control-linux-arm64.AppImage) · [.deb](https://github.com/saphid/steam-frame/releases/latest/download/Frame-Control-linux-arm64.deb) | `ssh`, and `adb` for Android apps (`sudo apt install adb`) |
+| **macOS** (Apple Silicon) | [Frame-Control-mac-arm64.dmg](https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-mac-arm64.dmg) | Nothing extra |
+| **Windows** 10 / 11 (x64) | [Frame-Control-Setup-x64.exe](https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-Setup-x64.exe) · [portable .zip](https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-win-x64.zip) | OpenSSH Client (normally installed) |
+| **Linux** (x64) | [AppImage](https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-linux-x86_64.AppImage) · [.deb](https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-linux-amd64.deb) | `ssh` (most desktops have it) |
+| **Linux** (arm64) | [AppImage](https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-linux-arm64.AppImage) · [.deb](https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-linux-arm64.deb) | `ssh`, and `adb` for Android apps (`sudo apt install adb`) |

-**iPhone and iPad:** the same features from your phone, with nothing to install on
-a computer. Build it from [`ios/`](ios) in Xcode; see [docs/iphone.md](docs/iphone.md).
+**Which build?** On a Mac, check Apple menu → About This Mac: the download is
+for Apple Silicon (M-series); no Intel Mac build is published. On Windows,
+check Settings → System → About → System type: the release is x64, not a native
+Windows ARM build. On Linux, `uname -m` reports `x86_64` (x64) or `aarch64`
+(arm64). Use `.deb` on Debian/Ubuntu, or AppImage on other distributions.

-The app brings its own Python and `adb`; SSH is built into macOS and Windows.
+**iPhone and iPad:** no App Store, TestFlight or `.ipa` download is provided in
+the current release. It runs from your phone without a computer after setup.
+Build it from [`ios/`](ios) in Xcode on a Mac with your own signing team; see
+[docs/iphone.md](docs/iphone.md).
+
+The app brings its own Python and `adb`. macOS includes SSH; Windows needs the
+OpenSSH Client optional feature (normally installed).
 From 0.4 it updates itself: when a new version is published, a banner offers
 **Update and restart**. It sends anonymous usage statistics, which you can turn
 off. Sharing compatibility results and error details is opt-in. See
@@ -139,7 +152,7 @@ distribution's. If you already have `adb`, the app uses yours.

 There's no paid Apple developer account behind it, so macOS says the app is
 damaged or can't be checked. Drag it to Applications, then clear the download
-quarantine once:
+quarantine once, only for a download you trust from the releases linked above:

 ```sh
 xattr -dr com.apple.quarantine "/Applications/Frame Control.app"
@@ -168,26 +181,44 @@ If it complains about FUSE, install `libfuse2` (Ubuntu 24.04+: `libfuse2t64`),
 or run it with `--appimage-extract-and-run`.
 </details>

+## Open the app
+
+- **macOS:** open the `.dmg`, drag **Frame Control** to **Applications**, then
+  open it from Applications. For the unsigned-app warning, use the macOS steps
+  above. Allow local network access and control of Terminal when prompted.
+- **Windows:** run the installer, then open **Frame Control** from Start. For
+  the portable download, extract the entire `.zip` first and run
+  `Frame Control.exe` inside it. See the SmartScreen note above.
+- **Linux:** install the `.deb` with your package installer and launch
+  **Frame Control** from your applications menu; or make the AppImage executable
+  and run it as described above. Install the OpenSSH client if `ssh` is missing.
+
 ## Set up the headset

-You type one password on the headset, once. Everything else happens on your
-computer.
+Keep the Frame awake and connect it and your computer to the same trusted local
+network. Guest Wi-Fi/client isolation can prevent discovery and connections.

 1. **On the Frame:** Steam Settings → System → **Enable Developer Mode**, then
-   in the Developer section, **Set User Password**. Pick something short:
-   you'll type it once more on your computer and then never again.
-2. **On your computer:** open Frame Control. It offers to **Set Up
-   Connection**, which finds the headset, creates an SSH key, and asks for that
-   password once in a terminal window. If it can't find the Frame, type the
-   IP address from the Frame's Quick Settings.
-
-   Before asking for the password it tries Valve's SteamOS devkit pairing: in
-   the headset, open Steam Settings → Developer → **Pair new host** and approve
-   the request, and no password is needed. (The service and the pairing-mode
-   step are verified on a Frame; the approval itself isn't yet. See
-   [SSH](docs/ssh.md#password-free-pairing-steamos-devkit-service).)
-3. That's it. The app now reaches the headset whenever it's awake and on the
-   same network. For anywhere else, see [Tailscale](docs/tailscale.md).
+   Developer → **Set User Password**. Choose a password that isn't easy to guess:
+   it also protects `sudo` and remote desktop, even after SSH keys are set up.
+2. **On your computer:** open Frame Control and choose **Set Up Connection…**.
+   If you dismissed the first-run prompt, use **Frame → Set Up Connection…**.
+   Setup opens a terminal and tries to find the headset. If it can't, use its IP
+   address from Quick Settings or Steam Settings → Internet. Windows/Linux setup
+   prompts for it; macOS exits instead. On macOS, return to the app →
+   **Devices & connection → + Add a headset…**, set SSH alias to `frame` for
+   the default headset, fill in **Address**, then choose **Set Up…**.
+3. **Pair or enter the password:** setup first tries Valve's devkit pairing.
+   Open Steam Settings → Developer → **Pair new host** in the headset and approve
+   only the request you just started. The service and pairing-mode step are
+   verified on a Frame; approval and key installation through that flow remain
+   unverified. If pairing fails or times out, setup falls back to asking for the
+   Developer Mode password in the computer's terminal. Password typing may show
+   no characters; press Enter when done. See [SSH details](docs/ssh.md#password-free-pairing-steamos-devkit-service).
+4. After setup succeeds, return to Frame Control. It uses SSH keys for later
+   connections whenever the Frame is awake and reachable. If it stays offline,
+   check Developer Mode, the address and network isolation, then run setup again.
+   For connections away from home, see [Tailscale](docs/tailscale.md).

 **What it changes:** only what you click. Installs go to your user account on
 the Frame (`--user` Flatpaks, Lepton instances, Steam downloads, sideloaded
@@ -252,8 +283,8 @@ Frame's software fits together, all checked against a real headset and labelled
  loopback `127.0.0.1:8080`) only through SSH tunnels. The compatibility
  database key (maintainer-only) is never written to the repo.
 - `steamos` has `sudo`, protected by the same Developer Mode password. Once
-  you've switched to key auth, a short password still protects `sudo` and
-  RDP, so pick one that isn't trivially guessable.
+  you've switched to key auth, that password still protects `sudo` and RDP,
+  so pick one that isn't trivially guessable.
 - Don't port-forward 22, 3389, or 5555–5599 from your router. For remote access,
  use Tailscale: `scripts/tailscale-on-frame.sh` (no sudo). In its userspace mode
  **every** Frame port is reachable from your tailnet, including Steam's DevTools
@@ -1,12 +1,12 @@
 {
  "name": "frame-control",
-  "version": "0.4.15",
+  "version": "0.4.17",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "frame-control",
-      "version": "0.4.15",
+      "version": "0.4.17",
      "license": "MIT",
      "devDependencies": {
        "electron": "^44.4.5",
@@ -1,7 +1,7 @@
 {
  "name": "frame-control",
  "productName": "Frame Control",
-  "version": "0.4.15",
+  "version": "0.4.17",
  "description": "Desktop app for managing a Valve Steam Frame over SSH",
  "private": true,
  "main": "main.js",
@@ -25,8 +25,28 @@ tested in another full Plasma session under a three-minute rollback timer.
 `ui/frame_backup.py session` reported Desktop Mode despite gamescope, and
 `ui/frame_backup.py game-mode` invoked the same guarded Return function used by
 the button. Game Mode became active and a second call made no switch. Battery
-remained at 99%; the timer and lock were removed. The literal desktop button
-was not clicked in this test, and older SteamOS builds remain fixture-tested.
+remained at 99%; the timer and lock were removed. That test used the production
+CLI rather than clicking the desktop button.
+
+Later on 2026-10-24, the published **v0.4.17 Linux x86_64 AppImage** passed the
+literal packaged-button check on the same Frame/build. With the shared lock and
+a verified three-minute rollback timer, the headset entered full Plasma Desktop
+Mode. In the packaged Electron window, **Tools → Backup & recovery → Check**
+reported Desktop Mode despite gamescope. A trusted automated pointer click on
+the visible **Return to Game Mode** button, accepting its confirmation, returned
+`switched: true` and `steamosctl switch-to-game-mode`. The systemd targets then
+confirmed Game Mode. A second confirmed button click returned `switched: false`;
+the Game Mode service invocation and SteamVR PID stayed unchanged. **Check**
+then reported Game Mode and disabled Return. The test app/server and virtual
+display were stopped; the timer and shared lock were removed. Steam and SteamVR remained running
+at 99% battery. [Commands, responses, cleanup and limits](evidence/return-game-mode-packaged-2026-10-24.json),
+[before](evidence/return-game-mode-packaged-2026-10-24-before.png) and
+[after](evidence/return-game-mode-packaged-2026-10-24-after.png).
+
+This used the unchanged extracted AppImage payload with its bundled Python on
+Xvfb (`--no-sandbox --disable-gpu`), following the packaged Export test in #156.
+FUSE mounting, desktop integration, hardware rendering and the view inside a
+worn headset were not checked. Older SteamOS builds remain fixture-tested.

 ## Back up

@@ -0,0 +1,38 @@
+{
+  "date_utc": "2026-10-24T07:54:37Z",
+  "frame_control_tag": "v0.4.16",
+  "steamos_version": "0.5.6",
+  "steamos_build": "20261015.6141207",
+  "host": "lxso2",
+  "interface": "source UI served by a temporary private Frame Control server, opened in T3 Code's desktop browser",
+  "action": "Clicked the visible Export button for Steam's retained real saved clip in Capture & Live",
+  "clip_id": "10230640/clips/clip_13009719723623972864_20261024_072115",
+  "api_observed": {
+    "post_clips_export_http": 200,
+    "get_job_http": 200,
+    "get_clips_http": 200
+  },
+  "ui_result": "Saved clip_13009719723623972864_20261024_072115.mp4 to ~/Videos/SteamFrame; button changed to Export again",
+  "output": {
+    "path": "~/Videos/SteamFrame/clip_13009719723623972864_20261024_072115.mp4",
+    "bytes": 159829,
+    "sha256": "f8a476eefb2bde7ba5cb464632ec9b952eea3ab1610b5bed2098bf1f11d62cf1",
+    "matches_previously_fully_decoded_export": true,
+    "duration_seconds": 10.288532,
+    "video": "H.264 1920x1080",
+    "audio": "AAC stereo"
+  },
+  "cleanup": {
+    "temporary_server_stopped": true,
+    "shared_device_lock_released": true,
+    "battery_percent_after": 99,
+    "desktop_mode_active_after": false,
+    "test_title_created": false,
+    "steam_source_clip_retained": true
+  },
+  "limits": [
+    "The test used the source UI, not a packaged desktop installer.",
+    "The retained source clip was nearly black; visible gameplay capture remains unverified.",
+    "Perceptual audio/video sync, long clips, trims and automatic copying were not tested."
+  ]
+}
@@ -0,0 +1,29 @@
+{
+  "date_utc": "2026-10-24",
+  "version": "v0.4.17",
+  "steam_os_version": "0.5.6",
+  "steam_os_build": "20261015.6141207",
+  "result": "PASS: the real Steam-saved clip exported beyond 60 seconds",
+  "method": "Steam manual recording of a reserved test title, then Frame Control's production frame_clips.export_clip path; no packaged GUI button click",
+  "source": {
+    "kind": "saved Steam clip",
+    "duration_seconds": 100.801,
+    "chunks": 68,
+    "gaps": 0
+  },
+  "export": {
+    "format": "MP4",
+    "bytes": 1377849,
+    "sha256": "82ef31f65e6933d122bc326d664beb2eb2e3ba6969f26c0032552e80fbe8d823",
+    "duration_seconds_ffprobe": 100.833335,
+    "video": "H.264, 1920x1080, 6049 frames",
+    "audio": "AAC, 48000 Hz, stereo",
+    "full_ffmpeg_decode": "passed without errors"
+  },
+  "cleanup": "Restored Steam recording mode to its prior off setting; stopped and removed only the reserved title and its processes; no recording or running Steam apps remained; Game Mode active, battery 100%, shared test lock released",
+  "limits": [
+    "This exercised the production export code path, not a packaged GUI Export click.",
+    "Visible gameplay quality, perceptual audio/video sync, trims and longer recordings were not checked.",
+    "The newly saved Steam source clip was retained; no user recording was deleted."
+  ]
+}
@@ -0,0 +1,94 @@
+{
+  "date_utc": "2026-10-24T09:08:35.523Z",
+  "result": "PASS: packaged Electron visible Export click saved the retained real Steam clip beyond 60 seconds",
+  "frame_control_tag": "v0.4.17",
+  "documentation_base_commit": "4e456480aefbe541e334dbd247328537f535bd94",
+  "host": "lxso2",
+  "steamos_version": "0.5.6",
+  "steamos_build": "20261015.6141207",
+  "package": {
+    "asset": "Frame-Control-linux-x86_64.AppImage",
+    "url": "https://github.com/saphid/frame-control/releases/download/v0.4.17/Frame-Control-linux-x86_64.AppImage",
+    "sha256": "b1b8eb82bf73a227b2cd36e8f0ef3a2ebdf7967c5853efb08a9634f38227015d",
+    "launch": "Verified release asset; --appimage-extract, then unmodified squashfs-root/AppRun. Electron used the bundled server and Python, not checkout source.",
+    "display": "Xvfb :137, 1440x1000x24; Electron window 1400x950 including native chrome",
+    "flags": [
+      "--no-sandbox",
+      "--disable-gpu",
+      "--remote-debugging-port=49371",
+      "--remote-debugging-address=127.0.0.1",
+      "--user-data-dir=/tmp/frame-packaged-export-20261024/electron-profile"
+    ],
+    "isolation": "Throwaway XDG_CONFIG_HOME, FRAME_CONTROL_DATA_DIR and Electron profile; telemetry and update checks disabled; existing SSH identity and normal home Videos destination used."
+  },
+  "ui": {
+    "navigation": "Dismissed optional email prompt with No thanks; clicked Tools, then Capture & Live; scrolled Steam clips into view.",
+    "row": "Steam recording \u00b7 Clip; Oct 24, 8:53 AM \u00b7 1:40 \u00b7 2 MB",
+    "action": "Playwright connected to this Electron instance over local CDP; locator.click() clicked its visible button named exactly Export. The test did not directly invoke an export function or API POST.",
+    "button": "button.small[data-clip-export=\"0\"]",
+    "click_is_trusted": true,
+    "button_bounds_css_pixels": {
+      "x": 1300.390625,
+      "y": 701.15625,
+      "width": 61.609375,
+      "height": 28
+    },
+    "post_clips_export_http": 200,
+    "job": "0ab20b1788adce63",
+    "job_poll_http": 200,
+    "saved_message": "Saved clip_15658413054201167872_20261024_085343.mp4 to ~/Videos/SteamFrame",
+    "final_row": "ON PC; Export again",
+    "screenshots": [
+      "clip-packaged-export-2026-10-24-before.png",
+      "clip-packaged-export-2026-10-24-after.png"
+    ],
+    "screenshot_scope": "Cropped to Steam clip rows and saved notification; unrelated screenshot thumbnails and host connection identity excluded."
+  },
+  "source": {
+    "clip_id": "10230640/clips/clip_15658413054201167872_20261024_085343",
+    "duration_seconds": 100.801,
+    "duration_provenance": "Retained real Steam clip from clip-long-2026-10-24.json; current packaged UI displays 1:40."
+  },
+  "output": {
+    "path": "~/Videos/SteamFrame/clip_15658413054201167872_20261024_085343.mp4",
+    "bytes": 1377849,
+    "sha256": "82ef31f65e6933d122bc326d664beb2eb2e3ba6969f26c0032552e80fbe8d823",
+    "matches_prior_production_export_size_and_sha256": true,
+    "duration_seconds_ffprobe": 100.833335,
+    "duration_difference_from_steam_seconds": 0.032335,
+    "video": "H.264, 1920x1080, 6049 decoded frames",
+    "audio": "AAC, 48000 Hz, stereo, 4724 decoded audio frames",
+    "validation": [
+      "ffprobe -v error -count_frames -show_entries format=duration,size:stream=codec_name,codec_type,width,height,sample_rate,channels,nb_read_frames -of json <output>: exit 0",
+      "sha256sum <output>: exact match to prior production export",
+      "ffmpeg -v error -xerror -i <output> -f null -: exit 0, no errors"
+    ]
+  },
+  "cleanup": {
+    "shared_lock": "Acquired with ssh frame mkdir /tmp/frame-test.lock after read-only battery/build/lock checks; released with rmdir after app shutdown; absence read back.",
+    "battery_percent_before": 99,
+    "battery_percent_after": 99,
+    "battery_status": "Not charging; charger Full",
+    "packaged_app_and_server_exited": true,
+    "test_xvfb_stopped": true,
+    "frame_export_cache_directories_remaining": 0,
+    "ffmpeg_processes_after": 0,
+    "game_mode_and_steamvr_running_after": true,
+    "steam_source_clip_retained": true,
+    "user_recordings_deleted": false,
+    "headset_install_or_settings_changes": false,
+    "local_export_retained": true
+  },
+  "limits": [
+    "The unchanged AppImage payload ran after extraction on a virtual X desktop, with Chromium sandbox and GPU disabled. FUSE mounting, desktop integration and hardware rendering were not tested.",
+    "The click was automated trusted pointer input in a visible Electron window on Xvfb, not a human click on a physical monitor. T3 collaborative preview opened successfully but drives separate browser tabs; Electron-native automation was used for this window.",
+    "No new game or Steam recording was started. Visible gameplay quality, audible content and perceptual audio/video sync were not assessed.",
+    "Clips longer than this retained 100-second clip, trims and automatic copying remain unverified.",
+    "No release, tag or application code was changed."
+  ],
+  "validation_local": {
+    "clip_regression_suite": "python3 -m unittest discover -s tests -p test_clips.py -v: 34 tests passed in 20.173s, including real ffmpeg long-recording export",
+    "json": "python3 -m json.tool: passed",
+    "diff": "git diff --check: passed"
+  }
+}
@@ -0,0 +1,95 @@
+{
+  "date": "2026-10-24",
+  "command": "scripts/frame-power-sample.sh --count 2 --interval 1",
+  "exitCode": 0,
+  "stopped": null,
+  "lockPolicy": "Existing sampler checked local and remote /tmp/frame-test.lock before reading; no lock acquired, bypassed or removed. Read-only run only.",
+  "samples": [
+    {
+      "time": 1792828506.4317346,
+      "osBuild": "20261015.6141207",
+      "elapsedSeconds": 0.057539,
+      "battery": {
+        "battery.percent": {
+          "value": 99,
+          "unit": "%",
+          "source": "/sys/class/power_supply/max1720x_bat_7-36",
+          "state": "available"
+        },
+        "battery.status": {
+          "value": "Not charging",
+          "unit": "state",
+          "source": "/sys/class/power_supply/max1720x_bat_7-36",
+          "state": "available"
+        },
+        "battery.watts": {
+          "value": -0.06,
+          "unit": "W",
+          "source": "/sys/class/power_supply/max1720x_bat_7-36",
+          "state": "available"
+        },
+        "battery.tempC": {
+          "value": 24.0,
+          "unit": "C",
+          "source": "/sys/class/power_supply/max1720x_bat_7-36",
+          "state": "available"
+        }
+      }
+    },
+    {
+      "time": 1792828507.4357972,
+      "osBuild": "20261015.6141207",
+      "elapsedSeconds": 1.061612,
+      "battery": {
+        "battery.percent": {
+          "value": 99,
+          "unit": "%",
+          "source": "/sys/class/power_supply/max1720x_bat_7-36",
+          "state": "available"
+        },
+        "battery.status": {
+          "value": "Not charging",
+          "unit": "state",
+          "source": "/sys/class/power_supply/max1720x_bat_7-36",
+          "state": "available"
+        },
+        "battery.watts": {
+          "value": -0.05,
+          "unit": "W",
+          "source": "/sys/class/power_supply/max1720x_bat_7-36",
+          "state": "available"
+        },
+        "battery.tempC": {
+          "value": 24.0,
+          "unit": "C",
+          "source": "/sys/class/power_supply/max1720x_bat_7-36",
+          "state": "available"
+        }
+      }
+    }
+  ],
+  "limitations": [
+    "No real low-charge or thermal condition induced.",
+    "No native notification delivery verified.",
+    "No worn-headset or native package tests.",
+    "Read-only parser/transport check; no background monitor or power-saving claim."
+  ],
+  "browserCheck": {
+    "page": "Production ui/index.html served statically; API calls intentionally unavailable",
+    "viewport": {
+      "width": 1280,
+      "height": 800
+    },
+    "bridge": "Synthetic desktop notification bridge; no native OS notification sent",
+    "result": "Initially unchecked and visible only after desktop host/bridge setup. Checkbox enabled through browser. Synthetic 12%, Discharging, -4 W samples at 0/30/60 seconds produced one bridge request, an in-page status and a toast. No horizontal overflow.",
+    "apiLimit": "Static server returned expected 404/501 API errors; not an end-to-end live desktop connection test."
+  },
+  "offlineValidation": [
+    "test_desktop_battery_comfort.py: 2 tests, production JS with monotonic fake clock and notification bridge",
+    "test_comfort*.py: 25 tests",
+    "test_battery.py: 7 tests",
+    "test_power*.py: 36 tests (loopback HTTP test run outside socket-restricted sandbox)",
+    "test_ui_workspace.py: 1 Python wrapper / Node workspace suite",
+    "test_ui_review.py: 1 Python wrapper / 9 Node regression tests, including switch reset and retained cooldown"
+  ]
+}
@@ -0,0 +1,114 @@
+# Linux PC host feasibility on lxso2, 2026-10-24
+
+**Blocked on this host's current desktop environment. No feature enabled and
+no feature PR opened.** Investigation for [issue #23](https://github.com/saphid/frame-control/issues/23),
+starting at `4e45648` (main after #154). This concerns flat desktop panels,
+not Linux PC VR streaming.
+
+## Decision
+
+The smallest useful candidate is one explicitly selected **whole screen**,
+captured through the ScreenCast portal's restricted PipeWire connection,
+encoded locally with GStreamer/x264, and sent to the existing viewer through
+the shared SSH controller. Input, individual windows and virtual displays
+would remain unsupported until separately verified. This candidate was **not
+implemented**: lxso2 currently cannot exercise the real capture permission path.
+
+Development packages could unblock compilation, but would not create a desktop,
+portal backend or consented screen. Synthetic encoding, an Xvfb screen grab or
+using the Frame as its own host would not verify Linux PC desktop capture.
+No host packages or services were changed.
+
+## Evidence
+
+Host: `lxso2`, Linux x86-64, kernel `6.8.0-139-generic`.
+
+- `DISPLAY`, `WAYLAND_DISPLAY` and `XDG_SESSION_TYPE` were unset. The user bus
+  was reachable at `/run/user/1000/bus`.
+- `/run/user/1000/pipewire-0` and `/run/user/1000/wayland-0` did not exist.
+  No processes matched Xorg, Xwayland, Xvfb, GNOME Shell, KWin Wayland, Weston,
+  PipeWire, WirePlumber or xdg-desktop-portal at the process check.
+- D-Bus `ListNames` returned D-Bus, systemd and anonymous connections, with no
+  `org.freedesktop.portal.Desktop`. `ListActivatableNames` also had no desktop
+  portal. These calls queried D-Bus itself without activating capture services.
+- `dpkg-query` found no `xdg-desktop-portal*` or `pipewire*` packages.
+  `libgstreamer1.0-0:amd64` was installed at `1.24.2-1ubuntu0.1`, but
+  `gstreamer1.0-tools` was uninstalled. `gst-launch-1.0` and `gst-inspect-1.0`
+  were absent from PATH. Xvfb was installed, but supplies no portal by itself.
+- `pkg-config --modversion` failed for `gstreamer-1.0`,
+  `gstreamer-app-1.0`, `gstreamer-video-1.0` and `libpipewire-0.3`.
+  `gio-unix-2.0` reported `2.80.0`.
+- `desktop/bundle/pc-host.so` did not exist.
+  `python3 desktop/build.py --with-x264 --out /tmp/frame-linux-pc-feasibility`
+  exited **1** before compilation: required GStreamer pkg-config modules were
+  missing. No native build or encoder runtime success is claimed.
+
+Reproduce the non-activating portal checks in the intended desktop user's
+session, using that session's actual runtime directory and bus:
+
+```sh
+gdbus call --session --dest org.freedesktop.DBus \
+  --object-path /org/freedesktop/DBus --method org.freedesktop.DBus.ListNames
+gdbus call --session --dest org.freedesktop.DBus \
+  --object-path /org/freedesktop/DBus --method org.freedesktop.DBus.ListActivatableNames
+pkg-config --modversion gstreamer-1.0 gstreamer-app-1.0 gstreamer-video-1.0 gio-unix-2.0
+```
+
+## Existing implementation reviewed
+
+- `ui/frame_pcview.py` selects PCView only on Windows and rejects Linux even
+  when enabled. Linux installers do not carry its native bundle.
+- `desktop/portal.c` creates a **RemoteDesktop** session, requests pointer and
+  keyboard devices, and selects monitors and windows (`types=3`). It is not
+  ScreenCast-only or screen-only. Its restricted fd/node and fresh-connection
+  handling are reusable.
+- `ui/frame_pc_agent.py` calls the selection a shared window or screen and
+  picks VA-API when the element is present, falling back to x264. A bounded
+  x264 slice needs explicit encoder policy and unsupported-input behavior;
+  exposing the existing Linux path alone would not meet that scope.
+- `app/main.js` starts Python with the inherited environment; it does not
+  supply a compositor, portal backend or capture permission.
+- `.github/workflows/pc-host.yml` installs native dependencies and tests
+  synthetic x264/protocol behavior with fake capture consent/input. This does
+  not establish interactive Linux desktop capture.
+- Issue #23 and its six existing comments distinguish prior synthetic
+  helper/viewer results from untested Linux desktop capture and consent.
+
+## Verification and limits
+
+`python3 -m unittest discover -s tests -p 'test_pc*.py' -v` exited **0**:
+27 tests ran successfully, with one additional native-class setup skip
+(`native PC libraries not built on this host`). Coverage includes the compiled
+C controller trace, Python adapters, grants and default-off/Windows-only gates.
+It does not prove native GStreamer capture or local-client streaming.
+
+No fake/local native stream, consent prompt, real desktop capture, Frame viewer
+run, benchmark, input or window mode was tested in this investigation. No SSH
+connection to the Frame was needed; no lock was acquired and no headset install,
+launch, stop or settings change was attempted. Issue #113 was left alone.
+No issue comments or other public messages were sent.
+
+## Concrete unblock and next slice
+
+1. Supply an interactive Linux desktop, physical or VM, with a working
+   ScreenCast portal/backend, PipeWire and accessible consent dialog. Installing
+   the portal frontend alone is insufficient. A VM can establish software
+   capture/x264 behavior while physical-host behavior remains unverified.
+2. Install the native dependencies listed in `pc-host.yml` in that environment
+   and build a local `--with-x264` bundle. Resolve x264 distribution
+   licensing/source obligations before shipping it: the current build labels
+   that option test-only and the Windows installer omits it.
+3. Implement a ScreenCast-only session with monitor-only selection, no
+   RemoteDesktop/device request, disabled input in protocol and viewer, hidden
+   window/virtual-display modes, and explicit x264 selection. Preserve the
+   default-off gate and existing Mac/Windows paths.
+4. Verify consent acceptance/refusal/cancellation, Stop/reopen, connection loss
+   and portal closure with a local client decoding actual captured content.
+   Run the shared benchmark and record results without inferring hardware or
+   physical laser behavior.
+5. Only after local capture works, acquire the shared Frame lock once and
+   follow [the headset procedure](../testing.md#headset-smoke-test) for a brief
+   viewer test. If occupied, leave the lock alone and defer device testing.
+
+These are prerequisites and proposed scope, not a ready feature. The Linux
+host request in #23 remains open.
@@ -0,0 +1,65 @@
+# Panel discovery investigation, 2026-10-24
+
+Base: v0.4.16 (`040581a`). Scope: issue #73, Desktop Capture and Control.
+
+## Evidence and change
+
+Issue #73 reports SteamOS 0.4.5 with its desktop visibly running, without a
+Frame Control version or steps. The maintainer's 2026-10-12 comment identifies
+the duplicate `loadPanels` UI function fixed in 0.4.3 and requests the exact
+remaining message and SteamOS build if it persists. There is no reporter
+follow-up. At this base, the functions are distinct and the existing Node
+regression checks their uniqueness and the Desktop GET request.
+
+Read-only source inspection found a remaining diagnostic ambiguity:
+`read_props()` returns `{}` for failed/timed-out X queries and missing root
+properties. `panels()` treated that like a confirmed empty focusable-window
+list. With no detected Plasma process it claimed no panel was open; with Plasma
+it claimed SteamOS was not listing the desktop. Neither claim follows from an
+unreadable list.
+
+The change checks for the presence of `GAMESCOPE_FOCUSABLE_WINDOWS` before
+those claims. An absent list now reports unknown panel state, suggests checking
+SteamVR and retrying/Headset view, and asks for the exact message and SteamOS
+version if persistent. Missing-tool and whole-run deadline explanations retain
+precedence. No new probes, retries, timeouts, input or capture routes are added.
+
+## Real-device boundary
+
+A preliminary read-only SSH inspection returned SteamOS 0.5.6, BUILD_ID
+`20261015.6141207`, battery 99%, discharging, and X0/X1 socket names. It made
+no headset changes. The shared lock was absent at that moment.
+
+The subsequent atomic `mkdir /tmp/frame-test.lock` failed with `File exists`.
+The guarded command exited with status 3 before the session, X-property or
+panel-helper probes ran. The other task's lock was left alone. No application
+was installed, started, stopped or focused; no headset settings changed.
+
+That implementation probe was blocked by the occupied shared device. The
+coordinator later supplied a separate narrow read-only observation on SteamOS
+0.5.6, BUILD_ID `20261015.6141207`, at battery 99%, with the shared lock absent
+and both `xprop` and `xwininfo` installed:
+
+- In **Game Mode**, `DISPLAY=:0 xprop -root GAMESCOPE_FOCUSABLE_WINDOWS
+  GAMESCOPE_FOCUSED_WINDOW` returned both properties **present but empty**.
+- On `DISPLAY=:1`, both properties were reported **not found**.
+
+This observation distinguishes a confirmed empty list on `:0` from absent
+properties on `:1`. It does **not** reproduce #73's Desktop Mode report on
+SteamOS 0.4.5, and it does **not** test this PR's code on the headset. It is a
+coordinator-supplied observation, separate from the blocked implementation probe
+above; no new headset probe was run for this follow-up.
+
+Remaining limit: there is no reproduction establishing a further
+capture/discovery fix for the reported Desktop Mode/build combination. This PR
+improves a demonstrated diagnostic error; it must not close #73 as a verified
+new capture fix.
+
+## Offline verification
+
+Focused Python regressions distinguish absent, focus-only, failed/timed-out X
+queries, confirmed empty and desktop-running lists. Existing tests cover
+missing tools, alternate displays, successful discovery and the 12-second
+deadline. The production page's Node behavior test verifies that both Capture
+and Control preserve the unreadable-list advice. These use fake X/HTTP/DOM
+boundaries and do not prove real SteamOS 0.4.5 capture or physical input.
@@ -0,0 +1,226 @@
+{
+  "date_utc": "2026-10-24T09:27:25.354Z",
+  "result": "PASS: literal packaged desktop Return to Game Mode button switched the real Frame from full Plasma; a repeat visible click made no second switch",
+  "documentation_base_commit": "71288d8980040c14f777f0e417f41f7105eaaac4",
+  "host": "lxso2",
+  "steamos_version": "0.5.6",
+  "steamos_build": "20261015.6141207",
+  "prior_evidence": [
+    "https://github.com/saphid/frame-control/issues/142",
+    "https://github.com/saphid/frame-control/pull/143",
+    "https://github.com/saphid/frame-control/pull/156"
+  ],
+  "package": {
+    "tag": "v0.4.17",
+    "asset": "Frame-Control-linux-x86_64.AppImage",
+    "url": "https://github.com/saphid/frame-control/releases/download/v0.4.17/Frame-Control-linux-x86_64.AppImage",
+    "sha256": "b1b8eb82bf73a227b2cd36e8f0ef3a2ebdf7967c5853efb08a9634f38227015d",
+    "verification": "sha256sum matched the live release asset digest. Independently extracted the retained asset into a new private test directory. cmp confirmed bundled frame_backup.py and frame_backup_remote.py equal the checkout versions. No source or payload was changed.",
+    "launch": "--appimage-extract, then squashfs-root/AppRun --no-sandbox --disable-gpu --remote-debugging-port=49372 --remote-debugging-address=127.0.0.1 --user-data-dir=/tmp/frame-return-button-20261024/electron-profile --window-size=1400,950",
+    "display": "Xvfb :138 -screen 0 1440x1000x24 -nolisten tcp; Electron content screenshot 1400x923",
+    "isolation": "Private XDG_CONFIG_HOME, XDG_CACHE_HOME, FRAME_CONTROL_DATA_DIR and Electron profile; FRAME_CONTROL_TELEMETRY=0 and FRAME_CONTROL_NO_UPDATE_CHECK=1. Existing authorized ssh frame identity retained; bundled server and Python used."
+  },
+  "preflight": {
+    "read_only_first": true,
+    "initial_mode": "gamescope-session.target=active; plasma-workspace-wayland.target=inactive",
+    "initial_battery_percent": 99,
+    "initial_battery_status": "Not charging; charger Full",
+    "steam_and_steamvr_running": true,
+    "running_steam_apps": [],
+    "default_login_mode": "game",
+    "lock": "mkdir /tmp/frame-test.lock succeeded atomically; no foreign lock was removed. Initial harmless probe attempt released its own lock, then a fresh atomic acquisition covered both full-session attempts."
+  },
+  "rollback": {
+    "unit": "fc-return-button-rollback-20261024",
+    "probe": "systemd-run --user --unit=fc-return-button-probe-20261024 --on-active=2s --timer-property=AccuracySec=1s --property=Type=oneshot --property=RemainAfterExit=yes /usr/bin/true",
+    "probe_execution": "Result=success\nExecMainStartTimestamp=Sat 2026-10-24 20:27:07 AEDT\nExecMainExitTimestamp=Sat 2026-10-24 20:27:07 AEDT\nExecMainCode=1\nExecMainStatus=0\n",
+    "arm": "systemd-run --user --unit=fc-return-button-rollback-20261024 --on-active=180s --timer-property=AccuracySec=1s /bin/sh -c <guarded command>",
+    "guarded_command": "if [ \"$(systemctl --user is-active gamescope-session.target)\" != active ]; then exec /usr/bin/steamosctl switch-to-game-mode; fi",
+    "verified_before_desktop": "TimersMonotonic={ OnActiveUSec=3min ; next_elapse=1d 21h 53min 49.130174s }\nNextElapseUSecMonotonic=1d 21h 53min 49.130174s\nBindsTo=\nPartOf=\nActiveState=active\nExecStart={ path=/bin/sh ; argv[]=/bin/sh -c if [ \"$(systemctl --user is-active gamescope-session.target)\" != active ]; then exec /usr/bin/steamosctl switch-to-game-mode; fi ; ignore_errors=no ; start_time=[n/a] ; stop_time=[n/a] ; pid=0 ; code=(null) ; status=0/0 }\nBindsTo=\nPartOf=\n",
+    "user_manager_linger": "yes",
+    "desktop_entry": "ssh frame steamosctl switch-to-desktop-mode",
+    "first_click_utc": "2026-10-24T09:27:27.037Z",
+    "cancelled_before_deadline": true,
+    "fired": false,
+    "limit": "The benign transient timer was observed executing. The actual rollback timer configuration was read back, then cancelled after the UI restored Game Mode; its recovery action was not deliberately allowed to fire."
+  },
+  "ui": {
+    "navigation": "Clicked nav Tools, Backup & recovery, and Check in the actual packaged Electron window. Initial Game Mode disabled Return. After full Plasma entry, Check enabled it.",
+    "automation": "Playwright connected to the packaged Electron instance over local CDP and used locator.click() on the visible button; accepted the native JavaScript confirm dialog. No Return API/CLI or production handler was directly invoked by the test. T3 preview was inspected separately and closed; it cannot control this Electron window.",
+    "clicks": [
+      {
+        "isTrusted": true,
+        "utc": "2026-10-24T09:27:27.037Z"
+      },
+      {
+        "isTrusted": true,
+        "utc": "2026-10-24T09:27:32.942Z"
+      }
+    ],
+    "button_bounds_css_pixels": {
+      "x": 47,
+      "y": 709.59375,
+      "width": 156.203125,
+      "height": 44
+    },
+    "confirmation_dialogs": [
+      {
+        "type": "confirm",
+        "message": "Return the headset to Game Mode?\n\nThis closes the desktop and any apps open in it, then starts Steam's Game Mode.",
+        "utc": "2026-10-24T09:27:27.042Z"
+      },
+      {
+        "type": "confirm",
+        "message": "Return the headset to Game Mode?\n\nThis closes the desktop and any apps open in it, then starts Steam's Game Mode.",
+        "utc": "2026-10-24T09:27:32.943Z"
+      }
+    ],
+    "desktop_check": {
+      "http": 200,
+      "body": {
+        "mode": "desktop",
+        "gamescope": true,
+        "plasma": true,
+        "nested_desktop": false,
+        "configured": "gamescope-wayland.desktop",
+        "config_file": "/etc/sddm.conf.d/steamos.conf",
+        "selector": "steamosctl",
+        "session_targets": {
+          "gamescope-session.target": "inactive",
+          "plasma-workspace-wayland.target": "active"
+        },
+        "mode_source": "session-targets"
+      }
+    },
+    "return_responses": [
+      {
+        "http": 200,
+        "body": {
+          "message": "Asked the headset to return to Game Mode; it restarts its session in a few seconds",
+          "state": {
+            "mode": "desktop",
+            "gamescope": true,
+            "plasma": true,
+            "nested_desktop": false,
+            "configured": "gamescope-wayland.desktop",
+            "config_file": "/etc/sddm.conf.d/steamos.conf",
+            "selector": "steamosctl",
+            "session_targets": {
+              "gamescope-session.target": "inactive",
+              "plasma-workspace-wayland.target": "active"
+            },
+            "mode_source": "session-targets"
+          },
+          "switched": true,
+          "command": "steamosctl switch-to-game-mode"
+        },
+        "utc": "2026-10-24T09:27:27.316Z"
+      },
+      {
+        "http": 200,
+        "body": {
+          "message": "The headset is already in Game Mode. The desktop you see is a panel: close it from the Steam dashboard.",
+          "state": {
+            "mode": "game",
+            "gamescope": true,
+            "plasma": false,
+            "nested_desktop": false,
+            "configured": "gamescope-wayland.desktop",
+            "config_file": "/etc/sddm.conf.d/steamos.conf",
+            "selector": "steamosctl",
+            "session_targets": {
+              "gamescope-session.target": "active",
+              "plasma-workspace-wayland.target": "inactive"
+            },
+            "mode_source": "session-targets"
+          },
+          "switched": false
+        },
+        "utc": "2026-10-24T09:27:33.126Z"
+      }
+    ],
+    "final_check": {
+      "http": 200,
+      "body": {
+        "mode": "game",
+        "gamescope": true,
+        "plasma": false,
+        "nested_desktop": false,
+        "configured": "gamescope-wayland.desktop",
+        "config_file": "/etc/sddm.conf.d/steamos.conf",
+        "selector": "steamosctl",
+        "session_targets": {
+          "gamescope-session.target": "active",
+          "plasma-workspace-wayland.target": "inactive"
+        },
+        "mode_source": "session-targets"
+      }
+    },
+    "final_return_disabled": true,
+    "final_text": "Game Mode: the headset is running normally. A desktop you see is a panel; close it from the Steam dashboard.",
+    "screenshots": [
+      "return-game-mode-packaged-2026-10-24-before.png",
+      "return-game-mode-packaged-2026-10-24-after.png"
+    ],
+    "screenshot_scope": "Cropped to the session controls and repeat-action notification; host identity, connection address and backup folder excluded."
+  },
+  "systemd_verification": {
+    "command": "ssh frame systemctl --user show gamescope-session.target plasma-workspace-wayland.target -p Id -p ActiveState -p SubState; ssh frame systemctl --user show gamescope-session.service -p InvocationID",
+    "before": "Id=gamescope-session.target\nActiveState=inactive\nSubState=dead\n\nId=plasma-workspace-wayland.target\nActiveState=active\nSubState=active\nInvocationID=892b843dbe1a4d2ba91b93057bd38463\n295589 /home/steamos/.local/share/Steam/steamrtarm64/steam -silent -vrdisable -deckard\n295066 /opt/steamvr/bin/linuxarm64/vrserver -waitformonitor -ipccontrolfilepath /tmp/SteamVR-IPCControlFile-294978\n",
+    "after_first_click": "Id=gamescope-session.target\nActiveState=active\nSubState=active\n\nId=plasma-workspace-wayland.target\nActiveState=inactive\nSubState=dead\nInvocationID=e8c1085b3bbd4e79a323b3e4a9bc6355\n297506 /opt/steamvr/bin/linuxarm64/vrserver -waitformonitor -ipccontrolfilepath /tmp/SteamVR-IPCControlFile-297420\n",
+    "after_repeat_click": "Id=gamescope-session.target\nActiveState=active\nSubState=active\n\nId=plasma-workspace-wayland.target\nActiveState=inactive\nSubState=dead\nInvocationID=e8c1085b3bbd4e79a323b3e4a9bc6355\n297826 /home/steamos/.local/share/Steam/steamrtarm64/steam -cef-enable-debugging -deckard -gamepadui -steamdeck -steamos3 -vrgamepadui\n297942 /home/steamos/.local/share/Steam/steamrtarm64/steam -child-update-ui -child-update-ui-socket 8 -cef-enable-debugging -deckard -gamepadui -steamdeck -steamos3 -vrgamepadui\n297506 /opt/steamvr/bin/linuxarm64/vrserver -waitformonitor -ipccontrolfilepath /tmp/SteamVR-IPCControlFile-297420\n",
+    "repeat_did_not_restart_game_mode": true,
+    "unchanged_game_service_invocation": "e8c1085b3bbd4e79a323b3e4a9bc6355",
+    "unchanged_steamvr_pid": 297506,
+    "delayed_final_readback_utc": "2026-10-24T09:28:05Z"
+  },
+  "cleanup": {
+    "complete": true,
+    "final_readback": "2026-10-24T09:28:05Z\nId=gamescope-session.target\nActiveState=active\n\nId=plasma-workspace-wayland.target\nActiveState=inactive\nInvocationID=e8c1085b3bbd4e79a323b3e4a9bc6355\nNEXT LEFT LAST PASSED UNIT ACTIVATES\n\n0 timers listed.\nId=fc-return-button-rollback-20261024.timer\nLoadState=not-found\nActiveState=inactive\n\nId=fc-return-button-rollback-20261024.service\nLoadState=not-found\nActiveState=inactive\n\nId=fc-return-button-probe-20261024.timer\nLoadState=not-found\nActiveState=inactive\n\nId=fc-return-button-probe-20261024.service\nLoadState=not-found\nActiveState=inactive\n297826 /home/steamos/.local/share/Steam/steamrtarm64/steam -cef-enable-debugging -deckard -gamepadui -steamdeck -steamos3 -vrgamepadui\n297506 /opt/steamvr/bin/linuxarm64/vrserver -waitformonitor -ipccontrolfilepath /tmp/SteamVR-IPCControlFile-297420\n99\nCharging\ngame\n",
+    "owned_lock_release_exit": 0,
+    "owned_lock_absent": true,
+    "host_processes": {
+      "xvfb": {
+        "pid": 1562020,
+        "exists": false,
+        "cmd": null,
+        "state": null
+      },
+      "electron": {
+        "pid": 1562023,
+        "exists": false,
+        "cmd": null,
+        "state": null
+      },
+      "x_socket_absent": true
+    },
+    "remaining_test_servers": [],
+    "battery_final_percent": 99,
+    "battery_final_status": "Charging",
+    "battery_range_observed_percent": [
+      99,
+      100
+    ],
+    "game_mode_steam_steamvr_running": true,
+    "default_login_mode_after": "game",
+    "headset_installs_or_global_settings_changed": false,
+    "rebooted": false,
+    "notes": "Stopping the timer succeeded. systemctl stop also named its never-started, unloaded service and returned 5; explicit readback confirms both rollback and probe timer/service units are not-found/inactive. No further switch was sent."
+  },
+  "attempts_and_harness_limits": [
+    "Initial harmless timer probe was garbage-collected before its exit metadata could be read. No Desktop Mode switch was attempted. Repeated with RemainAfterExit=yes and verified successful execution.",
+    "First full Plasma attempt clicked the visible packaged Return button and got HTTP 200 / switched=true. The harness then treated absent pgrep matches during the expected session restart as a fatal error. Independent readback confirmed Game Mode and SteamVR had returned. Rollback remained armed until that readback, then was cancelled. This incomplete attempt was not counted as the final pass.",
+    "Final full Plasma attempt tolerated transiently absent Steam/SteamVR while polling systemd targets, passed both trusted visible clicks, and completed the final Check. Stopping the unused rollback service returned unit-not-loaded; explicit subsequent readback verified all four owned probe/rollback units not-found/inactive and zero timers. Cleanup was completed before releasing our lock."
+  ],
+  "limits": [
+    "Unchanged AppImage payload ran after extraction on a virtual X desktop with Chromium sandbox and GPU disabled. FUSE mounting, desktop integration and hardware rendering were not tested.",
+    "Automated trusted pointer clicks in a visible Electron window; no physical-monitor human click or worn-headset visual/interaction assessment.",
+    "Verified only SteamOS 0.5.6 build 20261015.6141207 and the Linux x86_64 v0.4.17 package; older selectors/builds and other desktop platforms remain covered only by their existing tests.",
+    "No release, tag, application code, passwords or security/global settings changed."
+  ],
+  "validation": {
+    "focused_suite": "python3 -m unittest discover -s tests -p test_backup.py -v: 28 tests passed in 2.479s",
+    "json": "python3 -m json.tool: passed",
+    "diff": "git diff --check: passed"
+  }
+}
@@ -6,6 +6,45 @@ This is Frame Control code using Python, Steam and SteamVR already on the Frame.

 ![Family and comfort controls in the desktop app](img/comfort-desktop.png)

+## Desktop low-battery alert without a session
+
+In the desktop app, open **Tools → Family & comfort** and check **Alert on this
+computer at 15% or less**. This separate option does not start a session, install
+a worker or change the headset. It starts off whenever the page opens and turns
+off when you switch headsets. The choice is only for the current open page.
+
+It consumes the battery parser already used by normal status refreshes (also
+shared by the read-only power sampler). It adds no SSH calls, timers, sensor
+reads, third-party push or heat thresholds. Normal automatic status refreshes
+pause while the page is hidden, so this is **not a background or safety monitor**.
+Keep the app visible and connected. Use **Enable / test notifications** to check
+system delivery; operating-system settings may block notifications.
+
+Two fresh readings, at least 20 seconds and at most 90 seconds apart, must show
+15% or less, driver state `Discharging`, and signed battery power below −0.5 W.
+This avoids alerting on plugged-in idle readings, which can report discharging.
+Missing, invalid, stale or interrupted readings break confirmation. Disconnect,
+a failed status request, hiding the page or toggling the option also breaks
+confirmation. Unknown readings never mean zero charge.
+
+An alert appears in the page and requests a native desktop notification once
+per low-charge episode. Two readings at 20% or more rearm it, and at least ten
+minutes must pass between alerts (including across headset switches). A single
+recovery spike cannot rearm it. Toggling off/on does not clear the episode latch.
+Notification failure stays visible in the page and does not retry on every
+refresh. While an active family session has battery alerts enabled, that session
+handles battery alerts instead. Multiple app windows have independent state;
+this does not coordinate notifications between computers or windows.
+
+A read-only check on 2026-10-24, build **20261015.6141207**, received two samples
+at 99%, `Not charging`, approximately −0.06 W and 24 °C. No low-battery condition
+was induced, no notification was sent to the real headset, and no headset state
+was changed. The sampler's local and remote smoke-lock checks allowed the run;
+no lock was acquired or removed. Deterministic tests exercise low charge,
+recovery, missing readings, idle drain, timing and notification denial. See
+[recorded evidence](evidence/desktop-battery-comfort-2026-10-24.json). Native OS
+notification display, worn use and macOS/Windows packaging were not verified.
+
 ## Sessions

 Set a limit of 1–240 minutes, optional break and check-in intervals, then
@@ -107,6 +107,12 @@ The Linux adapter from #38 (desktop portal, PipeWire, VA-API) is in the tree,
 because it shares `capture.c` and the controller, and CI still builds and tests
 it. The app never offers it and the Linux installers don't include it.

+The [2026-10-24 lxso2 feasibility check](evidence/linux-pc-host-lxso2-2026-10-24.md)
+found no running or activatable desktop portal, no PipeWire socket and missing
+native build dependencies. Linux support remains disabled. The evidence records
+the build failure and prerequisites for a screen-only, view-only x264 slice;
+Linux capture, input and window modes have not been verified there.
+
 ## Measuring

 The Mac benchmark accepts the PC host:
@@ -8,13 +8,13 @@ Both are on **Tools → Capture & Live**. Everything is saved to
 Nothing needs installing on the computer or on the Frame: the work is done by
 the `ffmpeg` that SteamOS ships.

-**Recording is tested on a headset; Steam clip export isn't yet.** On a Frame
+**Recording and Steam clip export have each been tested on a headset.** On a Frame
 running SteamOS 0.5.6 (build 20261015.6141207), Record and Stop saved an
 8-second 1080p H.264 recording with AAC sound to the computer, Stop took about a
-second, and nothing was left running or stored on the Frame. That Frame had no
-Steam recordings, so the clip list came back empty and export has only been
-tested with files in Steam's format made by `ffmpeg`. The parts we're least sure
-of are listed under [What hasn't been checked](#what-hasnt-been-checked).
+second, and nothing was left running or stored on the Frame. A later test on
+that build created a saved clip with Steam's own recorder and exported it with
+Frame Control's production export function. The parts we're least sure of are
+listed under [What hasn't been checked](#what-hasnt-been-checked).

 ## Record

@@ -147,19 +147,65 @@ stand-in `ffmpeg`, so Stop, the time limit and the clean-up are tested as they
 run on the Frame. Where `ffmpeg` is installed, they also make a 65-second DASH
 recording with Steam's file names and export it with the real `ffmpeg`.

-## What hasn't been checked
+## Real Steam clip verification and remaining checks

-The 2026-10-24 read-only clip list on build `20261015.6141207` again returned
-zero clips: its `gamerecordings` directory held only `gamerecording.pb`. No
-Steam recording was created during that check, so a real Steam clip export is
-still unverified. The recording and Stop path were verified earlier on that
-build, as described above. Remaining checks:
+On 2026-10-24, v0.4.15 on build `20261015.6141207` recorded a ten-second
+reserved test session through Steam's own game recorder, saved it as a clip,
+then exported it with `frame_clips.export_clip`, the same implementation used
+by the desktop API. The 159,829-byte MP4 decoded completely: 10.29 seconds,
+1920×1080 H.264 video and stereo AAC audio (SHA-256
+`f8a476eefb2bde7ba5cb464632ec9b952eea3ab1610b5bed2098bf1f11d62cf1`).
+All 616 decoded video frames and the decoded audio matched Steam's source
+segments. Recording mode was restored
+to off; the reserved title and its processes were removed, the shared test lock
+was released, and the battery remained at 99%. The Steam source clip was kept.

- Audio and video sync. Both inputs are stamped with the wall clock, because
-  the camera device and the audio server otherwise count from different clocks.
- The exact layout of `gamerecordings` on the Frame's SteamOS build, and
-  whether a clip's segments start mid-recording. The parser is deliberately
-  loose about the layout.
+The inspected frame is nearly black in both Steam's source and the export, so
+this establishes file creation and faithful export, **not visible gameplay
+capture**. On v0.4.16, the literal desktop **Export** button was also clicked
+against that retained real Steam clip in the source UI on lxso2. The job
+completed and saved `~/Videos/SteamFrame/clip_13009719723623972864_20261024_072115.mp4`;
+its 159,829 bytes and SHA-256 matched the previously decoded export exactly.
+The temporary server stopped, the shared device lock was released, and the
+headset remained in Game Mode at 99% battery. See
+[`docs/evidence/clip-gui-export-2026-10-24.json`](evidence/clip-gui-export-2026-10-24.json)
+for the narrow proof. This did not exercise the packaged desktop installer.
+
+On 2026-10-24, the exact v0.4.17 tag exported a second real Steam-saved clip
+through `frame_clips.export_clip`, the same production path used by **Export**.
+Steam listed the clip at **100.801 seconds**, with 68 chunks and no gaps. The
+copied MP4 was **100.833 seconds** by `ffprobe` and decoded completely with
+`ffmpeg`; it was not cut at 60 seconds. The test restored Steam's recording
+mode, removed its reserved title and processes, and left Game Mode active at
+100% battery. See [the long-clip evidence](evidence/clip-long-2026-10-24.json).
+That code-path test did not click **Export** in the packaged desktop app or
+verify visible gameplay quality or perceptual audio/video sync.
+
+Later that day, the published v0.4.17 x86_64 Linux AppImage also passed the
+packaged desktop **Export** check against the retained 100.801-second clip.
+The asset SHA-256 was verified before launching its unchanged extracted payload
+in an isolated Electron profile on a virtual X desktop. An automated pointer
+click on the visible **Tools → Capture & Live → Steam clips → Export** button
+saved the MP4 and changed the row to **ON PC / Export again**. The saved file
+was 100.833335 seconds, decoded completely, and matched the prior production
+export by size and SHA-256. The app and test display were closed,
+the Frame export cache was empty, the source clip was retained, and the shared
+lock was released at 99% battery with Game Mode and SteamVR still running.
+See [the packaged export evidence](evidence/clip-packaged-export-2026-10-24.json)
+and its cropped before/after screenshots. This verifies the packaged Electron
+button and bundled export path; AppImage FUSE mounting, desktop integration,
+physical display/GPU rendering, gameplay quality and perceptual sync remain
+unverified. The virtual-display launch used `--no-sandbox --disable-gpu`.
+
+Remaining checks include:
+
+- Perceptual audio/video sync and audible content. Frame Control's separate
+  **Record** path stamps camera and audio inputs with the wall clock because
+  they otherwise count from different clocks.
+- Clips longer than the 100-second test and trims starting partway through a
+  Steam recording. Two real saved clips' directory layouts were checked; the
+  parser remains deliberately loose
+  for other layouts.
 - How much x264 at 1080p30 costs the Frame while a game is running.
 - Automatic copying: that 30 seconds without a write is a safe sign Steam has
  finished saving a clip, and how a once-a-minute listing feels on the Frame.
@@ -7,6 +7,9 @@ This covers three directions, plus input:
 - **C. iPhone → Frame**: mirror the phone inside the headset.
 - **PC VR from Linux**: [feasibility and options](linux-vr-streaming.md),
  including Valve's streaming and USB support. No Linux host tested yet.
+- **Linux desktop → Frame panels**: [PC-host feasibility on lxso2](evidence/linux-pc-host-lxso2-2026-10-24.md).
+  Blocked on missing desktop portal/PipeWire and native build dependencies;
+  Linux desktop capture remains disabled and unverified.
 - **Input**: type and point in the Frame from the Mac or iPhone.
 - **Live view and Control**: watch a panel flat and tap on it to use it.

@@ -285,6 +288,13 @@ How (**verified 2026-09-29**, SteamOS 0.4.1, build 20260925.6191901):
  [#73](https://github.com/saphid/frame-control/issues/73) (SteamOS 0.4.5, desktop
  open but not found). The likely cause there was the page itself: a second
  `loadPanels` (the panel switcher's) replaced the Desktop view's, fixed in #84.
+  If the `GAMESCOPE_FOCUSABLE_WINDOWS` property cannot be read, discovery now
+  reports that the panel list is unreadable and whether a panel is open is
+  unknown. A failed X connection or missing property is not evidence that the
+  desktop is closed. Check that SteamVR is running, retry or use Headset view;
+  if it persists, report the exact message and SteamOS version. The confirmed
+  empty-list advice is retained when the property is present but empty.
+  [2026-10-24 investigation and verification limits](evidence/panel-discovery-2026-10-24.md).
 - Tested from the iPhone app (Simulator): a tap on the Desktop view focused a
  text box in the panel and the text field typed into it; a trackpad move went
  exactly (+40, +25).
@@ -5,7 +5,8 @@ The Frame Control website, <https://frame-control.pages.dev>, on Cloudflare Page
 - `public/`: static pages. `/` is the landing page, `/feedback/` the feedback form, `/privacy/` the privacy note.
 - `functions/api/feedback.js`: `POST /api/feedback`, which turns the form into a GitHub issue labelled `feedback`.
 - `lib/feedback.js`: validation and issue formatting, tested by `test/feedback.test.mjs`.
- `public/js/site.js`: settings, including the Ko-fi page name for the donate buttons.
+- `public/js/site.js`: settings, including the Ko-fi page name for the donate buttons, OS hints and opening-help deep links. OS hints lead to instructions, never directly to an architecture-specific installer.
+- `test/onboarding.test.mjs`: desktop/mobile browser hints and opening-help deep links.

 ## Feedback → GitHub issues

@@ -33,3 +34,30 @@ npx wrangler pages deploy --branch main      # production
 ```

 Point `GITHUB_REPO` in `.dev.vars` at a scratch repo when testing locally so test issues don't land on the real tracker.
+
+## First-run verification
+
+Before changing download or setup instructions:
+
+- Compare every linked filename with `gh release view --repo saphid/frame-control --json tagName,assets`.
+  Browser OS hints cannot establish CPU architecture; keep every platform choice visible.
+- Run `node --test site/test/*.test.mjs` from the repo root, plus
+  `node --check site/public/js/site.js` and `node --check site/public/js/feedback.js`.
+- Serve `public/` locally (for example `python3 -m http.server 8793 --directory site/public`
+  from the repo root). Check 320px, 390px, 768px and desktop widths: section navigation,
+  the hero link, download cards, opening-help links, feedback and privacy pages. Check
+  horizontal overflow and that anchor targets clear the sticky header. Repeat with
+  JavaScript disabled: downloads and navigation must remain available.
+- Check setup labels against `app/main.js`, `scripts/connect.sh`, `ui/frame_connect.py`
+  and the Devices page. macOS discovery failure exits; Windows/Linux prompt for an IP.
+  The app's Devices → Add a headset dialog can pass an explicit address on all platforms.
+- Separate website checks from native installation and real-headset pairing evidence.
+  A successful page/link check does not verify an installer or headset approval flow.
+
+On 2026-10-24, the first-run update was checked against published v0.4.16 assets:
+all seven linked desktop installers returned HTTP 200 after redirects, as did the
+linked GitHub documentation and trailer. Local page/resource links and section
+fragments were checked; navigation stayed visible without horizontal overflow at
+320, 390, 768 and 1280 CSS pixels. Native macOS/Windows installs and real-headset
+pairing were not exercised for this documentation change. No site deployment was
+performed.
@@ -38,8 +38,13 @@ code { font: 14px ui-monospace, SFMono-Regular, Menlo, monospace; background: rg
 .top nav a { color: var(--muted); font-size: 14.5px; font-weight: 500; }
 .top nav a:hover, .top nav a[aria-current] { color: var(--bright); }
 .top .end { margin-left: auto; display: flex; gap: 10px; align-items: center; }
-@media (max-width: 880px) { .top nav { display: none; } }
-@media (max-width: 480px) { .top .end .ghost { display: none; } }
+@media (max-width: 1050px) {
+  html { scroll-padding-top: 150px; }
+  .top .wrap { height: auto; min-height: 64px; flex-wrap: wrap; gap: 8px 16px; padding-top: 12px; padding-bottom: 8px; }
+  .top nav { order: 3; width: 100%; margin-left: 0; flex-wrap: wrap; gap: 0 18px; }
+  .top nav a { padding: 8px 0; }
+}
+@media (max-width: 480px) { .top .end { display: none; } }

 /* ---- buttons ---- */
 .btn { display: inline-flex; align-items: center; justify-content: center; gap: 9px; height: 46px; padding: 0 22px; border-radius: 10px;
@@ -199,3 +204,11 @@ textarea { min-height: 180px; resize: vertical; }
 .done p { color: var(--muted); margin: 10px auto 24px; max-width: 460px; }
 .done .cta { margin-top: 0; }
 .page h1 { font-size: clamp(34px, 5vw, 48px); }
+
+/* Opening instructions remain readable on narrow screens. */
+.dl p, .setup-note { color: var(--muted); font-size: 15px; margin-top: 16px; }
+.dl { min-width: 0; }
+code { overflow-wrap: anywhere; }
+pre { white-space: pre-wrap; overflow-wrap: anywhere; }
+pre code { background: none; padding: 0; }
+@media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto; } }
@@ -4,7 +4,7 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Frame Control: manage your Steam Frame from your computer</title>
-<meta name="description" content="Free, open-source app for the Valve Steam Frame. See what the headset sees, install Steam games and Android apps, move files and text across, and check battery and status. macOS, Windows, Linux and iPhone.">
+<meta name="description" content="Free, open-source app for the Valve Steam Frame. See what the headset sees, install Steam games and Android apps, move files and text across, and check battery and status. Desktop downloads for macOS, Windows and Linux; iPhone build instructions.">
 <meta name="theme-color" content="#0e141b">
 <link rel="icon" href="/favicon.png">
 <link rel="apple-touch-icon" href="/apple-touch-icon.png">
@@ -41,13 +41,13 @@
 <main>
 <section class="hero">
  <div class="wrap">
-    <span class="eyebrow"><b>Free and open source</b><span class="sep"> · </span><span class="plats">macOS · Windows · Linux · iPhone</span></span>
+    <span class="eyebrow"><b>Free and open source</b><span class="sep"> · </span><span class="plats">macOS · Windows · Linux</span></span>
    <h1>Your Steam Frame, <span>managed from your desk.</span></h1>
-    <p class="lede">See what the headset sees, install games and Android apps, move files and text across, and keep an eye on battery and status. All over SSH, with nothing to install on the Frame.</p>
+    <p class="lede">See what the headset sees, install games and Android apps, move files and text across, and keep an eye on battery and status. Install Frame Control on your computer, then connect to your headset over SSH. This website provides downloads and instructions; it does not control the headset in your browser.</p>
    <div class="cta">
      <a class="btn primary" id="hero-download" href="#download">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3v12m0 0-5-5m5 5 5-5M4 20h16"/></svg>
-        <span data-label>Download Frame Control</span>
+        <span data-label>Choose your computer’s download</span>
      </a>
      <a class="btn ghost" href="#trailer">
        <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M8 5.5v13a1 1 0 0 0 1.5.86l10.5-6.5a1 1 0 0 0 0-1.72L9.5 4.64A1 1 0 0 0 8 5.5z"/></svg>
@@ -173,7 +173,7 @@
    <div class="head">
      <span class="kicker">iPhone and iPad</span>
      <h2>Also in your pocket</h2>
-      <p>The same features on iPhone and iPad, served from the Frame itself, so there's nothing to run on a computer. Build it from the repo in Xcode.</p>
+      <p>The same features on iPhone and iPad, served from the Frame itself, so there's nothing to run on a computer. There is no App Store, TestFlight or iOS download in the current release. Building it requires a Mac, Xcode and your own signing team. <a href="https://github.com/saphid/frame-control/blob/main/docs/iphone.md">iPhone build and pairing instructions</a>.</p>
    </div>
    <div class="phones">
      <img src="/img/phone-home.jpg" width="600" height="1304" loading="lazy" alt="Frame Control on iPhone: headset view and device status.">
@@ -186,23 +186,24 @@
  <div class="wrap">
    <div class="head">
      <span class="kicker">Setup</span>
-      <h2>One password, typed once</h2>
-      <p>Everything else happens on your computer.</p>
+      <h2>Connect your computer to the Frame</h2>
+      <p>First <a href="#download">install and open the desktop app</a>. Keep the headset awake, on the same trusted network as your computer. Guest Wi-Fi or client isolation can block the connection.</p>
    </div>
    <div class="steps">
      <div class="card">
-        <h3>Turn on Developer Mode</h3>
-        <p>On the Frame: Steam Settings → System → <b>Enable Developer Mode</b>, then <b>Set User Password</b> in the Developer section.</p>
+        <h3>Prepare the headset</h3>
+        <p>On the Frame: Steam Settings → System → <b>Enable Developer Mode</b>, then Developer → <b>Set User Password</b>. Choose a password that isn't easy to guess; it also protects remote desktop and <code>sudo</code>.</p>
      </div>
      <div class="card">
-        <h3>Set up the connection</h3>
-        <p>Open Frame Control and choose <b>Set Up Connection</b>. It finds the headset, makes an SSH key, and asks for that password once.</p>
+        <h3>Run connection setup</h3>
+        <p>In the desktop app, choose <b>Set Up Connection…</b>. If you skipped the first prompt, use <b>Frame → Set Up Connection…</b>. A terminal opens. If discovery fails, find the Frame's IP in Quick Settings or Steam Settings → Internet. Windows/Linux setup prompts for it. On macOS, return to the app → <b>Devices &amp; connection → + Add a headset…</b>, use SSH alias <code>frame</code> for the default headset, enter the IP in <b>Address</b> and choose <b>Set Up…</b>.</p>
      </div>
      <div class="card">
-        <h3>That's it</h3>
-        <p>The app reaches the headset whenever it's awake and on the same network. For anywhere else, use <a href="https://github.com/saphid/frame-control/blob/main/docs/tailscale.md">Tailscale</a>.</p>
+        <h3>Pair, with a password fallback</h3>
+        <p>Setup tries Valve's pairing first: open Developer → <b>Pair new host</b> in the headset and approve only your request. If it fails or times out, enter the Developer Mode password in the computer's terminal (typing may be invisible), then press Enter.</p>
      </div>
    </div>
+    <p class="setup-note">The devkit service and pairing-mode step were checked on a Frame; approval and key installation through that flow remain unverified. <a href="https://github.com/saphid/frame-control/blob/main/docs/ssh.md#password-free-pairing-steamos-devkit-service">Pairing details</a>. After setup succeeds, return to the app; future connections use SSH keys. Still offline? Check Developer Mode, the IP and network isolation, then rerun setup. For use away from home, see <a href="https://github.com/saphid/frame-control/blob/main/docs/tailscale.md">Tailscale</a>.</p>
  </div>
 </section>

@@ -211,32 +212,39 @@
    <div class="head">
      <span class="kicker">Download</span>
      <h2>Get Frame Control</h2>
-      <p>Free, with Python and adb built in. <span hidden>Version <span data-version></span>.</span> <a href="https://github.com/saphid/frame-control/releases">Release notes</a></p>
+      <p>Choose your computer’s OS and processor, not the headset’s. Python is bundled; Linux needs <code>ssh</code>, and arm64 Linux also needs your distribution’s <code>adb</code> for Android apps. <span hidden>Version <span data-version></span>.</span> <a href="https://github.com/saphid/frame-control/releases">Release notes</a></p>
    </div>
    <div class="downloads">
-      <div class="dl" data-os="mac">
-        <div class="os"><svg viewBox="0 0 24 24" fill="currentColor"><path d="M16.37 12.6c-.02-2.2 1.8-3.26 1.88-3.31-1.02-1.5-2.62-1.7-3.19-1.72-1.36-.14-2.65.8-3.34.8-.69 0-1.75-.78-2.88-.76a4.27 4.27 0 0 0-3.6 2.19c-1.53 2.66-.39 6.6 1.1 8.76.73 1.06 1.6 2.24 2.74 2.2 1.1-.04 1.51-.71 2.84-.71 1.32 0 1.7.71 2.86.69 1.18-.02 1.93-1.08 2.65-2.14.83-1.23 1.18-2.41 1.2-2.47-.03-.01-2.3-.88-2.32-3.5zM14.2 6.13c.6-.73 1.01-1.75.9-2.76-.87.04-1.92.58-2.54 1.3-.56.64-1.05 1.67-.92 2.66.97.08 1.96-.49 2.56-1.2z"/></svg><h3>macOS</h3><span class="tag" hidden>Your system</span></div>
-        <span class="need">Apple Silicon</span>
+      <div class="dl" id="download-mac" data-os="mac">
+        <div class="os"><svg viewBox="0 0 24 24" fill="currentColor"><path d="M16.37 12.6c-.02-2.2 1.8-3.26 1.88-3.31-1.02-1.5-2.62-1.7-3.19-1.72-1.36-.14-2.65.8-3.34.8-.69 0-1.75-.78-2.88-.76a4.27 4.27 0 0 0-3.6 2.19c-1.53 2.66-.39 6.6 1.1 8.76.73 1.06 1.6 2.24 2.74 2.2 1.1-.04 1.51-.71 2.84-.71 1.32 0 1.7.71 2.86.69 1.18-.02 1.93-1.08 2.65-2.14.83-1.23 1.18-2.41 1.2-2.47-.03-.01-2.3-.88-2.32-3.5zM14.2 6.13c.6-.73 1.01-1.75.9-2.76-.87.04-1.92.58-2.54 1.3-.56.64-1.05 1.67-.92 2.66.97.08 1.96-.49 2.56-1.2z"/></svg><h3>macOS</h3><span class="tag" hidden>OS detected</span></div>
+        <span class="need">Apple Silicon (M-series) only · no Intel Mac build</span>
        <div class="links">
          <a class="btn primary" href="https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-mac-arm64.dmg">Download .dmg</a>
        </div>
+        <p>Check Apple menu → About This Mac for your chip. Open the DMG, drag Frame Control to Applications, then open it there. Allow local network access and Terminal control when asked.</p>
+        <p>The app isn't notarized. <a href="#mac-opening">macOS opening instructions</a>.</p>
      </div>
-      <div class="dl" data-os="windows">
-        <div class="os"><svg viewBox="0 0 24 24" fill="currentColor"><path d="M3 5.5 10 4.5v7H3zM11 4.35 21 3v8.5H11zM3 12.5h7v7L3 18.5zM11 12.5h10V21l-10-1.4z"/></svg><h3>Windows</h3><span class="tag" hidden>Your system</span></div>
+      <div class="dl" id="download-windows" data-os="windows">
+        <div class="os"><svg viewBox="0 0 24 24" fill="currentColor"><path d="M3 5.5 10 4.5v7H3zM11 4.35 21 3v8.5H11zM3 12.5h7v7L3 18.5zM11 12.5h10V21l-10-1.4z"/></svg><h3>Windows</h3><span class="tag" hidden>OS detected</span></div>
        <span class="need">Windows 10 or 11, x64</span>
        <div class="links">
          <a class="btn primary" href="https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-Setup-x64.exe">Download installer</a>
          <a class="btn ghost" href="https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-win-x64.zip">Portable .zip</a>
        </div>
+        <p>Check Settings → System → About → System type. No native Windows ARM build is published. Run the installer, then open Frame Control from Start. The OpenSSH Client optional feature must be installed (it normally is). For portable use, extract the entire ZIP and run <code>Frame Control.exe</code>.</p>
+        <p>The installer isn't code-signed. <a href="#windows-opening">SmartScreen instructions</a>.</p>
      </div>
-      <div class="dl" data-os="linux">
-        <div class="os"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="4" width="18" height="16" rx="2"/><path d="m7 9 3 3-3 3M13 15h4"/></svg><h3>Linux</h3><span class="tag" hidden>Your system</span></div>
+      <div class="dl" id="download-linux" data-os="linux">
+        <div class="os"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="4" width="18" height="16" rx="2"/><path d="m7 9 3 3-3 3M13 15h4"/></svg><h3>Linux</h3><span class="tag" hidden>OS detected</span></div>
        <span class="need">x64 or arm64 · needs <code>ssh</code></span>
        <div class="links">
          <a class="btn primary" href="https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-linux-x86_64.AppImage">AppImage (x64)</a>
          <a class="btn ghost" href="https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-linux-amd64.deb">.deb (x64)</a>
          <a class="btn ghost" href="https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-linux-arm64.AppImage">AppImage (arm64)</a>
+          <a class="btn ghost" href="https://github.com/saphid/frame-control/releases/latest/download/Frame-Control-linux-arm64.deb">.deb (arm64)</a>
        </div>
+        <p>Run <code>uname -m</code>: <code>x86_64</code> means x64; <code>aarch64</code> means arm64. Install the matching .deb on Debian/Ubuntu and open Frame Control from your applications menu, or use AppImage on other distributions.</p>
+        <p><a href="#linux-opening">AppImage permissions and FUSE help</a>. On arm64 Debian/Ubuntu, install <code>adb</code> with <code>sudo apt install adb</code> for Android apps.</p>
      </div>
    </div>
  </div>
@@ -249,15 +257,22 @@
      <h2>Good questions</h2>
    </div>
    <div class="faq">
-      <details>
+      <details id="mac-opening">
        <summary>macOS says the app is damaged or can't be checked</summary>
-        <div><p>The app isn't notarized, because there's no paid Apple developer account behind it. Drag it to Applications, then clear the download quarantine once in Terminal:</p>
+        <div><p>The app isn't notarized, because there's no paid Apple developer account behind it. Only for a download you trust from the releases linked above: drag it to Applications, then clear the download quarantine once in Terminal:</p>
        <p><code>xattr -dr com.apple.quarantine "/Applications/Frame Control.app"</code></p></div>
      </details>
-      <details>
+      <details id="windows-opening">
        <summary>Windows SmartScreen says it protected my PC</summary>
        <div><p>The installer isn't code-signed. Choose <b>More info → Run anyway</b>, or use the portable .zip: unzip it anywhere and run <code>Frame Control.exe</code>.</p></div>
      </details>
+      <details id="linux-opening">
+        <summary>How do I open the Linux AppImage?</summary>
+        <div><p>In a terminal in your download folder, use the exact filename for your architecture. For x64:</p>
+        <pre><code>chmod +x Frame-Control-linux-x86_64.AppImage
+./Frame-Control-linux-x86_64.AppImage</code></pre>
+        <p>If FUSE is missing, install <code>libfuse2</code> (Ubuntu 24.04+: <code>libfuse2t64</code>), or run the same AppImage with <code>--appimage-extract-and-run</code>. Install your distribution’s OpenSSH client if <code>ssh</code> is missing.</p></div>
+      </details>
      <details>
        <summary>What does it change on my headset?</summary>
        <div><p>Only what you click. Installs go to your user account on the Frame, and nothing needs <code>sudo</code> except the power buttons. On your computer it adds a <code>Host frame</code> entry to <code>~/.ssh/config</code> and two SSH keys.</p></div>
@@ -5,8 +5,6 @@ const SITE = {
  kofi: "alexsouthwell",
 };

-const RELEASE = `https://github.com/${SITE.repo}/releases/latest/download/`;
-
 // Donate buttons.
 for (const el of document.querySelectorAll("[data-kofi]")) {
  if (SITE.kofi) el.href = `https://ko-fi.com/${SITE.kofi}`;
@@ -15,37 +13,39 @@ for (const el of document.querySelectorAll("[data-kofi]")) {
 for (const el of document.querySelectorAll("[data-needs-kofi]")) el.hidden = !SITE.kofi;
 for (const el of document.querySelectorAll("[data-no-kofi]")) el.hidden = !!SITE.kofi;

-// Best guess at the visitor's platform, for the hero button and the download cards.
+// Browser hints identify an OS, not a reliable CPU architecture. Always show
+// the install instructions and all choices before starting a download.
 function detectPlatform() {
  const ua = navigator.userAgent;
  const hint = navigator.userAgentData?.platform || navigator.platform || "";
-  if (/iPhone|iPad|iPod/.test(ua) || (/Mac/.test(hint) && navigator.maxTouchPoints > 1)) return "ios";
-  if (/Android/.test(ua)) return null;
+  if (/iPhone|iPad|iPod|Android/.test(ua) || (/Mac/.test(hint) && navigator.maxTouchPoints > 1)) return null;
  if (/Mac/.test(hint) || /Macintosh/.test(ua)) return "mac";
  if (/Win/.test(hint) || /Windows/.test(ua)) return "windows";
-  if (/Linux/.test(hint) || /Linux/.test(ua)) return /aarch64|arm64/i.test(ua + hint) ? "linux-arm" : "linux";
+  if (/Linux/.test(hint) || /Linux/.test(ua)) return "linux";
  return null;
 }

-const PLATFORMS = {
-  mac: { name: "macOS", file: "Frame-Control-mac-arm64.dmg" },
-  windows: { name: "Windows", file: "Frame-Control-Setup-x64.exe" },
-  linux: { name: "Linux", file: "Frame-Control-linux-x86_64.AppImage" },
-  "linux-arm": { name: "Linux (arm64)", file: "Frame-Control-linux-arm64.AppImage" },
-};
-
 const platform = detectPlatform();
 const hero = document.getElementById("hero-download");
-if (hero && PLATFORMS[platform]) {
-  hero.href = RELEASE + PLATFORMS[platform].file;
-  hero.querySelector("[data-label]").textContent = `Download for ${PLATFORMS[platform].name}`;
+if (hero && platform) {
+  hero.href = `#download-${platform}`;
+  const name = { mac: "macOS", windows: "Windows", linux: "Linux" }[platform];
+  hero.querySelector("[data-label]").textContent = `Choose a ${name} download`;
 }
-const card = platform && document.querySelector(`.dl[data-os="${platform.replace("-arm", "")}"]`);
+const card = platform && document.querySelector(`.dl[data-os="${platform}"]`);
 if (card) {
  card.classList.add("mine");
  card.querySelector(".tag").hidden = false;
 }

+// Keep linked opening instructions visible, including direct FAQ deep links.
+function revealInstructions() {
+  const target = document.getElementById(location.hash.slice(1));
+  if (target?.tagName === "DETAILS") target.open = true;
+}
+window.addEventListener("hashchange", revealInstructions);
+revealInstructions();
+
 // Latest version number, so the page never goes stale. Fails quietly.
 const versionEls = document.querySelectorAll("[data-version]");
 if (versionEls.length) {
@@ -0,0 +1,59 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { runInNewContext } from 'node:vm';
+
+const script = readFileSync(new URL('../public/js/site.js', import.meta.url), 'utf8');
+const html = readFileSync(new URL('../public/index.html', import.meta.url), 'utf8');
+
+function visit(navigator, hash = '') {
+  const label = { textContent: 'Choose your computer’s download' };
+  const hero = { href: '#download', querySelector: () => label };
+  const cards = Object.fromEntries(['mac', 'windows', 'linux'].map(os => [os, {
+    classes: [], classList: { add(name) { cards[os].classes.push(name); } },
+    tag: { hidden: true }, querySelector() { return this.tag; },
+  }]));
+  const details = { tagName: 'DETAILS', open: false };
+  const listeners = {};
+  const context = {
+    navigator, location: { hash }, window: { addEventListener: (name, fn) => { listeners[name] = fn; } },
+    document: {
+      querySelectorAll: () => [],
+      getElementById: id => id === 'hero-download' ? hero : id === 'mac-opening' ? details : null,
+      querySelector: selector => cards[selector.match(/data-os="([^"]+)"/)[1]],
+    },
+  };
+  runInNewContext(script, context);
+  return { hero, cards, details, listeners, context };
+}
+
+for (const [name, navigator, expected] of [
+  ['Intel Mac', { platform: 'MacIntel', userAgent: 'Macintosh' }, 'mac'],
+  ['Apple Silicon browser with Intel hint', { platform: 'MacIntel', userAgent: 'Macintosh', userAgentData: { platform: 'macOS' } }, 'mac'],
+  ['Windows', { platform: 'Win32', userAgent: 'Windows NT 10.0' }, 'windows'],
+  ['Linux x64', { platform: 'Linux x86_64', userAgent: 'Linux x86_64' }, 'linux'],
+  ['Linux ARM', { platform: 'Linux aarch64', userAgent: 'Linux aarch64' }, 'linux'],
+  ['iPhone', { platform: 'iPhone', userAgent: 'iPhone' }, null],
+  ['iPad desktop mode', { platform: 'MacIntel', userAgent: 'Macintosh', maxTouchPoints: 5 }, null],
+  ['Android', { platform: 'Linux armv8l', userAgent: 'Linux Android' }, null],
+  ['unknown', { userAgent: '' }, null],
+]) {
+  test(`${name} opens choices instead of guessing an installer architecture`, () => {
+    const { hero, cards } = visit(navigator);
+    assert.equal(hero.href, expected ? `#download-${expected}` : '#download');
+    assert.ok(html.includes(`id="${hero.href.slice(1)}"`));
+    assert.deepEqual(Object.keys(cards).filter(os => !cards[os].tag.hidden), expected ? [expected] : []);
+  });
+}
+
+test('opening help expands for direct and in-page links; unknown fragments are safe', () => {
+  const result = visit({ userAgent: '' }, '#mac-opening');
+  assert.equal(result.details.open, true);
+  result.details.open = false;
+  result.context.location.hash = '#unknown';
+  result.listeners.hashchange();
+  assert.equal(result.details.open, false);
+  result.context.location.hash = '#mac-opening';
+  result.listeners.hashchange();
+  assert.equal(result.details.open, true);
+});
@@ -23,7 +23,8 @@ function fixture() {
  const page = element('controlCenter');
  page.querySelectorAll = selector => selector === '[data-cc-category]' ? buttons : selector === '[data-cc-metric]' ? metrics : selector === '[data-cc-mac-link]' ? [element('macLink')] : [];
  page.querySelector = selector => selector === '[href="#connection"]' ? element('connectionLink') : cards.find(e=>selector === `[data-cc-card="${e.dataset.ccCard}"]`);
-  return {document:{getElementById:element},element,cards,buttons};
+  const listeners = {};
+  return {document:{hidden:false,getElementById:element,addEventListener(name,callback){listeners[name]=callback;}},listeners,element,cards,buttons};
 }
 function mounted(options = {}) {
  const f = fixture(), calls = [];
@@ -39,8 +40,10 @@ const flush = async () => { for(let i=0;i<12;i++)await Promise.resolve(); };
 // bootstrap, including the real Home-to-Control status handoff. Only unrelated
 // rendering helpers, timers and transport are stubbed.
 function sharedPage({productionApi=false} = {}) {
-  const f=fixture(), requests=[], writes=[], host=deferred(), job=deferred();
-  const context={document:f.document,FrameControlCenter:cc,window:{frameApp:{setUpConnection(){}}},
+  const f=fixture(), requests=[], writes=[], notifications=[], host=deferred(), job=deferred();
+  let now=0;
+  const context={document:f.document,FrameControlCenter:cc,performance:{now:()=>now},
+    window:{frameApp:{setUpConnection(){},notify:async(message,request)=>{notifications.push({message,request});}}},
    Date,setInterval,clearInterval,setTimeout:()=>1,clearTimeout(){},$:f.element,QUICK:[],installing:new Set(),
    battery(){},setVolume(){},renderHome(){},gb:String,dur:String,esc:String,meter(){},toast(){},
    runJob(title,id){context.installing.add(id);return job.promise;},
@@ -52,7 +55,11 @@ function sharedPage({productionApi=false} = {}) {
    watchConnection(){context.watched=true;}};
  vm.createContext(context);
  const stateDeclaration=pageSource.match(/let state = null[^\n]*/)[0];
-  vm.runInContext(stateDeclaration+'\nlet online = true, devGen = 1; const HOST = {computer:"computer"}; window.connDevice="frame-a";',context);
+  vm.runInContext(stateDeclaration+'\nlet online = true, devGen = 1, comfortActive = false; const HOST = {computer:"computer"}; window.connDevice="frame-a";',context);
+  // Load the real alert state machine and DOM wiring used by render, refresh,
+  // setOnline and onConnection; do not stub away their lifecycle behavior.
+  const batteryStart=pageSource.indexOf('class DesktopBatteryAlert'),batteryEnd=pageSource.indexOf('// ---- battery ----',batteryStart);
+  vm.runInContext(pageSource.slice(batteryStart,batteryEnd),context);
  const refreshStart=pageSource.indexOf('let refreshing = null'),refreshEnd=pageSource.indexOf('// ---- our VR HUD',refreshStart);
  const renderStart=pageSource.indexOf('function render(s) {'),renderEnd=pageSource.indexOf('// ---- view ----',renderStart);
  vm.runInContext(pageSource.slice(renderStart,renderEnd)+pageSource.slice(refreshStart,refreshEnd),context);
@@ -80,12 +87,48 @@ function sharedPage({productionApi=false} = {}) {
  const hostStart=pageSource.lastIndexOf('api("/api/host").then(h =>'),hostEnd=pageSource.indexOf('</script>',hostStart);
  vm.runInContext(pageSource.slice(hostStart,hostEnd),context);
  const bootstrapStart=pageSource.indexOf('window.frameControlCenter = FrameControlCenter.mount('),bootstrapEnd=pageSource.indexOf('</script>',bootstrapStart);
-  return {...f,context,requests,writes,host,refresh:()=>vm.runInContext('refresh()',context),
+  return {...f,context,requests,writes,notifications,host,setNow(value){now=value;},refresh:()=>vm.runInContext('refresh()',context),
    switchHeadset:()=>vm.runInContext('onConnection({now:Date.now()/1000,phase:"connected",devices_rev:0,device:{id:"frame-b",name:"Second Frame"}})',context),
    installFlatpak:()=>vm.runInContext('installFlatpak("test.app")',context),
    mount(){vm.runInContext(pageSource.slice(bootstrapStart,bootstrapEnd),context);return context.window.frameControlCenter;}};
 }
 const response = data => ({ok:true,status:200,json:async()=>data});
+test('production refresh confirms desktop alerts and failures interrupt confirmation', async () => {
+  const f=sharedPage({productionApi:true});
+  const low=sample();low.battery={percent:15,status:'Discharging',watts:-4};
+  const read=async(now,data=low)=>{
+    f.setNow(now);const pending=f.refresh();
+    f.requests.at(-1).resolve(response(data));await pending;
+  };
+  await read(0);await read(30000);
+  assert.equal(f.notifications.length,0,'desktop alert starts off');
+  f.element('desktopBatteryAlert').checked=true;
+  f.element('desktopBatteryAlert').onchange();
+  await read(60000);
+  const failed=f.refresh();f.requests.at(-1).reject(Error('Status transport failed'));await failed;
+  await read(90000);
+  assert.equal(f.notifications.length,0,'failed status interrupts low-battery confirmation');
+  await read(120000);
+  assert.equal(f.notifications.length,1);
+  assert.match(f.notifications[0].message,/15%.*draining/);
+  assert.equal(f.notifications[0].request,false,'refresh never requests notification permission');
+  await read(150000);
+  assert.equal(f.notifications.length,1,'same episode stays latched');
+  assert.equal(f.requests.length,7,'only explicit existing status reads are used');
+});
+test('production headset switch clears desktop opt-in and pending confirmation', async () => {
+  const f=sharedPage({productionApi:true});
+  f.element('desktopBatteryAlert').checked=true;
+  const low=sample();low.battery={percent:10,status:'Discharging',watts:-3};
+  const pending=f.refresh();f.requests[0].resolve(response(low));await pending;
+  assert.equal(vm.runInContext('desktopBattery.pending.condition',f.context),'low');
+  f.setNow(30000);f.switchHeadset();
+  assert.equal(f.element('desktopBatteryAlert').checked,false);
+  assert.equal(vm.runInContext('desktopBattery.pending',f.context),null);
+  assert.match(f.element('desktopBatteryStatus').textContent,/Headset changed/);
+  f.requests[1].resolve(response(low));await flush();
+  assert.equal(f.notifications.length,0,'new headset cannot inherit the prior opt-in');
+});
 for(const rejection of ['transport','body'])for(const delayedMount of [false,true]) {
  test(`production ${rejection} rejection from A preserves B ${delayedMount ? 'before delayed mount' : 'after mount'}`, async t => {
    const f=sharedPage({productionApi:true});
@@ -40,6 +40,15 @@ function page(answer) {
  if (!p.noPanelWhy().startsWith("The headset's desktop is running")) fail("why for capture: " + p.noPanelWhy());
  if (!p.ctrlTarget().why.startsWith("The headset's desktop is running")) fail("why for control: " + p.ctrlTarget().why);
 }
+// An unreadable list is unknown: both Capture and Control retain that distinction.
+{
+  const why = "Frame Control couldn't read gamescope's panel list, so it can't tell whether an app panel is open. " +
+    "Check that SteamVR is running in the headset, then try again or use the Headset view. " +
+    "If this persists, report your SteamOS version and this exact message.";
+  const p = page(() => ({ panels: [], focus: null, why }));
+  await p.loadPanels();
+  if (p.noPanelWhy() !== why || p.ctrlTarget().why !== why) fail("unreadable list reason lost");
+}
 // An older headset script without "why": the generic advice.
 {
  const p = page(() => ({ panels: [], focus: null }));
@@ -0,0 +1,105 @@
+"""Exercise the shipped desktop alert and its UI with a monotonic fake clock."""
+import pathlib
+import shutil
+import subprocess
+import unittest
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+
+
+@unittest.skipUnless(shutil.which('node'), 'Node exercises production page JavaScript')
+class DesktopBatteryComfort(unittest.TestCase):
+    def test_alert_confirmation_and_lifecycle(self):
+        page = (ROOT / 'ui/index.html').read_text(encoding='utf-8')
+        code = page.split('// ---- Desktop-only low-battery comfort:')[1].split('// ---- battery ----')[0]
+        code = code[code.index('class DesktopBatteryAlert'):]
+        js = r'''
+const assert = require('node:assert/strict');
+const elements = new Map();
+const $ = id => {
+  if (!elements.has(id)) elements.set(id, {checked:false, textContent:''});
+  return elements.get(id);
+};
+let now = 0, calls = [], toasts = [], devGen = 1, comfortActive = false;
+const performance = {now:()=>now};
+const listeners = {};
+const document = {hidden:false, addEventListener:(name,fn)=>listeners[name]=fn};
+const HOST = {mobile:false};
+const window = {frameApp:{notify:(message,request)=>{calls.push({message,request});return Promise.resolve();}}};
+const toast = message => toasts.push(message);
+''' + code + r'''
+(async () => {
+  const low = {percent:15,status:'Discharging',watts:-4};
+  const high = {...low,percent:20};
+  const a = new DesktopBatteryAlert();
+  assert.equal(a.sample(low,0),false);
+  assert.equal(a.sample(low,1000),false); // rapid manual refreshes cannot confirm
+  assert.equal(a.sample(low,30000),true);
+  for (let t=60000;t<=900000;t+=30000) assert.equal(a.sample(low,t),false);
+  assert.equal(a.sample(high,930000),false);
+  assert.equal(a.sample(low,960000),false); // a recovery spike did not rearm
+  assert.equal(a.sample(low,990000),false);
+  a.sample(high,1020000); a.sample(high,1050000);
+  assert.equal(a.sample(low,1080000),false);
+  assert.equal(a.sample(low,1110000),true);
+  const c = new DesktopBatteryAlert();
+  c.sample(low,0); assert.equal(c.sample(low,30000),true);
+  c.sample(high,60000); c.sample(high,90000);
+  c.sample(low,120000); assert.equal(c.sample(low,150000),false); // ten minute cap
+  assert.equal(c.sample(low,631000),false); // long gap requires fresh confirmation
+  assert.equal(c.sample(low,661000),true);
+  for (const bad of [null,{}, {...low,percent:null}, {...low,percent:NaN}, {...low,percent:-1},
+      {...low,percent:101},{...low,percent:'10'}, {...low,status:'Unknown'},
+      {...low,status:'Charging'}, {...low,status:'Full'}, {...low,status:'Not charging'},
+      {...low,watts:0},{...low,watts:-0.5},{...low,watts:null},{...low,watts:NaN}]) {
+    const b = new DesktopBatteryAlert();
+    b.sample(low,0); assert.equal(b.sample(bad,30000),false);
+    assert.equal(b.sample(low,60000),false); // unknown interrupts confirmation
+  }
+  const b = new DesktopBatteryAlert();
+  b.sample(low,0); b.invalidate(); assert.equal(b.sample(low,30000),false);
+  assert.equal(b.sample(low,121000),false); // stale gap
+  assert.equal(b.sample(low,120000),false); // clock rollback
+  desktopBatterySample(low); now=30000; desktopBatterySample(low);
+  assert.equal(calls.length,0); // opt-in starts unchecked
+  $('desktopBatteryAlert').checked=true; $('desktopBatteryAlert').onchange();
+  now=60000;desktopBatterySample(low);now=90000;desktopBatterySample(low);
+  assert.equal(calls.length,1); assert.equal(calls[0].request,false);
+  assert.match(calls[0].message,/15%.*draining/);
+  $('desktopBatteryAlert').checked=false;$('desktopBatteryAlert').onchange();
+  $('desktopBatteryAlert').checked=true;$('desktopBatteryAlert').onchange();
+  now=120000;desktopBatterySample(low);now=150000;desktopBatterySample(low);
+  assert.equal(calls.length,1); // toggling does not clear episode latch
+  desktopBattery.latched=false;desktopBattery.lastAlert=-Infinity;desktopBattery.invalidate();
+  now=180000;desktopBatterySample(low);document.hidden=true;listeners.visibilitychange();
+  document.hidden=false;now=210000;desktopBatterySample(low);assert.equal(calls.length,1);
+  now=240000;desktopBatterySample(low);assert.equal(calls.length,2);
+  desktopBattery.latched=false;desktopBattery.lastAlert=-Infinity;desktopBattery.invalidate();
+  comfortActive=true;$('batteryAlert').checked=true;
+  now=270000;desktopBatterySample(low);now=300000;desktopBatterySample(low);
+  assert.equal(calls.length,2); // existing session owns battery alerts
+  comfortActive=false;HOST.mobile=true;
+  now=330000;desktopBatterySample(low);now=360000;desktopBatterySample(low);
+  assert.equal(calls.length,2);
+  HOST.mobile=false;
+  window.frameApp.notify=()=>Promise.reject(Error('denied'));
+  now=390000;desktopBatterySample(low);now=420000;desktopBatterySample(low);
+  await new Promise(setImmediate);
+  assert.match($('desktopBatteryStatus').textContent,/not confirmed/);
+  now=450000;desktopBatterySample(low);
+  assert.equal(toasts.length,3); // delivery failure does not retry on refresh
+})().catch(e=>{console.error(e);process.exitCode=1;});
+'''
+        result = subprocess.run(['node', '-e', js], capture_output=True, text=True)
+        self.assertEqual(result.returncode, 0, result.stderr)
+
+    def test_existing_status_path_and_switch_reset(self):
+        page = (ROOT / 'ui/index.html').read_text(encoding='utf-8')
+        self.assertIn('desktopBatterySample(s.battery);', page)
+        switch = page.split('if (link.device !== null && devId !== link.device)')[1].split('devGen++;')[0]
+        self.assertIn('$("desktopBatteryAlert").checked = false;', switch)
+        refresh = page.split('function refresh()')[1].split('async function refreshAfterAudio')[0]
+        self.assertIn('desktopBattery.invalidate();', refresh)
+        block = page.split('// ---- Desktop-only low-battery comfort:')[1].split('// ---- battery ----')[0]
+        self.assertNotIn('setTimeout', block)
+        self.assertNotIn('api(', block)
@@ -355,6 +355,8 @@ class FindingPanels(unittest.TestCase):
        t.subprocess.run = lambda *a, **k: subprocess.CompletedProcess(a, 0, out, "")
        self.assertEqual(self.real_read_props(":0"), {"GAMESCOPE_FOCUSABLE_WINDOWS": [1, 0, 2, 3, 769, 4],
                                                      "GAMESCOPE_FOCUSED_WINDOW": [0]})
+        t.subprocess.run = lambda *a, **k: subprocess.CompletedProcess(a, 0, "GAMESCOPE_FOCUSABLE_WINDOWS(CARDINAL) = \n", "")
+        self.assertEqual(self.real_read_props(":0"), {"GAMESCOPE_FOCUSABLE_WINDOWS": []})
        t.subprocess.run = lambda *a, **k: subprocess.CompletedProcess(a, 0, "GAMESCOPE_FOCUSED_WINDOW:  not found.\n", "")
        self.assertEqual(self.real_read_props(":0"), {})

@@ -392,17 +394,52 @@ class FindingPanels(unittest.TestCase):
        self.assertIn("Headset view", out["why"])

    def test_desktop_running_but_not_listed(self):
+        self.props[(":0", "GAMESCOPE_FOCUSABLE_WINDOWS")] = []
        self.t.desktop_running = lambda: True
        out = self.t.panels()
        self.assertEqual(out["panels"], [])
        self.assertIn("desktop is running", out["why"])

    def test_nothing_open(self):
+        self.props[(":0", "GAMESCOPE_FOCUSABLE_WINDOWS")] = []
        out = self.t.panels()
        self.assertEqual(out, {"focus": None, "focus_display": None, "panels": [],
                               "why": "No app panel is open in the headset. Open the desktop or an app in "
                                      "the headset, then try again."})

+    def test_absent_list_is_unknown_even_when_desktop_is_running(self):
+        for desktop in (False, True):
+            with self.subTest(desktop=desktop):
+                self.t.desktop_running = lambda: desktop
+                self.t._ROOT.clear()
+                out = self.t.panels()
+                self.assertEqual(out["panels"], [])
+                self.assertIn("couldn't read gamescope's panel list", out["why"])
+                self.assertIn("can't tell whether", out["why"])
+                self.assertIn("Headset view", out["why"])
+                self.assertNotIn("No app panel is open", out["why"])
+
+    def test_focus_property_without_panel_list_is_unknown(self):
+        self.props[(":0", "GAMESCOPE_FOCUSED_WINDOW")] = [0]
+        self.assertIn("couldn't read gamescope's panel list", self.t.panels()["why"])
+
+    def test_failed_xprop_does_not_claim_no_panels_are_open(self):
+        t = self.t
+        t.read_props = self.real_read_props
+        saved = t.subprocess.run
+        self.addCleanup(setattr, t.subprocess, "run", saved)
+        for failure in ("refused", "timeout"):
+            with self.subTest(failure=failure):
+                def run(*args, **kwargs):
+                    if failure == "timeout":
+                        raise subprocess.TimeoutExpired(args[0], kwargs["timeout"])
+                    return subprocess.CompletedProcess(args[0], 1, "", "Can't open display")
+                t.subprocess.run = run
+                t._ROOT.clear()
+                out = t.panels()
+                self.assertIn("couldn't read gamescope's panel list", out["why"])
+                self.assertNotIn("No app panel is open", out["why"])
+
    def test_missing_x_tools_are_named(self):
        self.plasma_on(":0")
        self.t.shutil.which = lambda tool: None if tool == "xwininfo" else "/usr/bin/" + tool
@@ -10,6 +10,8 @@ function connectionFixture() {
    sourceState:{jobs:new Map(),detail:null,detailRequest:0},touches:new Map(),gesture:null,padType:{blur(){},value:''},
    log(){},renderPill(){},renderConnDlg(){},renderHome(){},resetShots(){},resetClips(){},renderBanner(){},loadDevices(){},renderDevices(){},renderTests(){},viaText(){return 'test';},netLabel(){return 'test';},refresh:()=>Promise.resolve(),reloadAll(){},checkContactPrompt(){},ctrlReset(){},padShow:s=>{c.pad.state=s.state;}});
  c.window.connDevice='a';
+  c.document.addEventListener=()=>{};
+  f.run(pick(html,'class DesktopBatteryAlert {','// ---- battery ----'));
  f.run('const UI_KEY="test";'+pick(html,'const HEADSET_FREE =','// What a panel shows'));
  f.run(pick(html,'function onConnection(s) {','// Read the event stream'));
  return f;
@@ -41,8 +43,15 @@ test('a device switch discards completed install results and the open detail',()
  Object.assign(c,{pad:{state:'off',queue:[]},padReset(){},sourceState:{jobs:new Map([['test:one',{done:true,result:{package:'app.on.a',game_data:true}}]]),detail:{app:{}},detailRequest:0}});
  f.el('appDetail').open=true;
  f.el('storageResult').textContent='Old headset storage';
+  f.el('desktopBatteryAlert').checked=true;
+  f.run('desktopBattery.pending={condition:"low",at:0};desktopBattery.latched=true;desktopBattery.lastAlert=42;');
  f.run('onConnection({phase:"connected",device:{id:"b",name:"B"},devices_rev:1,now:0})');
  assert.match(f.el('storageResult').textContent,/Headset changed/);
+  assert.equal(f.el('desktopBatteryAlert').checked,false);
+  assert.equal(f.run('desktopBattery.pending'),null);
+  assert.equal(f.run('desktopBattery.latched'),false);
+  assert.equal(f.run('desktopBattery.lastAlert'),42);
+  assert.match(f.el('desktopBatteryStatus').textContent,/Off.*Headset changed/);
  assert.equal(c.sourceState.jobs.size,0);assert.equal(c.sourceState.detail,null);assert.equal(f.el('appDetail').open,false);
 });
 test('only a preview matching current diagnostics consent can be sent or copied',async()=>{
@@ -271,7 +271,7 @@ def panels(limit=None):
        out["why"] = ("The headset took too long to list its panels (its X tools didn't answer in time). "
                      + ("Some may be missing. " if found else "") + "Try again, or use the Headset view.")
    elif not found:
-        out["why"] = why_none(unfound)
+        out["why"] = why_none(unfound, props)
    return out


@@ -295,13 +295,18 @@ def desktop_running():
    return False


-def why_none(listed):
+def why_none(listed, props):
    """Why panels() found nothing, in words the person at the computer can act on.
-    listed: how many of the windows gamescope lists aren't X11 windows on any display."""
+    listed: how many of the windows gamescope lists aren't X11 windows on any display.
+    props: the root properties actually read; an absent list is not an empty list."""
    missing = [tool for tool in ("xprop", "xwininfo") if not shutil.which(tool)]
    if missing:
        return (f"This SteamOS build has no {' or '.join(missing)}, which Frame Control uses to find the "
                "headset's panels. Use the Headset view instead, and please report your SteamOS version.")
+    if "GAMESCOPE_FOCUSABLE_WINDOWS" not in props:
+        return ("Frame Control couldn't read gamescope's panel list, so it can't tell whether an app panel is open. "
+                "Check that SteamVR is running in the headset, then try again or use the Headset view. "
+                "If this persists, report your SteamOS version and this exact message.")
    if listed:
        # gamescope lists windows, but none is an X11 window on any display: a Wayland
        # window (a desktop drawn straight to gamescope, say) can't be found or captured this way.
@@ -1465,6 +1465,12 @@
    </details>
  </section><section class="panel" id="comfort" style="margin:20px 0;padding:16px">
    <div class="shelf-head"><h2>Family and comfort</h2><span class="count">Session timer and reminders</span></div>
+    <div id="desktopBatteryComfort" hidden>
+      <h3>Desktop low-battery alert</h3>
+      <label><input id="desktopBatteryAlert" type="checkbox"> Alert on this computer at 15% or less</label>
+      <p class="hint">No session timer needed. Off when this page opens or you switch headsets. Uses normal status refreshes while the page is visible; no extra polling or headset changes. Two readings must confirm low charge and battery drain. One alert until charge recovers to 20%, with at least ten minutes between alerts.</p>
+      <p id="desktopBatteryStatus" class="hint" role="status">Off.</p>
+    </div>
    <form id="comfortForm">
      <div class="row" style="flex-wrap:wrap;gap:12px">
        <label>Session limit (minutes) <input id="sessionMinutes" type="number" min="1" max="240" value="30" required style="width:75px"></label>
@@ -2130,6 +2136,7 @@ const HOST = { computer: "computer" };
 function applyHostWording(h) {
  Object.assign(HOST, h);
  window.frameControlCenter?.host(h);
+  $("desktopBatteryComfort").hidden = !!h.mobile || !window.frameApp?.notify;
  // The iPhone app: the server runs on the Frame, and saving goes to the phone's Photos.
  document.body.classList.toggle("mobile", !!h.mobile);
  $("shotsFolder").hidden = !!h.mobile;
@@ -2240,6 +2247,7 @@ function setOnline(ok, why) {
  if (HOST.mobile) $('mobileConnectionStatus').textContent = ok ? 'Connected to the Frame serving this session.' : 'The Frame is disconnected. Retry or check its address in connection setup.';
  $('offline').hidden = ok;
  if (!ok) {
+    desktopBattery.invalidate();
    $("offMsg").textContent = why || "Can't reach the Frame";
    setConn(false, "Offline");
    $("battChip").hidden = true; closeDevPop();
@@ -2276,6 +2284,7 @@ function refresh() {
      setConn(true, state.hostname);
      setOnline(true);
    } catch (e) {
+      desktopBattery.invalidate();
      renderPerformance(null);
      if (!e.stale) stateRead = {valid: false, error: e};
      renderHome();
@@ -2456,6 +2465,60 @@ $("castBtn").onclick = () => {
  $("viewer").requestFullscreen?.().catch(() => {});
 };

+// ---- Desktop-only low-battery comfort: consumes existing status, never polls ----
+class DesktopBatteryAlert {
+  constructor() {
+    this.pending = null;
+    this.latched = false;
+    this.lastAlert = -Infinity;
+  }
+  invalidate() { this.pending = null; }
+  sample(b, now) {
+    // Require actual drain as well as driver state: plugged-in idle can report Discharging.
+    const valid = Number.isFinite(b?.percent) && b.percent >= 0 && b.percent <= 100 &&
+      ["Charging", "Discharging", "Full", "Not charging"].includes(b.status);
+    const low = valid && b.percent <= 15 && b.status === "Discharging" &&
+      Number.isFinite(b.watts) && b.watts < -0.5;
+    const recovered = valid && b.percent >= 20;
+    const condition = low ? "low" : recovered ? "recovered" : null;
+    if (!condition) { this.invalidate(); return false; }
+    if (!this.pending || this.pending.condition !== condition || now - this.pending.at > 90000 || now < this.pending.at) {
+      this.pending = {condition, at: now};
+      return false;
+    }
+    if (now - this.pending.at < 20000) return false;
+    if (recovered) this.latched = false;
+    if (!low || this.latched || now - this.lastAlert < 600000) return false;
+    this.latched = true;
+    this.lastAlert = now;  // latch even when system delivery fails; never retry on each refresh
+    return true;
+  }
+}
+const desktopBattery = new DesktopBatteryAlert();
+$("desktopBatteryAlert").onchange = () => {
+  desktopBattery.invalidate();
+  $("desktopBatteryStatus").textContent = $("desktopBatteryAlert").checked
+    ? "On. Waiting for two fresh status readings confirming low charge and battery drain."
+    : "Off.";
+};
+function desktopBatterySample(b) {
+  if (!$("desktopBatteryAlert").checked || HOST.mobile || !window.frameApp?.notify || document.hidden ||
+      (comfortActive && $("batteryAlert").checked)) {
+    desktopBattery.invalidate();
+    return;
+  }
+  if (!desktopBattery.sample(b, performance.now())) return;
+  const message = `Frame battery is low (${b.percent}%) and draining. Consider charging or taking a break.`;
+  $("desktopBatteryStatus").textContent = message;
+  toast(message);
+  // Desktop bridge only: never prompt or send a phone/browser push from a status refresh.
+  const generation = devGen;
+  window.frameApp.notify(message, false).catch(() => {
+    if (generation !== devGen || !$("desktopBatteryAlert").checked) return;
+    $("desktopBatteryStatus").textContent = message + " System notification delivery was not confirmed. Check system settings or use Enable / test notifications below.";
+  });
+}
+document.addEventListener("visibilitychange", () => desktopBattery.invalidate());
 // ---- battery ----
 function battery(b, power) {
  const pct = b?.percent;
@@ -2511,6 +2574,7 @@ function render(s) {
  renderHome(s);
  window.frameControlCenter?.status(s, stateReceivedAt, stateRead);
  battery(s.battery, s.power);
+  desktopBatterySample(s.battery);
  $("devPopTitle").textContent = $("devPopTitle").title = window.connName || "Headset";
  $("devName").textContent = `${s.hostname} · ${s.ip ?? "no IP"}`;
  $("updated").textContent = new Date(s.time * 1000).toLocaleTimeString();
@@ -6898,6 +6962,11 @@ function onConnection(s) {
    stateReceivedAt = null;
    stateRead = {valid: false, error: null};
    online = null;
+    $("desktopBatteryAlert").checked = false;
+    desktopBattery.invalidate();
+    // Keep the cooldown across switches, but a new headset can start its own charge episode.
+    desktopBattery.latched = false;
+    $("desktopBatteryStatus").textContent = "Off. Headset changed; enable for this headset if wanted.";
    devGen++;               // answers still on their way are about the other headset
    padReset(); ctrlReset();
    sourceState.jobs.clear(); sourceState.detail = null; sourceState.detailRequest++;
Author	SHA1	Message	Date
SAPHID	93689ec871	Document packaged Return to Game Mode button verification	2026-10-24 09:29:56 +00:00
Alex SouthwellandSAPHID	71288d8980	Document packaged desktop Steam clip Export verification (#156 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-24 09:19:46 +00:00
Alex SouthwellandSAPHID	64b9babe87	Document Linux PC-host feasibility blocker on lxso2 (#155 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-24 09:17:14 +00:00
Alex SouthwellandSAPHID	4e456480ae	Document real 100-second Steam clip export (#154 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-24 09:05:12 +00:00
Alex SouthwellandSAPHID	241f538f99	Bump version to 0.4.17 (#153 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-24 08:43:00 +00:00
Alex SouthwellandSAPHID	21dacfcbe7	Distinguish unreadable panel discovery from an empty list (#152 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-24 08:34:56 +00:00
Alex SouthwellandSAPHID	eb181d8996	Add opt-in desktop low-battery comfort alerts (#150 ) * Add opt-in desktop low-battery comfort alerts * Fix desktop battery alert test harness and Windows encoding --------- Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-24 08:22:56 +00:00
Alex SouthwellandSAPHID	827ddcf14f	Clarify desktop installation and first headset connection (#151 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-24 08:08:47 +00:00
Alex SouthwellandSAPHID	7c3894e630	docs: record real Frame clip Export button check (#149 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-24 08:04:06 +00:00
Alex SouthwellandSAPHID	040581a4c7	Bump Frame Control to 0.4.16 (#148 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-24 07:42:37 +00:00
Alex SouthwellandSAPHID	17f6d52717	Document real Steam clip export verification (#147 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-24 07:34:34 +00:00
Alex SouthwellandSAPHID	b4e80cab0a	Escape power report CSV metadata for spreadsheets (#146 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-24 07:28:26 +00:00