README: Live view

- Sound: the default output's pulse monitor (what the headset plays) as AAC in the same fMP4; the
  player starts muted (browser autoplay rules) with a Sound on button. Video timestamps go to the
  wall clock (-ts mono2abs) instead of forcing it on the pulse input, which gave bursts of AAC packets
  one shared timestamp; aresample=async=1 keeps the sound continuous.
- Late viewers start at a keyframe of the video track (audio samples are all sync).
- Qualities 360p/480p/720p/1080p scale down only; 'full' sends SteamVR's headset view at its own
  size (1920x1080 today; v4l2cam has no size option, so 2K/4K would only upscale).
- Player keeps a 0.3 s cushion and catches up at 1.1x; it seeks only when >2 s behind (seeking to the
  very edge starved playback).

CLAUDE.md

@@ -26,7 +26,15 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
     launch.sh logs `start/end <unix>` to `<anchor>/plays.log` (upgrade_launchers adds it; Proton launchers exec → start
     only) and shots are matched by time; thumbnails cached in `<data>/screenshots-cache/<frame>/`, shown by asset URL;
     delete leaves screenshots.vdf alone (Steam rewrites it at exit); game menu → "Screenshots" = `go("screenshots",
-    pkg)`); settings; welcome; activity panel). Files, Screenshots and the Library share right-click menus
+    pkg)`); live view (`views/live.py` + `install/livestream.py`: the Frame's built-in SteamVR "headset view" webcam
+    (`steamvr-v4l2cam.service` → v4l2loopback "SteamVR" /dev/video99, see docs/FRAME_RUNTIME.md) + the default
+    output's pulse monitor (sound) → ffmpeg/x264 + AAC (qualities scale down only; "full" = SteamVR's size) →
+    fragmented MP4 on an SSH exec channel's stdout (the script stops ffmpeg on stdin EOF) → relay on 127.0.0.1 (keeps
+    init + fragments since the last keyframe of the *video* track for late viewers) → player page
+    `install/live_player.py` (MSE; starts muted as browsers require, "Sound on" button; 0.3 s cushion, catches up at
+    1.1x, seeks only when >2 s behind: seeking to the very edge starved it) opened
+    in the user's default browser: Flet can't show video outside `flet build` bundles; the stream outlives the tab and
+    stops on disconnect/window close); settings; welcome; activity panel). Files, Screenshots and the Library share right-click menus
     (one `ft.ContextMenu` per view, filled on right-click; on one of several selected items they act on the whole
     selection, `C.menu_targets`) and click-and-drag multi-select (`C.DragSelect`: pan start/end on the area + item
     hover events, which Flutter also sends with the button held; Flet can't report item positions, so no rubber band).
@@ -514,7 +522,7 @@ lacks (ActivityNotFoundException) → imported by hand: libmain.so + game.json
 DATA/ → external files/WiiCompiledOpenXRVR/DATA, MOD/ → .../RetroRewind6 (decompiled with jadx). Lepton has no
 picker at all: a FramePort fix would be an injected picker activity. Generated cover/banner art used to suppress the
 Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
-**Steam library failures (GitHub #21/#30):** on some Frames Steam never loads FramePort's shortcuts.vdf entries (same SteamOS build and arm64 beta client as the dev Frame; IDs correct; file written before Steam starts): Play → console_log `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` (= "Game configuration unavailable", Steam treats the id as a store app). Cause unknown; agent v42/43 diagnostics: `launch` returns `steam` (started / error + code / silent from console_log), `collect_diag` adds `steam_library` (real Steam dir, beta, Steam start vs vdf write time, entries per account, devkit games) + `steam-console.txt` (incl. Steam's `logs/shortcuts.previous.txt` if present; steamclient.so has "LoadShortcuts: rejecting attempt to load shortcuts: invalid account ID"). **Fallback (agent v43):** when Play gets AppError_9 the agent registers the game through Steam's devkit interface (what Valve's Devkit Management Tool does, MIT: `devkit-1 steam://devkit-1/<~/.steam/steam.token>/create-shortcut?response=<file>&gameid=<id>&directory=~/devkit-game` written to ~/.steam/steam.pipe; answer file / `.error`; `~/devkit-game/<id>/launch.sh` = link to the game's launch.sh, `<id>-argv.json` ["launch.sh"] (relative to the folder), `<id>-settings.json` {steam_play 0, compat_tool ""}). Steam adds it live (no restart), picks its own appid (read back from shortcuts.vdf by DevkitGameID), shows it as a normal non-Steam game named "Devkit Game: <id>" (OpenVR 0, but VR works: owner-verified 2026-10-04), art copied to grid/<appid>*. Ids: letter first, then letters/digits/_ only (spaces, '-', leading digit → "missing/invalid arguments"). Later Plays use the devkit entry; uninstall (`devkit_unregister`, `delete-shortcut` live) and purge remove it. Verified on the dev Frame: register/launch/unregister; the AppError_9 trigger itself only in unit tests.
+**Steam library failures (GitHub #21/#30):** on some Frames Steam never loads FramePort's shortcuts.vdf entries (same SteamOS build and arm64 beta client as the dev Frame; IDs correct; file written before Steam starts): Play → console_log `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` (= "Game configuration unavailable", Steam treats the id as a store app). Cause unknown; agent v42/43 diagnostics: `launch` returns `steam` (started / error + code / silent from console_log), `collect_diag` adds `steam_library` (real Steam dir, beta, Steam start vs vdf write time, entries per account, devkit games) + `steam-console.txt` (incl. Steam's `logs/shortcuts.previous.txt` if present; steamclient.so has "LoadShortcuts: rejecting attempt to load shortcuts: invalid account ID"). **Fallback (agent v43):** when Play gets AppError_9 the agent registers the game through Steam's devkit interface (what Valve's Devkit Management Tool does, MIT: `devkit-1 steam://devkit-1/<~/.steam/steam.token>/create-shortcut?response=<file>&gameid=<id>&directory=~/devkit-game` written to ~/.steam/steam.pipe; answer file / `.error`; `~/devkit-game/<id>/launch.sh` = link to the game's launch.sh, `<id>-argv.json` ["launch.sh"] (relative to the folder), `<id>-settings.json` {steam_play 0, compat_tool ""}). Steam adds it live (no restart), picks its own appid (read back from shortcuts.vdf by DevkitGameID), shows it as a normal non-Steam game named "Devkit Game: <id>" (OpenVR 0, but VR works: owner-verified 2026-10-04), art copied to grid/<appid>*. Ids: letter first, then letters/digits/_ only (spaces, '-', leading digit → "missing/invalid arguments"). Later Plays use the devkit entry; uninstall (`devkit_unregister`, `delete-shortcut` live) and purge remove it. Verified on the dev Frame: register/launch/unregister; the AppError_9 trigger itself only in unit tests. GitHub #42 (two Steam accounts, neither MostRecent): Steam rewrote the active account's shortcuts.vdf without FramePort's entries right after starting, and added the devkit entry live without saving it, so `devkit_appid` (vdf only) failed ("Steam added the devkit entry but didn't save it"); agent v55 `devkit_appid_from_log` reads Steam's `sanitize shortcut app id "~/devkit-game/<id>/launch.sh": replacing 0 with N` console line. GitHub #41 (one account): same Steam behaviour, and every install restarts Steam, which forgets the never-saved devkit entry. Agent v56: the log fallback reads only the current session's console_log.txt; Play re-registers a devkit entry that gets AppError_9; art updates also write the devkit entry's grid art (`copy_grid_art`). Open: why some Frames' Steam never loads or saves shortcuts.vdf (single account too).
 **Exit game (GitHub #36, 2026-10-04):** `Apps.TerminateApp` (what Exit game calls; reachable for tests through Steam's CEF devtools on 127.0.0.1:8080, SharedJSContext, `Runtime.evaluate` — a stdlib websocket client is enough) closed both a normal shortcut and a devkit entry on the dev Frame within 1-3 s. SIGTERM to Steam's `reaper` alone left launch.sh + Lepton (setsid) + the container running (an earlier headset launch ran on for 87 min); SIGTERM to launch.sh cleans up in ~4 s. Agent v44: launch.sh's 2 s loop ends the game when its parent (the reaper) is gone; `upgrade_launchers` (from ensure_host_fixes) adds that to existing launchers in place. Which in-headset exit path fails is still unknown. Screenshots on the Frame: all under SteamVR's appid 250820 (`760/remote/250820/screenshots`, screenshots.vdf has creation time, no game).
 **SteamVR dashboard at game start (2026-10-04):** the dashboard (Resume game / controller / VR options) was open whenever a FramePort game started (also over Lepton's 2D launcher). Steam's UI exposes `SteamClient.OpenVR.VROverlay.{IsDashboardVisible,HideDashboard,ShowDashboard}` (CEF devtools, `steam_js` in the agent). Agent v44: launch.sh starts `_dashboard_worker` (waits for FrameBridge's first `pacing:` line in launch.log, then hides a visible dashboard for 25 s, at most 3 times; log `<base>/dashboard.log`; opt out with env FRAMEPORT_KEEP_DASHBOARD=1). Verified on the dev Frame (dashboard shown → 4XVR launched via Steam → hidden ~5 s after the first frames); not yet seen in the headset. **Headset (ITR2, 2026-10-05): too late** — Steam shows its frame menu (`valve.steam.gamepadui.frame.menu`, vrwebhelper_systemui.txt `[PooledPopups] Showing`) ~0.3 s after the game's first submitted frame (FrameBridge `new layer:`), but the first `pacing:` summary comes ~8 s later; the owner had pressed Resume (`[HideDashboard] return_to_game`) before the worker looked. Agent v52: watches from the first `new layer:` line (incremental log reads, 0.5 s polls, 30 s window). Agent v53: stops for good once the player opens the dashboard with the controller (`toggle_dashboard_action` in vrwebhelper_systemui.txt since the worker started): v52 closed it 60 ms after each press, and the game, paused for it, stayed paused.
 **Space warp / ITR2 (2026-10-04):** Into The Radius 2 (UE5, `libUnreal.so` + OVRPlugin, Vulkan) uses Application SpaceWarp (extra swapchains `376x376 format=97` motion vectors + `format=129` depth); #35 reports flickering textures. OVRPort's `patch_disable_space_warp` has no effect on UE5, and hiding XR_FB_space_warp in FrameBridge's enumerate doesn't reach the game either: **OVRPort's dispatcher offers/enables XR_FB_space_warp itself**. FrameBridge `hide_space_warp` (per game, off) hides it and strips `XrCompositionLayerSpaceWarpInfoFB` (1000171000) from the projection views (log `hide_space_warp: removed space warp info`); the game still renders its MV swapchains. Test build installed on the dev Frame; flicker not yet checked in a headset. Heuristic: UE5 + OVRPlugin shows it as an option (off). `equirect_emul` is suggested for Unreal games whose graphics API isn't detected ("GLES or unknown"); on Vulkan it switches itself off (Myst/Riven/ITR2): harmless, but Unreal Vulkan detection is a known gap.
@@ -526,6 +534,7 @@ Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
 **Catalog updates without a release (2026-10-05):** apps fetch `catalog/games/*.yaml` from GitHub `main` (`recommend/catalog.refresh_remote`: one API call `git/trees/main?recursive=1` + raw.githubusercontent downloads of changed blobs, cached as `catalog-gh-<sha>.yaml`, every 6 h; GUI at start + Settings → Data "Check now"; CLI background thread + `frameport catalog-update`). `catalog.load()` only reads the cache. A remote entry is skipped (`unusable_reason`) when it names a patch/adapter key this app doesn't register, has a field `CatalogEntry` doesn't know, or `min_app` > this version: add `min_app` (or rely on new patch ids) when a config needs an unreleased FramePort. Remote beats bundled unless the bundled entry has a later updated/verified date; the user's own entries still win as before. Off: setting `catalog.auto_update`, env FRAMEPORT_NO_CATALOG_UPDATE; FRAMEPORT_CATALOG_URL still overrides the source. So: **pushing a catalog change to main reaches users within 6 h** (their recipes follow via catalog_rev → Update on Frame).
 **Start activity / QuestCraft / ITR2 pop-in (2026-10-05):** WiiCompiled's VR part (`QuestActivity`, SDL, process `:game`) stays behind Lepton's flat window when the launcher is shown (`device.text_input_window`). `frame.start_activity` (opt-in; analysis `extra.vr_activity` = the original APK's activity with Meta's VR category when it isn't the launcher) gives that activity's filter LAUNCHER and every other LAUNCHER becomes INFO, per element (`axml.set_start_activity`); Lepton's own `apk-info-extractor --print-activity-name` (on the Frame under Lepton/liblepton/apk_extractor) then answers QuestActivity. **OVRPort gives every MAIN activity LAUNCHER + VR categories**, so the VR activity must come from the original APK's analysis, not the converted manifest. Lepton has no activity override (`APP_ACTIVITY` is reset when app_metadata.sh is sourced). QuestCraft reaches Minecraft 1.21.5 (Fabric, Vivecraft, Sodium; LTW "Large Thin Wrapper" GL 3.0 on the Frame's Zink) and stops at `OpenGL error 1282` in `WindowFramebuffer` createTexture (Minecraft's crash report in `files/instances/1.21.5/crash-reports/`, Pojlib's `files/latestlog.txt`); the vrclient SIGSEGV / "pthread_mutex_lock called on a destroyed mutex" afterwards is only the shutdown (Unity's render thread still in vrclient while the instance is destroyed). ITR2 "models popping in and out" in game: Unreal reads user config from **internal** storage (`lepton-data/internal/<pkg>/files/UnrealGame/<Project>/<Project>/Saved/Config/Android/Engine.ini`, not external); `r.AllowOcclusionQueries=0` there broke its menus (removed again). Vulkan shim `vk_query_slots` (two slots per occlusion query) never saw ITR2 create an occlusion query pool, and the run with it crashed (Unreal RenderThread SIGSEGV, caught by sentry-native: no tombstone; the backtrace is in `cache/sentry/*/.sentry-native/*.run/*.envelope` with module offsets) - left off. Next suspect: Unreal 5 mobile HZB occlusion reading depth stored with Valve's FDM injection layer; test = launcher `VK_INSTANCE_LAYERS=''` (Lepton then loads neither VALVE_rpo nor VALVE_fdm_injection, Fossilize still). QuestCraft: LTW overrides glGetError and returns 0 with `LIBGL_NOERROR` set; Lepton passes `LEPTON_ENV_<NAME>` to the app as `<NAME>`, so catalog `lepton_env: {LEPTON_ENV_LIBGL_NOERROR: '1'}` gets Minecraft past the GL error 1282; then black picture (see the catalog entry). FrameBridge logs `new layer` once per layer type per process and projection views only for the first frames, so a second session in the same process (Vivecraft after Unity) needs `layer_debug=1`.
 **Vulkan validation / ITR2 solved (2026-10-05):** Khronos' validation layer can't come from Lepton (its layer dir is in the read-only guest image; the Linux copies on the Frame are glibc) and a global `debug.vulkan.layers` property (via the LEPTON_GFXRECON_FP_PROPS trick) kills the container at boot. Working recipe: bundle `libVkLayer_khronos_validation.so` (Khronos android-binaries release, arm64-v8a, stored uncompressed) into a test APK re-signed with the game's key (`apk.sign.sign`), install with `frameport install <pkg> --apk`, and set the Vulkan shim's `vk_validation=1` (it adds the layer at vkCreateInstance; findings under the logcat tag VALIDATION in launch.log, each message ID capped at 10). ITR2's flicker + windows behind models = Unreal's Qualcomm shader-resolve subpasses with a depth resolve of a single-sampled depth attachment (VUID-04908/-03179); `vk_spec_fixes=1` drops that resolve (its TRANSFER_DST half never applies to ITR2: the main depth is transient). Valve's VALVE_rpo layer removed ITR2's fog (catalog `lepton_env: VK_INSTANCE_LAYERS: VK_LAYER_VALVE_fdm_injection`). `r.ViewDistanceScale=2` in the internal Saved/Config/Android/Engine.ini only exists on the owner's Frame (the catalog can't write internal storage yet). Launch tests: Lepton prints a transient "is not a running context" on the first start after an APK change (agent v54 `not_started` waits 30 s for "Boot complete!").
+**GitHub #38/#39 (2026-10-05):** PowerWash Simulator stuck at "Waiting.." on a reporter's Frame = Unity sized the right-eye image rect past its swapchain (rect 268+1656 on a 1920-wide swapchain; the runtime's recommended size differs per Frame) and SteamVR rejected every frame (`xrEndFrame failed -25`, XR_ERROR_SWAPCHAIN_RECT_INVALID), after which the game stopped calling xrEndFrame. FrameBridge `rect_clamp` (default on; sizes noted in xrCreateSwapchain; clamped layers count as swapped) keeps projection/quad rects inside their swapchain; triage `swapchain-rect-invalid`. Not reproducible on the dev Frame with `scale` (Unity's eye sizing isn't just the recommended width); no regression there (72 fps). The adapter's revision was NOT bumped (that would mark every installed game outdated): affected users rebuild. The Room VR (#38) = Unity's render thread SIGSEGV in libgallium_dri.so ~30 ms after the game recreates its eye swapchain with samples=4 (FrameBridge retries samples=1); the game's own code turns MSAA on (not OVRManager); candidate fix: hide GL_EXT_multisampled_render_to_texture (GL shim) - needs the APK to test. The launch test passed both (render thread dead / no frames): triage gap.
 **Lepton storage (2026-09-30):** each app's /sdcard (= /storage/emulated/0 → `<base>/lepton-data/external`) has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (liblepton/mounting.sh, only if they exist at start); agent v24 `storage_targets` reads that mapping. Android's MediaProvider canonicalises paths to /home/steamos/... and rejects every file ("doesn't appear under [/system/media...]"), `sm list-volumes` is empty: the media index never works, apps must browse folders. Lepton installs with `adb install -g` (runtime permissions granted, MANAGE_EXTERNAL_STORAGE too). Files: `install/files.py`, `frameport frame send|storage`, GUI Files tab (formerly Frame → Send files).
 **SteamVR per-app settings (2026-09-30):** editing steamvr.vrsettings while SteamVR runs is lost; the web API (127.0.0.1:27062 /app/setsettings) needs `x-steamvr-secret`. `native/vrsettings` = `fp_vrsettings.exe` (freestanding, OpenVR `FnTable:IVRSettings_003` as a Utility app, loads SteamVR's bin/win64/openvr_api.dll) sets them live and SteamVR persists them: section `steam.app.<shortcut appid>`, keys `preferredRefreshRate` (float) and `motionSmoothingOverride` (0 global, 1 on, 2 off, 3 always). Steam Link (vrlink) lists the Frame's rates 72/80/90/96/108/120/144 in vrserver.txt and follows the per-app preference ("host preferred N Hz"; whether the key is honoured is unverified in-headset yet). Judder metric: vrcompositor.txt session summary dropped + "Timed out. N total" (Stormland: 0 dropped but 313 timeouts in 2 min); fpsVR (`%LOCALAPPDATA%\fpsVR\*.json`, 0.1 ms histograms) gives p99 CPU/GPU ms. `pcvr.steamvr_tuning` (default on, PC only) applies on Play: highest rate whose budget ≥ p99×1.05, at least one step down, smoothing on.
 

README.md

@@ -32,6 +32,7 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V
   shortcut; they run natively on SteamOS.
 - **Screenshots tab:** the screenshots you took in the headset, sorted by game (matched by play time) and day;
   view them and download them to your computer.
+- **Live view tab:** watch what the headset shows, with sound, in a browser window on your computer.
 - **Self-updating** releases, redacted diagnostics, one-click problem reports and working-config sharing.
 
 ## Quick start
@@ -78,6 +79,14 @@ your computer.
 
 ![Screenshot viewer](docs/images/screenshot-viewer.png)
 
+## Live view
+
+The **Live view** tab streams what the headset shows, with its sound, to your computer: click **Start live view** and
+it opens in your default web browser (full screen with a double-click; click **Sound on** to hear it, as browsers start
+videos muted). Pick 360p to 1080p, or the headset view's full size. The picture comes from SteamVR's built-in headset
+view on the Frame and is encoded there while you watch (about one CPU core), so stop it when you're done. It's black
+while the headset sleeps.
+
 ## Compatibility
 
 If a game has already been tested with FramePort, it will automatically use the optimal game config. Otherwise, FramePort

agent/frameport_agent.py

@@ -36,7 +36,7 @@ import time
 import zlib
 from types import SimpleNamespace
 
-AGENT_VERSION = 54
+AGENT_VERSION = 56
 HOME = os.path.expanduser("~")
 STEAM = os.path.join(HOME, ".local/share/Steam")
 ANCHORS = os.path.join(HOME, "Applications/quest-frame")
@@ -1135,7 +1135,16 @@ def remove_from_library(user, remove, result):
 
 def update_library(user, packages, result, shortcuts=True):
     """Add/update installed games' shortcuts + grid art in one Steam account (Steam is closed; shortcuts=False: only
-    the grid art of shortcuts that are already right, while Steam runs)."""
+    the grid art of shortcuts that are already right, while Steam runs). A game's devkit entry (the Play fallback)
+    gets the same art: on Frames where Steam ignores shortcuts.vdf it is the one in the library (GitHub #41)."""
+    for pkg in packages:
+        gameid = devkit_gameid(pkg)
+        appid = devkit_appid(gameid) if gameid else None
+        if appid:
+            try:
+                copy_grid_art(pkg, appid, [user])
+            except OSError as exc:
+                result.setdefault("errors", []).append(f"{pkg}: devkit art: {exc}")
     vdf = os.path.join(STEAM, "userdata", user, "config/shortcuts.vdf")
     grid = os.path.join(os.path.dirname(vdf), "grid")
     os.makedirs(grid, exist_ok=True)
@@ -1278,7 +1287,28 @@ def devkit_appid(gameid):
         for v in (root.get("shortcuts") or {}).values():
             if isinstance(v, dict) and v.get("DevkitGameID") == gameid and v.get("appid"):
                 return v["appid"] & 0xFFFFFFFF
-    return None
+    return devkit_appid_from_log(gameid)
+
+
+def devkit_appid_from_log(gameid):
+    """The appid Steam picked for a devkit game, from its console log ('sanitize shortcut app id "<dir>/<id>/launch.sh":
+    replacing 0 with N'). Steam adds the entry live but may never save it (GitHub #41/#42), so the log of the running
+    Steam session is the fallback (console_log.previous.txt is the session before, whose live entries are gone). The
+    newest line wins."""
+    exe = os.path.join(DEVKIT_GAMES, gameid, "launch.sh")
+    pat = re.compile(r'sanitize shortcut app id "' + re.escape(exe) + r'": replacing \d+ with (\d+)')
+    found = None
+    for name in ("console_log.txt",):  # this Steam session only: entries added live are gone after a restart
+        try:
+            with open(os.path.join(STEAM, "logs", name), errors="replace") as f:
+                for line in f:
+                    if "sanitize shortcut app id" in line:
+                        m = pat.search(line)
+                        if m:
+                            found = int(m.group(1)) & 0xFFFFFFFF
+        except OSError:
+            continue
+    return found
 
 
 def devkit_register(pkg):
@@ -1320,8 +1350,14 @@ def devkit_register(pkg):
         time.sleep(0.5)
     if not appid:
         raise AgentError("Steam added the devkit entry but didn't save it")
+    copy_grid_art(pkg, appid)
+    return appid
+
+
+def copy_grid_art(pkg, appid, users=None):
+    """The game's Steam art (portrait, landscape, hero, logo) as grid/<appid>* in every (or the given) account."""
     anchor = os.path.join(ANCHORS, pkg)
-    for user in steam_users():
+    for user in users if users is not None else steam_users():
         grid = os.path.join(STEAM, "userdata", user, "config/grid")
         os.makedirs(grid, exist_ok=True)
         for kind, suffix in (("portrait", "p"), ("landscape", ""), ("hero", "_hero"), ("logo", "_logo")):
@@ -1331,7 +1367,6 @@ def devkit_register(pkg):
                     if re.match(rf"^{appid}{re.escape(suffix)}\.", os.path.basename(old)):
                         os.remove(old)
                 shutil.copy(img, os.path.join(grid, f"{appid}{suffix}{os.path.splitext(img)[1]}"))
-    return appid
 
 
 def devkit_unregister(pkg, steam_running=True):
@@ -1383,8 +1418,9 @@ def cmd_launch(args):
         raise AgentError(f"{NOT_IN_LIBRARY}: {dep.get('title') or pkg}")
     steam = steam_launch(appid, args.get("wait", 10))
     out = {"package": pkg, "gameid": steam_gameid(appid), "title": dep.get("title"), "via": via, "steam": steam}
-    if via == "shortcut" and steam["result"] == "error" and steam.get("code") == 9 and args.get("fallback", True):
+    if steam["result"] == "error" and steam.get("code") == 9 and args.get("fallback", True):
-        # Steam doesn't know the shortcut at all (it tried to license a store app with that id): devkit entry
+        # Steam doesn't know the shortcut at all (it tried to license a store app with that id): devkit entry. A devkit
+        # entry Steam never saved is gone after a Steam restart (every install restarts it, GitHub #41): add it again
         try:
             appid = devkit_register(pkg)
         except AgentError as exc:

artifacts/SHA256SUMS

@@ -4,10 +4,10 @@ b5949e9e90e4c51e2733b9f6cd3c857a447552ac7291aec340407c27b034b600  ./arm64-v8a/li
 383054f8b3b41dde76d062c71856cd3163655e50009c08454bc1793f393ead65  ./arm64-v8a/libfpg.so
 8e00552d1ab90f82749db3caad4f773351fa8a28edcc5ea5cbd1b31c434ff32a  ./arm64-v8a/libframe_xrshim.so
 3dfcb0f2bec47857bcecc7261c58e076d872d4649718c40850f29e10c75477dd  ./arm64-v8a/libglshim.so
-3e05bb8561c7fd8787b3120739b3ce66c68badb5b00571bd50ae7e6c1f159274  ./arm64-v8a/libopenxr_loader_generic.so
+0780f29b4844bcf5070929d8118cfcc2e7da2f16dd0dbfe1eaf12be7f5567401  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
 32525cd0a9ee3d9993d8871cd6905bdcf22cde4f4ba28f5db6434ce7d6554758  ./arm64-v8a/libvrapi.so
-33bf52994b8024e139af20d6915bc76a0c7341ce9b5bd136a3002236168bcbd1  ./armeabi-v7a/libopenxr_loader_generic.so
+9c82f4ff57395e220329a22d0f0f47ce88b77132bed4dfb7b57809077fd0d6c4  ./armeabi-v7a/libopenxr_loader_generic.so
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 1aa733117cf57ccff7cf23f0425dbfd73b0332a3ef1c905ceeca0ccd0449c4e0  ./linux-arm64/XR_APILAYER_FRAMEPORT_timefix.json
 28c2430a02bbd8902c5bfb9562c6fd0e318654f9e05c095bfeb94b0450ab1b07  ./linux-arm64/libxr_frameport_timefix.so

catalog/games/com.Aldin.WotW.yaml

@@ -0,0 +1,21 @@
+package: com.Aldin.WotW
+title: 'Waltz of the Wizard: Extended Edition'
+status: works
+notes: From what I tested, it just works. My only complaint is that the haptics go pretty crazy. But I don't remember
+  what it was like when I played it in my Quest. So it could be fine. 100% playable.
+tested_version: 5.0.8.1578
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 522cfebf954e1cab6054798479b0b32c5ba9e38cca83dd98db2ac0f7e3c0802a
+  app: 0.9.1
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 48
+  issue: 44
+source_hint: WotW

catalog/games/com.CMGames.IntoTheRadius2.yaml

@@ -4,7 +4,7 @@ status: works
 notes: Plays well (owner-verified 2026-10-05). Space warp is off, the headset's brief focus losses are hidden
   (focus_hold, up to 2.5 s), only Valve's foveation layer is loaded (its render-pass optimizer removed the fog) and
   an invalid depth resolve in Unreal's render passes is dropped (vk_spec_fixes; it made models flicker and windows
-  show behind them). Needs FramePort 0.9.2 or newer. Loading a save can take over a minute.
+  show behind them). Needs FramePort 0.10.0 or newer. Loading a save can take over a minute.
 details: Unreal Engine 5 game that uses Meta's Application SpaceWarp (extra motion-vector and depth swapchains). OVRPort's
   patch_disable_space_warp doesn't reach Unreal Engine 5, so FrameBridge's hide_space_warp hides XR_FB_space_warp and
   removes the space warp info from the eye images. Working config shared in GitHub issue 35. In the headset
@@ -32,5 +32,5 @@ lepton_env:
 verified:
   date: '2026-10-05'
   issue: 35
-min_app: 0.9.2
+min_app: 0.10.0
 source_hint: Into The Radius 2

catalog/games/com.qcxr.qcxr.yaml

@@ -1,7 +1,7 @@
 package: com.qcxr.qcxr
 title: QuestCraft
 status: works
-notes: Minecraft runs in VR (Vivecraft, about 72 fps; drops while worlds load). Needs FramePort 0.9.2 or newer for
+notes: Minecraft runs in VR (Vivecraft, about 72 fps; drops while worlds load). Needs FramePort 0.10.0 or newer for
   the picture (older versions show black). On first start QuestCraft downloads its Java runtime, which didn't unpack on
   the Frame once (see details).
 details: QuestCraft downloads its Java runtime (JRE.zip from QuestCraft's GitHub releases) into files/runtimes/JRE

catalog/triage.yaml

@@ -13,6 +13,11 @@ signatures:
     severity: fatal
     diagnosis: 32-bit-only APK. The Steam Frame has no AArch32; this cannot run. Use the PC (Rift) version via Revive.
     suggest: []
+  - id: swapchain-rect-invalid
+    pattern: 'xrEndFrame failed -25\b'
+    severity: fatal
+    diagnosis: The runtime rejects the game's frames because an image rect reaches past its swapchain (by a few pixels on some Frames); the game stops drawing (e.g. stuck at a "Waiting" box). FrameBridge from FramePort 0.10.1 clamps the rects - rebuild and reinstall the game.
+    suggest: [frame.adapter]
   - id: missing-ovr-symbol
     pattern: '(UnsatisfiedLinkError|cannot locate symbol) .*"?(ovr_[A-Za-z0-9_]+|ovrMessageType_ToString)'
     severity: fatal

docs/FRAME_RUNTIME.md

@@ -106,6 +106,29 @@
 - SSH: `sshd` must be enabled (`sudo systemctl enable --now sshd`), which needs a user password (`passwd`).
 - mDNS: avahi-daemon runs by default; hostname `frame` → `frame.local`.
 
+## Video of the headset view (surveyed 2026-10-05; used by the Live view tab)
+- `steamvr-v4l2cam.service` (user unit, part of gamescope-session.target, `Restart=always`) runs SteamVR's
+  `/opt/steamvr/bin/linuxarm64/v4l2cam --output=99`: it reads the compositor's "Headset View" (IVRHeadsetView) and
+  writes it to a v4l2loopback webcam named **"SteamVR"** (`/dev/video99`, 1920x1080 RGB24, advertised 30 fps, frames
+  arrive at the display rate). Nothing on the Frame reads it by default; idle it costs nothing, read ~0.2 core.
+  It shows what the wearer sees (SteamVR home, Steam's panels; a game's layers are expected but not yet seen in it).
+  Black and ~1 fps (one frame per ~1.0 s) while the headset sleeps (standby): a 30 fps stream then repeats each
+  frame in bursts, which looks like a stall in a player. Its size follows SteamVR's headset view (v4l2cam has no size
+  option), so the live view only scales down (360p/480p/720p/1080p) or sends it as is ("full").
+- Sound: `pactl get-default-sink` (`alsa_loopback_device.stereo.alsa_output.platform-sound.HiFi__Speaker__sink`) and its
+  `.monitor` source carry what the headset plays; the Frame's ffmpeg has the `pulse` input and `aac`. Timestamps: pulse
+  uses the wall clock, v4l2 CLOCK_MONOTONIC → `-ts mono2abs` on the v4l2 input. Don't force
+  `-use_wallclock_as_timestamps` on the pulse input: it stamped bursts of AAC packets with one time.
+- Steam's own game recording / Remote Play / broadcast capture the **gamescope** PipeWire node (`CDesktopCapturePipeWire:
+  ... node path: gamescope`): with gamescope's `--backend openvr` that's only the flat Steam UI, not VR. Steam's arm64
+  `libvideo.so` encodes with x264 (vaapi/nvenc paths don't apply). No cast/spectator feature for the Frame's own VR view
+  exists in Steam's UI; the SteamVR web server (27062) has no mirror route.
+- Encoding: the Qualcomm encoder (`/dev/video23` qcom-iris-encoder, V4L2 M2M) doesn't work with the stock tools (ffmpeg
+  `h264_v4l2m2m` hangs, gst `v4l2h264enc` not-negotiated). ffmpeg + libx264 works: FramePort's live view
+  (`install/livestream.py`: `fps=30` before the scale, ultrafast/zerolatency, 3 threads, nice 10, fragmented MP4 on
+  stdout, + AAC 128k) measured 0.34 core at 720p / 0.56 at 1080p with a quiet picture (video only); expect ~1-1.4
+  cores with a busy scene.
+
 ## Text input
 
 - Lepton's Android has no on-screen keyboard (IME) and VR apps run headless, so no Android window has keyboard focus

docs/GAMES.md

@@ -54,6 +54,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Under Cover | Quest | ✅ Works |  |
 | VR4 | Quest | ✅ Works |  |
 | Wallace & Gromit in The Grand Getaway | Quest | ✅ Works |  |
+| Waltz of the Wizard: Extended Edition | Quest | ✅ Works |  |
 | Wander | Quest | ✅ Works |  |
 | Accounting+ | Quest | ⚠️ Works with issues | Starts in VR, but doesn't get past its "press any button" screen. |
 | Arcsmith | Quest | ⚠️ Works with issues | Right eye distorts during movement (unresolved; swap, tracking, Valve layers, depth and pacing ruled out). |

docs/PLAYBOOK.md

@@ -56,6 +56,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Quest app keeps recentering / snapping the view when you turn your head; log shows session state 5→4→3→4→5 within a second | the Frame briefly takes focus; the app recenters on focus changes | unfixed: hiding the dips (debounce) made AC Nexus stay black, so it was removed |
 | Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | upload in the Files tab (Videos = /sdcard/Movies) and browse folders in the app |
 | Batman: Arkham Shadow closes during smoke-bomb effects; later input-tree corruption | Meta XR Audio Wwise deletes queued metadata still referenced by the current audio frame, then writes through the stale pointer | FrameBridge automatically retires metadata after current-frame references disappear, for the verified AArch64 SDK build only; see [AUDIO_METADATA.md](AUDIO_METADATA.md) |
+| Game stays on a loading or "Waiting" box although it reached FOCUSED; log `FrameBridge: xrEndFrame failed -25` then no more `pacing:` lines (e.g. PowerWash Simulator on some Frames, GitHub #39) | The eye image rect ends a few pixels past its swapchain (Unity rounds the swapchain width, the runtime's recommended size differs per Frame); SteamVR rejects every frame with XR_ERROR_SWAPCHAIN_RECT_INVALID | FrameBridge clamps every projection/quad image rect to its swapchain (`rect_clamp`, default on since 0.10.1; log `rect_clamp: view N image rect clamped`): rebuild + reinstall the game |
 | Game (Unity, GLES) freezes, `zink: DEVICE LOST` | multisampled render-to-texture hangs the GPU | `frame.unity_no_msaa`; if it persists: unfixable → PC version |
 | Only the Android home screen shows; the log has Unity's VR device as `None` (e.g. Accounting+, Unity 2017) | Unity 2017–2018 built-in Oculus support starts VR only when `com.oculus.systemactivities` is installed; Lepton has no Meta system apps, so Unity falls back to non-VR | `frame.unity_oculus_check`: that package name in libunity.so → `android`, plus `native/ovrpshim` (libfp_ovrp.so): Unity 2017's legacy frame loop (`ovrp_Update2`/`ovrp_BeginFrame`) never calls `ovrp_WaitToBeginFrame`, so without the shim no `xrWaitFrame` happens, `CompositorOpenXR::Update … outside of frame bounds` floods the log and the dashboard freezes. With it: log `ovrp frame loop shim: waited for frame N`, ~71 fps. Accounting+ then stops at "press any button" although its OVRInput gets clean input (`INPUT_PROBE` in the patch logs connected controllers/buttons/input focus per call) — unresolved |
 | Own-engine game crashes in `libVkLayer_fossilize.so` (Fossilize's recording thread, e.g. Roblox) | same as Deadpool VR: uninitialised pointers in what Fossilize records | `frame.vk_sanitize` now also covers own-engine libraries that load `libvulkan.so` by name |

native/adapter/frame_adapter.c

@@ -88,6 +88,7 @@ static int foveation_fix = 1;
 static int hide_space_warp = 0;
 static int controller_fix = 1;
 static int swapchain_fix = 1;
+static int rect_clamp = 1;  // clamp submitted image rects to their swapchain (SteamVR rejects a 1 px overrun)
 static int layer_fix = 1;
 static int mutable_fix = 0;
 static int swap_eyes = 0;
@@ -136,6 +137,7 @@ static void read_settings(const char *path) {
         if (sscanf(line, "hide_space_warp=%f", &value) == 1) hide_space_warp = value != 0;
         if (sscanf(line, "controller_fix=%f", &value) == 1) controller_fix = value != 0;
         if (sscanf(line, "swapchain_fix=%f", &value) == 1) swapchain_fix = value != 0;
+        if (sscanf(line, "rect_clamp=%f", &value) == 1) rect_clamp = value != 0;
         if (sscanf(line, "layer_fix=%f", &value) == 1) layer_fix = value != 0;
         if (sscanf(line, "mutable_fix=%f", &value) == 1) mutable_fix = value != 0;
         if (sscanf(line, "swap_eyes=%f", &value) == 1) swap_eyes = value != 0;
@@ -390,6 +392,45 @@ static void remember_swapchain(XrSwapchain handle) {
     pthread_mutex_unlock(&swapchains_lock);
 }
 
+// Swapchain sizes, to keep submitted image rects inside them (rect_clamp).
+#define MAX_SIZES 256
+static struct { XrSwapchain handle; uint32_t w, h; } sizes[MAX_SIZES];
+static pthread_mutex_t sizes_lock = PTHREAD_MUTEX_INITIALIZER;
+
+static void note_swapchain_size(XrSwapchain handle, uint32_t w, uint32_t h) {
+    pthread_mutex_lock(&sizes_lock);
+    int slot = -1;
+    for (int i = 0; i < MAX_SIZES; ++i) {
+        if (sizes[i].handle == handle) { slot = i; break; }
+        if (slot < 0 && sizes[i].handle == XR_NULL_HANDLE) slot = i;
+    }
+    if (slot >= 0) { sizes[slot].handle = handle; sizes[slot].w = w; sizes[slot].h = h; }
+    pthread_mutex_unlock(&sizes_lock);
+}
+
+static int swapchain_size(XrSwapchain handle, uint32_t *w, uint32_t *h) {
+    int found = 0;
+    pthread_mutex_lock(&sizes_lock);
+    for (int i = 0; i < MAX_SIZES && !found; ++i)
+        if (sizes[i].handle == handle && handle != XR_NULL_HANDLE) { *w = sizes[i].w; *h = sizes[i].h; found = 1; }
+    pthread_mutex_unlock(&sizes_lock);
+    return found;
+}
+
+// Clamp `r` to a w x h image; returns whether it changed.
+static int clamp_rect(XrRect2Di *r, uint32_t w, uint32_t h) {
+    XrRect2Di c = *r;
+    if (c.offset.x < 0) { c.extent.width += c.offset.x; c.offset.x = 0; }
+    if (c.offset.y < 0) { c.extent.height += c.offset.y; c.offset.y = 0; }
+    if ((uint32_t)c.offset.x >= w || (uint32_t)c.offset.y >= h) return 0;  // nothing sensible to keep: leave it
+    if ((int64_t)c.offset.x + c.extent.width > (int64_t)w) c.extent.width = (int32_t)(w - (uint32_t)c.offset.x);
+    if ((int64_t)c.offset.y + c.extent.height > (int64_t)h) c.extent.height = (int32_t)(h - (uint32_t)c.offset.y);
+    if (c.extent.width <= 0 || c.extent.height <= 0) return 0;
+    int changed = memcmp(&c, r, sizeof c) != 0;
+    *r = c;
+    return changed;
+}
+
 static void forget_swapchain(XrSwapchain handle) {
     pthread_mutex_lock(&swapchains_lock);
     for (size_t i = 0; i < swapchain_count; ++i)
@@ -439,6 +480,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
         (unsigned long long)fixed.usageFlags, (unsigned long long)fixed.createFlags, result);
     if (XR_SUCCEEDED(result)) {
         remember_swapchain(*swapchain);
+        note_swapchain_size(*swapchain, fixed.width, fixed.height);
         flip_on_create_swapchain(*swapchain, &fixed);
         emul_on_create_swapchain(*swapchain, &fixed);
         return result;
@@ -461,6 +503,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
     }
     if (XR_SUCCEEDED(result)) {
         remember_swapchain(*swapchain);
+        note_swapchain_size(*swapchain, fixed.width, fixed.height);
         flip_on_create_swapchain(*swapchain, &fixed);
         emul_on_create_swapchain(*swapchain, &fixed);
     }
@@ -1110,6 +1153,51 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
             layer = (const XrCompositionLayerBaseHeader *)&projections[count];
             ++swapped;
         }
+        if (rect_clamp) {
+            // Keep every image rect inside its swapchain: Unity/OVRPlugin can size the eye area a few pixels past
+            // the image on some Frames (PowerWash Simulator: rect 268+1656 on a 1920 wide swapchain) and SteamVR
+            // then rejects every frame with XR_ERROR_SWAPCHAIN_RECT_INVALID (-25) (GitHub #39).
+            uint32_t w, h;
+            if (layer->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
+                ((const XrCompositionLayerProjection *)layer)->viewCount <= 2) {
+                const XrCompositionLayerProjection *cur = (const XrCompositionLayerProjection *)layer;
+                int over = 0;
+                for (uint32_t v = 0; v < cur->viewCount; ++v) {
+                    XrRect2Di r = cur->views[v].subImage.imageRect;
+                    if (swapchain_size(cur->views[v].subImage.swapchain, &w, &h) && clamp_rect(&r, w, h)) over = 1;
+                }
+                if (over) {
+                    if (layer != (const XrCompositionLayerBaseHeader *)&projections[count]) projections[count] = *cur;
+                    if (projections[count].views != views[count])
+                        for (uint32_t v = 0; v < cur->viewCount; ++v) views[count][v] = cur->views[v];
+                    for (uint32_t v = 0; v < cur->viewCount; ++v)
+                        if (swapchain_size(views[count][v].subImage.swapchain, &w, &h) &&
+                            clamp_rect(&views[count][v].subImage.imageRect, w, h)) {
+                            static int logged;
+                            if (logged++ < 3)
+                                LOG("rect_clamp: view %u image rect clamped to %dx%d at %d,%d (swapchain %ux%u)", v,
+                                    views[count][v].subImage.imageRect.extent.width,
+                                    views[count][v].subImage.imageRect.extent.height,
+                                    views[count][v].subImage.imageRect.offset.x,
+                                    views[count][v].subImage.imageRect.offset.y, w, h);
+                        }
+                    projections[count].views = views[count];
+                    layer = (const XrCompositionLayerBaseHeader *)&projections[count];
+                    ++swapped;
+                }
+            } else if (layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD) {
+                const XrCompositionLayerQuad *q = (const XrCompositionLayerQuad *)layer;
+                XrRect2Di r = q->subImage.imageRect;
+                if (swapchain_size(q->subImage.swapchain, &w, &h) && clamp_rect(&r, w, h)) {
+                    if (layer != (const XrCompositionLayerBaseHeader *)&quads[count]) quads[count] = *q;
+                    quads[count].subImage.imageRect = r;
+                    layer = (const XrCompositionLayerBaseHeader *)&quads[count];
+                    ++swapped;
+                    static int logged;
+                    if (!logged++) LOG("rect_clamp: quad image rect clamped (swapchain %ux%u)", w, h);
+                }
+            }
+        }
         kept[count++] = layer;
     }
     XrFrameEndInfo fixed = *info;

scripts/ui_smoke.py

@@ -302,7 +302,7 @@ def main() -> int:
     game = args.game or (library.games()[0]["package"] if library.games() else None)
     steps = [("library", lambda a: a.navigate(0)), ("frame", lambda a: a.navigate(1)),
              ("files", lambda a: a.go("files")), ("screenshots", lambda a: a.go("screenshots")),
-             ("tools", lambda a: a.go("settings"))]
+             ("live", lambda a: a.go("live")), ("tools", lambda a: a.go("settings"))]
     if game:
         steps.insert(1, ("game", lambda a: a.open_game(game)))
         steps.insert(2, ("game-customize", lambda a: a.open_game(game, advanced=True)))

src/frameport/_version.py

@@ -1,2 +1,2 @@
 # The FramePort version: the single source (pyproject reads it via hatch; CI checks a release tag matches it).
-__version__ = "0.9.1"
+__version__ = "0.10.0"

src/frameport/install/live_player.py

@@ -0,0 +1,138 @@
+# ruff: noqa: E501  (the embedded page's JavaScript)
+"""The Live view player page (served by livestream.py). A Python string rather than an .html file: the
+PyInstaller fallback bundle only carries data files it is told about."""
+
+PLAYER_HTML = r"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>FramePort Live view</title>
+<style>
+  :root { --bg: #0e1013; --text: #e8eaed; --muted: #9aa0a6; --accent: #66b3ff; --panel: rgba(20, 22, 26, .82); }
+  html, body { margin: 0; height: 100%; background: var(--bg); color: var(--text);
+               font: 14px/1.4 system-ui, -apple-system, "Segoe UI", sans-serif; overflow: hidden; }
+  video { position: fixed; inset: 0; width: 100%; height: 100%; object-fit: contain; background: #000; }
+  #bar { position: fixed; left: 12px; right: 12px; bottom: 12px; display: flex; gap: 12px; align-items: center;
+         padding: 8px 12px; border-radius: 10px; background: var(--panel); transition: opacity .3s; }
+  body.idle #bar { opacity: 0; }
+  #dot { width: 9px; height: 9px; border-radius: 50%; background: var(--muted); flex: none; }
+  #dot.live { background: #3ddc84; } #dot.err { background: #ff6b6b; }
+  #msg { flex: 1; min-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  #info { color: var(--muted); font-variant-numeric: tabular-nums; }
+  button { background: transparent; color: var(--text); border: 1px solid #3c4043; border-radius: 6px;
+           padding: 4px 10px; font: inherit; cursor: pointer; }
+  button:hover { border-color: var(--accent); }
+</style>
+</head>
+<body>
+<video id="v" muted autoplay playsinline disablepictureinpicture></video>
+<div id="bar">
+  <span id="dot"></span><span id="msg">Connecting to the Frame…</span><span id="info"></span>
+  <button id="snd" hidden title="Browsers start videos muted: click to hear the Frame">Sound on</button>
+  <button id="fs" title="Full screen (or double-click the picture)">Full screen</button>
+</div>
+<script>
+"use strict";
+const video = document.getElementById("v"), dot = document.getElementById("dot");
+const msg = document.getElementById("msg"), info = document.getElementById("info");
+const CUSHION = 0.3, CATCH_UP = 0.7, FAR_BEHIND = 2.0, KEEP = 10;  // seconds behind the newest data
+let session = 0, frames = 0, lastFrames = 0, size = "";
+
+function say(text, state) { msg.textContent = text; dot.className = state || ""; }
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+async function status() {
+  try { const r = await fetch("status", {cache: "no-store"}); return await r.json(); }
+  catch (e) { return null; }
+}
+
+async function run() {
+  const id = ++session;
+  let st = await status();
+  while (id === session && (!st || !st.ready)) {
+    if (st && st.ended) { say("Stopped: " + st.ended + " — start it again in FramePort.", "err"); return; }
+    if (!st) { say("FramePort isn't streaming any more. Start Live view in FramePort.", "err"); return; }
+    say("Waiting for the first picture from the Frame…");
+    await sleep(500); st = await status();
+  }
+  const type = 'video/mp4; codecs="' + (st.codec || "avc1.640028") + '"';
+  const MS = window.ManagedMediaSource || window.MediaSource;
+  if (!MS || !MS.isTypeSupported(type)) { say("This browser can't play H.264 video (" + type + "). Copy this page's address into another browser.", "err"); return; }
+  size = st.width ? st.width + "×" + st.height : "";
+  snd.hidden = !st.audio;
+  const ms = new MS();
+  video.disableRemotePlayback = true;
+  video.src = URL.createObjectURL(ms);
+  await new Promise(r => ms.addEventListener("sourceopen", r, {once: true}));
+  const sb = ms.addSourceBuffer(type);
+  sb.mode = "segments";
+  const pending = [];
+  const pump = () => {
+    if (sb.updating || !pending.length || ms.readyState !== "open") return;
+    try { sb.appendBuffer(pending.shift()); } catch (e) { trim(true); }
+  };
+  const trim = (force) => {
+    if (sb.updating || !sb.buffered.length) return;
+    const start = sb.buffered.start(0), cut = video.currentTime - (force ? 1 : KEEP);
+    if (cut > start) { try { sb.remove(start, cut); } catch (e) {} }
+  };
+  sb.addEventListener("updateend", () => {
+    if (sb.buffered.length) {
+      const end = sb.buffered.end(sb.buffered.length - 1);
+      const lag = end - video.currentTime;
+      if (lag > FAR_BEHIND || video.currentTime < sb.buffered.start(0)) video.currentTime = Math.max(end - CUSHION, 0);
+      else video.playbackRate = lag > CATCH_UP ? 1.1 : lag < CUSHION ? 1.0 : video.playbackRate;
+      if (video.paused) video.play().catch(() => {});
+    }
+    pump();
+  });
+  try {
+    const resp = await fetch("stream.mp4", {cache: "no-store"});
+    if (!resp.ok) throw new Error(await resp.text());
+    say("Live from the Frame", "live");
+    const reader = resp.body.getReader();
+    let n = 0;
+    while (id === session) {
+      const {value, done} = await reader.read();
+      if (done) break;
+      pending.push(value); frames++;
+      if (++n % 60 === 0) trim(false);
+      pump();
+    }
+  } catch (e) {
+    say("Connection lost (" + e.message + "), reconnecting…", "err");
+  }
+  if (id !== session) return;
+  await sleep(1000);
+  const again = await status();
+  if (again && again.ended) { say("Stopped: " + again.ended + " — start it again in FramePort.", "err"); return; }
+  run();
+}
+
+setInterval(() => {
+  const chunks = frames - lastFrames; lastFrames = frames;
+  info.textContent = [size, chunks ? "receiving" : ""].filter(Boolean).join(" · ");
+}, 1000);
+document.addEventListener("visibilitychange", () => { if (!document.hidden) run(); });
+const toggleFs = () => document.fullscreenElement ? document.exitFullscreen() : document.documentElement.requestFullscreen();
+document.getElementById("fs").onclick = toggleFs;
+const snd = document.getElementById("snd");
+let wantSound = false;  // the choice survives reconnects (each one makes a new MediaSource)
+snd.onclick = () => {
+  wantSound = !wantSound; video.muted = !wantSound;
+  snd.textContent = wantSound ? "Mute" : "Sound on";
+  if (wantSound) video.play().catch(() => {});
+};
+video.addEventListener("loadedmetadata", () => { video.muted = !wantSound; });
+video.ondblclick = toggleFs;
+let idle;
+document.addEventListener("mousemove", () => {
+  document.body.classList.remove("idle"); clearTimeout(idle);
+  idle = setTimeout(() => document.body.classList.add("idle"), 2500);
+});
+run();
+</script>
+</body>
+</html>
+"""

src/frameport/install/livestream.py

@@ -0,0 +1,508 @@
+"""Live view: what the Frame shows, played in a browser window on this PC (the GUI's Live view tab).
+
+The Frame sends fragmented MP4 (H.264) on the stdout of one SSH command (`source_command`); a small HTTP server on
+127.0.0.1 relays it to a player page (`live_player.py`: Media Source Extensions, no plugin). Flet has no video control
+outside packaged builds, so the picture is shown in the browser, which also decodes it in hardware.
+
+The relay keeps the init segment (ftyp + moov) and the fragments since the last keyframe, so a viewer that opens later
+starts at a keyframe. No image bytes ever go through Flet.
+"""
+from __future__ import annotations
+
+import json
+import queue
+import struct
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+SAMPLE_NON_SYNC = 0x10000  # ISO/IEC 14496-12 sample_is_non_sync_sample
+CLIENT_QUEUE = 240  # fragments a slow viewer may lag behind before it's dropped (it reconnects at a keyframe)
+
+
+# ------------------------------------------------------------------------------------------------ MP4 parsing
+def iter_boxes(data: bytes, start: int = 0, end: int | None = None):
+    """(type, payload start, box end) of each complete box in data[start:end]."""
+    end = len(data) if end is None else end
+    pos = start
+    while pos + 8 <= end:
+        size, kind = struct.unpack_from(">I4s", data, pos)
+        header = 8
+        if size == 1:
+            if pos + 16 > end:
+                return
+            size = struct.unpack_from(">Q", data, pos + 8)[0]
+            header = 16
+        elif size == 0:
+            size = end - pos
+        if size < header or pos + size > end:
+            return
+        yield kind.decode("latin-1"), pos + header, pos + size
+        pos += size
+
+
+def _child(data: bytes, start: int, end: int, kind: str):
+    for k, s, e in iter_boxes(data, start, end):
+        if k == kind:
+            return s, e
+    return None
+
+
+def fragment_is_keyframe(moof: bytes, track_id: int | None = None) -> bool:
+    """Whether a movie fragment starts with a sync sample in the given track (default: its first track): trun's
+    first-sample flags, else its per-sample flags, else tfhd's default flags. Unknown or no such track → False: a
+    viewer then waits for the next fragment that is one."""
+    top = _child(moof, 0, len(moof), "moof")
+    if not top:
+        return False
+    for kind, s, e in iter_boxes(moof, *top):
+        if kind != "traf":
+            continue
+        default_flags = None
+        tfhd = _child(moof, s, e, "tfhd")
+        if tfhd:
+            p = tfhd[0]
+            flags = int.from_bytes(moof[p + 1:p + 4], "big")
+            if track_id is not None and struct.unpack_from(">I", moof, p + 4)[0] != track_id:
+                continue
+            p += 8  # version/flags + track_ID
+            for bit, size in ((0x1, 8), (0x2, 4), (0x8, 4), (0x10, 4)):
+                if flags & bit:
+                    p += size
+            if flags & 0x20 and p + 4 <= tfhd[1]:
+                default_flags = struct.unpack_from(">I", moof, p)[0]
+        trun = _child(moof, s, e, "trun")
+        if not trun:
+            continue
+        p = trun[0]
+        flags = int.from_bytes(moof[p + 1:p + 4], "big")
+        count = struct.unpack_from(">I", moof, p + 4)[0]
+        p += 8
+        if flags & 0x1:
+            p += 4  # data_offset
+        if flags & 0x4:
+            return not struct.unpack_from(">I", moof, p)[0] & SAMPLE_NON_SYNC
+        if count and flags & 0x400:
+            if flags & 0x100:
+                p += 4
+            if flags & 0x200:
+                p += 4
+            return not struct.unpack_from(">I", moof, p)[0] & SAMPLE_NON_SYNC
+        if default_flags is not None:
+            return not default_flags & SAMPLE_NON_SYNC
+        return False
+    return False
+
+
+def codec_string(init: bytes) -> str | None:
+    """The MSE codecs parameter from the init segment: `avc1.PPCCLL` (from avcC), plus `mp4a.40.2` when it has an AAC
+    track (ffmpeg's aac encoder writes AAC-LC)."""
+    i = init.find(b"avcC")
+    if i < 0 or i + 8 > len(init):
+        return None
+    profile, compat, level = init[i + 5], init[i + 6], init[i + 7]
+    out = f"avc1.{profile:02x}{compat:02x}{level:02x}"
+    if b"mp4a" in init:
+        out += ", mp4a.40.2"
+    return out
+
+
+def video_track_id(init: bytes) -> int | None:
+    """track_ID of the init segment's video track (its trak's hdlr is 'vide')."""
+    moov = _child(init, 0, len(init), "moov")
+    if not moov:
+        return None
+    for kind, s, e in iter_boxes(init, *moov):
+        if kind != "trak":
+            continue
+        tkhd, mdia = _child(init, s, e, "tkhd"), _child(init, s, e, "mdia")
+        hdlr = mdia and _child(init, *mdia, "hdlr")
+        if tkhd and hdlr and init[hdlr[0] + 8:hdlr[0] + 12] == b"vide":
+            version = init[tkhd[0]]
+            return struct.unpack_from(">I", init, tkhd[0] + (20 if version == 1 else 12))[0]
+    return None
+
+
+def video_size(init: bytes) -> tuple[int, int] | None:
+    """Width and height from the init segment's avc1 sample entry."""
+    i = init.find(b"avc1")
+    if i < 0 or i + 4 + 28 > len(init):
+        return None
+    p = i + 4 + 24  # sample entry: 6 reserved + 2 data ref index + 16 pre_defined/reserved
+    return struct.unpack_from(">HH", init, p)
+
+
+class Mp4Splitter:
+    """Cuts a byte stream into the init segment and movie fragments (moof + mdat), whatever the read sizes."""
+
+    def __init__(self):
+        self.buf = bytearray()
+        self.init = bytearray()
+        self.have_init = False
+        self._moof: bytes | None = None
+
+    def feed(self, data: bytes) -> list[tuple[str, bytes]]:
+        """[("init", bytes) | ("fragment", bytes)] completed by this data."""
+        self.buf += data
+        out = []
+        while True:
+            if len(self.buf) < 8:
+                break
+            size, kind = struct.unpack_from(">I4s", self.buf, 0)
+            header = 8
+            if size == 1:
+                if len(self.buf) < 16:
+                    break
+                size = struct.unpack_from(">Q", self.buf, 8)[0]
+                header = 16
+            if size < header:
+                raise ValueError(f"bad MP4 box size {size}")
+            if len(self.buf) < size:
+                break
+            box = bytes(self.buf[:size])
+            del self.buf[:size]
+            kind = kind.decode("latin-1")
+            if not self.have_init:
+                self.init += box
+                if kind == "moov":
+                    self.have_init = True
+                    out.append(("init", bytes(self.init)))
+            elif kind == "moof":
+                self._moof = box
+            elif kind == "mdat" and self._moof is not None:
+                out.append(("fragment", self._moof + box))
+                self._moof = None
+            # other top-level boxes (styp, sidx, free) carry nothing a viewer needs
+        return out
+
+
+# ------------------------------------------------------------------------------------------------ relay
+def _end(q: queue.Queue) -> None:
+    """Tell a viewer's sender the stream is over: drop what it hasn't sent yet, then the end marker (None)."""
+    try:
+        while True:
+            q.get_nowait()
+    except queue.Empty:
+        pass
+    try:
+        q.put_nowait(None)
+    except queue.Full:
+        pass
+
+
+class Relay:
+    """Fan-out of one MP4 stream to any number of HTTP viewers."""
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self.init: bytes | None = None
+        self.video_track: int | None = None
+        self.gop: list[bytes] = []  # fragments since the last keyframe fragment (incl.)
+        self.clients: list[queue.Queue] = []
+        self.frames = 0
+        self.bytes = 0
+        self.started = time.time()
+        self.ended: str | None = None  # why the source stopped
+        self._splitter = Mp4Splitter()
+
+    def feed(self, data: bytes) -> None:
+        for kind, chunk in self._splitter.feed(data):
+            with self._lock:
+                self.bytes += len(chunk)
+                if kind == "init":
+                    self.init = chunk
+                    self.video_track = video_track_id(chunk)
+                    continue
+                self.frames += 1
+                if fragment_is_keyframe(chunk, self.video_track):
+                    self.gop = [chunk]
+                elif self.gop:
+                    self.gop.append(chunk)
+                for q in list(self.clients):
+                    try:
+                        q.put_nowait(chunk)
+                    except queue.Full:  # too slow: drop it, its page reconnects (never block: we hold the lock)
+                        self.clients.remove(q)
+                        _end(q)
+
+    def finish(self, reason: str) -> None:
+        with self._lock:
+            self.ended = reason
+            for q in self.clients:
+                _end(q)
+            self.clients.clear()
+
+    def subscribe(self) -> tuple[bytes | None, list[bytes], queue.Queue]:
+        q: queue.Queue = queue.Queue(CLIENT_QUEUE)
+        with self._lock:
+            self.clients.append(q)
+            return self.init, list(self.gop), q
+
+    def unsubscribe(self, q: queue.Queue) -> None:
+        with self._lock:
+            if q in self.clients:
+                self.clients.remove(q)
+
+    def status(self) -> dict:
+        with self._lock:
+            init = self.init
+            out = {"ready": init is not None, "ended": self.ended, "viewers": len(self.clients),
+                   "fragments": self.frames, "bytes": self.bytes, "seconds": round(time.time() - self.started, 1)}
+        if init:
+            out["codec"] = codec_string(init)
+            out["audio"] = b"mp4a" in init
+            size = video_size(init)
+            if size:
+                out["width"], out["height"] = size
+        return out
+
+
+def player_html() -> bytes:
+    from .live_player import PLAYER_HTML
+
+    return PLAYER_HTML.encode("utf-8")
+
+
+class _Handler(BaseHTTPRequestHandler):
+    server: _Server
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, fmt, *args):  # quiet
+        pass
+
+    def _send(self, code: int, body: bytes, ctype: str) -> None:
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):  # noqa: N802
+        path = self.path.split("?", 1)[0]
+        live = self.server.live
+        if path in ("/", "/index.html"):
+            self._send(200, player_html(), "text/html; charset=utf-8")
+        elif path == "/status":
+            self._send(200, json.dumps(live.relay.status()).encode(), "application/json")
+        elif path == "/stream.mp4":
+            self._stream(live.relay)
+        else:
+            self._send(404, b"not found", "text/plain")
+
+    def _stream(self, relay: Relay) -> None:
+        if relay.ended:
+            self._send(503, relay.ended.encode(), "text/plain")
+            return
+        init, gop, q = relay.subscribe()
+        try:
+            deadline = time.time() + 30
+            while init is None:  # the source hasn't sent its init segment yet
+                if relay.ended or time.time() > deadline:
+                    self._send(503, (relay.ended or "no picture yet").encode(), "text/plain")
+                    return
+                time.sleep(0.1)
+                relay.unsubscribe(q)
+                init, gop, q = relay.subscribe()
+            self.send_response(200)
+            self.send_header("Content-Type", "video/mp4")
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("Transfer-Encoding", "chunked")
+            self.end_headers()
+            self._chunk(init)
+            for f in gop:
+                self._chunk(f)
+            while True:
+                try:
+                    f = q.get(timeout=5)
+                except queue.Empty:
+                    if relay.ended:
+                        break
+                    continue
+                if f is None:
+                    break
+                self._chunk(f)
+            self.wfile.write(b"0\r\n\r\n")
+        except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError, OSError):
+            pass
+        finally:
+            relay.unsubscribe(q)
+
+    def _chunk(self, data: bytes) -> None:
+        self.wfile.write(f"{len(data):x}\r\n".encode() + data + b"\r\n")
+        self.wfile.flush()
+
+
+class _Server(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+    live: LiveStream
+
+
+# ------------------------------------------------------------------------------------------------ the Frame's side
+# SteamVR on the Frame runs `steamvr-v4l2cam.service` (Valve's v4l2cam): it copies the compositor's "headset view"
+# (what the wearer sees: games, SteamVR home, Steam's panels) into a v4l2loopback webcam named "SteamVR"
+# (/dev/video99, 1920x1080 RGB24, frames at the display rate). It costs nothing until someone reads it. Steam's own
+# recording/Remote Play capture gamescope instead (only the flat Steam UI in VR) and encode with x264 as well; the
+# Frame's Qualcomm encoder (qcom-iris) doesn't work with the stock ffmpeg/GStreamer. So: read the headset view, drop
+# to 30 fps before scaling, x264 at low priority, fragmented MP4 on stdout. Black while the headset sleeps.
+DEVICE_NAME = "SteamVR"
+# The headset view's size comes from SteamVR (1920x1080 on SteamOS 0.3.0; v4l2cam follows it, it has no size option),
+# so qualities are heights the picture is scaled *down* to (never up: a 2K/4K setting would only add bytes); "full"
+# sends it at its own size, whatever SteamVR makes it.
+QUALITY = {  # max height (None = the headset view's own), bitrate
+    "360p": (360, "1M"),
+    "480p": (480, "1500k"),
+    "720p": (720, "3M"),
+    "1080p": (1080, "6M"),
+    "full": (None, "10M"),
+}
+DEFAULT_QUALITY = "720p"
+FPS = 30
+# Clocks: pulse stamps audio with the wall clock, v4l2 with CLOCK_MONOTONIC → `-ts mono2abs` puts the picture on the
+# wall clock too. (Forcing -use_wallclock_as_timestamps on the pulse input gave bursts of AAC packets one shared time,
+# a broken audio timeline.) aresample=async=1 keeps the sound continuous across hiccups.
+AUDIO_BITRATE = "128k"  # AAC of the Frame's default output's monitor = what the headset plays (Lepton/Proton games)
+ENCODER_THREADS = 3  # leaves the game most of the CPU
+
+
+def source_command(quality: str = DEFAULT_QUALITY, fps: int = FPS) -> str:
+    """Shell script for the Frame: finds the headset-view device, streams fMP4 (H.264, + AAC sound of the
+    default output when there is one) to stdout and stops when the SSH channel closes (stdin reaches EOF).
+    Exit 3 = no headset view device (SteamVR not running)."""
+    h, rate = QUALITY.get(quality, QUALITY[DEFAULT_QUALITY])
+    # width -2 keeps the aspect ratio (even, as yuv420p needs); full size only drops an odd last row/column
+    scale = (",crop=trunc(iw/2)*2:trunc(ih/2)*2" if h is None
+             else f",scale=-2:'min({h},ih)':flags=fast_bilinear")
+    return f"""dev=
+for d in /sys/class/video4linux/video*; do
+  [ "$(cat "$d/name" 2>/dev/null)" = "{DEVICE_NAME}" ] && dev=/dev/${{d##*/}} && break
+done
+if [ -z "$dev" ]; then echo "no SteamVR headset view device: is SteamVR running?" >&2; exit 3; fi
+exec 3<&0
+export XDG_RUNTIME_DIR=${{XDG_RUNTIME_DIR:-/run/user/$(id -u)}}  # (an SSH session may lack it: PipeWire's socket)
+audio=(-an)
+sink=$(pactl get-default-sink 2>/dev/null)
+if [ -n "$sink" ]; then
+  audio=(-thread_queue_size 1024 -f pulse -fragment_size 3840 -i "$sink.monitor"
+         -map 0:v -map 1:a -af aresample=async=1 -c:a aac -b:a {AUDIO_BITRATE} -ac 2 -ar 48000)
+fi
+nice -n 10 ffmpeg -nostdin -hide_banner -loglevel error \\
+  -thread_queue_size 64 -ts mono2abs -f v4l2 -input_format rgb24 -i "$dev" "${{audio[@]}}" \\
+  -vf "fps={fps}{scale},format=yuv420p" -c:v libx264 -preset ultrafast -tune zerolatency -threads {ENCODER_THREADS} \\
+  -g {fps} -b:v {rate} -maxrate {rate} -bufsize {rate} \\
+  -f mp4 -movflags empty_moov+default_base_moof -frag_duration 100000 - &
+pid=$!
+( cat <&3 >/dev/null; kill $pid 2>/dev/null ) >/dev/null 2>&1 &  # (a background job's own stdin is /dev/null)
+wait $pid
+"""
+
+
+class FrameSource:
+    """The stdout of `source_command` on the Frame, on its own SSH channel of the existing connection."""
+
+    def __init__(self, frame, quality: str):
+        self.frame = frame
+        self.quality = quality
+        self.chan = None
+
+    def open(self):
+        transport = self.frame.client.get_transport()
+        if transport is None or not transport.is_active():
+            raise ConnectionError("not connected to the Frame")
+        self.chan = transport.open_session()
+        from ..frame.connection import sh_quote
+
+        self.chan.exec_command("bash -c " + sh_quote(source_command(self.quality)))
+        return self
+
+    def read(self, n: int) -> bytes:
+        data = self.chan.recv(n)
+        if not data:
+            err = b""
+            while self.chan.recv_stderr_ready():
+                err += self.chan.recv_stderr(4096)
+            if err.strip():
+                raise RuntimeError(err.decode("utf-8", "replace").strip().splitlines()[-1])
+        return data
+
+    def close(self) -> None:
+        if self.chan is not None:
+            try:
+                self.chan.shutdown_write()  # EOF on the script's stdin: it stops ffmpeg
+            finally:
+                self.chan.close()
+
+
+def start(frame, quality: str = DEFAULT_QUALITY) -> LiveStream:
+    """Start streaming the Frame's headset view; open `.url` in a browser to watch."""
+    src = FrameSource(frame, quality)
+    return LiveStream(src.open, src.close).start()
+
+
+class LiveStream:
+    """One live view: the source command on the Frame + the local relay server.
+
+    `open_source()` returns a file-like object with `read(n)`; it's the stdout of a command on the Frame (or, in tests,
+    a local process). `stop()` ends both.
+    """
+
+    def __init__(self, open_source, close_source=None, host: str = "127.0.0.1", port: int = 0):
+        self._open_source = open_source
+        self._close_source = close_source
+        self.relay = Relay()
+        self.server = _Server((host, port), _Handler)
+        self.server.live = self
+        self._threads: list[threading.Thread] = []
+        self._stop = threading.Event()
+        self.on_end = None  # callback(reason) when the source stops by itself
+
+    @property
+    def url(self) -> str:
+        host, port = self.server.server_address[:2]
+        return f"http://{host}:{port}/"
+
+    def start(self) -> LiveStream:
+        t1 = threading.Thread(target=self.server.serve_forever, name="live-http", daemon=True)
+        t2 = threading.Thread(target=self._pump, name="live-source", daemon=True)
+        self._threads = [t1, t2]
+        t1.start()
+        t2.start()
+        return self
+
+    def _pump(self) -> None:
+        reason = "stopped"
+        try:
+            src = self._open_source()
+            while not self._stop.is_set():
+                data = src.read(65536)
+                if not data:
+                    reason = "the Frame stopped sending a picture"
+                    break
+                self.relay.feed(data)
+        except Exception as exc:  # noqa: BLE001
+            from ..errors import explain
+
+            reason = explain(exc)
+        if self._stop.is_set():
+            reason = "stopped"
+        self.relay.finish(reason)
+        if not self._stop.is_set() and self.on_end:
+            self.on_end(reason)
+
+    @property
+    def running(self) -> bool:
+        return not self._stop.is_set() and self.relay.ended is None
+
+    def stop(self) -> None:
+        if self._stop.is_set():
+            return
+        self._stop.set()
+        if self._close_source:
+            try:
+                self._close_source()
+            except Exception:  # noqa: BLE001
+                pass
+        self.relay.finish("stopped")
+        self.server.shutdown()
+        self.server.server_close()

src/frameport/locales/template.json

@@ -38,6 +38,7 @@
  "108 Hz": "",
  "120 Hz": "",
  "144 Hz": "",
+ "360p (lightest)": "",
  "360° (equirect) layers, e.g. a video player's virtual theatre or 360° videos (e.g. 4XVR), which the Frame's runtime lacks, are drawn by a background thread into a layer behind the game's own picture: the 360° image is converted only when it changes (a theatre once, a 360° video once per video frame) and the view is drawn for each frame's head pose. GLES games only; without it these layers are missing (black).": "",
  "360° 3D": "",
  "360° detail": "",
@@ -46,6 +47,7 @@
  "360° sharpness": "",
  "360° video frame rate limit": "",
  "72 Hz": "",
+ "720p (recommended)": "",
  "80 Hz": "",
  "90 Hz": "",
  "920 × 430": "",
@@ -182,6 +184,7 @@
  "Choose PNG, JPEG or WebP images. Steam fills any missing shape from the ones you choose; FramePort never replaces your images automatically.": "",
  "Choose…": "",
  "Chosen by you.": "",
+ "Clamp image rects": "",
  "Clean up Frida leftovers in smali": "",
  "Cleans up graphics data that crashes some Unreal games on the Frame.": "",
  "Clear": "",
@@ -232,6 +235,7 @@
  "Couldn't read the file list: {exc}": "",
  "Couldn't read the Frame's folders: {exc}": "",
  "Couldn't read {path}: {exc}": "",
+ "Couldn't start the live view: {exc}": "",
  "Couldn't use {choice}: {exc}": "",
  "Cover": "",
  "Create": "",
@@ -404,6 +408,7 @@
  "Freed {value:.1f} GiB on the Frame": "",
  "From the tested recipe for this game": "",
  "From the {src}": "",
+ "Full (headset view size)": "",
  "Full launch log": "",
  "Game": "",
  "Game arguments (select SteamVR / OpenXR)": "",
@@ -505,6 +510,7 @@
  "Keep game saves on the Frame": "",
  "Keep menus in place": "",
  "Keeps a smoothing setting off that the game turns on itself and that can freeze the Frame.": "",
+ "Keeps every submitted image rect inside its swapchain. Unity can size the eye area a few pixels past the image on some Frames; SteamVR then rejects every frame (xrEndFrame -25, XR_ERROR_SWAPCHAIN_RECT_INVALID) and the game stops drawing (e.g. PowerWash Simulator stuck at \"Waiting\").": "",
  "Keeps one label so the title is stable.": "",
  "Keeps one name for the game, so it shows the same everywhere.": "",
  "Keyboard connected to {label}.": "",
@@ -547,6 +553,8 @@
  "Linux": "",
  "Linux app (arm64)": "",
  "Linux VR app · OpenXR": "",
+ "Live": "",
+ "Live view": "",
  "Loading…": "",
  "Loads FramePort's OpenXR layer under Proton on the Frame. The Frame's SteamVR runtime only accepts OpenXR 1.0 apps, but Proton's VR helper asks for 1.1, so without the layer VR never starts (the game shows as a flat window, or Revive fails with 'Unable to load LibOVRRT DLL'); the layer retries as 1.0. It also emulates xrConvertTimespecTimeToTimeKHR if a runtime refuses it. Ignored on this PC.": "",
  "Loads libglshim.so ahead of libEGL in every engine library that fetches GL through eglGetProcAddress. Fixes Quest-only leniency that Mesa/Zink rejects: #pragma before #extension, implicit int/float conversions (enables GL_EXT_shader_implicit_conversions), and multiview shaders used on single-view framebuffers (hides GL_OVR_multiview; gl_hide_multiview=0 turns that off). Logs every failed shader with its source lines (logcat tag GLShim). Symptom: black screen with working audio in a GLES game.": "",
@@ -613,6 +621,7 @@
  "No release notes.": "",
  "No screenshots yet": "",
  "No Unreal crash reporter": "",
+ "no viewer open": "",
  "No Wi-Fi needed: for networks that block the setup, and faster game uploads": "",
  "No: a 2D app": "",
  "None": "",
@@ -626,6 +635,7 @@
  "Not offered by Steam on this Frame yet": "",
  "Not recommended: breaks games that load VrApi through OVRPlugin.": "",
  "Not set up": "",
+ "Not streaming": "",
  "Not verified on many games yet: try it if the game doesn't work without it.": "",
  "Notes (what you checked, known issues)": "",
  "Nothing found. Try a shorter or different name.": "",
@@ -659,6 +669,7 @@
  "Open": "",
  "Open game": "",
  "Open GitHub issue": "",
+ "Open viewer": "",
  "OpenGL ES games run on the Frame through Zink (OpenGL on top of Vulkan), which is stricter than Quest drivers. Vulkan games run natively.": "",
  "Opens a prefilled GitHub issue with this game's recipe, so it can join the built-in catalog (no account token needed; you review and submit it on GitHub). No game files or personal data are sent.": "",
  "Opens the app straight in VR, skipping its flat launcher screen (turn off to use the launcher, e.g. to import new content).": "",
@@ -733,6 +744,7 @@
  "Put the Frame to sleep": "",
  "Put the Frame to sleep?": "",
  "Puts settings files next to the game on the Frame (e.g. to turn off an unsupported effect).": "",
+ "Quality": "",
  "Quest": "",
  "Quest games (Lepton)": "",
  "Quest ✓": "",
@@ -909,11 +921,14 @@
  "Source": "",
  "square, 256 × 256": "",
  "Standard for every game": "",
+ "Start live view": "",
  "Start straight in VR (skip the 2D launcher)": "",
  "Starting SteamVR and {title} — put your headset on": "",
+ "Starting the stream on the Frame…": "",
  "Starting {title} on the Frame — put the headset on": "",
  "Starting {title}, but SteamVR isn't running — it may open as a flat window. Start SteamVR and relaunch.": "",
  "Starting…": "",
+ "Starts a video stream on the Frame and opens it in your browser.": "",
  "Starts the game on the Frame while nobody is wearing it and reads the log: did it start, create a VR session and render frames. It can't check what you'd see: tracking only runs with the headset on.": "",
  "Starts the game through Steam on this PC (SteamVR + Revive)": "",
  "Starts the game through the Frame's Steam — put the headset on": "",
@@ -930,7 +945,9 @@
  "steamos@frame.local or an IP address": "",
  "SteamVR": "",
  "Stereo (3D) 360° layers: 0 = as the game sends them, 2 = flat (the left image to both eyes).": "",
+ "Stop": "",
  "Stop objects popping in and out": "",
+ "Stopped: {why}": "",
  "Stops Meta's audio library from reporting to Meta (only matters on PC emulators).": "",
  "Stops some Unreal games from closing themselves right after starting.": "",
  "Stops strict debugging checks that make some games quit.": "",
@@ -963,6 +980,7 @@
  "The copy on your Frame differs from what FramePort would install now (the recipe or your game files changed). Update to install the new build; saves are kept.": "",
  "The CPU types the game ships code for. The Frame runs only 64-bit ARM (arm64-v8a); 32-bit-only games can't run on it.": "",
  "The download didn't finish. Check your internet connection.": "",
+ "The first picture takes a few seconds.": "",
  "The Frame can't show curved panels; this shows them as gently bent strips.": "",
  "The Frame goes to sleep in a few seconds. Wake it with its power button.": "",
  "The Frame goes to sleep now.": "",
@@ -985,8 +1003,10 @@
  "the game didn't pass its checks (see the list above)": "",
  "the installed game (APK and its data)": "",
  "The launch settings changed since it was installed: update the Steam shortcut": "",
+ "The live view can start once FramePort is connected to the Frame.": "",
  "the log of the last start": "",
  "The PC VR counterpart of OVRPort's 'Patch Oculus detection for Unreal'. Unreal's Oculus plugin only starts when the Oculus service announces a headset (the Windows event 'OculusHMDConnected'); without it the game runs as a flat window. On the Frame the launcher runs the game through FramePort's small helper (fp_oculushmd.exe) that provides that event while the game runs, instead of relying only on Revive's hook of the check. Ignored on this PC (the Oculus app or Revive handle it there).": "",
+ "The picture opens in your default web browser, where it plays smoothly and can go full screen. It shows the headset's view with its sound (click Sound on in the player) whatever is running: Steam's menus, SteamVR or a game; while the headset sleeps the picture is black and updates about once a second. Streaming costs the Frame a little performance; stop it when you're done.": "",
  "the previous version, kept for one rollback": "",
  "The repack's own Revive · runs the game directly": "",
  "The small helper program FramePort runs on the Frame (installs, launch tests, Steam entries). It comes with this app and is replaced on the Frame automatically whenever it differs.": "",
@@ -1115,6 +1135,7 @@
  "Videos, documents, mods and saves on your Steam Frame": "",
  "View": "",
  "View screenshot": "",
+ "Viewer address on this PC: {url}": "",
  "VR (OpenXR)": "",
  "VrApi → OpenXR adapter (OVRPort)": "",
  "VrApi → OpenXR bridge": "",
@@ -1132,6 +1153,7 @@
  "Waiting for the Frame": "",
  "Waiting for your Frame": "",
  "Waiting for your Frame… (code {code})": "",
+ "Watch what the headset shows, in a window on this PC": "",
  "Welcome to FramePort": "",
  "What FramePort will do": "",
  "What happens? (optional: you can also write it on GitHub)": "",
@@ -1251,7 +1273,12 @@
   "",
   ""
  ],
+ "{n} viewer": [
+  "",
+  ""
+ ],
  "{on} on your Frame": "",
+ "{rate}/s": "",
  "{remaining} more after this": "",
  "{title} couldn't be added to the Frame's Steam library: {why}": "",
  "{title} failed: {error}": "",

src/frameport/patches/settings.py

@@ -108,6 +108,10 @@ SETTINGS = [
      "Override the guardian width (0 = use guardian, min 1.5 m)."),
     ("scene_depth", "float", 0.0, "Emulated room depth (m)",
      "Override the guardian depth (0 = use guardian, min 1.5 m)."),
+    ("rect_clamp", "int", 1, "Clamp image rects",
+     "Keeps every submitted image rect inside its swapchain. Unity can size the eye area a few pixels past the image "
+     "on some Frames; SteamVR then rejects every frame (xrEndFrame -25, XR_ERROR_SWAPCHAIN_RECT_INVALID) and the game "
+     "stops drawing (e.g. PowerWash Simulator stuck at \"Waiting\")."),
     ("swap_eyes", "int", 0, "Swap eyes", "Swap left/right views (diagnostic)."),
     ("strip_depth", "int", 0, "Strip depth layers", "Remove XR_KHR_composition_layer_depth chains (diagnostic)."),
     ("mutable_fix", "int", 0, "Mutable swapchain fix", "Experimental Vulkan mutable-format workaround."),
@@ -138,7 +142,7 @@ SETTINGS = [
 
 
 # settings that need a new build, not only new settings files: the Vulkan shim learned vk_shader_fix in 0.6.4 and
-# vk_query_slots in 0.9.2
+# vk_query_slots and vk_spec_fixes in 0.10.0
 REVISIONS = {"vk_shader_fix": 2, "vk_query_slots": 3, "vk_spec_fixes": 2}
 
 # How the "Game settings" dialog shows each setting to non-technical users: group, level (common settings are always
@@ -232,7 +236,7 @@ UI: dict[str, dict] = {
                             control=("choice", [(0, "As the game sends it"), (2, "Flat")])),
     **{key: dict(group="troubleshooting", level="advanced", control=("switch",)) for key in (
         "foveation_fix", "hide_space_warp", "swapchain_fix", "layer_fix", "gl_hide_multiview", "mutable_fix",
-        "flip_quads", "swap_eyes", "vk_validation",
+        "flip_quads", "swap_eyes", "vk_validation", "rect_clamp",
         "strip_depth", "respace_kick", "layer_debug", "eye_debug", "release_wait")},
 }
 

src/frameport/ui/app.py

@@ -32,6 +32,7 @@ NAV = [("library", tr("Library"), ft.Icons.GRID_VIEW_ROUNDED),
        ("frame", tr("Steam Frame"), ft.Icons.VIEW_IN_AR_ROUNDED),
        ("files", tr("Files"), ft.Icons.FOLDER_OPEN_ROUNDED),
        ("screenshots", tr("Screenshots"), ft.Icons.PHOTO_LIBRARY_OUTLINED),
+       ("live", tr("Live view"), ft.Icons.CAST_ROUNDED),
        ("settings", tr("Settings"), ft.Icons.TUNE_ROUNDED)]
 POLL_SECONDS = 30
 
@@ -70,12 +71,14 @@ class FramePortApp:
         self.library_view = None  # created once (views/library.LibraryView), re-mounted on every visit
         self.files_view = None  # likewise (views/files.FilesView): keeps the location/folder between visits
         self.screenshots_view = None  # likewise (views/screenshots.ScreenshotsView): keeps the game filter
+        self.live_view = None  # likewise (views/live.LiveView): owns the running stream, which outlives the tab
         self.exe_queue: list[str] = []  # games whose executable the user should confirm (after a scan)
         self._failures: list[Job] = []  # failed installs/tests, shown together when the queue is done
         self.jobs = jobs_module.shared()  # one queue per process, shared by every window session
         self.jobs.subscribe(self._on_job)
         self._handled_jobs: set[int] = set()  # finished jobs this session has reacted to (pop-ups, refreshes)
-        page.on_close = lambda e: self.jobs.unsubscribe(self._on_job)  # session gone: stop drawing into it
+        page.on_close = lambda e: (self.jobs.unsubscribe(self._on_job),  # session gone: stop drawing into it
+                                   self.stop_live())  # and stop a live view (it would keep the Frame encoding)
         from .updater import Updater
 
         self.updater = Updater(self)  # new FramePort releases (sidebar card, Library bar, one-click update)
@@ -349,6 +352,12 @@ class FramePortApp:
                 if self.screenshots_view is None:
                     self.screenshots_view = ScreenshotsView(self)
                 view = self.screenshots_view.mount(*self.route[1:])
+            elif kind == "live":
+                from .views.live import LiveView
+
+                if self.live_view is None:
+                    self.live_view = LiveView(self)
+                view = self.live_view.mount()
             elif kind == "settings":
                 view = SettingsView(self).build()
             else:
@@ -378,9 +387,16 @@ class FramePortApp:
         elif self.route[0] == "screenshots" and (self.screenshots_view is None or self.screenshots_view.root is None
                                                  or self.frame_state != "connected"):
             self.render()
+        elif self.route[0] == "live" and (self.live_view is None or self.live_view.root is None
+                                          or self.frame_state != "connected"):
+            self.render()
         else:
             self._refresh_sidebar()
 
+    def stop_live(self) -> None:
+        if self.live_view is not None:
+            self.live_view.stop()
+
     def open_game(self, package: str, advanced: bool = False, show_all: bool = False) -> None:
         self.go("game", package, advanced, show_all)
 
@@ -1826,6 +1842,7 @@ class FramePortApp:
             work()
 
     def disconnect(self):
+        self.stop_live()
         if self.target:
             try:
                 self.target.close()

src/frameport/ui/views/live.py

@@ -0,0 +1,176 @@
+"""Live view: watch what the Frame shows, in a browser window on this PC.
+
+Flet can't play video outside packaged builds, so this tab only starts and stops the stream (install/livestream.py)
+and opens the player page in the user's browser. Persistent: the stream keeps running while other tabs are open; the
+status line is refreshed once a second while the tab is shown (properties only, no new controls).
+"""
+from __future__ import annotations
+
+import threading
+import time
+from typing import TYPE_CHECKING
+
+import flet as ft
+
+from ...errors import explain
+from ...i18n import tr, tr_n
+from .. import components as C
+from .. import theme as T
+from .files_dialog import human
+
+if TYPE_CHECKING:
+    from ..app import FramePortApp
+
+QUALITIES = [("360p", tr("360p (lightest)")), ("480p", "480p"), ("720p", tr("720p (recommended)")),
+             ("1080p", "1080p"), ("full", tr("Full (headset view size)"))]
+
+
+def status_text(st: dict) -> str:
+    """One line for the relay's status (livestream.Relay.status)."""
+    if st.get("ended"):
+        return tr("Stopped: {why}").format(why=st["ended"])
+    if not st.get("ready"):
+        return tr("Starting the stream on the Frame…")
+    parts = [tr("Live")]
+    if st.get("width"):
+        parts.append(f"{st['width']}×{st['height']}")
+    secs = max(st.get("seconds") or 0, 1)
+    parts.append(tr("{rate}/s").format(rate=human(int((st.get("bytes") or 0) / secs))))
+    n = st.get("viewers") or 0
+    parts.append(tr("no viewer open") if not n else tr_n("{n} viewer", "{n} viewers", n))
+    return " · ".join(parts)
+
+
+def default_quality() -> str:
+    from ...install.livestream import DEFAULT_QUALITY
+
+    return DEFAULT_QUALITY
+
+
+class LiveView:
+    def __init__(self, app: FramePortApp):
+        self.app = app
+        self.live = None  # install.livestream.LiveStream while streaming
+        self.quality = default_quality()
+        self._busy = False
+        self._ticker: threading.Thread | None = None
+        self.root = None
+        self.dot = C.dot(T.TEXT_3, 10)
+        self.state = C.body(tr("Not streaming"), T.TEXT, weight=ft.FontWeight.W_500)
+        self.detail = C.meta("")
+        self.quality_dd = ft.Dropdown(label=tr("Quality"), value=self.quality, width=T.px(260), dense=True,
+                                      options=[ft.DropdownOption(key=k, text=t) for k, t in QUALITIES],
+                                      on_select=self._set_quality)
+        self.start_btn = C.primary(tr("Start live view"), ft.Icons.PLAY_ARROW_ROUNDED, self._start, big=True)
+        self.open_btn = C.secondary(tr("Open viewer"), ft.Icons.OPEN_IN_NEW_ROUNDED, self._open)
+        self.stop_btn = C.ghost(tr("Stop"), ft.Icons.STOP_ROUNDED, self._stop_click)
+        self.url = C.meta("", selectable=True)
+
+    # ---------------------------------------------------------------- building
+    def mount(self) -> ft.Control:
+        app = self.app
+        heading, sub = tr("Live view"), tr("Watch what the headset shows, in a window on this PC")
+        if not (app.target and app.frame_state == "connected"):
+            return ft.Column([
+                app.top_bar(heading, sub),
+                C.empty_state(ft.Icons.CAST_ROUNDED, tr("Connect your Frame first"),
+                              tr("The live view can start once FramePort is connected to the Frame."),
+                              C.primary(tr("Connect"), ft.Icons.LINK_ROUNDED, lambda e: app.go("frame")))], expand=True)
+        if self.root is None:
+            self.root = ft.Column([
+                app.top_bar(heading, sub),
+                C.card(ft.Column([
+                    ft.Row([self.dot, self.state], spacing=T.S2,
+                           vertical_alignment=ft.CrossAxisAlignment.CENTER),
+                    self.detail,
+                    ft.Container(height=T.S2),
+                    ft.Row([self.start_btn, self.open_btn, self.stop_btn, self.quality_dd],  # (no expand child: wraps)
+                           spacing=T.S3, wrap=True, vertical_alignment=ft.CrossAxisAlignment.CENTER),
+                    self.url,
+                ], spacing=T.S2)),
+                C.callout(tr("The picture opens in your default web browser, where it plays smoothly and can go "
+                             "full screen. It shows the headset's view with its sound "
+                             "(click Sound on in the player) whatever is running: Steam's menus, SteamVR or a game; "
+                             "while the headset sleeps the picture is black and updates about once a second. "
+                             "Streaming costs the Frame a little performance; "
+                             "stop it when you're done.")),
+            ], spacing=T.S4, horizontal_alignment=ft.CrossAxisAlignment.STRETCH)
+        self._refresh(update=False)
+        self._ensure_ticker()
+        return self.root
+
+    def _refresh(self, update: bool = True) -> None:
+        live = self.live
+        running = bool(live and live.running)
+        if live is None:
+            self.dot.bgcolor, self.state.value = T.TEXT_3, tr("Not streaming")
+            self.detail.value = tr("Starts a video stream on the Frame and opens it in your browser.")
+        else:
+            st = live.relay.status()
+            ok = running and st.get("ready")
+            self.dot.bgcolor = T.OK if ok else T.ERROR if st.get("ended") else T.WARN
+            self.state.value = status_text(st)
+            self.detail.value = "" if ok or st.get("ended") else tr("The first picture takes a few seconds.")
+        self.start_btn.visible = not running
+        self.start_btn.disabled = self._busy
+        self.open_btn.visible = self.stop_btn.visible = running
+        self.quality_dd.disabled = running or self._busy
+        self.url.value = (tr("Viewer address on this PC: {url}").format(url=live.url) if running else "")
+        self.url.visible = running
+        if update:
+            C.update(self.dot, self.state, self.detail, self.start_btn, self.open_btn, self.stop_btn,
+                     self.quality_dd, self.url)
+
+    def _ensure_ticker(self) -> None:
+        if self._ticker and self._ticker.is_alive():
+            return
+
+        def tick():
+            while self.app.route[:1] == ("live",):
+                self._refresh()
+                time.sleep(1)
+
+        self._ticker = threading.Thread(target=tick, name="live-status", daemon=True)
+        self._ticker.start()
+
+    # ---------------------------------------------------------------- actions
+    def _set_quality(self, e) -> None:
+        self.quality = e.control.value or default_quality()
+
+    def _start(self, e=None) -> None:
+        if self._busy or (self.live and self.live.running):
+            return
+        self._busy = True
+        self._refresh()
+        self.app.run_bg(self._start_bg)
+
+    def _start_bg(self) -> None:
+        from ...install import livestream
+
+        try:
+            if self.live:
+                self.live.stop()
+            self.live = livestream.start(self.app.target.frame, quality=self.quality)
+            self.live.on_end = lambda why: self._refresh()
+        except Exception as exc:  # noqa: BLE001
+            self.live = None
+            self.app.toast(tr("Couldn't start the live view: {exc}").format(exc=explain(exc)), error=True)
+        finally:
+            self._busy = False
+        self._refresh()
+        if self.live:
+            self._open()
+
+    def _open(self, e=None) -> None:
+        if self.live and self.live.running:
+            self.app.open_url(self.live.url)
+
+    def _stop_click(self, e=None) -> None:
+        self.app.run_bg(self.stop)
+
+    def stop(self) -> None:
+        """Stop streaming (also called when the Frame disconnects or the app closes)."""
+        live, self.live = self.live, None
+        if live:
+            live.stop()
+        self._refresh()

tests/test_agent.py

@@ -1315,3 +1315,49 @@ def test_launch_test_waits_for_a_first_boot(monkeypatch, tmp_path):
     assert a.not_started(first, 31)  # no boot: the container really failed
     assert not a.not_started(first + "Boot complete!\nInstalling game.apk...\n", 120)
     assert not a.not_started("Boot complete!\n", 120)
+
+
+def test_devkit_appid_from_steams_console_log(monkeypatch, tmp_path):
+    """GitHub #42: Steam added the devkit entry live but never saved shortcuts.vdf; its console log names the appid."""
+    a = load_agent(monkeypatch, tmp_path)
+    logs = Path(a.STEAM) / "logs"
+    logs.mkdir(parents=True, exist_ok=True)
+    exe = f"{a.DEVKIT_GAMES}/I_Am_Cat/launch.sh"
+    (logs / "console_log.txt").write_text(
+        f'[2026-10-05 14:45:37] sanitize shortcut app id "{exe}": replacing 0 with 3849978641, reason: k_unAppIdInvalid\n'
+        f'[2026-10-05 14:45:38] sanitize shortcut app id "{a.DEVKIT_GAMES}/Other/launch.sh": replacing 0 with 5\n'
+        f'[2026-10-05 15:29:14] sanitize shortcut app id "{exe}": replacing 0 with 3849978642, reason: k_unAppIdInvalid\n')
+    assert a.devkit_appid("I_Am_Cat") == 3849978642  # nothing in shortcuts.vdf: the newest log line
+    assert a.devkit_appid("Missing") is None
+
+
+def test_devkit_appid_ignores_the_previous_steam_session(monkeypatch, tmp_path):
+    """Live devkit entries die with Steam (GitHub #41): an appid from console_log.previous.txt is stale."""
+    a = load_agent(monkeypatch, tmp_path)
+    logs = Path(a.STEAM) / "logs"
+    logs.mkdir(parents=True, exist_ok=True)
+    exe = f"{a.DEVKIT_GAMES}/Batman/launch.sh"
+    (logs / "console_log.previous.txt").write_text(f'sanitize shortcut app id "{exe}": replacing 0 with 77, x\n')
+    (logs / "console_log.txt").write_text("Steam started\n")
+    assert a.devkit_appid("Batman") is None
+
+
+def test_launch_registers_a_lost_devkit_entry_again(monkeypatch, tmp_path):
+    """After a Steam restart Steam forgot the (never saved) devkit entry: Play gets AppError_9 and registers it again."""
+    a = load_agent(monkeypatch, tmp_path)
+    monkeypatch.setattr(a, "check_pkg", lambda p: p)
+    monkeypatch.setattr(a, "deployment", lambda p: {"appid": 111, "title": "Batman"})
+    monkeypatch.setattr(a, "run", lambda *x, **k: subprocess.CompletedProcess([], 0, "", ""))
+    monkeypatch.setattr(a, "devkit_gameid", lambda p: "Batman")
+    monkeypatch.setattr(a, "devkit_appid", lambda g: 222)  # the stale entry from before the restart
+    registered = []
+    monkeypatch.setattr(a, "devkit_register", lambda p: registered.append(p) or 333)
+    launches = []
+
+    def launch(appid, wait=10):
+        launches.append(appid)
+        return {"result": "error", "code": 9} if appid == 222 else {"result": "started"}
+    monkeypatch.setattr(a, "steam_launch", launch)
+    out = a.cmd_launch({"package": "com.camouflaj.manta"})
+    assert registered == ["com.camouflaj.manta"] and launches == [222, 333]
+    assert out["via"] == "devkit" and out["steam"]["result"] == "started"

tests/test_livestream.py

@@ -0,0 +1,247 @@
+"""Live view: the fragmented-MP4 relay (box splitting, keyframe detection, late viewers), the player page, and the
+Frame-side script (device lookup, stops when the SSH channel closes)."""
+import io
+import shutil
+import struct
+import subprocess
+import time
+import urllib.request
+
+import pytest
+
+from frameport.install import livestream as L
+
+
+def box(kind: str, payload: bytes) -> bytes:
+    return struct.pack(">I4s", 8 + len(payload), kind.encode()) + payload
+
+
+def full(kind: str, flags: int, payload: bytes) -> bytes:
+    return box(kind, struct.pack(">I", flags) + payload)  # version 0
+
+
+def init_segment(w=1280, h=720) -> bytes:
+    # avc1 sample entry: 6 reserved + 2 data ref + 16 pre_defined/reserved, then width/height; avcC: version,
+    # profile 0x42, compat 0xc0, level 0x1f
+    avcc = box("avcC", bytes([1, 0x42, 0xC0, 0x1F]) + b"\0" * 4)
+    avc1 = box("avc1", b"\0" * 24 + struct.pack(">HH", w, h) + b"\0" * 50 + avcc)
+    return box("ftyp", b"isom\0\0\0\0") + box("moov", box("trak", avc1))
+
+
+def fragment(key: bool, how: str = "first", seq: int = 0) -> bytes:
+    flags = 0 if key else L.SAMPLE_NON_SYNC
+    if how == "first":  # trun first_sample_flags (what ffmpeg writes)
+        trun = full("trun", 0x1 | 0x4, struct.pack(">IiI", 2, 0, flags))
+        tfhd = full("tfhd", 0, struct.pack(">I", 1))
+    elif how == "sample":  # per-sample flags
+        trun = full("trun", 0x400, struct.pack(">II", 1, flags))
+        tfhd = full("tfhd", 0, struct.pack(">I", 1))
+    else:  # tfhd default flags
+        trun = full("trun", 0, struct.pack(">I", 1))
+        tfhd = full("tfhd", 0x20, struct.pack(">II", 1, flags))
+    return box("moof", box("mfhd", struct.pack(">II", 0, seq)) + box("traf", tfhd + trun)) + \
+        box("mdat", bytes([seq % 256]) * 32)
+
+
+@pytest.mark.parametrize("how", ["first", "sample", "default"])
+def test_keyframe_detection(how):
+    assert L.fragment_is_keyframe(fragment(True, how))
+    assert not L.fragment_is_keyframe(fragment(False, how))
+
+
+def test_keyframe_unknown_is_not_key():
+    assert not L.fragment_is_keyframe(box("moof", box("mfhd", b"\0" * 8)))
+    assert not L.fragment_is_keyframe(b"junk")
+
+
+def test_codec_and_size():
+    init = init_segment(1920, 1080)
+    assert L.codec_string(init) == "avc1.42c01f"
+    assert L.video_size(init) == (1920, 1080)
+    assert L.codec_string(b"nothing") is None
+
+
+def test_splitter_any_read_size():
+    stream = init_segment() + fragment(True, seq=1) + fragment(False, seq=2) + box("free", b"x")
+    for step in (1, 7, 64, len(stream)):
+        sp, out = L.Mp4Splitter(), []
+        for i in range(0, len(stream), step):
+            out += sp.feed(stream[i:i + step])
+        assert [k for k, _ in out] == ["init", "fragment", "fragment"]
+        assert out[0][1] == init_segment()
+        assert out[1][1] == fragment(True, seq=1)
+
+
+def test_splitter_rejects_garbage():
+    with pytest.raises(ValueError):
+        L.Mp4Splitter().feed(struct.pack(">I4s", 3, b"bad!"))
+
+
+def test_relay_late_viewer_starts_at_keyframe():
+    r = L.Relay()
+    r.feed(init_segment() + fragment(True, seq=1) + fragment(False, seq=2) + fragment(True, seq=3)
+           + fragment(False, seq=4))
+    init, gop, q = r.subscribe()
+    assert init == init_segment()
+    assert gop == [fragment(True, seq=3), fragment(False, seq=4)]
+    r.feed(fragment(False, seq=5))
+    assert q.get_nowait() == fragment(False, seq=5)
+    st = r.status()
+    assert st["ready"] and st["codec"] == "avc1.42c01f" and st["width"] == 1280 and st["viewers"] == 1
+    r.finish("gone")
+    assert q.get_nowait() is None and r.status()["ended"] == "gone"
+
+
+def test_relay_drops_slow_viewer(monkeypatch):
+    monkeypatch.setattr(L, "CLIENT_QUEUE", 2)
+    r = L.Relay()
+    r.feed(init_segment())
+    _, _, q = r.subscribe()
+    for i in range(3):
+        r.feed(fragment(True, seq=i))
+    assert r.status()["viewers"] == 0  # dropped; its page reconnects at a keyframe
+
+
+class _Source:
+    """A byte stream fed at the pace a test chooses."""
+
+    def __init__(self, data: bytes):
+        self.f = io.BytesIO(data)
+
+    def read(self, n):
+        time.sleep(0.01)
+        return self.f.read(min(n, 200))
+
+
+def test_server_serves_page_status_and_stream():
+    data = init_segment() + b"".join(fragment(i % 3 == 0, seq=i) for i in range(6))
+    live = L.LiveStream(lambda: _Source(data)).start()
+    try:
+        page = urllib.request.urlopen(live.url, timeout=5).read()
+        assert b"MediaSource" in page and b"stream.mp4" in page
+        deadline = time.time() + 5
+        while live.relay.ended is None and time.time() < deadline:
+            time.sleep(0.05)
+        import json
+
+        st = json.loads(urllib.request.urlopen(live.url + "status", timeout=5).read())
+        assert st["ready"] and st["fragments"] == 6 and st["ended"]
+        with pytest.raises(urllib.error.HTTPError):  # source over: no stream to join (503 isn't hung)
+            urllib.request.urlopen(live.url + "stream.mp4", timeout=5).read()
+    finally:
+        live.stop()
+    assert not live.running
+
+
+def test_stream_endpoint_sends_init_then_gop():
+    gate = []
+
+    class Slow:
+        def __init__(self):
+            self.parts = [init_segment(), fragment(True, seq=1), fragment(False, seq=2)]
+
+        def read(self, n):
+            if self.parts:
+                return self.parts.pop(0)
+            while not gate:
+                time.sleep(0.02)
+            return b""
+
+    live = L.LiveStream(Slow).start()
+    try:
+        deadline = time.time() + 5
+        while live.relay.status()["fragments"] < 2 and time.time() < deadline:
+            time.sleep(0.02)
+        resp = urllib.request.urlopen(live.url + "stream.mp4", timeout=5)
+        assert resp.headers["Content-Type"] == "video/mp4"
+        gate.append(1)
+        body = resp.read()
+        assert body == init_segment() + fragment(True, seq=1) + fragment(False, seq=2)
+    finally:
+        live.stop()
+
+
+def test_source_command_scales_down_only():
+    c720 = L.source_command("720p")
+    assert "scale=-2:'min(720,ih)'" in c720 and "fps=30" in c720 and '"SteamVR"' in c720
+    assert c720.index("fps=30") < c720.index("scale=")  # drop frames before the expensive scale
+    for q, (h, _) in L.QUALITY.items():
+        assert ("scale=" in L.source_command(q)) == (h is not None)
+    assert L.source_command("bogus") == L.source_command(L.DEFAULT_QUALITY)
+
+
+@pytest.mark.skipif(not shutil.which("bash"), reason="needs bash")
+def test_source_command_without_device_exits_3(tmp_path):
+    script = L.source_command().replace("/sys/class/video4linux", str(tmp_path))
+    p = subprocess.run(["bash", "-c", script], capture_output=True, text=True, timeout=10, stdin=subprocess.DEVNULL)
+    assert p.returncode == 3 and "SteamVR" in p.stderr
+
+
+@pytest.mark.skipif(not shutil.which("bash"), reason="needs bash")
+def test_source_command_stops_when_stdin_closes(tmp_path):
+    """The SSH channel closing = EOF on stdin: the encoder must stop (it would keep the Frame busy)."""
+    dev = tmp_path / "video99"
+    dev.mkdir()
+    (dev / "name").write_text("SteamVR\n")
+    bindir = tmp_path / "bin"
+    bindir.mkdir()
+    fake = bindir / "ffmpeg"
+    fake.write_text("#!/bin/sh\nexec sleep 30\n")
+    fake.chmod(0o755)
+    script = L.source_command().replace("/sys/class/video4linux", str(tmp_path))
+    p = subprocess.Popen(["bash", "-c", script], stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                         env={"PATH": f"{bindir}:/usr/bin:/bin"})
+    time.sleep(0.5)
+    assert p.poll() is None  # streaming
+    p.stdin.close()
+    assert p.wait(timeout=5) is not None
+
+
+def trak(track_id: int, handler: bytes, entry: bytes) -> bytes:
+    tkhd = full("tkhd", 3, b"\0" * 8 + struct.pack(">I", track_id) + b"\0" * 68)
+    hdlr = full("hdlr", 0, b"\0" * 4 + handler + b"\0" * 13)
+    return box("trak", tkhd + box("mdia", hdlr + box("minf", box("stbl", box("stsd", entry)))))
+
+
+def av_init() -> bytes:
+    avc1 = box("avc1", b"\0" * 24 + struct.pack(">HH", 1280, 720) + b"\0" * 50
+               + box("avcC", bytes([1, 0x42, 0xC0, 0x1F]) + b"\0" * 4))
+    return box("ftyp", b"isom\0\0\0\0") + box("moov", trak(2, b"soun", box("mp4a", b"\0" * 28))
+                                                 + trak(1, b"vide", avc1))
+
+
+def av_fragment(video_key: bool, seq: int) -> bytes:
+    """Audio traf first (all sync samples), then the video traf."""
+    def traf(tid, flags):
+        return box("traf", full("tfhd", 0, struct.pack(">I", tid)) + full("trun", 0x4, struct.pack(">II", 1, flags)))
+    return box("moof", box("mfhd", struct.pack(">II", 0, seq)) + traf(2, 0)
+               + traf(1, 0 if video_key else L.SAMPLE_NON_SYNC)) + box("mdat", b"x" * 8)
+
+
+def test_audio_track_codecs_and_video_track():
+    init = av_init()
+    assert L.codec_string(init) == "avc1.42c01f, mp4a.40.2"
+    assert L.video_track_id(init) == 1
+    assert L.video_track_id(init_segment()) is None  # (the minimal helper has no tkhd/hdlr)
+
+
+def test_keyframe_looks_at_video_track_only():
+    assert not L.fragment_is_keyframe(av_fragment(False, 1), 1)  # the audio traf's sync sample doesn't count
+    assert L.fragment_is_keyframe(av_fragment(True, 1), 1)
+    assert not L.fragment_is_keyframe(av_fragment(True, 1), 7)  # no such track
+
+
+def test_relay_with_audio():
+    r = L.Relay()
+    r.feed(av_init() + av_fragment(True, 1) + av_fragment(False, 2) + av_fragment(False, 3))
+    _, gop, _ = r.subscribe()
+    assert len(gop) == 3  # the non-key fragments with audio didn't restart the group
+    st = r.status()
+    assert st["audio"] and st["codec"].endswith("mp4a.40.2")
+
+
+def test_source_command_captures_default_output():
+    cmd = L.source_command()
+    assert "pactl get-default-sink" in cmd and "$sink.monitor" in cmd and "-c:a aac" in cmd
+    assert "-ts mono2abs" in cmd and "-use_wallclock_as_timestamps" not in cmd  # both on pulse's wall clock
+    assert "aresample=async=1" in cmd

tests/test_triage.py

@@ -75,3 +75,11 @@ def test_rejected_controller_profile_is_information_only():
     f = {x.id: x for x in triage(log, "RUNNING", "com.example.game").findings}
     assert f["controller-profile-rejected"].severity == "info"
     assert triage(log, "RUNNING", "com.example.game").verdict == "pass"
+
+
+def test_swapchain_rect_invalid_is_recognised():
+    """GitHub #39: SteamVR rejected PowerWash Simulator's frames (rect a few px past the swapchain)."""
+    from frameport.validate import triage
+
+    log = "10-05 08:13:02.100  1149  1312 I FrameBridge: xrEndFrame failed -25\n"
+    assert "swapchain-rect-invalid" in [f.id for f in triage.triage(log).findings]