Bump version to 0.4.17 (#153 )

Co-authored-by: SAPHID <saphid@users.noreply.github.com>
Distinguish unreadable panel discovery from an empty list (#152 )
2026-10-24 18:01:56 +02:00 · 2026-10-24 08:43:00 +00:00 · 2026-10-24 08:34:56 +00:00 · 2026-10-24 08:22:56 +00:00 · 2026-10-24 08:08:47 +00:00 · 2026-10-24 08:04:06 +00:00
22 changed files with 776 additions and 89 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.16",
+  "version": "0.4.17",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "frame-control",
-      "version": "0.4.16",
+      "version": "0.4.17",
      "license": "MIT",
      "devDependencies": {
        "electron": "^44.4.5",
@@ -1,7 +1,7 @@
 {
  "name": "frame-control",
  "productName": "Frame Control",
-  "version": "0.4.16",
+  "version": "0.4.17",
  "description": "Desktop app for managing a Valve Steam Frame over SSH",
  "private": true,
  "main": "main.js",
@@ -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,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,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.
@@ -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
@@ -162,16 +162,22 @@ was released, and the battery remained at 99%. The Steam source clip was kept.

 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**. The literal desktop **Export** button was not clicked. Remaining
-checks include:
+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.
+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.
 - Long saved clips, trims starting partway through a Steam recording, and the
-  desktop **Export** button. One real saved clip's
-  directory layout was checked; the parser remains deliberately loose for
-  other layouts.
+  packaged desktop app's **Export** button. One real saved clip's directory
+  layout was 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.
@@ -285,6 +285,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
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