Merge pull request #131 from saphid/fix/issue-87-recovery-polish

Fix remaining host-key recovery UI clipping and punctuation

.github/workflows/pc-host.yml

@@ -0,0 +1,53 @@
+name: PC host libraries
+# PC in the headset (Experimental). The Windows job builds the native adapter
+# and runs the real-encoder protocol tests; the installer's own bundle is
+# tested in release.yml. The Linux adapter from PR #38 isn't shipped or offered
+# in the app, but shares capture.c and controller.c, so it's still built here.
+# These builds add the GPL x264 encoder for headless tests only: they're never
+# uploaded or shipped.
+on:
+  pull_request:
+    paths: ["desktop/**", "ui/**", "tests/**", "scripts/macview-bench.py", ".github/workflows/pc-host.yml"]
+  workflow_dispatch:
+jobs:
+  linux:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Native libraries
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libglib2.0-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-pipewire libpipewire-0.3-modules libspa-0.2-modules
+          python3 desktop/build.py --with-x264
+      - name: Tests (real x264, fake capture consent/input)
+        env:
+          FRAME_PC_REQUIRE_NATIVE: "1"
+          FRAME_PC_REQUIRE_X264: "1"
+        run: python3 -m unittest discover -s tests -p 'test_pc*.py' -v
+  windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: msys2/setup-msys2@v2
+        with:
+          msystem: UCRT64
+          update: true
+      # A mirror's HTTP 429 once failed this install (2026-10-24): retry, so a
+      # flaky mirror can't break a release build.
+      - name: MSYS2 packages for the PC host
+        shell: msys2 {0}
+        run: |
+          for attempt in 1 2 3; do
+            pacman -S --needed --noconfirm mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-pkgconf mingw-w64-ucrt-x86_64-python mingw-w64-ucrt-x86_64-gstreamer mingw-w64-ucrt-x86_64-gst-plugins-base mingw-w64-ucrt-x86_64-gst-plugins-good mingw-w64-ucrt-x86_64-gst-plugins-bad mingw-w64-ucrt-x86_64-gst-plugins-ugly && exit 0
+            sleep $((attempt * 30))
+          done
+          exit 1
+      - name: Native build and tests (x264; WGC and MF need a desktop/GPU)
+        shell: msys2 {0}
+        run: |
+          python desktop/build.py --with-x264
+          FRAME_PC_REQUIRE_NATIVE=1 FRAME_PC_REQUIRE_X264=1 python -m unittest discover -s tests -p 'test_pc*.py' -v

.github/workflows/release.yml

@@ -3,14 +3,14 @@ name: release
 # Pushing a v* tag builds Frame Control for macOS, Windows and Linux and attaches
 # the installers to that tag's GitHub release (created as a draft if missing).
 # Pull requests that change how the installers are built (the Electron app, the
-# macOS helper it compiles, or this workflow) build the same installers as
+# Windows PC helper libraries, the macOS helper, or this workflow) build the same installers as
 # artifacts. ui/, scripts/, frame/ and apk-catalog/ are copied in as they are and
 # are tested by the checks workflow; run this one by hand to package them early.
 on:
   push:
     tags: ["v*"]
   pull_request:
-    paths: ["app/**", "mac/frame-mac-view/**", ".github/workflows/release.yml"]
+    paths: ["app/**", "desktop/**", "mac/frame-mac-view/**", ".github/workflows/release.yml"]
   workflow_dispatch:
 
 # A newer push to the same pull request supersedes a build still in progress.
@@ -75,6 +75,28 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: "24"
+      # PC in the headset (Experimental, Windows only): our capture adapter and
+      # the GStreamer libraries it uses, bundled into resources/desktop/bundle.
+      - uses: msys2/setup-msys2@v2
+        if: runner.os == 'Windows'
+        with:
+          msystem: UCRT64
+          update: true
+      # A mirror's HTTP 429 once failed this install (2026-10-24): retry, so a
+      # flaky mirror can't break a release build.
+      - name: MSYS2 packages for the PC host
+        if: runner.os == 'Windows'
+        shell: msys2 {0}
+        run: |
+          for attempt in 1 2 3; do
+            pacman -S --needed --noconfirm mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-pkgconf mingw-w64-ucrt-x86_64-python mingw-w64-ucrt-x86_64-gstreamer mingw-w64-ucrt-x86_64-gst-plugins-base mingw-w64-ucrt-x86_64-gst-plugins-good mingw-w64-ucrt-x86_64-gst-plugins-bad mingw-w64-ucrt-x86_64-gst-plugins-ugly && exit 0
+            sleep $((attempt * 30))
+          done
+          exit 1
+      - name: Windows PC streaming libraries
+        if: runner.os == 'Windows'
+        shell: msys2 {0}
+        run: python desktop/build.py --out app/build/desktop/win-x64
       - name: Build
         working-directory: app
         shell: bash
@@ -95,6 +117,19 @@ jobs:
           for ($i = 0; $i -lt 60 -and -not (Test-Path (Join-Path $installed 'Uninstall Frame Control.exe')); $i++) { Start-Sleep 2 }
           node app/build/check-resources.js (Join-Path $installed 'resources') app/dist/win-unpacked/resources
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+      # From the installed app, so this also proves the installer carries the
+      # libraries. After the check above, and without writing __pycache__,
+      # so it can't change what that check compares.
+      - name: Test the installed app's Python with the Windows PC libraries
+        if: runner.os == 'Windows'
+        shell: bash
+        env:
+          PYTHONDONTWRITEBYTECODE: "1"
+        run: |
+          resources="$(cygpath -u "$LOCALAPPDATA")/Programs/Frame Control/resources"
+          python="$resources/python/python.exe"
+          native="$(cygpath -w "$resources/desktop/bundle")"
+          FRAME_PC_NATIVE="$native" FRAME_PC_REQUIRE_NATIVE=1 FRAME_PC_INSTALLER_BUNDLE=1 "$python" -B -m unittest discover -s tests -p 'test_pc*.py' -v
       - name: Upload to the release
         if: startsWith(github.ref, 'refs/tags/')
         shell: bash

.gitignore

@@ -7,5 +7,15 @@ compat-db/.lakebed/
 tests/smoke/results/
 mac/bin/
 
+# Shared desktop streaming controller build products
+desktop/controller.dll
+desktop/controller.dylib
+desktop/controller.so
+desktop/*.obj
+desktop/*.lib
+desktop/*.exp
+desktop/bundle/
+app/build/desktop/
+
 # Downloaded at build time (frame/kdeconnect/fetch.py, app/build/fetch-deps.js)
 frame/kdeconnect/packages/

CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## Unreleased
+
+- Keep the full host-key recovery explanation readable in Devices, including
+  long addresses, and remove doubled punctuation from the connection tooltip
+  (issue #87). Refresh stays within the header and switching headsets selects
+  the new headset's details.
+
+- Fix experimental PC screen capture on Windows builds whose streaming libraries
+  lack Windows Graphics Capture. Whole screens use Desktop Duplication; individual
+  windows are hidden with an explanation instead of failing when shown. A Windows
+  VM streamed a real desktop to the Frame; physical input remains unverified.
+
+- Add read-only battery health in Tools: charging state, temperature, cycle count,
+  and available capacity with explicit unknown states. The parser was checked
+  on a real Frame; the connected desktop UI was tested with synthetic readings.
+
+- Add Tools → Game storage: read-only headset filesystem capacity and Steam
+  library/game install-size breakdown, with unknown sizes, partial inventories
+  and permission/missing-drive states. Includes instructions for Steam's own
+  Move UI; Frame Control does not move or delete game files. The read-only
+  parser was checked on a real Frame; the connected UI and game moves were not.
+
+- Add `scripts/frame-doctor.sh` for read-only setup and pairing diagnostics,
+  with verified SSH identity, private summaries and actionable next steps
+  (issue #34). Connection steps links to the diagnostic guide. Repairs remain
+  manual; restart-loop evidence stops deeper diagnostics. The real Frame
+  verified the SSH connection and safety stop; deeper checks were skipped.
+- Fixed headset smoke cleanup reporting success while a smoke-title process
+  could remain running after its files were removed. Cleanup now stops and
+  rechecks processes tied to exact reserved test-title paths, uses PID handles
+  for safe TERM/KILL escalation, and records stopped PIDs. Unrelated titles and
+  shared Wine services are left alone. Verified with local Linux process
+  regressions and a 13/13 real Frame smoke run that stopped five test-owned
+  Proton process PIDs before removing the Windows test title.

README.md

@@ -226,6 +226,7 @@ Frame's software fits together, all checked against a real headset and labelled
 | [Sideloading Linux and Windows games](docs/sideloading.md) | A .zip, folder or .exe as a Steam Devkit Game, runtime detection |
 | [Install links for websites](docs/web-install.md) | `frame-control://install` links and manifests, the rules, a button to paste |
 | [VR comfort and HUD](docs/vr-utilities.md) · [Steam games](docs/steam-games.md) · [VR video](docs/vr-video.md) · [WebXR in Chromium](docs/webxr-chromium.md) | Installing and buying, watching VR180/360, the Chromium build |
+| [PC in the headset](docs/pc-in-headset.md) | Experimental, Windows only, off until you turn it on: a whole PC screen as a panel in the Frame. Tested in a Windows VM; individual windows need a WGC-enabled build |
 | [Mac in the headset](docs/mac-in-headset.md) | Mac windows and screens as panels in the Frame, with laser and keyboard input |
 | [VR mods and custom songs](docs/mods.md) | UEVR for Unreal games from Frame Control (install, play in VR, remove), the per-game table, Beat Saber blockers |
 | [SSH](docs/ssh.md) · [Streaming](docs/streaming.md) · [Files](docs/file-transfer.md) · [Panels](docs/panels.md) · [Tailscale](docs/tailscale.md) | Topic notes |
@@ -274,3 +275,5 @@ into a draft release, which reaches users once published. See
 licence, notably KDE Connect (GPL) for the keyboard and trackpad; see
 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Steam, Steam Frame and SteamVR are trademarks of Valve
 Corporation. This project isn't affiliated with or endorsed by Valve.
+
+See [Game storage](docs/game-storage.md) for read-only headset space and Steam install sizes, and [the changelog](CHANGELOG.md) for unreleased changes.

THIRD_PARTY_NOTICES.md

@@ -10,6 +10,8 @@ ship other people's software, unchanged, each under its own licence:
 | adb (Android SDK Platform-Tools) | Desktop apps (not Linux arm64) | Apache-2.0 and others | `NOTICE.txt` in the app's `tools` folder |
 | Mozilla's CA certificate list, as published by curl | Desktop apps | MPL-2.0 | https://curl.se/docs/caextract.html |
 | Electron | Desktop apps | MIT (Chromium: BSD-3-Clause and others) | `LICENSE` and `LICENSES.chromium.html` in the app |
+| GStreamer 1.x, a few of its plugins and the libraries they need, as [MSYS2](https://packages.msys2.org/) builds them | Windows app only, for the experimental [PC in the headset](docs/pc-in-headset.md) | LGPL-2.1-or-later and others (per package); the GPL x264 encoder is left out | `libraries.json` (exact package versions) and the `licenses` folder in the app's `desktop/bundle` folder |
 
 Frame Control starts KDE Connect and talks to it over its network protocol;
-it doesn't link to it or include its code.
+it doesn't link to it or include its code. On Windows, Frame Control's own
+`pc-host.dll` links to GStreamer dynamically; the libraries are unmodified.

app/package-lock.json

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

app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frame-control",
   "productName": "Frame Control",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "Desktop app for managing a Valve Steam Frame over SSH",
   "private": true,
   "main": "main.js",
@@ -198,7 +198,16 @@
         "zip"
       ],
       "icon": "build/icon.png",
-      "artifactName": "Frame-Control-win-${arch}.${ext}"
+      "artifactName": "Frame-Control-win-${arch}.${ext}",
+      "extraResources": [
+        {
+          "from": "build/desktop/${os}-${arch}",
+          "to": "desktop/bundle",
+          "filter": [
+            "**/*"
+          ]
+        }
+      ]
     },
     "nsis": {
       "oneClick": false,

app/preferences.js

@@ -1,7 +1,7 @@
 // Client choices live outside the local server's changing URL/origin.
 const fs = require("node:fs");
 const path = require("node:path");
-const KEYS = ["mvSeparate", "padUsed"];
+const KEYS = ["mvSeparate", "padUsed", "pcView"];
 const valid = value => value === "0" || value === "1";
 
 function preferenceStore(file) {

app/test/preferences.test.js

@@ -36,7 +36,7 @@ test("client choices survive a new native session and local server origin", t =>
   assert.deepEqual(first.read(), { mvSeparate: "1", padUsed: "1" });
 });
 
-test("only the two non-sensitive binary choices can enter the native store", t => {
+test("only the non-sensitive binary choices can enter the native store", t => {
   const file = fixture(t), store = preferenceStore(file);
   for (const [key, value] of [["token", "secret"], ["__proto__", "1"], ["padUsed", true], ["mvSeparate", "yes"]]) {
     assert.throws(() => store.write(key, value), /Invalid preference/);
@@ -58,3 +58,11 @@ test("a missing or damaged preference file retains usable defaults", t => {
   store.write("padUsed", "1");
   assert.deepEqual(store.read(), { padUsed: "1" });
 });
+
+test("the PC in the headset opt-in is remembered and off unless saved", t => {
+  const file = fixture(t), store = preferenceStore(file);
+  assert.equal(store.read().pcView, undefined);
+  store.write("pcView", "1");
+  assert.deepEqual(preferenceStore(file).read(), { pcView: "1" });
+  assert.throws(() => store.write("pcView", "on"), /Invalid preference/);
+});

bench/results/2026-09-28-c5fc552-dirty-pc-agent-frame-arm64-hairpin.json

@@ -0,0 +1,311 @@
+{
+ "label": "pc-agent-frame-arm64-hairpin",
+ "date": "2026-09-28T22:36:19",
+ "commit": "c5fc552+dirty",
+ "config": {
+  "quality": "balanced",
+  "mode": "separate",
+  "net": "none",
+  "delay_ms": 0,
+  "buffer_ms": 250,
+  "host": "frame",
+  "usb": false,
+  "ssh_opts": [],
+  "encoder": "",
+  "duration_s": 10.0,
+  "browser_flags": []
+ },
+ "frame_build": "20260925.6191901",
+ "mac": "26.5.2",
+ "host_platform": "Linux aarch64, SteamOS Frame, BUILD_ID 20260925.6191901 (synthetic host only)",
+ "source": "",
+ "pc_host": true,
+ "headset": "0:03.056203 [Info] - 1 - leaving standby",
+ "scenarios": [
+  {
+   "scenario": "test",
+   "frames_sent": 351,
+   "frames_drawn": 351,
+   "frames_shown": 324,
+   "duration_s": 10.1,
+   "stages_ms": {
+    "capture": {
+     "p50": 0.1,
+     "p95": 0.2,
+     "p99": 0.5,
+     "n": 351
+    },
+    "queue": {
+     "p50": 0.1,
+     "p95": 0.3,
+     "p99": 0.4,
+     "n": 351
+    },
+    "encode": {
+     "p50": 2.0,
+     "p95": 2.9,
+     "p99": 3.5,
+     "n": 351
+    },
+    "socket": {
+     "p50": 0.1,
+     "p95": 0.4,
+     "p99": 0.6,
+     "n": 351
+    },
+    "network": {
+     "p50": 11.6,
+     "p95": 75.7,
+     "p99": 130.1,
+     "n": 351
+    },
+    "decode": {
+     "p50": 0.7,
+     "p95": 2.1,
+     "p99": 4.1,
+     "n": 351
+    },
+    "draw": {
+     "p50": 0.4,
+     "p95": 0.8,
+     "p99": 1.1,
+     "n": 351
+    },
+    "present": {
+     "p50": 0.8,
+     "p95": 18.1,
+     "p99": 24.9,
+     "n": 324
+    },
+    "content": {
+     "p50": 15.1,
+     "p95": 80.3,
+     "p99": 134.2,
+     "n": 351
+    },
+    "content_shown": {
+     "p50": 21.0,
+     "p95": 71.8,
+     "p99": 146.3,
+     "n": 324
+    }
+   },
+   "fps": 34.8,
+   "fps_shown": 32.0,
+   "late_pct": 53.41,
+   "stall_max": 226.8,
+   "stalls_over_100ms": 7,
+   "mbps": 0.26,
+   "keyframes": 6,
+   "size": "1280x720",
+   "captured": 607,
+   "viewer_never_drawn": 0,
+   "input_ms": {
+    "p50": 43.3,
+    "p95": 98.4,
+    "p99": 110.1,
+    "n": 18
+   },
+   "input_shown_ms": {
+    "p50": 54.7,
+    "p95": 98.9,
+    "p99": 114.0,
+    "n": 18
+   },
+   "input_parts_ms": {
+    "uplink": {
+     "p50": 17.1,
+     "p95": 48.3,
+     "p99": 53.1,
+     "n": 18
+    },
+    "mac": {
+     "p50": 12.5,
+     "p95": 32.9,
+     "p99": 35.7,
+     "n": 18
+    },
+    "back": {
+     "p50": 16.8,
+     "p95": 50.0,
+     "p99": 55.9,
+     "n": 18
+    }
+   },
+   "inputs": {
+    "asked": 18,
+    "sent": 18,
+    "seen": 18
+   },
+   "timeline": [
+    {
+     "t": 0,
+     "fps": 38,
+     "mbps": 0.3,
+     "content_p50": 14.8,
+     "content_p95": 25.3,
+     "bitrate": 2764800,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 1,
+     "fps": 33,
+     "mbps": 0.24,
+     "content_p50": 15.6,
+     "content_p95": 103.5,
+     "bitrate": 3845448,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 2,
+     "fps": 39,
+     "mbps": 0.28,
+     "content_p50": 15.6,
+     "content_p95": 29.9,
+     "bitrate": 5283790,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 3,
+     "fps": 25,
+     "mbps": 0.21,
+     "content_p50": 17.8,
+     "content_p95": 175.9,
+     "bitrate": 2764800,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 4,
+     "fps": 34,
+     "mbps": 0.22,
+     "content_p50": 15.4,
+     "content_p95": 69.8,
+     "bitrate": 2764800,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 5,
+     "fps": 38,
+     "mbps": 0.29,
+     "content_p50": 17.7,
+     "content_p95": 68.7,
+     "bitrate": 2764800,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 6,
+     "fps": 38,
+     "mbps": 0.26,
+     "content_p50": 15.0,
+     "content_p95": 18.2,
+     "bitrate": 3091280,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 7,
+     "fps": 30,
+     "mbps": 0.22,
+     "content_p50": 19.2,
+     "content_p95": 111.0,
+     "bitrate": 1725204,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 8,
+     "fps": 35,
+     "mbps": 0.26,
+     "content_p50": 13.4,
+     "content_p95": 102.6,
+     "bitrate": 1725204,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 9,
+     "fps": 38,
+     "mbps": 0.28,
+     "content_p50": 12.3,
+     "content_p95": 20.9,
+     "bitrate": 1725204,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 10,
+     "fps": 3,
+     "mbps": 0.02,
+     "content_p50": 20.9,
+     "content_p95": 24.7,
+     "bitrate": 1725204,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    }
+   ],
+   "adapt": [],
+   "content_p50": 15.1,
+   "content_p95": 80.3,
+   "input_p50": 43.3,
+   "input_p95": 98.4,
+   "grades": {
+    "input_replies": "local",
+    "content_p50": "local",
+    "content_p95": "acceptable",
+    "input_p50": "local",
+    "input_p95": "acceptable",
+    "fps": "bad",
+    "late_pct": "bad",
+    "stall_max": "acceptable"
+   },
+   "controller": {
+    "target": 3442081,
+    "ceiling": 5529600,
+    "tier": 0,
+    "fps": 60,
+    "scale": 1.0,
+    "baseRtt": 13.334,
+    "inFlight": 1,
+    "slack": 71.738,
+    "adapt": true
+   },
+   "events": [
+    {
+     "t": 3.77,
+     "e": "target 2764800 bit/s; tier 0"
+    },
+    {
+     "t": 7.42,
+     "e": "target 1725204 bit/s; tier 0"
+    }
+   ],
+   "source_fps": 60.1,
+   "cpu": {
+    "host": "not sampled"
+   },
+   "viewer": "h264 software; ANGLE (Mesa, zink Vulkan 1.4(Turnip Adreno (TM) 750 (MESA_TURNIP)), OpenGL 4.6); raf 71 Hz",
+   "show_s": 1.88,
+   "panel": "valve.steam.desktopgame.2001932457",
+   "src": "test",
+   "route": "network"
+  }
+ ],
+ "proof": "Synthetic x264 PC agent runs on the Frame itself, forwarded via Mac and back. Not Windows/Linux desktop capture or laser input."
+}

bench/results/2026-09-28-cd20243-pc-agent-frame-arm64-final.json

@@ -0,0 +1,302 @@
+{
+ "label": "pc-agent-frame-arm64-final",
+ "date": "2026-09-28T22:55:27",
+ "commit": "cd20243",
+ "config": {
+  "quality": "balanced",
+  "mode": "native",
+  "net": "none",
+  "delay_ms": 0,
+  "buffer_ms": 250,
+  "host": "frame",
+  "usb": false,
+  "ssh_opts": [],
+  "encoder": "",
+  "duration_s": 10.0,
+  "browser_flags": []
+ },
+ "frame_build": "20260925.6191901",
+ "mac": "26.5.2",
+ "host_platform": "Linux aarch64, SteamOS Frame, BUILD_ID 20260925.6191901 (synthetic host only)",
+ "source": "",
+ "pc_host": true,
+ "headset": "0:03.056203 [Info] - 1 - leaving standby",
+ "scenarios": [
+  {
+   "scenario": "test",
+   "frames_sent": 400,
+   "frames_drawn": 400,
+   "frames_shown": 339,
+   "duration_s": 10.2,
+   "stages_ms": {
+    "capture": {
+     "p50": 0.1,
+     "p95": 0.1,
+     "p99": 0.2,
+     "n": 400
+    },
+    "queue": {
+     "p50": 0.1,
+     "p95": 0.2,
+     "p99": 0.4,
+     "n": 400
+    },
+    "encode": {
+     "p50": 2.0,
+     "p95": 2.7,
+     "p99": 3.1,
+     "n": 400
+    },
+    "socket": {
+     "p50": 0.1,
+     "p95": 0.3,
+     "p99": 0.4,
+     "n": 400
+    },
+    "network": {
+     "p50": 11.8,
+     "p95": 25.2,
+     "p99": 37.8,
+     "n": 400
+    },
+    "decode": {
+     "p50": 0.7,
+     "p95": 1.5,
+     "p99": 2.0,
+     "n": 400
+    },
+    "draw": {
+     "p50": 0.3,
+     "p95": 0.7,
+     "p99": 1.0,
+     "n": 400
+    },
+    "present": {
+     "p50": 0.8,
+     "p95": 19.3,
+     "p99": 26.8,
+     "n": 339
+    },
+    "content": {
+     "p50": 15.1,
+     "p95": 28.6,
+     "p99": 41.3,
+     "n": 400
+    },
+    "content_shown": {
+     "p50": 17.6,
+     "p95": 39.0,
+     "p99": 47.2,
+     "n": 339
+    }
+   },
+   "fps": 39.3,
+   "fps_shown": 33.4,
+   "late_pct": 50.25,
+   "stall_max": 69.3,
+   "stalls_over_100ms": 0,
+   "mbps": 0.35,
+   "keyframes": 6,
+   "size": "1280x720",
+   "captured": 612,
+   "viewer_never_drawn": 0,
+   "input_ms": {
+    "p50": 76.6,
+    "p95": 98.2,
+    "p99": 127.8,
+    "n": 19
+   },
+   "input_shown_ms": {
+    "p50": 80.5,
+    "p95": 107.8,
+    "p99": 128.1,
+    "n": 16
+   },
+   "input_parts_ms": {
+    "uplink": {
+     "p50": 36.5,
+     "p95": 57.6,
+     "p99": 83.2,
+     "n": 19
+    },
+    "mac": {
+     "p50": 14.6,
+     "p95": 31.3,
+     "p99": 31.7,
+     "n": 19
+    },
+    "back": {
+     "p50": 15.1,
+     "p95": 32.8,
+     "p99": 36.2,
+     "n": 19
+    }
+   },
+   "inputs": {
+    "asked": 19,
+    "sent": 19,
+    "seen": 19
+   },
+   "timeline": [
+    {
+     "t": 0,
+     "fps": 40,
+     "mbps": 0.34,
+     "content_p50": 11.7,
+     "content_p95": 27.4,
+     "bitrate": 5529600,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 1,
+     "fps": 39,
+     "mbps": 0.37,
+     "content_p50": 11.9,
+     "content_p95": 28.2,
+     "bitrate": 5529600,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 2,
+     "fps": 41,
+     "mbps": 0.35,
+     "content_p50": 11.4,
+     "content_p95": 16.6,
+     "bitrate": 5529600,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 3,
+     "fps": 39,
+     "mbps": 0.37,
+     "content_p50": 12.7,
+     "content_p95": 28.0,
+     "bitrate": 5529600,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 4,
+     "fps": 38,
+     "mbps": 0.33,
+     "content_p50": 15.3,
+     "content_p95": 30.0,
+     "bitrate": 5529600,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 5,
+     "fps": 39,
+     "mbps": 0.37,
+     "content_p50": 16.7,
+     "content_p95": 28.5,
+     "bitrate": 5529600,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 6,
+     "fps": 41,
+     "mbps": 0.38,
+     "content_p50": 15.9,
+     "content_p95": 29.4,
+     "bitrate": 5529600,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 7,
+     "fps": 41,
+     "mbps": 0.31,
+     "content_p50": 15.6,
+     "content_p95": 28.2,
+     "bitrate": 5529600,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 8,
+     "fps": 38,
+     "mbps": 0.38,
+     "content_p50": 15.5,
+     "content_p95": 25.9,
+     "bitrate": 5529600,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 9,
+     "fps": 38,
+     "mbps": 0.29,
+     "content_p50": 16.7,
+     "content_p95": 28.8,
+     "bitrate": 5529600,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    },
+    {
+     "t": 10,
+     "fps": 6,
+     "mbps": 0.03,
+     "content_p50": 17.6,
+     "content_p95": 23.1,
+     "bitrate": 5529600,
+     "tier": 0,
+     "w": 1280,
+     "net": null
+    }
+   ],
+   "adapt": [],
+   "content_p50": 15.1,
+   "content_p95": 28.6,
+   "input_p50": 76.6,
+   "input_p95": 98.2,
+   "grades": {
+    "input_replies": "local",
+    "content_p50": "local",
+    "content_p95": "local",
+    "input_p50": "acceptable",
+    "input_p95": "acceptable",
+    "fps": "bad",
+    "late_pct": "bad",
+    "stall_max": "local"
+   },
+   "controller": {
+    "target": 5529600,
+    "ceiling": 5529600,
+    "tier": 0,
+    "fps": 60,
+    "scale": 1.0,
+    "baseRtt": 12.332,
+    "inFlight": 0,
+    "slack": 74.12,
+    "adapt": true
+   },
+   "events": [],
+   "source_fps": 60.0,
+   "cpu": {
+    "host": "not sampled"
+   },
+   "viewer": "h264 software; ANGLE (Mesa, zink Vulkan 1.4(Turnip Adreno (TM) 750 (MESA_TURNIP)), OpenGL 4.6); raf 72 Hz",
+   "show_s": 1.75,
+   "panel": "valve.steam.desktopgame.2001932457",
+   "src": "test",
+   "route": "network"
+  }
+ ],
+ "proof": "Synthetic x264 PC agent runs on the Frame itself, forwarded via Mac and back. Not Windows/Linux desktop capture or laser input."
+}

desktop/build-controller.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Build the common controller for the Python PC host (a C11 compiler needed)."""
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+root = Path(__file__).resolve().parent
+suffix = '.dll' if sys.platform == 'win32' else '.dylib' if sys.platform == 'darwin' else '.so'
+out = root / ('controller' + suffix)
+if sys.platform == 'win32' and os.environ.get('CC', 'cl') == 'cl':
+    cmd = ['cl', '/nologo', '/O2', '/LD', '/std:c11', str(root / 'controller.c'), '/link', '/OUT:' + str(out)]
+else:
+    cmd = [os.environ.get('CC', 'cc'), '-O2', '-std=c11', '-shared', '-fPIC', str(root / 'controller.c'), '-o', str(out)]
+subprocess.run(cmd, cwd=root, check=True)
+print(out)

desktop/build.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Build our native PC adapter and bundle its ordinary shared libraries.
+
+Run on the target architecture after installing GStreamer development packages.
+No GStreamer executable or desktop streaming application is shipped or invoked.
+Linux libc, display/GPU drivers and the portal service remain platform pieces.
+
+x264 is GPL, so the bundle the Windows installer ships leaves it out: Windows
+encodes with Media Foundation. --with-x264 adds it for CI's headless protocol
+tests, which have no GPU or desktop to encode with.
+"""
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+
+ROOT = Path(__file__).resolve().parent
+
+
+def output(*args):
+    return subprocess.check_output(args, text=True).strip()
+
+
+def build(destination, with_x264=False):
+    win = sys.platform == 'win32'
+    destination.mkdir(parents=True, exist_ok=True)
+    modules = ['gstreamer-1.0', 'gstreamer-app-1.0', 'gstreamer-video-1.0']
+    if not win:
+        modules += ['gio-unix-2.0']
+    import shlex
+    flags = shlex.split(output('pkg-config', '--cflags', '--libs', *modules))
+    lib = destination / ('pc-host.dll' if win else 'pc-host.so')
+    cmd = [os.environ.get('CC', 'gcc' if win else 'cc'), '-std=c11', '-O2', '-shared', '-Wall', '-Wextra']
+    if not win:
+        cmd += ['-fPIC', '-Wl,-rpath,$ORIGIN/lib']
+    subprocess.run(cmd + [str(ROOT / f) for f in ('controller.c', 'capture.c', 'portal.c')] + flags + ['-o', str(lib)], check=True)
+    prefix = Path(output('pkg-config', '--variable=prefix', 'gstreamer-1.0'))
+    plugin_dir = Path(output('pkg-config', '--variable=pluginsdir', 'gstreamer-1.0'))
+    plugins_out, libs_out = destination / 'lib' / 'gstreamer-1.0', destination / ('bin' if win else 'lib')
+    plugins_out.mkdir(parents=True, exist_ok=True)
+    libs_out.mkdir(parents=True, exist_ok=True)
+    names = ['coreelements', 'videotestsrc', 'videoconvertscale', 'app', 'jpeg', 'videoparsersbad']
+    if with_x264:
+        names.append('x264')
+    names += ['d3d11', 'mediafoundation'] if win else ['pipewire', 'va']
+    pending = [lib]
+    for name in names:
+        matches = list(plugin_dir.glob('*gst' + name + ('.dll' if win else '.so')))
+        if not matches:
+            raise SystemExit('Missing GStreamer library: ' + name)
+        for source in matches:
+            target = plugins_out / source.name
+            shutil.copy2(source, target)
+            pending.append(source)
+    if not win:
+        # PipeWire dynamically loads support and protocol modules. ldd cannot
+        # discover those; bundle them with a private client-only config instead
+        # of accidentally loading a different distro's client modules/config.
+        libdir = plugin_dir.parent
+        for relative in ('pipewire-0.3/libpipewire-module-protocol-native.so',
+                         'pipewire-0.3/libpipewire-module-client-node.so',
+                         'pipewire-0.3/libpipewire-module-adapter.so',
+                         'spa-0.2/support/libspa-support.so',
+                         'spa-0.2/support/libspa-dbus.so',
+                         'spa-0.2/videoconvert/libspa-videoconvert.so'):
+            source = libdir / relative
+            if not source.is_file():
+                raise SystemExit('Missing PipeWire runtime library: ' + str(source))
+            target = destination / 'lib' / relative
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(source, target)
+            pending.append(source)
+        config = destination / 'share' / 'pipewire'
+        config.mkdir(parents=True, exist_ok=True)
+        (config / 'client.conf').write_text(
+            'context.spa-libs = { support.* = support/libspa-support video.* = videoconvert/libspa-videoconvert }\n'
+            'context.modules = [\n'
+            '  { name = libpipewire-module-protocol-native }\n'
+            '  { name = libpipewire-module-client-node }\n'
+            '  { name = libpipewire-module-adapter }\n'
+            ']\n')
+    copied = set()
+    while pending:
+        binary = pending.pop()
+        if win:
+            imported = re.findall(r'DLL Name:\s*(\S+)', output('objdump', '-p', str(binary)))
+            dependencies = [prefix / 'bin' / name for name in imported]
+        else:
+            dependencies = [Path(p) for p in re.findall(r'=>\s+(/\S+)', output('ldd', str(binary)))]
+        for dep in dependencies:
+            if not dep.is_file() or dep.name in copied:
+                continue
+            if not win and re.match(r'lib(c|m|dl|rt|pthread|resolv)\.so', dep.name):
+                continue
+            shutil.copy2(dep, libs_out / dep.name)
+            copied.add(dep.name)
+            pending.append(dep)
+    # License texts and package provenance accompany the dynamically linked
+    # libraries. Distribution builders keep the upstream package/source URLs.
+    licenses = destination / 'licenses'
+    licenses.mkdir(exist_ok=True)
+    if win:
+        source = prefix / 'share' / 'licenses'
+        if source.exists():
+            shutil.copytree(source, licenses, dirs_exist_ok=True)
+        packages = output('pacman', '-Q') if shutil.which('pacman') else 'See MSYS2 build log'
+    else:
+        packages = output('dpkg-query', '-W', '-f=${Package} ${Version}\n') if shutil.which('dpkg-query') else ''
+        # Debian copyright files contain licenses and source homepage details.
+        for path in Path('/usr/share/doc').glob('*/copyright'):
+            shutil.copy2(path, licenses / (path.parent.name + '.copyright'))
+    (destination / 'libraries.json').write_text(json.dumps(dict(gstreamer=output('pkg-config', '--modversion', 'gstreamer-1.0'),
+        plugins=names, libraries=sorted(copied), packages=packages), indent=2))
+    print(lib)
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--out', type=Path, default=ROOT / 'bundle')
+    parser.add_argument('--with-x264', action='store_true', help='add the GPL x264 encoder (CI tests only, never shipped)')
+    args = parser.parse_args()
+    build(args.out.resolve(), args.with_x264)

desktop/capture.c

@@ -0,0 +1,134 @@
+/* Frame Control's capture/encode adapter. GStreamer is a bundled library;
+ * capture uses WGC on Windows and the consented PipeWire fd on Linux. */
+#include "controller.h"
+#include <gst/gst.h>
+#include <gst/app/gstappsink.h>
+#include <gst/video/video-event.h>
+#include <string.h>
+
+typedef int (*Gate)(int stage, int64_t pts, int64_t capture, int64_t arrived);
+typedef struct {
+    GstElement *pipeline, *encoder, *sink, *raw_queue;
+    Gate gate;
+    GstSample *sample;
+    GstMapInfo map;
+    int mapped;
+    char error[512];
+} Capture;
+typedef struct { const unsigned char *data; int size, key, width, height; int64_t pts; } Encoded;
+FC_API int64_t fc_now(void) {return g_get_monotonic_time();}
+FC_API void fc_gst_init(void) {gst_init(NULL,NULL);}
+FC_API int fc_has_element(const char *name) {
+    GstElementFactory *f=gst_element_factory_find(name);
+    if(!f)return 0;gst_object_unref(f);return 1;
+}
+FC_API int fc_has_property(const char *element, const char *property) {
+    /* Probe the same initialized GStreamer instance that capture uses. The
+     * bundled MSYS2 plugin can omit optional WGC properties entirely. */
+    GstElement *source=gst_element_factory_make(element,NULL);
+    if(!source)return 0;
+    int found=g_object_class_find_property(G_OBJECT_GET_CLASS(source),property)!=NULL;
+    gst_object_unref(source);
+    return found;
+}
+static GstPadProbeReturn probe(GstPad *pad,GstPadProbeInfo *info,gpointer data) {
+    Capture *c=data; GstBuffer *b=GST_PAD_PROBE_INFO_BUFFER(info);
+    if(!b)return GST_PAD_PROBE_OK;
+    int64_t now=fc_now(), cap=now;
+    GstClock *clock=gst_element_get_clock(c->pipeline);
+    if(clock && GST_BUFFER_PTS_IS_VALID(b)) {
+        GstClockTime current=gst_clock_get_time(clock),origin=gst_element_get_base_time(c->pipeline);
+        if(current>=origin && current-origin>=GST_BUFFER_PTS(b))
+            cap-= (int64_t)((current-origin-GST_BUFFER_PTS(b))/1000);
+    }
+    if(clock)gst_object_unref(clock);
+    int stage=GPOINTER_TO_INT(g_object_get_data(G_OBJECT(pad),"stage"));
+    if(stage==1) return c->gate(stage,(int64_t)GST_BUFFER_PTS(b),cap,now)>0 ? GST_PAD_PROBE_OK : GST_PAD_PROBE_DROP;
+    int phase=0;
+    for(;;) {
+        /* While congested, prefer a newer raw picture queued upstream. If
+         * nothing changed, retain this last picture until the gate opens;
+         * an idle window must not stay stale after a dropped final update. */
+        guint queued=0;
+        if(phase && c->raw_queue)g_object_get(c->raw_queue,"current-level-buffers",&queued,NULL);
+        if(queued)return GST_PAD_PROBE_DROP;
+        int decision=c->gate(phase,(int64_t)GST_BUFFER_PTS(b),cap,now);
+        if(decision)return decision>0 ? GST_PAD_PROBE_OK : GST_PAD_PROBE_DROP;
+        phase=2;g_usleep(2000);
+    }
+}
+FC_API Capture *fc_capture_open(const char *pipeline,Gate gate,char *error,int capacity) {
+    GError *e=NULL;Capture *c=g_new0(Capture,1);c->gate=gate;
+    c->pipeline=gst_parse_launch(pipeline,&e);
+    if(e || !c->pipeline) {
+        g_strlcpy(error,e?e->message:"No pipeline",capacity);
+        if(e)g_error_free(e);if(c->pipeline)gst_object_unref(c->pipeline);g_free(c);return NULL;
+    }
+    c->encoder=gst_bin_get_by_name(GST_BIN(c->pipeline),"enc");
+    c->sink=gst_bin_get_by_name(GST_BIN(c->pipeline),"out");
+    GstElement *raw=gst_bin_get_by_name(GST_BIN(c->pipeline),"gate");
+    if(!c->encoder || !c->sink || !raw) {
+        g_strlcpy(error,"Pipeline is missing enc, out or gate",capacity);
+        if(raw)gst_object_unref(raw);if(c->encoder)gst_object_unref(c->encoder);
+        if(c->sink)gst_object_unref(c->sink);gst_object_unref(c->pipeline);g_free(c);return NULL;
+    }
+    c->raw_queue=gst_bin_get_by_name(GST_BIN(c->pipeline),"raw_queue");
+    GstPad *p=gst_element_get_static_pad(raw,"src");
+    g_object_set_data(G_OBJECT(p),"stage",GINT_TO_POINTER(0));
+    gst_pad_add_probe(p,GST_PAD_PROBE_TYPE_BUFFER,probe,c,NULL);gst_object_unref(p);gst_object_unref(raw);
+    p=gst_element_get_static_pad(c->encoder,"sink");
+    g_object_set_data(G_OBJECT(p),"stage",GINT_TO_POINTER(1));
+    gst_pad_add_probe(p,GST_PAD_PROBE_TYPE_BUFFER,probe,c,NULL);gst_object_unref(p);
+    gst_element_set_state(c->pipeline,GST_STATE_PLAYING);
+    return c;
+}
+FC_API int fc_capture_pull(Capture *c,Encoded *out) {
+    if(c->mapped) {gst_buffer_unmap(gst_sample_get_buffer(c->sample),&c->map);c->mapped=0;}
+    if(c->sample){gst_sample_unref(c->sample);c->sample=NULL;}
+    GstBus *bus=gst_element_get_bus(c->pipeline);
+    GstMessage *m=gst_bus_pop_filtered(bus,GST_MESSAGE_ERROR);gst_object_unref(bus);
+    if(m) {
+        if(GST_MESSAGE_TYPE(m)==GST_MESSAGE_ERROR) {
+            GError *e=NULL;char *debug=NULL;gst_message_parse_error(m,&e,&debug);
+            g_strlcpy(c->error,e->message,sizeof(c->error));g_error_free(e);g_free(debug);
+        } else g_strlcpy(c->error,"The capture source closed",sizeof(c->error));
+        gst_message_unref(m);return -1;
+    }
+    c->sample=gst_app_sink_try_pull_sample(GST_APP_SINK(c->sink),100*GST_MSECOND);
+    if(!c->sample) {
+        if(gst_app_sink_is_eos(GST_APP_SINK(c->sink))) {
+            g_strlcpy(c->error,"The capture source closed",sizeof(c->error));return -1;
+        }
+        return 0;
+    }
+    GstBuffer *b=gst_sample_get_buffer(c->sample);
+    if(!gst_buffer_map(b,&c->map,GST_MAP_READ))return 0;
+    c->mapped=1;out->data=c->map.data;out->size=(int)c->map.size;
+    out->key=!GST_BUFFER_FLAG_IS_SET(b,GST_BUFFER_FLAG_DELTA_UNIT);out->pts=(int64_t)GST_BUFFER_PTS(b);
+    const GstStructure *s=gst_caps_get_structure(gst_sample_get_caps(c->sample),0);
+    gst_structure_get_int(s,"width",&out->width);gst_structure_get_int(s,"height",&out->height);return 1;
+}
+FC_API const char *fc_capture_error(Capture *c) {return c->error;}
+FC_API void fc_capture_bitrate(Capture *c,int bps) {
+    g_object_set(c->encoder,"bitrate",(guint)MAX(1,bps/1000),NULL);
+}
+FC_API void fc_capture_test(Capture *c,uint32_t input) {
+    GstElement *source=gst_bin_get_by_name(GST_BIN(c->pipeline),"source");
+    if(source) {
+        /* Each benchmark click visibly changes the ball, before injection is
+         * timestamped. This is a response, not merely a protocol input echo. */
+        guint color=0xff000000u | ((input*2654435761u)&0x00ffffffu);
+        g_object_set(source,"foreground-color",color,NULL);gst_object_unref(source);
+    }
+}
+FC_API void fc_capture_key(Capture *c) {
+    GstPad *p=gst_element_get_static_pad(c->encoder,"src");
+    gst_pad_send_event(p,gst_video_event_new_upstream_force_key_unit(GST_CLOCK_TIME_NONE,TRUE,0));gst_object_unref(p);
+}
+FC_API void fc_capture_close(Capture *c) {
+    gst_element_set_state(c->pipeline,GST_STATE_NULL);
+    if(c->mapped)gst_buffer_unmap(gst_sample_get_buffer(c->sample),&c->map);
+    if(c->sample)gst_sample_unref(c->sample);
+    if(c->raw_queue)gst_object_unref(c->raw_queue);
+    gst_object_unref(c->sink);gst_object_unref(c->encoder);gst_object_unref(c->pipeline);g_free(c);
+}

desktop/controller.c

@@ -0,0 +1,130 @@
+/* A C port of the Mac agent's RateController (mac/frame-mac-view/Sources/
+ * Controller.swift) for the Windows host. Same gate, demand protection, bitrate
+ * recovery and tier hysteresis; bounded sample buffers. The Mac agent keeps its
+ * Swift original, so a change to either must be made to both:
+ * tests/test_pc_controller.py checks this one against the Swift trace. */
+#include "controller.h"
+#include <stdlib.h>
+#include <string.h>
+#define CAP 1024
+#define MIN(a,b) ((a)<(b)?(a):(b))
+#define MAX(a,b) ((a)>(b)?(a):(b))
+typedef struct { int64_t t, v; uint32_t seq; } Sample;
+typedef struct { Sample a[CAP]; int n; } Samples;
+struct FCController {
+    int max_fps, enabled, ceiling, target, tier, frame_bytes, held, signal, saw_ack;
+    int64_t decrease, increase, below, above, slack;
+    Samples flight, rtts, acked, sent, captures;
+};
+static const int fps[] = {60,45,30,30,30}, scale[] = {100,100,100,75,50};
+static const double floors[] = {.45,.28,.16,.08,0};
+static void remove_first(Samples *s, int n) {
+    s->n -= n; memmove(s->a, s->a+n, (size_t)s->n*sizeof(Sample));
+}
+static void add(Samples *s, Sample v, int cap) {
+    if (s->n >= cap) remove_first(s, 1);
+    s->a[s->n++] = v;
+}
+static void expire(Samples *s, int64_t oldest) {
+    int n=0; while(n<s->n && s->a[n].t<oldest) n++;
+    remove_first(s,n);
+}
+static int64_t base(FCController *c) {
+    int64_t v=0;
+    for(int i=0;i<c->rtts.n;i++) if(!i || c->rtts.a[i].v<v) v=c->rtts.a[i].v;
+    return v;
+}
+static int compare(const void *a, const void *b) {
+    int64_t x=*(const int64_t*)a, y=*(const int64_t*)b;
+    return (x>y)-(x<y);
+}
+static int64_t quantile(Samples *s,int64_t since,int numerator,int denominator) {
+    int64_t a[CAP]; int n=0;
+    for(int i=0;i<s->n;i++) if(s->a[i].t>since) a[n++]=s->a[i].v;
+    if(!n) return 0;
+    qsort(a,(size_t)n,sizeof(int64_t),compare);
+    return a[n*numerator/denominator];
+}
+static int rate(Samples *s) {
+    int64_t total=0; for(int i=0;i<s->n;i++) total+=s->a[i].v;
+    return (int)MIN(total*16,2147483647);
+}
+FCController *fc_new(int max_fps,int enabled) {
+    FCController *c=calloc(1,sizeof(*c));
+    if(c) {c->max_fps=MAX(1,max_fps);c->enabled=enabled;c->slack=40000;}
+    return c;
+}
+void fc_free(FCController *c) {free(c);}
+void fc_ceiling(FCController *c,int bps) {
+    if(!c->target || c->target>bps) c->target=bps;
+    c->ceiling=bps;
+}
+int fc_gate(FCController *c,int64_t now,int counts) {
+    if(!c->enabled || !c->saw_ack) return 1;
+    expire(&c->flight,now-2000000);
+    if(!c->flight.n) return 1;
+    int64_t interval=1000000/MIN(c->max_fps,fps[c->tier]);
+    int window=MAX(3,(int)((base(c)+c->slack)/interval)+1);
+    if(c->flight.n<window && now-c->flight.a[0].t<=base(c)+c->slack) return 1;
+    if(counts) c->held++;
+    return 0;
+}
+void fc_capture(FCController *c,int64_t now) {add(&c->captures,(Sample){now,0,0},256);}
+void fc_sent(FCController *c,uint32_t seq,int bytes,int64_t now) {
+    Sample s={now,bytes,seq};add(&c->flight,s,512);add(&c->sent,s,CAP);
+}
+int fc_ack(FCController *c,uint32_t seq,int64_t now) {
+    c->saw_ack=1;
+    for(int i=0;i<c->flight.n;i++) if(c->flight.a[i].seq==seq) {
+        Sample s=c->flight.a[i];remove_first(&c->flight,i+1);
+        add(&c->rtts,(Sample){now,now-s.t,0},CAP);
+        add(&c->acked,(Sample){now,s.v,0},CAP);return 1;
+    }
+    return 0;
+}
+int fc_update(FCController *c,int64_t now) {
+    expire(&c->rtts,now-10000000);expire(&c->acked,now-500000);
+    expire(&c->sent,now-500000);expire(&c->flight,now-2000000);
+    expire(&c->captures,now-1000000);
+    if(!c->enabled || c->ceiling<=0) return 0;
+    int64_t baseline=base(c), spread=quantile(&c->rtts,now-2000000,9,10);
+    int64_t jitter=spread ? spread-baseline : 0;
+    c->slack=1000000/MIN(c->max_fps,fps[c->tier])+MIN(MAX(jitter*3/2,25000),80000);
+    int64_t recent=quantile(&c->rtts,now-300000,1,2);
+    int64_t queue=recent ? recent-baseline : 0;
+    int64_t age=c->flight.n ? now-c->flight.a[0].t : 0;
+    int delivered=rate(&c->acked),sending=rate(&c->sent);
+    if(c->sent.n) c->frame_bytes=sending/16/c->sent.n;
+    int demand=(int)MIN((int64_t)MIN(c->captures.n,MIN(c->max_fps,fps[c->tier]))*c->frame_bytes*8,2147483647);
+    int signal=(sending>=c->target/2 && queue>40000)||c->held>=3||age>baseline+100000;
+    int congested=signal && c->signal;c->signal=signal;c->held=0;
+    if(congested && now-c->decrease>300000) {
+        int next=MAX(300000,MIN((int64_t)c->target*4/5,MAX((int64_t)delivered*9/10,c->target/2)));
+        if(demand>0 && (int64_t)demand*2<=(int64_t)c->target*5/4) next=MAX(next,MIN(c->target,(int64_t)demand*2));
+        c->target=next;c->decrease=now;
+    } else if(!congested && now-c->decrease>1000000 && now-c->increase>250000 && c->target<c->ceiling &&
+              (sending>(int64_t)c->target*6/10 || now-c->decrease>3000000)) {
+        c->target=MIN(c->ceiling,(int64_t)(c->target*1.1)+50000);c->increase=now;
+    }
+    double share=(double)c->target/MAX(c->ceiling,1);
+    if(c->tier<4 && share<floors[c->tier] && sending>=(int64_t)c->target*7/10) {
+        if(!c->below)c->below=now;
+        if(now-c->below>500000) {
+            for(c->tier=0;c->tier<4 && share<floors[c->tier];c->tier++) {}
+            c->below=0;
+        }
+    } else c->below=0;
+    if(c->tier>0 && share>floors[c->tier-1]*1.25) {
+        if(!c->above)c->above=now;
+        if(now-c->above>2000000) {c->tier--;c->above=0;}
+    } else c->above=0;
+    return c->target;
+}
+int64_t fc_value(FCController *c,int field) {
+    switch(field) {
+    case 0:return c->target;case 1:return c->ceiling;case 2:return c->tier;
+    case 3:return MIN(c->max_fps,fps[c->tier]);case 4:return scale[c->tier];
+    case 5:return base(c);case 6:return c->flight.n;case 7:return c->slack;
+    default:return 0;
+    }
+}

desktop/controller.h

@@ -0,0 +1,29 @@
+/* Shared latency controller. Times are monotonic host microseconds.
+ * Callers serialize access. Capture is gated BEFORE encoding: dropping an
+ * encoded inter frame would break the decoder's reference chain. */
+#ifndef FRAME_CONTROLLER_H
+#define FRAME_CONTROLLER_H
+#include <stdint.h>
+#ifdef _WIN32
+#define FC_API __declspec(dllexport)
+#else
+#define FC_API
+#endif
+#ifdef __cplusplus
+extern "C" {
+#endif
+typedef struct FCController FCController;
+FC_API FCController *fc_new(int fps, int enabled);
+FC_API void fc_free(FCController *c);
+FC_API void fc_ceiling(FCController *c, int bps);
+FC_API int fc_gate(FCController *c, int64_t now, int counts);
+FC_API void fc_capture(FCController *c, int64_t now);
+FC_API void fc_sent(FCController *c, uint32_t seq, int bytes, int64_t now);
+FC_API int fc_ack(FCController *c, uint32_t seq, int64_t now);
+FC_API int fc_update(FCController *c, int64_t now);
+/* target, ceiling, tier, fps, scale percent, baseline us, in flight, slack us */
+FC_API int64_t fc_value(FCController *c, int field);
+#ifdef __cplusplus
+}
+#endif
+#endif

desktop/portal.c

@@ -0,0 +1,147 @@
+/* xdg-desktop-portal RemoteDesktop + ScreenCast, one consented session per
+ * panel. PipeWire receives the portal fd, never the unrestricted daemon fd.
+ * Input uses only the devices granted in Start's response. */
+#ifndef _WIN32
+#include "controller.h"
+#include <gio/gio.h>
+#include <gio/gunixfdlist.h>
+#include <unistd.h>
+#include <string.h>
+#define BUS "org.freedesktop.portal.Desktop"
+#define PATH "/org/freedesktop/portal/desktop"
+#define RD "org.freedesktop.portal.RemoteDesktop"
+#define SC "org.freedesktop.portal.ScreenCast"
+typedef struct {
+    GDBusConnection *bus;
+    GMainContext *context;
+    char *session;
+    int fd;
+    unsigned node, devices;
+    int width,height;
+} Portal;
+typedef struct {GVariant *result;int done;unsigned code;} Response;
+static void response(GDBusConnection *c,const char *sender,const char *path,const char *iface,
+                     const char *signal,GVariant *params,gpointer data) {
+    (void)c;(void)sender;(void)path;(void)iface;(void)signal;
+    Response *r=data;g_variant_get(params,"(u@a{sv})",&r->code,&r->result);r->done=1;
+}
+static void option(GVariantBuilder *b,const char *key,GVariant *v) {g_variant_builder_add(b,"{sv}",key,v);}
+static GVariant *request(Portal *p,const char *iface,const char *method,GVariant *args,
+                         const char *token,char *error,int capacity) {
+    char *sender=g_strdup(g_dbus_connection_get_unique_name(p->bus)+1);
+    for(char *c=sender;*c;c++)if(*c=='.')*c='_';
+    char *path=g_strdup_printf(PATH "/request/%s/%s",sender,token);g_free(sender);
+    Response r={0};GError *e=NULL;
+    guint sub=g_dbus_connection_signal_subscribe(p->bus,BUS,"org.freedesktop.portal.Request","Response",
+                                                 path,NULL,G_DBUS_SIGNAL_FLAGS_NONE,response,&r,NULL);
+    GVariant *reply=g_dbus_connection_call_sync(p->bus,BUS,PATH,iface,method,args,G_VARIANT_TYPE("(o)"),
+                                               G_DBUS_CALL_FLAGS_NONE,10000,NULL,&e);
+    if(reply)g_variant_unref(reply);
+    int64_t deadline=g_get_monotonic_time()+120000000;
+    while(!e && !r.done && g_get_monotonic_time()<deadline) {
+        while(g_main_context_iteration(p->context,FALSE)) {}
+        g_usleep(10000);
+    }
+    if(!r.done) {
+        GVariant *closed=g_dbus_connection_call_sync(p->bus,BUS,path,"org.freedesktop.portal.Request","Close",
+                                NULL,NULL,G_DBUS_CALL_FLAGS_NONE,2000,NULL,NULL);
+        if(closed)g_variant_unref(closed);
+    }
+    g_dbus_connection_signal_unsubscribe(p->bus,sub);g_free(path);
+    if(e || !r.done || r.code) {
+        g_strlcpy(error,e?e->message:!r.done?"Screen sharing request timed out":"Screen sharing was cancelled or refused",capacity);
+        if(e)g_error_free(e);if(r.result)g_variant_unref(r.result);return NULL;
+    }
+    return r.result;
+}
+FC_API void fc_portal_close(Portal *p) {
+    if(!p)return;
+    if(p->session && p->bus) {
+        GVariant *r=g_dbus_connection_call_sync(p->bus,BUS,p->session,"org.freedesktop.portal.Session","Close",
+                                                NULL,NULL,G_DBUS_CALL_FLAGS_NONE,2000,NULL,NULL);
+        if(r)g_variant_unref(r);
+    }
+    if(p->fd>=0){close(p->fd);p->fd=-1;}
+    g_free(p->session);if(p->bus)g_object_unref(p->bus);
+    if(p->context)g_main_context_unref(p->context);g_free(p);
+}
+/* Each pipeline gets a fresh restricted PipeWire connection. A dup of a
+ * previously consumed protocol socket is not a new connection.
+ * Ownership: the Portal owns p->fd for its whole life and is its only closer.
+ * pipewiresrc never takes the fd it is given: its core connects with
+ * pw_context_connect_fd(ctx, fcntl(fd, F_DUPFD_CLOEXEC, 3), ...) and that
+ * duplicate is what PipeWire closes on teardown (src/gst/gstpipewirecore.c,
+ * unchanged from 0.3.19 through 1.x). So closing p->fd here is not a double
+ * close; not closing it would leak one socket per pipeline reopen. The
+ * caller closes the previous pipeline before asking for a new fd. */
+FC_API int fc_portal_refresh(Portal *p,char *error,int capacity) {
+    GVariantBuilder b;g_variant_builder_init(&b,G_VARIANT_TYPE_VARDICT);
+    GUnixFDList *fds=NULL;GError *e=NULL;
+    GVariant *r=g_dbus_connection_call_with_unix_fd_list_sync(p->bus,BUS,PATH,SC,"OpenPipeWireRemote",
+         g_variant_new("(oa{sv})",p->session,&b),G_VARIANT_TYPE("(h)"),G_DBUS_CALL_FLAGS_NONE,10000,NULL,&fds,NULL,&e);
+    if(!r){g_strlcpy(error,e->message,capacity);g_error_free(e);return -1;}
+    int handle;g_variant_get(r,"(h)",&handle);g_variant_unref(r);
+    int fd=g_unix_fd_list_get(fds,handle,&e);g_object_unref(fds);
+    if(fd<0){g_strlcpy(error,e->message,capacity);g_error_free(e);return -1;}
+    if(p->fd>=0)close(p->fd);
+    p->fd=fd;return fd;
+}
+FC_API Portal *fc_portal_select(char *error,int capacity) {
+    Portal *p=g_new0(Portal,1);p->fd=-1;p->context=g_main_context_new();
+    g_main_context_push_thread_default(p->context);
+    GError *e=NULL;GVariant *r=NULL;
+    p->bus=g_bus_get_sync(G_BUS_TYPE_SESSION,NULL,&e);
+    if(!p->bus) {g_strlcpy(error,e->message,capacity);g_error_free(e);goto fail;}
+    GVariantBuilder b;char token[64],session[64];
+    g_snprintf(session,sizeof(session),"fc_%u",g_random_int());
+    g_snprintf(token,sizeof(token),"fc_%u",g_random_int());
+    g_variant_builder_init(&b,G_VARIANT_TYPE_VARDICT);
+    option(&b,"handle_token",g_variant_new_string(token));option(&b,"session_handle_token",g_variant_new_string(session));
+    r=request(p,RD,"CreateSession",g_variant_new("(a{sv})",&b),token,error,capacity);if(!r)goto fail;
+    g_variant_lookup(r,"session_handle","s",&p->session);g_variant_unref(r);r=NULL;
+    if(!p->session){g_strlcpy(error,"Portal did not return a session",capacity);goto fail;}
+    g_snprintf(token,sizeof(token),"fc_%u",g_random_int());g_variant_builder_init(&b,G_VARIANT_TYPE_VARDICT);
+    option(&b,"handle_token",g_variant_new_string(token));option(&b,"types",g_variant_new_uint32(3));
+    r=request(p,RD,"SelectDevices",g_variant_new("(oa{sv})",p->session,&b),token,error,capacity);if(!r)goto fail;g_variant_unref(r);
+    g_snprintf(token,sizeof(token),"fc_%u",g_random_int());g_variant_builder_init(&b,G_VARIANT_TYPE_VARDICT);
+    option(&b,"handle_token",g_variant_new_string(token));option(&b,"types",g_variant_new_uint32(3));
+    option(&b,"multiple",g_variant_new_boolean(FALSE));option(&b,"cursor_mode",g_variant_new_uint32(2));
+    r=request(p,SC,"SelectSources",g_variant_new("(oa{sv})",p->session,&b),token,error,capacity);if(!r)goto fail;g_variant_unref(r);
+    g_snprintf(token,sizeof(token),"fc_%u",g_random_int());g_variant_builder_init(&b,G_VARIANT_TYPE_VARDICT);
+    option(&b,"handle_token",g_variant_new_string(token));
+    r=request(p,RD,"Start",g_variant_new("(osa{sv})",p->session,"",&b),token,error,capacity);if(!r)goto fail;
+    g_variant_lookup(r,"devices","u",&p->devices);
+    GVariant *streams=g_variant_lookup_value(r,"streams",G_VARIANT_TYPE("a(ua{sv})"));
+    if(streams && g_variant_n_children(streams)>0) {
+        GVariant *entry=g_variant_get_child_value(streams,0),*props=NULL;
+        g_variant_get(entry,"(u@a{sv})",&p->node,&props);
+        g_variant_lookup(props,"size","(ii)",&p->width,&p->height);
+        g_variant_unref(props);g_variant_unref(entry);
+    }
+    if(streams)g_variant_unref(streams);g_variant_unref(r);r=NULL;
+    if(!p->node || p->width<=0 || p->height<=0) {g_strlcpy(error,"Portal returned no stream size",capacity);goto fail;}
+    if(fc_portal_refresh(p,error,capacity)<0)goto fail;
+    g_main_context_pop_thread_default(p->context);return p;
+fail:
+    g_main_context_pop_thread_default(p->context);fc_portal_close(p);return NULL;
+}
+FC_API int fc_portal_value(Portal *p,int field) {
+    switch(field){case 0:return p->fd;case 1:return (int)p->node;case 2:return p->width;
+                 case 3:return p->height;case 4:return (int)p->devices;default:return 0;}
+}
+FC_API int fc_portal_input(Portal *p,int type,double x,double y,int code,int down) {
+    const char *method=NULL;GVariant *args=NULL;GVariantBuilder b;g_variant_builder_init(&b,G_VARIANT_TYPE_VARDICT);
+    if(type==0 && (p->devices&2)) {
+        method="NotifyPointerMotionAbsolute";args=g_variant_new("(oa{sv}udd)",p->session,&b,p->node,x,y);
+    } else if(type==1 && (p->devices&2)) {
+        method="NotifyPointerButton";args=g_variant_new("(oa{sv}iu)",p->session,&b,code,(guint)down);
+    } else if(type==2 && (p->devices&2)) {
+        method="NotifyPointerAxis";args=g_variant_new("(oa{sv}dd)",p->session,&b,x,y);
+    } else if(type==3 && (p->devices&1)) {
+        method="NotifyKeyboardKeysym";args=g_variant_new("(oa{sv}iu)",p->session,&b,code,(guint)down);
+    } else return 0;
+    GError *e=NULL;GVariant *r=g_dbus_connection_call_sync(p->bus,BUS,PATH,RD,method,args,NULL,
+                                                       G_DBUS_CALL_FLAGS_NONE,2000,NULL,&e);
+    if(e)g_error_free(e);if(r)g_variant_unref(r);return r!=NULL;
+}
+#endif

docs/backup-and-recovery.md

@@ -14,6 +14,13 @@ reported Game Mode, so **Return to Game Mode** changed nothing. Not tested on a
 headset: a restore after a real factory reset, a restore that replaces files,
 Android data restore, and the switch out of a real Desktop Mode session. Unit
 tests and the fake Frame cover those (see [Verification](#verification)).
+On 2026-10-24 a read-only session check on the same build again reported Game
+Mode (`gamescope=true`, `plasma=false`, `nested_desktop=false`) and the
+`steamos-session-select` command was present. Opening the nested desktop for a
+clipboard test did not enter full Desktop Mode. A full session switch was not
+attempted because it restarts the headset session and a reliable return path
+was not established; the **Return to Game Mode** branch for a real full
+Desktop Mode session remains unverified.
 
 ## Back up
 

docs/battery-health.md

@@ -0,0 +1,59 @@
+# Battery and health monitoring
+
+Open **Control Center → Battery & thermal health**, or expand **System
+information**, to read the Frame's charge, charging state, signed battery
+power, battery temperature and driver-reported health. Optional readings show
+charge cycles, full charge capacity, design capacity and full / design capacity.
+The existing battery chip also shows charging state and temperature.
+
+These are read-only readings from the Linux host's `/sys/class/power_supply`,
+not Android's container battery view. The probe prefers the documented Frame
+fuel gauge, `max1720x_bat_7-36`, over other battery nodes, excludes peripheral
+(`scope=Device`) and absent batteries, and otherwise uses a deterministic
+battery fallback. The UI shows the selected source path.
+
+| Reading | Linux attribute | Interpretation |
+|---|---|---|
+| Charge | `capacity` | Integer 0–100 percent; zero is a real reading |
+| Charging state | `status` | Charging, Full, Discharging or Not charging; missing/unknown states stay unavailable |
+| Battery power | `voltage_now × current_now` | Microvolts and microamps converted to signed watts; positive means charging on the Frame |
+| Temperature | `temp` | Tenths of a degree Celsius, including valid negative readings |
+| Battery health | `health` | Driver status such as Good or Overheat; not a wear percentage |
+| Charge cycles | `cycle_count` | Driver-reported count, including zero |
+| Full/design capacity | `charge_full`, `charge_full_design` | Microamp-hours converted to mAh |
+| Full / design capacity | Ratio of those two capacities | Fuel-gauge estimate; not a diagnosis or a guaranteed runtime |
+| Time estimate | `time_to_full_now`, `time_to_empty_now` | Seconds; displayed only for the corresponding charging/discharging state |
+
+Unavailable means the field is absent, unreadable or invalid. One missing
+sensor does not hide the others. Zero design capacity cannot produce a ratio. Time estimates outside 1 second
+to 7 days and battery temperatures outside −273.15 to 200 °C are rejected
+as invalid readings; these bounds are not thermal warning thresholds.
+The ratio may exceed 100% because full capacity is a gauge estimate, so the app
+does not clamp it or invent a wear warning. The app does not estimate health
+from charge percentage or assign temperature thresholds. Existing thermal
+alerts use the kernel's own hot/critical trip points.
+
+A connected charger does not necessarily mean charging: the Frame can still
+drain under load or sit idle near full charge. A 100% capacity reading alone
+does not prove the driver reports Full. Missing status is explicitly unknown;
+near-zero measured battery power with a charger is shown as not charging.
+Failed, stale or disconnected status samples clear Control Center readings.
+
+**No charge controls are provided.** Frame's SteamOS charge-limit backend is
+unsupported; see [charge-limit research](charge-limit.md). Monitoring never
+writes to power supplies, pauses charging, changes current or sets a limit.
+
+## Verification
+
+`tests/test_battery.py` uses temporary sysfs-like files for conversion,
+malformed/missing values, permission failures, source selection and partial
+sensor support. `tests/control_center.cjs` exercises charging states, optional
+metrics and failed/stale/disconnected sample handling. These tests do not
+connect to a headset. On 2026-10-24, the PR's uninstalled parser was also
+piped over SSH to a real Frame running SteamOS 0.5.6 (build
+`20261015.6141207`). Its read-only sysfs result selected
+`max1720x_bat_7-36` and reported 99% charge, Not charging, 24.9 °C,
+Good driver health, 14 cycles, 2,920 mAh full and 2,700 mAh design capacity
+(108.1% fuel-gauge estimate). The Control Center UI was not run against this
+headset; Windows and macOS were not tested. Optional fields are not claimed to
+be available on every firmware build.

docs/changelog.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## Unreleased
+
+- Battery monitoring now selects the Frame fuel gauge predictably, handles
+  missing or invalid readings, and shows optional cycle count, full/design
+  capacity and estimated capacity health in Control Center. Unknown charging
+  status stays explicit. Monitoring is read-only; charge limits remain
+  unsupported on Frame. The read-only parser was checked on a real Frame; the UI was not.

docs/charge-limit.md

@@ -18,6 +18,9 @@ read-only checks below on a Frame running SteamOS 0.5.6 (build 20261015.6141207)
   `charging_enable` and `charging_pause`, both `root`-only (`-rw-r--r--`).
 - `deckard-charger.service` (Deckard Battery Charger service) is enabled and running.
 
+For safe read-only readings in Control Center, see [battery and health
+monitoring](battery-health.md). It does not provide charging controls.
+
 ## How Steam does it on other devices
 
 - Steam's **Settings → Power → Battery Charge Limit** shipped to the Deck in

docs/devices.md

@@ -97,6 +97,12 @@ The app rereads the gateway every 5 seconds and Tailscale's state every
 
 ## The connection, stage by stage
 
+When a connection fails, the header pill keeps its compact offline state and
+retry countdown; its tooltip and connection dialog contain the full reason.
+Devices shows a short reason in the headset row (with the full reason in its
+tooltip) and a wrapping recovery explanation in the selected headset's details.
+**Use this headset** also selects that headset's details.
+
 The connector runs in the server (`frame_link.Link`) and moves through:
 
 1. **Checking this computer's network**: gateway, Wi-Fi, this computer's IP, Tailscale.

docs/evidence/windows-vm-2026-10-24.md

@@ -0,0 +1,151 @@
+# Windows VM and real Frame test, 2026-10-24
+
+The v0.4.10 installer could enumerate windows/screens and encode a synthetic
+Media Foundation stream, but every desktop capture failed at pipeline parsing:
+`no property "capture-api" in element "d3d11screencapturesrc"`.
+MSYS2's GStreamer 1.28.8 package disables WGC. After the fix, the same installed
+bundle captured the actual Windows desktop with Desktop Duplication and sent
+H.264 to a real Frame: 219 sent frame records, 215 decoded and drawn before the
+snapshot. Individual windows are explicitly unavailable with this bundle.
+
+The base was `e9cbb8fd5555f5cfceeba1babadf2d7d35dcd3be` (`v0.4.10`, origin/main,
+including merged #121), in isolated branch `t3/test-windows-vm-headset`.
+
+## Evidence
+
+- [Capture before the fix](windows-vm-2026-10-24/capture-before.json): five
+  synthetic H.264 frames and five JPEG frames; zero desktop/window frames,
+  with the missing-property error for both codecs.
+- [Actual bundled properties](windows-vm-2026-10-24/plugin-properties.json):
+  `monitor-handle` exists; `capture-api`, `window-handle`, `show-border` do not.
+  [MSYS2 package build](https://github.com/msys2/MINGW-packages/blob/master/mingw-w64-gst-plugins-bad/PKGBUILD)
+  sets `-Dd3d11-wgc=disabled`. Upstream
+  [installs those properties conditionally](https://github.com/GStreamer/gstreamer/blob/main/subprojects/gst-plugins-bad/sys/d3d11/gstd3d11screencapturesrc.cpp).
+- [Capture after the fix](windows-vm-2026-10-24/capture-after.json): the real
+  display produces five H.264 and five JPEG frames. Window sources are hidden
+  with an explicit reason, and the display selects `capture_api=dxgi`.
+- [Raw locked headset session](windows-vm-2026-10-24/headset-session.json):
+  Windows helper, Media Foundation encoder, reverse SSH tunnel, production
+  panel launcher and shared viewer. The image below was captured from that
+  viewer's own X window on the Frame, rather than the VM's console.
+- [Windows tests](windows-vm-2026-10-24/windows-tests.txt) and
+  [guest system details](windows-vm-2026-10-24/windows-system.txt).
+
+![Windows VM desktop decoded in the Frame's own viewer](windows-vm-2026-10-24/headset-view.png)
+
+## Host and VM prerequisites
+
+lxso2: Intel Core i7-8700, 12 logical CPUs, VT-x/KVM; Docker 29.1.3 and Compose
+2.40.3. Before starting: 31 GiB RAM, 15 GiB available; 147 GiB free disk.
+Swap was already full. No other VM or service workload was started or stopped.
+Docker listed no Windows VM, and ports 2222/8006/13389 were unused.
+
+The execution sandbox hid KVM and denied Docker/network access. Checks outside
+it found `/dev/kvm`, `/dev/net/tun` and the Docker daemon. Direct user access to
+KVM was denied, but a disposable Docker container with `--device /dev/kvm`
+opened it successfully; no host permissions changed.
+
+Created only `frame-winvm-priority3`, labelled
+`frame-control.task=priority3-windows-test`: 4 vCPUs, 8 GiB guest RAM, 32 GiB
+growable disk, no restart, 150-second stop timeout. SSH 2222 and console 8006
+bind only 127.0.0.1; RDP is unpublished. No GPU passthrough. Image:
+`dockurr/windows@sha256:16fd7c39a3e48bb946d29c59dc6015942e5b900a1fa5d7e5552053bfc48ee2ea`
+(Windows for Docker v6.06, QEMU v11.1.1).
+
+The container downloaded Windows 11 from Microsoft, with no activation changes.
+It took about 16 minutes to reach the first desktop. Guest build 26200.8037,
+Red Hat VirtIO GPU DOD driver 100.103.104.30200. The old WindowsProductName
+registry field still says Windows 10 Pro; the actual desktop/setup is Windows
+11. After installing the app, the 32 GiB disk had about 9.3 GB free.
+
+Official `Frame-Control-Setup-x64.exe` v0.4.10 SHA-256:
+`30165bc5aa39f941cacc697d195dc5c30b01ad0b9ffb472da8a18a5220549202`.
+Its installer exited 0. The VM stream used an intermediate Python/UI-only
+fix with the released DLL bundle and bundled Python 3.12.14. A later CI failure
+showed that probing GStreamer through a separately loaded DLL could see a
+different, uninitialized instance. The final fix probes optional properties
+through the capture DLL itself. Windows CI checks that native change; the VM
+stream was not repeated with the final DLL.
+
+OEM setup added OpenSSH Server, PowerShell and a dedicated public login key;
+password authentication is disabled. Its config needed an explicit
+`AuthorizedKeysFile C:/ProgramData/ssh/administrators_authorized_keys` before
+key login worked. The default informational share was replaced with a private
+writable staging share inside this container. These were test-VM setup steps,
+not app defects. Host setup files and the stopped VM disk are retained under
+`/tmp/frame-winvm-priority3/`; no private keys are committed or printed.
+The Frame test key was generated inside Windows and its private key stayed
+there. Only its public key was temporarily authorized on the Frame. After
+testing, the guest key and scheduled task were removed; `docker stop -t 150`
+shut down the dedicated VM. Inspection confirmed `exited`, restart `no`
+(container exit 143; logs show the ACPI shutdown signal, waiting for Windows,
+and `Shutdown completed!`). The disk is retained
+for reuse; the VM is not running.
+
+## Checks
+
+- Baseline PC-focused suite: 24 tests passed, one native class skipped.
+- After fix: full Linux unittest suite **1260 tests, OK, 15 skipped**, 144.366 s;
+  focused final PC suite **27 tests, OK, one native class skipped**. The C
+  controller's frozen 600-state trace ran on Linux.
+- Actual Windows installer bundle with the intermediate Python/UI fix:
+  **33 tests, OK, four skipped** (no C compiler, Linux PipeWire test, two
+  CI-only x264 tests). Its GObject property probe, host/encoder check and
+  x264-absence check ran. The final native probe is checked in the PR's
+  Windows CI build, not by this VM run.
+- Browser check with the real production HTML/JavaScript and mocked Windows API
+  responses: DXGI whole-screen Show remains available, the limitation appears
+  once, WGC window sources retain Show, off hides controls, and the limitation
+  text is escaped. This used a static asset server, without headset API access.
+- `node --test app/test/*.test.js`: passed, three test files.
+- `node --test site/test/*.test.mjs`: passed, one test file.
+- The first full Linux run inside the sandbox failed (11 failures, 139 errors),
+  including loopback socket `PermissionError`. The successful full runs were
+  outside that socket restriction.
+- An initial guest test archive omitted `apk-catalog`, causing one import
+  error; the complete archive produced the 33-test passing Windows run.
+
+Raw local logs: `/tmp/frame-windows-{pc,app,site}-tests.log`,
+`/tmp/frame-windows-full-tests-unrestricted.log`,
+`/tmp/frame-windows-full-fixed-tests.log`, and
+`/tmp/frame-winvm-priority3/`. The committed artifacts above preserve the
+capture, Windows test and headset evidence independently of those local files.
+
+## Shared Frame session and cleanup
+
+Read-only checks first: SteamOS 0.5.6, BUILD_ID `20261015.6141207`, battery 99%,
+Not charging (another supply reports Full). The lock was free.
+
+Both attempts acquired `/tmp/frame-test.lock` atomically before any key or
+viewer changes, and removed only the lock acquired by this task. The first,
+35-second attempt failed because the test wrapper sent CRLF script input and
+left SSH stdin open. Production already sends script bytes and closes stdin;
+correcting the wrapper resolved both. Its key was removed and lock released.
+
+The successful session held the lock **03:09:36–03:10:05 UTC (29 seconds)**.
+It used a dedicated `pc-view-priority3` profile and port range 47960–47964,
+leaving existing viewers/profiles alone. The app's Windows `PCView` captured
+`display:65537`, 1280×800, Light preset (30 fps ceiling), and opened panel
+`valve.steam.desktopgame.2001396898`. The viewer reported H.264 software decode,
+218 received frames, 215 decoded/drawn before the snapshot (219 sent records).
+
+This mostly idle, roughly ten-second sample reported 19 fps and content delay
+p50/p95 51.6/75.2 ms. These are observations, not a performance-target pass.
+
+Cleanup stopped the helper and tunnel, closed the own viewer, removed its two
+possible profile paths and log, then removed the exact public-key line. The
+`authorized_keys` SHA-256 was identical before/after. A follow-up login from
+Windows with that key failed with exit 255. Separate checks found no task-owned
+viewer processes, the profile absent, and the shared lock released. Battery
+remained 99%; the sampled gamescope focus properties matched before/after.
+No reboot, global settings changes, game launch or Steam/SteamVR stop occurred.
+
+## Limits
+
+This verifies a Windows VM's desktop capture, Media Foundation encoding and
+real Frame viewer decode/rendering. It does not verify physical-PC hardware
+encoding, WGC or individual-window capture, mixed DPI, multiple displays,
+physical laser alignment/clicks, keyboard layouts, resize/minimise, busy-scene
+performance, bitrate/encoder restarts, or worn-headset comfort. No input was
+injected during the real Frame session. The installed app’s Tools navigation was not exercised; its streaming
+controller, tunnel and viewer were exercised directly. No independent review was performed.

docs/evidence/windows-vm-2026-10-24/capture-after.json

@@ -0,0 +1,53 @@
+{
+  "python": "3.12.14 (main, Sep 24 2026, 17:57:31) [MSC v.1944 64 bit (AMD64)]",
+  "resources": "C:\\Users\\frame\\AppData\\Local\\Programs\\Frame Control\\resources",
+  "elements": {
+    "d3d11screencapturesrc": true,
+    "mfh264enc": true,
+    "jpegenc": true,
+    "x264enc": false
+  },
+  "windowCaptureReason": "Individual windows are unavailable in this build. Choose a whole screen instead.",
+  "windows": [],
+  "displays": [
+    {
+      "src": "display:65537",
+      "name": "Display 1",
+      "x": 0,
+      "y": 0,
+      "w": 1280,
+      "h": 800,
+      "capture_api": "dxgi"
+    }
+  ],
+  "runs": [
+    {
+      "source": "test",
+      "codec": "h264",
+      "frames": 5,
+      "pipeline": "videotestsrc name=source is-live=true pattern=ball ! video/x-raw,framerate=30/1 ! queue name=raw_queue leaky=downstream max-size-buffers=1 max-size-bytes=0 max-size-time=0 ! identity name=gate ! videoconvert ! videoscale add-borders=false ! video/x-raw,width=640,height=360,format=NV12 ! mfh264enc name=enc low-latency=true bframes=0 gop-size=60 bitrate=1000 ! h264parse config-interval=-1 ! video/x-h264,stream-format=byte-stream,alignment=au ! appsink name=out sync=false max-buffers=2 drop=false",
+      "last_bytes": 154
+    },
+    {
+      "source": "test",
+      "codec": "jpeg",
+      "frames": 5,
+      "pipeline": "videotestsrc name=source is-live=true pattern=ball ! video/x-raw,framerate=30/1 ! queue name=raw_queue leaky=downstream max-size-buffers=1 max-size-bytes=0 max-size-time=0 ! identity name=gate ! videoconvert ! videoscale add-borders=false ! video/x-raw,width=640,height=360 ! jpegenc name=enc quality=80 ! appsink name=out sync=false max-buffers=2 drop=false",
+      "last_bytes": 7336
+    },
+    {
+      "source": "display:65537",
+      "codec": "h264",
+      "frames": 5,
+      "pipeline": "d3d11screencapturesrc show-cursor=true monitor-handle=65537 ! video/x-raw,framerate=30/1 ! queue name=raw_queue leaky=downstream max-size-buffers=1 max-size-bytes=0 max-size-time=0 ! identity name=gate ! videoconvert ! videoscale add-borders=false ! video/x-raw,width=640,height=360,format=NV12 ! mfh264enc name=enc low-latency=true bframes=0 gop-size=60 bitrate=1000 ! h264parse config-interval=-1 ! video/x-h264,stream-format=byte-stream,alignment=au ! appsink name=out sync=false max-buffers=2 drop=false",
+      "last_bytes": 65
+    },
+    {
+      "source": "display:65537",
+      "codec": "jpeg",
+      "frames": 5,
+      "pipeline": "d3d11screencapturesrc show-cursor=true monitor-handle=65537 ! video/x-raw,framerate=30/1 ! queue name=raw_queue leaky=downstream max-size-buffers=1 max-size-bytes=0 max-size-time=0 ! identity name=gate ! videoconvert ! videoscale add-borders=false ! video/x-raw,width=640,height=360 ! jpegenc name=enc quality=80 ! appsink name=out sync=false max-buffers=2 drop=false",
+      "last_bytes": 113339
+    }
+  ]
+}

docs/evidence/windows-vm-2026-10-24/capture-before.json

@@ -0,0 +1,96 @@
+{
+  "python": "3.12.14 (main, Sep 24 2026, 17:57:31) [MSC v.1944 64 bit (AMD64)]",
+  "resources": "C:\\Users\\frame\\AppData\\Local\\Programs\\Frame Control\\resources",
+  "elements": {
+    "d3d11screencapturesrc": true,
+    "mfh264enc": true,
+    "jpegenc": true,
+    "x264enc": false
+  },
+  "windows": [
+    {
+      "src": "window:131836",
+      "id": 131836,
+      "title": "Administrator: C:\\WINDOWS\\system32\\cmd.exe - powershell  -noprofile -executionpolicy bypass -file \\\\host.lan\\data\\bootstrap.ps1",
+      "app": "Windows",
+      "w": 1115,
+      "h": 628,
+      "x": 51,
+      "y": 52
+    },
+    {
+      "src": "window:327926",
+      "id": 327926,
+      "title": "Administrator: Install",
+      "app": "Windows",
+      "w": 979,
+      "h": 512,
+      "x": 85,
+      "y": 78
+    },
+    {
+      "src": "window:65856",
+      "id": 65856,
+      "title": "Program Manager",
+      "app": "Windows",
+      "w": 1280,
+      "h": 800,
+      "x": 0,
+      "y": 0
+    }
+  ],
+  "displays": [
+    {
+      "src": "display:65537",
+      "name": "Display 1",
+      "x": 0,
+      "y": 0,
+      "w": 1280,
+      "h": 800
+    }
+  ],
+  "runs": [
+    {
+      "source": "test",
+      "codec": "h264",
+      "frames": 5,
+      "pipeline": "videotestsrc name=source is-live=true pattern=ball ! video/x-raw,framerate=30/1 ! queue name=raw_queue leaky=downstream max-size-buffers=1 max-size-bytes=0 max-size-time=0 ! identity name=gate ! videoconvert ! videoscale add-borders=false ! video/x-raw,width=640,height=360,format=NV12 ! mfh264enc name=enc low-latency=true bframes=0 gop-size=60 bitrate=1000 ! h264parse config-interval=-1 ! video/x-h264,stream-format=byte-stream,alignment=au ! appsink name=out sync=false max-buffers=2 drop=false",
+      "last_bytes": 154
+    },
+    {
+      "source": "test",
+      "codec": "jpeg",
+      "frames": 5,
+      "pipeline": "videotestsrc name=source is-live=true pattern=ball ! video/x-raw,framerate=30/1 ! queue name=raw_queue leaky=downstream max-size-buffers=1 max-size-bytes=0 max-size-time=0 ! identity name=gate ! videoconvert ! videoscale add-borders=false ! video/x-raw,width=640,height=360 ! jpegenc name=enc quality=80 ! appsink name=out sync=false max-buffers=2 drop=false",
+      "last_bytes": 7336
+    },
+    {
+      "source": "display:65537",
+      "codec": "h264",
+      "frames": 0,
+      "pipeline": "d3d11screencapturesrc capture-api=wgc show-cursor=true show-border=true monitor-handle=65537 ! video/x-raw,framerate=30/1 ! queue name=raw_queue leaky=downstream max-size-buffers=1 max-size-bytes=0 max-size-time=0 ! identity name=gate ! videoconvert ! videoscale add-borders=false ! video/x-raw,width=640,height=360,format=NV12 ! mfh264enc name=enc low-latency=true bframes=0 gop-size=60 bitrate=1000 ! h264parse config-interval=-1 ! video/x-h264,stream-format=byte-stream,alignment=au ! appsink name=out sync=false max-buffers=2 drop=false",
+      "error": "no property \"capture-api\" in element \"d3d11screencapturesrc\""
+    },
+    {
+      "source": "display:65537",
+      "codec": "jpeg",
+      "frames": 0,
+      "pipeline": "d3d11screencapturesrc capture-api=wgc show-cursor=true show-border=true monitor-handle=65537 ! video/x-raw,framerate=30/1 ! queue name=raw_queue leaky=downstream max-size-buffers=1 max-size-bytes=0 max-size-time=0 ! identity name=gate ! videoconvert ! videoscale add-borders=false ! video/x-raw,width=640,height=360 ! jpegenc name=enc quality=80 ! appsink name=out sync=false max-buffers=2 drop=false",
+      "error": "no property \"capture-api\" in element \"d3d11screencapturesrc\""
+    },
+    {
+      "source": "window:131836",
+      "codec": "h264",
+      "frames": 0,
+      "pipeline": "d3d11screencapturesrc capture-api=wgc show-cursor=true show-border=true window-handle=131836 ! video/x-raw,framerate=30/1 ! queue name=raw_queue leaky=downstream max-size-buffers=1 max-size-bytes=0 max-size-time=0 ! identity name=gate ! videoconvert ! videoscale add-borders=false ! video/x-raw,width=640,height=360,format=NV12 ! mfh264enc name=enc low-latency=true bframes=0 gop-size=60 bitrate=1000 ! h264parse config-interval=-1 ! video/x-h264,stream-format=byte-stream,alignment=au ! appsink name=out sync=false max-buffers=2 drop=false",
+      "error": "no property \"capture-api\" in element \"d3d11screencapturesrc\""
+    },
+    {
+      "source": "window:131836",
+      "codec": "jpeg",
+      "frames": 0,
+      "pipeline": "d3d11screencapturesrc capture-api=wgc show-cursor=true show-border=true window-handle=131836 ! video/x-raw,framerate=30/1 ! queue name=raw_queue leaky=downstream max-size-buffers=1 max-size-bytes=0 max-size-time=0 ! identity name=gate ! videoconvert ! videoscale add-borders=false ! video/x-raw,width=640,height=360 ! jpegenc name=enc quality=80 ! appsink name=out sync=false max-buffers=2 drop=false",
+      "error": "no property \"capture-api\" in element \"d3d11screencapturesrc\""
+    }
+  ]
+}

docs/evidence/windows-vm-2026-10-24/plugin-properties.json

@@ -0,0 +1,65 @@
+{
+  "gstreamer": "1.28.8",
+  "plugins": [
+    "coreelements",
+    "videotestsrc",
+    "videoconvertscale",
+    "app",
+    "jpeg",
+    "videoparsersbad",
+    "d3d11",
+    "mediafoundation"
+  ],
+  "packages": [
+    "mingw-w64-ucrt-x86_64-gst-plugins-bad 1.28.8-2",
+    "mingw-w64-ucrt-x86_64-gst-plugins-bad-libs 1.28.8-2",
+    "mingw-w64-ucrt-x86_64-gstreamer 1.28.8-1"
+  ],
+  "elements": {
+    "d3d11screencapturesrc": {
+      "name": "The name of the object",
+      "parent": "The parent of the object",
+      "blocksize": "Size in bytes to read per buffer (-1 = default)",
+      "num-buffers": "Number of buffers to output before sending EOS (-1 = unlimited)",
+      "typefind": "Run typefind before negotiating (deprecated, non-functional)",
+      "do-timestamp": "Apply current stream time to buffers",
+      "automatic-eos": "Automatically EOS when the segment is done",
+      "monitor-index": "Zero-based index for monitor to capture (-1 = primary monitor)",
+      "monitor-handle": "A HMONITOR handle of monitor to capture",
+      "show-cursor": "Whether to show mouse cursor",
+      "crop-x": "Horizontal coordinate of top left corner for the screen capture area",
+      "crop-y": "Vertical coordinate of top left corner for the screen capture area",
+      "crop-width": "Width of screen capture area (0 = maximum)",
+      "crop-height": "Height of screen capture area (0 = maximum)"
+    },
+    "d3d12screencapturesrc": null,
+    "mfh264enc": {
+      "name": "The name of the object",
+      "parent": "The parent of the object",
+      "qos": "Handle Quality-of-Service events from downstream",
+      "min-force-key-unit-interval": "Minimum interval between force-keyunit requests in nanoseconds",
+      "bitrate": "Bitrate in kbit/sec",
+      "rc-mode": "Rate Control Mode",
+      "adaptive-mode": "Adaptive Mode",
+      "vbv-buffer-size": "VBV(HRD) Buffer Size in bytes (0 = MFT default)",
+      "max-bitrate": "The maximum bitrate applied when rc-mode is \"pcvbr\" in kbit/sec",
+      "quality-vs-speed": "Quality and speed tradeoff, [0, 33]: Low complexity, [34, 66]: Medium complexity, [67, 100]: High complexity",
+      "cabac": "Enable CABAC entropy coding",
+      "sps-id": "The SPS id to use",
+      "pps-id": "The PPS id to use",
+      "bframes": "The maximum number of consecutive B frames",
+      "gop-size": "The number of pictures from one GOP header to the next. Depending on GPU vendor implementation, zero gop-size might produce only one keyframe at the beginning (-1 for automatic)",
+      "threads": "The number of worker threads used by a encoder, (0 = MFT default)",
+      "content-type": "Indicates the type of video content",
+      "qp": "QP applied when rc-mode is \"qvbr\"",
+      "low-latency": "Enable low latency encoding",
+      "min-qp": "The minimum allowed QP applied to all rc-mode",
+      "max-qp": "The maximum allowed QP applied to all rc-mode",
+      "qp-i": "QP applied to I frames",
+      "qp-p": "QP applied to P frames",
+      "qp-b": "QP applied to B frames",
+      "ref": "The number of reference frames",
+      "d3d11-aware": "Whether device can support Direct3D11 interop"
+    }
+  }
+}

docs/evidence/windows-vm-2026-10-24/windows-system.txt

@@ -0,0 +1,18 @@
+
+WindowsProductName WindowsVersion OsBuildNumber
+------------------ -------------- -------------
+Windows 10 Pro     2009           26200        
+
+
+
+Name                              DriverVersion     Status
+----                              -------------     ------
+Red Hat VirtIO GPU DOD controller 100.103.104.30200 OK    
+
+
+
+       Used       Free
+       ----       ----
+23951253504 9314816000
+
+

docs/evidence/windows-vm-2026-10-24/windows-tests.txt

@@ -0,0 +1,79 @@
+python.exe : test_original_mac_congestion_and_recovery 
+(test_pc_controller.ControllerTrace.test_original_mac_congestion_and_recovery) ... skipped 'C 
+compiler not installed; native build jobs cover this trace'
+At line:12 char:1
++ & $python -B -m unittest discover -s tests -p 'test_pc*.py' -v 2>&1 | ...
++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    + CategoryInfo          : NotSpecified: (test_original_m...ver this trace':String) [], Remote 
+   Exception
+    + FullyQualifiedErrorId : NativeCommandError
+ 
+test_controller_is_inert_after_close 
+(test_pcview.AdapterTests.test_controller_is_inert_after_close) ... ok
+test_dxgi_only_bundle_captures_displays_without_optional_wgc_properties (test_pcview.AdapterTests.
+test_dxgi_only_bundle_captures_displays_without_optional_wgc_properties) ... ok
+test_idle_source_is_not_a_stall (test_pcview.AdapterTests.test_idle_source_is_not_a_stall) ... ok
+test_library_path_prepend_adds_no_empty_entry 
+(test_pcview.AdapterTests.test_library_path_prepend_adds_no_empty_entry) ... ok
+test_linux_uses_only_portal_fd_and_node 
+(test_pcview.AdapterTests.test_linux_uses_only_portal_fd_and_node) ... ok
+test_malformed_viewer_input_is_dropped_not_fatal 
+(test_pcview.AdapterTests.test_malformed_viewer_input_is_dropped_not_fatal) ... ok
+test_pc_card_receives_window_capture_limitation 
+(test_pcview.AdapterTests.test_pc_card_receives_window_capture_limitation) ... ok
+test_pc_reuses_launcher_and_namespaces_panel_ids 
+(test_pcview.AdapterTests.test_pc_reuses_launcher_and_namespaces_panel_ids) ... ok
+test_portal_input_clamps_and_releases_held_state 
+(test_pcview.AdapterTests.test_portal_input_clamps_and_releases_held_state) ... ok
+test_refused_windows_focus_never_clicks_the_covering_app 
+(test_pcview.AdapterTests.test_refused_windows_focus_never_clicks_the_covering_app) ... ok
+test_session_end_releases_native_input_only_once 
+(test_pcview.AdapterTests.test_session_end_releases_native_input_only_once) ... ok
+test_stats_keep_capture_time_and_bound_records 
+(test_pcview.AdapterTests.test_stats_keep_capture_time_and_bound_records) ... ok
+test_windows_release_and_negative_monitor_origin 
+(test_pcview.AdapterTests.test_windows_release_and_negative_monitor_origin) ... ok
+test_windows_sources_follow_actual_wgc_capabilities 
+(test_pcview.AdapterTests.test_windows_sources_follow_actual_wgc_capabilities) ... ok
+test_windows_uses_wgc_and_media_foundation 
+(test_pcview.AdapterTests.test_windows_uses_wgc_and_media_foundation) ... ok
+test_never_offered_off_windows_even_when_turned_on 
+(test_pcview.GatingTests.test_never_offered_off_windows_even_when_turned_on) ... ok
+test_off_by_default_starts_nothing (test_pcview.GatingTests.test_off_by_default_starts_nothing) 
+... ok
+test_only_windows_gets_the_pc_host (test_pcview.GatingTests.test_only_windows_gets_the_pc_host) 
+... ok
+test_server_enable_action (test_pcview.GatingTests.test_server_enable_action) ... ok
+test_turning_off_stops_streams_and_the_helper 
+(test_pcview.GatingTests.test_turning_off_stops_streams_and_the_helper) ... ok
+test_turning_on_checks_for_the_bundled_libraries 
+(test_pcview.GatingTests.test_turning_on_checks_for_the_bundled_libraries) ... ok
+test_expiry_and_stop_before_redeem (test_pcview.GrantsTests.test_expiry_and_stop_before_redeem) 
+... ok
+test_source_bound_retry_ack_and_stop 
+(test_pcview.GrantsTests.test_source_bound_retry_ack_and_stop) ... ok
+test_agent_reports_its_host_and_encoder 
+(test_pcview.NativeTests.test_agent_reports_its_host_and_encoder) ... ok
+test_auth_and_real_h264_stats (test_pcview.NativeTests.test_auth_and_real_h264_stats) ... skipped 
+'x264 is only in CI test bundles, not the installer'
+test_bundled_pipewire_context_needs_no_system_modules 
+(test_pcview.NativeTests.test_bundled_pipewire_context_needs_no_system_modules) ... skipped 
+'Linux PipeWire client libraries'
+test_installer_bundle_leaves_out_gpl_x264 
+(test_pcview.NativeTests.test_installer_bundle_leaves_out_gpl_x264) ... ok
+test_last_raw_picture_survives_a_closed_gate 
+(test_pcview.NativeTests.test_last_raw_picture_survives_a_closed_gate) ... skipped 'x264 is only 
+in CI test bundles, not the installer'
+test_native_property_probe_checks_the_instantiated_element 
+(test_pcview.NativeTests.test_native_property_probe_checks_the_instantiated_element) ... ok
+test_card_says_experimental_and_what_is_unverified 
+(test_pcview.PageTests.test_card_says_experimental_and_what_is_unverified) ... ok
+test_opt_in_is_remembered_with_the_client_preferences 
+(test_pcview.PageTests.test_opt_in_is_remembered_with_the_client_preferences) ... ok
+test_tool_link_is_windows_only_and_marked_experimental 
+(test_pcview.PageTests.test_tool_link_is_windows_only_and_marked_experimental) ... ok
+
+----------------------------------------------------------------------
+Ran 33 tests in 1.684s
+
+OK (skipped=4)

docs/file-transfer.md

@@ -62,6 +62,12 @@ refused with a message, so send big things as a file. An empty clipboard, or
 one holding an image, says so. Neither the server nor its log ever records what
 was on the clipboard.
 
-**Not tested on a headset yet.** Reading uses the same Klipper interface as
-sending, which was verified on 2026-09-25, but `getClipboardContents` itself
-hasn't been tried on a Frame. The fake Frame (`tests/fakeframe`) answers it.
+**Verified on a Frame, 2026-10-24:** SteamOS 0.5.6, build
+`20261015.6141207`. With a temporary nested desktop open, Frame Control sent
+a 47-character test marker to Klipper, then **Copy the headset's clipboard**
+read it through `getClipboardContents` and set a Linux PC's X11 clipboard.
+Reading that PC clipboard returned the exact marker. The prior headset
+clipboard was restored and the test desktop was closed. The PC side used a
+temporary X display on lxso2; macOS and Windows clipboard backends, a user's
+copy action in a headset app, and image/size error cases remain untested on a
+real headset. The fake Frame (`tests/fakeframe`) covers the protocol cases.

docs/frame-doctor.md

@@ -0,0 +1,121 @@
+# Frame doctor
+
+Run `scripts/frame-doctor.sh` from a checkout on macOS or Linux to diagnose
+first-time setup, pairing and common Frame failures without applying repairs.
+It needs Bash, Python 3 and OpenSSH on the computer, and Python 3 on the Frame.
+Windows users can run `python scripts/frame_doctor.py` with Python and OpenSSH
+installed; the desktop app does not bundle this command.
+
+```sh
+scripts/frame-doctor.sh
+scripts/frame-doctor.sh --alias bedroom --lan frame.local
+scripts/frame-doctor.sh --alias frame --lan 192.168.1.40
+```
+
+Use only addresses belonging to your intended headset. The command tries the
+existing `frame` SSH alias first (Tailscale if setup configured it that way),
+then `frame.local`, then USB-C at `10.86.200.233`. `--alias`, `--lan` and `--usb`
+override those defaults. It reports the successful path without printing its
+address. It neither discovers other devices nor enables Tailscale.
+
+The existing alias supplies the user, port, keys and known-hosts file. LAN and
+USB overrides preserve its `HostKeyAlias`, or its configured hostname if no
+alias was set. A first connection therefore needs trusted setup first. The
+doctor never accepts a new host key, deletes a saved key, generates keys or
+sends a pairing request. It uses your trusted OpenSSH configuration; OpenSSH
+can evaluate `Match exec` conditions in that configuration. Proxy commands,
+jumps, local commands, forwarding and connection sharing are disabled for
+these direct diagnostic connections.
+
+## Reading the result
+
+Each of the eleven runbook sections has one line: `OK`, `WARN`, `BROKEN` or
+`UNKNOWN`. `OK` means only that the stated check passed, not that the whole
+feature works. Optional features that are off may produce a warning.
+
+| Section | Read-only evidence and limits |
+|---|---|
+| 1. Boot and crash history | Previous-boot kernel-oops signatures; one day of coredump history. An oops alone does not prove an unclean reset. |
+| 2. Wi-Fi | NetworkManager's wlan0 state, without SSIDs or connection profiles. |
+| 3. Displays and SteamVR | DSI timeout signatures in the recent kernel journal; no display, compositor or game is launched. |
+| 4. Steam and storage | Free space in home and `devkit-game`, including separate mounts; missing Steam install marker. No CRC scan or restart. |
+| 5. Idle sleep and keep-awake | Existing keep-awake unit state; never takes ownership or changes idle timers. |
+| 6. Remote wake | WoWLAN state, without arming it or testing suspend. Wake with the power button. |
+| 7. Lepton | Recent port-clash, binder and data-clearing signatures; no Android/container commands. |
+| 8. Chromium XR | Crash history; no browser profile or environment inspection. |
+| 9. KDE Connect | Process presence; absence is normal when sharing is off. |
+| 10. Streaming and capture | ffmpeg crash history; no capture or encoder is started. |
+| 11. Panels | Always `UNKNOWN`: placement requires the user's visual confirmation. |
+
+Journal samples are capped at 2,000 entries; current-boot samples cover the
+last ten minutes. This can miss older or high-volume failures. Empty,
+inaccessible or permission-limited journals are `UNKNOWN`, never zero errors.
+Commands time out individually, and each SSH probe is bounded to 90 seconds.
+
+Exit codes: **0** if all reported checks are OK; **1** for warnings, broken or
+unknown checks after connecting; **2** if no authenticated SSH path exists or
+local SSH setup is unavailable. Panel verification currently means a connected
+run normally exits 1. Automation should read the labelled checks rather than
+treating a warning as proof the headset is unusable.
+
+## First-time setup and pairing
+
+- **No SSH response:** wake the headset with its power button. Check the cable
+  or Steam Settings → Internet, then enable Developer Mode. Sleep and network
+  failure can look alike; a timeout cannot distinguish them.
+- **Key rejected:** open **Set Up Connection** in Frame Control. In the headset,
+  open Steam Settings → Developer → **Pair new host**, then approve setup's
+  request. The doctor only checks whether devkit port 32000 responds; that
+  does not prove pairing mode is open or the service is healthy.
+- **Unknown or changed identity:** verify the intended headset through setup
+  or Devices → **Check its key**. Do not delete `known_hosts` to bypass this.
+- **No devkit response:** check Developer Mode and the address. See
+  [SSH setup](ssh.md) for the manual fallback. The doctor cannot turn SSH on.
+
+No password is requested. Enter any password required by the separate setup
+flow only in its local terminal; never paste it into an issue or report.
+
+## Restart safety and recovery
+
+Before deeper checks, and again afterwards, the doctor samples Steam and
+SteamVR `NRestarts` and health-check tracker sizes two seconds apart. Rising
+counters stop diagnostics immediately. Nonempty health-check trackers also stop
+deeper checks even when stable, since a short sample could miss a slower loop.
+Missing counters or counters that reset stop deeper checks as `UNKNOWN`. Stable
+counters with empty trackers still cannot rule out a slower restart loop.
+
+The [historical runbook from PR #33](https://github.com/saphid/frame-control/blob/cce3d940302054ab5246c92d740afaefc4e58d38/docs/frame-doctor.md)
+is the source for these section numbers and observed signatures (September
+2026 builds). Its section 4 describes freezing and verifying health-check
+trackers before prolonged recovery during a live loop. That changes headset
+state, so this read-only implementation stops and directs you there instead.
+It does not implement issue #34's automatic fixes, before/after repair runs,
+or full recovery automation. Review build-specific recovery instructions with
+the person using the headset; a repair can remove data.
+
+Never reload `ath12k`, suspend remotely, kill gamescope to diagnose a loop,
+reset or force power off during extraction/repair, or write passwords to disk.
+The doctor never restarts services, signals processes, repairs Steam, changes
+WoWLAN/standby settings, takes keep-awake ownership, installs anything or writes
+a report. Nothing needs restoring after its checks. Manual/device tests must
+follow the [shared-device lock and battery procedure](testing.md#headset-smoke-test).
+
+## Privacy and verification
+
+Only fixed diagnostic summaries leave the remote probe. Raw journals, process
+arguments, environment variables, SSH errors, account IDs, network addresses,
+SSIDs, keys and tokens are not printed. No telemetry or HTTP request is sent;
+the only pairing-service probe is a TCP connection. SSH produces normal access
+logs. Review summaries before sharing them; feature availability can still be
+personal information. Redirecting stdout saves a report only if you choose it.
+
+Unit tests use mocked boundaries. `scripts/e2e.sh test_doctor` covers asleep,
+disk-full, SSH/devkit-off and missing-key faults against the fake Frame. Its
+stable restart counters are explicitly simulated, not proof about SteamOS.
+On 2026-10-24 the script ran read-only against a real Frame, SteamOS build
+`20261015.6141207`. It verified the configured SSH alias and key login,
+then reported `WARN Restart safety`: nonempty health-check trackers. It
+correctly skipped all eleven deeper sections and exited 1. No raw logs,
+addresses or keys were printed, and no repair or restart was attempted.
+This verifies the safety stop on that device; the deeper checks are not
+claimed as headset-tested.

docs/game-storage.md

@@ -0,0 +1,91 @@
+# Game storage
+
+Open **Tools → Game storage** for a read-only snapshot of the headset's user
+filesystem and Steam libraries. Refresh after an installation, download or move.
+The page never moves, deletes or modifies content, starts Steam, requests root,
+or recursively scans game files. It works through the existing SSH connection.
+
+## What the numbers mean
+
+- **Total, free and used** come from `statvfs` on the headset user's home and
+  each library path. Free is space available to that user; reserved blocks mean
+  used + free can be less than total. These are filesystem sizes, not advertised
+  drive capacity, and do not include separate system partitions.
+- Libraries come from `~/.local/share/Steam/steamapps/libraryfolders.vdf` plus
+  the default Steam library. Modern nested and older numbered-path records are
+  accepted; canonical duplicate paths are shown once. No drive is mounted.
+- Two paths can share one filesystem. Their capacity must **not** be added.
+  An unmounted drive whose mount directory still exists can report the parent
+  filesystem's capacity: the page labels this as the filesystem containing the
+  path, rather than claiming the removable drive is connected.
+- Game sizes are Steam's `SizeOnDisk` records in `appmanifest_<appid>.acf`, sorted
+  largest first, with unknown sizes last. A missing, negative or invalid size
+  is **Unknown**, while an explicit zero remains zero. Records may be stale,
+  including during downloads or moves; they do not measure allocated blocks.
+- Games/apps and runtimes/tools have separate subtotals of **known recorded**
+  sizes. Runtime classification uses names (Proton, Steam Linux Runtime,
+  Steamworks Common, FEX and Lepton Development), so it is only a convenience.
+  Additional apps or runtimes may fall in the game/app group.
+- Saves, Proton prefixes, shaders, workshops, downloads, Android apps,
+  sideloaded games, media and OS files are **unmeasured other usage**. The page
+  does not subtract manifest totals from filesystem usage to invent a size for
+  them. Recorded content is not an exhaustive storage breakdown.
+
+Permission denied, missing/disconnected paths, unavailable filesystem reads,
+invalid metadata and partial inventories are reported separately. A failed read
+is never proof of an empty library. If library discovery fails, other libraries
+may be missing from the view. Refresh clears the old results immediately; a
+headset switch clears the snapshot and ignores late replies from the old device.
+
+## Moving a game safely
+
+Use Steam's own **Settings → Storage** on the headset (or in desktop Steam):
+choose the source drive, select the games and choose **Move**, then pick a
+Steam-supported destination. A second Steam library must already be available.
+Steam may withhold Move or a destination when it cannot perform the operation.
+Let Steam finish, follow Steam's errors/recovery prompts, then Refresh here.
+Do not manually delete files to make room or interrupt an in-progress move.
+
+[Valve's moving guide](https://help.steampowered.com/en/faqs/view/4BD4-4528-6B2E-8327#move)
+was read in a browser on 2026-10-24 and documents this UI. This is an instructional
+handoff: the page does not send a URI or silently open a UI on the headset.
+The guide's separate Windows instructions for moving the entire Steam client
+are outside this feature's scope.
+
+### Why Frame Control does not automate moving
+
+The repository's Valve devkit tools register and launch developer titles; no
+supported game-move operation is provided there. The existing Steam CEF bridge
+uses internal client APIs, which are not a verified supported contract for a
+move transaction. [Valve's public ISteamApps reference](https://partner.steamgames.com/doc/api/ISteamApps) provides install-directory
+and installed-depot queries but no documented move transaction with completion,
+cancellation, rollback and error guarantees. The public support guide describes
+the user-operated Storage UI, rather than such an automation interface.
+
+Consequently this feature adds no move endpoint or guessed internal Steam call,
+manifest rewrite, copy/delete fallback, or custom rollback. Automating a move
+requires a supported interface and verified behaviour for full disks, disconnects,
+running games, downloads, cancellation and Steam restart first.
+
+## Verification and limits
+
+`tests/test_storage.py` runs the actual probe against temporary Steam metadata
+and filesystem/error fixtures. It covers multiple libraries, duplicate paths,
+zero/unknown/invalid sizes, corrupt manifests, unreadable directories and files,
+missing discovery/drives, reserved capacity and read-only file preservation.
+A loopback HTTP test executes the real guarded endpoint with SSH mocked.
+`tests/storage.cjs` runs the production renderer, navigation and refresh handlers
+with DOM/transport boundaries faked, including escaping, offline errors,
+out-of-order refreshes and headset switches. It runs through unittest discovery.
+
+The production storage component was rendered with synthetic data at 390px and
+900px widths; both fit without horizontal overflow. This checks component
+layout, not the full connected application or headset browser.
+
+On 2026-10-24 the uninstalled storage parser was piped read-only over SSH
+to a real Frame running SteamOS build `20261015.6141207`. It reported
+710.4 GiB free on the user filesystem, one available Steam library, 29
+readable app manifests, zero unknown sizes and zero parse/permission issues.
+No game names or raw metadata were printed in the test report. The
+connected UI, removable media, Steam's Move UI and an actual game move were
+not tested. UI and error-state fixtures remain synthetic.

docs/mac-in-headset.md

@@ -4,7 +4,8 @@ Frame Control can show any Mac window, or a whole Mac screen, as its own panel
 in the Steam Frame. You place each panel anywhere in the room with the SteamVR
 dashboard. The laser clicks and drags, the thumbstick scrolls, and you type on
 the Mac's own keyboard. Find it under **Tools → Mac in the headset** (macOS
-only).
+only). On Windows there's an experimental port,
+[PC in the headset](pc-in-headset.md).
 
 The confidence labels are the same as in [ssh.md](ssh.md).
 

docs/pc-in-headset.md

@@ -0,0 +1,155 @@
+# PC in the headset (Experimental)
+
+**Tools → PC in the headset**, on Windows only. It's the Windows version of
+[Mac in the headset](mac-in-headset.md): a whole screen on your PC
+becomes its own SteamVR panel in the Frame. Individual windows are available only
+with streaming libraries built with Windows Graphics Capture (WGC); the shipped
+MSYS2 libraries disable WGC, so this build explains that limitation and offers
+whole screens. Place the panel with the dashboard's Float
+in World, Move and Size, point and click with the laser, scroll with the
+thumbstick, and type on the PC's keyboard.
+
+**It's experimental.** A Windows 11 VM has captured its real desktop with
+Desktop Duplication and encoded it with Media Foundation and JPEG. Physical PCs,
+hardware encoding and physical laser input remain unverified. See
+[the dated evidence](evidence/windows-vm-2026-10-24.md) for results and limits.
+Reports are welcome through the
+[feedback form](https://frame-control.pages.dev/feedback/).
+
+## Turning it on
+
+It's off by default. Until you tick **Turn on PC in the headset** on the card,
+Frame Control starts no helper, loads none of the streaming libraries and lists
+no windows. The choice is remembered on this computer. Turning it off ends
+every stream, closes the viewers in the headset and stops the helper.
+
+The card and its Tools link only appear in the Windows app. On macOS the card
+is Mac in the headset, as before; on Linux and the iPhone app there's no card.
+
+## How it works
+
+The ported pieces are from [PR #38](https://github.com/saphid/frame-control/pull/38).
+Frame Control owns the host helper, input, authentication, streaming protocol,
+panel launcher and adaptation. It doesn't need Sunshine, OBS or any other
+streaming app. GStreamer is bundled as ordinary libraries.
+
+| | Windows |
+|---|---|
+| Capture | GStreamer's `d3d11screencapturesrc`: Desktop Duplication for whole screens in the shipped build; Windows.Graphics.Capture by window (HWND) or screen (HMONITOR) when that implementation is present |
+| Encoding | Media Foundation's H.264 encoder (`mfh264enc`), low latency, no B-frames. Whether it uses the GPU depends on the PC; **not verified** |
+| Input | `SendInput`, mapped through the source's bounds, with per-monitor DPI awareness |
+
+API references:
+[Windows capture](https://learn.microsoft.com/en-us/windows/uwp/audio-video-camera/screen-capture),
+[GStreamer WGC](https://gstreamer.freedesktop.org/documentation/d3d11/d3d11screencapturesrc.html),
+[Media Foundation encoder](https://gstreamer.freedesktop.org/documentation/mediafoundation/mfh264enc.html).
+
+It needs Windows 10 or 11 with Desktop Duplication and a Media Foundation
+H.264 encoder (Windows "N" editions need the Media Feature Pack). WGC-enabled
+builds can also capture individual windows. Clicks and
+keys can't reach administrator apps or the sign-in screen, which an ordinary
+process can't drive. If Windows won't bring the chosen window to the front,
+input is refused rather than sent to the app covering it: bring the window
+forward, then Stop and Show again. Minimised or closed windows stop sending
+pictures. Protected video isn't supported. Mac in the headset's "own display
+per window" is Mac-only.
+
+The pieces it shares with Mac in the headset:
+
+- `ui/frame_macview.py` owns the SSH tunnel, reconnects, quality presets and
+  panel launch. `ui/frame_pcview.py` picks the Windows helper
+  (`ui/frame_pc_agent.py`, `ui/frame_pc_capture.py`, `desktop/capture.c`) and
+  holds the on/off switch. `/api/macview` is the endpoint for both.
+- `ui/mac-view.html` is the one viewer in the headset. Its frame header, H.264
+  and JPEG payloads, reconnect handshake, clock sync, timing reports and input
+  messages are unchanged.
+- `desktop/controller.c` is a C port of the Mac helper's Swift rate controller,
+  for the Windows helper. The Mac keeps its Swift original;
+  `tests/test_pc_controller.py` checks the port against a frozen 600-state
+  trace from it. Capture is gated before encoding, so encoded frames are never
+  dropped, and an idle window's last picture still goes out once the link
+  clears.
+- Stream records use the Mac helper's JSON schema (`ui/frame_stream_stats.py`),
+  so the benchmark's analysis is shared.
+
+## Packaging
+
+The Windows installer carries `resources/desktop/bundle`: `pc-host.dll` (our
+adapter and the controller), the GStreamer plugins it uses (`coreelements`,
+`videotestsrc`, `videoconvertscale`, `app`, `jpeg`, `videoparsersbad`,
+`d3d11`, `mediafoundation`) and the DLLs they depend on, all from MSYS2's
+UCRT64 packages. `libraries.json` records the GStreamer version, the plugins,
+each copied DLL and the exact package versions; licence texts are in
+`licenses/`.
+
+MSYS2's `gst-plugins-bad` build disables `d3d11-wgc`. The presence of
+`d3d11screencapturesrc` alone does not prove WGC support: its `capture-api`,
+`window-handle` and `show-border` properties are conditional. The helper queries
+those properties on the instantiated element, advertises only supported
+sources, and omits all three properties for the DXGI whole-screen pipeline.
+It never substitutes a screen crop for an unavailable window capture.
+
+The x264 encoder is **not** in the installer. It's GPL, and Windows encodes
+with Media Foundation, so only CI's test builds include it
+(`desktop/build.py --with-x264`). The macOS and Linux installers are unchanged.
+
+From a source checkout on Windows, build the bundle from an MSYS2 UCRT64 shell
+with the packages listed in `.github/workflows/pc-host.yml`:
+
+```sh
+python desktop/build.py              # what the installer ships
+python desktop/build.py --with-x264  # for the native tests
+```
+
+A missing bundle is reported on the card; nothing is downloaded on first use.
+
+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.
+
+## Measuring
+
+The Mac benchmark accepts the PC host:
+
+```sh
+python scripts/macview-bench.py run --pc --scenario test --label pc-test
+python scripts/macview-bench.py run --pc --scenario capture --source window:12345 --label windows-window
+```
+
+`capture` needs a window or screen id from the helper's `/windows` or
+`/displays`. CPU sampling isn't available on PC hosts. See
+[Mac in the headset](mac-in-headset.md) for the targets and shaping options.
+
+## What's verified
+
+- **Verified in CI, this PR:** on `windows-latest`, the native adapter builds
+  and a real x264 synthetic stream passes the ticket, reconnect, timing and
+  input-echo tests through the helper. The Windows installer builds with the
+  bundle, and its bundled Python loads the bundle, starts the helper and
+  confirms x264 isn't in it. Unit tests check the Windows-only, off-by-default
+  gating, the card and the Tools link on macOS, Windows and Linux.
+- **Verified, #38, 2026-09-28, real Frame on SteamOS BUILD_ID 20260925.6191901:**
+  the PC helper (ARM64, on the Frame itself, x264 test pattern) streamed
+  through a Mac SSH relay into the shared viewer: 400 frames at 39.3 fps,
+  content latency p50/p95 15.1/28.6 ms, synthetic input p50 76.6 ms, at
+  revision `cd20243`. The frame-rate and late-frame targets failed. This
+  proves the helper and the viewer work together; it isn't Windows capture or
+  a real PC link.
+  [Raw result](../bench/results/2026-09-28-cd20243-pc-agent-frame-arm64-final.json),
+  [earlier probe](../bench/results/2026-09-28-c5fc552-dirty-pc-agent-frame-arm64-hairpin.json).
+- **Verified, #38, on a Mac:** the C controller matched all 600 states of the
+  Swift controller's congestion and recovery trace.
+- **Verified, 2026-10-24:** Windows 11 VM build 26200.8037 on lxso2, using
+  the v0.4.10 installer with this fix, captured its actual desktop and streamed
+  H.264 to Frame BUILD_ID `20261015.6141207`: 219 sent frame records, 215 decoded
+  and drawn before the snapshot. The own-panel screenshot shows the Windows
+  desktop. This short, mostly idle run does not establish performance targets.
+  [Evidence, raw traces and cleanup](evidence/windows-vm-2026-10-24.md).
+- **Not verified:** Windows.Graphics.Capture, physical-PC capture, hardware
+  Media Foundation encoding, encoder restarts when the bitrate
+  changes, mixed-DPI and multi-monitor input alignment, window resize and
+  minimise, non-US keyboard layouts, physical laser input, and how it performs
+  in a worn headset. No numbers are claimed for these. Not tested with a
+  worn headset. See the dated VM evidence for the separate automated checks.
+- **Not reviewed independently.** #38 tried an independent review that never
+  completed.

docs/recording.md

@@ -149,11 +149,12 @@ recording with Steam's file names and export it with the real `ffmpeg`.
 
 ## What hasn't been checked
 
-None of this has run on a Steam Frame yet. In particular:
+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:
 
-- That SteamOS's `ffmpeg` can read `@DEFAULT_MONITOR@`. It has the PulseAudio
-  output device (the media player plays through it), so the input is expected,
-  but if it fails the recording is video only, as above.
 - 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

docs/scripts.md

@@ -7,6 +7,10 @@ run on Linux. On Windows, use the app.
 
 ## Minimum typing on the headset
 
+If setup or pairing fails, run `scripts/frame-doctor.sh` from this checkout.
+It checks existing SSH access without requesting passwords, pairing or applying
+repairs. See the [Frame doctor guide](frame-doctor.md) for results and next steps.
+
 Valve's own developer docs say SSH, ADB, and RDP are all turned on through a
 **UI toggle**. You don't need a terminal, `passwd`, or `systemctl`. The only
 thing you type on the headset is a password you choose.

docs/testing.md

@@ -44,6 +44,20 @@ them on macOS, Windows and Linux. They don't pick up `tests/e2e`.
 
 ## The fake Frame
 
+Frame doctor has focused offline tests in `tests/test_frame_doctor.py` and
+fake-Frame fault tests in `tests/e2e/test_doctor.py`:
+
+```sh
+python3 -m unittest discover -s tests -p test_frame_doctor.py -v
+scripts/e2e.sh test_doctor
+```
+
+They cover privacy filtering, host-key preservation, restart safety and missing
+journal evidence, plus asleep, full-title-storage, SSH/devkit-off and missing-key
+faults. The fake's doctor-only `systemctl show` responses assume stable restart
+counters and inactive keep-awake; unsupported queries fail. These tests do not
+exercise a real SteamOS user manager or touch a headset.
+
 `tests/fakeframe/` builds a container that stands in for the headset, and a
 second one for the computer Frame Control runs on. `scripts/e2e.sh` builds
 both, starts them with `docker compose`, runs `tests/e2e` in the host
@@ -164,6 +178,43 @@ does). A cleanup that fails counts as a failed step. Results go to
 screen; it exits 0 when every step passed, 1 if one failed, 2 if the headset
 isn't reachable.
 
+Smoke process cleanup runs before and after title removal and during the
+initial/final leftover sweeps. It targets only the reserved `fc_smoke_arm64`,
+`fc_smoke_x86_64`, `fc_smoke_exe` IDs and their legacy `fc-smoke-` equivalents.
+On the target, `tests/smoke/stop_processes.py` requires the SSH user's uid and
+an exact title directory in `/proc` cwd/exe or an individual absolute command
+argument; similarly named folders and shell command substrings do not count.
+Deleted cwd/exe paths still count, so a process left after file removal can be
+found. It sends SIGTERM, waits up to three seconds, then uses SIGKILL with
+another three-second bound, rescanning for survivors. PID handles prevent PID
+reuse from signalling another process. Linux Python 3.9+ with pidfd support
+is required; missing support, signal errors and survivors fail the
+cleanup step. Stopped PIDs are recorded in the results JSON.
+If the initial leftover cleanup fails, the run skips installs and pairing and
+records the failure instead of overwriting an active test title.
+
+This deliberately does not stop shared Wine/Proton services by name or prefix,
+Steam, SteamVR, process groups or arbitrary descendants. A process that drops
+all title-path evidence cannot safely be attributed and is outside this
+check. Unreadable `/proc` fields provide no ownership evidence; other readable
+fields are still checked, and a wholly unattributable process is left alone.
+Real Frame verification, 2026-10-24, SteamOS build `20261015.6141207`: the
+fixed Python smoke entry point passed all 13 steps under the shared device lock.
+The `fc_smoke_exe` launch ran under Proton Experimental (ARM64), and its
+remove step stopped five test-owned wrapper/Proton PIDs before removing the
+title; the following process sweep found none. The final cleanup found no
+test titles or processes, the test desktop was closed, and the battery
+remained at 99%. The `scripts/frame-smoke.sh` zsh wrapper could not run
+on lxso2 because zsh is absent; `python3 tests/smoke/frame_smoke.py` ran
+the same entry point instead.
+The local regression suite runs real Linux processes in temporary fake title
+directories (including deleted folders and a TERM-resistant wrapper); it checks
+exit, escalation and survival of unrelated processes without SSH or a headset:
+
+```sh
+python3 -m unittest discover -s tests -p test_smoke_cleanup.py -v
+```
+
 `--pair` asks the devkit service to pair a new RSA key, which needs someone
 in the headset to open **Settings → Developer → Pair new host** and approve
 it; the key is checked and then taken out of `authorized_keys` again.
@@ -187,11 +238,36 @@ refuses ids with a hyphen (`missing/invalid arguments`), which the fake had
 accepted. The fake now refuses them the same way, and Frame Control makes ids
 Steam accepts.
 
+## PC panel host tests
+
+PC in the headset (Experimental, Windows only). `tests/test_pcview.py` checks
+that only Windows gets the PC host and that it starts nothing until turned on,
+the Tools link and card wording, source-bound tickets, reconnect/Stop
+revocation, input release, source-coordinate mapping and use of the existing
+panel launcher. `tests/test_pc_controller.py` checks the C rate controller
+against a frozen trace of the Mac's Swift one.
+
+The `PC host libraries` workflow builds the native adapter on Windows (and
+the unshipped Linux adapter on Ubuntu x64 and ARM64), then runs a real x264
+synthetic stream through the HTTP/WebSocket agent. x264 is GPL, so only these
+CI builds include it (`desktop/build.py --with-x264`); the release workflow
+tests the installer's own bundle with its bundled Python and checks x264 isn't
+in it. `FRAME_PC_REQUIRE_NATIVE=1` and `FRAME_PC_REQUIRE_X264=1` make a missing
+bundle or encoder fail CI instead of skipping.
+
+These automated CI checks do not capture a desktop, exercise Media Foundation
+or a GPU, or check laser alignment. A [Windows test VM](#windows-test-vm) run
+on 2026-10-24 captured its actual desktop with Desktop Duplication, encoded
+with Media Foundation and streamed to a real Frame. It found MSYS2 disables
+WGC: an element name alone does not prove its optional capture properties
+exist. Native property-probe tests and source-selection regressions now cover
+that boundary. [Dated evidence and limits](evidence/windows-vm-2026-10-24.md);
+[what's verified](pc-in-headset.md#whats-verified).
+
 ## Windows test VM
 
-The unit tests run on Windows in CI, but the app itself doesn't. Anything that
-depends on the Windows desktop (Remote Desktop, the installer, the bundled
-Python, file dialogs) needs a real Windows machine. This is a Windows 11 VM in a
+Windows CI runs the unit tests and checks installer contents. Desktop capture,
+installer launch and interactive behavior need a Windows machine. This is a Windows 11 VM in a
 [dockur/windows](https://github.com/dockur/windows) container on a Linux machine
 with KVM, driven from the Mac with `scripts/windows-vm.sh`.
 
@@ -211,7 +287,14 @@ Setting it up, once, on the Linux machine:
   `~/.ssh/id_ed25519_winvm` on the Mac) in
   `C:\ProgramData\ssh\administrators_authorized_keys`.
 - Give it 4 cores, 8 GB of memory and a 32 GB disk. That's enough for the app
-  and the tests.
+  and the tests. Inspect free memory/disk, KVM access and existing VMs before
+  starting; leave other VMs alone. The first install can take tens of minutes
+  (the 2026-10-24 run took about 16 minutes to reach the desktop), rather than
+  the 1–2 minute startup of an already installed guest.
+- For PC streaming, check the actual bundled capture properties. MSYS2's
+  GStreamer build disables WGC: this app falls back to Desktop Duplication for
+  whole screens and explains why individual windows are unavailable. A VM
+  capture test does not prove physical GPU encoding or laser alignment.
 
 Using it, with `WINVM_HOST` set to the Linux machine's ssh alias:
 
@@ -335,4 +418,37 @@ checksums, restore checks after a reset, restore writing only its own files,
 unsafe archives and backup names, and the exact Game Mode command.
 `tests/e2e/test_recovery_kit.py` backs up and restores a Proton save on the fake
 Frame through the server. See [backup-and-recovery.md](backup-and-recovery.md#verification).
-No backup or restore has been run on a real headset yet.
+A full backup and an identical-file Proton save restore were checked on a
+real Frame running build `20261015.6141207`; an after-reset restore and
+Android data restore remain unverified. See the linked device evidence.
+
+## Game storage
+
+`python3 -m unittest discover -s tests -p test_storage.py -v` exercises the
+read-only metadata probe, guarded HTTP endpoint and Node renderer/navigation
+regressions. All headset reads are temporary fixtures or mocked SSH. See
+[game storage](game-storage.md#verification-and-limits) for coverage and device
+verification limits. This suite does not move games or contact a headset.
+
+## Battery monitoring
+
+`tests/test_battery.py` covers real file parsing with temporary sysfs-like
+files, source preference, missing/invalid sensors and permission errors.
+`tests/control_center.cjs` covers charging states and optional health fields,
+alongside existing stale/offline handling. No headset is used. See
+[battery monitoring](battery-health.md) for sources, units and limitations.
+
+## Host-key recovery presentation
+
+`python3 -m unittest discover -s tests -p test_link_ui.py -v` runs the page's
+connection/banner/selection functions in Node and checks the recovery CSS guard.
+`test_link.py` covers connection failures and short probe reasons with fake SSH
+and local sockets. Neither suite uses a real headset.
+
+Browser verification on 2026-10-24 used the current page's markup, styles and
+recovery renderers with synthetic changed-key state and two headsets at
+1280×800. It caught a later `.item .s` rule overriding the earlier wrapping
+rule, which the original source-only assertion missed. Check computed wrapping,
+the complete explanation, tooltip punctuation, Refresh bounds and selection
+after **Use this headset** when changing these styles. This fixture does not
+exercise Electron integration or a real SSH identity change.

scripts/frame-doctor.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Read-only setup and health diagnostics; see docs/frame-doctor.md.
+set -euo pipefail
+root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)
+exec python3 "$root/scripts/frame_doctor.py" "$@"

scripts/frame_doctor.py

@@ -0,0 +1,279 @@
+"""Read-only doctor. Also sent over SSH on stdin; never installed on the Frame.
+
+Only fixed summaries leave the probe: no raw journals, addresses, account IDs,
+process arguments, environment, key material or HTTP response bodies.
+"""
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import socket
+import subprocess
+import sys
+import time
+
+SECTIONS = ('Boot and crash history', 'Wi-Fi', 'Displays and SteamVR',
+            'Steam and storage', 'Idle sleep and keep-awake', 'Remote wake',
+            'Lepton (Android)', 'Chromium XR', 'KDE Connect',
+            'Streaming and capture', 'Panels')
+
+
+def run(args, timeout=4, **kwargs):
+    try:
+        return subprocess.run(args, capture_output=True, text=True, timeout=timeout, **kwargs)
+    except (OSError, UnicodeError, subprocess.TimeoutExpired):
+        return None
+
+
+def command(*args):
+    r = run(list(args))
+    return r.stdout if r is not None and r.returncode == 0 else None
+
+
+def journal(*args):
+    # Even exit 0 can mean the account cannot see the system journal.
+    r = run(['journalctl', '--no-pager', '-q', '-n', '2000', *args])
+    if r is None or r.returncode or r.stderr.strip() or not r.stdout.strip():
+        return None
+    return r.stdout
+
+
+def snapshot():
+    values = []
+    for unit in ('steam', 'steamvr'):
+        s = command('systemctl', '--user', 'show', unit + '.service',
+                    '-p', 'NRestarts', '--value')
+        if s is None or not s.strip().isdigit():
+            return None
+        values.append(int(s.strip()))
+        p = Path('/run/user') / str(os.getuid()) / (unit + '-short-session-tracker')
+        try:
+            values.append(p.stat().st_size)
+        except FileNotFoundError:
+            values.append(0)
+        except OSError:
+            return None
+    return values
+
+
+def guard():
+    first = snapshot()
+    time.sleep(2)
+    second = snapshot()
+    if first is None or second is None:
+        return 'unknown'
+    if any(b > a for a, b in zip(first, second)):
+        return 'loop'
+    if first != second:
+        return 'unknown'  # counters reset or tracker replaced during the sample
+    if second[1] or second[3]:
+        return 'risk'  # avoid a long run even if a short sample missed the loop
+    return 'stable'
+
+
+def signal_check(text, pattern, problem, healthy):
+    if text is None:
+        return ['UNKNOWN', 'Evidence unavailable; consult the runbook locally.']
+    return ['WARN', problem] if re.search(pattern, text, re.I) else ['OK', healthy]
+
+
+def storage():
+    # devkit-game may be a separate mount (including in the fake Frame).
+    try:
+        paths = [Path.home()]
+        games = Path.home() / 'devkit-game'
+        if games.exists():
+            paths.append(games)
+        free = min(shutil.disk_usage(p).free for p in paths)
+        if free < 16 * 1024**2:
+            return ['BROKEN', 'Less than 16 MiB free; review storage in Frame Control before installing.']
+        if free < 256 * 1024**2:
+            return ['WARN', 'Less than 256 MiB free; review storage before large installs.']
+        return ['OK', 'Home and title storage have at least 256 MiB free.']
+    except OSError:
+        return ['UNKNOWN', 'Storage could not be read.']
+
+
+def probe():
+    state = guard()
+    if state != 'stable':
+        return {'guard': state, 'checks': []}
+    kernel = journal('-b', '-k', '--since=-10min')
+    recent = journal('-b', '--since=-10min')
+    previous = journal('-b', '-1', '-k')
+    crashes = command('coredumpctl', 'list', '--no-pager', '--since=-1d')
+    checks = []
+    boot = signal_check(previous, r'Unable to handle kernel|Internal error|Kernel panic',
+                        'Previous boot has a kernel oops; this alone does not prove an unclean reset.',
+                        'No kernel-oops signature in the sampled previous boot.')
+    if crashes is None and boot[0] != 'WARN':
+        boot = ['UNKNOWN', 'Crash history unavailable; inspect boot history locally.']
+    elif crashes is not None and boot[0] != 'WARN' and re.search(r'SIG(SEGV|ABRT)|\b(SEGV|ABRT)\b', crashes):
+        boot = ['WARN', 'Crash records exist in the last day; inspect locally using the runbook.']
+    checks.append(boot)
+    wifi = command('nmcli', '-t', '-f', 'DEVICE,TYPE,STATE', 'device')
+    checks.append(signal_check(wifi if wifi and 'wlan0:wifi:' in wifi else None, r'wlan0:wifi:(unavailable|disconnected|failed)',
+                               'Wi-Fi is unavailable or disconnected; check Steam Settings > Internet. Never reload ath12k.',
+                               'No unavailable/disconnected wlan0 reported; other interfaces may differ.'))
+    checks.append(signal_check(kernel, r'wait for video done',
+                               'Display timeouts observed; follow display recovery before touching Steam.',
+                               'No display-timeout signature in recent kernel sample.'))
+    if checks[-1][0] != 'WARN' and recent is not None and re.search(r'left-over process|steamvr.service: Failed|!modifiers.empty', recent):
+        checks[-1] = ['WARN', 'SteamVR/session failure signature observed; inspect locally before restarting anything.']
+    disk = storage()
+    if disk[0] == 'OK' and not (Path.home() / '.local/share/Steam/.install-complete').exists():
+        disk = ['WARN', 'Steam install marker is missing; do not restart Steam for diagnosis. Consult the runbook.']
+    checks.append(disk)
+    awake = command('systemctl', '--user', 'show', 'fc-keep-awake.service', '-p', 'ActiveState', '--value')
+    checks.append(['UNKNOWN', 'Keep-awake state unavailable.'] if awake is None or not awake.strip() else
+                  ['WARN', 'Keep-awake is active; leave it with its owner.'] if awake.strip() == 'active' else
+                  ['OK', 'Keep-awake is inactive; diagnostics do not inhibit sleep.'])
+    wow = command('iw', 'phy', 'phy0', 'wowlan', 'show')
+    checks.append(['UNKNOWN', 'WoWLAN state unavailable; remote wake is not verified.'] if wow is None else
+                  ['OK', 'WoWLAN is disabled; wake the headset with its power button.'] if 'WoWLAN is disabled' in wow else
+                  ['WARN', 'WoWLAN may be armed; review the runbook. Remote wake is not reliable.'])
+    checks.append(signal_check(recent, r'Listen failed for HOST TCP|binder_user_error|Clearing baked app data',
+                               'Android failure signature observed; inspect Lepton locally before retrying.',
+                               'No known Android failure signature in recent journal sample.'))
+    checks.append(signal_check(crashes, r'chromium|/chrome\b',
+                               'Chromium crash history found; update/relaunch the panel through its normal UI.',
+                               'No Chromium crash signature in available crash history.'))
+    kde = run(['pgrep', '-f', 'frame-control/kdeconnect/root/usr/lib/kdeconnectd'])
+    checks.append(['UNKNOWN', 'KDE Connect process check unavailable.'] if kde is None or kde.returncode not in (0, 1) else
+                  ['OK', 'KDE Connect process found.'] if kde.returncode == 0 else
+                  ['WARN', 'KDE Connect is not running; normal if keyboard/trackpad sharing is off.'])
+    checks.append(signal_check(crashes, r'ffmpeg',
+                               'Capture crash history found; consult software-encoder guidance in the runbook.',
+                               'No ffmpeg crash signature in available crash history.'))
+    checks.append(['UNKNOWN', 'Panel placement needs visual confirmation; open one panel at a time.'])
+    # A short sample is not proof that Steam is healthy. Recheck after collecting.
+    after = guard()
+    return {'guard': after, 'checks': checks if after == 'stable' else []}
+
+
+SSH_OPTIONS = ['BatchMode=yes', 'NumberOfPasswordPrompts=0', 'StrictHostKeyChecking=yes',
+               'UpdateHostKeys=no', 'CheckHostIP=no', 'ConnectTimeout=3', 'ConnectionAttempts=1',
+               'ControlMaster=no', 'ControlPath=none', 'ClearAllForwardings=yes',
+               'PermitLocalCommand=no', 'RemoteCommand=none', 'RequestTTY=no',
+               'ProxyCommand=none', 'ProxyJump=none', 'ForwardAgent=no', 'ForwardX11=no']
+
+
+def ssh_args(alias, host=None, identity=None):
+    args = ['ssh']
+    for opt in SSH_OPTIONS:
+        args += ['-o', opt]
+    if host:
+        args += ['-o', 'HostName=' + host, '-o', 'HostKeyAlias=' + identity]
+    return args + [alias]
+
+
+def failure(text):
+    # Never echo SSH stderr: it can contain addresses, paths or remote text.
+    if 'REMOTE HOST IDENTIFICATION HAS CHANGED' in text:
+        return 'SSH identity changed; use Devices > Check its key after verifying the headset. Do not delete known_hosts.'
+    if 'Host key verification failed' in text:
+        return 'SSH identity is untrusted; verify it through Set Up Connection or Devices > Check its key.'
+    if 'Permission denied' in text:
+        return "SSH key rejected; use Set Up Connection, then Developer > Pair new host in the headset."
+    return 'No SSH response; wake the headset, check the network/cable and enable Developer Mode.'
+
+
+def port_open(host, port):
+    try:
+        with socket.create_connection((host, port), timeout=2):
+            return True
+    except OSError:
+        return False
+
+
+def report(data):
+    state = data.get('guard')
+    if state != 'stable':
+        status = 'BROKEN' if state == 'loop' else 'WARN' if state == 'risk' else 'UNKNOWN'
+        message = {'loop': 'Counters are rising. Stop diagnostics; use the runbook health-check recovery procedure.',
+                   'risk': 'Health-check trackers contain failures. Deeper checks skipped; review the runbook before recovery.'}
+        print(status + ' Restart safety: ' + message.get(state, 'Cannot verify restart counters; deeper checks skipped for safety.'))
+        for i, label in enumerate(SECTIONS, 1):
+            print(f'UNKNOWN {i}. {label}: Skipped until restart safety is verified.')
+        return 1
+    checks = data.get('checks')
+    # Treat the remote endpoint as untrusted. Only accept pairs from our own
+    # fixed vocabulary by matching against the production probe's messages.
+    if not isinstance(checks, list) or len(checks) != len(SECTIONS):
+        print('UNKNOWN Probe: Incomplete diagnostic response; no raw output displayed.')
+        return 1
+    for check in checks:
+        if (not isinstance(check, list) or len(check) != 2 or check[0] not in ('OK', 'WARN', 'BROKEN', 'UNKNOWN')
+                or not isinstance(check[1], str) or check[1] not in MESSAGES):
+            print('UNKNOWN Probe: Unexpected diagnostic response; no raw output displayed.')
+            return 1
+    print('OK Restart safety: No rising counters during short samples; this is not a health guarantee.')
+    for i, (label, (status, message)) in enumerate(zip(SECTIONS, checks), 1):
+        print(f'{status} {i}. {label}: {message}')
+    return int(any(c[0] != 'OK' for c in checks))
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description='Read-only Frame setup diagnostics. Never pairs, repairs or asks for a password.')
+    parser.add_argument('--alias', default='frame', help='Existing trusted SSH alias (default: frame)')
+    parser.add_argument('--lan', default='frame.local', help='LAN fallback host/IP')
+    parser.add_argument('--usb', default='10.86.200.233', help='USB fallback IP; use only with the intended headset connected')
+    args = parser.parse_args(argv)
+    for value in (args.alias, args.lan, args.usb):
+        if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,252}', value):
+            parser.error('Use a plain alias, hostname or IP address.')
+    print('Frame doctor: read-only; no passwords, pairing, repairs or raw logs. No report is saved.')
+    if not shutil.which('ssh'):
+        print('BROKEN Setup: Install an OpenSSH client, then run Set Up Connection.')
+        return 2
+    config = run(ssh_args(args.alias)[:-1] + ['-G', args.alias])
+    if config is None or config.returncode:
+        print('UNKNOWN Setup: SSH configuration could not be read; check it locally.')
+        return 2
+    settings = dict(line.split(' ', 1) for line in config.stdout.splitlines() if ' ' in line)
+    identity = settings.get('hostkeyalias') or settings.get('hostname', args.alias)
+    source = Path(__file__).read_text()
+    for label, host in (('configured alias (Tailscale if configured)', None), ('LAN', args.lan), ('USB-C', args.usb)):
+        result = run(ssh_args(args.alias, host, identity) + ['python3 -B - --probe'], timeout=90, input=source)
+        if result is not None and result.returncode == 0:
+            try:
+                data = json.loads(result.stdout)
+                if not isinstance(data, dict):
+                    raise ValueError()
+            except ValueError:
+                print('UNKNOWN Probe: Invalid response; check Python 3 availability on the headset. No raw output displayed.')
+                return 1
+            print('OK Connection: ' + label + '; verified SSH identity and key login.')
+            return report(data)
+        if result is not None and result.returncode != 255:
+            print('UNKNOWN Probe: SSH connected but diagnostics failed; check Python 3 on the headset.')
+            return 1
+        reason = failure(result.stderr if result is not None else '')
+        print('WARN Connection (' + label + '): ' + reason)
+    # No /register call: an open devkit port cannot prove pairing mode is enabled.
+    hosts = (settings.get('hostname', args.alias), args.lan, args.usb)
+    if any(port_open(host, 32000) for host in hosts):
+        print('WARN Pairing: Devkit port responds. Use Set Up Connection and Developer > Pair new host; no pairing request was sent.')
+    else:
+        print('UNKNOWN Pairing: Devkit port did not respond. Needs your hands: wake headset, enable Developer Mode and check its address.')
+    for i, label in enumerate(SECTIONS, 1):
+        print(f'UNKNOWN {i}. {label}: No authenticated SSH path.')
+    return 2
+
+
+# Derive the output allowlist from literal strings, not remote data. This module
+# has no dynamic diagnostic messages. AST stays stdlib and runs only locally.
+def messages():
+    import ast
+    tree = ast.parse(Path(__file__).read_text())
+    return {node.value for node in ast.walk(tree) if isinstance(node, ast.Constant) and isinstance(node.value, str)}
+
+
+if __name__ == '__main__':
+    if sys.argv[1:] == ['--probe']:
+        print(json.dumps(probe()))
+    else:
+        MESSAGES = messages()
+        sys.exit(main())

scripts/macview-bench.py

@@ -55,6 +55,7 @@ from urllib.parse import quote, urlencode  # %20, not +: the agent's URLComponen
 ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(ROOT / "ui"))
 import frame_macview  # noqa: E402
+import frame_pcview  # noqa: E402
 
 RESULTS = ROOT / "bench" / "results"
 PAGES = ROOT / "bench" / "pages"
@@ -254,7 +255,10 @@ class LabView(frame_macview.MacView):
 
 def ssh_runner(base):
     def run(remote, stdin=None, timeout=30):
-        r = subprocess.run([*base, remote], input=stdin, capture_output=True, text=True, timeout=timeout)
+        r = subprocess.run([*base, remote], input=stdin.encode("utf-8") if stdin is not None else None,
+                           capture_output=True, timeout=timeout)
+        r.stdout = r.stdout.decode("utf-8", errors="replace")
+        r.stderr = r.stderr.decode("utf-8", errors="replace")
         if r.returncode:
             e = RuntimeError((r.stderr or r.stdout).strip())
             e.stdout = r.stdout
@@ -381,7 +385,11 @@ def run_scenario(args, scenario, agent_port, token, frame_ssh):
     if args.browser_flag is not None:
         mv.browser_flags = [f for f in args.browser_flag if f]
     chrome = None
-    src = "test"
+    src = args.source or "test"
+    cpu = None
+    if args.pc:
+        mv.host = "windows" if sys.platform == "win32" else "linux"
+        mv.viewer_profile = "pc-view"
     try:
         if scenario in ("scroll", "type"):
             chrome = chrome_window(f"{scenario}.html")
@@ -405,9 +413,10 @@ def run_scenario(args, scenario, agent_port, token, frame_ssh):
         since = max([f["s"] for f in first["frames"]] or [0])
         captured_before = first["captured"]
         start_mac_us = mv.call("/stats", id=stream["id"])["now"]
-        agent_pid = int(subprocess.run(["pgrep", "-f", "Frame Mac View Lab.app/Contents/MacOS/frame-mac-view"],
-                                       capture_output=True, text=True).stdout.split()[0])
-        cpu = CpuSampler(frame_ssh, agent_pid)
+        if not args.pc:
+            agent_pid = int(subprocess.run(["pgrep", "-f", "Frame Mac View Lab.app/Contents/MacOS/frame-mac-view"],
+                                           capture_output=True, text=True).stdout.split()[0])
+            cpu = CpuSampler(frame_ssh, agent_pid)
         if relay:
             relay.begin()
         expected = 0  # input events the harness asked the viewer for
@@ -443,7 +452,8 @@ def run_scenario(args, scenario, agent_port, token, frame_ssh):
         if not streams:
             raise SystemExit(f"{scenario}: the stream ended during the run (did the Frame go to sleep?)")
         data = streams[0]
-        cpu.stop()
+        if cpu:
+            cpu.stop()
         if args.raw:
             Path(f"{args.raw}-{scenario}.json").write_text(json.dumps(data))
         result = summarize(scenario, data, start_mac_us, end_mac_us, args, relay, schedule, expected)
@@ -452,7 +462,7 @@ def run_scenario(args, scenario, agent_port, token, frame_ssh):
                             for e in data.get("events", []) if e["t"] >= start_mac_us]
         result["captured"] = (captured_end if captured_end is not None else data["captured"]) - captured_before
         result["source_fps"] = round(result["captured"] / max(result["duration_s"], 1), 1)
-        result["cpu"] = cpu.summary()
+        result["cpu"] = cpu.summary() if cpu else {"host": "not sampled"}
         result["viewer"] = data["summary"].get("decoder", "")
         result["show_s"] = show_s
         result["panel"] = shown.get("panel")
@@ -460,6 +470,8 @@ def run_scenario(args, scenario, agent_port, token, frame_ssh):
         result["route"] = mv.route
         return result
     finally:
+        if cpu:
+            cpu.stop()
         try:
             mv.stop(src)
         except Exception:  # noqa: BLE001 - best effort
@@ -670,6 +682,8 @@ def fmt(v):
 
 def add_run_args(r):
     r.add_argument("--scenario", default="test,scroll,type")
+    r.add_argument("--pc", action="store_true", help="run the bundled PC host; use --scenario test or capture")
+    r.add_argument("--source", default="", help="PC source: window:ID, display:ID, or choose (Linux portal)")
     r.add_argument("--duration", type=float, default=20)
     r.add_argument("--warmup", type=float, default=3)
     r.add_argument("--quality", default="balanced", choices=list(frame_macview.QUALITY))
@@ -717,7 +731,7 @@ def frame_ssh_for(args):
 
 
 def run_suite(args, frame_ssh, quiet=False):
-    agent_port, token = lab_agent()
+    agent_port, token = (args.pc_view.port, args.pc_view.token) if args.pc else lab_agent()
     results = []
     for sc in args.scenario.split(","):
         if not quiet:
@@ -744,11 +758,12 @@ def document(args, frame_ssh, results, **extra):
     commit = git("rev-parse", "--short", "HEAD") + ("+dirty" if git("status", "--porcelain", "--", "mac", "ui") else "")
     return {
         "label": args.label or args.cmd, "date": datetime.datetime.now().isoformat(timespec="seconds"), "commit": commit,
-        "config": {"quality": args.quality, "mode": args.mode, "net": args.net or "none", "delay_ms": args.delay,
+        "config": {"quality": args.quality, "mode": "native" if args.pc else args.mode, "net": args.net or "none", "delay_ms": args.delay,
                    "buffer_ms": args.buffer, "host": args.host or args.frame, "usb": args.usb, "ssh_opts": args.ssh_opt,
                    "encoder": os.environ.get("FRAME_MAC_VIEW_ENCODER", ""), "duration_s": args.duration,
                    "browser_flags": args.browser_flag if args.browser_flag is not None else frame_macview.BROWSER_FLAGS},
-        "frame_build": build.strip().partition("=")[2], "mac": platform.mac_ver()[0], "headset": standby[-40:],
+        "frame_build": build.strip().partition("=")[2], "mac": platform.mac_ver()[0],
+        "host_platform": platform.platform(), "source": args.source, "pc_host": args.pc, "headset": standby[-40:],
         "scenarios": results, **extra,
     }
 
@@ -819,19 +834,46 @@ def main():
             print("\nworse:\n  " + "\n  ".join(regs))
         sys.exit(1 if regs else 0)
 
-    lab_agent()
+    if args.pc and (args.cmd == "ab" or args.scenario not in ("test", "capture")):
+        p.error("PC runs use --scenario test or --scenario capture; Mac automation is not portable")
+    if args.pc and args.scenario == "capture" and not args.source:
+        p.error("capture needs --source window:ID, display:ID, or choose")
+    if not args.pc:
+        lab_agent()
     frame_ssh = frame_ssh_for(args)
     # Keep the Mac's screen awake: virtual displays aren't removed while it sleeps.
     runs = 1 if args.cmd == "run" else args.repeat * len(args.arm)
-    awake = subprocess.Popen(["caffeinate", "-d", "-u", "-t", str(int(runs * (args.duration * 4 + 60) + 120))])
+    awake = subprocess.Popen(["caffeinate", "-d", "-u", "-t", str(int(runs * (args.duration * 4 + 60) + 120))]) if sys.platform == "darwin" else None
+    args.pc_view = None
     try:
+        if args.pc:
+            args.pc_view = frame_pcview.PCView(frame_ssh[:-1], ssh_runner(frame_ssh), frame_ssh[-1])
+            args.pc_view.ensure_agent()
+            if args.source == "choose":
+                args.pc_view.call("/permissions", method="POST")
+                print("Choose a window or screen in your desktop's sharing dialog.", flush=True)
+                deadline = time.monotonic()+125
+                while time.monotonic() < deadline:
+                    state = args.pc_view.call("/status")
+                    if not state.get("selecting"):
+                        sources = args.pc_view.call("/windows")["windows"]
+                        if not sources:
+                            raise SystemExit(state.get("selectionError") or "Nothing was shared")
+                        args.source = sources[-1]["src"]
+                        break
+                    time.sleep(.5)
+                else:
+                    raise SystemExit("Sharing dialog timed out")
         if args.cmd == "ab":
             arm_runs, table = ab(args, frame_ssh)
             write(document(args, frame_ssh, [], arms=args.arm, runs=arm_runs, table=table), args)
             return
         results = run_suite(args, frame_ssh)
     finally:
-        awake.terminate()
+        if args.pc_view:
+            args.pc_view.shutdown()
+        if awake:
+            awake.terminate()
     doc = document(args, frame_ssh, results)
     write(doc, args)
     bad = [f"{r['scenario']} {k}" for r in results for k, v in r["grades"].items() if v in ("bad", "missing")]

tests/control_center.cjs

@@ -165,6 +165,50 @@ test('metrics use real fields, preserve zero, and distinguish unavailable values
   assert.equal(cc.metrics({battery:{percent:0,status:'Discharging'}}).battery,'0%');
   assert.match(cc.metrics({thermalAlerts:[{zone:'battery',tempC:45,limitC:44}]}).thermal,/battery 45 °C ≥ 44 °C/);
 });
+test('battery health distinguishes charging states and optional sensors', () => {
+  for (const status of [null, 'Unknown', 'Unexpected']) {
+    const m = cc.metrics({battery:{percent:100,status,timeToEmpty:3600}});
+    assert.equal(m.batteryDetail,'Charging state unavailable');
+    assert.equal(m.estimate,'Unavailable');
+  }
+  assert.equal(cc.metrics({battery:{status:'Not charging'}}).batteryDetail,'Not charging');
+  assert.equal(cc.metrics({battery:{status:'Full'}}).batteryDetail,'Fully charged');
+  assert.equal(cc.metrics({battery:{status:'Charging',timeToFull:3600}}).estimate,'1 h 0 min to full');
+  assert.equal(cc.metrics({battery:{status:'Discharging',timeToEmpty:600}}).estimate,'10 min remaining');
+  const m = cc.metrics({battery:{cycleCount:0,fullMah:4500,designMah:5000,capacityHealthPercent:90,
+    source:'/sys/class/power_supply/max1720x_bat_7-36',health:'Unknown',tempC:0}});
+  assert.equal(m.cycles,'0'); assert.equal(m.capacityHealth,'90%');
+  assert.equal(m.fullCapacity,'4,500 mAh'); assert.equal(m.batteryTemp,'0 °C');
+  assert.equal(m.batteryHealth,'Unavailable'); assert.match(m.batterySource,/max1720x/);
+  for (const key of ['cycles','fullCapacity','designCapacity','capacityHealth','batterySource','batteryHealth','batteryTemp'])
+    assert.equal(cc.metrics(null)[key],'Unavailable');
+});
+test('battery chip preserves unknown status and does not infer Full at 100%', () => {
+  const f=fixture();
+  const start=pageSource.indexOf('function battery(b, power)');
+  const end=pageSource.indexOf('// hidePopover', start);
+  const context={$:f.element,dur:String}; vm.createContext(context);
+  vm.runInContext(pageSource.slice(start,end),context);
+  context.battery({percent:100,status:'Unknown'},{watts:20});
+  assert.equal(f.element('battState').textContent,'Charging state unavailable');
+  context.battery({percent:50,status:'Not charging'},null);
+  assert.equal(f.element('battState').textContent,'Not charging');
+  context.battery({percent:50,status:'Charging',watts:2,tempC:0},null);
+  assert.match(f.element('battState').textContent,/Charging/);
+  assert.match(f.element('battDetail').textContent,/battery 0°C/);
+  context.battery(null,null);
+  assert.equal(f.element('battState').textContent,'Battery unknown');
+});
+test('new health readings clear after a failed status read', () => {
+  const f=mounted();
+  f.ui.status({...sample(),battery:{...sample().battery,cycleCount:42,capacityHealthPercent:92,
+    fullMah:4600,designMah:5000,source:'/sys/class/power_supply/max1720x_bat_7-36'}});
+  assert.equal(f.element('metric-capacityHealth').textContent,'92%');
+  f.ui.unavailable(Error('Read failed'));
+  for (const key of ['cycles','fullCapacity','designCapacity','capacityHealth','batterySource'])
+    assert.equal(f.element('metric-'+key).textContent,'Unavailable');
+  f.ui.destroy();
+});
 test('audio controller validates before any API call and rejects offline or expired readings', async () => {
   let context={online:true,fresh:true,sample:sample(),device:'frame-a',generation:1},calls=[];
   const controller=cc.createController({api:async(...args)=>{calls.push(args);return {};},getContext:()=>context});

tests/e2e/test_doctor.py

@@ -0,0 +1,43 @@
+"""Real doctor/SSH against fake-Frame faults; never a real headset."""
+import subprocess
+import sys
+
+import harness
+from harness import ROOT, ctl
+
+harness.require()
+
+
+class Doctor(harness.FrameTestCase):
+    def doctor(self):
+        return subprocess.run([sys.executable, str(ROOT / 'scripts/frame_doctor.py'),
+                               '--lan', harness.FAKE_HOST, '--usb', harness.FAKE_HOST],
+                              capture_output=True, text=True, timeout=120)
+
+    def test_disk_full(self):
+        before = self.doctor()
+        self.assertNotIn('BROKEN 4. Steam and storage', before.stdout)
+        ctl('disk-full', 'on')
+        r = self.doctor()
+        self.assertEqual(r.returncode, 1, r.stdout + r.stderr)
+        self.assertIn('BROKEN 4. Steam and storage: Less than 16 MiB free', r.stdout)
+
+    def test_unreachable_asleep(self):
+        ctl('sleep', 'on')
+        r = self.doctor()
+        self.assertEqual(r.returncode, 2, r.stdout + r.stderr)
+        self.assertIn('No authenticated SSH path', r.stdout)
+
+    def test_no_ssh_and_no_devkit(self):
+        ctl('sshd', 'off')
+        ctl('devkit-service', 'off')
+        r = self.doctor()
+        self.assertEqual(r.returncode, 2, r.stdout + r.stderr)
+        self.assertIn('Devkit port did not respond', r.stdout)
+
+    def test_no_keys_but_devkit_available(self):
+        ctl('keys', 'none')
+        r = self.doctor()
+        self.assertEqual(r.returncode, 2, r.stdout + r.stderr)
+        self.assertIn('SSH key rejected', r.stdout)
+        self.assertIn('no pairing request was sent', r.stdout)

tests/fakeframe/rootfs/usr/local/bin/systemctl

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+"""Doctor's read-only systemd queries in a container without a user manager.
+
+Stable NRestarts=0 and inactive keep-awake are harness assumptions, not observed
+device behavior. Real Frame query forms come from the historical doctor runbook
+(2026-09-28, BUILD_ID 20260925.6191901). No service control is emulated here.
+"""
+import sys
+
+args = sys.argv[1:]
+if args in (['--user', 'show', 'steam.service', '-p', 'NRestarts', '--value'],
+            ['--user', 'show', 'steamvr.service', '-p', 'NRestarts', '--value']):
+    print('0')
+elif args == ['--user', 'show', 'fc-keep-awake.service', '-p', 'ActiveState', '--value']:
+    print('inactive')
+else:
+    sys.exit(1)

tests/smoke/frame_smoke.py

@@ -13,11 +13,12 @@ BUILD_ID in tests/smoke/results/<time>-<BUILD_ID>.json (git-ignored):
   (someone has to open Settings > Developer > Pair new host and approve it in
   the headset), checked, and taken out of authorized_keys again.
 
-Everything it installs is removed again, also when a step fails: the titles
-(named fc_smoke_*, and leftovers of an interrupted run first), their Steam
+Everything it installs is removed again, also when a step fails: the reserved
+fc_smoke_{arm64,x86_64,exe} titles (and legacy leftovers first), their Steam
 shortcuts, the paired key, and ~/devkit-utils if it wasn't there before (if it
 was, it stays, synced to this checkout as Frame Control always does). A
-cleanup that fails is a failed step.
+cleanup that fails is a failed step. Test-owned processes are stopped and
+rechecked around deletion; shared Proton services are never stopped by name.
 
 Usage: python3 tests/smoke/frame_smoke.py [--pair]     (or scripts/frame-smoke.sh)
 Env:   FRAME_ALIAS (default frame), FRAME_SMOKE_RESULTS (default tests/smoke/results)
@@ -45,11 +46,17 @@ import frame_android  # noqa: E402
 import frame_connect  # noqa: E402
 import frame_titles  # noqa: E402
 import tiny_programs  # noqa: E402
+import stop_processes  # noqa: E402
 
 RESULTS = Path(os.environ.get('FRAME_SMOKE_RESULTS') or HERE / 'results')
 PREFIX = 'fc_smoke_'
-# Earlier runs named titles fc-smoke*, which Steam refused to register but left on disk.
-OLD_PREFIX = 'fc-smoke'
+
+
+def stop_titles(ids):
+    """Run the same bounded, PID-safe helper used by the local process tests."""
+    return json.loads(frame_android.ssh(
+        'python3 - ' + ' '.join(shlex.quote(gid) for gid in sorted(ids)),
+        input=(HERE / 'stop_processes.py').read_text(), timeout=20))
 
 
 class Smoke:
@@ -172,14 +179,17 @@ def title_cycle(smoke, kind, folder):
         return detail
 
     def remove():
+        stopped = stop_titles({gid})
         frame_titles.remove(gid)
+        # A wrapper could have launched a child just as deletion completed.
+        after = stop_titles({gid})
         left = ssh(f'ls -d ~/devkit-game/{gid} ~/devkit-game/{gid}-*.json 2>/dev/null || true').strip()
         if left:
             raise AssertionError(f'left behind: {left}')
         if gid in {t['id'] for t in frame_titles.list_titles()}:
             raise AssertionError(f'{gid} is still listed')
         smoke.installed.discard(gid)
-        return {'removed': gid}
+        return {'removed': gid, 'process_cleanup': [stopped, after]}
 
     if smoke.step(f'{kind}: install', install)['ok']:
         smoke.step(f'{kind}: launch', launch)
@@ -187,15 +197,21 @@ def title_cycle(smoke, kind, folder):
 
 
 def cleanup(smoke):
-    """Remove this run's titles and any fc_smoke_* an interrupted run left: the folder,
-    its json files, and (through steamos-delete) Steam's shortcut. Raises if anything stays."""
+    """Stop reserved smoke processes and remove their titles and shortcuts.
+
+    Legacy fc-smoke-* IDs are included; arbitrary similarly named titles are
+    never removed. Raises if any owned process, file or shortcut stays.
+    """
     problems = []
     try:
-        ids = {t['id'] for t in frame_titles.list_titles() if t['id'].startswith((PREFIX, OLD_PREFIX))}
+        ids = {t['id'] for t in frame_titles.list_titles() if t['id'] in stop_processes.IDS}
     except frame_android.FrameError as e:
         ids = set()
         problems.append(f'could not list titles: {e}')
     ids |= smoke.installed
+    # Scan every reserved ID, even when a prior run removed its folder and
+    # shortcut but left Proton running. Stop before removing any more files.
+    stopped = stop_titles(stop_processes.IDS)
     gone = set()
     for gid in sorted(ids):
         try:
@@ -226,9 +242,10 @@ def cleanup(smoke):
                     smoke.installed.discard(gid)
         except (frame_android.FrameError, AssertionError) as e:
             problems.append(f"syncing Steam's shortcuts: {e}")
+    after = stop_titles(stop_processes.IDS)
     if problems:
         raise AssertionError('; '.join(problems))
-    return {'removed': sorted(ids)}
+    return {'removed': sorted(ids), 'process_cleanup': [stopped, after]}
 
 
 # Runs on the Frame: drop the lines holding one key from authorized_keys, writing a
@@ -307,15 +324,17 @@ def main():
     # Frame Control copies Valve's devkit tools to ~/devkit-utils on the first install
     # (as Valve's client does). If they weren't there before, they go again at the end.
     had_utils = ssh('test -d ~/devkit-utils && echo yes || true').strip() == 'yes'
-    smoke.step('cleanup: leftovers from earlier runs', cleanup, smoke)
+    ready = smoke.step('cleanup: leftovers from earlier runs', cleanup, smoke)['ok']
     folder = tempfile.mkdtemp(prefix='frame-smoke-')
     try:
-        smoke.step('devkit service: properties.json', properties)
-        smoke.step('status', status, build)
-        for kind in ('arm64', 'x86_64', 'exe'):
-            title_cycle(smoke, kind, folder)
-        if args.pair:
-            smoke.step('devkit pairing (throwaway key)', pair, folder)
+        # Do not overwrite a leftover title when safe process cleanup failed.
+        if ready:
+            smoke.step('devkit service: properties.json', properties)
+            smoke.step('status', status, build)
+            for kind in ('arm64', 'x86_64', 'exe'):
+                title_cycle(smoke, kind, folder)
+            if args.pair:
+                smoke.step('devkit pairing (throwaway key)', pair, folder)
     finally:
         smoke.step('cleanup: everything this run installed', cleanup, smoke)
         if not had_utils:

tests/smoke/stop_processes.py

@@ -0,0 +1,91 @@
+"""Linux-only smoke cleanup helper, sent over SSH before deleting test files.
+
+Only exact, reserved smoke title directories establish ownership. Never signal
+by process name, process group, Steam app id, or a shared Wine/Proton prefix.
+"""
+import json
+import os
+from pathlib import Path
+import signal
+import sys
+import time
+
+IDS = frozenset(prefix + kind for prefix in ('fc_smoke_', 'fc-smoke-')
+                for kind in ('arm64', 'x86_64', 'exe'))
+
+
+def owned(pid, roots):
+    """Require our uid and an exact cwd/exe or individual absolute argv path.
+
+    /proc retains a deleted cwd/exe with ' (deleted)' appended. This also lets
+    the final sweep catch an older run whose title was already removed.
+    """
+    proc = Path('/proc') / str(pid)
+    try:
+        if pid == os.getpid() or proc.stat().st_uid != os.getuid():
+            return False
+        state = (proc / 'stat').read_text().rsplit(')', 1)[1].split()[0]
+        if state == 'Z':
+            return False
+        paths = []
+        for key in ('cwd', 'exe'):
+            try:
+                paths.append(os.readlink(proc / key).removesuffix(' (deleted)'))
+            except (FileNotFoundError, PermissionError):
+                pass
+        try:
+            paths += os.fsdecode((proc / 'cmdline').read_bytes()).split('\0')
+        except PermissionError:
+            pass
+        return any(path == root or path.startswith(root + '/')
+                   for path in paths for root in roots)
+    except (FileNotFoundError, ProcessLookupError, PermissionError):
+        return False
+
+
+def candidates(roots):
+    return sorted(int(p.name) for p in Path('/proc').iterdir()
+                  if p.name.isdigit() and owned(int(p.name), roots))
+
+
+def stop(ids, grace=3):
+    if not ids or not set(ids) <= IDS:
+        raise ValueError('only reserved smoke title IDs may be stopped')
+    if not hasattr(os, 'pidfd_open') or not hasattr(signal, 'pidfd_send_signal'):
+        raise RuntimeError('safe smoke cleanup requires Linux Python with pidfd support')
+    roots = [str(Path.home() / 'devkit-game' / gid) for gid in ids]
+    stopped = set()
+    for sig in (signal.SIGTERM, signal.SIGKILL):
+        # Re-scan while waiting: wrappers can spawn a child during shutdown.
+        deadline = time.monotonic() + grace
+        while True:
+            pids = candidates(roots)
+            if not pids:
+                return {'stopped_pids': sorted(stopped)}
+            for pid in pids:
+                try:
+                    fd = os.pidfd_open(pid)
+                except ProcessLookupError:
+                    continue
+                try:
+                    # Open first, then revalidate ownership. The handle cannot
+                    # signal an unrelated process if this numeric PID is reused.
+                    if owned(pid, roots):
+                        try:
+                            signal.pidfd_send_signal(fd, sig)
+                            stopped.add(pid)
+                        except ProcessLookupError:
+                            pass
+                finally:
+                    os.close(fd)
+            if time.monotonic() >= deadline:
+                break
+            time.sleep(0.1)
+    left = candidates(roots)
+    if left:
+        raise RuntimeError(f'smoke processes survived cleanup: {left}')
+    return {'stopped_pids': sorted(stopped)}
+
+
+if __name__ == '__main__':
+    print(json.dumps(stop(sys.argv[1:])))

tests/storage.cjs

@@ -0,0 +1,50 @@
+const {test}=require('node:test');
+const assert=require('node:assert/strict');
+const {workspaceFixture,html}=require('./workspace_fixture.cjs');
+function fixture() {
+  const f=workspaceFixture();
+  const start=html.indexOf('// ---- Read-only game storage ----');
+  f.run(html.slice(start,html.indexOf('// ---- Backup and recovery kit',start)));
+  const size=html.indexOf('function sizeText(');
+  f.run(html.slice(size,html.indexOf('const backupKinds',size)));
+  return f;
+}
+const sample={home:{state:'ok',total:1000,free:200,used:700},discovery:'permission-denied',libraries:[{
+  path:'<img onerror=alert(1)>',capacity:{state:'missing'},state:'partial',gameBytes:10,toolBytes:0,
+  recordedBytes:10,unknownSizes:1,issues:[{file:'bad.acf',state:'invalid-metadata'}],
+  apps:[{appid:'1',name:'<script>bad</script>',bytes:null,kind:'game'},{appid:'2',name:'Zero',bytes:0,kind:'game'}]}]};
+test('navigation reaches storage and refresh runs once per visit',()=>{
+  const f=fixture();let calls=0;f.context.loadStorage=()=>calls++;
+  f.navigate('#storage');assert.equal(f.activePage,'tools');assert.equal(f.el('storage').hidden,false);
+  assert.equal(f.el('storage').parentNode,f.el('toolWorkspace'));assert.equal(calls,1);
+});
+test('unknown, shared capacity, partial discovery and untrusted names remain explicit',()=>{
+  const f=fixture();f.context.sample=sample;const out=f.run('renderStorage(sample)');
+  assert.match(out,/Permission denied/);assert.match(out,/Missing or disconnected/);
+  assert.match(out,/Unknown/);assert.match(out,/0 bytes/);assert.match(out,/Partial inventory/);
+  assert.match(out,/must not be added/);assert.match(out,/Other usage is unmeasured/);
+  assert.match(out,/&lt;script&gt;/);assert.doesNotMatch(out,/<script>|<img/);
+});
+test('refresh clears old data, ignores earlier requests and shows offline failure',async()=>{
+  const f=fixture(),pending=[];
+  f.context.api=()=>new Promise((resolve,reject)=>pending.push({resolve,reject}));
+  f.el('storageResult').innerHTML='old data';
+  const first=f.run('loadStorage()'),second=f.run('loadStorage()');
+  assert.match(f.el('storageResult').textContent,/Reading/);
+  pending[1].resolve(sample);await second;
+  const current=f.el('storageResult').innerHTML;
+  pending[0].resolve({...sample,libraries:[]});await first;
+  assert.equal(f.el('storageResult').innerHTML,current);
+  const last=f.run('loadStorage()');pending[2].reject(new Error('Offline'));await last;
+  assert.match(f.el('storageResult').textContent,/Storage unavailable: Offline/);
+});
+test('a response or error from another headset cannot update the view',async()=>{
+  for(const fail of [false,true]) {
+    const f=fixture();let resolve,reject;
+    f.context.api=()=>new Promise((yes,no)=>{resolve=yes;reject=no;});
+    const request=f.run('loadStorage()');f.context.devGen++;
+    f.el('storageResult').textContent='New headset';
+    fail?reject(new Error('Old headset')):resolve(sample);await request;
+    assert.equal(f.el('storageResult').textContent,'New headset');assert.equal(f.el('storageResult').innerHTML,'');
+  }
+});

tests/test_battery.py

@@ -0,0 +1,86 @@
+"""Read-only sysfs battery parsing; fixture values, no real headset access."""
+import sandbox  # noqa: F401
+from pathlib import Path
+import sys
+import tempfile
+import unittest
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'ui'))
+import frame_status as status
+
+
+class Battery(unittest.TestCase):
+    def probe(self, fields):
+        # Real files exercise missing files, whitespace and integer conversion.
+        with tempfile.TemporaryDirectory() as tmp:
+            node = Path(tmp) / 'max1720x_bat_7-36'
+            node.mkdir()
+            for name, value in dict(type='Battery', **fields).items():
+                (node / name).write_text(str(value) + '\n')
+            with mock.patch.object(status.glob, 'glob', return_value=[str(node)]):
+                result = status.battery()
+            if result:
+                result.pop('source')
+            return result
+
+    def test_frame_units_and_optional_health(self):
+        b = self.probe(dict(capacity=73, status='Charging', voltage_now=3800000,
+                            current_now=1000000, temp=325, health='Good',
+                            charge_full=4600000, charge_full_design=5000000,
+                            cycle_count=42, time_to_full_now=3600))
+        self.assertEqual(b, dict(percent=73, status='Charging', watts=3.8,
+                                tempC=32.5, health='Good', timeToFull=3600,
+                                timeToEmpty=None, cycleCount=42, fullMah=4600,
+                                designMah=5000, capacityHealthPercent=92))
+
+    def test_zero_negative_current_and_temperature(self):
+        b = self.probe(dict(capacity=0, cycle_count=0, temp=-50,
+                            voltage_now=3800000, current_now=-1000000))
+        self.assertEqual((b['percent'], b['cycleCount'], b['tempC'], b['watts']),
+                         (0, 0, -5, -3.8))
+
+    def test_missing_optional_sensors_stay_null(self):
+        b = self.probe(dict(capacity=50, status='Discharging'))
+        self.assertEqual(b['percent'], 50)
+        self.assertTrue(all(value is None for key, value in b.items()
+                            if key not in ('percent', 'status')))
+
+    def test_invalid_values_do_not_break_other_readings(self):
+        for invalid in ('abc', '', '-1', '101', '12.5'):
+            b = self.probe(dict(capacity=invalid, status='Charging', temp='bad',
+                                charge_full=4500000, charge_full_design=0,
+                                time_to_full_now=-1, time_to_empty_now=4294967295,
+                                cycle_count=-1, voltage_now='bad', current_now=100))
+            self.assertIsNone(b['percent'])
+            for key in ('watts', 'tempC', 'capacityHealthPercent', 'timeToFull', 'timeToEmpty', 'cycleCount'):
+                self.assertIsNone(b[key], key)
+            self.assertEqual(b['status'], 'Charging')
+
+    def test_no_battery_and_unreadable_type(self):
+        with mock.patch.object(status.glob, 'glob', return_value=[]):
+            self.assertIsNone(status.battery())
+        with mock.patch.object(status.glob, 'glob', return_value=['/missing']), \
+                mock.patch('builtins.open', side_effect=PermissionError):
+            self.assertIsNone(status.battery())
+
+    def test_prefers_frame_and_excludes_peripheral_or_absent_batteries(self):
+        paths = ['/sys/class/power_supply/aaa', '/sys/class/power_supply/max1720x_bat_7-36']
+        def read(path):
+            return {'type': 'Battery', 'capacity': '80'}.get(path.rsplit('/', 1)[-1])
+        with mock.patch.object(status.glob, 'glob', return_value=paths), \
+                mock.patch.object(status, 'read', side_effect=read):
+            self.assertEqual(status.battery()['source'], paths[1])
+        self.assertIsNone(self.probe(dict(scope='Device', capacity=99)))
+        self.assertIsNone(self.probe(dict(present=0, capacity=99)))
+
+    def test_permission_failure_affects_only_one_sensor(self):
+        actual_open = open
+        def guarded(path, *args, **kwargs):
+            if str(path).endswith('/temp'):
+                raise PermissionError('unreadable')
+            return actual_open(path, *args, **kwargs)
+        with mock.patch('builtins.open', side_effect=guarded):
+            b = self.probe(dict(capacity=45, temp=300))
+        self.assertEqual(b['percent'], 45)
+        self.assertIsNone(b['tempC'])

tests/test_frame_doctor.py

@@ -0,0 +1,122 @@
+"""Doctor tests never contact a headset or the user's SSH configuration."""
+import importlib.util
+import io
+import json
+from pathlib import Path
+import subprocess
+import unittest
+from unittest.mock import patch, Mock
+
+ROOT = Path(__file__).resolve().parents[1]
+spec = importlib.util.spec_from_file_location('frame_doctor', ROOT / 'scripts/frame_doctor.py')
+doctor = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(doctor)
+doctor.MESSAGES = doctor.messages()
+
+
+def result(out='', code=0, err=''):
+    return subprocess.CompletedProcess([], code, out, err)
+
+
+class FrameDoctor(unittest.TestCase):
+    def main(self, responses, **kwargs):
+        config = result('hostname private-tailnet.ts.net\nhostkeyalias pinned-frame\n')
+        with patch.object(doctor.shutil, 'which', return_value='/usr/bin/ssh'), \
+                patch.object(doctor, 'run', side_effect=[config, *responses]) as run, \
+                patch.object(doctor, 'port_open', return_value=kwargs.get('devkit', False)), \
+                patch('sys.stdout', new_callable=io.StringIO) as output:
+            code = doctor.main([])
+        return code, output.getvalue(), run
+
+    def test_unreachable_is_actionable_without_exposing_stderr(self):
+        code, text, _ = self.main([result(code=255, err='secret-token 192.0.2.5')] * 3)
+        self.assertEqual(code, 2)
+        self.assertIn('wake headset', text)
+        self.assertEqual(text.count('No authenticated SSH path.'), 11)
+        self.assertNotIn('secret-token', text)
+        self.assertNotIn('192.0.2.5', text)
+        self.assertNotIn('private-tailnet', text)
+
+    def test_no_keys_and_devkit_available_never_registers(self):
+        code, text, run = self.main([result(code=255, err='Permission denied')] * 3, devkit=True)
+        self.assertEqual(code, 2)
+        self.assertIn('no pairing request was sent', text)
+        self.assertIn('Pair new host', text)
+        self.assertFalse(any('/register' in str(c.args[0]) for c in run.call_args_list))
+
+    def test_fallback_preserves_identity_and_disables_mutating_ssh_options(self):
+        _, text, run = self.main([result(code=255), result(json.dumps({'guard': 'loop', 'checks': []}))])
+        args = run.call_args_list[2].args[0]
+        for flag in ('HostKeyAlias=pinned-frame', 'HostName=frame.local', 'BatchMode=yes',
+                     'StrictHostKeyChecking=yes', 'UpdateHostKeys=no', 'PermitLocalCommand=no',
+                     'ClearAllForwardings=yes', 'ControlPath=none'):
+            self.assertIn(flag, args)
+        self.assertIn('OK Connection: LAN', text)
+        self.assertIn('Counters are rising', text)
+
+    def test_hostkey_failure_does_not_suggest_deleting_identity(self):
+        _, text, _ = self.main([result(code=255, err='REMOTE HOST IDENTIFICATION HAS CHANGED')] * 3)
+        self.assertIn('Do not delete known_hosts', text)
+
+    def test_invalid_probe_response_never_prints_remote_data(self):
+        for payload in ('a secret token', json.dumps({'guard': 'stable', 'checks': [['OK', 'secret']] * 11})):
+            code, text, _ = self.main([result(payload)])
+            self.assertEqual(code, 1)
+            self.assertNotIn('secret', text)
+
+    def test_guard_stops_before_any_deeper_checks(self):
+        for state in ('loop', 'unknown', 'risk'):
+            with patch.object(doctor, 'guard', return_value=state), patch.object(doctor, 'journal') as journal:
+                self.assertEqual(doctor.probe(), {'guard': state, 'checks': []})
+                journal.assert_not_called()
+
+    def test_rising_and_reset_counters_and_missing_data(self):
+        for snapshots, expected in (([[0, 0, 0, 0], [1, 0, 0, 0]], 'loop'),
+                                    ([[1, 0, 0, 0], [0, 0, 0, 0]], 'unknown'),
+                                    ([None, None], 'unknown'),
+                                    ([[0, 4, 0, 0]] * 2, 'risk'),
+                                    ([[0, 0, 0, 0]] * 2, 'stable')):
+            with patch.object(doctor, 'snapshot', side_effect=snapshots), patch.object(doctor.time, 'sleep'):
+                self.assertEqual(doctor.guard(), expected)
+
+    def test_journal_permission_denied_and_empty_are_unknown(self):
+        for response in (result('partial', err='not seeing messages from other users'), result(), result(code=1)):
+            with patch.object(doctor, 'run', return_value=response):
+                self.assertIsNone(doctor.journal('-b'))
+        self.assertEqual(doctor.signal_check(None, 'bad', 'problem', 'healthy')[0], 'UNKNOWN')
+
+    def test_disk_full_reports_broken_and_never_fixes(self):
+        with patch.object(doctor.shutil, 'disk_usage', return_value=Mock(free=0)):
+            check = doctor.storage()
+        with patch('sys.stdout', new_callable=io.StringIO) as output:
+            code = doctor.report({'guard': 'stable', 'checks': [check] * 11})
+        self.assertEqual(code, 1)
+        self.assertIn('BROKEN 4. Steam and storage', output.getvalue())
+
+    def test_probe_only_emits_approved_messages_and_rechecks_guard(self):
+        with patch.object(doctor, 'guard', side_effect=['stable', 'stable']) as guard, \
+                patch.object(doctor, 'journal', return_value=None), \
+                patch.object(doctor, 'command', return_value=None), \
+                patch.object(doctor, 'run', return_value=None), \
+                patch.object(doctor, 'storage', return_value=['UNKNOWN', 'Storage could not be read.']):
+            data = doctor.probe()
+        self.assertEqual(guard.call_count, 2)
+        self.assertEqual(len(data['checks']), 11)
+        with patch('sys.stdout', new_callable=io.StringIO):
+            self.assertEqual(doctor.report(data), 1)
+
+    def test_help_shell_entry_point_is_offline(self):
+        # This Bash wrapper is for macOS/Linux; Windows uses the Python CLI.
+        import os, shutil
+        if os.name == 'nt':
+            self.skipTest('POSIX shell wrapper')
+        if not shutil.which('bash'):
+            self.skipTest('bash unavailable')
+        r = subprocess.run(['bash', str(ROOT / 'scripts/frame-doctor.sh'), '--help'],
+                           capture_output=True, text=True, timeout=5)
+        self.assertEqual(r.returncode, 0, r.stderr)
+        self.assertIn('Never pairs', r.stdout)
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_link_ui.py

@@ -64,6 +64,7 @@ class LinkUI(unittest.TestCase):
   renderPill();
   assert.match($('conn').innerHTML, /<b>Office Frame<\/b><span>Offline<span class="via"> · retrying in 12 s<\/span>/);
   assert.ok($('conn').title.includes(changed.error.message));
+  assert.ok(!$('conn').title.includes('..'), $('conn').title);
   // Without a short reason: the stage that failed.
   link.s = {...changed, retry_at: null, error: {stage: 'identity', message: 'Something.'}};
   renderPill();
@@ -120,7 +121,9 @@ class LinkUI(unittest.TestCase):
 class HeaderLayout(unittest.TestCase):
     def test_the_devices_tab_explanation_wraps(self):
         # It was cut to one line with no way to read the rest.
-        self.assertIn(".dev-problem .s { white-space: normal; }", PAGE)
+        # More specific than the later .item .s rule: the old equal-specificity
+        # rule passed this test while the browser still clipped the explanation.
+        self.assertIn(".item.dev-problem .s { white-space: normal; overflow-wrap: anywhere; }", PAGE)
         self.assertEqual(len(re.findall(r'<div class="item dev-problem" role="alert">', PAGE)), 2)
 
     def test_the_header_buttons_dont_give_way(self):

tests/test_macview.py

@@ -84,7 +84,10 @@ class Helpers(unittest.TestCase):
     @unittest.skipUnless(shutil.which("bash"), "needs bash")
     @unittest.skipIf(os.name == "nt", "Windows' bash.exe is WSL's launcher, and runners have no distribution")
     def test_launch_script_parses(self):
-        r = subprocess.run(["bash", "-n"], input=frame_macview.LAUNCH, text=True, capture_output=True)
+        bash = str(Path(os.environ.get("ProgramFiles", "C:/Program Files")) / "Git/bin/bash.exe") if sys.platform == "win32" else "bash"
+        if sys.platform == "win32" and not Path(bash).exists():
+            self.skipTest("Git Bash is not installed (WSL bash is not a local shell)")
+        r = subprocess.run([bash, "-n"], input=frame_macview.LAUNCH.encode("utf-8"), capture_output=True)
         self.assertEqual(r.returncode, 0, r.stderr)
 
     def test_show_checks_the_source_before_anything_else(self):

tests/test_page_startup.py

@@ -9,7 +9,7 @@ import subprocess
 import unittest
 
 ROOT = pathlib.Path(__file__).resolve().parents[1]
-STUBS = ['$', 'toggleLive', 'scrollToY', 'scroller', 'loadMacView', 'loadPanels', 'loadPanelSwitcher', 'loadBackups', 'loadTitles', 'showAndroidTab',
+STUBS = ['$', 'toggleLive', 'scrollToY', 'scroller', 'loadMacView', 'loadPanels', 'loadPanelSwitcher', 'loadBackups', 'loadStorage', 'loadTitles', 'showAndroidTab',
          'loadAndroid', 'loadDisplays', 'setGameSource', 'requestAnimationFrame']
 
 RUN = r'''

tests/test_pc_controller.py

@@ -0,0 +1,64 @@
+"""Frozen regression trace from the original mac-in-headset Swift controller.
+The 600-state reference was produced at 1b90c64, before the C extraction:
+60 seconds with a slow/congested middle, then recovery. No generated behavior
+from the new implementation is used to calculate the expected digest.
+"""
+import ctypes as C
+import hashlib
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / 'ui'))
+from frame_pc_capture import Controller
+
+
+class ControllerTrace(unittest.TestCase):
+    def test_original_mac_congestion_and_recovery(self):
+        cc = shutil.which('cc') or shutil.which('gcc')
+        if not cc:
+            self.skipTest('C compiler not installed; native build jobs cover this trace')
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / ('trace.dll' if sys.platform == 'win32' else 'trace.so')
+            subprocess.run([cc, '-O2', '-shared', '-fPIC', str(ROOT/'desktop/controller.c'), '-o', str(path)], check=True, capture_output=True)
+            lib = C.CDLL(str(path))
+            sig = {'new': (C.c_void_p, [C.c_int, C.c_int]), 'free': (None, [C.c_void_p]),
+                   'ceiling': (None, [C.c_void_p, C.c_int]), 'value': (C.c_int64, [C.c_void_p, C.c_int]),
+                   'capture': (None, [C.c_void_p, C.c_int64]), 'gate': (C.c_int, [C.c_void_p, C.c_int64, C.c_int]),
+                   'sent': (None, [C.c_void_p, C.c_uint32, C.c_int, C.c_int64]),
+                   'ack': (C.c_int, [C.c_void_p, C.c_uint32, C.c_int64]), 'update': (C.c_int, [C.c_void_p, C.c_int64])}
+            for name, (ret, args) in sig.items():
+                fn = getattr(lib, 'fc_'+name)
+                fn.restype, fn.argtypes = ret, args
+            c = Controller(lib, 60, 8000000)
+            due, states, seq = [], [], 0
+            try:
+                for tick in range(6000):
+                    now = 10000000+tick*10000
+                    for t, s in due:
+                        if t <= now:
+                            c.call('ack', s, now)
+                    due = [(t, s) for t, s in due if t > now]
+                    if tick % 2 == 0:
+                        c.call('capture', now)
+                        if c.call('gate', now, 1):
+                            seq += 1
+                            c.call('sent', seq, 8000 if tick < 1000 or tick > 4000 else 22000, now)
+                            due.append((now+(240000 if 1500 < tick < 3500 else 20000), seq))
+                    if tick % 10 == 0:
+                        c.update(now)
+                        x = c.state()
+                        states.append([x[k] for k in ('target', 'ceiling', 'tier', 'fps', 'inFlight')] +
+                                      [round(x['scale']*100), round(x['baseRtt']*1000), round(x['slack']*1000)])
+                digest = hashlib.sha256(json.dumps(states, separators=(',', ':')).encode()).hexdigest()
+                self.assertEqual(digest, '1932f16aafce5c9157bcd2aba5d90719a366f9999422920aaeae78a6cdec08f6')
+            finally:
+                c.close()
+                if sys.platform == 'win32':
+                    import _ctypes
+                    _ctypes.FreeLibrary(lib._handle)

tests/test_pcview.py

@@ -0,0 +1,582 @@
+"""PC adapters: grants, input cleanup, launcher reuse and native codec contract.
+Native tests require the bundled libraries; CI sets REQUIRE_NATIVE so a missing
+bundle is a failure, never a silent skip. No desktop consent or GPU is faked as
+successful real-host capture.
+
+The encoding tests need x264, which only CI's own builds bundle (it's GPL, so
+the installer leaves it out). FRAME_PC_REQUIRE_X264=1 makes its absence a
+failure; FRAME_PC_INSTALLER_BUNDLE=1 checks the installer's bundle instead.
+"""
+import ctypes
+import http.client
+import json
+import os
+from pathlib import Path
+import shutil
+import struct
+import subprocess
+import sys
+import threading
+import time
+import unittest
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / 'ui'))
+import frame_pc_agent as agent
+import frame_pc_capture as capture
+import frame_pcview
+import frame_macview
+from frame_stream_stats import Stats
+from test_macview import WS
+
+
+class GrantsTests(unittest.TestCase):
+    def test_source_bound_retry_ack_and_stop(self):
+        g = agent.Grants('master')
+        ticket = g.ticket('window:1')
+        self.assertIsNone(g.redeem('window:2', {'t': ticket}))
+        key = g.redeem('window:1', {'t': ticket})
+        self.assertEqual(key, g.redeem('window:1', {'t': ticket}))
+        g.ack(key)
+        self.assertIsNone(g.redeem('window:1', {'t': ticket}))
+        self.assertEqual(key, g.redeem('window:1', {'r': key}))
+        self.assertIsNone(g.redeem('window:2', {'r': key}))
+        g.revoke('window:1')
+        self.assertIsNone(g.redeem('window:1', {'r': key}))
+
+    def test_expiry_and_stop_before_redeem(self):
+        g = agent.Grants('master')
+        with mock.patch.object(agent.time, 'monotonic', return_value=1):
+            ticket = g.ticket('test')
+        with mock.patch.object(agent.time, 'monotonic', return_value=62):
+            self.assertIsNone(g.redeem('test', {'t': ticket}))
+        ticket = g.ticket('test')
+        g.revoke()
+        self.assertIsNone(g.redeem('test', {'t': ticket}))
+
+
+class GatingTests(unittest.TestCase):
+    """Experimental, Windows only, and off until the person turns it on."""
+
+    def view(self):
+        return frame_pcview.PCView(['ssh'], mock.Mock(), 'frame')
+
+    def test_only_windows_gets_the_pc_host(self):
+        for platform, cls in (('win32', frame_pcview.PCView), ('linux', frame_macview.MacView),
+                              ('darwin', frame_macview.MacView)):
+            with mock.patch.object(frame_pcview.sys, 'platform', platform):
+                view = frame_pcview.host_view(['ssh'], mock.Mock(), 'frame')
+            self.assertIs(type(view), cls, platform)
+
+    def test_off_by_default_starts_nothing(self):
+        view = self.view()
+        with mock.patch.object(frame_pcview.sys, 'platform', 'win32'), \
+                mock.patch.object(frame_macview.subprocess, 'Popen', side_effect=AssertionError('started while off')):
+            state = view.state()
+            self.assertEqual(state, {'available': False, 'reason': frame_pcview.OFF, 'host': view.host,
+                                     'experimental': True, 'enabled': False})
+            with self.assertRaises(frame_macview.MacViewError):
+                view.show('window:12')
+        view.run.assert_not_called()
+
+    def test_never_offered_off_windows_even_when_turned_on(self):
+        view = self.view()
+        view.enabled = True
+        with mock.patch.object(frame_pcview.sys, 'platform', 'linux'):
+            self.assertIn('only available on Windows', view.unavailable())
+
+    def test_turning_on_checks_for_the_bundled_libraries(self):
+        view = self.view()
+        missing = mock.Mock(is_file=mock.Mock(return_value=False))
+        with mock.patch.object(frame_pcview.sys, 'platform', 'win32'), \
+                mock.patch.object(frame_pcview, 'LIBRARY', missing):
+            state = view.set_enabled(True)
+        self.assertTrue(state['enabled'])
+        self.assertFalse(state['available'])
+        self.assertIn('libraries are missing', state['reason'])
+
+    def test_turning_off_stops_streams_and_the_helper(self):
+        view = self.view()
+        view.enabled = True
+        agent = mock.Mock()
+        agent.poll.return_value = None
+        view.agent, view.tunnel = agent, mock.Mock()
+        tunnel = view.tunnel
+        tunnel.poll.return_value = None
+        view.stop = mock.Mock()
+        with mock.patch.object(frame_pcview.sys, 'platform', 'win32'):
+            state = view.set_enabled(False)
+        view.stop.assert_called_once_with()
+        agent.stdin.close.assert_called_once()
+        agent.wait.assert_called()
+        tunnel.terminate.assert_called_once()
+        self.assertIsNone(view.agent)
+        self.assertEqual((state['enabled'], state['reason']), (False, frame_pcview.OFF))
+
+    def test_server_enable_action(self):
+        import sandbox  # noqa: F401  (keeps the server off real data and services)
+        import server
+        with mock.patch.object(server, 'macview', frame_macview.MacView(['ssh'], mock.Mock(), 'frame')):
+            with self.assertRaises(server.Failure) as e:
+                server.macview_action({'action': 'enable', 'on': True})
+            self.assertIn('only available on Windows', str(e.exception))
+        view = self.view()
+        view.set_enabled = mock.Mock(return_value={'enabled': True})
+        with mock.patch.object(server, 'macview', view):
+            self.assertEqual(server.macview_action({'action': 'enable', 'on': True}), {'enabled': True})
+            server.macview_action({'action': 'enable', 'on': 'yes'})  # anything but true is off
+        self.assertEqual([c.args for c in view.set_enabled.call_args_list], [(True,), (False,)])
+
+
+class PageTests(unittest.TestCase):
+    page = (ROOT / 'ui' / 'index.html').read_text(encoding='utf-8')
+
+    def test_tool_link_is_windows_only_and_marked_experimental(self):
+        self.assertIn('<a href="#macview" id="pcToolLink" hidden><span>PC in the headset</span>'
+                      '<small>Experimental:', self.page)
+        self.assertIn('$("pcToolLink").hidden = h.mobile || h.os !== "Windows";', self.page)
+        self.assertIn('$("macToolLink").hidden = h.mobile || h.os !== "macOS";', self.page)
+
+    def test_card_says_experimental_and_what_is_unverified(self):
+        self.assertIn('<span class="tag" id="mvTag" hidden>Experimental</span>', self.page)
+        self.assertIn('<input type="checkbox" id="mvPcOn">', self.page)
+        self.assertIn('Tested in a Windows VM; physical PCs, hardware encoding and laser clicks remain unverified.', self.page)
+        self.assertIn('docs/pc-in-headset.md', self.page)
+
+    def test_opt_in_is_remembered_with_the_client_preferences(self):
+        self.assertIn("const keys = ['mvSeparate', 'padUsed', 'pcView']", self.page)
+        prefs = (ROOT / 'app' / 'preferences.js').read_text(encoding='utf-8')
+        self.assertIn('const KEYS = ["mvSeparate", "padUsed", "pcView"];', prefs)
+
+
+class AdapterTests(unittest.TestCase):
+    def test_dxgi_only_bundle_captures_displays_without_optional_wgc_properties(self):
+        p = capture.pipeline(dict(src='display:65537', capture_api='dxgi'), 'win32', 'mfh264enc', 640, 360, 30, 1000000)
+        self.assertIn('monitor-handle=65537', p)
+        self.assertNotIn('capture-api=', p)
+        self.assertNotIn('show-border=', p)
+        self.assertIn('mfh264enc', p)
+        for source in (dict(src='window:42', capture_api='dxgi'),
+                       dict(src='display:42', capture_api='dxgi ! fakesink')):
+            with self.assertRaises(ValueError):
+                capture.pipeline(source, 'win32', 'mfh264enc', 640, 360, 30, 1000000)
+
+    def test_windows_sources_follow_actual_wgc_capabilities(self):
+        for wgc in (False, True):
+            with self.subTest(wgc=wgc):
+                native, windows = mock.Mock(), mock.Mock()
+                native.has_property.return_value = wgc
+                windows.sources.side_effect = lambda: ([dict(src='window:12', w=800, h=600)],
+                                                       [dict(src='display:4', w=1920, h=1080)])
+                with mock.patch.object(agent.sys, 'platform', 'win32'), \
+                        mock.patch.object(agent, 'Windows', return_value=windows):
+                    host = agent.Agent(native, 'test', ROOT/'ui/mac-view.html')
+                wins, displays = host.lists()
+                self.assertEqual(len(wins), int(wgc))
+                self.assertEqual(displays[0]['capture_api'], 'wgc' if wgc else 'dxgi')
+                self.assertEqual(host.source('display:4')['capture_api'], displays[0]['capture_api'])
+                if wgc:
+                    self.assertEqual(host.source('window:12')['capture_api'], 'wgc')
+                    self.assertEqual(host.window_capture_reason, '')
+                else:
+                    with self.assertRaisesRegex(ValueError, 'Individual windows are unavailable'):
+                        host.source('window:12')
+                    self.assertIn('whole screen', host.window_capture_reason)
+                # Synthetic encoder/protocol checks remain available without WGC.
+                self.assertEqual(host.source('test')['src'], 'test')
+
+    def test_pc_card_receives_window_capture_limitation(self):
+        view = frame_pcview.PCView([], lambda *a: None, 'frame')
+        view.enabled = True
+        view.call = mock.Mock(side_effect=lambda path: {
+            '/status': dict(screen=True, accessibility=True, windowCaptureReason=agent.WINDOW_CAPTURE_UNAVAILABLE),
+            '/windows': dict(windows=[]), '/displays': dict(displays=[dict(src='display:4')])}[path])
+        with mock.patch.object(frame_pcview.sys, 'platform', 'win32'), \
+                mock.patch.object(frame_pcview, 'LIBRARY', mock.Mock(is_file=lambda: True)):
+            state = view.state()
+        self.assertTrue(state['available'])
+        self.assertEqual(state['windowCaptureReason'], agent.WINDOW_CAPTURE_UNAVAILABLE)
+        self.assertEqual(state['windows'], [])
+        self.assertEqual(state['displays'], [dict(src='display:4')])
+
+    def test_windows_uses_wgc_and_media_foundation(self):
+        for kind in ('window', 'display'):
+            pipeline = capture.pipeline(dict(src=kind+':42'), 'win32', 'mfh264enc', 640, 360, 30, 1000000)
+            self.assertIn('capture-api=wgc', pipeline)
+            self.assertIn('window-handle=42' if kind == 'window' else 'monitor-handle=42', pipeline)
+            self.assertIn('mfh264enc name=enc low-latency=true bframes=0', pipeline)
+            self.assertNotIn('drop=true', pipeline)
+        with self.assertRaises(ValueError):
+            capture.pipeline(dict(src='window:42 ! fakesink'), 'win32', 'mfh264enc', 640, 360, 30, 1000000)
+
+    def test_linux_uses_only_portal_fd_and_node(self):
+        p = capture.pipeline(dict(src='window:consented', fd=19, node=47), 'linux', 'x264enc', 640, 360, 30, 1000000)
+        self.assertIn('pipewiresrc fd=19 path=47', p)
+        self.assertIn('tune=zerolatency', p)
+        self.assertEqual(capture.dimensions(1920, 1080, 1280), (1280, 720))
+
+    def test_portal_input_clamps_and_releases_held_state(self):
+        native = mock.Mock()
+        native.lib.fc_portal_input.return_value = 1
+        inp = capture.PortalInput(native, dict(portal=123, w=100, h=50))
+        inp.handle(dict(t='m', e='down', b=0, x=2, y=-1))
+        inp.handle(dict(t='k', e='down', key='Control'))
+        inp.release()
+        calls = native.lib.fc_portal_input.call_args_list
+        self.assertEqual(calls[0].args, (123, 0, 99, 0, 0, 0))
+        self.assertIn(mock.call(123, 1, 0, 0, 0x110, 0), calls)
+        self.assertIn(mock.call(123, 3, 0, 0, 0xffe3, 0), calls)
+        self.assertFalse(inp.buttons or inp.keys)
+
+    def test_windows_release_and_negative_monitor_origin(self):
+        host = mock.Mock()
+        host.user.GetSystemMetrics.side_effect = [-1920, 0, 3840, 1080]
+        inp = capture.WindowsInput(host, dict(src='display:4', x=-1920, y=0, w=1920, h=1080))
+        inp.handle(dict(t='m', e='down', b=2, x=0, y=0))
+        self.assertEqual(host.send.call_args_list[0], mock.call(mouse=(0, 0, 0, 0xc001)))
+        inp.handle(dict(t='k', e='down', code='ControlLeft', key='Control'))
+        inp.release()
+        self.assertIn(mock.call(mouse=(0, 0, 0, 0x10)), host.send.call_args_list)
+        self.assertIn(mock.call(key=(162, 0, 2)), host.send.call_args_list)
+
+    def test_refused_windows_focus_never_clicks_the_covering_app(self):
+        host = mock.Mock()
+        host.rect.return_value = (0, 0, 800, 600)
+        host.user.GetForegroundWindow.return_value = 99
+        host.user.SetForegroundWindow.return_value = False
+        inp = capture.WindowsInput(host, dict(src='window:12', w=800, h=600))
+        with self.assertRaisesRegex(RuntimeError, 'could not focus'):
+            inp.handle(dict(t='m', e='down', b=0, x=.5, y=.5))
+        host.send.assert_not_called()
+
+    def test_pc_reuses_launcher_and_namespaces_panel_ids(self):
+        view = frame_pcview.PCView(['ssh'], mock.Mock(return_value='panel created'), 'frame')
+        view.call = mock.Mock(side_effect=lambda path, **kw: {'screen': True, 'ticket': 'one-use', 'streams': []})
+        view.ensure_tunnel = mock.Mock()
+        view.remote_port = 47900
+        view.show('window:12')
+        self.assertEqual(view.run.call_args.kwargs['stdin'], frame_macview.LAUNCH)
+        self.assertNotEqual(frame_macview.panel_id('window:12'), frame_macview.panel_id('window:12', 'windows'))
+        self.assertFalse(view.prefer_usb)
+        with self.assertRaises(frame_macview.MacViewError):
+            view.show('separate:12')
+
+    def test_session_end_releases_native_input_only_once(self):
+        session = object.__new__(agent.Session)
+        session.lock, session.input_lock = threading.RLock(), threading.RLock()
+        session.stop_event = threading.Event()
+        session.ws, session.input = mock.Mock(), mock.Mock()
+        session.released = False
+        session.end()
+        session.end()
+        session.input.release.assert_called_once()
+        self.assertTrue(session.stop_event.is_set())
+
+    def test_idle_source_is_not_a_stall(self):
+        # PipeWire/WGC deliver frames only on damage: a static desktop sends
+        # its first frame and then nothing. That must not end the session.
+        session = object.__new__(agent.Session)
+        session.lock, session.pending = threading.RLock(), {}
+        session.stats = Stats(lambda: 0)
+        session.stats.captured = 1
+        self.assertIsNone(session.stalled(60000000, 0, 0))
+        # A frame that entered the encoder and never came out is a fault.
+        session.pending[5] = dict(cap=0, arr=0, e0=1000000, tier=0, br=0)
+        self.assertIn('encoder', session.stalled(12000000, 0, 0))
+        self.assertIsNone(session.stalled(10000000, 0, 0))
+        # No initial frame at all after the pipeline opened is a fault.
+        session.pending.clear()
+        self.assertIn('capture', session.stalled(12000000, 0, 1))
+        self.assertIsNone(session.stalled(9000000, 0, 1))
+
+    def test_controller_is_inert_after_close(self):
+        lib = mock.Mock()
+        lib.fc_new.return_value = 1234
+        lib.fc_value.return_value = 100
+        controller = capture.Controller(lib, 60, 5000000)
+        controller.close()
+        lib.fc_free.assert_called_once_with(1234)
+        lib.reset_mock()
+        state = controller.state()
+        self.assertEqual((state['fps'], state['target'], state['scale']), (60, 0, 1))
+        self.assertEqual(controller.call('gate', 1, 1), 0)
+        self.assertEqual(controller.update(1), 0)
+        controller.close()
+        self.assertEqual(lib.method_calls, [])  # nothing touched the freed pointer
+
+    def test_library_path_prepend_adds_no_empty_entry(self):
+        env = {}
+        frame_pcview.prepend(env, 'LD_LIBRARY_PATH', '/opt/fc/lib')
+        self.assertEqual(env['LD_LIBRARY_PATH'], '/opt/fc/lib')
+        frame_pcview.prepend(env, 'LD_LIBRARY_PATH', '/x')
+        self.assertEqual(env['LD_LIBRARY_PATH'], '/x' + os.pathsep + '/opt/fc/lib')
+        with mock.patch.dict(os.environ, clear=True):
+            env = frame_pcview.PCView([], lambda *a: None, 'frame').agent_environment()
+        for name in ('PATH', 'LD_LIBRARY_PATH'):
+            parts = env.get(name, 'x').split(os.pathsep)
+            self.assertNotIn('', parts, name)
+
+    def test_malformed_viewer_input_is_dropped_not_fatal(self):
+        session = object.__new__(agent.Session)
+        session.lock, session.input_lock = threading.RLock(), threading.RLock()
+        session.stop_event, session.key_event = threading.Event(), threading.Event()
+        session.src, session.codec, session.key, session.w, session.h = 'display:1', 'h264', 'r', 100, 100
+        session.source = dict(src='display:1', w=100, h=100, portal=1)
+        session.input_enabled, session.released = True, False
+        session.native = mock.Mock()
+        session.native.now.return_value = 0
+        session.controller, session.agent = mock.Mock(), mock.Mock()
+        session.stats = Stats(lambda: 0)
+        session.produce = lambda: None
+        lib = mock.Mock()
+        lib.fc_portal_input.return_value = 1
+        session.input = capture.PortalInput(mock.Mock(lib=lib), session.source)
+        session.ws = mock.Mock()
+        session.ws.receive.side_effect = [
+            dict(t='m', x='left', y=0), dict(t='wheel', dx=[1]), dict(t='k', e='down', key=None, i='x'),
+            dict(t='fd', drop='many'), dict(t='rx', s=[1]), dict(t='m', x=.5, y=.5), ConnectionError('closed')]
+        with self.assertRaises(ConnectionError):
+            session.start()
+        # Every malformed message was skipped; the good move after them still ran.
+        moves = [c.args for c in lib.fc_portal_input.call_args_list if c.args[1] == 0]
+        self.assertAlmostEqual(moves[-1][2], .5*99)
+        self.assertEqual(session.ws.receive.call_count, 7)
+
+    def test_stats_keep_capture_time_and_bound_records(self):
+        stats = Stats(lambda: 10000000)
+        stats.input(dict(t='m', i=1, tv=9999990))
+        f = stats.add(cap=10000001, arr=10000002, e0=10000003, e1=10000004)
+        self.assertEqual(f['echo'], 1)
+        stats.report(dict(t='rx', s=f['s'], r=10000010))
+        stats.report(dict(t='fd', f=[[f['s'], 10000011, 10000012, 10000013]]))
+        self.assertEqual(stats.snapshot(settle=0)['inputs'][0]['frame'], f['s'])
+        for _ in range(4100):
+            stats.add(cap=10000001)
+        self.assertEqual(len(stats.frames), 4096)
+
+
+def x264_bundled():
+    return any((capture.NATIVE / 'lib' / 'gstreamer-1.0').glob('*gstx264*'))
+
+
+def needs_x264(test):
+    def run(self):
+        if not x264_bundled():
+            if os.environ.get('FRAME_PC_REQUIRE_X264') == '1':
+                raise AssertionError('CI required x264 in the native PC bundle (desktop/build.py --with-x264)')
+            raise unittest.SkipTest('x264 is only in CI test bundles, not the installer')
+        return test(self)
+    run.__name__, run.__doc__ = test.__name__, test.__doc__
+    return run
+
+
+class NativeTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        if not capture.LIBRARY.exists():
+            if os.environ.get('FRAME_PC_REQUIRE_NATIVE') == '1':
+                raise AssertionError('CI required native PC libraries but they were not built')
+            raise unittest.SkipTest('native PC libraries not built on this host')
+        cls.token = 'test-' + os.urandom(8).hex()
+        env = frame_pcview.PCView([], lambda *a: None, 'frame').agent_environment()
+        env['FRAME_MAC_VIEW_TOKEN'] = cls.token
+        cls.proc = subprocess.Popen([sys.executable, str(ROOT/'ui/frame_pc_agent.py'), 'serve', '--port', '0',
+            '--page', str(ROOT/'ui/mac-view.html'), '--exit-on-eof'], stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE, text=True, env=env)
+        line = cls.proc.stdout.readline()
+        if 'listening' not in line:
+            raise AssertionError('Native agent failed: ' + cls.proc.stderr.read())
+        cls.port = int(line.rsplit(':', 1)[1])
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.proc.stdin.close()
+        try:
+            rc = cls.proc.wait(10)
+        except subprocess.TimeoutExpired:
+            cls.proc.kill()
+            raise AssertionError('Native agent did not stop after EOF')
+        error = cls.proc.stderr.read()
+        cls.proc.stdout.close()
+        cls.proc.stderr.close()
+        if rc:
+            raise AssertionError('Native agent exited %s: %s' % (rc, error))
+
+    def request(self, path, method='GET'):
+        conn = http.client.HTTPConnection('127.0.0.1', self.port, timeout=10)
+        try:
+            conn.request(method, path)
+            response = conn.getresponse()
+            return response.status, response.read()
+        finally:
+            conn.close()
+
+    def tearDown(self):
+        self.request('/close?k='+self.token, 'POST')
+
+    def test_native_property_probe_checks_the_instantiated_element(self):
+        code = """
+from frame_pc_capture import Native
+n = Native()
+assert n.has_property('fakesink', 'sync')
+assert not n.has_property('fakesink', 'not-a-gstreamer-property')
+assert not n.has_property('not-a-gstreamer-element', 'sync')
+"""
+        env = frame_pcview.PCView([], lambda *a: None, 'frame').agent_environment()
+        env['PYTHONPATH'] = str(ROOT/'ui')
+        result = subprocess.run([sys.executable, '-c', code], env=env, capture_output=True, text=True, timeout=15)
+        self.assertEqual(result.returncode, 0, result.stderr)
+
+    @unittest.skipUnless(sys.platform.startswith('linux'), 'Linux PipeWire client libraries')
+    def test_bundled_pipewire_context_needs_no_system_modules(self):
+        # No portal request, remote connection or desktop capture: create and
+        # destroy a private client context to test the dynamically loaded SPA
+        # and protocol modules that ldd cannot discover.
+        code = """
+import ctypes as C, os
+lib = C.CDLL(os.path.join(os.environ['FRAME_PC_NATIVE'], 'lib', 'libpipewire-0.3.so.0'))
+for name, ret, args in [
+    ('pw_init', None, [C.c_void_p, C.c_void_p]),
+    ('pw_main_loop_new', C.c_void_p, [C.c_void_p]),
+    ('pw_main_loop_get_loop', C.c_void_p, [C.c_void_p]),
+    ('pw_context_new', C.c_void_p, [C.c_void_p, C.c_void_p, C.c_size_t]),
+    ('pw_context_find_factory', C.c_void_p, [C.c_void_p, C.c_char_p]),
+    ('pw_context_find_spa_lib', C.c_char_p, [C.c_void_p, C.c_char_p]),
+    ('pw_context_destroy', None, [C.c_void_p]),
+    ('pw_main_loop_destroy', None, [C.c_void_p])]:
+    fn = getattr(lib, name)
+    fn.restype, fn.argtypes = ret, args
+lib.pw_init(None, None)
+loop = lib.pw_main_loop_new(None)
+assert loop, 'bundled SPA loop support did not load'
+context = lib.pw_context_new(lib.pw_main_loop_get_loop(loop), None, 0)
+assert context, 'bundled PipeWire client modules did not load'
+assert lib.pw_context_find_factory(context, b'adapter'), 'video adapter factory is missing'
+# The exported factory is video.adapt, which needs a live follower node to
+# instantiate. Check its configured library and exported factory without
+# pretending a headless context is a consented video stream.
+plugin_name = lib.pw_context_find_spa_lib(context, b'video.adapt')
+assert plugin_name, 'video.adapt has no bundled library mapping'
+plugin = C.CDLL(os.path.join(os.environ['SPA_PLUGIN_DIR'], plugin_name.decode() + '.so'))
+class Factory(C.Structure):
+    _fields_ = [('version', C.c_uint32), ('name', C.c_char_p)]
+plugin.spa_handle_factory_enum.argtypes = [C.POINTER(C.POINTER(Factory)), C.POINTER(C.c_uint32)]
+plugin.spa_handle_factory_enum.restype = C.c_int
+factory, index, names = C.POINTER(Factory)(), C.c_uint32(), []
+while plugin.spa_handle_factory_enum(C.byref(factory), C.byref(index)) > 0:
+    names.append(factory.contents.name)
+assert b'video.adapt' in names, 'bundled SPA video adapter factory is missing'
+lib.pw_context_destroy(context)
+lib.pw_main_loop_destroy(loop)
+"""
+        env = frame_pcview.PCView([], lambda *a: None, 'frame').agent_environment()
+        env['FRAME_PC_NATIVE'] = str(capture.NATIVE)
+        result = subprocess.run([sys.executable, '-c', code], env=env, capture_output=True, text=True, timeout=15)
+        self.assertEqual(result.returncode, 0, result.stderr)
+
+    def test_agent_reports_its_host_and_encoder(self):
+        self.assertEqual(self.request('/status')[0], 403)
+        status, body = self.request('/status?k='+self.token)
+        self.assertEqual(status, 200)
+        data = json.loads(body)
+        if sys.platform == 'win32':
+            self.assertEqual((data['host'], data['encoder']), ('windows', 'mfh264enc'))
+        self.assertEqual(data['streams'], [])
+
+    @unittest.skipUnless(os.environ.get('FRAME_PC_INSTALLER_BUNDLE') == '1', 'checks the installer\'s bundle')
+    def test_installer_bundle_leaves_out_gpl_x264(self):
+        self.assertFalse(x264_bundled())
+        self.assertFalse(list((capture.NATIVE / 'bin').glob('libx264*')))
+        plugins = [p.name for p in (capture.NATIVE / 'lib' / 'gstreamer-1.0').iterdir()]
+        for name in ('mediafoundation', 'd3d11', 'jpeg'):
+            self.assertTrue(any(p.endswith('gst%s.dll' % name) for p in plugins), (name, plugins))
+
+    @needs_x264
+    def test_last_raw_picture_survives_a_closed_gate(self):
+        # A source sends ONE changed frame, then becomes idle. It must reach
+        # the encoder after congestion clears, without needing another update.
+        code = """
+import ctypes as C, sys, time
+from frame_pc_capture import Native, GATE, Encoded, pipeline
+native = Native()
+start = None
+closing = False
+phases = []
+def gate(stage, pts, capture, arrived):
+    global start
+    phases.append(stage)
+    if closing: return -1
+    if start is None: start = time.monotonic()
+    return int(stage == 1 or time.monotonic()-start >= .15)
+callback = GATE(gate)
+p = pipeline(dict(src='test'), sys.platform, 'x264enc', 320, 180, 30, 300000)
+p = p.replace('is-live=true', 'is-live=true num-buffers=1')
+error = C.create_string_buffer(1024)
+handle = native.lib.fc_capture_open(p.encode(), callback, error, len(error))
+assert handle, error.value
+try:
+    frame = Encoded()
+    result = 0
+    deadline = time.monotonic()+5
+    while not result and time.monotonic() < deadline:
+        result = native.lib.fc_capture_pull(handle, C.byref(frame))
+    assert result == 1, native.lib.fc_capture_error(handle)
+    assert frame.key and frame.size > 17
+    assert phases.count(0) == 1 and 2 in phases, phases
+finally:
+    closing = True
+    native.lib.fc_capture_close(handle)
+"""
+        env = frame_pcview.PCView([], lambda *a: None, 'frame').agent_environment()
+        env['PYTHONPATH'] = str(ROOT / 'ui')
+        result = subprocess.run([sys.executable, '-c', code], env=env, capture_output=True, text=True, timeout=10)
+        self.assertEqual(result.returncode, 0, result.stderr)
+
+    @needs_x264
+    def test_auth_and_real_h264_stats(self):
+        self.assertEqual(self.request('/status')[0], 403)
+        status, body = self.request('/ticket?src=test&k='+self.token, 'POST')
+        self.assertEqual(status, 200)
+        ticket = json.loads(body)['ticket']
+        ws = WS(self.port, '/stream?src=test&fps=30&max=640&t='+ticket)
+        try:
+            self.assertEqual(ws.status, 101)
+            key, got, echo = None, 0, False
+            ws.send_text(json.dumps(dict(t='m', e='down', i=7, tv=1, x=.2, y=.3)))
+            deadline = time.monotonic()+10
+            while time.monotonic() < deadline and (got < 5 or not echo):
+                op, data = ws.recv()
+                if op == 1:
+                    m = json.loads(data)
+                    self.assertNotEqual(m.get('t'), 'error', m)
+                    if m.get('t') == 'hello':
+                        key = m['r']
+                        ws.send_text(json.dumps(dict(t='ack')))
+                elif op == 2:
+                    got += 1
+                    seq, echoed = struct.unpack('!II', data[9:17])
+                    now = struct.unpack('!Q', data[1:9])[0]
+                    echo |= echoed == 7
+                    self.assertIn(b'\x00\x00\x00\x01', data[17:])
+                    ws.send_text(json.dumps(dict(t='rx', s=seq, r=now+100)))
+                    ws.send_text(json.dumps(dict(t='fd', f=[[seq, now+200, now+300, now+400]])))
+            self.assertGreaterEqual(got, 5)
+            self.assertTrue(echo)
+            time.sleep(.1)
+            stats = json.loads(self.request('/stats?settle=0&k='+self.token)[1])['streams'][0]
+            self.assertGreater(stats['frames'][0]['e1'], stats['frames'][0]['e0'])
+            self.assertIn('controller', stats)
+            used = WS(self.port, '/stream?src=test&t='+ticket)
+            self.assertEqual(used.status, 403)
+            used.close()
+            self.request('/close?src=test&k='+self.token, 'POST')
+            revoked = WS(self.port, '/stream?src=test&r='+key)
+            self.assertEqual(revoked.status, 403)
+            revoked.close()
+        finally:
+            ws.close()
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_smoke_cleanup.py

@@ -0,0 +1,153 @@
+"""Smoke cleanup against real local Linux processes, never a headset or SSH."""
+import sandbox  # noqa: F401
+import os
+from pathlib import Path
+import shutil
+import shlex
+import signal
+import subprocess
+import sys
+import tempfile
+import unittest
+from unittest import mock
+
+SMOKE = Path(__file__).resolve().parent / 'smoke'
+sys.path.insert(0, str(SMOKE))
+import stop_processes  # noqa: E402
+import frame_smoke  # noqa: E402
+
+
+@unittest.skipUnless(sys.platform == 'linux' and hasattr(os, 'pidfd_open'), 'Linux pidfds required')
+class RealProcesses(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.home = Path(self.tmp.name)
+        self.title = self.home / 'devkit-game' / 'fc_smoke_exe'
+        self.title.mkdir(parents=True)
+        self.children = []
+        self.patcher = mock.patch.object(stop_processes.Path, 'home', return_value=self.home)
+        self.patcher.start()
+        self.addCleanup(self.patcher.stop)
+        self.addCleanup(self.reap)
+
+    def reap(self):
+        for child in self.children:
+            if child.poll() is None:
+                child.kill()
+            child.wait(timeout=5)
+
+    def start(self, cwd, *args, ignore=False):
+        code = ('import signal,time; '
+                + ('signal.signal(signal.SIGTERM, signal.SIG_IGN); ' if ignore else '')
+                + 'print("ready", flush=True); time.sleep(60)')
+        child = subprocess.Popen([sys.executable, '-c', code, *args], cwd=cwd,
+                                 stdout=subprocess.PIPE, text=True)
+        self.children.append(child)
+        self.addCleanup(child.stdout.close)
+        self.assertEqual(child.stdout.readline().strip(), 'ready')
+        return child
+
+    def test_deleted_title_process_is_stopped_but_similar_names_survive(self):
+        owned = self.start(self.title)
+        neighbour = self.title.with_name('fc_smoke_exe_other')
+        neighbour.mkdir()
+        other = self.start(neighbour, 'fc_smoke_exe', 'wine', 'proton')
+        shutil.rmtree(self.title)
+        # Reproduces the old success condition: no title remains, yet it runs.
+        self.assertFalse(self.title.exists())
+        self.assertIsNone(owned.poll())
+        def local_target(command, *, input, timeout):
+            return subprocess.run(shlex.split(command), input=input, text=True,
+                                  capture_output=True, check=True, timeout=timeout,
+                                  env={**os.environ, 'HOME': str(self.home)}).stdout
+
+        # Exercise the production SSH command and stdin payload against a local
+        # fake target, including the helper's CLI and JSON result contract.
+        with mock.patch.object(frame_smoke.frame_android, 'ssh', side_effect=local_target):
+            result = frame_smoke.stop_titles({'fc_smoke_exe'})
+        self.assertIn(owned.pid, result['stopped_pids'])
+        self.assertEqual(owned.wait(timeout=5), -signal.SIGTERM)
+        self.assertIsNone(other.poll())
+
+    def test_proton_style_absolute_argument_escalates_without_stopping_shared_wine(self):
+        owned = self.start(self.home, str(self.title / 'fc-smoke-exe.exe'), ignore=True)
+        shared = self.start(self.home, 'wineserver', '-p')
+        quoted = self.start(self.home, 'echo ' + str(self.title / 'fc-smoke-exe.exe'))
+        result = stop_processes.stop(['fc_smoke_exe'], grace=0.2)
+        self.assertIn(owned.pid, result['stopped_pids'])
+        self.assertEqual(owned.wait(timeout=5), -signal.SIGKILL)
+        self.assertIsNone(shared.poll())
+        self.assertIsNone(quoted.poll())
+        self.assertEqual(stop_processes.stop(['fc_smoke_exe']), {'stopped_pids': []})
+
+    def test_unreadable_cwd_does_not_abort_scan_or_hide_readable_argv(self):
+        owned = self.start(self.home, str(self.title / 'fc-smoke-exe.exe'))
+        other = self.start(self.home, 'wineserver')
+        with mock.patch.object(stop_processes.os, 'readlink', side_effect=PermissionError):
+            self.assertTrue(stop_processes.owned(owned.pid, [str(self.title)]))
+            self.assertFalse(stop_processes.owned(other.pid, [str(self.title)]))
+            result = stop_processes.stop(['fc_smoke_exe'], grace=0.2)
+        self.assertIn(owned.pid, result['stopped_pids'])
+        self.assertEqual(owned.wait(timeout=5), -signal.SIGTERM)
+        self.assertIsNone(other.poll())
+
+
+class Safety(unittest.TestCase):
+    def test_non_test_ids_rejected_before_scanning(self):
+        for ids in ([], ['portal2'], ['fc_smoke_exe/../portal2'], ['fc_smoke_custom']):
+            with self.subTest(ids=ids), self.assertRaises(ValueError):
+                stop_processes.stop(ids)
+
+    @unittest.skipUnless(sys.platform == 'linux', 'Linux signalling helper')
+    def test_lost_ownership_after_open_never_signalled(self):
+        with mock.patch.object(stop_processes, 'candidates', side_effect=[[123], [], []]), \
+                mock.patch.object(stop_processes.os, 'pidfd_open', return_value=9, create=True), \
+                mock.patch.object(stop_processes.os, 'close'), \
+                mock.patch.object(stop_processes, 'owned', return_value=False), \
+                mock.patch.object(stop_processes.signal, 'pidfd_send_signal', create=True) as send:
+            self.assertEqual(stop_processes.stop(['fc_smoke_exe'], grace=0), {'stopped_pids': []})
+            send.assert_not_called()
+
+    @unittest.skipUnless(sys.platform == 'linux', 'Linux signalling helper')
+    def test_survivor_is_a_failure(self):
+        with mock.patch.object(stop_processes, 'candidates', return_value=[123]), \
+                mock.patch.object(stop_processes.os, 'pidfd_open', return_value=9, create=True), \
+                mock.patch.object(stop_processes.os, 'close'), \
+                mock.patch.object(stop_processes, 'owned', return_value=True), \
+                mock.patch.object(stop_processes.signal, 'pidfd_send_signal', create=True):
+            with self.assertRaisesRegex(RuntimeError, 'survived cleanup'):
+                stop_processes.stop(['fc_smoke_exe'], grace=0)
+
+    def test_cleanup_scans_even_when_title_already_removed(self):
+        with mock.patch.object(frame_smoke.frame_titles, 'list_titles', return_value=[]), \
+                mock.patch.object(frame_smoke, 'ssh') as ssh, \
+                mock.patch.object(frame_smoke, 'stop_titles', return_value={'stopped_pids': [42]}) as stop:
+            result = frame_smoke.cleanup(frame_smoke.Smoke())
+            self.assertEqual(stop.call_args_list, [mock.call(stop_processes.IDS)] * 2)
+            self.assertEqual(result['process_cleanup'][0]['stopped_pids'], [42])
+            ssh.assert_not_called()
+
+    def test_stop_failure_prevents_file_removal(self):
+        with mock.patch.object(frame_smoke.frame_titles, 'list_titles', return_value=[{'id': 'fc_smoke_exe'}]), \
+                mock.patch.object(frame_smoke, 'ssh') as ssh, \
+                mock.patch.object(frame_smoke, 'stop_titles', side_effect=RuntimeError('still running')):
+            with self.assertRaisesRegex(RuntimeError, 'still running'):
+                frame_smoke.cleanup(frame_smoke.Smoke())
+            ssh.assert_not_called()
+
+    def test_failed_initial_cleanup_prevents_install_and_records_failure(self):
+        with tempfile.TemporaryDirectory() as folder, \
+                mock.patch.object(frame_smoke, 'RESULTS', Path(folder)), \
+                mock.patch.object(frame_smoke.sys, 'argv', ['frame_smoke.py']), \
+                mock.patch.object(frame_smoke.subprocess, 'run', return_value=mock.Mock(returncode=0)), \
+                mock.patch.object(frame_smoke.tempfile, 'mkdtemp', return_value=folder), \
+                mock.patch.object(frame_smoke, 'os_release', return_value={
+                    'BUILD_ID': 'fake', 'VERSION_ID': 'fake', 'VARIANT_ID': 'fake'}), \
+                mock.patch.object(frame_smoke, 'ssh', return_value='yes'), \
+                mock.patch.object(frame_smoke, 'cleanup', side_effect=RuntimeError('cannot stop')), \
+                mock.patch.object(frame_smoke, 'title_cycle') as cycle, \
+                mock.patch('builtins.print'):
+            self.assertEqual(frame_smoke.main(), 1)
+            cycle.assert_not_called()
+            self.assertEqual(len(list(Path(folder).glob('*-fake.json'))), 1)

tests/test_storage.py

@@ -0,0 +1,151 @@
+"""Storage inventory uses only local temporary metadata; no headset connection."""
+import sandbox  # noqa: F401
+import http.client
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+from types import SimpleNamespace
+import unittest
+from unittest.mock import patch
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / 'ui'))
+import frame_storage as storage
+import server
+
+
+class Storage(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.home = Path(self.tmp.name)
+        self.steam = self.home / '.local/share/Steam'
+        (self.steam / 'steamapps').mkdir(parents=True)
+
+    def write(self, relative, text):
+        path = self.steam / 'steamapps' / relative
+        path.write_text(text)
+        return path
+
+    def app(self, appid, name, size=None):
+        return self.write(f'appmanifest_{appid}.acf', '"AppState" { "appid" "%s" "name" "%s" %s }' %
+                          (appid, name, '' if size is None else '"SizeOnDisk" "%s"' % size))
+
+    def inventory(self):
+        return storage.inventory(self.home, self.steam)
+
+    def test_multilibrary_dedup_sizes_and_read_only(self):
+        extra = self.home / 'other library'
+        (extra / 'steamapps').mkdir(parents=True)
+        self.write('libraryfolders.vdf', '"libraryfolders" { "0" { "path" "%s" } "1" { "path" "%s" } "2" "%s" }' %
+                   (self.steam, extra, extra))
+        self.app(1, 'Game', '400')
+        self.app(2, 'Proton 10', '100')
+        self.app(3, 'Unknown')
+        self.app(4, 'Zero', '0')
+        self.app(5, 'Bad', '-10')
+        (extra / 'steamapps/appmanifest_9.acf').write_text('"AppState" { "appid" "9" "name" "Other" "SizeOnDisk" "200" }')
+        before = {p: p.read_bytes() for p in self.home.rglob('*') if p.is_file()}
+        result = self.inventory()
+        self.assertEqual(result['discovery'], 'ok')
+        self.assertEqual(len(result['libraries']), 2)
+        lib = result['libraries'][0]
+        self.assertEqual((lib['gameBytes'], lib['toolBytes'], lib['recordedBytes'], lib['unknownSizes']), (400, 100, 500, 2))
+        self.assertEqual([a['bytes'] for a in lib['apps']], [400, 100, 0, None, None])
+        self.assertEqual(result['libraries'][1]['recordedBytes'], 200)
+        self.assertEqual(before, {p: p.read_bytes() for p in self.home.rglob('*') if p.is_file()})
+
+    def test_partial_and_corrupt_metadata_never_become_empty_success(self):
+        self.write('libraryfolders.vdf', '"libraryfolders" {')
+        self.app(1, 'Good', '12')
+        self.write('appmanifest_2.acf', '"AppState" { "appid" "2"')
+        self.write('appmanifest_3.acf', '"AppState" { "appid" "9" }')
+        r = self.inventory()
+        self.assertEqual(r['discovery'], 'invalid-metadata')
+        lib = r['libraries'][0]
+        self.assertEqual((lib['state'], lib['recordedBytes'], len(lib['issues'])), ('partial', 12, 2))
+
+    def test_permission_denied_discovery_listing_manifest_and_capacity(self):
+        original = storage.read_vdf
+        self.app(1, 'Game', '10')
+        def read(path):
+            if str(path).endswith('appmanifest_1.acf') or str(path).endswith('libraryfolders.vdf'):
+                raise PermissionError('denied')
+            return original(path)
+        with patch.object(storage, 'read_vdf', side_effect=read), patch.object(storage.os, 'statvfs', side_effect=PermissionError(), create=True):
+            r = self.inventory()
+        self.assertEqual(r['discovery'], 'permission-denied')
+        self.assertEqual(r['home']['state'], 'permission-denied')
+        self.assertIsNone(r['home']['free'])
+        self.assertEqual(r['libraries'][0]['issues'][0]['state'], 'permission-denied')
+        with patch.object(storage.os, 'scandir', side_effect=PermissionError()):
+            self.assertEqual(self.inventory()['libraries'][0]['state'], 'permission-denied')
+
+    def test_disconnected_library_and_missing_discovery(self):
+        r = self.inventory()
+        self.assertEqual(r['discovery'], 'missing')
+        missing = self.home / 'disconnected'
+        self.write('libraryfolders.vdf', '"libraryfolders" { "1" { "path" "%s" } }' % missing)
+        lib = self.inventory()['libraries'][1]
+        self.assertEqual(lib['state'], 'missing')
+        self.assertIsNone(lib['capacity']['total'])
+
+    def test_reserved_capacity_and_shared_filesystem(self):
+        stat = SimpleNamespace(f_blocks=100, f_frsize=1024, f_bavail=10, f_bfree=20)
+        with patch.object(storage.os, 'statvfs', return_value=stat, create=True):
+            r = self.inventory()
+        self.assertEqual((r['home']['total'], r['home']['free'], r['home']['used']), (102400, 10240, 81920))
+        self.assertEqual(r['home']['filesystem'], r['libraries'][0]['capacity']['filesystem'])
+
+    def test_keyvalues_comments_escaping_and_limits(self):
+        path = self.write('parse.vdf', '// comment\n"root" { "name" "A \\"quote\\"" "nested" { "size" "42" } }')
+        self.assertEqual(storage.read_vdf(path)['root']['name'], 'A "quote"')
+        path.write_text('"root" { "name" "}" }')
+        self.assertEqual(storage.read_vdf(path)['root']['name'], '}')
+        for bad in ['"a" {', '"a" "1" "a" "2"', '"a" }', 'garbage', '"a" {"b" "c"}}']:
+            path.write_text(bad)
+            with self.assertRaises(ValueError):
+                storage.read_vdf(path)
+        path.write_text('x' * (storage.MAX_TEXT + 1))
+        with self.assertRaises(ValueError):
+            storage.read_vdf(path)
+
+    def test_http_probe_is_guarded_and_read_only(self):
+        httpd = server.ThreadingHTTPServer(('127.0.0.1', 0), server.Handler)
+        thread = threading.Thread(target=httpd.serve_forever, daemon=True)
+        thread.start()
+        try:
+            with patch.object(server, 'ssh', return_value=json.dumps(self.inventory())) as ssh:
+                conn = http.client.HTTPConnection(*httpd.server_address)
+                conn.request('GET', '/api/storage')
+                response = conn.getresponse()
+                self.assertEqual(response.status, 403)
+                response.read()
+                ssh.assert_not_called()
+                conn.request('GET', '/api/storage', headers={'X-Frame-UI': server.UI_KEY})
+                response = conn.getresponse()
+                self.assertEqual(response.status, 200)
+                self.assertIn('libraries', json.loads(response.read()))
+                self.assertEqual(ssh.call_args.args, ('python3 -',))
+                self.assertEqual(ssh.call_args.kwargs['stdin'], (ROOT / 'ui/frame_storage.py').read_text())
+                with patch.object(server, 'LINK', SimpleNamespace(active_device=lambda: {'id': 'new-frame'})):
+                    ssh.reset_mock()
+                    conn.request('GET', '/api/storage', headers={'X-Frame-UI': server.UI_KEY, 'X-Frame-Device': 'old-frame'})
+                    response = conn.getresponse()
+                    self.assertEqual(response.status, 409)
+                    response.read()
+                    ssh.assert_not_called()
+                conn.close()
+        finally:
+            httpd.shutdown()
+            httpd.server_close()
+            thread.join()
+
+    @unittest.skipUnless(shutil.which('node'), 'Node required')
+    def test_ui_behavior(self):
+        r = subprocess.run(['node', '--test', str(ROOT / 'tests/storage.cjs')], capture_output=True, text=True)
+        self.assertEqual(r.returncode, 0, r.stdout + r.stderr)

tests/ui_review.cjs

@@ -40,7 +40,9 @@ test('a device switch discards completed install results and the open detail',()
   const f=connectionFixture(),c=f.context;
   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.run('onConnection({phase:"connected",device:{id:"b",name:"B"},devices_rev:1,now:0})');
+  assert.match(f.el('storageResult').textContent,/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()=>{

ui/control-center.js

@@ -16,8 +16,8 @@
       description:'Set the default headset output volume or mute it. Changes apply only when you choose Apply or Mute.',
       keywords:'sound speakers headphones loud quiet', special:'audio'},
     {id:'health', category:'device', icon:'pulse', title:'Battery & thermal health', kind:'read', label:'Read-only metrics',
-      description:'Inspect charge, signed battery power, charger capability, battery temperature and health. Heat warnings use the kernel’s own hot and critical trip points.',
-      keywords:'battery charging charger charge time estimate remaining power watts usb health heat temperature thermal sensor', special:'health', links:[['#comfort','Configure battery & heat alerts']]},
+      description:'Inspect charge, signed battery power, charger readings, battery temperature, health and optional capacity / cycle readings. Heat warnings use the kernel’s own hot and critical trip points.',
+      keywords:'battery charging charger charge time estimate remaining power watts usb health cycles capacity wear heat temperature thermal sensor', special:'health', links:[['#comfort','Configure battery & heat alerts']]},
     {id:'storage', category:'device', icon:'files', title:'Storage & memory', kind:'read', label:'Read-only metrics',
       description:'Check free user and system storage plus available RAM. Manage installed apps in their existing libraries, or use SFTP for files.',
       keywords:'disk space root home free total ram memory capacity cleanup usage storage', special:'storage', links:[['#library','Installed games'],['#linuxApps','Linux apps'],['#power','SFTP & remote tools']]},
@@ -144,9 +144,9 @@
     const capacity = b.percent;
     const idle = !!s.power && Number.isFinite(b.watts) && Math.abs(b.watts) < .5;
     const charging = b.status === 'Charging';
-    const full = b.status === 'Full' || (!!s.power && capacity >= 100);
+    const full = b.status === 'Full';
     const batteryState = !sample ? 'Connect to read charge and power' : !s.battery ? 'Battery sensor unavailable' :
-      full ? 'Fully charged' : charging ? 'Charging' : idle ? 'Plugged in · not charging' : s.power ? 'Plugged in · on battery' : 'On battery';
+      full ? 'Fully charged' : charging ? 'Charging' : b.status === 'Not charging' || idle ? (s.power ? 'Plugged in · not charging' : 'Not charging') : b.status === 'Discharging' ? (s.power ? 'Plugged in · on battery' : 'On battery') : 'Charging state unavailable';
     return {
       battery:number(capacity, '%'), batteryDetail:batteryState,
       storage:h ? gib(h.free) : 'Unavailable', storageDetail:h ? `${gib(h.total)} total · user storage` : 'User storage unavailable',
@@ -155,8 +155,11 @@
       rootFree:gib(s.disk?.root?.free), rootTotal:gib(s.disk?.root?.total), memoryAvailable:gib(m?.available),
       fps:number(p.compositorFps, '', 1), fpsDetail:'Compositor FPS · not game FPS',
       power:number(b.watts, ' W', 1), charger:s.power ? `${s.power.type || 'Connected'} · ${number(s.power.watts, ' W', 1)}` : sample ? 'No charger reported' : 'Unavailable',
-      batteryTemp:number(b.tempC, ' °C', 1), batteryHealth:b.health || 'Unavailable',
-      estimate:charging ? (b.timeToFull > 0 ? `${duration(b.timeToFull)} to full` : 'Unavailable') : !full && !idle && b.timeToEmpty > 0 && b.timeToEmpty < 86400 ? `${duration(b.timeToEmpty)} remaining` : 'Unavailable',
+      batteryTemp:number(b.tempC, ' °C', 1), batteryHealth:b.health && b.health !== 'Unknown' ? b.health : 'Unavailable',
+      batterySource:b.source || 'Unavailable', cycles:number(b.cycleCount),
+      fullCapacity:number(b.fullMah, ' mAh', 1), designCapacity:number(b.designMah, ' mAh', 1),
+      capacityHealth:number(b.capacityHealthPercent, '%', 1),
+      estimate:charging ? (b.timeToFull > 0 ? `${duration(b.timeToFull)} to full` : 'Unavailable') : b.status === 'Discharging' && !idle && b.timeToEmpty > 0 && b.timeToEmpty < 86400 ? `${duration(b.timeToEmpty)} remaining` : 'Unavailable',
       wifi:s.wifi?.ssid || 'Unavailable', signal:number(s.wifi?.signal, '%'), ip:s.ip || 'Unavailable',
       uptime:duration(s.uptime), os:s.os?.version || 'Unavailable', build:s.os?.build || 'Unavailable',
       temperature:number(s.temp, ' °C', 1), cpu:number(p.cpuPercent, '%', 1), gpu:number(p.gpuMHz, ' MHz', 1),
@@ -214,7 +217,8 @@
     const metric = (id, label) => `<div><dt>${label}</dt><dd data-cc-metric="${id}">Unavailable</dd></div>`;
     const perf = `<dl class="cc-readings">${[['appFps','Application FPS'],['frame','Compositor period'],['render','Render GPU time'],['compositorCpu','Compositor CPU'],['cpu','System CPU'],['gpu','GPU clock'],['temperature','Hottest sensor']].map(([id,label])=>metric(id,label)).join('')}</dl><p class="cc-note">GPU time is render time, not utilisation. The hottest sensor is not necessarily CPU temperature.</p><p class="cc-note" data-cc-metric="thermal">Trip data unavailable</p>`;
     const audio = `<div class="cc-audio"><label for="ccVolume">Output volume <output id="ccVolumeValue" for="ccVolume">—</output></label><input id="ccVolume" type="range" min="0" max="100" step="1" value="0" disabled><div class="cc-audio-actions"><button class="action small" id="ccApplyVolume" disabled>Apply volume</button><button class="small" id="ccMute" disabled>Mute</button><span id="ccAudioReadback" class="cc-note">Waiting for an audio reading</span></div><p class="cc-note" id="ccAudioResult" role="status"></p></div>`;
-    const health = `<dl class="cc-readings">${[['battery','Charge'],['power','Battery power · signed'],['charger','Charger'],['estimate','Battery estimate'],['batteryTemp','Battery temperature'],['batteryHealth','Battery health']].map(([id,label])=>metric(id,label)).join('')}</dl>`;
+    const batteryNote = 'Read-only. Unavailable means not reported, unreadable or invalid. Health is the driver’s status; full / design capacity is a fuel-gauge estimate, not a diagnosis. Charge limits are unsupported on Frame.';
+    const health = `<dl class="cc-readings">${[['battery','Charge'],['batteryDetail','Charging state'],['power','Battery power · signed'],['charger','Charger'],['estimate','Battery estimate'],['batteryTemp','Battery temperature'],['batteryHealth','Battery health'],['cycles','Charge cycles'],['fullCapacity','Full charge capacity'],['designCapacity','Design capacity'],['capacityHealth','Full / design capacity'],['batterySource','Battery source']].map(([id,label])=>metric(id,label)).join('')}</dl><p class="cc-note">${batteryNote}</p>`;
     const forcequit = `<div class="cc-quit"><div class="cc-audio-actions"><button class="small" type="button" id="ccRunningCheck">Check what’s running</button></div><ul class="cc-running" id="ccRunningList"></ul><p class="cc-note" id="ccRunningResult" role="status"></p></div>`;
     const storage = `<dl class="cc-readings">${[['storage','User storage free'],['rootFree','System storage free'],['rootTotal','System storage total'],['memoryAvailable','Memory available']].map(([id,label])=>metric(id,label)).join('')}</dl>`;
     get('ccCategories').innerHTML = categories.map(([id,label,symbol])=>`<button type="button" data-cc-category="${id}" aria-pressed="${id === 'all'}">${icon(symbol)}<span>${label}</span><span class="cc-category-count"></span></button>`).join('');

ui/frame_macview.py

@@ -56,12 +56,12 @@ BROWSER_FLAGS = []
 PANEL_BOX = (1920, 1080)
 
 # Opens one viewer on gamescope's X display and gives its window its own panel
-# id. Args: appid url width height tag [browser flags...]. The page puts "[tag]" in its title at
+# id. Args: appid url width height tag profile [browser flags...]. The page puts "[tag]" in its title at
 # once, which is how its X window is found (Chromium may hand the URL to an
 # instance that's already running, so there's no process to follow).
 LAUNCH = r"""set -u
-appid=$1 url=$2 w=$3 h=$4 tag=$5
-shift 5
+appid=$1 url=$2 w=$3 h=$4 tag=$5 profile=$6
+shift 6
 export DISPLAY=:0 LC_ALL=C.UTF-8
 unset WAYLAND_DISPLAY
 if ! xprop -root GAMESCOPE_FOCUSABLE_WINDOWS >/dev/null 2>&1; then
@@ -73,15 +73,15 @@ common=(--ozone-platform=x11 --force-device-scale-factor=1 --no-first-run --no-d
   --disable-features=Translate,MediaRouter --autoplay-policy=no-user-gesture-required
   "--window-size=$w,$h" "$@" "--app=$url")
 if [ -x "$HOME/chromium-xr/chrome" ]; then
-  cmd=("$HOME/chromium-xr/chrome" "--user-data-dir=$HOME/.local/share/frame-control/mac-view" "${common[@]}")
+  cmd=("$HOME/chromium-xr/chrome" "--user-data-dir=$HOME/.local/share/frame-control/$profile" "${common[@]}")
 elif flatpak info org.chromium.Chromium >/dev/null 2>&1; then
   cmd=(flatpak run org.chromium.Chromium
-    "--user-data-dir=$HOME/.var/app/org.chromium.Chromium/data/frame-mac-view" "${common[@]}")
+    "--user-data-dir=$HOME/.var/app/org.chromium.Chromium/data/frame-$profile" "${common[@]}")
 else
   echo "NO_BROWSER"
   exit 3
 fi
-log=/tmp/frame-mac-view.log
+log=/tmp/frame-$profile.log
 setsid nohup "${cmd[@]}" >>"$log" 2>&1 </dev/null &
 for _ in $(seq 1 60); do
   sleep 0.5
@@ -105,9 +105,9 @@ class MacViewError(Exception):
     pass
 
 
-def panel_id(src):
+def panel_id(src, host="mac"):
     """A stable panel id per source, in the range panel-on-frame.sh uses."""
-    return 2_001_000_000 + zlib.crc32(f"mac:{src}".encode()) % 1_000_000
+    return 2_001_000_000 + zlib.crc32(f"{host}:{src}".encode()) % 1_000_000
 
 
 def fit(w, h, box=PANEL_BOX):
@@ -116,6 +116,9 @@ def fit(w, h, box=PANEL_BOX):
 
 
 class MacView:
+    host = "mac"
+    viewer_profile = "mac-view"
+
     def __init__(self, tunnel_ssh, run, frame, track=None):
         self.tunnel_ssh = list(tunnel_ssh)
         self.run = run
@@ -174,6 +177,12 @@ class MacView:
         except OSError:
             return False
 
+    def agent_command(self):
+        return [str(AGENT)]
+
+    def agent_environment(self):
+        return {**os.environ, "FRAME_MAC_VIEW_TOKEN": self.token}
+
     def ensure_agent(self):
         with self.lock:
             if self.agent and self.agent.poll() is None:
@@ -182,11 +191,11 @@ class MacView:
             if reason:
                 raise MacViewError(reason)
             self.build()
-            env = {**os.environ, "FRAME_MAC_VIEW_TOKEN": self.token}
+            env = self.agent_environment()
             # The same port as before when restarting, so a running tunnel still
             # fits; otherwise (or if it's gone) whatever the system gives.
             for port in dict.fromkeys([self.port or 0, 0]):
-                self.agent = subprocess.Popen([str(AGENT), "serve", "--port", str(port), "--page", str(PAGE),
+                self.agent = subprocess.Popen([*self.agent_command(), "serve", "--port", str(port), "--page", str(PAGE),
                                                "--exit-on-eof"], env=env, stdin=subprocess.PIPE,
                                               stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
                 line = self.agent.stdout.readline()
@@ -195,7 +204,7 @@ class MacView:
                     break
                 self.agent.kill()
             else:
-                raise MacViewError(f"The Mac streaming helper didn't start: {line.strip() or 'no output'}")
+                raise MacViewError(f"The streaming helper didn't start: {line.strip() or 'no output'}")
             if self.port != int(m.group(1)):
                 self._drop_tunnel()
             self.port = int(m.group(1))
@@ -211,7 +220,7 @@ class MacView:
             with urllib.request.urlopen(req, timeout=10) as r:
                 return json.load(r)
         except (urllib.error.URLError, OSError, ValueError) as e:
-            raise MacViewError(f"The Mac streaming helper didn't answer: {e}")
+            raise MacViewError(f"The streaming helper didn't answer: {e}")
 
     # ---- the tunnel from the Frame ----
 
@@ -396,7 +405,7 @@ class MacView:
         # the agent no longer counts them, so only move when none are out there.
         others = self.shown - {src}
         self.ensure_tunnel(allow_new_port=not others)
-        appid = panel_id(src)
+        appid = panel_id(src, self.host)
         # Unique per launch, so a new window is never confused with an old one.
         tag = "fc" + secrets.token_hex(4)
         # A single-use ticket for this source, not Frame Control's key: the URL
@@ -406,7 +415,7 @@ class MacView:
                   "bpp": q["bpp"]}
         url = f"http://127.0.0.1:{self.remote_port}/view?{urlencode(params)}"
         w, h = fit(width or 1280, height or 720)
-        args = " ".join(_quote(str(a)) for a in (appid, url, w, h, tag, *self.browser_flags))
+        args = " ".join(_quote(str(a)) for a in (appid, url, w, h, tag, self.viewer_profile, *self.browser_flags))
         try:
             out = self.run("bash -s -- " + args, stdin=LAUNCH, timeout=60)
         except Exception as e:  # noqa: BLE001 - the server's Failure carries the Frame's words
@@ -438,7 +447,8 @@ class MacView:
             if self.shown or self.shows != shows or self.launching:
                 return
             try:
-                self.run("pkill -f '[f]rame-control/mac-view|[d]ata/frame-mac-view' || true", timeout=10)
+                pattern = "[f]rame-control/" + self.viewer_profile + "|[d]ata/frame-" + self.viewer_profile
+                self.run("pkill -f " + _quote(pattern) + " || true", timeout=10)
             except Exception:
                 pass
 
@@ -449,7 +459,9 @@ class MacView:
         status = self.call("/status")
         windows = self.call("/windows").get("windows", []) if status.get("screen") else []
         displays = self.call("/displays").get("displays", [])
-        return {"available": True, "screen": status.get("screen", False),
+        return {"available": True, "host": self.host, "selecting": status.get("selecting", False),
+                **({"windowCaptureReason": status["windowCaptureReason"]} if status.get("windowCaptureReason") else {}),
+                "selectionError": status.get("selectionError", ""), "screen": status.get("screen", False),
                 "accessibility": status.get("accessibility", False), "streams": status.get("streams", []),
                 "windows": windows, "displays": displays, "tunnel": self.tunnel_up(),
                 "route": self.route}

ui/frame_pc_agent.py

@@ -0,0 +1,635 @@
+#!/usr/bin/env python3
+"""Frame Control's Windows/Linux host. Same ticket, H.264/JPEG, timing and
+input protocol as frame-mac-view; serves the same ui/mac-view.html.
+
+Only loopback is bound. Frame Control owns the master token, the Frame gets
+one-source tickets and reconnect keys. Native libraries are bundled.
+"""
+import argparse
+import base64
+import ctypes as C
+import hashlib
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import json
+import math
+import os
+import queue
+from pathlib import Path
+import secrets
+import socket
+import struct
+import sys
+import threading
+import time
+from urllib.parse import parse_qs, urlsplit
+
+from frame_pc_capture import Native, Controller, Windows, WindowsInput, PortalInput, Encoded, GATE, dimensions, pipeline
+from frame_stream_stats import Stats
+
+
+# Viewer fields are untrusted JSON: float('x'), int(None), m['t'] missing.
+MALFORMED = (ValueError, TypeError, KeyError, OverflowError)
+WINDOW_CAPTURE_UNAVAILABLE = 'Individual windows are unavailable in this build. Choose a whole screen instead.'
+
+
+class Grants:
+    """Caller holds the agent lock, including replacement and Stop."""
+    def __init__(self, token):
+        self.token, self.tickets, self.keys = token, {}, {}
+
+    def master(self, key):
+        return isinstance(key, str) and secrets.compare_digest(key, self.token)
+
+    def ticket(self, src):
+        self.tickets = {k: v for k, v in self.tickets.items() if v[1] > time.monotonic()}
+        if len(self.tickets) >= 128:
+            raise ValueError('Too many pending viewers')
+        ticket = secrets.token_urlsafe(24)
+        self.tickets[ticket] = (src, time.monotonic()+60, None)
+        return ticket
+
+    def redeem(self, src, q):
+        if self.master(q.get('k')):
+            key = secrets.token_urlsafe(24)
+            self.keys[key] = src
+            return key
+        entry = self.tickets.get(q.get('t'))
+        if entry and entry[0] == src and entry[1] > time.monotonic():
+            key = entry[2] or secrets.token_urlsafe(24)
+            self.tickets[q['t']] = (src, entry[1], key)
+            self.keys[key] = src
+            return key
+        key = q.get('r')
+        return key if key and self.keys.get(key) == src else None
+
+    def ack(self, key):
+        self.tickets = {k: v for k, v in self.tickets.items() if v[2] != key}
+
+    def revoke(self, src=None):
+        self.tickets = {k: v for k, v in self.tickets.items() if src is not None and v[0] != src}
+        self.keys = {k: v for k, v in self.keys.items() if src is not None and v != src}
+
+
+class WebSocket:
+    def __init__(self, handler):
+        self.sock, self.reader = handler.connection, handler.rfile
+        self.lock = threading.Lock()
+        self.closed = False
+        self.sock.settimeout(5)
+        self.sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+
+    def send(self, data, opcode=1):
+        if not isinstance(data, bytes):
+            data = json.dumps(data, separators=(',', ':')).encode()
+        n = len(data)
+        head = bytes([0x80 | opcode, n]) if n < 126 else bytes([0x80 | opcode, 126]) + struct.pack('!H', n) if n <= 65535 else bytes([0x80 | opcode, 127]) + struct.pack('!Q', n)
+        with self.lock:
+            if self.closed:
+                raise ConnectionError('Viewer disconnected')
+            self.sock.sendall(head + data)
+
+    def exact(self, n):
+        data = self.reader.read(n)
+        if len(data) != n:
+            raise ConnectionError('Viewer disconnected')
+        return data
+
+    def receive(self):
+        a, b = self.exact(2)
+        opcode, size = a & 15, b & 127
+        if a & 0x70 or not a & 0x80 or not b & 0x80 or opcode not in (1, 8, 9, 10):
+            raise ValueError('Unsupported WebSocket frame')
+        if size == 126:
+            size = struct.unpack('!H', self.exact(2))[0]
+        elif size == 127:
+            size = struct.unpack('!Q', self.exact(8))[0]
+        if size > 65536 or (opcode >= 8 and size > 125):
+            raise ValueError('WebSocket message too large')
+        mask = self.exact(4)
+        data = bytes(v ^ mask[i % 4] for i, v in enumerate(self.exact(size)))
+        if opcode == 8:
+            raise ConnectionError('Viewer closed')
+        if opcode == 9:
+            self.send(data, 10)
+        if opcode != 1:
+            return {}
+        message = json.loads(data)
+        if not isinstance(message, dict):
+            raise ValueError('Expected an input object')
+        return message
+
+    def close(self):
+        self.closed = True
+        try:
+            self.sock.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+
+
+class Session:
+    def __init__(self, agent, ws, key, source, query):
+        self.agent, self.native, self.ws, self.key, self.source = agent, agent.native, ws, key, source
+        self.src = source['src']
+        self.codec = query.get('codec', 'h264')
+        if self.codec not in ('h264', 'jpeg'):
+            raise ValueError('Unsupported codec')
+        self.fps = min(120, max(5, int(query.get('fps', 60))))
+        bpp = float(query.get('bpp', .1))
+        if not math.isfinite(bpp):
+            raise ValueError('Invalid bitrate')
+        self.w, self.h = dimensions(source['w'], source['h'], min(3840, max(320, int(query.get('max', 1920)))))
+        self.bitrate = max(300000, int(self.w*self.h*self.fps*min(.5, max(.02, bpp))))
+        self.controller = Controller(self.native.lib, self.fps, self.bitrate)
+        self.stats = Stats(self.native.now)
+        self.stop_event, self.key_event = threading.Event(), threading.Event()
+        self.lock, self.input_lock = threading.RLock(), threading.RLock()
+        self.pending, self.last_submit = {}, 0
+        self.reconfiguring = False
+        self.test_inputs = queue.Queue(maxsize=128)
+        self.input = None if self.src == 'test' else WindowsInput(agent.windows, source) if agent.windows else PortalInput(self.native, source)
+        self.writer = None
+        self.released = False
+        self.input_enabled = self.src == 'test' or self.source.get('devices', 3) == 3
+
+    def gate(self, stage, pts, capture, arrived):
+        # Exceptions cannot cross a ctypes callback boundary.
+        try:
+            with self.lock:
+                if self.stop_event.is_set() or self.reconfiguring:
+                    return -1
+                if stage == 1:
+                    if pts in self.pending:
+                        self.pending[pts]['e0'] = self.native.now()
+                    return 1
+                if stage == 0:
+                    self.stats.captured += 1
+                    self.controller.call('capture', arrived)
+                now = self.native.now()
+                state = self.controller.state()
+                if len(self.pending) >= 3 or now-self.last_submit < 1000000/state['fps'] or not self.controller.call('gate', now, int(stage == 0)):
+                    if stage == 0:
+                        self.stats.skipped += 1
+                    return 0
+                self.pending[pts] = dict(cap=capture, arr=arrived, e0=now, tier=state['tier'], br=state['target'])
+                self.last_submit = now
+                return 1
+        except Exception:
+            self.stop_event.set()
+            return -1
+
+    STALL = 10000000
+
+    def stalled(self, now, opened, captured_at_open):
+        """PipeWire and WGC deliver frames only on screen damage, so an idle
+        desktop legitimately produces no output. Fail only on evidence of a
+        fault: a frame entered the encoder and never came out, or the capture
+        never produced its initial frame after the pipeline opened."""
+        with self.lock:
+            oldest = min((r['e0'] for r in self.pending.values()), default=None)
+            captured = self.stats.captured
+        if oldest is not None and now-oldest > self.STALL:
+            return 'The encoder stopped producing frames; check the video encoder'
+        if captured == captured_at_open and now-opened > self.STALL:
+            return 'No frames captured for 10 seconds; check capture permissions'
+        return None
+
+    def fresh_pipewire(self):
+        if 'portal' not in self.source:
+            return
+        error = C.create_string_buffer(1024)
+        fd = self.native.lib.fc_portal_refresh(self.source['portal'], error, len(error))
+        if fd < 0:
+            raise RuntimeError(error.value.decode(errors='replace'))
+        self.source['fd'] = fd
+
+    def produce(self):
+        native, capture = self.native.lib, None
+        try:
+            encoder = "x264enc" if self.src == "test" and self.native.has("x264enc") else self.agent.encoder
+            self.fresh_pipewire()
+            description = pipeline(self.source, sys.platform, encoder, self.w, self.h, self.fps, self.bitrate, self.codec)
+            self.callback = GATE(self.gate)
+            error = C.create_string_buffer(1024)
+            capture = native.fc_capture_open(description.encode(), self.callback, error, len(error))
+            if not capture:
+                raise RuntimeError(error.value.decode(errors='replace'))
+            last_update = last_stats = self.native.now()
+            last_config = opened = last_update
+            captured_at_open = self.stats.captured
+            applied = (self.w, self.h, self.bitrate)
+            wanted = applied
+            while not self.stop_event.is_set():
+                while not self.test_inputs.empty():
+                    event = self.test_inputs.get_nowait()
+                    try:
+                        native.fc_capture_test(capture, int(event.get('i', 0)) & 0xffffffff)
+                        self.stats.input(event)
+                    except MALFORMED:
+                        pass  # a bad probe field drops the event, not the stream
+                output = Encoded()
+                result = native.fc_capture_pull(capture, C.byref(output))
+                now = self.native.now()
+                if result < 0:
+                    raise RuntimeError(native.fc_capture_error(capture).decode(errors='replace'))
+                if result:
+                    with self.lock:
+                        # At most three raw frames are in flight; no B-frames.
+                        # x264 offsets PTS, so match the FIFO encode order while
+                        # retaining the actual pre-encode capture timestamp.
+                        raw_pts = next(iter(self.pending), None)
+                        record = self.pending.get(raw_pts)
+                        if record is None:
+                            raise RuntimeError('Encoder changed frame timestamps; timing cannot be matched')
+                        data = C.string_at(output.data, output.size)
+                        f = self.stats.add(**record, e1=now, snd=now, b=len(data), k=output.key,
+                                           w=output.width or self.w, h=output.height or self.h)
+                        self.controller.call('sent', f['s'], len(data)+17, now)
+                    self.ws.send(struct.pack('!BQII', output.key, max(0, f['cap']), f['s'], f['echo'])+data, 2)
+                    with self.lock:
+                        f['wire'] = self.native.now()
+                        self.pending.pop(raw_pts, None)
+                stall = self.stalled(now, opened, captured_at_open)
+                if stall:
+                    raise RuntimeError(stall)
+                if self.key_event.is_set():
+                    self.key_event.clear()
+                    if self.codec == 'h264':
+                        native.fc_capture_key(capture)
+                if now-last_update >= 100000:
+                    target = self.controller.update(now)
+                    state = self.controller.state()
+                    w, h = dimensions(self.w, self.h, max(320, int(max(self.w, self.h)*state['scale'])))
+                    if target and self.codec == 'h264' and encoder == 'x264enc':
+                        native.fc_capture_bitrate(capture, target)
+                        self.bitrate = target
+                    # Hardware properties are not uniformly mutable in PLAYING.
+                    # Drain then reopen the pipeline at a keyframe when its
+                    # budget changes materially. The portal fd/session stays
+                    # alive, so this does not bypass or repeat user consent.
+                    desired_bitrate = target or applied[2]
+                    bitrate_change = self.codec == 'h264' and encoder != 'x264enc' and abs(desired_bitrate-applied[2]) > applied[2]*.2
+                    if not self.reconfiguring and now-last_config >= 1000000 and ((w, h) != applied[:2] or bitrate_change):
+                        wanted = (w, h, desired_bitrate)
+                        with self.lock:
+                            self.reconfiguring = True
+                    last_update = now
+                if self.reconfiguring:
+                    with self.lock:
+                        drained = not self.pending
+                    if drained:
+                        native.fc_capture_close(capture)
+                        capture = None
+                        self.fresh_pipewire()
+                        description = pipeline(self.source, sys.platform, encoder, wanted[0], wanted[1], self.fps, wanted[2], self.codec)
+                        capture = native.fc_capture_open(description.encode(), self.callback, error, len(error))
+                        if not capture:
+                            raise RuntimeError(error.value.decode(errors='replace'))
+                        applied, self.bitrate, last_config = wanted, wanted[2], now
+                        opened, captured_at_open = now, self.stats.captured
+                        with self.lock:
+                            self.reconfiguring = False
+                if now-last_stats >= 1000000:
+                    self.ws.send(dict(self.stats.summary(), t='stats', bitrate=self.bitrate,
+                                      size='%dx%d' % (self.w, self.h), tier=self.controller.state()['tier']))
+                    last_stats = now
+        except Exception as e:
+            try:
+                self.ws.send({'t': 'error', 'message': str(e)})
+            except OSError:
+                pass
+        finally:
+            self.stop_event.set()
+            if capture:
+                native.fc_capture_close(capture)
+            self.ws.close()
+
+    def start(self):
+        if self.stop_event.is_set():
+            self.controller.close()
+            return
+        self.ws.send(dict(t='hello', r=self.key))
+        self.ws.send(dict(t='info', src=self.src, title=self.source.get('title', self.source.get('name', 'Test pattern')),
+                          app='PC', codec=self.codec, input=self.input_enabled,
+                          inputMessage='Allow pointer and keyboard control in the host sharing dialog.',
+                          aspect=self.w/self.h, warm=0))
+        with self.lock:
+            if self.stop_event.is_set():
+                self.controller.close()
+                return
+            self.writer = threading.Thread(target=self.produce, daemon=True)
+            self.writer.start()
+        try:
+            while not self.stop_event.is_set():
+                m = self.ws.receive()
+                t = m.get('t')
+                if t == 'ping':
+                    self.ws.send(dict(t='pong', c=m.get('c', 0), a=self.native.now()))
+                elif t == 'ack':
+                    with self.agent.lock:
+                        self.agent.grants.ack(self.key)
+                elif t == 'key-frame':
+                    self.key_event.set()
+                elif t in ('rx', 'fd', 'clock'):
+                    try:
+                        self.stats.report(m)
+                    except MALFORMED:
+                        pass
+                    if t == 'rx' and isinstance(m.get('s'), int):
+                        self.controller.call('ack', m['s'] & 0xffffffff, self.native.now())
+                elif t in ('m', 'wheel', 'k', 'text', 'release'):
+                    with self.input_lock:
+                        if self.stop_event.is_set():
+                            break
+                        if self.input:
+                            if not self.input_enabled and t != 'release':
+                                continue
+                            try:
+                                self.input.handle(m)
+                                self.stats.input(m)
+                            except MALFORMED:
+                                pass  # drop a malformed viewer event; keep the session
+                            except RuntimeError as e:
+                                self.input_enabled = False
+                                try:
+                                    self.input.release()
+                                except RuntimeError:
+                                    pass
+                                self.ws.send(dict(t='error', message=str(e)))
+                        elif m.get('i'):
+                            try:
+                                self.test_inputs.put_nowait(m)
+                            except queue.Full:
+                                pass
+        finally:
+            self.end()
+            self.writer.join(6)
+            if not self.writer.is_alive():
+                self.controller.close()
+
+    def end(self):
+        with self.lock:
+            self.stop_event.set()
+        self.ws.close()
+        with self.input_lock:
+            if self.input and not self.released:
+                self.released = True
+                try:
+                    self.input.release()
+                except (RuntimeError, OSError):
+                    pass
+
+
+class Agent:
+    def __init__(self, native, token, page):
+        self.native, self.page = native, page
+        self.lock = threading.RLock()
+        self.grants = Grants(token)
+        self.sessions, self.sources = {}, {}
+        self.next_id, self.selecting, self.selection_error = 1, False, ''
+        self.windows = Windows() if sys.platform == 'win32' else None
+        self.wgc = bool(self.windows) and all(native.has_property('d3d11screencapturesrc', p)
+                                            for p in ('capture-api', 'window-handle', 'show-border'))
+        self.window_capture_reason = WINDOW_CAPTURE_UNAVAILABLE if self.windows and not self.wgc else ''
+        self.encoder = 'mfh264enc' if self.windows else 'vah264enc' if native.has('vah264enc') else 'x264enc'
+        self.shutting_down = False
+        self.selection_generation = 0
+
+    def lists(self):
+        if self.windows:
+            windows, displays = self.windows.sources()
+            if not self.wgc:
+                windows = []
+            for source in windows + displays:
+                source['capture_api'] = 'wgc' if self.wgc else 'dxgi'
+            self.sources = {s['src']: s for s in windows + displays}
+            return windows, displays
+        return [{k: v for k, v in s.items() if k not in ('portal', 'fd', 'node')} for s in self.sources.values()], []
+
+    def source(self, src):
+        if src == 'test':
+            return dict(src='test', title='Test pattern', w=1280, h=720)
+        if self.window_capture_reason and isinstance(src, str) and src.startswith('window:'):
+            raise ValueError(self.window_capture_reason)
+        self.lists()
+        if src not in self.sources:
+            raise ValueError('Choose a window or screen on this computer first')
+        return dict(self.sources[src])
+
+    def select(self):
+        if self.windows or self.selecting or self.shutting_down:
+            return
+        if len(self.sources) >= 8:
+            raise ValueError('Stop a panel before sharing another source')
+        self.selecting, self.selection_error = True, ''
+        generation = self.selection_generation
+        def choose():
+            error = C.create_string_buffer(1024)
+            portal = self.native.lib.fc_portal_select(error, len(error))
+            with self.lock:
+                self.selecting = False
+                if not portal:
+                    self.selection_error = error.value.decode(errors='replace')
+                elif self.shutting_down or generation != self.selection_generation:
+                    self.native.lib.fc_portal_close(portal)
+                else:
+                    fd, node, w, h, devices = [self.native.lib.fc_portal_value(portal, i) for i in range(5)]
+                    src = 'window:' + secrets.token_hex(8)
+                    self.sources[src] = dict(src=src, title='Shared window or screen', app='Linux portal',
+                                             w=w, h=h, fd=fd, node=node, portal=portal, devices=devices)
+        threading.Thread(target=choose, daemon=True).start()
+
+    def stop(self, src=None):
+        with self.lock:
+            if src is None:
+                self.selection_generation += 1
+            self.grants.revoke(src)
+            sessions = [s for s in self.sessions.values() if src is None or s.src == src]
+            for session in sessions:
+                try:
+                    session.ws.send(dict(t='close'))
+                except OSError:
+                    pass
+                session.end()
+        for session in sessions:
+            if session.writer and session.writer is not threading.current_thread():
+                session.writer.join(6)
+        # The capture is stopped before releasing its PipeWire fd/session.
+        with self.lock:
+            if not self.windows:
+                for key, source in list(self.sources.items()):
+                    if src is None or key == src:
+                        if any(s.src == key and s.writer and s.writer.is_alive() for s in sessions):
+                            continue
+                        self.native.lib.fc_portal_close(source['portal'])
+                        self.sources.pop(key, None)
+        return {'closed': len(sessions)}
+
+
+class Handler(BaseHTTPRequestHandler):
+    protocol_version = 'HTTP/1.1'
+
+    def log_message(self, *args):
+        pass  # URLs contain credentials
+
+    def reply(self, data, status=200, content='application/json'):
+        if not isinstance(data, bytes):
+            data = json.dumps(data).encode()
+        self.send_response(status)
+        self.send_header('Content-Type', content)
+        self.send_header('Content-Length', str(len(data)))
+        self.send_header('Cache-Control', 'no-store')
+        self.send_header('Connection', 'close')
+        self.end_headers()
+        self.wfile.write(data)
+        self.close_connection = True
+
+    def do_GET(self):
+        self.dispatch('GET')
+
+    def do_POST(self):
+        self.dispatch('POST')
+
+    def dispatch(self, method):
+        agent = self.server.agent
+        url = urlsplit(self.path)
+        q = {k: v[-1] for k, v in parse_qs(url.query).items()}
+        try:
+            if method == 'GET' and url.path == '/ping':
+                return self.reply(b'frame-mac-view', content='text/plain')
+            if method == 'GET' and url.path == '/view':
+                return self.reply(agent.page.read_bytes(), content='text/html; charset=utf-8')
+            if method == 'GET' and url.path == '/stream':
+                return self.stream(q)
+            if not agent.grants.master(q.get('k', self.headers.get('X-Token'))):
+                return self.reply({'error': 'forbidden'}, 403)
+            if method == 'POST' and url.path == '/close':
+                return self.reply(agent.stop(q.get('src')))
+            with agent.lock:
+                windows, displays = agent.lists()
+                if method == 'GET' and url.path == '/status':
+                    data = dict(version=1, host='windows' if agent.windows else 'linux', screen=True,
+                                windowCaptureReason=agent.window_capture_reason,
+                                accessibility=True, selecting=agent.selecting, selectionError=agent.selection_error,
+                                encoder=agent.encoder, finished=[], streams=[dict(id=i, src=s.src,
+                                    title=s.source.get('title', ''), stats=s.stats.summary(), controller=s.controller.state())
+                                    for i, s in agent.sessions.items() if not s.stop_event.is_set()])
+                elif method == 'GET' and url.path in ('/windows', '/displays'):
+                    data = dict(windows=windows, displays=displays, screen=True)
+                elif method == 'POST' and url.path == '/ticket':
+                    agent.source(q.get('src'))
+                    data = {'ticket': agent.grants.ticket(q['src'])}
+                elif method == 'POST' and url.path == '/permissions':
+                    agent.select()
+                    data = {'selecting': agent.selecting}
+                elif method == 'GET' and url.path == '/stats':
+                    data = dict(now=agent.native.now(), streams=[dict(id=i, src=s.src, controller=s.controller.state(),
+                         events=list(s.controller.events), **s.stats.snapshot(max(0, int(q.get('since', 0))), max(0, int(q.get('settle', 1500000)))))
+                         for i, s in agent.sessions.items() if q.get('id', str(i)) == str(i) and not s.stop_event.is_set()])
+                elif method == 'POST' and url.path == '/bench':
+                    data = {'sent': 0}
+                    for s in agent.sessions.values():
+                        if s.src == q.get('src'):
+                            m = {k: v for k, v in q.items() if k not in ('k', 'src')}
+                            for k in ('x', 'y', 'interval'):
+                                if k in m:
+                                    m[k] = float(m[k])
+                            s.ws.send(dict(m, t='bench'))
+                            data['sent'] += 1
+                else:
+                    return self.reply({'error': 'not found'}, 404)
+            self.reply(data)
+        except (ValueError, RuntimeError) as e:
+            self.reply({'error': str(e)}, 400)
+        except (OSError, ConnectionError):
+            self.close_connection = True
+
+    def stream(self, query):
+        agent = self.server.agent
+        with agent.lock:
+            key = agent.grants.redeem(query.get('src'), query)
+            if not key:
+                return self.reply({'error': 'forbidden'}, 403)
+            source = agent.source(query.get('src'))
+            if self.headers.get('Upgrade', '').lower() != 'websocket' or self.headers.get('Sec-WebSocket-Version') != '13':
+                return self.reply({'error': 'expected WebSocket'}, 400)
+            wskey = self.headers.get('Sec-WebSocket-Key', '')
+            if len(base64.b64decode(wskey, validate=True)) != 16:
+                raise ValueError('Bad WebSocket key')
+            if len(agent.sessions) >= 8:
+                raise ValueError('At most eight panels may be open')
+            # Stop can revoke and close only a registered session. Register
+            # under the same lock as redemption, before any capture starts.
+            session = Session(agent, WebSocket(self), key, source, query)
+            for old in list(agent.sessions.values()):
+                if old.key == key or old.src == source['src']:
+                    if old.key != key:
+                        agent.grants.keys.pop(old.key, None)
+                        try:
+                            old.ws.send(dict(t='close'))
+                        except OSError:
+                            pass
+                    old.end()
+                    if old.writer:
+                        old.writer.join(6)
+                        if old.writer.is_alive():
+                            session.controller.close()
+                            raise ValueError('The previous capture is still stopping; retry shortly')
+            ident = agent.next_id
+            agent.next_id += 1
+            agent.sessions[ident] = session
+            accept = base64.b64encode(hashlib.sha1((wskey+'258EAFA5-E914-47DA-95CA-C5AB0DC85B11').encode()).digest()).decode()
+            self.send_response(101)
+            self.send_header('Upgrade', 'websocket')
+            self.send_header('Connection', 'Upgrade')
+            self.send_header('Sec-WebSocket-Accept', accept)
+            self.end_headers()
+        try:
+            session.start()
+        except (OSError, ValueError, RuntimeError):
+            session.end()
+        finally:
+            session.end()
+            if session.writer:
+                session.writer.join(6)
+            if not session.writer or not session.writer.is_alive():
+                session.controller.close()
+            with agent.lock:
+                agent.sessions.pop(ident, None)
+            self.close_connection = True
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('command', choices=['serve'])
+    parser.add_argument('--port', type=int, default=0)
+    parser.add_argument('--page', type=Path, required=True)
+    parser.add_argument('--exit-on-eof', action='store_true')
+    args = parser.parse_args()
+    token = os.environ.get('FRAME_MAC_VIEW_TOKEN')
+    if not token:
+        raise SystemExit('Frame Control must provide a private token')
+    native = Native()
+    server = ThreadingHTTPServer(('127.0.0.1', args.port), Handler)
+    agent = server.agent = Agent(native, token, args.page)
+    if args.exit_on_eof:
+        def eof():
+            sys.stdin.buffer.read()
+            with agent.lock:
+                agent.shutting_down = True
+            agent.stop()
+            server.shutdown()
+        threading.Thread(target=eof, daemon=True).start()
+    print('listening on 127.0.0.1:%d' % server.server_port, flush=True)
+    try:
+        server.serve_forever()
+    finally:
+        agent.shutting_down = True
+        agent.stop()
+        server.server_close()
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except (OSError, RuntimeError, AttributeError) as e:
+        raise SystemExit('PC streaming helper: ' + str(e))

ui/frame_pc_capture.py

@@ -0,0 +1,393 @@
+"""Native PC capture and input bindings. No desktop-streaming app required.
+
+The packaged native library contains our adapter and the shared rate controller;
+GStreamer supplies WGC/Media Foundation and PipeWire/VA-API/x264 libraries.
+"""
+import ctypes as C
+import os
+from pathlib import Path
+import re
+import sys
+import threading
+
+ROOT = Path(__file__).resolve().parent.parent
+NATIVE = Path(os.environ.get('FRAME_PC_NATIVE', ROOT / 'desktop' / 'bundle'))
+LIBRARY = NATIVE / ('pc-host.dll' if sys.platform == 'win32' else 'pc-host.so')
+
+
+class Encoded(C.Structure):
+    _fields_ = [('data', C.c_void_p), ('size', C.c_int), ('key', C.c_int),
+                ('width', C.c_int), ('height', C.c_int), ('pts', C.c_int64)]
+
+
+GATE = C.CFUNCTYPE(C.c_int, C.c_int, C.c_int64, C.c_int64, C.c_int64)
+
+
+class Native:
+    def __init__(self, path=LIBRARY):
+        self.dll_dirs = []
+        if sys.platform == 'win32':
+            # Set process coordinates before loading GStreamer: a plugin may
+            # create a helper HWND during discovery, after which it is too late.
+            user = C.WinDLL('user32')
+            user.SetProcessDpiAwarenessContext.argtypes = [C.c_void_p]
+            user.SetProcessDpiAwarenessContext(C.c_void_p(-4))
+            for folder in (path.parent, path.parent / 'bin'):
+                self.dll_dirs.append(os.add_dll_directory(str(folder)))
+        self.lib = C.CDLL(str(path))
+        signatures = {
+            'fc_now': (C.c_int64, []), 'fc_gst_init': (None, []),
+            'fc_has_element': (C.c_int, [C.c_char_p]),
+            'fc_has_property': (C.c_int, [C.c_char_p, C.c_char_p]),
+            'fc_new': (C.c_void_p, [C.c_int, C.c_int]), 'fc_free': (None, [C.c_void_p]),
+            'fc_ceiling': (None, [C.c_void_p, C.c_int]),
+            'fc_gate': (C.c_int, [C.c_void_p, C.c_int64, C.c_int]),
+            'fc_capture': (None, [C.c_void_p, C.c_int64]),
+            'fc_sent': (None, [C.c_void_p, C.c_uint32, C.c_int, C.c_int64]),
+            'fc_ack': (C.c_int, [C.c_void_p, C.c_uint32, C.c_int64]),
+            'fc_update': (C.c_int, [C.c_void_p, C.c_int64]),
+            'fc_value': (C.c_int64, [C.c_void_p, C.c_int]),
+            'fc_capture_open': (C.c_void_p, [C.c_char_p, GATE, C.c_char_p, C.c_int]),
+            'fc_capture_pull': (C.c_int, [C.c_void_p, C.POINTER(Encoded)]),
+            'fc_capture_error': (C.c_char_p, [C.c_void_p]),
+            'fc_capture_bitrate': (None, [C.c_void_p, C.c_int]),
+            'fc_capture_key': (None, [C.c_void_p]),
+            'fc_capture_test': (None, [C.c_void_p, C.c_uint32]), 'fc_capture_close': (None, [C.c_void_p]),
+        }
+        if sys.platform.startswith('linux'):
+            signatures.update({
+                'fc_portal_select': (C.c_void_p, [C.c_char_p, C.c_int]),
+                'fc_portal_close': (None, [C.c_void_p]),
+                'fc_portal_refresh': (C.c_int, [C.c_void_p, C.c_char_p, C.c_int]),
+                'fc_portal_value': (C.c_int, [C.c_void_p, C.c_int]),
+                'fc_portal_input': (C.c_int, [C.c_void_p, C.c_int, C.c_double, C.c_double, C.c_int, C.c_int]),
+            })
+        for name, (result, args) in signatures.items():
+            fn = getattr(self.lib, name)
+            fn.restype, fn.argtypes = result, args
+        self.lib.fc_gst_init()
+
+    def has(self, name):
+        return bool(self.lib.fc_has_element(name.encode()))
+
+    def has_property(self, element, name):
+        """Check optional element properties in the initialized capture DLL."""
+        return bool(self.lib.fc_has_property(element.encode(), name.encode()))
+
+    def now(self):
+        return self.lib.fc_now()
+
+
+class Controller:
+    def __init__(self, lib, fps, ceiling):
+        # close() may run on the stream thread while /status reads state();
+        # after close every entry point is a no-op, never a NULL dereference.
+        self.lib, self.lock, self.fps = lib, threading.RLock(), fps
+        self.enabled = os.environ.get('FRAME_MAC_VIEW_ADAPT') != '0'
+        self.ptr = lib.fc_new(fps, self.enabled)
+        if not self.ptr:
+            raise MemoryError('Unable to allocate the streaming controller')
+        lib.fc_ceiling(self.ptr, ceiling)
+        self.events = []
+
+    def state(self):
+        with self.lock:
+            names = ['target', 'ceiling', 'tier', 'fps', 'scale', 'baseRtt', 'inFlight', 'slack']
+            if not self.ptr:
+                out = dict.fromkeys(names, 0)
+                out.update(fps=self.fps, scale=100)
+            else:
+                out = {k: self.lib.fc_value(self.ptr, i) for i, k in enumerate(names)}
+            out.update(scale=out['scale'] / 100, baseRtt=out['baseRtt'] / 1000,
+                       slack=out['slack'] / 1000, adapt=self.enabled)
+            return out
+
+    def call(self, name, *args):
+        with self.lock:
+            return getattr(self.lib, 'fc_' + name)(self.ptr, *args) if self.ptr else 0
+
+    def update(self, now):
+        with self.lock:
+            if not self.ptr:
+                return 0
+            old = self.state()
+            result = self.lib.fc_update(self.ptr, now)
+            state = self.state()
+            if state['target'] < old['target'] or state['tier'] != old['tier']:
+                self.events.append({'t': now, 'e': 'target %s bit/s; tier %s' % (state['target'], state['tier'])})
+                self.events = self.events[-200:]
+            return result
+
+    def close(self):
+        with self.lock:
+            if self.ptr:
+                self.lib.fc_free(self.ptr)
+                self.ptr = None
+
+
+def dimensions(w, h, maximum):
+    scale = min(1, maximum / max(w, h))
+    return max(2, int(w * scale) // 2 * 2), max(2, int(h * scale) // 2 * 2)
+
+
+def pipeline(source, platform, encoder, w, h, fps, bitrate, codec='h264'):
+    """Only locally constructed numeric source IDs enter the pipeline parser."""
+    if source['src'] == 'test':
+        capture = 'videotestsrc name=source is-live=true pattern=ball'
+    elif platform == 'win32':
+        kind, ident = source['src'].split(':')
+        if kind not in ('window', 'display') or not re.fullmatch(r'[0-9]+', ident):
+            raise ValueError('Invalid Windows capture source')
+        api = source.get('capture_api', 'wgc')
+        if api not in ('wgc', 'dxgi') or (api == 'dxgi' and kind != 'display'):
+            raise ValueError('This build can only capture whole screens without Windows Graphics Capture')
+        prop = 'window-handle' if kind == 'window' else 'monitor-handle'
+        # DXGI-only builds don't expose capture-api or show-border at all.
+        mode = ' capture-api=wgc show-border=true' if api == 'wgc' else ''
+        capture = 'd3d11screencapturesrc%s show-cursor=true %s=%d' % (mode, prop, int(ident))
+    else:
+        capture = 'pipewiresrc fd=%d path=%d do-timestamp=true' % (source['fd'], source['node'])
+    # The source gate runs before conversion/encoding. There is no leaky queue
+    # of H.264 frames; every encoded reference frame reaches the socket.
+    raw = '%s ! video/x-raw,framerate=%d/1 ! queue name=raw_queue leaky=downstream max-size-buffers=1 max-size-bytes=0 max-size-time=0 ! identity name=gate ! videoconvert ! videoscale add-borders=false ! video/x-raw,width=%d,height=%d' % (capture, fps, w, h)
+    if codec == 'jpeg':
+        enc = 'jpegenc name=enc quality=80'
+        parse = ''
+    else:
+        choices = {
+            'mfh264enc': 'mfh264enc name=enc low-latency=true bframes=0 gop-size=60',
+            'vah264enc': 'vah264enc name=enc b-frames=0 key-int-max=60',
+            'x264enc': 'x264enc name=enc tune=zerolatency speed-preset=ultrafast bframes=0 key-int-max=60',
+        }
+        enc = choices[encoder] + ' bitrate=%d' % max(1, bitrate // 1000)
+        raw += ',format=NV12' if encoder != 'x264enc' else ',format=I420'
+        parse = ' ! h264parse config-interval=-1 ! video/x-h264,stream-format=byte-stream,alignment=au'
+    return raw + ' ! ' + enc + parse + ' ! appsink name=out sync=false max-buffers=2 drop=false'
+
+
+# X11 keysyms work on Wayland through the RemoteDesktop portal too. The host's
+# keyboard layout handles physical keys; Unicode text is sent as Unicode keysyms.
+KEYSYMS = {'Enter': 0xff0d, 'Tab': 0xff09, 'Backspace': 0xff08, 'Escape': 0xff1b,
+           'Delete': 0xffff, 'ArrowLeft': 0xff51, 'ArrowUp': 0xff52, 'ArrowRight': 0xff53,
+           'ArrowDown': 0xff54, 'Home': 0xff50, 'End': 0xff57, 'PageUp': 0xff55,
+           'PageDown': 0xff56, 'Shift': 0xffe1, 'Control': 0xffe3, 'Alt': 0xffe9, 'Meta': 0xffeb}
+
+
+class PortalInput:
+    def __init__(self, native, source):
+        self.lib, self.source = native.lib, source
+        self.buttons, self.keys = set(), set()
+
+    def emit(self, kind, x=0, y=0, code=0, down=0):
+        if not self.lib.fc_portal_input(self.source['portal'], kind, x, y, code, down):
+            raise RuntimeError('The desktop portal refused input; check the sharing permission')
+
+    def release(self):
+        error = None
+        for values, kind in ((self.buttons, 1), (self.keys, 3)):
+            for code in list(values):
+                try:
+                    self.emit(kind, code=code, down=0)
+                    values.discard(code)
+                except RuntimeError as e:
+                    error = e
+        if error:
+            raise error
+
+    def handle(self, m):
+        t = m['t']
+        if t == 'release':
+            return self.release()
+        if t in ('m', 'wheel'):
+            x, y = (max(0, min(1, float(m.get(k, 0)))) for k in ('x', 'y'))
+            self.emit(0, x * (self.source['w'] - 1), y * (self.source['h'] - 1))
+        if t == 'm' and m.get('e') in ('up', 'down'):
+            b = {0: 0x110, 1: 0x112, 2: 0x111}.get(m.get('b', 0))
+            if b is not None:
+                down = m['e'] == 'down'
+                self.emit(1, code=b, down=down)
+                (self.buttons.add if down else self.buttons.discard)(b)
+        elif t == 'wheel':
+            self.emit(2, max(-4096, min(4096, float(m.get('dx', 0)))), max(-4096, min(4096, float(m.get('dy', 0)))))
+        elif t == 'k':
+            key = str(m.get('key', ''))
+            k = KEYSYMS.get(key) or (ord(key) if len(key) == 1 and ord(key) < 256 else
+                                     0x1000000 + ord(key) if len(key) == 1 else 0)
+            if k:
+                down = m.get('e') == 'down'
+                self.emit(3, code=k, down=down)
+                (self.keys.add if down else self.keys.discard)(k)
+        elif t == 'text':
+            for ch in str(m.get('s', ''))[:4096]:
+                k = ord(ch) if ord(ch) < 256 else 0x1000000 + ord(ch)
+                self.emit(3, code=k, down=1)
+                self.emit(3, code=k, down=0)
+
+
+class Windows:
+    """WGC source handles and SendInput. No elevation or global input hook."""
+    def __init__(self):
+        from ctypes import wintypes as W
+        self.W = W
+        self.user = C.WinDLL('user32', use_last_error=True)
+        self.dwm = C.WinDLL('dwmapi')
+        self.user.IsWindow.argtypes = [W.HWND]
+        self.user.IsWindowVisible.argtypes = [W.HWND]
+        self.user.IsIconic.argtypes = [W.HWND]
+        self.user.GetWindowTextLengthW.argtypes = [W.HWND]
+        self.user.GetWindowTextW.argtypes = [W.HWND, W.LPWSTR, C.c_int]
+        self.user.GetWindowRect.argtypes = [W.HWND, C.POINTER(W.RECT)]
+        self.user.SetForegroundWindow.argtypes = [W.HWND]
+        self.user.GetForegroundWindow.argtypes = []
+        self.user.GetForegroundWindow.restype = W.HWND
+        self.dwm.DwmGetWindowAttribute.argtypes = [W.HWND, W.DWORD, C.c_void_p, W.DWORD]
+        self.callback = C.WINFUNCTYPE(W.BOOL, W.HWND, W.LPARAM)
+        self.monitor_callback = C.WINFUNCTYPE(W.BOOL, W.HMONITOR, W.HDC, C.POINTER(W.RECT), W.LPARAM)
+        self.user.EnumWindows.argtypes = [self.callback, W.LPARAM]
+        self.user.EnumDisplayMonitors.argtypes = [W.HDC, C.c_void_p, self.monitor_callback, W.LPARAM]
+        class Mouse(C.Structure):
+            _fields_ = [('dx', W.LONG), ('dy', W.LONG), ('data', W.DWORD), ('flags', W.DWORD),
+                        ('time', W.DWORD), ('extra', C.c_size_t)]
+        class Key(C.Structure):
+            _fields_ = [('vk', W.WORD), ('scan', W.WORD), ('flags', W.DWORD), ('time', W.DWORD), ('extra', C.c_size_t)]
+        class Union(C.Union):
+            _fields_ = [('mouse', Mouse), ('key', Key)]
+        class Input(C.Structure):
+            _fields_ = [('type', W.DWORD), ('data', Union)]
+        self.Mouse, self.Key, self.Input = Mouse, Key, Input
+        self.user.SendInput.argtypes = [W.UINT, C.POINTER(Input), C.c_int]
+        self.user.SendInput.restype = W.UINT
+
+    def rect(self, hwnd):
+        r = self.W.RECT()
+        if not self.user.IsWindow(hwnd) or self.user.IsIconic(hwnd):
+            raise RuntimeError('The captured window closed or was minimized')
+        # WGC captures the visible extended frame, excluding invisible resize borders.
+        if self.dwm.DwmGetWindowAttribute(hwnd, 9, C.byref(r), C.sizeof(r)):
+            if not self.user.GetWindowRect(hwnd, C.byref(r)):
+                raise RuntimeError('Cannot locate the captured window')
+        return r.left, r.top, r.right - r.left, r.bottom - r.top
+
+    def sources(self):
+        windows, displays = [], []
+        def window(hwnd, _):
+            if not self.user.IsWindowVisible(hwnd) or self.user.IsIconic(hwnd):
+                return True
+            n = self.user.GetWindowTextLengthW(hwnd)
+            if n:
+                title = C.create_unicode_buffer(n + 1)
+                self.user.GetWindowTextW(hwnd, title, n + 1)
+                try:
+                    x, y, w, h = self.rect(hwnd)
+                    if w > 0 and h > 0:
+                        windows.append(dict(src='window:%d' % hwnd, id=hwnd, title=title.value,
+                                            app='Windows', w=w, h=h, x=x, y=y))
+                except RuntimeError:
+                    pass
+            return True
+        def monitor(handle, dc, rect, data):
+            r = rect.contents
+            displays.append(dict(src='display:%d' % handle, name='Display %d' % (len(displays) + 1),
+                                 x=r.left, y=r.top, w=r.right-r.left, h=r.bottom-r.top))
+            return True
+        self.user.EnumWindows(self.callback(window), 0)
+        self.user.EnumDisplayMonitors(None, None, self.monitor_callback(monitor), 0)
+        return windows, displays
+
+    def send(self, mouse=None, key=None):
+        inp = self.Input()
+        inp.type = 0 if mouse else 1
+        if mouse:
+            inp.data.mouse = self.Mouse(*mouse, 0, 0)
+        else:
+            inp.data.key = self.Key(*key, 0, 0)
+        if self.user.SendInput(1, C.byref(inp), C.sizeof(inp)) != 1:
+            raise RuntimeError('Windows refused input (elevated apps and the secure desktop cannot be controlled)')
+
+
+class WindowsInput:
+    def __init__(self, host, source):
+        self.host, self.source = host, source
+        self.buttons, self.keys = set(), set()
+
+    def release(self):
+        error = None
+        for button in list(self.buttons):
+            try:
+                self.host.send(mouse=(0, 0, 0, {0: 4, 1: 0x40, 2: 0x10}[button]))
+                self.buttons.discard(button)
+            except RuntimeError as e:
+                error = e
+        for vk in list(self.keys):
+            try:
+                extended = 1 if vk in (33, 34, 35, 36, 37, 38, 39, 40, 45, 46, 91, 92, 163, 165) else 0
+                self.host.send(key=(vk, 0, 2 | extended))
+                self.keys.discard(vk)
+            except RuntimeError as e:
+                error = e
+        if error:
+            raise error
+
+    def focus(self):
+        if not self.source['src'].startswith('window:'):
+            return
+        hwnd = int(self.source['src'].split(':')[1])
+        user = self.host.user
+        if user.GetForegroundWindow() != hwnd and not user.SetForegroundWindow(hwnd):
+            raise RuntimeError('Windows could not focus this window. Bring it to the front on your PC, then press Stop and Show again.')
+        if user.GetForegroundWindow() != hwnd:
+            raise RuntimeError('The selected window is not in front. Reopen the view after bringing it to the front on your PC.')
+
+    def handle(self, m):
+        t, u = m['t'], self.host.user
+        if t == 'release':
+            return self.release()
+        if t in ('m', 'wheel'):
+            source = self.source
+            if source['src'].startswith('window:'):
+                hwnd = int(source['src'].split(':')[1])
+                x, y, w, h = self.host.rect(hwnd)
+                if m.get('e') == 'down' or t == 'wheel':
+                    self.focus()
+            else:
+                x, y, w, h = (source[k] for k in ('x', 'y', 'w', 'h'))
+            x += max(0, min(1, float(m.get('x', 0)))) * (w - 1)
+            y += max(0, min(1, float(m.get('y', 0)))) * (h - 1)
+            left, top, width, height = (u.GetSystemMetrics(i) for i in (76, 77, 78, 79))
+            self.host.send(mouse=(round((x-left)*65535/max(1,width-1)), round((y-top)*65535/max(1,height-1)), 0, 0xc001))
+        if t == 'm' and m.get('e') in ('up', 'down'):
+            b = m.get('b', 0)
+            if b in (0, 1, 2):
+                down = m['e'] == 'down'
+                self.host.send(mouse=(0, 0, 0, {0: 2, 1: 0x20, 2: 8}[b] * (1 if down else 2)))
+                (self.buttons.add if down else self.buttons.discard)(b)
+        elif t == 'wheel':
+            for name, flag, direction in (('dy', 0x800, -1), ('dx', 0x1000, 1)):
+                delta = int(max(-4096, min(4096, float(m.get(name, 0))))) * direction
+                if delta:
+                    self.host.send(mouse=(0, 0, delta & 0xffffffff, flag))
+        elif t == 'k':
+            code, down = str(m.get('code', '')), m.get('e') == 'down'
+            if down:
+                self.focus()
+            special = {'Enter': 13, 'Escape': 27, 'Tab': 9, 'Backspace': 8, 'Space': 32,
+                       'ArrowLeft': 37, 'ArrowUp': 38, 'ArrowRight': 39, 'ArrowDown': 40,
+                       'Delete': 46, 'Home': 36, 'End': 35, 'PageUp': 33, 'PageDown': 34,
+                       'ShiftLeft': 160, 'ShiftRight': 161, 'ControlLeft': 162, 'ControlRight': 163,
+                       'AltLeft': 164, 'AltRight': 165, 'MetaLeft': 91, 'MetaRight': 92}
+            vk = special.get(code, 0)
+            if re.fullmatch(r'Key[A-Z]', code) or re.fullmatch(r'Digit[0-9]', code):
+                vk = ord(code[-1])
+            if vk:
+                extended = 1 if vk in (33, 34, 35, 36, 37, 38, 39, 40, 45, 46, 91, 92, 163, 165) else 0
+                self.host.send(key=(vk, 0, extended | (0 if down else 2)))
+                (self.keys.add if down else self.keys.discard)(vk)
+            elif down and len(str(m.get('key', ''))) == 1:
+                self.handle({'t': 'text', 's': m['key']})
+        elif t == 'text':
+            self.focus()
+            raw = str(m.get('s', ''))[:4096].encode('utf-16-le')
+            for i in range(0, len(raw), 2):
+                unit = int.from_bytes(raw[i:i+2], 'little')
+                self.host.send(key=(0, unit, 4))
+                self.host.send(key=(0, unit, 6))

ui/frame_pcview.py

@@ -0,0 +1,130 @@
+"""PC in the headset (Experimental, Windows only), behind the existing MacView
+tunnel/panel controller.
+
+The public /api/macview name and viewer URL are the Mac feature's. Only helper
+launch, platform availability and source validation are different. No second
+viewer, SSH supervisor or benchmark launcher.
+
+It is off until the person turns it on in Tools: until then nothing starts,
+no native library is loaded and no window is listed. The Linux adapter from
+PR #38 is in the tree but never offered (host_view only picks this on Windows).
+"""
+import os
+import sys
+import subprocess
+from frame_macview import MacView, MacViewError, ROOT
+from frame_pc_capture import LIBRARY, NATIVE
+
+
+def prepend(env, name, path):
+    """An empty entry means the current directory to the loader; never add one."""
+    rest = env.get(name, '')
+    env[name] = str(path) + (os.pathsep + rest if rest else '')
+
+
+OFF = 'Off. Turn it on to list your windows and screens.'
+
+
+class PCView(MacView):
+    viewer_profile = 'pc-view'
+    host = 'windows' if sys.platform == 'win32' else 'linux'
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.prefer_usb = False  # Mac networksetup probe is platform-specific
+        self.enabled = False
+
+    def unavailable(self):
+        if sys.platform != 'win32':
+            return 'PC in the headset is only available on Windows for now.'
+        if not self.enabled:
+            return OFF
+        if not LIBRARY.is_file():
+            return 'The PC streaming libraries are missing from this build. See docs/pc-in-headset.md.'
+        return None
+
+    def state(self):
+        result = super().state()
+        result.update(host=self.host, experimental=True, enabled=self.enabled)
+        return result
+
+    def set_enabled(self, on):
+        """Turning it off ends every stream and the helper; nothing restarts
+        it until it's turned on again (ensure_agent asks unavailable())."""
+        if on:
+            with self.lock:
+                self.enabled = True
+            return self.state()
+        try:
+            self.stop()  # while still enabled, so the viewers on the Frame close too
+        except MacViewError:
+            pass
+        with self.lock:
+            self.enabled = False
+            self._drop_tunnel()
+            agent, self.agent = self.agent, None
+        if agent and agent.poll() is None:
+            # EOF gives the host a chance to release held input, including on
+            # Windows where terminate is uncatchable.
+            if agent.stdin:
+                agent.stdin.close()
+            try:
+                agent.wait(10)
+            except subprocess.TimeoutExpired:
+                agent.kill()
+                agent.wait(5)
+        return self.state()
+
+    def build(self):
+        pass  # native libraries are built and bundled with the app
+
+    def agent_command(self):
+        return [sys.executable, str(ROOT / 'ui' / 'frame_pc_agent.py')]
+
+    def agent_environment(self):
+        env = super().agent_environment()
+        env['GST_PLUGIN_PATH_1_0'] = str(NATIVE / 'lib' / 'gstreamer-1.0')
+        env['GST_PLUGIN_SYSTEM_PATH_1_0'] = ''
+        cache = os.path.join(os.path.expanduser('~'), '.cache', 'frame-control')
+        os.makedirs(cache, exist_ok=True)
+        env['GST_REGISTRY_1_0'] = os.path.join(cache, 'gstreamer-registry.bin')
+        env['GST_REGISTRY_FORK'] = 'no'
+        if sys.platform == 'win32':
+            prepend(env, 'PATH', NATIVE / 'bin')
+        else:
+            prepend(env, 'LD_LIBRARY_PATH', NATIVE / 'lib')
+            env['PIPEWIRE_MODULE_DIR'] = str(NATIVE / 'lib' / 'pipewire-0.3')
+            env['SPA_PLUGIN_DIR'] = str(NATIVE / 'lib' / 'spa-0.2')
+            env['PIPEWIRE_CONFIG_DIR'] = str(NATIVE / 'share' / 'pipewire')
+            env['PIPEWIRE_CONFIG_NAME'] = 'client.conf'
+        return env
+
+    def shutdown(self):
+        self.closing = True
+        try:
+            self.stop()
+        except MacViewError:
+            pass
+        if self.tunnel and self.tunnel.poll() is None:
+            self.tunnel.terminate()
+        if self.agent and self.agent.poll() is None:
+            # EOF gives the host a chance to release held input and portal
+            # sessions, including on Windows where terminate is uncatchable.
+            if self.agent.stdin:
+                self.agent.stdin.close()
+            try:
+                self.agent.wait(10)
+            except subprocess.TimeoutExpired:
+                self.agent.kill()
+                self.agent.wait(5)
+
+    def _show(self, src, quality, width, height):
+        if src.startswith('separate:'):
+            raise MacViewError('Separate virtual displays are a Mac-only feature. Choose a window or screen.')
+        return super()._show(src, quality, width, height)
+
+
+def host_view(*args, **kwargs):
+    """Windows gets the PC host; everywhere else keeps the Mac view, which
+    reports itself unavailable off macOS."""
+    return (PCView if sys.platform == 'win32' else MacView)(*args, **kwargs)

ui/frame_status.py

@@ -45,19 +45,40 @@ def num(path, scale=1.0):
 
 
 def battery():
-    for d in glob.glob("/sys/class/power_supply/*"):
+    # Prefer the documented Frame fuel gauge over controller/peripheral batteries.
+    supplies = sorted(glob.glob("/sys/class/power_supply/*"),
+                      key=lambda d: (os.path.basename(d) != "max1720x_bat_7-36", d))
+    for d in supplies:
         if read(d + "/type") != "Battery":
             continue
-        cap = read(d + "/capacity")
+        if read(d + "/scope") == "Device" or read(d + "/present") == "0":
+            continue
+
+        def value(name, scale=1, minimum=None, maximum=None):
+            n = num(d + "/" + name, scale)
+            if n is None or not math.isfinite(n):
+                return None
+            if (minimum is not None and n < minimum) or (maximum is not None and n > maximum):
+                return None
+            return n
+
         # max1720x reports microvolts/microamps; current is positive while charging.
-        volts, amps = num(d + "/voltage_now", 1e-6), num(d + "/current_now", 1e-6)
-        return {"percent": int(cap) if cap and cap.isdigit() else None,
+        volts, amps = value("voltage_now", 1e-6, 0), value("current_now", 1e-6)
+        full = value("charge_full", 1e-3, 0)
+        design = value("charge_full_design", 1e-3, 0)
+        return {"source": d,
+                "percent": value("capacity", minimum=0, maximum=100),
                 "status": read(d + "/status"),
                 "watts": round(volts * amps, 2) if volts is not None and amps is not None else None,
-                "timeToFull": num(d + "/time_to_full_now"),
-                "timeToEmpty": num(d + "/time_to_empty_now"),
-                "tempC": num(d + "/temp", 0.1),
-                "health": read(d + "/health")}
+                # Reject negative/unsigned sentinel estimates and implausible temperatures.
+                "timeToFull": value("time_to_full_now", minimum=1, maximum=604800),
+                "timeToEmpty": value("time_to_empty_now", minimum=1, maximum=604800),
+                "tempC": value("temp", 0.1, -273.15, 200),
+                "health": read(d + "/health"),
+                "cycleCount": value("cycle_count", minimum=0),
+                "fullMah": full if full else None,
+                "designMah": design if design else None,
+                "capacityHealthPercent": round(full / design * 100, 1) if full and design else None}
     return None
 
 

ui/frame_storage.py

@@ -0,0 +1,152 @@
+"""Read-only headset storage inventory, piped over SSH as python3 -.
+
+No recursive size scans, Steam IPC, subprocesses or writes. Manifest sizes are
+Steam's recorded content sizes, not filesystem allocation measurements.
+"""
+import json
+import os
+from pathlib import Path
+import re
+import time
+
+HOME = Path.home()
+STEAM = HOME / '.local/share/Steam'
+MAX_TEXT = 2 * 1024 * 1024
+TOOLS = re.compile(r'^(Steam Linux Runtime|Proton|Steamworks Common|FEX$|Lepton Development$)')
+
+
+def state(error):
+    if isinstance(error, PermissionError):
+        return 'permission-denied'
+    if isinstance(error, FileNotFoundError):
+        return 'missing'
+    return 'unavailable'
+
+
+def read_vdf(path):
+    """Small strict KeyValues reader; reject truncated/malformed input explicitly."""
+    with open(path, encoding='utf-8', errors='strict') as stream:
+        text = stream.read(MAX_TEXT + 1)
+    if len(text) > MAX_TEXT:
+        raise ValueError('metadata too large')
+    tokens = []
+    pos = 0
+    pattern = re.compile(r'\s+|//[^\n]*|"((?:[^"\\]|\\.)*)"|([{}])')
+    while pos < len(text):
+        match = pattern.match(text, pos)
+        if not match:
+            raise ValueError('invalid KeyValues')
+        pos = match.end()
+        if match.group(1) is not None:
+            tokens.append(('text', re.sub(r'\\(["\\])', r'\1', match.group(1))))
+        elif match.group(2):
+            tokens.append(('brace', match.group(2)))
+    index = 0
+
+    def pairs(depth=0):
+        nonlocal index
+        if depth > 20:
+            raise ValueError('metadata too deep')
+        result = {}
+        while index < len(tokens):
+            key_type, key = tokens[index]
+            index += 1
+            if key_type == 'brace' and key == '}':
+                if not depth:
+                    raise ValueError('unexpected brace')
+                return result
+            if key_type == 'brace' or index >= len(tokens):
+                raise ValueError('missing value')
+            value_type, value = tokens[index]
+            index += 1
+            if value_type == 'brace' and value == '{':
+                value = pairs(depth + 1)
+            elif value_type == 'brace':
+                raise ValueError('missing value')
+            if key.lower() in result:
+                raise ValueError('duplicate key')
+            result[key.lower()] = value
+        if depth:
+            raise ValueError('unclosed object')
+        return result
+    return pairs()
+
+
+def capacity(path):
+    try:
+        s = os.statvfs(path)
+        return {'state': 'ok', 'total': s.f_blocks * s.f_frsize,
+                'free': s.f_bavail * s.f_frsize,
+                'used': (s.f_blocks - s.f_bfree) * s.f_frsize,
+                'filesystem': str(os.stat(path).st_dev)}
+    except (OSError, AttributeError) as error:
+        return {'state': state(error), 'total': None, 'free': None, 'used': None,
+                'filesystem': None}
+
+
+def inventory(home=None, steam=None):
+    home, steam = Path(home or HOME), Path(steam or STEAM)
+    paths = [steam]
+    discovery = 'ok'
+    try:
+        folders = read_vdf(steam / 'steamapps/libraryfolders.vdf').get('libraryfolders')
+        if not isinstance(folders, dict):
+            raise ValueError('missing libraryfolders')
+        for key, value in folders.items():
+            if not key.isdigit():
+                continue
+            path = value.get('path') if isinstance(value, dict) else value
+            if not isinstance(path, str) or not os.path.isabs(path) or '\x00' in path:
+                raise ValueError('invalid library path')
+            paths.append(Path(path))
+    except OSError as error:
+        discovery = state(error)
+    except (ValueError, UnicodeError):
+        discovery = 'invalid-metadata'
+    libraries, seen = [], set()
+    for path in paths:
+        canonical = os.path.realpath(path)
+        if canonical in seen:
+            continue
+        seen.add(canonical)
+        lib = {'path': str(path), 'capacity': capacity(path), 'state': 'ok',
+               'apps': [], 'issues': [], 'recordedBytes': 0, 'unknownSizes': 0,
+               'gameBytes': 0, 'toolBytes': 0}
+        try:
+            with os.scandir(path / 'steamapps') as entries:
+                manifests = sorted(entry.path for entry in entries
+                                   if re.fullmatch(r'appmanifest_\d+\.acf', entry.name))
+            for manifest in manifests:
+                try:
+                    fields = read_vdf(manifest).get('appstate')
+                    if not isinstance(fields, dict):
+                        raise ValueError('missing AppState')
+                    appid = fields.get('appid', '')
+                    if not isinstance(appid, str) or not appid.isdigit() or Path(manifest).name != f'appmanifest_{appid}.acf':
+                        raise ValueError('invalid appid')
+                    name = fields.get('name') or appid
+                    if not isinstance(name, str):
+                        raise ValueError('invalid name')
+                    raw = fields.get('sizeondisk')
+                    size = int(raw) if isinstance(raw, str) and raw.isascii() and raw.isdigit() and len(raw) <= 18 else None
+                    kind = 'tool' if TOOLS.match(name) else 'game'
+                    lib['apps'].append({'appid': appid, 'name': name, 'bytes': size, 'kind': kind})
+                    if size is None:
+                        lib['unknownSizes'] += 1
+                    else:
+                        lib['recordedBytes'] += size
+                        lib['toolBytes' if kind == 'tool' else 'gameBytes'] += size
+                except (OSError, ValueError, UnicodeError) as error:
+                    lib['issues'].append({'file': Path(manifest).name,
+                                          'state': state(error) if isinstance(error, OSError) else 'invalid-metadata'})
+            lib['apps'].sort(key=lambda app: (app['bytes'] is None, -(app['bytes'] or 0), app['name'].lower()))
+            if lib['issues']:
+                lib['state'] = 'partial'
+        except OSError as error:
+            lib['state'] = state(error)
+        libraries.append(lib)
+    return {'time': time.time(), 'home': capacity(home), 'discovery': discovery, 'libraries': libraries}
+
+
+if __name__ == '__main__':
+    print(json.dumps(inventory()))

ui/frame_stream_stats.py

@@ -0,0 +1,88 @@
+"""The desktop stream's timing records, in the Mac viewer/bench schema.
+
+Times are host monotonic microseconds. Zero means unknown, never a fabricated
+capture/display timestamp. Storage is bounded to the same 4096/512 records as
+Stats.swift. The existing macview-bench.py grades these records unchanged.
+"""
+from collections import OrderedDict
+import threading
+
+
+def distribution(values):
+    values = sorted(v for v in values if v is not None)
+    if not values:
+        return {}
+    return {key: round(values[min(len(values)-1, int((len(values)-1)*p + .5))], 1)
+            for key, p in (('p50', .5), ('p95', .95))}
+
+
+class Stats:
+    def __init__(self, now):
+        self.now, self.lock = now, threading.RLock()
+        self.frames, self.inputs = OrderedDict(), OrderedDict()
+        self.captured = self.skipped = self.dropped = 0
+        self.rtt, self.decoder, self.synced = 0, '', False
+        self.sequence = 0
+
+    def add(self, **values):
+        with self.lock:
+            self.sequence = (self.sequence + 1) & 0xffffffff
+            record = dict.fromkeys(('s', 'k', 'b', 'w', 'h', 'cap', 'arr', 'e0', 'e1', 'snd',
+                                    'wire', 'rx', 'dec', 'drw', 'vs', 'echo', 'tier', 'br'), 0)
+            record.update(values, s=self.sequence)
+            self.frames[self.sequence] = record
+            while len(self.frames) > 4096:
+                self.frames.popitem(last=False)
+            for event in self.inputs.values():
+                if not event['frame'] and event['inj'] <= record['cap']:
+                    event.update(frame=self.sequence, cap=record['cap'])
+                    record['echo'] = event['id']
+            return record
+
+    def report(self, message):
+        with self.lock:
+            if message['t'] == 'rx':
+                frame = self.frames.get(message.get('s'))
+                if frame and isinstance(message.get('r'), (int, float)):
+                    frame['rx'] = int(message['r'])
+            elif message['t'] == 'fd':
+                for item in message.get('f', [])[:4096]:
+                    if isinstance(item, list) and len(item) >= 4:
+                        frame = self.frames.get(item[0])
+                        if frame:
+                            for name, val in zip(('dec', 'drw', 'vs'), item[1:4]):
+                                if isinstance(val, (int, float)):
+                                    frame[name] = int(val)
+                self.dropped += max(0, int(message.get('drop', 0)))
+            elif message['t'] == 'clock':
+                self.rtt = float(message.get('rtt', 0))
+                self.decoder = str(message.get('dec', ''))[:1024]
+                self.synced = True
+
+    def input(self, m):
+        if not isinstance(m.get('i'), int) or not m['i']:
+            return
+        with self.lock:
+            self.inputs[m['i']] = dict(id=m['i'], kind=m['t'], tv=m.get('tv') or 0,
+                                       inj=self.now(), frame=0, cap=0)
+            while len(self.inputs) > 512:
+                self.inputs.popitem(last=False)
+
+    def summary(self):
+        with self.lock:
+            now = self.now()
+            frames = [f for f in self.frames.values() if f['cap'] >= now-2000000]
+            out = dict(captured=self.captured, skipped=self.skipped, dropped=self.dropped,
+                       rtt=self.rtt, decoder=self.decoder, synced=self.synced,
+                       fps=sum(f['vs'] > 0 for f in frames)/2, sentFps=len(frames)/2,
+                       mbps=round(sum(f['b'] for f in frames)*4/1e6, 2))
+            for key, start, end in (('capture', 'cap', 'arr'), ('queue', 'arr', 'e0'),
+                                    ('encode', 'e0', 'e1'), ('network', 'e1', 'rx'),
+                                    ('decode', 'rx', 'dec'), ('draw', 'dec', 'drw'), ('total', 'cap', 'drw')):
+                out[key] = distribution([(f[end]-f[start])/1000 for f in frames if f[start] and f[end]])
+            return out
+
+    def snapshot(self, since=0, settle=1500000):
+        with self.lock:
+            return dict(frames=[dict(f) for f in self.frames.values() if f['s'] > since and f['cap'] <= self.now()-settle],
+                        inputs=[dict(i) for i in self.inputs.values()], captured=self.captured, summary=self.summary())

ui/index.html

@@ -175,7 +175,8 @@
   .dev-panel select, .dlg select { background: rgba(0,0,0,.28); color: var(--text); border: 1px solid transparent; border-radius: 3px;
                                    padding: 8px 8px; font: inherit; font-size: 13px; }
   .addr .t { overflow-wrap: anywhere; }
-  .addr .s, .dev-problem .s { white-space: normal; }
+  .addr .s { white-space: normal; }
+  .item.dev-problem .s { white-space: normal; overflow-wrap: anywhere; }
   .addr-edit { display: grid; grid-template-columns: 2fr 1fr 1.4fr auto auto; gap: 8px; align-items: center; width: 100%; }
   .addr-add { display: grid; grid-template-columns: 2fr 1.4fr auto; gap: 8px; margin-top: 12px; }
   @media (max-width: 700px) { .dev-form, .addr-edit, .addr-add, .adv .dev-form, .conn-add, .conn-edit { grid-template-columns: 1fr; } }
@@ -1018,6 +1019,9 @@
     #appsLinux .row { flex-wrap:wrap!important; }
   }
 
+  #storage .card { padding:16px; border:1px solid rgba(255,255,255,.1); border-radius:8px; margin-top:16px; }
+  #storage .grow, #storage .sub { overflow-wrap:anywhere; }
+  #storage .item > span { flex-shrink:0; }
 </style>
 <link rel="stylesheet" href="/control-center.css">
 </head>
@@ -1124,7 +1128,10 @@
           <div><dt>Battery power · signed</dt><dd data-cc-metric="power">Unavailable</dd></div><div><dt>Charger</dt><dd data-cc-metric="charger">Unavailable</dd></div>
           <div><dt>Battery temperature</dt><dd data-cc-metric="batteryTemp">Unavailable</dd></div><div><dt>Battery health</dt><dd data-cc-metric="batteryHealth">Unavailable</dd></div>
           <div><dt>Battery estimate</dt><dd data-cc-metric="estimate">Unavailable</dd></div>
-        </dl><p class="cc-note">Positive battery watts mean charging; negative means discharge. Estimates are reported by the battery and may be unavailable.</p>
+          <div><dt>Charge cycles</dt><dd data-cc-metric="cycles">Unavailable</dd></div><div><dt>Full charge capacity</dt><dd data-cc-metric="fullCapacity">Unavailable</dd></div>
+          <div><dt>Design capacity</dt><dd data-cc-metric="designCapacity">Unavailable</dd></div><div><dt>Full / design capacity</dt><dd data-cc-metric="capacityHealth">Unavailable</dd></div>
+          <div><dt>Battery source</dt><dd data-cc-metric="batterySource">Unavailable</dd></div>
+        </dl><p class="cc-note">Positive battery watts mean charging; negative means discharge. Unavailable sensors are not reported, unreadable or invalid. Health is the driver’s status; full / design capacity is a fuel-gauge estimate, not a diagnosis. Charge limits are unsupported on Frame.</p>
         <div class="cc-services" id="ccServices"></div>
       </details>
     </section>
@@ -1420,7 +1427,7 @@
 
   <div class="page" data-page="tools">
 <div class="workspace-heading"><div><a href="#tools" id="toolBack" class="workspace-link" hidden>← All tools</a><h1 id="toolTitle">Tools</h1><p id="toolSubtitle">Choose a task for your Frame.</p></div></div>
-<div id="toolDirectory"><section class="tool-group"><h2>Content & files</h2><div class="quick-routes"><a href="#transfer"><span>Send to Frame</span><small>Add files, APKs or your own games</small></a><a href="#media"><span>Media player</span><small>Play your own videos and media</small></a><a href="#linuxApps"><span>Linux apps</span><small>Install and manage desktop apps</small></a></div></section><section class="tool-group"><h2>Play & control</h2><div class="quick-routes"><a href="#capture"><span>Capture & Live</span><small>See and control the headset view</small></a><a href="#pad" title="Type on the headset (T)"><span>Type on the headset</span><small>Keyboard, trackpad and clipboard</small></a><a href="#panels"><span>Panel switcher</span><small>Bring an open panel into view</small></a><a href="#vrTools"><span>VR tools</span><small>Performance HUD and VR utilities</small></a><a href="#comfort"><span>Family & comfort</span><small>Session reminders and breaks</small></a><a href="#macview" id="macToolLink" hidden><span>Mac in the headset</span><small>Share Mac windows and displays</small></a></div></section><section class="tool-group"><h2>Your Frame</h2><div class="quick-routes"><a href="#backup" id="backupToolLink"><span>Backup &amp; recovery</span><small>Save games and settings, restore after a reset</small></a></div><a class="workspace-link" href="#settings">Connection, display &amp; preferences →</a></section><section class="tool-group"><h2>Assistant</h2><a class="workspace-link" href="/assistant">Open assistant &amp; AI agents →</a><p class="sub">Use your own model endpoint or review a proposed MCP action.</p></section></div>
+<div id="toolDirectory"><section class="tool-group"><h2>Content & files</h2><div class="quick-routes"><a href="#transfer"><span>Send to Frame</span><small>Add files, APKs or your own games</small></a><a href="#media"><span>Media player</span><small>Play your own videos and media</small></a><a href="#linuxApps"><span>Linux apps</span><small>Install and manage desktop apps</small></a></div></section><section class="tool-group"><h2>Play & control</h2><div class="quick-routes"><a href="#capture"><span>Capture & Live</span><small>See and control the headset view</small></a><a href="#pad" title="Type on the headset (T)"><span>Type on the headset</span><small>Keyboard, trackpad and clipboard</small></a><a href="#panels"><span>Panel switcher</span><small>Bring an open panel into view</small></a><a href="#vrTools"><span>VR tools</span><small>Performance HUD and VR utilities</small></a><a href="#comfort"><span>Family & comfort</span><small>Session reminders and breaks</small></a><a href="#macview" id="macToolLink" hidden><span>Mac in the headset</span><small>Share Mac windows and displays</small></a><a href="#macview" id="pcToolLink" hidden><span>PC in the headset</span><small>Experimental: share this PC's screen</small></a></div></section><section class="tool-group"><h2>Your Frame</h2><div class="quick-routes"><a href="#storage"><span>Game storage</span><small>Free space and Steam install sizes</small></a><a href="#backup" id="backupToolLink"><span>Backup &amp; recovery</span><small>Save games and settings, restore after a reset</small></a></div><a class="workspace-link" href="#settings">Connection, display &amp; preferences →</a></section><section class="tool-group"><h2>Assistant</h2><a class="workspace-link" href="/assistant">Open assistant &amp; AI agents →</a><p class="sub">Use your own model endpoint or review a proposed MCP action.</p></section></div>
   <div class="grid-3" id="toolWorkspace">
 <section class="panel" id="vrTools">
     <div class="shelf-head"><h2>VR comfort and performance</h2><span class="spacer"></span><span class="sub" id="vrUpdated">Waiting for the Frame</span></div>
@@ -1667,6 +1674,17 @@
         Saved spatial layouts are not available yet.</div>
     </section>
 
+    <section class="panel" id="storage" hidden>
+      <div class="shelf-head"><h2>Game storage</h2><span class="spacer"></span><button class="small" id="storageRefresh">Refresh</button></div>
+      <p class="sub">Read-only snapshot. Steam's recorded install sizes may be stale and exclude saves, shaders, downloads, Android and sideloaded content. No files are scanned recursively or changed.</p>
+      <div id="storageResult" role="status" aria-live="polite">Open this tool to read headset storage.</div>
+      <div class="card" style="margin-top:16px"><h3>Move a game with Steam</h3>
+        <p>On the headset, open Steam → Settings → Storage, choose the source drive, select the game, then choose Move and a destination. If Storage is unavailable in the headset UI, use desktop Steam’s Settings → Storage.</p>
+        <p class="sub">Steam offers destinations it supports. Let Steam finish and handle any errors, then Refresh here. Frame Control cannot verify a supported move API or its recovery behaviour, so it never moves or deletes game files.</p>
+        <a href="https://help.steampowered.com/en/faqs/view/4BD4-4528-6B2E-8327#move" target="_blank" rel="noopener">Steam's storage and moving guide ↗</a>
+      </div>
+    </section>
+
     <section class="panel" id="backup" hidden>
       <div class="shelf-head"><h2>Back up the Frame</h2><span class="spacer"></span>
         <button class="small" id="backupFolder">Open backups folder</button></div>
@@ -1703,8 +1721,19 @@
     </section>
 
     <section class="panel" id="macview" hidden>
-      <div class="shelf-head"><h2>Mac in the headset</h2><span class="count" id="mvCount"></span><span class="spacer"></span>
+      <div class="shelf-head"><h2 id="mvTitle">Mac in the headset</h2><span class="tag" id="mvTag" hidden>Experimental</span><span class="count" id="mvCount"></span><span class="spacer"></span>
         <button class="small" id="mvRefresh">Refresh</button></div>
+      <div id="mvPc" hidden>
+        <p class="hint" style="color:var(--warn)">Experimental. Shows a whole PC screen as a panel in the
+          headset, with laser and keyboard input. Individual windows are offered only when this build supports them.
+          Tested in a Windows VM; physical PCs, hardware encoding and laser clicks remain unverified. Clicks and keys
+          can't reach administrator apps or the sign-in screen.
+          <a href="https://github.com/saphid/frame-control/blob/main/docs/pc-in-headset.md" target="_blank" rel="noopener noreferrer">What's verified</a></p>
+        <label class="mv-opt"><input type="checkbox" id="mvPcOn"> Turn on PC in the headset
+          <span class="sub">off by default; nothing runs and no windows are listed until it's on</span></label>
+        <div class="sub" id="mvPcState" role="status" aria-live="polite" hidden></div>
+      </div>
+      <div id="mvMain">
       <label class="mv-opt"><input type="checkbox" id="mvSeparate" checked> Give each window its own display
         <span class="sub">its menus and sheets come along, nothing covers it, and it goes back when you stop</span></label>
       <div class="row" style="margin:0 0 12px"><label for="mvQuality">Picture quality</label>
@@ -1721,7 +1750,8 @@
         <button class="small danger" data-mv="stopall">Stop all</button>
       </div>
       <div class="hint">Each window or screen becomes its own panel in the headset. Place it with the SteamVR dashboard
-        (Float in World, Move, Size). Point and click with the laser, scroll with the thumbstick, and type on the Mac's keyboard.</div>
+        (Float in World, Move, Size). Point and click with the laser, scroll with the thumbstick, and type on your computer's keyboard.</div>
+      </div>
     </section>
 
     <section class="panel" id="privacy">
@@ -1969,6 +1999,8 @@
     <input type="text" id="caLabel" maxlength="60" placeholder="Label, e.g. Home" aria-label="Label for the new address">
     <button class="small" type="submit">Add</button></form>
   <details class="conn-more" id="connMore"><summary>Connection steps</summary>
+    <p class="sub">Trouble setting up or pairing? <a href="https://github.com/saphid/frame-control/blob/main/docs/frame-doctor.md" target="_blank" rel="noopener noreferrer">Read-only diagnostic guide</a>
+      explains how to check a connection without sharing passwords or keys.</p>
     <ol class="stages" id="connStages"></ol>
     <h3>This computer</h3>
     <dl class="facts" id="connNet"></dl>
@@ -2410,12 +2442,11 @@ $("castBtn").onclick = () => {
 // ---- battery ----
 function battery(b, power) {
   const pct = b?.percent;
-  const full = b?.status === "Full" || (!!power && pct >= 100);
+  const full = b?.status === "Full";
   const charging = !full && b?.status === "Charging";
   // A weak charger can lose to the load: plugged in but still draining.
   // Topped up on a charger it reports Discharging at ~0 W: that's idle, not draining.
   const idle = !!power && b?.watts != null && Math.abs(b.watts) < 0.5;
-  const draining = !full && !charging && !idle && (!power || b?.status === "Discharging" || b?.watts < 0);
   const low = !charging && !full && pct != null && pct <= 15;
   const color = full || charging ? "#59bf40" : low ? "#d94126" : pct != null && pct <= 30 ? "#d9a23a" : "#dcdedf";
 
@@ -2425,7 +2456,8 @@ function battery(b, power) {
   else if (charging) {
     label = b.watts > 0 ? `Charging · ${b.watts.toFixed(1)} W` : "Charging"; cls = "charging";
     if (b.timeToFull > 0) detail.push(`Full in ${dur(b.timeToFull)}`);
-  } else if (!draining) { label = "Plugged in, not charging"; cls = "draining"; }
+  } else if (b.status === "Not charging" || idle) { label = "Not charging"; cls = "draining"; }
+  else if (b.status !== "Discharging") { label = "Charging state unavailable"; cls = "draining"; }
   else {
     label = low ? "Battery low" : power ? "Plugged in, still draining" : "On battery";
     cls = low ? "low" : "draining";
@@ -5413,6 +5445,39 @@ $("panelList").onclick = e => {
   act("Show panel", () => api("/api/panels", {action: "focus", key: b.dataset.panel}), b);
 };
 
+// ---- Read-only game storage ----
+let storageSeq = 0;
+const storageState = s => ({'permission-denied':'Permission denied', missing:'Missing or disconnected',
+  unavailable:'Unavailable', 'invalid-metadata':'Invalid Steam metadata', partial:'Partial inventory', ok:'Available'}[s] || 'Unknown');
+const storageBytes = n => typeof n === 'number' && Number.isFinite(n) && n >= 0 ? sizeText(n) : 'Unknown';
+function storageCapacity(c) {
+  if (!c || c.state !== 'ok') return esc(storageState(c?.state));
+  return `${storageBytes(c.free)} free / ${storageBytes(c.total)} total · ${storageBytes(c.used)} used`;
+}
+function renderStorage(r) {
+  return `<div class="card"><h3>Headset user filesystem</h3><p>${storageCapacity(r.home)}</p>
+    <p class="sub">Filesystem space available to your user; excludes separate system partitions. Reserved space can make used + free less than total.</p></div>` +
+    (r.discovery !== 'ok' ? `<p class="sub">Library discovery: ${esc(storageState(r.discovery))}. Additional libraries may be absent from this view.</p>` : '') +
+    r.libraries.map(lib => `<div class="card" style="margin-top:16px"><h3 style="overflow-wrap:anywhere">${esc(lib.path)}</h3>
+      <p>${storageCapacity(lib.capacity)}</p><p class="sub">Filesystem containing this library path; paths on the same filesystem share this space. Capacities must not be added together.</p>
+      <p>${esc(storageState(lib.state))} · Known games/apps: ${storageBytes(lib.gameBytes)} · Known runtimes / tools (by name): ${storageBytes(lib.toolBytes)}</p>
+      <p class="sub">Known recorded content: ${storageBytes(lib.recordedBytes)} · ${lib.unknownSizes} unknown sizes · ${lib.issues.length} unreadable / invalid manifests. Other usage is unmeasured.</p>
+      <div class="list">${lib.apps.map(app => `<div class="item"><div class="grow">${esc(app.name)}<div class="sub">Steam ${esc(app.appid)} · ${app.kind === 'tool' ? 'Runtime / tool' : 'Game / app'}</div></div><span>${storageBytes(app.bytes)}</span></div>`).join('') || '<p class="sub">No readable Steam manifests found; this does not prove the library is empty.</p>'}</div>
+      ${lib.issues.map(i => `<p class="sub">${esc(i.file)}: ${esc(storageState(i.state))}</p>`).join('')}</div>`).join('') +
+      `<p class="sub">Snapshot received ${esc(new Date().toLocaleTimeString())}. Refresh after installs, downloads or moves.</p>`;
+}
+async function loadStorage() {
+  const seq = ++storageSeq, gen = devGen;
+  $('storageResult').textContent = 'Reading headset storage…';
+  try {
+    const result = await api('/api/storage');
+    if (seq === storageSeq && gen === devGen) $('storageResult').innerHTML = renderStorage(result);
+  } catch (error) {
+    if (seq === storageSeq && gen === devGen) $('storageResult').textContent = `Storage unavailable: ${error.message}`;
+  }
+}
+$('storageRefresh').onclick = loadStorage;
+
 // ---- Backup and recovery kit (ui/frame_backup.py) ----
 const BACKUP_KIND = {saves: "Game saves", settings: "Settings", android: "Android app data"};
 function sizeText(n) {
@@ -5546,7 +5611,7 @@ $("sessionGame").onclick = e => {
 };
 
 // ---- Mac in the headset: windows and displays as panels (ui/frame_macview.py) ----
-let mvSeq = 0, mvTimer = 0;
+let mvSeq = 0, mvTimer = 0, mvPcAsked = false;
 // streaming: the src it's shown as (a window may be "separate:<id>"), or "".
 // How a live stream is doing: frames shown, Mac-to-headset delay, bitrate, and
 // whether the network made it step down (fewer frames, then fewer pixels).
@@ -5572,9 +5637,27 @@ async function loadMacView(restart) {
   try { s = await api("/api/macview" + (restart ? "?restart=1" : "")); } catch (e) { err = e; }
   if (seq !== mvSeq || location.hash !== "#macview") return;
   const box = $("macview");
-  if (err) { box.hidden = false; return failed($("mvWindows"), err); }
-  if (!s.available) { box.hidden = true; return; }
+  if (err) { box.hidden = $("mvMain").hidden = false; return failed($("mvWindows"), err); }
+  // PC in the headset (Windows, Experimental) is off until turned on here.
+  const pc = !!s.host && s.host !== "mac";
+  $("mvTitle").textContent = pc ? "PC in the headset" : "Mac in the headset";
+  $("mvTag").hidden = $("mvPc").hidden = !pc;
+  $("mvPcOn").checked = !!s.enabled;
+  if (pc && !s.enabled && clientPreferences.get("pcView") === "1" && !restart && !mvPcAsked) {
+    mvPcAsked = true;  // once per page: a failure to start shouldn't loop
+    return mvPcEnable(true, true);
+  }
+  if (!s.available) {
+    box.hidden = !pc;
+    $("mvMain").hidden = true;
+    $("mvCount").textContent = "";
+    if (pc) { $("mvPcState").textContent = s.reason || ""; $("mvPcState").hidden = !s.reason; }
+    return;
+  }
   box.hidden = false;
+  $("mvMain").hidden = false;
+  $("mvPcState").hidden = true;
+  $("mvSeparate").closest("label").hidden = pc;  // separate virtual displays are a Mac feature
   const live = new Set((s.streams || []).map(x => x.src));
   const byStream = src => (s.streams || []).find(x => x.src === src);
   $("mvCount").textContent = live.size ? `${live.size} showing${s.route === "usb" ? " · over USB-C" : ""}` : "";
@@ -5584,6 +5667,7 @@ async function loadMacView(restart) {
   $("mvPerm").hidden = !perm.length;
   $("mvPerm").innerHTML = perm.join(" ") + `<div class="row"><button class="small action" data-mv="perm">Allow…</button>
     <span class="sub">Then press Refresh. macOS may ask you to reopen Frame Control.</span></div>`;
+  if (pc) $("mvPerm").hidden = true;  // Windows asks for no permission; elevated apps just refuse input
   const liveAs = src => live.has(src) ? src : src.startsWith("window:") && live.has("separate:" + src.slice(7)) ? "separate:" + src.slice(7) : "";
   $("mvDisplays").innerHTML = (s.displays || []).map(d =>
     mvRow(d.src, `Whole screen: ${d.name}`, `${d.w}×${d.h}${d.main ? " · main display" : ""}`, d.w, d.h, liveAs(d.src), byStream(liveAs(d.src)))).join("");
@@ -5591,16 +5675,26 @@ async function loadMacView(restart) {
   $("mvWinCount").textContent = wins.length ? `${wins.length}` : "";
   $("mvWindows").innerHTML = !s.screen ? `<div class="sub">Windows appear here once Screen Recording is allowed.</div>`
     : wins.length ? wins.map(w => mvRow(w.src, w.title || w.app, `${w.title ? w.app + " · " : ""}${w.w}×${w.h}`, w.w, w.h, liveAs(w.src), byStream(liveAs(w.src)))).join("")
-    : `<div class="sub">No windows open on this Mac's current desktop.</div>`;
+    : `<div class="sub">${pc && s.windowCaptureReason ? esc(s.windowCaptureReason) : `No windows open on this ${pc ? "PC" : "Mac's current desktop"}.`}</div>`;
   // Keep the numbers fresh while something is in the headset and the card is on screen.
   clearTimeout(mvTimer);
   const tick = () => { mvTimer = document.hidden || !box.offsetParent ? setTimeout(tick, 3000) : (loadMacView(), 0); };
   if (live.size) mvTimer = setTimeout(tick, 3000);
 }
 $("mvRefresh").onclick = () => loadMacView(true);
+// The choice is remembered on this computer; the server starts with it off.
+async function mvPcEnable(on, quiet) {
+  if (!quiet) clientPreferences.set("pcView", on ? "1" : "0");
+  const turn = () => api("/api/macview", { action: "enable", on });
+  if (quiet) { try { await turn(); } catch {} }
+  else await act(on ? "Turn on PC in the headset" : "Turn off PC in the headset", async () =>
+    ({ ...await turn(), message: on ? "PC in the headset is on." : "PC in the headset is off. Nothing is shared." }), $("mvPcOn"));
+  loadMacView();
+}
+$("mvPcOn").onchange = e => mvPcEnable(e.target.checked);
 // ---- client preferences: native storage survives changing localhost origins ----
 const clientPreferences = (() => {
-  const keys = ['mvSeparate', 'padUsed'], values = {}, changed = new Set();
+  const keys = ['mvSeparate', 'padUsed', 'pcView'], values = {}, changed = new Set();
   const valid = value => value === '0' || value === '1';
   const remember = (key, value) => {
     values[key] = value;
@@ -5637,7 +5731,7 @@ $("macview").onclick = async e => {
   const b = e.target.closest("[data-mv]"); if (!b) return;
   const src = b.dataset.src;
   if (b.dataset.mv === "show") {
-    const as = $("mvSeparate").checked && src.startsWith("window:") ? "separate:" + src.slice(7) : src;
+    const as = !$("mvSeparate").closest("label").hidden && $("mvSeparate").checked && src.startsWith("window:") ? "separate:" + src.slice(7) : src;
     await act(`Show ${b.dataset.title} in the headset`, async () => {
       const r = await api("/api/macview", { action: "show", src: as, quality: $("mvQuality").value,
                                             w: +b.dataset.w || undefined, h: +b.dataset.h || undefined });
@@ -5658,10 +5752,10 @@ const PAGES = ["apps", "games", "tools", "settings"];
 const SECONDARY_PAGES = ["home", "capture", "devices", "control"];
 const SECTION_PAGE = {library:"games", discover:"apps", android:"apps", view:"capture", shots:"capture", device:"home",
   vrTools:"tools", comfort:"tools", assistant:"tools", pad:"tools", sideloaded:"games", getgames:"games", steamStore:"games", androidLibrary:"apps", appStore:"apps", linuxApps:"apps",
-  display:"settings", androidSettings:"settings", transfer:"tools", media:"tools", artworkSettings:"settings", autoSync:"settings", power:"settings", macview:"tools", privacy:"settings", panels:"tools", backup:"tools"};
+  display:"settings", androidSettings:"settings", transfer:"tools", media:"tools", artworkSettings:"settings", autoSync:"settings", power:"settings", macview:"tools", privacy:"settings", panels:"tools", storage:"tools", backup:"tools"};
 const TOOL_TITLES = {transfer:"Send to Frame", media:"Media player", artworkSettings:"Library artwork", autoSync:"Copy to this computer",
   pad:"Type on the headset", panels:"Panel switcher", vrTools:"VR tools", comfort:"Family & comfort", androidSettings:"App display & reports",
-  power:"Remote & power", macview:"Mac in the headset", privacy:"Privacy & updates", backup:"Backup & recovery"};
+  power:"Remote & power", macview:"Mac in the headset", privacy:"Privacy & updates", storage:"Game storage", backup:"Backup & recovery"};
 const workspace = {source:"all", scope:"installed", apps:"installed", scroll:new Map(), key:null, hash:null, y:0};
 let page = "apps";
 // Reuse the existing live lists and form handlers in their new destinations.
@@ -5768,6 +5862,7 @@ function showPage(e) {
   if (tool === 'macview') loadMacView();
   if (tool === 'panels') loadPanelSwitcher();
   if (tool === 'backup') loadBackups();
+  if (tool === 'storage') loadStorage();
   if (tool === 'androidSettings') {
     $('repNew').hidden = false; $('androidSettings').prepend($('repNew')); loadDisplays();
   }
@@ -6524,7 +6619,7 @@ function renderPill() {
   }
   $("conn").innerHTML = `<span class="dot ${dot}"></span><span class="pt"><b>${esc(dev)}</b><span>${esc(word)}` +
     `${via ? `<span class="via"> · ${esc(via)}</span>` : ""}</span></span>`;
-  $("conn").title = `${dev}: ${detail}. Click to see or change its addresses.`;
+  $("conn").title = `${dev}: ${detail.replace(/[.\s]+$/, "")}. Click to see or change its addresses.`;
   return true;
 }
 window.connPill = renderPill;
@@ -6746,6 +6841,7 @@ function onConnection(s) {
     androidApps = []; androidSeq++; androidPending.clear(); $('installedDetail').close(); resetShots(); resetClips();
     renderHome();
     titlesSeq++; disp.seq++; runningSeq++;  // answers to loads already on their way are ignored
+    $('storageResult').textContent = 'Headset changed. Open Game storage or Refresh to read this headset.';
     runningGames = []; $("nowRunning").hidden = true; $("runningList").innerHTML = "";
     if (cat.apps) filterCatalog();  // "Installed" tags were the other headset's
     // Confirmations still open were checked against the other headset.
@@ -7160,6 +7256,8 @@ api("/api/host").then(h => {
   Object.assign(HOST, h);
   window.frameControlCenter?.host(h);
   $("macToolLink").hidden = h.mobile || h.os !== "macOS";
+  $("pcToolLink").hidden = h.mobile || h.os !== "Windows";
+  if (!h.mobile && h.os === "Windows") TOOL_TITLES.macview = "PC in the headset";
   $("backupToolLink").hidden = !!h.mobile;  // backups are folders on a computer
   if (h.mobile) return;
   $("offSetup").hidden = false; $("offSetup").onclick = setUpActive;  // the server opens it in a terminal

ui/mac-view.html

@@ -22,7 +22,7 @@
 </head>
 <body>
 <canvas id="c" width="16" height="9"></canvas>
-<div id="note">Connecting to the Mac…</div>
+<div id="note">Connecting to your computer…</div>
 <div id="hud" hidden></div>
 <script>
 "use strict";
@@ -243,14 +243,14 @@ async function connect() {
     // Refused before ever getting a key: the ticket expired or was revoked,
     // and retrying can't help.
     if (!reconnectKey && ++failedStarts >= 3) {
-      show("This view has expired. Press Show in Frame Control on the Mac to open it again.");
+      show("This view has expired. Press Show in Frame Control on your computer to open it again.");
       return;
     }
     hideNoteOnFrame = true;
     // The Mac may be asleep or the tunnel restarting: keep trying.
     retry = Math.min(retry + 1, 6);
     // Keep the Mac's reason (a missing permission, a closed window) on screen.
-    show(lastError ? `${lastError} Retrying…` : "Lost the Mac. Reconnecting…");
+    show(lastError ? `${lastError} Retrying…` : "Lost the computer. Reconnecting…");
     setTimeout(connect, 500 * 2 ** retry);
   };
 }
@@ -269,7 +269,7 @@ function control(m) {
     document.title = tag ? `${name} [${tag}]` : name;
     if (!m.input) {
       hideNoteOnFrame = false;  // a warning, not a connection notice: let it stay its 8 s
-      show("Clicks and keys need Accessibility permission on the Mac (Frame Control asks for it).", 8000);
+      show(m.inputMessage || "Clicks and keys need Accessibility permission on the Mac (Frame Control asks for it).", 8000);
     }
   } else if (m.t === "error") {
     stats.errors.push(m.message);
@@ -391,7 +391,7 @@ addEventListener("keydown", e => onKey(e, true));
 addEventListener("keyup", e => onKey(e, false));
 addEventListener("blur", () => send({ t: "release" }));
 
-show("Connecting to the Mac…");
+show("Connecting to your computer…");
 connect();
 </script>
 </body>

ui/server.py

@@ -59,6 +59,7 @@ import frame_contact  # noqa: E402
 import frame_host  # noqa: E402
 import frame_link  # noqa: E402
 import frame_macview  # noqa: E402
+import frame_pcview  # noqa: E402
 import frame_media  # noqa: E402
 import frame_panels  # noqa: E402
 import frame_quest  # noqa: E402
@@ -2832,12 +2833,13 @@ def push_media(path):
             "id": token + "/" + name}
 
 
-# ---- Mac in the headset (frame_macview.py) ----------------------------------
+# ---- Mac in the headset (frame_macview.py), PC in the headset (frame_pcview.py) ----
 
 # The tunnel gets its own connection: the shared master's options would win
 # over anything added after them.
-macview = frame_macview.MacView(["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=8"],
-                                lambda remote, stdin=None, timeout=30: ssh(remote, stdin=stdin, timeout=timeout),
+macview = frame_pcview.host_view(["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=8"],
+                                lambda remote, stdin=None, timeout=30: ssh(remote, stdin=stdin.encode("utf-8") if stdin is not None else None,
+                                                                           timeout=timeout, text=False).decode("utf-8", errors="replace"),
                                 FRAME, track=_live_tunnels.add)
 
 
@@ -2854,7 +2856,8 @@ def macview_state(query=None):
 
 
 def macview_action(body):
-    """{action: show|stop|permissions, src, quality, w, h}."""
+    """{action: show|stop|permissions, src, quality, w, h} | {action: enable, on}.
+    enable turns PC in the headset (Experimental, Windows only) on or off."""
     if LOCAL:
         raise Failure("Runs on your computer, not the headset.", 400)
     action = body.get("action")
@@ -2867,6 +2870,10 @@ def macview_action(body):
             return macview.stop(body.get("src") or None)
         if action == "permissions":
             return macview.request_permissions()
+        if action == "enable":
+            if not isinstance(macview, frame_pcview.PCView):
+                raise Failure("PC in the headset is only available on Windows.", 400)
+            return macview.set_enabled(body.get("on") is True)
     except frame_macview.MacViewError as e:
         raise Failure(str(e), 502)
     raise Failure("unknown action", 400)
@@ -3286,6 +3293,9 @@ class Handler(BaseHTTPRequestHandler):
                 self.send_json(json.loads(ssh("python3 -", stdin=(HERE / "frame_computer.py").read_text(), timeout=20)))
             elif path == "/api/status":
                 self.send_json(status({}))
+            elif path == "/api/storage":
+                with working(self.headers.get("X-Frame-Device")):
+                    self.send_json(json.loads(ssh("python3 -", stdin=(HERE / "frame_storage.py").read_text(), timeout=20)))
             elif path == "/api/running":
                 self.send_json(running_games())
             elif path == "/api/steam/owned":