Android version / web wrapper: warnings only, never unsupported from the manifest alone (owner's call): the recipe notes, game page (warning callout) and CLI say what the manifest asks for; a launch test's triage (android-too-new, web-wrapper) decides

The game page's "What FramePort will do" for a Linux app gets a Desktop Mode switch ("In the menu and on the
desktop", default on): kept in the library entry (desktop_entry; patches don't apply to Linux apps), passed to
finalize_linux at install and applied at once on the Frame through the agent's desktop_entry command when the app is
installed. The agent side (menu + desktop .desktop files, launcher with FRAMEPORT_DESKTOP=1, refresh for existing
installs, removal on uninstall/purge) came with agent v63. Help text desktop_entry, INSTALL/FRAME_RUNTIME/PLAYBOOK,
CLAUDE.md. Game Mode's Steam Input problem from the report is separate.

Closes #84

CLAUDE.md

@@ -28,13 +28,24 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
     delete leaves screenshots.vdf alone (Steam rewrites it at exit); game menu → "Screenshots" = `go("screenshots",
     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
+    output's pulse monitor (sound) → `fp_venc` (`native/venc`, own clean-room V4L2 driver of the Frame's iris
+    hardware encoder: RGB24→NV12 box downscale with NEON, H.264 CBR, one frame per slot of an even fraction of the
+    panel rate read from DRM, e.g. 96 Hz → 32 fps; stdin `k` = keyframe, EOF = stop; `--probe` / `--selftest`;
+    artifact `linux-arm64-bin/`, synced to `~/.local/share/frameport/bin` by sha256 at stream start, no agent change)
+    piped into ffmpeg (`-c:v copy` + AAC), else the old ffmpeg/x264 30 fps path (qualities scale down only; "full" =
+    SteamVR's size; stderr `live: encoder=… fps=…` → status line) →
+    fragmented MP4 on an SSH exec channel's stdout (stdin EOF stops it) → relay on 127.0.0.1 (a new viewer asks
+    the hardware encoder for a keyframe and waits for it, else gets init + fragments since the last keyframe of the
+    *video* track) → 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
+    stops on disconnect/window close); monitor (`views/monitor.py` + `frame/monitor.py` + agent v62 `_monitor`: one
+    JSON sample per tick over an SSH exec channel while the tab is shown (stopped in go/disconnect/on_close, the
+    agent ends at EOF); sources and costs in docs/FRAME_RUNTIME.md "Monitoring sources"; game card (fps from
+    FrameBridge pacing; End game = Steam's Exit game, then cmd_stop), tiles with `C.Sparkline` (Flet canvas, no charts
+    extension), details, a pooled process table (Game / Steam & SteamVR / All; right-click: end / force kill / end
+    game; MON_CRITICAL needs force, MON_NEVER is refused)); 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).
@@ -60,6 +71,14 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
     uploads are interruptible (Cancel checked per MiB) and resumable (big files via SFTP `.part` append, small files
     streamed in tar batches; the agent counts files already in `incoming/`). Multi-select in the Library queues
     installs after asking every needed question up front. Failures end in one pop-up (Resume / Uninstall / log).
+  - Other drives (GitHub #90, agent v63): anchors stay in ~/Applications/quest-frame, a game's files may live in
+    `<mount>/FramePort/<pkg>` (`deployment.json` base). Agent `drives` (/proc/mounts, /run/media + Steam library
+    drives; vfat/exfat/ntfs/read-only refused), prepare*/finalize_linux `dest` (unmounted = error, never a fallback;
+    installed games keep their base), `move` (detached systemd-run + `move_status`; cp -a under podman unshare,
+    count+bytes check, symlink retarget, launch.sh: Quest app_dir line / Linux+PC VR rewritten from the record's
+    `launcher` field, else text swap), list_installed `drive`/`drive_missing` (install_state keeps such games
+    "installed"). PC: `install/drives.py`, library setting `install.drive` (Frame page → Storage), game menu
+    "Move to…" (job kind tool-frame), CLI `frame drives`/`frame move`/`install --dest`. Untested on the device.
   - **PC VR repacks are pre-patched to run directly** (proven: Rick and Morty, Vader Immortal run when the exe is
     launched directly; Revive breaks them). So Rift games default to `as_is` = install the copy unchanged and launch
     the exe directly (`pcvr.xr_timefix` for the Frame OpenXR-1.1→1.0 fix, `pcvr.no_crash_reporter` for Unreal).
@@ -111,11 +130,20 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
     set: the name on a colour from the title hash + the APK icon, `steam_set_for`; 2D Android apps get no store lookups) and tags: how it runs, the original platform
     (Meta Quest / Oculus Rift), genres, user tags — merged with tags set in Steam (non-Steam shortcuts can't hold a
     description).
-  - Linux apps (GitHub #31, library kind `linux`, `linux.<slug>`): GUI = Add games → "Add a Linux app (arm64)…" /
+  - Linux apps (GitHub #31, library kind `linux`, `linux.<slug>`; x86_64 builds run through FEX (app 3127680, no SLR:
+    RootFS /usr/share/guestos/fex-mesa from the OS image; needs `STEAM_COMPAT_DATA_PATH`, see docs/FRAME_RUNTIME.md):
+    agent v61 `linux_x86_tools`/`pick_tool`, `install_proton`/`proton_status` `kind: linux_x86`, `finalize_linux
+    x86_64`, `installer.ensure_proton(kind=)`; an arm64 program wins over an x86_64 one): GUI = Add
+    games → "Add a Linux app…" /
     "…folder…" (`app.add_linux` job → `pipeline.add_linux_app`); game page `linux_summary` (program + Change…, AppImage,
     OpenXR, source) instead of recipe/patches, `C.missing_libraries` callout (Frame deployment, else last install);
     no Analyze/Rebuild/recipe/share/Game settings actions, Frame only; platform "Linux" badge + library filter; Steam
     tags "Linux app on Frame"/"Linux"; `_follow_catalog` skips them; local files of a lone AppImage = the file only.
+    Desktop Mode entries (GitHub #84, agent v63): finalize_linux writes `frameport-<slug>.desktop` to
+    ~/.local/share/applications (+ ~/Desktop if it exists; `X-FramePort-Package` marks ours), launch.sh with
+    `FRAMEPORT_DESKTOP=1` skips the Steam-parent watchdog and Steam's display; ensure_host_fixes refreshes entries
+    (older installs, stale ones removed), uninstall/purge remove them. Per app: library entry field `desktop_entry`
+    (default on; patches don't apply to Linux apps) → game page switch → agent `desktop_entry`. Untested on device.
   - Quest/Rift twins stay separate entries, shown and named in Steam "Title (Quest)"/"(Rift)" (`core/titles.py`).
   - `Recipe.as_is` = install unchanged (pre-patched libraries): `pipeline.prepare_as_is`; auto for APKs that already
     contain FrameBridge (`frame_patched`). For Rift it changes nothing (the dump is never modified; the Frame copy
@@ -131,6 +159,10 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
   - `patches/` — **the unit of modularity**. `base.py` (Patch interface, registry), `overport.py` (overport CLI patch ids,
     discovered dynamically via `overport patches`), `frame/*.py` (one module per Frame fix), `settings.py` (FrameBridge
     adapter keys + device files as patches). Add a patch = add a module that calls `register(...)`.
+    `upstream.py`: upstream fixes that replace a workaround per build (a probe finds the fix in OVRPort's output →
+    the build leaves the workaround out, `build.superseded`; recipes unchanged). Registered: `ovrport.haptic_envelope`
+    (→ `adapter.haptic_fix`, `frame/haptic_envelope.py`) and `ovrport.microphone_stream` (→ `frame.ovr_microphone`),
+    both fixed in OVRPort runtime 3.4.3-aa54c3f (ovrport/app#73; haptics owner-verified with Lucky's Tale 2026-10-07).
   - `analysis/` — APK/ELF inspection (`detect.py`), `elf.py` (pyelftools reads; own DT_NEEDED writer), `stubgen.py`
     (generates the ovr_* stub .so without a compiler).
   - `apk/` — `axml.py` (binary manifest editor), `workspace.py` (staged zip edits), `sign.py` (apksigner; it aligns too).
@@ -613,6 +645,40 @@ head-pose deadline ends VR mode without a worn headset (not a game bug).
 layers, depth, pacing ruled out. Sniper Elite VR (DEVICE LOST), Espire 1 (Mesa GL upload crash), HITMAN 3 (freedreno
 crash): use PC versions.
 
+**Install links / FrameDrop button protocol (2026-10-07, not yet clicked end to end from a browser):** FrameDrop
+(framedropvr.com, a closed-source Windows sideloader) defines "Install with FrameDrop" buttons:
+`https://framedropvr.com/install?manifest=<url>|url=<file>` → that page opens `framedrop://install?…` (1.6 s, else its
+home page); manifest `{"schema":"framedrop.install/v1","name","files":[{"url","sha256"}]}` (name = Steam title; .apk
+or Linux .zip). `deeplink.py` (no Flet) parses framedrop://, frameport:// and the pasted https link, enforces its
+rules (https; http only on loopback; no credentials; no LAN/loopback/link-local IPs, also after DNS and redirects; URL
+ends in a file name), caps manifests at 256 KiB, ignores non-hex sha256 (FrameDrop's own example has a placeholder),
+downloads into `<data>/downloads/<slug>-<hash>/` (OBBs → `obb/` next to the APK, `.part` removed on cancel/mismatch);
+`pipeline.add_from_link` routes APK / Linux / exe and sets `title` + `title_locked` + `link` (a bare file link keeps
+FramePort's title). GUI: `views/link_dialog.py` (always asks first), Add games → "Install from a link…", CLI
+`frameport open-link [--yes --no-install --gui]`. **A `flet build` bundle can't take a URL argument** (the Flutter
+host treats any argv as a developer page URL), so `urlhandler.py` registers a script, not FramePort.exe: Windows
+HKCU `Software\Classes\{framedrop,frameport}` → hidden PowerShell `frameport-link-handler.ps1`; WSL (source runs)
+the same keys → `wsl.exe -d <distro> -e sh frameport-link-handler.sh`; Linux `frameport-links.desktop` +
+`xdg-mime`; macOS unsupported (Apple Events, paste instead). The script drops the link into `<data>/links/*.link`
+and starts FramePort unless `<data>/gui.alive` is < 10 s old (`gui.starting` stops double starts); the GUI's
+`_watch_links` thread touches the heartbeat and opens links (newest window session). Settings → Install links: one
+switch per scheme (`links.framedrop`, `links.frameport`, default on); a scheme another program owns (FrameDrop) is
+only taken with "Use FramePort for these links" (`register([s], force=True)`); off removes only FramePort's own
+registration (`MARK` in the command). Never registered with FRAMEPORT_HOME/FRAMEPORT_NO_LINK_HANDLER (tests,
+screenshots). Same round: files dropped on the Library (`ui/dropped.py`, bundles only like the Files tab), "Add a
+Windows program (.exe)…" (`pipeline.add_windows_exe`: exe in Downloads/home/drive root copied alone into
+`<data>/windows-apps/<slug>/`), patch `device.display_mode` (Automatic / VR / Flat window → `InstallContext.display`,
+`installer.show_window`). FramePort-only manifest extension `"frameport": {"description", "icon"}` (bad values ignored; icon: same URL rules,
+≤2 MiB, Pillow-checked, ≥32 px, saved as PNG in `<data>/downloads/icons/`, shown in the question by asset URL, then
+`sources.apply_custom(pkg, "icon")` unless `.picked` exists; description fills `details.description` only when
+empty). Bare file links get a title guessed from the file name (`title_from_filename`: version/arch dropped, package
+names → last part). Windows test of 0.12.1.dev191 (2026-10-07): a button click opened the dialog; but a click right
+after closing FramePort did nothing (the closed window's heartbeat was < 10 s old) → the handler scripts now wait
+up to 4 s for the link file to be taken before trusting the heartbeat, the window's CLOSE event / atexit delete
+`gui.alive`, and the Windows command runs under `conhost.exe --headless` (plain `-WindowStyle Hidden` flashed a
+console). Screens: `scripts/ui_smoke.py --links --fake-frame --game <pkg>` (tall pages: `--viewport
+1280x7000`; Flutter's popup menu ignores Escape).
+
 ## Releases, CI, GitHub
 Maintainer-only notes (accounts, credentials, key locations) live in the git-ignored `CLAUDE.local.md`.
 Public repo `github.com/spoopyghosty0/frameport` (branch `main`). Push a `v*` tag → CI (`.github/workflows/build.yml`)

README.md

@@ -28,11 +28,15 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V
   curved and 360° layers); game settings as simple switches.
 - **Beyond Quest:** Android apps as windows, PC VR via Proton or Revive, Windows (non-VR) games via Proton, a Files
   tab with drag and drop.
-- **Linux apps:** install arm64 Linux apps (AppImage, a folder, or a zip/tar archive) on the Frame with a Steam
-  shortcut; they run natively on SteamOS.
+- **Linux apps:** install Linux apps (AppImage, a folder, or a zip/tar archive) on the Frame with a Steam
+  shortcut; arm64 builds run natively on SteamOS, x86_64 builds through Valve's FEX translator.
+- **Install links:** "Install with FrameDrop" buttons on web pages (the one-click protocol of the FrameDrop
+  sideloader) and pasted links open in FramePort, which asks, downloads, adds and installs the build.
 - **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.
+- **Monitor tab:** the running game's frame rate, the Frame's load, temperatures, power and battery live, and its
+  processes, which you can end. [More](#monitor).
 - **Self-updating** releases, redacted diagnostics, one-click problem reports and working-config sharing.
 
 ## Quick start
@@ -59,9 +63,9 @@ with OBB files): [docs/FAQ.md](docs/FAQ.md).
 ## Type on Frame
 
 Typing in VR is painful, so FramePort turns your computer's keyboard into a keyboard for the Frame. Open **Type on
-Frame** (keyboard icon on the sidebar's Frame card, the Steam Frame page, or a game's menu), select a text field in
-the headset and type: searches, logins, chat, in any app, in Steam or on the desktop. Paste longer text to type it in
-one go. Nothing to install: FramePort adds a virtual keyboard on the Frame while the window is open, without root.
+Frame** (its own tab in the sidebar), select a text field in the headset and type: searches, logins, chat, in any
+app, in Steam or on the desktop. Paste longer text to type it in one go. Nothing to install: FramePort adds a virtual
+keyboard on the Frame while the tab is open, without root.
 
 ![Type on Frame](docs/images/type-on-frame.png)
 
@@ -87,6 +91,17 @@ videos muted). Pick 360p to 1080p, or the headset view's full size. The picture
 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.
 
+## Monitor
+
+The **Monitor** tab shows what the Frame is doing while it's open: the running game with its frame rate against the
+display's refresh rate, CPU, graphics chip, memory, the hottest temperature with the fan speed, power draw and battery
+time left, each with a 2-minute chart. **Show details** adds every CPU core, all temperature sensors, where the power
+goes and the network. Below, the game's processes (or Steam's, or all of them) with their CPU, GPU and memory use:
+right-click one to end it, or end the whole game. Programs that Steam, SteamVR or the desktop need are marked and ask
+again. The Frame sends the numbers itself (about 1 % of one CPU core) and stops when you leave the tab.
+
+![Monitor](docs/images/monitor.png)
+
 ## Compatibility
 
 If a game has already been tested with FramePort, it will automatically use the optimal game config. Otherwise, FramePort

artifacts/SHA256SUMS

@@ -5,12 +5,13 @@ e7554c6343ee2989b0a273ee6230e65c25bfe6499eefd00de19f5f0fee58754f  ./arm64-v8a/li
 383054f8b3b41dde76d062c71856cd3163655e50009c08454bc1793f393ead65  ./arm64-v8a/libfpg.so
 06c8a17b37cb1513fdfeba87ece457a02097bb22dd0a3a3a8719fb8fea16b52a  ./arm64-v8a/libframe_xrshim.so
 9f5ba793d1804728394a8fe9e83028e13f1bc939b558892e7beb5c3662317259  ./arm64-v8a/libglshim.so
-d7709fe953a3170467ec0c53e6b715833014512fbd8d91803a9cb2aecf0961ad  ./arm64-v8a/libopenxr_loader_generic.so
+cc5b493cadefe76ad13fd096d3f8494a140ba593e0e1692db12d284bc548c1cf  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
 aa4dc0020c77e12d41ef6ce80b23ad90c9cb7e882338eddf2261efe8645cf38d  ./arm64-v8a/libvrapi.so
-f994e6bc9ae32ab7ad17ffc992e10dce19289bed44d577b5ac08d7e99eb0174d  ./armeabi-v7a/libopenxr_loader_generic.so
+c10412dd76a65a1d587b7ed226367d1a6f2bec238c733c97ee67eb8870c868e8  ./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
+b10b3a5c10c3339fc63fd9f6cb4d01ea29be11a863d0ebad1389ea69fd471940  ./linux-arm64-bin/fp_venc
 c2c70f4af1a5c3e6089dff1130161dd417f8044f99ec639eeecf1083930aab16  ./win-x64/fp_oculushmd.exe
 60ebc5fea05b8945082e2ca8b9f2eb74616012a26eb50133af273dff0fcddc42  ./win-x64/fp_vrsettings.exe

catalog/games/com.CortopiaStudios.Graves.yaml

@@ -0,0 +1,19 @@
+package: com.CortopiaStudios.Graves
+title: GORN2
+status: works
+tested_version: 1.10.1
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-07'
+  known_good_sha256: d8a7949edc90c19902eb89f888ad6a350475387d630991767b3097667ad16d4c
+  app: 0.12.0
+  overport_cli: 1.2.5
+  issue: 88
+source_hint: GORN 2

catalog/games/com.ToastVR.RichiesPlankExperience.yaml

@@ -0,0 +1,22 @@
+package: com.ToastVR.RichiesPlankExperience
+title: Richie's Plank Experience
+status: works
+tested_version: 2.3.585
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-07'
+  known_good_sha256: 7eb1366c2398e554624a5d66aefb0c731c64b1b6944bc1726d9187f123c37fb7
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 59
+  issue: 95
+source_hint: apks

catalog/games/com.characterBank.ruinsmagus.yaml

@@ -0,0 +1,21 @@
+package: com.characterBank.ruinsmagus
+title: RUINSMAGUS
+status: works
+tested_version: 1.2.3
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-07'
+  known_good_sha256: 230e5625fbdfebb47c4d96aeb87f45270e4e6c79a33c08315c90626ab7465fe5
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261006.6173745'
+  agent: 59
+  issue: 89
+source_hint: RUINSMAGUS

catalog/games/org.timecrisis.quest.yaml

@@ -0,0 +1,18 @@
+package: org.timecrisis.quest
+title: Time Crisis VR (Experimental)
+status: works
+notes: Fully playable at 120hz
+tested_version: 0.8.3
+engine: Other
+xr: OpenXR
+frame:
+- frame.sdl_clipboard
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 4e67411a8e9c0b5fbb19ca7908c4222aa5ad1b2d47a8f4b5018b4fe9c2f5324e
+  app: 0.12.0
+  overport_cli: 1.2.3
+  frame_build: '20261005.6135832'
+  agent: 59
+  issue: 80
+source_hint: TimeCrisisVR-v0.8.3-quest

catalog/triage.yaml

@@ -8,11 +8,26 @@ signatures:
     severity: fatal
     diagnosis: Lepton found no activity with category LAUNCHER.
     suggest: [frame.launcher]
+  - id: linux-x86-no-fex
+    pattern: '(cannot execute binary file: Exec format error|exec format error)'
+    severity: fatal
+    diagnosis: An x86_64 Linux program was started directly; the Frame's arm64 CPU needs FEX (x86 translation) for it. Reinstall the app with FramePort 0.12 or newer, which installs FEX and starts the program through it.
+    suggest: []
   - id: no-arm64
     pattern: 'INSTALL_FAILED_NO_MATCHING_ABIS'
     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: android-too-new
+    pattern: '(NoClassDefFoundError|ClassNotFoundException|NoSuchMethodError)\b.*(Landroid/window/|android\.window\.|(storeStoreFence|loadLoadFence)\(\)V in class Ljava/lang/invoke/VarHandle)'
+    severity: fatal
+    diagnosis: The app calls Android 12/13+ classes (android.window.*, VarHandle fences) that the Frame's Android 11 (API 30) container doesn't have; it needs a newer Android (e.g. minSdk 34 apps). Nothing to patch - it can't run until Valve updates the Frame's Android.
+    suggest: []
+  - id: web-wrapper
+    pattern: '(Creating TwaLauncher for com\.oculus\.browser|NameNotFoundException:? com\.oculus\.browser)'
+    severity: fatal
+    diagnosis: The app is a website in an Android wrapper (Trusted Web Activity) that opens Meta's browser (com.oculus.browser), which the Frame doesn't have, so nothing opens. There's no game to port - open the website (TWALauncherActivity's "Using URL" line) in a browser instead.
+    suggest: []
   - id: unity-render-crash
     pattern: 'CRASH\s*:.*#\d+\s+pc [0-9a-f]+\s+\S*libgallium_dri\.so'
     severity: fatal
@@ -91,6 +106,12 @@ signatures:
       harmless (Meta's OVRPlugin suggests plain Touch too); a game that suggests only these gets them again as Touch
       (profile_remap, on by default; log "controller profile ... -> oculus/touch_controller").
     suggest: []
+  - id: input-call-failed
+    pattern: 'input_diag: unsupported: (xrStringToPath|xrCreateAction|xrAttachSessionActionSets|xrSyncActions) ->'
+    severity: warning
+    diagnosis: The runtime refused one of the game's controller-input calls (logged by input_diag; the line names the
+      call, the result and the argument), so controls set up through it don't work.
+    suggest: []
   - id: gl-shader-failed
     pattern: 'GLShim\s*: SHADER COMPILE FAILED|#extension directive is not allowed in the middle|could not implicitly convert operands'
     severity: error

docs/ARCHITECTURE.md

@@ -35,6 +35,11 @@
 ## Extending
 - **New fix**: `patches/frame/<name>.py` with a `Patch` subclass (`detect`, `apply`, optional `validate`), plus a
   signature in `catalog/triage.yaml` and a PLAYBOOK row. Stages: `overport` | `apk` | `install`.
+- **Upstream fixed a bug we work around**: register an `UpstreamFix` (`patches/upstream.py`) in the workaround's
+  module: a probe that finds the fix in OVRPort's output (True / False / None = can't tell). Each build runs the probes
+  on the converted APK and leaves out the workarounds whose fix is there (log "not needed: …", `build.superseded`,
+  left out of settings.conf at install; game page and `frameport show` say so). The recipe keeps asking for the fix,
+  so builds made with an older runtime keep the workaround. `FRAMEPORT_KEEP_WORKAROUNDS=1` turns it off.
 - **New heuristic**: put it in the patch's `detect()` (and `applies()` for visibility), with the evidence in the
   reason text; check `scripts/eval_heuristics.py` still reproduces the catalog and add a test in
   `tests/test_heuristics.py`.

docs/FRAME_RUNTIME.md

@@ -28,6 +28,23 @@
   work on Android 11: `policy_control` is gone, `cmd statusbar send-disable-flag home recents` has no `back` and
   moves the back button onto the app's controls, the `sysui_nav_bar` layout and disabling SystemUI had no effect.
 
+## Where FramePort keeps games (internal storage, microSD)
+- Every game has an **anchor** on internal storage: `~/Applications/quest-frame/<pkg>/` with `launch.sh`,
+  `deployment.json`, `artwork/` and `plays.log`. Steam's shortcut points at the anchor's `launch.sh`, so it never
+  changes when the files move.
+- The game's files (`lepton-app/`, `lepton-data/` = saves, `lepton-shaders/`, `settings.conf`, `launch.log`; PC VR:
+  `game/`, `revive/`, `compatdata/` = Proton prefix; Linux: `app/`) live in `deployment.json["base"]`: the anchor
+  itself on internal storage, or `<mount>/FramePort/<pkg>` on another drive (GitHub #90, agent v63).
+- SteamOS mounts removable drives (microSD) under `/run/media/<user>/<label or uuid>`; the agent's `drives` reads
+  `/proc/mounts` (plus the drives of Steam library folders) and refuses vfat/exfat/ntfs (Lepton's data and Proton
+  prefixes need Unix owners, permissions and symlinks) and read-only mounts. A drive that isn't mounted is an error for
+  new installs (never a silent fallback to internal storage); `list_installed` marks games on it `drive_missing` and
+  their launchers stop with "storage not mounted?".
+- `move` copies with `cp -a` inside `podman unshare` (files Lepton's containers own belong to subordinate user ids),
+  compares file count + bytes, retargets absolute symlinks into the old folder (the LibOVRRT → Revive redirect), points
+  `launch.sh` at the new folder and only then deletes the old copy; on the same filesystem it renames instead.
+  Moving a game whose Lepton data holds absolute paths, or a PC VR prefix, is not yet verified on the device.
+
 ## OpenXR runtime (as seen by games through overport's loader)
 - Instance extensions present include KHR_android_create_instance (must be enabled; the adapter adds it),
   KHR_vulkan_enable(2), KHR_opengl_es_enable, KHR_composition_layer_depth, FB_display_refresh_rate, EXT_hand_tracking
@@ -69,6 +86,17 @@
   SteamLinuxRuntime_4). None are installed by default.
 - `steam -ifrunning steam://install/<appid>` only opens a confirmation dialog in the headset. The agent's unattended
   mode writes an appmanifest stub (StateFlags 1026, installdir from appinfo) and restarts Steam, which then downloads it.
+- **x86_64 Linux apps (agent v61; verified on the device 2026-10-07: an x86_64 glibc test program installed + launch test RUNNING, "machine=x86_64 glibc=2.41"):**
+  FEX is Steam app 3127680 (`fex`, installs as `common/FEX-Emu`, ~6 MB, 21 s via the appmanifest-stub path:
+  `install_proton` / `proton_status` with `kind: linux_x86`). Its toolmanifest commandline is
+  `/fex-compat-tool %verb% --`, **no** require_tool_appid: it does not use the Steam Linux Runtime. fex-compat-tool
+  (Python) runs `<FEX-Emu>/usr/bin/FEX` with RootFS `/usr/share/guestos/fex-mesa` (part of the SteamOS image: an
+  x86 Arch-style root with glibc 2.41, Mesa, graphics_provider.json for x86_64 + i386), emulates x86_64 and i386
+  (emulator.json), honours `STEAM_FEX_TSOENABLED`, `STEAM_FEX_MULTIBLOCK`, `STEAM_COMPAT_FEX_CONFIG`, sets
+  `tu_override_uncached_as_cache_coherent=true` and logs to `/tmp/fex-compat-tool-<pid>.log`. It **exits 1 ("No compat
+  data path?") without `STEAM_COMPAT_DATA_PATH`** (keeps Config.json/AppConfig/Server/Telemetry in `<it>/fex-emu/`):
+  the Linux launcher exports `<base>/compatdata`. Version seen: FEX-2607-76-g37265b1. ldd can't read x86 programs,
+  so the missing-library check is skipped for them; an x86_64 AppImage is extracted through the same chain.
 - The command Steam runs is built from each tool's `toolmanifest.vdf` (`commandline`, `require_tool_appid`):
   `<SLR4-arm64>/_v2-entry-point --verb=waitforexitandrun -- <Proton>/proton waitforexitandrun <exe>`.
 - Proton sets up VR (vrclient/wineopenxr registry) only when `SteamGameId` is set (steam_helper `setup_vr_registry`).
@@ -109,6 +137,12 @@
 - Processes started from Steam (Konsole, SSH sessions?) share steam.service's cgroup: use `systemd-run --user`.
 - 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`.
+- Desktop Mode menu entries (GitHub #84, agent v63): Linux apps get `~/.local/share/applications/frameport-<slug>.desktop`
+  (+ an executable copy in `~/Desktop` when that folder exists; Plasma starts executable `.desktop` files there
+  without a trust prompt), `Exec=env FRAMEPORT_DESKTOP=1 "<anchor>/launch.sh"`, marked `X-FramePort-Package=<pkg>`.
+  Plasma's launcher exits right after starting the program, so with `FRAMEPORT_DESKTOP=1` the Linux launcher skips
+  its "Steam parent gone → end the app" watchdog and keeps the desktop's DISPLAY/WAYLAND_DISPLAY instead of taking
+  gamescope's from Steam. Not yet tried from the Frame's Desktop Mode.
 
 ## 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
@@ -131,7 +165,60 @@
   `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.
+  cores with a busy scene. That is now only the fallback.
+- Hardware encoding (2026-10-07): the iris encoder works when driven directly through the V4L2 stateful encoder
+  interface. That is FramePort's `fp_venc` (`native/venc`, spec + every measured value in `native/venc/SPEC.md`).
+  Facts:
+  - Device: `/dev/video23` (`/dev/video-enc0` links to it), driver `iris_driver`, M2M multiplanar.
+  - Formats: input NV12/NV21/AB24(RGBA)/QC24/Q08C; output H264/HEVC; sizes 128..8192.
+  - NV12 layout (S_FMT answers):
+    - stride is a multiple of 128;
+    - the returned height is padded to a multiple of 32;
+    - CbCr starts at stride × padded height;
+    - sizeimage is rounded up to 4 KiB;
+    - the default crop is the requested size.
+  - Controls: CBR, FORCE_KEY_FRAME, PREPEND_SPSPPS_TO_IDR, HEADER_MODE joined, FRAME_SKIP_MODE, H.264 profiles
+    Baseline..Constrained High, levels up to 6.0.
+  - The `steamos` user can open it (group video).
+  - The panel's current refresh rate can be read without privileges through DRM: `/dev/dri/card0` is mode 0666, and
+    GETCRTC reports e.g. `2*2160x2160_96` (clock 1402720 kHz / 4448 × 3285 = 96 Hz) even while the headset sleeps.
+    The panel offers 72/80/90/96/108/120/144 Hz.
+  - `/dev/video99` (v4l2loopback) has `max_buffers=2`: a reader asking for more gets 2.
+  - Mid-stream keyframe requests (FORCE_KEY_FRAME) take effect on the next frame, and the GOP restarts from there.
+  - Measured 2026-10-07 with the headset asleep (still picture):
+    - `fp_venc` alone at 32/36 fps: 1% of a core at 1080p, 2.5% at 720p.
+    - Live view end to end: `fp_venc` 2.6% + ffmpeg 8.4% (AAC encoding + muxing).
+  - Conversion cost per new picture (self-test, NEON, 2026-10-07):
+    - 1080p (no scaling): 0.6–1.0 ms.
+    - 720p (exact 3:2 fast path): 1.3–1.65 ms, down from 5.6 ms with the generic box loop (~11 ms at idle clocks).
+    - 360p (3:1 fast path): 0.7 ms.
+    - 480p: 2.8 ms; its 852-px width doesn't repeat cleanly, so it uses the generic path.
+    - At 36 fps with live content that is roughly 2–6% of a core.
+  - ffmpeg with raw H.264 on a pipe:
+    - `-framerate` is ignored.
+    - `-fflags nobuffer` loses the first seconds of tiny frames.
+    - Numbering frames from 0 (`setts`) with no input timestamps holds all output ~7 s next to pulse's audio.
+    - Arrival stamps alone (`-use_wallclock_as_timestamps 1`) bunch frames that are read together: gaps of 0–10 ms
+      and 45+ ms, seen in the headset test as dropped frames.
+    - What works: `-probesize 32 -analyzeduration 0 -use_wallclock_as_timestamps 1` on the input (ffmpeg reads it in
+      step with the audio), then `-bsf:v setts=ts=N*(1/fps)/TB` on the output (exactly even frames; audio still
+      0–N s alongside), plus `frag_keyframe` so that a requested keyframe starts a fragment.
+    - With sound, ffmpeg paces its inputs against each other and pulse's audio arrives later than the wall clock
+      (more while something plays). The video input then counts as ahead, and ffmpeg stops reading it for up to
+      0.7 s, so the writer blocks. That was the cause of 1080p dropping frames: busy 1080p replayed with sound took
+      34–47 s for 20 s of video. Video alone was fine; `nice`, `-raw_packet_size` and the input queue size didn't
+      matter. Shifting the video input back fixes it, but too far makes ffmpeg hold the video for interleaving and
+      release it in clumps: -1 s gave output gaps of up to 550 ms, a longer and stuttering delay in the browser.
+      -0.25 s is the measured sweet spot (no stalled writes at busy 1080p with sound, steady 50–150 ms output; -0.5 s
+      already clumps). Output audio/video spans stay equal because setts sets the output times.
+    - Browser delay (headless Chromium, 720p, 2026-10-07): muted about 0.2–0.35 s behind the newest data; with
+      sound about 1 s. Chrome keeps about 0.6 s of audio ahead and stalls below that, whatever the player does:
+      1.1× catch-up gave 8 stalls per 30 s, no speed-up 1–2, same average lag; 50 ms fragments didn't help. So the
+      player doesn't speed up while sound is on.
+  - Quality (owner's headset test, 2026-10-07): 3 Mbit/s CBR at 720p36 showed heavy compression artifacts. The
+    hardware path now uses VBR with a 1.5× peak (the encoder accepts BITRATE_MODE VBR + BITRATE_PEAK) and higher
+    targets: 360p 1.5, 480p 2.5, 720p 5, 1080p 8, Full 10 Mbit/s. The x264 fallback keeps its rates.
+  - The default sink is SUSPENDED while nothing plays; its monitor still delivers (silent) audio.
 
 ## Text input
 
@@ -143,3 +230,26 @@
   one everywhere (FramePort's "Type on Frame", agent `_keyboard`).
 - Unity text fields close without a system keyboard; see `frame.unity_text_input` in PLAYBOOK.md.
 
+
+## Monitoring sources (probed 2026-10-07, SteamOS 0.4.3, kernel 6.18; used by the Monitor tab, agent `_monitor`)
+
+All readable by the steamos user without root; the agent reads them directly (no programs started per sample).
+
+| Metric | Source | Notes |
+|---|---|---|
+| CPU | `/proc/stat` deltas; `cpufreq/policy{0,2,5,7}` | 8 cores in 4 clusters: 0-1 / 2-4 / 5-6 / 7 (max 2.27 / 3.15 / 2.96 / 3.05 GHz) |
+| GPU busy | Sum of `drm-engine-gpu` (ns) deltas in `/proc/<pid>/fdinfo/<fd>` over every render-node fd (msm DRM) | Gives GPU % per process too. A process can hold several render fds: add them all. Lepton games see the node as `/dev/kgsl-3d0` (bind mount of `/dev/dri/renderD128`). `drm-total-memory` reads 0 |
+| GPU clock | `/sys/class/devfreq/3d00000.gpu/{cur,max}_freq` | 231–903 MHz in 12 steps |
+| Memory / pressure | `/proc/meminfo`; `/proc/pressure/{cpu,memory,io}` (`some avg10`) | 16 GB RAM, 8 GB swap |
+| Temperatures | `/sys/class/thermal/thermal_zone*/{type,temp}` | 48 zones: `cpu*`/`cpuss*`, `gpuss-*`, `ddr`, `nsph*` (NPU), `pm8550*`/`pm8010*` (power ICs), `modem*`, `camera*`, `video`, `max1720x_bat*` |
+| Fan | hwmon `slg4ax46073v` `fan1_input` | ~8200 rpm idle |
+| Power | hwmon `max34417_*` `power{1-4}_{label,input}` (µW) | `vph` = whole system (~3.6 W idle), `gfx` = GPU, `apc0/1/2` = CPU clusters, `nsp1/2` = NPU; each read is an I2C transfer (~0.7 ms wall), so only these are read |
+| Battery | `power_supply/max1720x_bat_7-36` | `current_now` (µA, negative = draining) × `voltage_now` (µV) = watts; `time_to_empty_now`/`time_to_full_now` (s), `cycle_count`, `health`, `temp` (0.1 °C) |
+| Game fps | `<base>/launch.log` lines `FrameBridge: pacing: N fps …` (every ~5 s) | Quest games only; SteamVR writes PC VR frame stats only as an end-of-session summary in `vrcompositor.txt` |
+| Game container | conmon `-n lepton-steamlaunch-<appid>`; its child's `/proc/<pid>/cgroup` → `cpu.stat`, `memory.current` | The container's ~90 Android processes show as uid 1000 on the host and can be signalled (4XVR, 2026-10-07); Android names them after the package's last 15 characters (`lus4xvrplayerov`), the full name is in `cmdline` |
+
+Cost: a naive sample (fds of ~520 processes scanned) took 43 ms CPU. With kernel threads skipped after their first
+sighting, command lines checked once per process, render fds cached (rescanned every 60 s, every 4 s for busy young
+game processes without one), temperatures every 2 s, the CPU-cluster power rails every 5 s and the battery gauge every
+2-10 s, the stream measured ~10-13 ms CPU per 1 s tick on the device (idle clocks; idle or with 4XVR running) = about
+1 % of one core, ~0.15 % of the whole CPU. The I2C sensors (power monitors, battery gauge) are the slowest reads.

docs/GAMES.md

@@ -27,6 +27,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Dinosaur Island | Quest | ✅ Works |  |
 | Espire 2 | Quest | ✅ Works |  |
 | Genotype | Quest | ✅ Works |  |
+| GORN2 | Quest | ✅ Works |  |
 | H.U.N.T | Quest | ✅ Works |  |
 | I Am Cat | Quest | ✅ Works |  |
 | I Am Monkey | Quest | ✅ Works |  |
@@ -50,9 +51,11 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Path of the Warrior | Quest | ✅ Works |  |
 | PowerWash Simulator VR | Quest | ✅ Works |  |
 | QuestCraft | Quest | ✅ Works |  |
+| Richie's Plank Experience | Quest | ✅ Works |  |
 | Rick and Morty: Virtual Rick-ality | PC VR | ✅ Works |  |
 | Riven | Quest | ✅ Works |  |
 | Robo Recall | Quest | ✅ Works |  |
+| RUINSMAGUS | Quest | ✅ Works |  |
 | Sniper Elite VR: Winter Warrior | Quest | ✅ Works |  |
 | Space Pirate Trainer Quest | Quest | ✅ Works |  |
 | Stremio | Quest | ✅ Works |  |
@@ -62,6 +65,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | The Boys VR | Quest | ✅ Works |  |
 | The Climb 2 | Quest | ✅ Works |  |
 | The Room VR | Quest | ✅ Works |  |
+| Time Crisis VR (Experimental) | Quest | ✅ Works |  |
 | Toy Master | Quest | ✅ Works |  |
 | Under Cover | Quest | ✅ Works |  |
 | VR4 | Quest | ✅ Works |  |
@@ -71,6 +75,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Arcsmith | Quest | ⚠️ Works with issues | Right eye distorts during movement (unresolved; swap, tracking, Valve layers, depth and pacing ruled out). |
 | Assassin's Creed Nexus | Quest | ⚠️ Works with issues | Some launch warning text is still upside down; the rest of the UI is fixed by flip emulation. |
 | BONELAB | Quest | ⚠️ Works with issues | Build 1.2068 plays (head tracking and controls work with frame.unity_user_presence); the newer build 1.2974 crashes at start (Vulkan), no fix yet. |
+| Doom3Quest | Quest | ⚠️ Works with issues | PDA shows black screen. |
 | Myst | Quest | ⚠️ Works with issues | Minor graphical glitches on some objects. |
 | Phantom: Covert Ops | Quest | ⚠️ Works with issues | DLC/store button crashes (no Meta store). |
 | Pinball FX VR | Quest | ⚠️ Works with issues | Plays; mixed reality mode not working yet. |

docs/INSTALL.md

@@ -85,13 +85,50 @@ which would end Desktop Mode). This is new: please report anything odd with **Re
 - If the Frame goes to sleep, turns off or leaves the Wi-Fi, the queue **waits** and continues once it's back; uploads
   pick up where they stopped. While installs run, FramePort keeps the Frame from going to sleep. Before a large batch
   it checks the Frame has enough free space.
+- **microSD card / other drives:** the **Steam Frame** page's **Storage** section lists the Frame's drives and sets
+  where new games go (**Install new games to**). Games go into a `FramePort` folder on the card. To move a game that's
+  installed already, right-click it → **Move to…** (the game must be closed; saves, settings and the Steam entry stay).
+  A game on the card only starts while the card is inserted (FramePort then says "SD Card not inserted"). Cards
+  formatted as FAT, exFAT or NTFS can't hold games: format the card in SteamOS first.
 - Your own game files are never changed. The converted copy is temporary: it's removed once the game is on the Frame
   (Settings → Installing: keep them, or remove all now).
 - **Game settings…** (game menu or the Steam Frame page): sharpness, refresh rate, controllers, menus, 360° video and
   mixed-reality options in plain words, only those that matter for the game. Changes are kept with the game and,
   when it's installed, used the next time it starts.
 - Ordinary Android apps (no VR) are installed unchanged and shown as a flat window in the headset. Android's
-  back/home/recents buttons are hidden by default (patch **Hide Android's navigation bar**).
+  back/home/recents buttons are hidden by default (patch **Hide Android's navigation bar**). If FramePort guesses
+  wrong (a phone app shows nothing in the headset, or a VR app opens as a flat window), choose **VR** or **Flat
+  window** under **Show as VR or as a flat window** in the game's **Customize** section, then **Update on Frame**.
+- **Add games → Add a Windows program (.exe)…** adds a single Windows program; the Frame runs it through Proton (as a
+  window unless it is a VR game). A program sitting in Downloads, the home folder or a drive root is copied on its
+  own first, so the install doesn't upload everything next to it.
+- In the packaged app you can also **drag files onto the Library**: APKs, Linux apps (AppImage, `.zip`/`.tar.gz`),
+  Windows programs (`.exe`), folders, or a FrameDrop manifest (`.json`).
+
+### Install links ("Install with FrameDrop" buttons)
+
+Some developers put an **Install with FrameDrop** button on their site (the one-click protocol of the FrameDrop
+sideloader, documented at framedropvr.com/docs). FramePort understands the same links:
+
+- **Clicking a button** opens FramePort (or the window that's already open) on Windows and Linux. FramePort shows
+  the title, the files, their size and whether a checksum is given, and asks before it downloads anything. Then it
+  downloads the build, adds it to your library and starts the usual install on the Frame. If no Frame is connected,
+  the game is added now and installs once the Frame is back.
+- **Add games → Install from a link…** takes the button's address (right-click → Copy link), a `framedrop://` or
+  `frameport://` link, a manifest (`.json`) or a direct link to an APK, a Linux build or a Windows program. Use it on
+  macOS, where web pages can't hand links to FramePort yet.
+- **Settings → Install links** has one switch for `framedrop://` links (the buttons) and one for FramePort's own
+  `frameport://` links. Both are on by default. If FrameDrop is installed too and already opens `framedrop://`
+  links, FramePort leaves them to it; **Use FramePort for these links** takes them over (turn the switch off to give
+  them back).
+- **For developers:** a FrameDrop manifest works as it is
+  (`{"schema": "framedrop.install/v1", "name": "…", "files": [{"url": "https://…", "sha256": "…"}]}`). FramePort
+  also reads an optional `"frameport": {"description": "…", "icon": "https://….png"}` object (FrameDrop ignores
+  it): the install question then shows the icon and description, and they become the game's icon and "About this
+  game" text when no store has them. Without a manifest (a bare file link) FramePort guesses the title from the
+  file name and replaces it with the app's own name once it's downloaded.
+- Only `https://` links to public servers are used (plain `http://` only on this PC, for testing); links with a
+  user name or password, or pointing into your local network, are refused. Only install from sites you trust.
 
 ![Game page](images/game.png)
 
@@ -102,10 +139,10 @@ reality), showing only what matters for that game. Changes are kept with the gam
 
 ## Typing on the Frame
 
-- **Type on Frame** (Steam Frame page, a game's menu, or the keyboard icon on the sidebar's Frame card): while the
-  window is open, this computer's keyboard works as a keyboard plugged into the Frame. Select a text field in the
-  headset (in an app, Steam or the desktop) and type; Esc and shortcuts go to the Frame too. Paste longer text into
-  the box to type it in one go (US keyboard layout). Click **Done** to disconnect.
+- **Type on Frame** (its own tab in the sidebar; also on the Steam Frame page and in a game's menu): while the tab is
+  open, this computer's keyboard works as a keyboard plugged into the Frame. Select a text field in the headset (in
+  an app, Steam or the desktop) and type; Esc and shortcuts go to the Frame too. Paste longer text into the box to
+  type it in one go (US keyboard layout). Opening another tab disconnects the keyboard.
 - **Steam's on-screen keyboard** opens for text fields of apps shown as a window (2D apps, and VR apps with
   **Show the app's Android window**). Steam lists that window as **Gamescope** (the Frame's display compositor);
   leave it open: it's what receives the typing, the VR view isn't affected.
@@ -113,6 +150,19 @@ reality), showing only what matters for that game. Changes are kept with the gam
   **Make Unity text fields work** for them. The first time, it downloads Cpp2IL (a tool that finds the right spot in the
   game's code, ~17 MB). Games added before this version: open the game's menu → **Analyze again**, then reinstall.
 
+## Watching the Frame (Monitor)
+
+- **Monitor** (its own tab in the sidebar) shows live what the Frame is doing while the tab is open: the running game
+  with its frame rate (Quest games), CPU, graphics chip, memory, the hottest temperature with the fan speed, power
+  draw and battery time left, each with a 2-minute chart. **Show details** adds every CPU core, all temperature
+  sensors, where the power goes and the network.
+- **Processes**: **Game** (default) lists the running game's processes, **Steam & SteamVR** and **All** show more.
+  Right-click a process (or use **⋯**) to end it, force-kill it or end its whole game; **End game** on the game card
+  closes the game the way Steam's Exit game does. A lock marks programs whose end would close Steam, SteamVR or the
+  desktop: FramePort asks again before ending those.
+- The numbers come every second (or every 2/5 s) and cost the Frame about 1 % of one CPU core; nothing keeps
+  running on the Frame after you leave the tab.
+
 ## Updating
 
 **Game configs** (the tested recipes in the catalog) update by themselves: FramePort checks GitHub every 6 hours for
@@ -156,18 +206,25 @@ starts it if asked). FramePort installs it on the Frame and Proton runs it as a
 it shows up in the Frame's Steam library tagged "Windows game on Frame". Whether a game runs depends on Proton on ARM
 (x86 games run through emulation).
 
-## Linux apps (arm64)
+## Linux apps
 
 The Frame runs SteamOS on an arm64 CPU, so native Linux apps built for **aarch64/arm64** run on it directly (no
-Android container, no Proton). **Add games → Add a Linux app (arm64)…** takes an AppImage or a `.zip`/`.tar.gz`/
+Android container, no Proton). **Add games → Add a Linux app…** takes an AppImage or a `.zip`/`.tar.gz`/
 `.tar.xz` archive; **Add a Linux app folder…** takes an unpacked app. FramePort finds the program that starts it (the
 game page's **Change…** picks another one) and whether it's a VR (OpenXR) app. **Install on Frame** uploads it
 unchanged and adds it to the Frame's Steam library, tagged "Linux app on Frame"; Play, launch tests and Uninstall
 work like for other games.
 
-- x86_64 builds can't run on the Frame: FramePort says so when you add one. Look for an aarch64/arm64 download.
-- The app must bring the libraries SteamOS doesn't have. If some are missing, the install reports them and the game
+- **x86_64 builds** run through **FEX**, Valve's x86 translator, with the x86 system libraries SteamOS ships for it
+  (the way Steam on the Frame runs x86 Linux games). The first install of one installs FEX on the Frame (Steam
+  restarts once and downloads it, a few MB). They run slower than arm64 builds: when an app offers both, FramePort picks the arm64 one. The game
+  page shows which CPU a build is for.
+- The app must bring the libraries SteamOS doesn't have (checked for arm64 builds; x86_64 builds use FEX's x86
+  system, which has glibc and Mesa, and aren't checked ahead). If some are missing, the install reports them and the game
   page lists them: look for a build that includes them.
+- **Desktop Mode:** Linux apps also appear in Desktop Mode's application menu and as an icon on its desktop. Some
+  apps work better there, with a mouse and keyboard, than in Gaming Mode (where Steam Input turns the controllers into
+  a gamepad). Switch it off per app on the game page (**Desktop Mode**).
 - From the command line: `frameport add-linux <AppImage, folder or archive> [--exe <program>]`.
 
 ## Files on the Frame (videos, documents, mods, saves)
@@ -207,12 +264,14 @@ and `frameport <command> --help` describe every option. The main ones:
 | Command | What it does |
 |---|---|
 | `scan <folder>` / `list` / `show <game>` | add games, list the library, show a game's analysis and patches |
-| `add-linux <path>` | add an arm64 Linux app (AppImage, folder or archive) |
+| `add-linux <path>` | add a Linux app, arm64 or x86_64 (AppImage, folder or archive) |
 | `recipe <game> --enable/--disable <patch>` | change a game's patches (`patches` lists them all) |
 | `build <game>` / `install <game>` / `test <game>` | build, install on the Frame (`--to pc` for PC VR on this PC), launch test |
 | `frame discover` / `frame connect` / `frame info` | find, pair with and describe the Frame |
 | `frame send` / `frame storage` / `frame cleanup` | copy files to the Frame, show where they go, free space |
+| `frame drives` / `frame move <game> --to <drive>` / `install --dest <drive>` | the Frame's drives (microSD), move a game, install to a drive |
 | `tools status` / `tools install` | the tools FramePort downloads |
+| `open-link "<link>"` | install from an "Install with FrameDrop" button's address or a manifest/APK/zip link (`--yes`, `--no-install`) |
 | `diag report <game>` / `share-recipe <game>` | report a problem / share a working recipe |
 | `update` | update FramePort |
 

docs/PLAYBOOK.md

@@ -21,7 +21,10 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | `cannot locate symbol "ovrPeerConnectionState_ToString"` (or another `ovr<Enum>_ToString`) at start (BlazeRush, GitHub #57) | OVRPort's platform loader lacks several Platform SDK enum helpers | `frame.ovrstubs` now stubs them too; `*_ToString` stubs return "" (not NULL) |
 | Exits right after the OpenXR instance is created: `Failed to create XR session: -50` (`XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING`, Lambda1VR) | the game skips `xrGet*GraphicsRequirementsKHR`; Meta's runtime tolerates it, SteamVR's doesn't. Lambda1VR's TBXR doesn't even enable `XR_KHR_opengl_es_enable` (only `XR_EXT_local_floor`) | FrameBridge adds `XR_KHR_opengl_es_enable` when an app enables no graphics API extension, asks for the requirements on the game's behalf and retries xrCreateSession once (logs `added XR_KHR_opengl_es_enable …`, `the app skipped …; asked for it`; every launch logs the final extension list `xrCreateInstance with N extension(s)`); triage `graphics-requirements-missing`. Verified headless: Lambda1VR runs at 72 fps |
 | Exits at start: `OVRAvatar-Loader: DisplayErrorAndExit: Failed to launch SystemActivities` after `ovrAvatar_Initialize: Failed to load AvatarSDK driver` (BlazeRush, GitHub #57) | Meta's avatar loader needs Horizon; it then tries Meta's error screen and aborts | `frame.avatar_stub` (same exports, do nothing); triage `avatar-driver-missing`. Games that ship the library but don't start avatars at launch (Lucky's Tale, BattleSisters, Arcsmith) don't need it |
+| Frame freezes or the game is killed (OOM) on the first controller vibration (e.g. Lucky's Tale's save slots, BattleSisters) | OVRPort runtimes up to 3.4.3-23204ea read the haptic envelope's duration (ns) as seconds and allocate gigabytes of samples (GitHub #9, ovrport/app#73) | `adapter.haptic_fix` (envelope → one plain vibration in `native/xrshim`). Fixed in runtime 3.4.3-aa54c3f: builds made with it leave the workaround out by themselves (log "not needed: adapter.haptic_fix", `frameport show` "last build left out"); rebuild an older build to switch |
 | Controller vibrations much stronger than on a Quest (The Boys VR, Jurassic World, BONELAB, …) | OVRPlugin games send amplitude envelopes; `haptic_fix` turned each into one vibration at the envelope's *peak* for its whole duration (a short fading pulse became a long full-strength buzz) | `haptic_fix` now uses the envelope's RMS; Game settings → "Vibration strength" (`haptic_scale`, 0-1) scales every vibration in FrameBridge; launch.log shows the first requests (`haptic: …`). OVRPlugin stops a vibration with amplitude 0 (2 s duration): FrameBridge turns that into xrStopHapticFeedback (without it the last buzz ran its full 2 s) |
+| Play or a launch test fails at once: `Game files missing at <path> (storage not mounted?)` in launch.log, or "… files are on a drive that isn't inserted" (GitHub #90) | the game was installed or moved to a microSD card (`<mount>/FramePort/<pkg>`) that isn't inserted or mounted now | insert the card; or move the game back (game menu → Move to…, `frameport frame move <pkg> --to internal`) once the card is back. `frameport frame drives` shows what the agent sees (exFAT/NTFS cards are refused: format in SteamOS) |
+| A Linux app started from Desktop Mode's menu closes after ~2 s, or opens on the wrong display (GitHub #84) | its launcher predates agent v63: the "Steam parent gone" watchdog ended it when Plasma's launcher exited, and it took gamescope's DISPLAY from Steam | connect FramePort once (agent v63's `upgrade_launchers` adds the `FRAMEPORT_DESKTOP` checks; the menu entry runs `env FRAMEPORT_DESKTOP=1 <anchor>/launch.sh`). Game Mode controller problems in such apps are Steam Input's (a separate issue) |
 | Every game suddenly fails to start: `crun: create keyring …: Disk quota exceeded`, `is not a running context` | rootless podman leaked a kernel keyring per launch; 200-key quota exhausted | `keyring = false` in `~/.config/containers/containers.conf` (FramePort agent does it), then reboot the Frame once |
 | A Unity app's text field shows a caret for a moment and loses focus; no keyboard appears (e.g. Stremio VR login) | Unity's TMP_InputField/InputField wait for Android's on-screen keyboard and close themselves without one (Lepton has none); headless VR apps also have no focused Android window, so no key press reaches them | `frame.unity_text_input` (Cpp2IL finds `TouchScreenKeyboardShouldBeUsed`/`isKeyboardUsingEvents`, rewritten to false/true) + `device.text_input_window` (lepton-show-flatscreen: Steam's keyboard and Type on Frame work) |
 | Play gives Steam's "Game configuration unavailable"; Steam's console_log: `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` | this Frame's Steam never loaded FramePort's shortcuts.vdf entry (it treats the id as a store app); cause unknown (GitHub #21/#30) | automatic since agent v43: Play registers the game through Steam's devkit interface ("Devkit Game: …", `devkit_register`) and starts that; uninstall removes it. Agent v58: a devkit entry Steam forgot after a restart is added again live on Play (no NOT_IN_LIBRARY → no Steam restart), and installs/art updates of devkit games only copy art (no Steam restart, GitHub #41) |
@@ -29,6 +32,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Black screen at start while audio/ExoPlayer runs; log `xrEndFrame: dropped N unusable layer(s)`, a quad layer with swapchain 0x0 (e.g. I Am Monkey's intro video) | The game plays video into an Android-surface swapchain (XR_KHR_android_surface_swapchain); the Frame's runtime lists the extension but returns FUNCTION_UNSUPPORTED | adapter `surface_emul` (default on): FrameBridge gives the player a SurfaceTexture-backed Surface and copies each frame into an ordinary swapchain (log `surface_emul: …`) |
 | The game quits right after start: `Something failed to initialize. Quitting!` / `We don't have write permission to …/files/cloud/data` (e.g. SUPERHOT) | The game created a save folder with mode 1700; inside Lepton the app writes through the folder's group | launch.sh `fix_perms` adds owner + group write to every folder in the game's storage (agent 41); reinstall to get the new launcher |
 | The whole Frame slows to a halt, then the game is killed (`Out of memory: Killed process … anon-rss:10+ GB`), e.g. Lucky's Tale | The game's own memory grows ~1 GB/s on Unity's `Loading.PreloadManager` thread (perf page-fault profile); not the flat window, not the text-input patches | none yet: mark unsupported; profile with `perf record -p <pid> -e page-faults --call-graph fp` (works as steamos, `perf_event_paranoid` 2) |
+| A Linux app exits at once: `cannot execute binary file: Exec format error` in launch.log | an x86_64 program started directly (installed before FramePort ran x86 builds through FEX, or by hand) | reinstall it: x86_64 Linux apps install FEX on the Frame and start through it (agent v61, `kind: linux_x86`; FEX also needs `STEAM_COMPAT_DATA_PATH`: "No compat data path?" in launch.log = an agent v60 launcher, reinstall); triage `linux-x86-no-fex`. Prefer an arm64 build when the app offers one |
 | `APP_ACTIVITY is empty`, nothing starts | Manifest has category INFO only; Lepton needs LAUNCHER | `frame.launcher` (automatic) |
 | PC VR game on the Frame shows as a flat window / Revive: `Unable to load LibOVRRT DLL` / `LoaderInstance::CreateInstance chained CreateInstance call failed` | Frame SteamVR runtime rejects OpenXR apiVersion 1.1 (`XR_ERROR_API_VERSION_UNSUPPORTED`), which Proton 11's VR helper requests | `pcvr.xr_timefix` (Frame OpenXR layer, default on): retries xrCreateInstance as 1.0 |
 | Unreal PC VR game on the Frame runs as a flat window although OpenXR works (no `LogHMD` OVRPlugin lines; Unreal logs nothing when it skips the Oculus plugin) / launch.log: `FramePort oculushmd: could not create the OculusHMDConnected event` | UE's OculusHMD (and LibOVR's `ovr_Detect`) only start when the Windows event `OculusHMDConnected` exists and is signalled; on a PC the Oculus service creates it. Revive hooks `OpenEventW` for it, but that relies on Detours patching Wine's (ARM64EC) kernelbase | `pcvr.oculus_unreal` (default for Unreal Rift games; PC VR counterpart of overport's `patch_oculus_unreal`): launch.sh runs the injector through `fp_oculushmd.exe`, which provides the real event until the game exits |
@@ -41,14 +45,18 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Uploads to the Frame are slow (~15 MB/s) | PC and Frame both on Wi-Fi through the home router | Connect the PC to the Frame's own hotspot (or a USB cable): FramePort uses the direct link automatically (~80-100 MB/s); job log line "Transfer link" |
 | PC VR game exits right away: `Unhandled Exception: 0xc06d007e` (after `FOnlineSubsystemOculus::InitWithWindowsPlatform`) | Delay-loaded `LibOVRPlatform64_1.dll` (Oculus Platform SDK, installed with the Oculus app) is missing | None on the Frame (entitlement check; FramePort doesn't replace it). PC mode with the Oculus app |
 | Unreal PC VR game opens the crash reporter instead of closing | UE starts CrashReportClient.exe on a crash | `pcvr.no_crash_reporter` (default for Unreal Rift games): `-nocrashreports` + CrashReportClient.exe renamed `.disabled` in the Frame copy |
+| A backup's game was added without its data (library `data_dir` null, `data_bytes` 0) although the folder has .obb files | The OBBs sit in a layout the scan didn't know: `<game>/obb/<package>/`, `Android/obb/<package>/`, or SideQuest-style `<game>/apk/x.apk` + `<game>/obb/<package>/` | `sources/quest_dump.find_data_dir` finds a `<package>` folder with .obb files ≤3 levels below the APK's folder or ≤2 below its parent (skipping neighbouring folders with APKs: other games); an `apk`/`apks` folder counts as part of its game folder. Add the folder again (Analyze again doesn't look for data) |
+| Unreal game: `JNI_OnLoad` (OVRPlugin), then silence: no OpenXR instance, no crash, no frames (GitHub #85 TRIANGLE STRATEGY; launch-test finding `missing-obb`) | Installed without its OBB: the manifest says `com.epicgames.ue4.GameActivity.bHasOBBFiles` = true (UE5: `com.epicgames.unreal.…`) but the library has no data folder (`data_dir` null, `data_bytes` 0) | Put the .obb files in a `<package>` (or `obb/`) folder next to the APK, add the folder again, reinstall. Analysis `extra.expects_obb`; the game page, the install question and `frameport scan`/`install` warn; launch tests that sent no frames get the `missing-obb` finding from the library (the game logs nothing). Unity split-binary builds have no reliable sign in the APK |
 | `INSTALL_FAILED_NO_MATCHING_ABIS` | 32-bit-only APK; Frame has no AArch32 | None. PC/Rift version via Revive |
+| Crash at start: `NoClassDefFoundError: … Landroid/window/OnBackInvokedCallback;` or `NoSuchMethodError: No static method storeStoreFence()V in class Ljava/lang/invoke/VarHandle;` (GitHub #71/#72, triage `android-too-new`) | The APK needs Android 13+ (minSdk 33 or more; those were 34) and calls its classes at start; Lepton's Android is 11 (API 30). OVRPort lowers minSdk to 29, so it installs anyway. minSdk ≤ 32 (Quest's Android 12L) is fine: 16 working catalog games declare 32 | None (analysis `extra.min_sdk` > 32 → a warning on the game page/CLI and in the recipe notes; never unsupported from the manifest alone, the launch test's triage decides). Waits for Valve to update Lepton's Android |
+| Nothing opens; `TWALauncherActivity: Using URL from Manifest (https://…)`, `Creating TwaLauncher for com.oculus.browser`, `NameNotFoundException: com.oculus.browser` (GitHub #86 Mahjong Table VR, triage `web-wrapper`) | The APK is a Trusted Web Activity (Bubblewrap / Meta's PWA packaging): a website that opens in Meta's browser, which Lepton doesn't have | None: open the URL in a browser. Analysis `extra.web_wrapper` (manifest meta-data `android.support.customtabs.trusted.DEFAULT_URL`, resolved through resources.arsc, or androidbrowserhelper's LauncherActivity) → a warning with the URL (not unsupported: the manifest alone never decides) |
 | `UnsatisfiedLinkError` / `cannot locate symbol "ovr_…"` | overport's platform loader lacks Meta platform functions | `frame.ovrstubs` (automatic, generated stubs) |
 | missing `ovrMessageType_ToString` | same, but the game needs a real string | `frame.ovrplatformcompat` (automatic) |
 | The game stays in its built-in language or waits at start although its OBB / files hold language packs (`<tag>.lang`, e.g. `de.lang`) | overport's platform loader answers `ovr_LanguagePack_GetCurrent/SetCurrent` with request id 0, so the game never gets the pack's path | `frame.langpacks` (opt-in, experimental, shown for games whose data has `*.lang`; `native/langpack`, build it with `python native/build.py --only langpack`). Default pack: the one the game applies, else env `FRAMEPORT_LANGPACK=<tag>`, else the only pack; search path override `FRAMEPORT_LANGPACK_DIRS`. Unreal games (Deadpool VR) grey out a pack whose asset `Metadata` differs from the game's version string: the patch writes the APK's versionName as Metadata (env `FRAMEPORT_LANGPACK_META` overrides) and reports the pack under the `/storage/emulated/0/Android/obb/<pkg>/` spelling of its path; with `/sdcard/…` the text switched but the dialogue stayed silent (verified in the headset with Deadpool VR) |
 | `ClassNotFoundException com.oculus.os.AnalyticsEvent` → abort | Quest telemetry lookup in Meta XR Audio (Unreal build) or native code | `frame.metaxr_telemetry` + `frame.oculusos` (automatic) |
 | `JNI DETECTED ERROR`, `GetStringUTFChars … NULL` | CheckJNI is on because overport marks the app debuggable | `frame.nodebug` |
 | Unreal game quits a few seconds after start (`System.exit`) | ForceQuit after a failed Quest platform check | alternate build with `patch_remove_unreal_force_quit` (`use_alt`) |
-| Unreal game crashes a few seconds after the logo with no backtrace (Unreal's own signal handler hides it: logcat-crash.log empty, Zygote `exited due to signal 11`); the crashing thread is `GameThread`, pc in `libaaudio.so`, lr `libovrplatformloader.so (ovr_Microphone_GetOutputBufferMaxSize+0x10)`; the last platform call is `ovr_Microphone_Create` (e.g. The Walking Dead: Saints & Sinners Ch. 2) | OVRPort's platform loader opens the microphone's AAudio stream only in `ovr_Microphone_Start`, but `GetOutputBufferMaxSize` reads that stream unchecked; Unreal's Oculus voice asks for the size right after `Create` | `frame.ovr_microphone` (NULL check rewritten in place; size 0 until the microphone starts) |
+| Unreal game crashes a few seconds after the logo with no backtrace (Unreal's own signal handler hides it: logcat-crash.log empty, Zygote `exited due to signal 11`); the crashing thread is `GameThread`, pc in `libaaudio.so`, lr `libovrplatformloader.so (ovr_Microphone_GetOutputBufferMaxSize+0x10)`; the last platform call is `ovr_Microphone_Create` (e.g. The Walking Dead: Saints & Sinners Ch. 2) | OVRPort's platform loader opens the microphone's AAudio stream only in `ovr_Microphone_Start`, but `GetOutputBufferMaxSize` reads that stream unchecked; Unreal's Oculus voice asks for the size right after `Create` | `frame.ovr_microphone` (NULL check rewritten in place; size 0 until the microphone starts). OVRPort runtime 3.4.3-aa54c3f has the check itself: builds made with it leave the patch out (log "not needed: frame.ovr_microphone", `patches/upstream.py`) |
 | `xrCreateSwapchain` -26 / format unsupported (GLES) | Frame takes only sRGB formats, no MSAA | adapter `swapchain_fix` (default on) |
 | Frames rejected, "Waiting…" forever | a layer uses a failed swapchain or an extension that isn't enabled (e.g. equirect2) | adapter `layer_fix` (default on) |
 | `xrConvert…TimeKHR` FUNCTION_UNSUPPORTED spam; VrApi bridge stalls before recenter | runtime lacks timespec conversion | current adapter emulates it |
@@ -76,6 +84,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | View jumps sideways / game pauses or freezes for a moment every few seconds (e.g. Blade & Sorcery, BattleGlide) | the Frame drops focus for ~0.5 s (FOCUSED→VISIBLE→SYNCHRONIZED); games pause or re-align the player (`OnVRPresence … Teleport`) | adapter `focus_hold` |
 | SDL / LÖVE app crashes at start: `NullPointerException … ClipboardManager.addPrimaryClipChangedListener` in `SDLClipboardHandler.<init>` (e.g. Dramatic Shape) | Lepton's Android has no clipboard service (`service check clipboard`: not found) | `frame.sdl_clipboard` (that call → nops in classes.dex, in place, `apk/dex.py`); reproduced and verified with LÖVE for Android 11.5 |
 | Controllers do nothing (e.g. stuck on a setup screen); log: `xrSuggestInteractionProfileBindings … XR_ERROR_PATH_UNSUPPORTED` | the game only suggests bindings for Meta's newer profiles (Touch Plus / Touch Pro); the Frame's Android runtime knows `oculus/touch_controller`, not those | adapter `profile_remap` (default on): the bindings are suggested again for Touch (log: `controller profile … -> oculus/touch_controller`) |
+| Some buttons do nothing or the wrong thing (e.g. a Quest game's X/Y on the Frame's left controller) | the game binds only Quest Touch and SteamVR maps Touch onto the Frame controllers with its own remap (Touch left X/Y land on the d-pad, right X and Y repeat B), or the runtime rejected a profile or an input call | turn on adapter `input_diag` (diagnostics, off by default; `frameport settings <pkg> input_diag=1`) and look for `input_diag:` lines: `bindings: <profile> accepted` or `unsupported: interaction profile <profile> -> <result>` with the rejected paths, `bindings: /user/hand/<hand> uses <profile>`, `unsupported: function <name>`, `unsupported: xrCreateAction -> <result> (<action>)` |
 | Unity game hangs or the whole Frame restarts (e.g. in a menu); log: `The current MSAA level is 0, but the recommended MSAA level is 4. Switching to the recommended level.` (e.g. Lucky's Tale) | Meta's OVRManager (`useRecommendedMSAALevel`) turns 4x MSAA on at runtime, past QualitySettings; multisampled render-to-texture on GLES/Zink hangs the GPU | `frame.unity_runtime_msaa_off` (Cpp2IL: `OVRDisplay.get_recommendedMSAALevel` → 0) |
 | Unity game: one eye shows only effects or grey, the other is fine (e.g. I Am Cat, Oculus XR Plugin on GLES) | the game's single-pass multiview rendering goes wrong for array slice 1 (the adapter submits both slices correctly) | `frame.unity_multipass` (Cpp2IL: `OculusSettings.GetStereoRenderingMode` → MultiPass); `swap_eyes=1` tells whether the game or the adapter is at fault |
 | Setup/intro loops every launch (Espire 2) | save folders created without write permission | launcher repairs permissions every 2 s (built in) |
@@ -85,6 +94,8 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Symptom | Cause | Fix |
 |---|---|---|
 | 2D Android app: Steam says it's running but nothing shows | Lepton runs apps headless unless the app folder has `lepton-show-flatscreen` | FramePort adds it for apps without VR (agent v28+); reinstall apps installed before |
+| A phone/tablet app shows nothing in the headset, or a VR app opens as a flat window | FramePort's VR/2D guess (`vr_kind`) is wrong for this app | patch `device.display_mode` → **Flat window** or **VR** (Customize → "Show as VR or as a flat window"), then Update on Frame |
+| "Install with FrameDrop" button opens FrameDrop (or nothing) instead of FramePort | another program owns `framedrop://`, or the switch is off, or macOS (Flet can't receive links there) | Settings → Install links → **Use FramePort for these links**; else Add games → Install from a link… (paste the button's address) |
 | 2D Android app: back/home/recents buttons cover the app's own buttons | Android's navigation bar | patch `device.hide_navbar` (on by default for apps without VR) sets `qemu.hw.mainkeys=1`; reinstall to apply |
 | Black screen, audio works, GLES engine with direct VrApi | Mesa rejects Quest-style GLSL | `frame.gl_shim` (logs `GLShim: SHADER COMPILE FAILED` + source lines) |
 | Black screen, audio works, log `Unsupported VrApi layer type N` | bridge drops frames containing that layer | extend the bridge (cylinder=3 is converted to a quad already) |
@@ -107,10 +118,21 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Unreal 5 game crashes in `vulkan.freedreno.so` called straight from `libUnreal.so` right after its swapchains, or a few seconds into the first frames (Metro Awakening) | Unreal turns on fragment-density-map foveation because Turnip offers VK_EXT_fragment_density_map, then records barriers (to `FRAGMENT_DENSITY_MAP_OPTIMAL`) and image views (2D array R8G8) for a density map the Frame never provides (VK_NULL_HANDLE); Turnip dereferences it | adapter `vk_hide_fdm=1` (the game doesn't see the extension) + `vk_spec_fixes=1` (leaves out null-image barriers, refuses null-image views); triage `unreal-fdm-missing`. Found by disassembling the driver at the crash pc: the struct offsets (0x58 = VkSubpassDescription2, 0x48/0x60 = image barriers, viewType/format in registers) name the call |
 | Own-engine game crashes in `je_free` from its own library on the first frames (Roblox) | the game frees memory it doesn't own; not the Vulkan shim or the format fallback | unsupported |
 
+## Live view (Live view tab, `install/livestream.py`)
+| Symptom | Cause | Fix |
+|---|---|---|
+| Status line says "software encoder" (30 fps, the Frame's CPU busier) | `fp_venc --probe` failed (missing upload, encoder busy or refused a format: exit 4) or the helper couldn't be put on the Frame | on the Frame: `~/.local/share/frameport/bin/fp_venc --probe; echo $?` and `--selftest`; the app log names upload failures. `FP_VENC_DISABLE=1` forces the fallback for tests |
+| Picture drifts out of sync with the sound | the hardware path relies on one H.264 frame per fps slot (ffmpeg `-framerate`); `fp_venc: stats … skipped=` > 0 on stderr means slots were skipped | see the stats line (every 10 s); a stopped/suspended Frame skips slots on purpose |
+| Viewer joins only after several seconds | the keyframe request (`k` on the channel) didn't reach the encoder; the viewer then waits for the next regular keyframe (4 s) | check `live: encoder=hardware` came first (requests are sent only then) |
+
 ## Debugging techniques that worked
 - A user's problem report: `frameport diag inspect <FramePort-diag-*.zip>` re-triages its launch log with the current
   signatures; the zip has the recipe, analysis, ELF/PE imports, Frame logs and versions (docs/DIAGNOSTICS.md).
 - Read `<base>/launch.log` (logcat mirror). Filter the game's pid: `Start proc <pid>:<package>`.
+- **Monitor tab** (GUI, while a game runs): fps from FrameBridge's pacing lines next to GPU busy %, the hottest
+  sensor, memory pressure and per-process CPU/GPU/memory. A memory runaway (Lucky's Tale, Vader Immortal) shows as
+  rising memory + "waiting" before the OOM kill; a GPU-bound game as GPU near 100 % with fps under target; heat as the
+  temperature tile turning amber/red. Sources and costs: FRAME_RUNTIME.md "Monitoring sources".
 - The adapter logs as `FrameBridge` (settings, xrCreateInstance result, swapchain retries, pacing fps).
 - For GLES/GLAD engines, wrap `eglGetProcAddress` to see shader compile errors (build the shim with `-DGLSHIM_TRACE`
   for per-FBO draw counts and draw-call errors; the bridge has `-DOVP_GL_DIAG` for eye-image readback).

native/README.md

@@ -11,7 +11,7 @@ embeds debug paths (`-g`) and the dex depends on the d8 version, so those differ
 
 | Dir | Artifact | What / why |
 |---|---|---|
-| `adapter/` | `{arm64-v8a,armeabi-v7a}/libopenxr_loader_generic.so` | **FrameBridge**: replaces overport's generic loader (which is renamed `libopenxr_loader_original.so`) and fixes Steam Frame runtime gaps. Hooks xrCreateInstance, swapchains, xrEndFrame, spaces, xrPollEvent, … everything else is forwarded by `gen_forwarders.py`-generated tail calls. `scene_emu.c` = Meta scene/spatial-entity emulation; `flip_vk.c` = Vulkan blit for VERTICAL_FLIP quads. `session_fixes.c` = per-game session fixes, all off by default and hooked only when on (`layer_debug` diagnostics, `stable_local`, `focus_hold`, aim correction `aim_pitch/aim_yaw/aim_forward`, `refresh_rate`); `layer_emul_gl.c` = `equirect_emul` (GLES sessions only): 360° equirect/equirect2 layers become one adapter projection layer, drawn by a worker thread with its own EGL context shared with the app's: each 360° image is converted to a cube map only when it changes, and the view is redrawn only after a 4° head turn (GL/EGL resolved with dlopen, so Vulkan games never load them); `layer_math.h` = their pose/face math, tested on the host by `tests/test_layer_emul.py`. `render_model.c` = XR_FB_render_model emulation (setting `controller_models`, off by default): serves `files/framebridge/controller_{left,right}.glb`, which the agent converts on the Frame from SteamVR's own Frame controller render models (never shipped by FramePort); tested on the host by `tests/test_render_model.py`. Settings: `libframe_settings.so` in the APK + `settings.conf`/`framebridge.conf` on the Frame. |
+| `adapter/` | `{arm64-v8a,armeabi-v7a}/libopenxr_loader_generic.so` | **FrameBridge**: replaces overport's generic loader (which is renamed `libopenxr_loader_original.so`) and fixes Steam Frame runtime gaps. Hooks xrCreateInstance, swapchains, xrEndFrame, spaces, xrPollEvent, … everything else is forwarded by `gen_forwarders.py`-generated tail calls. `scene_emu.c` = Meta scene/spatial-entity emulation; `flip_vk.c` = Vulkan blit for VERTICAL_FLIP quads. `session_fixes.c` = per-game session fixes, all off by default and hooked only when on (`layer_debug` diagnostics, `stable_local`, `focus_hold`, aim correction `aim_pitch/aim_yaw/aim_forward`, `refresh_rate`); `input_diag.c` = controller-input diagnostics (setting `input_diag`, off by default and hooked only when on; logs suggested interaction profiles and the runtime's answers, each hand's current profile, functions the runtime lacks and failing input/haptics/perf calls, each line once; tested on the host by `tests/test_input_diag.py`); `layer_emul_gl.c` = `equirect_emul` (GLES sessions only): 360° equirect/equirect2 layers become one adapter projection layer, drawn by a worker thread with its own EGL context shared with the app's: each 360° image is converted to a cube map only when it changes, and the view is redrawn only after a 4° head turn (GL/EGL resolved with dlopen, so Vulkan games never load them); `layer_math.h` = their pose/face math, tested on the host by `tests/test_layer_emul.py`. `render_model.c` = XR_FB_render_model emulation (setting `controller_models`, off by default): serves `files/framebridge/controller_{left,right}.glb`, which the agent converts on the Frame from SteamVR's own Frame controller render models (never shipped by FramePort); tested on the host by `tests/test_render_model.py`. Settings: `libframe_settings.so` in the APK + `settings.conf`/`framebridge.conf` on the Frame. |
 | `vrapi-bridge/` | `arm64-v8a/libvrapi.so` | VrApi → OpenXR bridge from [Android-XR-Bridge/OVRPort](https://github.com/Android-XR-Bridge/OVRPort) `native/vrapi` at 5e7df52 (GPL-3.0, `LICENSE.upstream`; unchanged upstream as of OVRPort v1.2.5, which ships the unpatched code as its opt-in `patch_vrapi_openxr` in experimental CLI builds), with our changes in `upstream-patches/`: GLES sessions + GL texture swapchains, cylinder→quad layers, GL vertical flip, UNORM↔sRGB format twins, 30 s VR-mode deadline, VALID-only recenter, loading-icon layers skipped, `vrapi_PollEvent`/`RecenterPose`/`SetDisplayRefreshRate`/`GetSystemPropertyFloatArray` (BlazeRush imports them, GitHub #57), diagnostics behind `-DOVP_GL_DIAG`. `upstream-patches/` reproduces these sources from the fork's `native/vrapi` (checked 2026-10-06 against its latest commit); upstream PRs Android-XR-Bridge/OVRPort#3-#8, tracked in GitHub #75. |
 | `platformcompat/` | `arm64-v8a/libovrplatformcompat.so` | Real `ovrMessageType_ToString` (same fork, `native/platform`). |
 | `langpack/` | `arm64-v8a/libfp_langpack.so` | Language packs for the Meta Platform SDK (patch `frame.langpacks`, opt-in). overport's platform loader is a dispatcher in front of Meta's own loader and answers `ovr_LanguagePack_GetCurrent/SetCurrent` with `return 0` (no reply ever). This library becomes the loader's first DT_NEEDED; the loader's own exports of the 31 functions it defines are made STB_LOCAL in `.dynsym` (`elf.hide_exports`, nothing moves), so symbol lookups reach the library first. It serves `<tag>.lang` files found in the game's OBB / app files (`$FRAMEPORT_LANGPACK_DIRS` overrides the search path) through `ovr_LanguagePack_*`, `ovr_AssetFile_GetList` (the loader's list + the packs) and `ovr_AssetFile_StatusById`; its own message queue is merged into `ovr_PopMessage`, and every handle that is not ours (an address-range check) goes to the loader's original function, whose address is read at run time from the loader's in-memory `.dynsym`. With patch `frame.asset_files` (marker byte `@FPASSETS@`, or env `FRAMEPORT_ASSET_FILES=1`) it also lists the data's `*.pak` content files as installed `default` asset files and answers `ovr_AssetFile_DownloadById` for them at once (a completed `DownloadUpdate`, then the result with the path). Host-tested against a stand-in loader (`tests/test_langpack.py`, plain `cc`, no NDK); the bionic/headset side is unverified. |
@@ -19,6 +19,7 @@ embeds debug paths (`-g`) and the dex depends on the d8 version, so those differ
 | `xrlayer/` | `linux-arm64/libxr_frameport_timefix.so` + `XR_APILAYER_FRAMEPORT_timefix.json` | OpenXR API layer for Windows PC VR games under Proton on the Frame (glibc aarch64, built freestanding with the NDK's clang), on by default (patch `pcvr.xr_timefix`). Retries `xrCreateInstance` as an OpenXR 1.0 app when the runtime rejects 1.1 (the Frame's SteamVR runtime does, and Proton 11's VR helper asks for 1.1). Also emulates `xrConvertTimespecTimeToTimeKHR`/`xrConvertTimeToTimespecTimeKHR` if the runtime refuses them (the Frame's Android runtime does; its Linux runtime, used by Proton, supports them as of 2026-09-29 — so this part is only a fallback; Proton's wineopenxr needs them for `XR_KHR_win32_convert_performance_counter_time`, which Revive requires) with the adapter's xrWaitFrame-calibrated offset, and drops the extension from xrCreateInstance if the runtime rejects it. Enabled per game by the Proton launch.sh (`XR_API_LAYER_PATH`, `XR_ENABLE_API_LAYERS`). `tests/test_xrlayer.py` builds it for x86_64 and drives it via ctypes. |
 | `oculushmd/` | `win-x64/fp_oculushmd.exe` | PC VR counterpart of overport's `patch_oculus_unreal` (patch `pcvr.oculus_unreal`, default for Unreal Rift games on the Frame). Unreal's OculusHMD and LibOVR's `ovr_Detect` only start when the Windows named event `OculusHMDConnected` exists and is signalled (the Oculus service creates it). `fp_oculushmd.exe <command line>` creates it (manual reset, signalled), runs the command (Revive's injector) in a job object and keeps the event until every process in the job — the game and its children — has exited (fallback without job support: 3 minutes); returns the command's exit code and logs `FramePort oculushmd: …` to stderr (launch.log). Freestanding Windows x64 console exe (no CRT, no Windows SDK): the NDK's clang + `lld-link /Brepro` with a kernel32 import library generated by `llvm-dlltool`, so it's byte-reproducible. Tested on Windows from WSL with a build whose event name is `-DEVENT_NAME=L"…"` (the Oculus service owns the real event on a PC with the Oculus app). |
 | `xrshim/` | `arm64-v8a/libframe_xrshim.so` | FrameBridge extension shim, only in builds with `controller_models=1`. overport's dispatcher (`libopenxr_loader.so`) answers `xrGetInstanceProcAddr` from a fixed table and refuses everything else (`overportOXR: Unknown proc addr: xrLoadRenderModelFB`), so the adapter never sees XR_FB_render_model lookups. Meta's OVRPlugin gets the function with `dlopen("libopenxr_loader.so")` + `dlsym`, so FramePort rewrites that `.rodata` string in `libOVRPlugin.so` (same length, in place) to `libframe_xrshim.so`. The shim returns the adapter's emulated functions (`framebridge_extension_proc`) and forwards every other name to overport. A DT_NEEDED interposer does not work here (dlsym on a handle searches that library first); tried and dropped. |
+| `venc/` | `linux-arm64-bin/fp_venc` | Hardware H.264 encoder for the live view, run on the Frame (spec: `venc/SPEC.md`). Reads SteamVR's "headset view" webcam (v4l2loopback `/dev/video99`, RGB24), box-scales and converts it to NV12 (BT.709 limited range; `convert.c`, NEON with a bit-identical scalar reference, also built for x86_64 by the host test), and feeds the SoC's V4L2 stateful encoder (`dev-encoder.rst`, Qualcomm iris `/dev/video-enc0`): CBR, no B-frames, SPS/PPS on every IDR, one frame per slot of a fixed grid (fps = a divisor of the panel refresh read through DRM KMS, default cap 45), Annex B on stdout. stdin `k` = keyframe, `q`/EOF = drain and stop; `--probe` prints the setup as JSON, `--selftest` compares NEON and scalar output. Fully static and freestanding (raw syscalls, own `_start`; only the NDK's kernel UAPI headers, staged in `.cache/uapi-arm64`), byte-reproducible. Lives in `linux-arm64-bin/` because `linux-arm64/` is uploaded whole as the OpenXR layer. |
 | `java-stubs/` | `dex/oculusos-stubs.dex` | No-op `com.oculus.os.AnalyticsEvent` / `UnifiedTelemetryLogger` for native code that looks them up. |
 
 The ovr_* stub library is *not* prebuilt: `src/frameport/analysis/stubgen.py` generates it per game from the exact

native/adapter/frame_adapter.c

@@ -26,6 +26,9 @@
 //    render_model.c);
 //  * per-game session fixes (session_fixes.c, all off by default): layer_debug diagnostics, stable_local,
 //    focus_hold, aim pose correction (aim_pitch/aim_yaw/aim_forward), refresh_rate;
+//  * optionally logs controller-input diagnostics: suggested interaction profiles and the runtime's answers, each
+//    hand's current profile, functions the runtime lacks, failing input/haptics/perf calls (input_diag,
+//    input_diag.c, off by default);
 //  * optionally shows 360° (equirect/equirect2) layers as cube-face quads drawn by a worker thread with a shared
 //    GLES context (equirect_emul, layer_emul_gl.c; GLES sessions only, off by default).
 //
@@ -125,6 +128,7 @@ static int controller_models;  // serve Frame controller models via XR_FB_render
 static int sync_guard;       // xrSyncActions one at a time with xrPollEvent, paused briefly after focus returns
 static int profile_remap = 1; // Meta's newer controller profiles (rejected by the Frame) -> oculus/touch_controller
 static int layer_debug;      // diagnostics: layers, swapchains, session states, spaces, aim/grip, refresh rates
+static int input_diag;       // diagnostics: controller profiles, bindings, missing functions, failing input calls
 static int stable_local;     // keep every LOCAL space the app creates on the session-start origin
 static int focus_hold = 1;   // hide brief focus dips once the session has been focused for a while
 static float focus_hold_ms = 5000;  // longest focus dip focus_hold hides
@@ -171,6 +175,7 @@ static void read_settings(const char *path) {
         if (sscanf(line, "scene_depth=%f", &value) == 1 && value > 0.5f && value < 20.0f) scene_depth = value;
         if (sscanf(line, "controller_models=%f", &value) == 1) controller_models = value != 0;
         if (sscanf(line, "layer_debug=%f", &value) == 1) layer_debug = value != 0;
+        if (sscanf(line, "input_diag=%f", &value) == 1) input_diag = value != 0;
         if (sscanf(line, "surface_emul=%f", &value) == 1) surface_emul = value != 0;
         if (sscanf(line, "eye_debug=%f", &value) == 1) eye_debug = value != 0;
         if (sscanf(line, "release_wait=%f", &value) == 1) release_wait = (int)value;
@@ -234,6 +239,7 @@ static void initialize(void) {
         snprintf(path, sizeof(path), "/sdcard/Android/data/%s/files/framebridge.log", process);
         log_file = fopen(path, "a");
     }
+    if (input_diag) LOG("per-game: input_diag=1 (controller-input diagnostics)");
     if (hide_space_warp) LOG("per-game: hide_space_warp=1 (XR_FB_space_warp hidden, space warp info removed)");
     if (strip_color_bias) LOG("per-game: strip_color_bias=%d (layer color scale/bias removed)", strip_color_bias);
     if (frame_balance) LOG("per-game: frame_balance=1 (an open frame is ended before the next one begins)");
@@ -820,6 +826,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrDestroySpace(XrSpace space) {
     return fn ? fn(space) : XR_ERROR_FUNCTION_UNSUPPORTED;
 }
 
+#include "input_diag.c"
 #include "session_fixes.c"
 #include "layer_emul_gl.c"
 #include "snapshot_gl.c"
@@ -873,8 +880,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSession(XrInstance instance, const XrSess
 // Vibrations: logged (the first few, to see what games ask for) and scaled by haptic_scale. Plain vibrations, Meta's
 // amplitude envelopes and PCM buffers all pass here: games' own calls, OVRPort's VrApi bridge and the xrshim alike.
 static int haptics_logged;
-XRAPI_ATTR XrResult XRAPI_CALL xrApplyHapticFeedback(XrSession session, const XrHapticActionInfo *info,
-                                                    const XrHapticBaseHeader *feedback) {
+static XrResult apply_haptics(XrSession session, const XrHapticActionInfo *info, const XrHapticBaseHeader *feedback) {
     PFN_xrApplyHapticFeedback fn = (PFN_xrApplyHapticFeedback)lookup(active_instance, "xrApplyHapticFeedback");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
     if (!feedback) return fn(session, info, feedback);
@@ -919,6 +925,15 @@ XRAPI_ATTR XrResult XRAPI_CALL xrApplyHapticFeedback(XrSession session, const Xr
     return fn(session, info, feedback);
 }
 
+XRAPI_ATTR XrResult XRAPI_CALL xrApplyHapticFeedback(XrSession session, const XrHapticActionInfo *info,
+                                                    const XrHapticBaseHeader *feedback) {
+    XrResult result = apply_haptics(session, info, feedback);
+    if (input_diag && XR_FAILED(result))  // always hooked (haptic_scale), so input_diag reports failures here
+        diag_call_failed("xrApplyHapticFeedback", result,
+                         feedback && feedback->type != XR_TYPE_HAPTIC_VIBRATION ? "(not XrHapticVibration)" : NULL);
+    return result;
+}
+
 XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateSwapchainImages(XrSwapchain swapchain, uint32_t capacity, uint32_t *count,
         XrSwapchainImageBaseHeader *images) {
     PFN_xrEnumerateSwapchainImages fn = (PFN_xrEnumerateSwapchainImages)lookup(active_instance, "xrEnumerateSwapchainImages");
@@ -1573,6 +1588,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetCurrentInteractionProfile(XrSession session,
         (PFN_xrGetCurrentInteractionProfile)lookup(active_instance, "xrGetCurrentInteractionProfile");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
     XrResult result = fn(session, user, state);
+    if (input_diag && XR_SUCCEEDED(result) && state) input_diag_current_profile(user, state->interactionProfile);
     if (layer_debug && active_instance) {  // which device each hand has, as the runtime reports it
         PFN_xrPathToString str = (PFN_xrPathToString)lookup(active_instance, "xrPathToString");
         char who[XR_MAX_PATH_LENGTH] = "?", what[XR_MAX_PATH_LENGTH] = "(none)";
@@ -1726,15 +1742,22 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
         HOOK(xrWaitSwapchainImage)
         HOOK(xrReleaseSwapchainImage)
     }
-    if (sync_guard || layer_debug) HOOK_AS(xrSyncActions, hook_xrSyncActions)
+    if (sync_guard || layer_debug || input_diag) HOOK_AS(xrSyncActions, hook_xrSyncActions)
     if (layer_debug) HOOK_AS(xrGetActionStateBoolean, hook_xrGetActionStateBoolean)
-    if (layer_debug || aim_correction_on() || profile_remap)
+    if (layer_debug || aim_correction_on() || profile_remap || input_diag)
         HOOK_AS(xrSuggestInteractionProfileBindings, hook_xrSuggestInteractionProfileBindings)
     if (layer_debug || aim_correction_on()) {
         HOOK_AS(xrCreateActionSpace, hook_xrCreateActionSpace)
     }
 #undef HOOK_AS
 #undef HOOK
+    if (input_diag) {  // logs only: wraps a few input/haptics/perf calls, notes lookups the runtime can't answer
+        PFN_xrVoidFunction diag = input_diag_hook(name);
+        XrResult result = next_gipa(instance, name, function);
+        input_diag_lookup(instance, name, result, *function);
+        if (diag && XR_SUCCEEDED(result) && *function) *function = diag;
+        return result;
+    }
     return next_gipa(instance, name, function);
 }
 

native/adapter/input_diag.c

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Included by frame_adapter.c (before session_fixes.c). input_diag: controller-input diagnostics, off by default and
+// hooked only when on; logs only, never changes what the game or the runtime sees. Each distinct line is logged once:
+//  * every interaction profile the game suggests bindings for, with the runtime's answer; a rejected profile lists
+//    all its binding paths ("unsupported: interaction profile ...");
+//  * the profile the runtime reports for each hand (xrGetCurrentInteractionProfile, before controller_fix rewrites
+//    the answer for the game): a game without a Steam Frame binding gets SteamVR's Touch remap, so this shows
+//    whether the game's input runs through it;
+//  * functions the game looks up that the runtime doesn't provide ("unsupported: function ...");
+//  * failing input, haptics and performance calls with the result name and the argument that failed.
+
+#define DIAG_MAX 512
+#define DIAG_KEY (2 * XR_MAX_PATH_LENGTH + 32)
+static uint64_t diag_seen[DIAG_MAX];  // FNV-1a hashes of the keys already logged
+static int diag_count;
+static pthread_mutex_t diag_lock = PTHREAD_MUTEX_INITIALIZER;
+
+static int diag_first(const char *key) {  // 1 the first time `key` is seen; 0 for everything after DIAG_MAX keys
+    uint64_t hash = 14695981039346656037ull;
+    for (const unsigned char *c = (const unsigned char *)key; *c; ++c) hash = (hash ^ *c) * 1099511628211ull;
+    pthread_mutex_lock(&diag_lock);
+    int first = 1;
+    for (int i = 0; i < diag_count && first; ++i) first = diag_seen[i] != hash;
+    if (first && diag_count < DIAG_MAX) diag_seen[diag_count++] = hash;
+    else if (first) {  // full: stop rather than repeat a per-frame failure
+        static int full;
+        if (!full) { full = 1; LOG("input_diag: %d distinct findings, logging no more", DIAG_MAX); }
+        first = 0;
+    }
+    pthread_mutex_unlock(&diag_lock);
+    return first;
+}
+
+static const char *diag_result_name(XrResult result, char *buf, size_t size) {
+    PFN_xrResultToString fn =
+        active_instance ? (PFN_xrResultToString)lookup(active_instance, "xrResultToString") : NULL;
+    char name[XR_MAX_RESULT_STRING_SIZE];
+    if (fn && XR_SUCCEEDED(fn(active_instance, result, name))) snprintf(buf, size, "%s", name);
+    else snprintf(buf, size, "%d", result);
+    return buf;
+}
+
+static void diag_call_failed(const char *fn, XrResult result, const char *detail) {
+    char key[DIAG_KEY], name[XR_MAX_RESULT_STRING_SIZE];
+    snprintf(key, sizeof(key), "%s:%d:%s", fn, result, detail ? detail : "");
+    if (diag_first(key))
+        LOG("input_diag: unsupported: %s -> %s%s%s", fn, diag_result_name(result, name, sizeof(name)),
+            detail ? " " : "", detail ? detail : "");
+}
+
+// Called by hook_xrSuggestInteractionProfileBindings with the runtime's answer to the game's own suggestion (before
+// profile_remap suggests it again for Touch).
+static void input_diag_suggested(XrInstance instance, const XrInteractionProfileSuggestedBinding *suggested,
+                                 XrResult result, PFN_xrPathToString to_string) {
+    if (!input_diag || !suggested || !to_string) return;
+    char profile[XR_MAX_PATH_LENGTH] = "?", key[DIAG_KEY], name[XR_MAX_RESULT_STRING_SIZE];
+    uint32_t size = 0;
+    to_string(instance, suggested->interactionProfile, sizeof(profile), &size, profile);
+    snprintf(key, sizeof(key), "suggest:%s:%d", profile, result);
+    if (!diag_first(key)) return;
+    if (XR_SUCCEEDED(result)) {
+        LOG("input_diag: bindings: %s accepted (%u paths)", profile, suggested->countSuggestedBindings);
+        return;
+    }
+    LOG("input_diag: unsupported: interaction profile %s -> %s (%u bindings):", profile,
+        diag_result_name(result, name, sizeof(name)), suggested->countSuggestedBindings);
+    for (uint32_t i = 0; i < suggested->countSuggestedBindings; ++i) {
+        char path[XR_MAX_PATH_LENGTH];
+        if (XR_SUCCEEDED(to_string(instance, suggested->suggestedBindings[i].binding, sizeof(path), &size, path)))
+            LOG("input_diag:   %s", path);
+    }
+}
+
+// Called by xrGetCurrentInteractionProfile with the runtime's answer.
+static void input_diag_current_profile(XrPath user, XrPath profile) {
+    PFN_xrPathToString to_string =
+        active_instance ? (PFN_xrPathToString)lookup(active_instance, "xrPathToString") : NULL;
+    if (!input_diag || !to_string) return;
+    char u[XR_MAX_PATH_LENGTH] = "?", p[XR_MAX_PATH_LENGTH] = "none", key[DIAG_KEY];
+    uint32_t size = 0;
+    to_string(active_instance, user, sizeof(u), &size, u);
+    if (profile) to_string(active_instance, profile, sizeof(p), &size, p);
+    snprintf(key, sizeof(key), "current:%s:%s", u, p);
+    if (diag_first(key)) LOG("input_diag: bindings: %s uses %s", u, p);
+}
+
+// ---------------------------------------------------------------- failing calls
+// xrSyncActions and xrSuggestInteractionProfileBindings are reported from session_fixes.c's hooks,
+// xrApplyHapticFeedback from frame_adapter.c's (always hooked for haptic_scale).
+#define DIAG_CHECKED(name, params, args, detail)                                                                    \
+    static XRAPI_ATTR XrResult XRAPI_CALL diag_##name params {                                                     \
+        PFN_##name fn = (PFN_##name)lookup(active_instance, #name);                                                \
+        if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;                                                             \
+        XrResult result = fn args;                                                                                 \
+        if (XR_FAILED(result)) diag_call_failed(#name, result, detail);                                            \
+        return result;                                                                                             \
+    }
+static const char *diag_name_detail(const char *name) {
+    static __thread char buf[XR_MAX_PATH_LENGTH + 8];
+    snprintf(buf, sizeof(buf), "(%s)", name ? name : "null");
+    return buf;
+}
+static const char *diag_perf_detail(XrPerfSettingsDomainEXT domain, XrPerfSettingsLevelEXT level) {
+    static __thread char buf[64];
+    snprintf(buf, sizeof(buf), "(domain %d level %d)", (int)domain, (int)level);
+    return buf;
+}
+DIAG_CHECKED(xrStringToPath, (XrInstance instance, const char *path, XrPath *out), (instance, path, out),
+             diag_name_detail(path))
+DIAG_CHECKED(xrCreateAction, (XrActionSet set, const XrActionCreateInfo *info, XrAction *action), (set, info, action),
+             diag_name_detail(info ? info->actionName : NULL))
+DIAG_CHECKED(xrAttachSessionActionSets, (XrSession session, const XrSessionActionSetsAttachInfo *info),
+             (session, info), NULL)
+DIAG_CHECKED(xrPerfSettingsSetPerformanceLevelEXT,
+             (XrSession session, XrPerfSettingsDomainEXT domain, XrPerfSettingsLevelEXT level),
+             (session, domain, level), diag_perf_detail(domain, level))
+#undef DIAG_CHECKED
+
+// xrGetInstanceProcAddr: our wrapper for `name`, NULL if it isn't one of ours.
+static PFN_xrVoidFunction input_diag_hook(const char *name) {
+#define DIAG(fn) if (!strcmp(name, #fn)) return (PFN_xrVoidFunction)diag_##fn;
+    DIAG(xrStringToPath)
+    DIAG(xrCreateAction)
+    DIAG(xrAttachSessionActionSets)
+    DIAG(xrPerfSettingsSetPerformanceLevelEXT)
+#undef DIAG
+    return NULL;
+}
+
+// After the runtime's own lookup: a function the game asked for that the runtime doesn't provide.
+static void input_diag_lookup(XrInstance instance, const char *name, XrResult result, PFN_xrVoidFunction fn) {
+    if (!input_diag || instance == XR_NULL_HANDLE || (XR_SUCCEEDED(result) && fn)) return;
+    char key[DIAG_KEY], rname[XR_MAX_RESULT_STRING_SIZE];
+    snprintf(key, sizeof(key), "fn:%s", name);
+    if (diag_first(key))
+        LOG("input_diag: unsupported: function %s not provided by the runtime (%s)", name,
+            diag_result_name(result, rname, sizeof(rname)));
+}

native/adapter/session_fixes.c

@@ -110,11 +110,12 @@ static int input_syncs, input_sync_ok, input_bool_reads, input_bool_true, input_
 static XRAPI_ATTR XrResult XRAPI_CALL hook_xrSyncActions(XrSession session, const XrActionsSyncInfo *info) {
     PFN_xrSyncActions fn = (PFN_xrSyncActions)lookup(active_instance, "xrSyncActions");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
-    if (!sync_guard) {  // installed for layer_debug only: count
+    if (!sync_guard) {  // installed for layer_debug / input_diag only: count, report failures
         XrResult r = fn(session, info);
         __atomic_add_fetch(&input_syncs, 1, __ATOMIC_RELAXED);
         if (r == XR_SUCCESS) __atomic_add_fetch(&input_sync_ok, 1, __ATOMIC_RELAXED);
         input_last_sync_result = r;
+        if (input_diag && XR_FAILED(r)) diag_call_failed("xrSyncActions", r, NULL);
         return r;
     }
     pthread_mutex_lock(&sync_lock);
@@ -123,6 +124,7 @@ static XRAPI_ATTR XrResult XRAPI_CALL hook_xrSyncActions(XrSession session, cons
     pthread_mutex_unlock(&sync_lock);
     static int logged;
     if (wait > 0 && logged++ < 5) LOG("sync_guard: input paused for %.0f ms after focus returned", wait / 1e6);
+    if (input_diag && XR_FAILED(r)) diag_call_failed("xrSyncActions", r, NULL);
     return r;
 }
 
@@ -324,6 +326,7 @@ static XRAPI_ATTR XrResult XRAPI_CALL hook_xrSuggestInteractionProfileBindings(X
                 note_pose_binding(suggested->suggestedBindings[i].action, path);
         }
     XrResult r = fn(instance, suggested);
+    input_diag_suggested(instance, suggested, r, to_string);  // the runtime's answer to the game's own suggestion
     if (!profile_remap || !suggested || !to_string) return r;
     char profile[XR_MAX_PATH_LENGTH] = {0};
     uint32_t size = 0;

native/build.py

@@ -7,10 +7,10 @@ Everything is fetched on demand into native/.cache (git-ignored):
   - Temurin JDK 21 (javac) and Android build-tools (d8) for the Java stub classes
 Then builds: FrameBridge adapter (arm64 + arm32), VrApi bridge, platform compat, language packs, GL shim, oculusos stub dex, the
 timefix OpenXR layer for Proton games (linux-arm64, glibc; the NDK's clang builds it freestanding), the
-OculusHMDConnected helper for Rift games under Proton (win-x64 PE; the NDK's clang + lld-link, no Windows SDK), and
-rewrites artifacts/SHA256SUMS. Run `frameport parity` afterwards to see which games change.
+OculusHMDConnected helper for Rift games under Proton (win-x64 PE; the NDK's clang + lld-link, no Windows SDK), the
+live view's hardware H.264 encoder fp_venc (linux-arm64-bin, static freestanding executable), and rewrites artifacts/SHA256SUMS. Run `frameport parity` afterwards to see which games change.
 
-    python native/build.py [--only adapter,bridge,compat,langpack,glshim,eglfmt,ovrtrace,dex,xrlayer,oculushmd,xrshim,vkshim,ovrpshim,vrsettings] [--ndk PATH]
+    python native/build.py [--only adapter,bridge,compat,langpack,glshim,eglfmt,ovrtrace,dex,xrlayer,oculushmd,xrshim,vkshim,ovrpshim,vrsettings,venc] [--ndk PATH]
 """
 from __future__ import annotations
 
@@ -158,6 +158,32 @@ def build_xrlayer(tc: Path):
     shutil.copy(src / "XR_APILAYER_FRAMEPORT_timefix.json", out / "XR_APILAYER_FRAMEPORT_timefix.json")
 
 
+def uapi_arm64(tc: Path) -> Path:
+    """Only the kernel UAPI headers of the NDK sysroot (linux/, asm-generic/, drm/, aarch64 asm/), rebuilt every time,
+    so no bionic libc header can end up on a freestanding build's include path."""
+    inc = tc / "sysroot/usr/include"
+    dest = CACHE / "uapi-arm64"
+    shutil.rmtree(dest, ignore_errors=True)
+    for d in ("linux", "asm-generic", "drm"):
+        shutil.copytree(inc / d, dest / d)
+    shutil.copytree(inc / "aarch64-linux-android/asm", dest / "asm")
+    return dest
+
+
+def build_venc(tc: Path):
+    """fp_venc (Linux aarch64, runs on the Frame): SteamVR headset view -> V4L2 hardware H.264 encoder -> stdout, for the
+    live view. Fully static and freestanding (raw syscalls, own _start), so it needs no libc at build or run time.
+    Goes to linux-arm64-bin/, not linux-arm64/ (that folder is uploaded whole as the OpenXR layer)."""
+    src = HERE / "venc"
+    uapi = uapi_arm64(tc)
+    out = ART / "linux-arm64-bin"
+    out.mkdir(parents=True, exist_ok=True)
+    run([tc / "bin/clang", "--target=aarch64-linux-gnu", "-ffreestanding", "-nostdlib", "-nostdlibinc", "-static",
+         "-fno-stack-protector", "-fno-builtin", "-O2", "-Wall", "-Wextra", "-Werror", "-fuse-ld=lld",
+         "-Wl,--build-id=none", "-Wl,-z,max-page-size=65536", "-e", "_start", "-I", src / "include", "-I", uapi,
+         f"-ffile-prefix-map={HERE}=native", "fp_venc.c", "convert.c", "sys.c", "-o", out / "fp_venc"], cwd=src)
+
+
 OCULUSHMD_IMPORTS = ("CreateEventW", "CreateJobObjectW", "AssignProcessToJobObject", "QueryInformationJobObject",
                      "CreateProcessW", "ResumeThread", "WaitForSingleObject", "GetExitCodeProcess", "CloseHandle",
                      "Sleep", "GetCommandLineW", "GetLastError", "GetStdHandle", "WriteFile", "ExitProcess")
@@ -326,7 +352,7 @@ def write_sums():
 
 def main():
     ap = argparse.ArgumentParser()
-    ap.add_argument("--only", default="adapter,bridge,compat,langpack,glshim,eglfmt,ovrtrace,dex,xrlayer,oculushmd,xrshim,vkshim,ovrpshim,vrsettings")
+    ap.add_argument("--only", default="adapter,bridge,compat,langpack,glshim,eglfmt,ovrtrace,dex,xrlayer,oculushmd,xrshim,vkshim,ovrpshim,vrsettings,venc")
     ap.add_argument("--ndk")
     args = ap.parse_args()
     parts = set(args.only.split(","))
@@ -338,8 +364,8 @@ def main():
              "glshim": lambda: build_glshim(tc), "eglfmt": lambda: build_eglfmt(tc), "ovrtrace": lambda: build_ovrtrace(tc), "xrshim": lambda: build_xrshim(tc), "dex": build_dex, "xrlayer": lambda: build_xrlayer(tc),
              "oculushmd": lambda: build_oculushmd(tc), "vkshim": lambda: build_vkshim(tc),
              "ovrpshim": lambda: build_ovrpshim(tc),
-             "vrsettings": lambda: build_vrsettings(tc)}
-    for name in ("adapter", "bridge", "compat", "langpack", "glshim", "eglfmt", "ovrtrace", "xrshim", "vkshim", "ovrpshim", "dex", "xrlayer", "oculushmd", "vrsettings"):
+             "vrsettings": lambda: build_vrsettings(tc), "venc": lambda: build_venc(tc)}
+    for name in ("adapter", "bridge", "compat", "langpack", "glshim", "eglfmt", "ovrtrace", "xrshim", "vkshim", "ovrpshim", "dex", "xrlayer", "oculushmd", "vrsettings", "venc"):
         if name in parts:
             log(f"build {name}")
             steps[name]()

native/venc/SPEC.md

@@ -0,0 +1,215 @@
+# fp_venc — specification
+
+A small program that runs **on the Steam Frame** (SteamOS, aarch64 Linux with glibc) and hardware-encodes the
+SteamVR "headset view" webcam to an H.264 elementary stream on stdout. FramePort's live view (PC side) pipes that
+stream into ffmpeg on the Frame, which adds sound and packs fragmented MP4. The program is used for **live viewing
+only**: low latency, constant bitrate, evenly spaced frames, a keyframe whenever the viewer side asks for one.
+
+Sources: the Linux kernel's V4L2 documentation (`Documentation/userspace-api/media/v4l/dev-encoder.rst` = the
+memory-to-memory stateful encoder interface, `ext-ctrls-codec.rst`, `buffer.rst`, `vidioc-*.rst`), the DRM KMS UAPI
+(`drm_mode.h`), and the facts measured on the Frame listed in "Measured facts". Nothing else.
+
+## Files
+- `native/venc/convert.h`, `convert.c` — the picture converter (pure computation, no syscalls). Must compile for
+  **aarch64** (NEON path + scalar path) **and x86_64** (scalar path only; used by the host unit test).
+- `native/venc/sys.h` (+ `.c` if wanted) — raw Linux aarch64 syscalls (`svc #0`), `_start`, `memcpy`/`memset`/`memmove`
+  (the compiler may emit calls to them), small string/number helpers (parse decimal, print decimal, write a whole buffer).
+- `native/venc/fp_venc.c` — command line, source, encoder, DRM refresh query, main loop.
+- `native/venc/include/sys/time.h` — minimal stub so the kernel UAPI `linux/videodev2.h` compiles without a libc
+  (`struct timeval { long tv_sec; long tv_usec; };` and whatever else that header needs).
+- `native/build.py` — a `build_venc(tc)` step (see "Build").
+
+Keep it small and readable: plain C11, no clever macros, comments that explain *why*. Target ≤ ~900 lines total.
+
+## Build
+No libc exists at build time (the toolchain is the Android NDK's clang; its sysroot is bionic). The program is a fully
+static, freestanding executable:
+
+```
+clang --target=aarch64-linux-gnu -ffreestanding -nostdlib -nostdlibinc -static -fno-stack-protector
+      -fno-builtin -O2 -Wall -Wextra -Werror -fuse-ld=lld -Wl,--build-id=none -Wl,-z,max-page-size=65536
+      -e _start -I native/venc/include -I <uapi> -ffile-prefix-map=<native dir>=native
+      fp_venc.c convert.c [sys.c] -o artifacts/linux-arm64-bin/fp_venc
+```
+- `<uapi>`: a staging directory made by build.py under `native/.cache/uapi-arm64/` containing **only** copies of the
+  NDK sysroot's kernel UAPI folders `usr/include/linux`, `usr/include/asm-generic`, `usr/include/drm` and
+  `usr/include/aarch64-linux-android/asm` (as `asm/`). Never put the bionic libc headers on the include path.
+- `stdint.h`, `stddef.h`, `stdbool.h` and `arm_neon.h` come from clang's own resource directory (allowed).
+- Floating point is allowed but not needed; prefer integer math.
+- Add `venc` to build.py's `--only` default list, the docstring, the `steps` dict and the ordered build tuple (last).
+  The step creates `artifacts/linux-arm64-bin/` itself (not `linux-arm64/`: that folder is uploaded whole as the OpenXR layer). `write_sums()` then lists the new file.
+- The binary must be reproducible (same source → same bytes) and contain no local paths.
+
+## Command line
+```
+fp_venc [--height N] [--bitrate BPS] [--peak BPS] [--fps N] [--max-fps N] [--gop-seconds N]
+        [--source PATH] [--encoder PATH] [--probe | --selftest]
+```
+- `--height N`: output height, scaled **down** only. Default: the source height. See "Output size".
+- `--bitrate BPS`: target bitrate in bit/s. Default 3000000.
+- `--peak BPS`: above the bitrate = VBR capped at this peak (the live view uses 1.5×), else CBR.
+- `--fps N`: output frame rate; overrides the automatic choice.
+- `--max-fps N`: cap for the automatic choice. Default 45.
+- `--gop-seconds N`: keyframe interval in seconds. Default 4.
+- `--source PATH`: V4L2 capture device. Default: the `/dev/videoN` whose `/sys/class/video4linux/videoN/name` is
+  exactly `SteamVR` (strip the trailing newline).
+- `--encoder PATH`: the encoder node. Default: `/dev/video-enc0` if it exists, else the first
+  `/sys/class/video4linux/videoN` whose `name` contains `encoder` and that passes the capability check below.
+- `--probe`: do every setup step up to and including buffer allocation (no STREAMON, no frames), print the info JSON
+  (below) on **stdout**, exit.
+- `--selftest`: run the converter self-test (below) and exit. Needs no devices.
+
+Exit codes: 0 ok · 1 self-test failed / runtime error after streaming started · 2 bad arguments · 3 no source
+device · 4 hardware encoder not usable (missing, wrong caps, a required format refused, any setup ioctl failed).
+When the environment variable `FP_VENC_DISABLE=1` is set, setup fails with exit 4 (used to test the fallback).
+The environment is on the stack after argv (`_start`: `argc` at `[sp]`, `argv` at `sp+8`, `envp` after argv's NULL).
+
+### Info JSON
+One line, keys in this order, no spaces:
+`{"encoder":"/dev/video23","source":"/dev/video99","src":[1920,1080],"out":[1280,720],"refresh":96,"fps":32,"bitrate":3000000}`
+`refresh` is the panel rate in whole Hz (0 when unknown). In normal (streaming) mode the same line is written to
+**stderr** right after setup, prefixed `fp_venc: info ` — the PC side reads it for its status line.
+
+## Frame rate
+1. Read the panel's current refresh rate through DRM (read-only, no master needed; `/dev/dri/card0` is mode 0666 on
+   the Frame): open `/dev/dri/card0` (`O_RDWR|O_CLOEXEC`), `DRM_IOCTL_MODE_GETRESOURCES` once for the counts and
+   once more with an array for the CRTC ids, then `DRM_IOCTL_MODE_GETCRTC` for each. Among CRTCs with `mode_valid`,
+   take the one with the largest `hdisplay × vdisplay`. Rate in milli-Hz = `clock(kHz) × 1 000 000 / (htotal × vtotal)`;
+   round to whole Hz. Any failure → refresh unknown.
+2. `fps` = `--fps` if given; else if the refresh is known: `refresh / ceil(refresh / max_fps)` (integer division,
+   rounded to nearest): 72→36, 80→40, 90→45, 96→32, 108→36, 120→40, 144→36; else 30.
+Rationale: frames on an even grid of the panel's refresh look smooth; 30 fps on a 72/96 Hz panel judders.
+
+## Output size
+`out_h = min(--height or src_h, src_h)`, rounded **down** to even. `out_w = floor(src_w × out_h / src_h)` rounded down
+to even. Both ≥ 2. (1920×1080 → 360: 640×360; 480: 852×480; 720: 1280×720; 1080: 1920×1080.)
+
+## Converter (`convert.h`)
+```c
+#include <stdint.h>
+#include <stddef.h>
+void   fp_out_size(int src_w, int src_h, int max_h, int *out_w, int *out_h);   /* rule above; max_h <= 0 = src_h */
+size_t fp_scratch_size(int src_w, int src_h, int out_w, int out_h);           /* bytes of scratch fp_convert needs */
+/* RGB24 (R,G,B bytes) → NV12 (BT.709, limited range). Writes out_w×out_h luma and out_w×out_h/2 interleaved CbCr. */
+void   fp_convert_scalar(const uint8_t *src, int src_w, int src_h, int src_stride,
+                         uint8_t *y, int y_stride, uint8_t *uv, int uv_stride,
+                         int out_w, int out_h, void *scratch);
+void   fp_convert(/* same parameters */);   /* NEON on aarch64; identical to fp_convert_scalar elsewhere */
+```
+Both functions must produce **bit-identical** output; the exact definition is:
+
+1. **Scaling (box average).** For output column `i` the source columns are `[x0, x1)` with
+   `x0 = i·src_w / out_w`, `x1 = (i+1)·src_w / out_w` (integer division); rows likewise with `src_h/out_h`. Each
+   channel of output pixel (i, j) is `(S + n/2) / n` (integer division), `S` = sum of that channel over the block,
+   `n` = block width × block height. When the size is unchanged this is the identity.
+2. **Luma** from each scaled pixel (R, G, B):
+   `Y = 16 + ((47·R + 157·G + 16·B + 128) >> 8)`.
+3. **Chroma** per 2×2 block of scaled pixels: first average each channel, `C = (c00 + c01 + c10 + c11 + 2) >> 2`,
+   then `Cb = 128 + ((−26·R − 86·G + 112·B + 128) >> 8)`, `Cr = 128 + ((112·R − 102·G − 10·B + 128) >> 8)`
+   (`>>` on a signed 32-bit value = floor division by 256). Write Cb then Cr.
+4. Clamp Y to [16, 235] and Cb/Cr to [16, 240] (the formulas already stay inside; clamp anyway).
+The input is sRGB-encoded full-range RGB; no linearisation (video expects gamma-encoded values).
+
+**Performance:** at 1920×1080 → 1920×1080 the aarch64 `fp_convert` should take ≤ 4 ms per frame on one core; scaled
+outputs not more. Suggested shape (free to differ if output stays identical): NEON vertical accumulation of the rows of
+each output row into a uint16/uint32 row buffer, horizontal block sums + division (a per-block-size reciprocal table is
+fine only if it is exact for every possible sum; otherwise divide), NEON colour conversion with `vld3`/widening
+multiplies. The identity size gets a direct NEON path (no box step). Exact 3:2 and 3:1 ratios (720p and 360p from
+1080p) get their own NEON paths: the boxes repeat every 3 source pixels (widths 1,2 resp. 3), so the averages are
+rounding shifts / an exact multiply (×7282 >> 16 = ÷9 for every possible sum). The self-test covers them, including
+columns left over after the 48-pixel steps (1158×648 → 432/216).
+
+### Self-test (`--selftest`)
+Deterministic synthetic images (a 32-bit LCG noise image, a horizontal gradient, solid black/white/red/green/blue,
+a 1-pixel checkerboard) at source sizes 1920×1080, 1922×1080, 333×201 and 64×64, each converted for max heights
+{source height, 720, 480, 360, 100} where ≤ source height. `fp_convert` must equal `fp_convert_scalar` byte for byte
+(Y and UV planes, using strides larger than the width to catch stride bugs). Print `fp_venc: selftest ok (N cases)` or
+the first mismatch (size, plane, x, y, both values) on stderr; exit 0/1. Also time 50 conversions 1920×1080→1080 and
+→720 and print the average ms each.
+
+## Source (V4L2 capture, `/dev/video99`)
+v4l2loopback device written by SteamVR's `v4l2cam` (single-planar `V4L2_BUF_TYPE_VIDEO_CAPTURE`).
+- Open `O_RDWR|O_NONBLOCK|O_CLOEXEC`. `VIDIOC_QUERYCAP`: needs `V4L2_CAP_VIDEO_CAPTURE` + `V4L2_CAP_STREAMING`
+  (check `device_caps` when `V4L2_CAP_DEVICE_CAPS` is set). `VIDIOC_G_FMT`: pixelformat must be `V4L2_PIX_FMT_RGB24`
+  (else exit 4); use its width, height and `bytesperline` (0 → width×3).
+- `VIDIOC_REQBUFS` 3 × `V4L2_MEMORY_MMAP`, `VIDIOC_QUERYBUF` + `mmap(PROT_READ, MAP_SHARED)` each, `VIDIOC_QBUF` all,
+  `VIDIOC_STREAMON`.
+- At most one dequeued buffer is held (the newest frame). When a newer one is dequeued, re-queue the held one first.
+  Drain all ready buffers on each wake-up so the held one is always the newest.
+
+## Encoder (V4L2 memory-to-memory, multi-planar)
+Follow the "Initialization" and "Encoding" sections of `dev-encoder.rst`:
+1. Open `O_RDWR|O_NONBLOCK|O_CLOEXEC`. `VIDIOC_QUERYCAP`: needs `V4L2_CAP_VIDEO_M2M_MPLANE` and
+   `V4L2_CAP_STREAMING` (in `device_caps`).
+2. **Coded format first** — `VIDIOC_S_FMT` on `V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`: `pixelformat = V4L2_PIX_FMT_H264`,
+   width/height = out size, `num_planes = 1`. Must come back as H264 (else exit 4). Its `sizeimage` is the size of
+   the encoded-frame buffers.
+3. **Raw format** — `VIDIOC_S_FMT` on `V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`: `V4L2_PIX_FMT_NV12`, out size,
+   `num_planes = 1`, `colorspace = V4L2_COLORSPACE_REC709`, `ycbcr_enc = V4L2_YCBCR_ENC_709`,
+   `quantization = V4L2_QUANTIZATION_LIM_RANGE`, `xfer_func = V4L2_XFER_FUNC_709`. Use what comes back:
+   `num_planes` must be 1 (else exit 4); `stride = plane_fmt[0].bytesperline`; the returned `height` is the padded
+   height `H'`; the CbCr plane starts at `stride × H'` inside the same buffer; require
+   `stride × H' × 3/2 ≤ plane_fmt[0].sizeimage` and `stride ≥ out_w` (else exit 4).
+4. **Visible rectangle** — `VIDIOC_S_SELECTION` (type `V4L2_BUF_TYPE_VIDEO_OUTPUT`, target `V4L2_SEL_TGT_CROP`,
+   rect 0,0,out_w,out_h). If the driver rejects the single-planar type, retry with the `_MPLANE` type. Failure is only
+   a warning when `G_SELECTION` already reports that rectangle.
+5. **Frame rate** — `VIDIOC_S_PARM` on the OUTPUT queue: `timeperframe = 1/fps` (warning on failure).
+6. **Controls** — `VIDIOC_S_EXT_CTRLS` (or `VIDIOC_S_CTRL` one by one), each best-effort: a refused control prints
+   `fp_venc: warning: <name> refused (<errno>)` and continues:
+   - `V4L2_CID_MPEG_VIDEO_H264_PROFILE` = HIGH; `V4L2_CID_MPEG_VIDEO_H264_LEVEL` = the lowest level whose limits
+     (H.264 Table A-1: MaxFS macroblocks per frame, MaxMBPS macroblocks per second, MaxBR ×1.25 for High in kbit/s)
+     fit out size × fps × bitrate, among 3.1, 3.2, 4, 4.1, 4.2, 5, 5.1, 5.2;
+   - `V4L2_CID_MPEG_VIDEO_BITRATE_MODE` = CBR; `V4L2_CID_MPEG_VIDEO_BITRATE` = bitrate;
+     `V4L2_CID_MPEG_VIDEO_BITRATE_PEAK` = bitrate; `V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE` = 1;
+   - `V4L2_CID_MPEG_VIDEO_B_FRAMES` = 0; `V4L2_CID_MPEG_VIDEO_GOP_SIZE` = fps × gop_seconds;
+   - `V4L2_CID_MPEG_VIDEO_HEADER_MODE` = JOINED_WITH_1ST_FRAME; `V4L2_CID_MPEG_VIDEO_PREPEND_SPSPPS_TO_IDR` = 1
+     (every keyframe is decodable on its own — a viewer may join at any keyframe);
+   - `V4L2_CID_MPEG_VIDEO_FRAME_SKIP_MODE` = DISABLED (one output frame per input frame: the PC side derives
+     timestamps from the frame count).
+7. **Buffers** — `VIDIOC_REQBUFS` OUTPUT_MPLANE 4 × MMAP and CAPTURE_MPLANE 4 × MMAP; `VIDIOC_QUERYBUF` + `mmap` every
+   buffer (OUTPUT: read/write, fill with Y=16/CbCr=128 once so padding rows are defined; CAPTURE: read).
+   (`--probe` stops here: print the JSON, exit 0.)
+8. Queue all CAPTURE buffers, `VIDIOC_STREAMON` both queues.
+9. Per frame: write NV12 into a free OUTPUT buffer (`bytesused` = sizeimage), `VIDIOC_QBUF`. Dequeue finished OUTPUT
+   buffers (they become free). Dequeue CAPTURE buffers: write `bytesused − data_offset` bytes from
+   `mem + data_offset` to stdout, re-queue. `V4L2_BUF_FLAG_ERROR` on a capture buffer: re-queue, count, don't write.
+   `V4L2_BUF_FLAG_LAST`: the encoder is drained.
+10. **Keyframe on request** — set `V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME` (button) just before queuing the next frame.
+11. **Stop** — `VIDIOC_ENCODER_CMD` `V4L2_ENC_CMD_STOP`, keep dequeuing/writing CAPTURE buffers until one has
+    `V4L2_BUF_FLAG_LAST` (or 1 s passes), `VIDIOC_STREAMOFF` both queues, close, exit 0.
+
+## Main loop and timing
+- Ignore `SIGPIPE` (`rt_sigaction` with `SIG_IGN`; no restorer needed for SIG_IGN) so a closed stdout is an `EPIPE`
+  error → stop quietly (exit 0).
+- **stdin protocol** (stdin is the SSH channel; non-blocking reads after `poll`): byte `k` = request a keyframe;
+  byte `q` or end of file = stop (step 11); other bytes ignored.
+- **Fixed frame grid.** `t0` = `CLOCK_MONOTONIC` when streaming starts; slot `n` is due at `t0 + n·10⁹/fps` ns.
+  Exactly **one** frame is queued per slot, always: at slot time, convert the held (newest) source frame — even if it
+  was already used, e.g. while the headset is in standby the source delivers ~1 fps — so the stream's frame count
+  always equals elapsed time × fps. The ffmpeg side relies on that (`-framerate fps`, no timestamps in the stream).
+  Before the first source frame arrives, submit black frames (Y=16, CbCr=128).
+- If no OUTPUT buffer is free at slot time, wait for one (it's the encoder's latency; normal is a few ms). If the loop
+  falls behind (several slots due), submit the missed slots back to back with the same picture. If more than `fps`
+  slots (1 s) are missed at once (e.g. the process was stopped), log it, skip forward to the current slot and continue.
+- Wait with `ppoll` on: source fd (POLLIN), encoder fd (POLLIN = capture ready, POLLOUT = output buffer done),
+  stdin (POLLIN|POLLHUP), timeout = time to the next slot.
+- stdout writes are blocking writes of whole packets (loop over partial writes; `EINTR`/`EAGAIN` retry).
+- Every 10 s print one stderr line: `fp_venc: stats frames=<n> repeats=<frames that reused an already-sent picture>
+  late=<slots submitted late> skipped=<slots skipped> kbps=<average output bitrate>`.
+- All stderr lines start with `fp_venc: `. No output on stdout except the H.264 stream (or the probe JSON).
+
+## Measured facts (the Frame, SteamOS 0.3.0 kernel 6.18, 2026-10-07)
+- Encoder: `/dev/video23` (`/dev/video-enc0` → it), name `qcom-iris-encoder`, driver `iris_driver`, caps
+  M2M multiplanar + streaming. OUTPUT formats: Q08C, NV12, NV21, AB24, QC24. CAPTURE formats: H264, HEVC. Frame sizes
+  128×128 … 8192×8192 step 1. The `steamos` user can open it (group `video`).
+- NV12 S_FMT results (stride / returned height / sizeimage): 640×360 → 640/384/368640; 854×480 → 896/480/647168;
+  1280×720 → 1280/736/1413120; 1920×1080 → 1920/1088/3133440. Default OUTPUT crop = the requested size.
+- Controls present: B_FRAMES (0–7), GOP_SIZE, BITRATE_MODE (VBR, CBR), BITRATE / BITRATE_PEAK (≤ 245 000 000),
+  FRAME_RC_ENABLE, HEADER_MODE (separate, joined with 1st frame), FORCE_KEY_FRAME, H264 PROFILE (Baseline, Constrained
+  Baseline, Main, High, Constrained High), H264 LEVEL (1 … 6.0, default 5), PREPEND_SPSPPS_TO_IDR, FRAME_SKIP_MODE,
+  H264 entropy (CABAC default), I/P QP ranges, intra-refresh period, LTR, hierarchical coding.
+- Source: `/dev/video99`, v4l2loopback, name `SteamVR`, single-planar capture, RGB24 only, 1920×1080, bytesperline
+  5760, advertised 30 fps but frames come at the panel rate when worn, ~1.1 fps in standby.
+- DRM: `/dev/dri/card0` (msm, mode 0666); one active CRTC 4320×2160 (`2*2160x2160_96`, clock 1402720 kHz,
+  htotal 4448, vtotal 3285 → 96.00 Hz). The panel offers 72/80/90/96/108/120/144 Hz.
+- ffmpeg's stock `h264_v4l2m2m` hangs on this encoder; that's why this program exists.

native/venc/convert.c

@@ -0,0 +1,356 @@
+/* RGB24 -> NV12 converter (see convert.h and SPEC.md "Converter"). The scalar code is the definition; the NEON code
+ * must produce the same bytes (fp_venc --selftest compares them). */
+#include "convert.h"
+
+#if defined(__aarch64__)
+#include <arm_neon.h>
+#endif
+
+void fp_out_size(int src_w, int src_h, int max_h, int *out_w, int *out_h)
+{
+    int h = (max_h <= 0 || max_h > src_h) ? src_h : max_h;
+    h &= ~1;
+    int w = (int)((int64_t)src_w * h / src_h) & ~1;
+    *out_w = w < 2 ? 2 : w;
+    *out_h = h < 2 ? 2 : h;
+}
+
+static size_t align16(size_t n) { return (n + 15) & ~(size_t)15; }
+
+/* Scratch layout for scaled output: per-column channel sums of the current output row's source rows (uint32, or
+ * uint16 in the NEON path), the source column where each output column starts, and two scaled RGB rows (one NV12
+ * row pair: chroma needs both). */
+size_t fp_scratch_size(int src_w, int src_h, int out_w, int out_h)
+{
+    (void)src_h;
+    (void)out_h;
+    return align16((size_t)src_w * 3 * 4) + align16(((size_t)out_w + 1) * 4) + align16((size_t)out_w * 6 + 16);
+}
+
+static uint8_t clamp_u8(int v, int lo, int hi) { return (uint8_t)(v < lo ? lo : v > hi ? hi : v); }
+
+/* BT.709 limited range. `>>` on a negative int is an arithmetic (floor) shift with clang/gcc on every target we
+ * build for, which is what the spec's formula means. */
+static uint8_t luma(int r, int g, int b) { return clamp_u8(16 + ((47 * r + 157 * g + 16 * b + 128) >> 8), 16, 235); }
+static uint8_t cb_of(int r, int g, int b) { return clamp_u8(128 + ((-26 * r - 86 * g + 112 * b + 128) >> 8), 16, 240); }
+static uint8_t cr_of(int r, int g, int b) { return clamp_u8(128 + ((112 * r - 102 * g - 10 * b + 128) >> 8), 16, 240); }
+
+/* One NV12 row pair from two RGB rows, columns [x, w) (w even). */
+static void pair_scalar(const uint8_t *r0, const uint8_t *r1, int x, int w, uint8_t *y0, uint8_t *y1, uint8_t *uv)
+{
+    for (; x < w; x += 2) {
+        const uint8_t *a = r0 + x * 3, *b = r1 + x * 3;
+        y0[x] = luma(a[0], a[1], a[2]);
+        y0[x + 1] = luma(a[3], a[4], a[5]);
+        y1[x] = luma(b[0], b[1], b[2]);
+        y1[x + 1] = luma(b[3], b[4], b[5]);
+        int r = (a[0] + a[3] + b[0] + b[3] + 2) >> 2;
+        int g = (a[1] + a[4] + b[1] + b[4] + 2) >> 2;
+        int bl = (a[2] + a[5] + b[2] + b[5] + 2) >> 2;
+        uv[x] = cb_of(r, g, bl);
+        uv[x + 1] = cr_of(r, g, bl);
+    }
+}
+
+struct layout { uint32_t *colsum; int32_t *xb; uint8_t *rgb; };
+
+static struct layout split(void *scratch, int src_w, int out_w)
+{
+    struct layout l;
+    uint8_t *p = scratch;
+    l.colsum = (uint32_t *)p;
+    p += align16((size_t)src_w * 3 * 4);
+    l.xb = (int32_t *)p;
+    p += align16(((size_t)out_w + 1) * 4);
+    l.rgb = p;
+    for (int i = 0; i <= out_w; i++) l.xb[i] = (int32_t)((int64_t)i * src_w / out_w);
+    return l;
+}
+
+void fp_convert_scalar(const uint8_t *src, int src_w, int src_h, int src_stride,
+                       uint8_t *y, int y_stride, uint8_t *uv, int uv_stride,
+                       int out_w, int out_h, void *scratch)
+{
+    if (out_w == src_w && out_h == src_h) {
+        for (int j = 0; j < out_h; j += 2)
+            pair_scalar(src + (size_t)j * src_stride, src + (size_t)(j + 1) * src_stride, 0, out_w,
+                        y + (size_t)j * y_stride, y + (size_t)(j + 1) * y_stride, uv + (size_t)(j / 2) * uv_stride);
+        return;
+    }
+    struct layout l = split(scratch, src_w, out_w);
+    int cols = src_w * 3;
+    for (int j = 0; j < out_h; j++) {
+        int ya = (int)((int64_t)j * src_h / out_h), yb = (int)((int64_t)(j + 1) * src_h / out_h);
+        for (int k = 0; k < cols; k++) l.colsum[k] = 0;
+        for (int r = ya; r < yb; r++) {
+            const uint8_t *row = src + (size_t)r * src_stride;
+            for (int k = 0; k < cols; k++) l.colsum[k] += row[k];
+        }
+        uint8_t *out = l.rgb + (size_t)(j & 1) * out_w * 3;
+        for (int i = 0; i < out_w; i++) {
+            int xa = l.xb[i], xe = l.xb[i + 1];
+            uint64_t n = (uint64_t)(xe - xa) * (uint64_t)(yb - ya);
+            for (int c = 0; c < 3; c++) {
+                uint64_t s = 0;
+                for (int x = xa; x < xe; x++) s += l.colsum[x * 3 + c];
+                out[i * 3 + c] = (uint8_t)((s + n / 2) / n);
+            }
+        }
+        if (j & 1)
+            pair_scalar(l.rgb, l.rgb + (size_t)out_w * 3, 0, out_w, y + (size_t)(j - 1) * y_stride,
+                        y + (size_t)j * y_stride, uv + (size_t)(j / 2) * uv_stride);
+    }
+}
+
+#if defined(__aarch64__)
+
+/* 16 pixels of 2 rows -> 32 luma bytes + 8 CbCr pairs. All intermediates fit: luma sums <= 220*255+128 < 2^16
+ * (uint16), chroma partial sums stay within +-28688 (int16). vrshrn_n_u16(x, 8) == (x + 128) >> 8 and
+ * vrshrq_n_u16(x, 2) == (x + 2) >> 2 exactly (the rounding add is done without overflow). */
+static inline uint8x16_t luma16(uint8x16x3_t p)
+{
+    uint16x8_t lo = vmull_u8(vget_low_u8(p.val[0]), vdup_n_u8(47));
+    lo = vmlal_u8(lo, vget_low_u8(p.val[1]), vdup_n_u8(157));
+    lo = vmlal_u8(lo, vget_low_u8(p.val[2]), vdup_n_u8(16));
+    uint16x8_t hi = vmull_u8(vget_high_u8(p.val[0]), vdup_n_u8(47));
+    hi = vmlal_u8(hi, vget_high_u8(p.val[1]), vdup_n_u8(157));
+    hi = vmlal_u8(hi, vget_high_u8(p.val[2]), vdup_n_u8(16));
+    uint8x16_t yv = vaddq_u8(vcombine_u8(vrshrn_n_u16(lo, 8), vrshrn_n_u16(hi, 8)), vdupq_n_u8(16));
+    return vminq_u8(vmaxq_u8(yv, vdupq_n_u8(16)), vdupq_n_u8(235));
+}
+
+static inline uint8x8_t chroma8(int16x8_t r, int16x8_t g, int16x8_t b, int16_t kr, int16_t kg, int16_t kb)
+{
+    int16x8_t v = vmulq_n_s16(r, kr);
+    v = vmlaq_n_s16(v, g, kg);
+    v = vmlaq_n_s16(v, b, kb);
+    v = vshrq_n_s16(vaddq_s16(v, vdupq_n_s16(128)), 8);              /* arithmetic = floor */
+    v = vaddq_s16(v, vdupq_n_s16(128));
+    v = vminq_s16(vmaxq_s16(v, vdupq_n_s16(16)), vdupq_n_s16(240));
+    return vqmovun_s16(v);
+}
+
+static void pair_neon(const uint8_t *r0, const uint8_t *r1, int w, uint8_t *y0, uint8_t *y1, uint8_t *uv)
+{
+    int x = 0;
+    for (; x + 16 <= w; x += 16) {
+        uint8x16x3_t a = vld3q_u8(r0 + x * 3), b = vld3q_u8(r1 + x * 3);
+        vst1q_u8(y0 + x, luma16(a));
+        vst1q_u8(y1 + x, luma16(b));
+        int16x8_t rr = vreinterpretq_s16_u16(vrshrq_n_u16(vpadalq_u8(vpaddlq_u8(a.val[0]), b.val[0]), 2));
+        int16x8_t gg = vreinterpretq_s16_u16(vrshrq_n_u16(vpadalq_u8(vpaddlq_u8(a.val[1]), b.val[1]), 2));
+        int16x8_t bb = vreinterpretq_s16_u16(vrshrq_n_u16(vpadalq_u8(vpaddlq_u8(a.val[2]), b.val[2]), 2));
+        uint8x8x2_t c;
+        c.val[0] = chroma8(rr, gg, bb, -26, -86, 112);
+        c.val[1] = chroma8(rr, gg, bb, 112, -102, -10);
+        vst2_u8(uv + x, c);
+    }
+    pair_scalar(r0, r1, x, w, y0, y1, uv);
+}
+
+/* Box sums of one output row's source rows, as uint16 (callers ensure rows * 255 fits). */
+static void vsum16(const uint8_t *src, int src_stride, int ya, int yb, int cols, uint16_t *cs)
+{
+    const uint8_t *row = src + (size_t)ya * src_stride;
+    int k = 0;
+    for (; k + 16 <= cols; k += 16) {
+        uint8x16_t v = vld1q_u8(row + k);
+        vst1q_u16(cs + k, vmovl_u8(vget_low_u8(v)));
+        vst1q_u16(cs + k + 8, vmovl_high_u8(v));
+    }
+    for (; k < cols; k++) cs[k] = row[k];
+    for (int r = ya + 1; r < yb; r++) {
+        row = src + (size_t)r * src_stride;
+        k = 0;
+        for (; k + 16 <= cols; k += 16) {
+            uint8x16_t v = vld1q_u8(row + k);
+            vst1q_u16(cs + k, vaddw_u8(vld1q_u16(cs + k), vget_low_u8(v)));
+            vst1q_u16(cs + k + 8, vaddw_high_u8(vld1q_u16(cs + k + 8), v));
+        }
+        for (; k < cols; k++) cs[k] = (uint16_t)(cs[k] + row[k]);
+    }
+}
+
+/* Exact fast paths for the two ratios the live view uses from SteamVR's 1920x1080: 3:2 (720p) and 3:1 (360p). The
+ * box rule (x0 = i * src / out) then repeats every 3 source pixels: 3:2 gives widths 1, 2, 1, 2, ... (rows alike),
+ * 3:1 width 3. Same bytes as the generic path, without its per-pixel scalar loop. */
+
+/* 48 pixels of an RGB row -> ph[c][k] = channel c of pixels 3g+k, g = 0..15. */
+static inline void load48(const uint8_t *row, uint8x16_t ph[3][3])
+{
+    uint8_t planes[3][48];
+    for (int q = 0; q < 3; q++) {
+        uint8x16x3_t p = vld3q_u8(row + q * 48);
+        for (int c = 0; c < 3; c++) vst1q_u8(planes[c] + q * 16, p.val[c]);
+    }
+    for (int c = 0; c < 3; c++) {
+        uint8x16x3_t s = vld3q_u8(planes[c]);
+        ph[c][0] = s.val[0], ph[c][1] = s.val[1], ph[c][2] = s.val[2];
+    }
+}
+
+/* (a + b + c + d + 2) >> 2 for 16 lanes. */
+static inline uint8x16_t avg4(uint8x16_t a, uint8x16_t b, uint8x16_t c, uint8x16_t d)
+{
+    uint16x8_t lo = vaddq_u16(vaddl_u8(vget_low_u8(a), vget_low_u8(b)), vaddl_u8(vget_low_u8(c), vget_low_u8(d)));
+    uint16x8_t hi = vaddq_u16(vaddl_high_u8(a, b), vaddl_high_u8(c, d));
+    return vcombine_u8(vrshrn_n_u16(lo, 2), vrshrn_n_u16(hi, 2));
+}
+
+/* Store even/odd output pixels (16 each per channel) as 32 interleaved RGB pixels. */
+static inline void store_pairs(uint8_t *out, uint8x16_t even[3], uint8x16_t odd[3])
+{
+    uint8x16x3_t a, b;
+    for (int c = 0; c < 3; c++) a.val[c] = vzip1q_u8(even[c], odd[c]), b.val[c] = vzip2q_u8(even[c], odd[c]);
+    vst3q_u8(out, a);
+    vst3q_u8(out + 48, b);
+}
+
+/* 3 source rows -> 2 RGB output rows (3:2 both ways): row a from r0 alone, row b from r1 + r2. */
+static void rows_3to2(const uint8_t *r0, const uint8_t *r1, const uint8_t *r2, int src_w, uint8_t *oa, uint8_t *ob)
+{
+    int x = 0;
+    uint8_t *pa = oa, *pb = ob;
+    for (; x + 48 <= src_w; x += 48, pa += 96, pb += 96) {
+        uint8x16_t a[3][3], b[3][3], c[3][3], ea[3], odda[3], eb[3], oddb[3];
+        load48(r0 + x * 3, a), load48(r1 + x * 3, b), load48(r2 + x * 3, c);
+        for (int ch = 0; ch < 3; ch++) {
+            ea[ch] = a[ch][0];                                              /* 1x1 */
+            odda[ch] = vrhaddq_u8(a[ch][1], a[ch][2]);                      /* 2x1: (s + 1) >> 1 */
+            eb[ch] = vrhaddq_u8(b[ch][0], c[ch][0]);                        /* 1x2 */
+            oddb[ch] = avg4(b[ch][1], b[ch][2], c[ch][1], c[ch][2]);        /* 2x2: (s + 2) >> 2 */
+        }
+        store_pairs(pa, ea, odda);
+        store_pairs(pb, eb, oddb);
+    }
+    for (; x < src_w; x += 3, pa += 6, pb += 6)
+        for (int ch = 0; ch < 3; ch++) {
+            const uint8_t *p0 = r0 + x * 3 + ch, *p1 = r1 + x * 3 + ch, *p2 = r2 + x * 3 + ch;
+            pa[ch] = p0[0];
+            pa[3 + ch] = (uint8_t)((p0[3] + p0[6] + 1) >> 1);
+            pb[ch] = (uint8_t)((p1[0] + p2[0] + 1) >> 1);
+            pb[3 + ch] = (uint8_t)((p1[3] + p1[6] + p2[3] + p2[6] + 2) >> 2);
+        }
+}
+
+/* 3 source rows -> 1 RGB output row (3:1 both ways): (sum of 9 + 4) / 9, the division as *7282 >> 16 (exact for
+ * every sum up to 9 * 255 + 4). */
+static void row_3to1(const uint8_t *r0, const uint8_t *r1, const uint8_t *r2, int src_w, uint8_t *out)
+{
+    int x = 0;
+    uint8_t *p = out;
+    for (; x + 48 <= src_w; x += 48, p += 48) {
+        uint8x16_t a[3][3], b[3][3], c[3][3];
+        load48(r0 + x * 3, a), load48(r1 + x * 3, b), load48(r2 + x * 3, c);
+        uint8x16x3_t o;
+        for (int ch = 0; ch < 3; ch++) {
+            uint16x8_t lo = vdupq_n_u16(4), hi = vdupq_n_u16(4);
+            for (int k = 0; k < 3; k++) {
+                lo = vaddw_u8(vaddw_u8(vaddw_u8(lo, vget_low_u8(a[ch][k])), vget_low_u8(b[ch][k])), vget_low_u8(c[ch][k]));
+                hi = vaddw_high_u8(vaddw_high_u8(vaddw_high_u8(hi, a[ch][k]), b[ch][k]), c[ch][k]);
+            }
+            uint16x4_t m = vdup_n_u16(7282);
+            uint16x8_t qlo = vcombine_u16(vshrn_n_u32(vmull_u16(vget_low_u16(lo), m), 16),
+                                          vshrn_n_u32(vmull_u16(vget_high_u16(lo), m), 16));
+            uint16x8_t qhi = vcombine_u16(vshrn_n_u32(vmull_u16(vget_low_u16(hi), m), 16),
+                                          vshrn_n_u32(vmull_u16(vget_high_u16(hi), m), 16));
+            o.val[ch] = vcombine_u8(vmovn_u16(qlo), vmovn_u16(qhi));
+        }
+        vst3q_u8(p, o);
+    }
+    for (; x < src_w; x += 3, p += 3)
+        for (int ch = 0; ch < 3; ch++) {
+            int s = 4;
+            for (int k = 0; k < 3; k++) s += r0[(x + k) * 3 + ch] + r1[(x + k) * 3 + ch] + r2[(x + k) * 3 + ch];
+            p[ch] = (uint8_t)(s / 9);
+        }
+}
+
+#define MAX_RECIP_BW 64
+
+void fp_convert(const uint8_t *src, int src_w, int src_h, int src_stride,
+                uint8_t *y, int y_stride, uint8_t *uv, int uv_stride,
+                int out_w, int out_h, void *scratch)
+{
+    if (out_w == src_w && out_h == src_h) {
+        for (int j = 0; j < out_h; j += 2)
+            pair_neon(src + (size_t)j * src_stride, src + (size_t)(j + 1) * src_stride, out_w,
+                      y + (size_t)j * y_stride, y + (size_t)(j + 1) * y_stride, uv + (size_t)(j / 2) * uv_stride);
+        return;
+    }
+    if (src_w * 2 == out_w * 3 && src_h * 2 == out_h * 3) {   /* 3:2 (out_h even: whole 3-row groups) */
+        struct layout l = split(scratch, src_w, out_w);
+        uint8_t *a = l.rgb, *b = l.rgb + (size_t)out_w * 3;
+        for (int t = 0; t < out_h / 2; t++) {
+            const uint8_t *r0 = src + (size_t)(3 * t) * src_stride;
+            rows_3to2(r0, r0 + src_stride, r0 + 2 * (size_t)src_stride, src_w, a, b);
+            pair_neon(a, b, out_w, y + (size_t)(2 * t) * y_stride, y + (size_t)(2 * t + 1) * y_stride,
+                      uv + (size_t)t * uv_stride);
+        }
+        return;
+    }
+    if (src_w == out_w * 3 && src_h == out_h * 3) {           /* 3:1 */
+        struct layout l = split(scratch, src_w, out_w);
+        uint8_t *a = l.rgb, *b = l.rgb + (size_t)out_w * 3;
+        for (int j = 0; j < out_h; j += 2) {
+            const uint8_t *r0 = src + (size_t)(3 * j) * src_stride, *r3 = r0 + 3 * (size_t)src_stride;
+            row_3to1(r0, r0 + src_stride, r0 + 2 * (size_t)src_stride, src_w, a);
+            row_3to1(r3, r3 + src_stride, r3 + 2 * (size_t)src_stride, src_w, b);
+            pair_neon(a, b, out_w, y + (size_t)j * y_stride, y + (size_t)(j + 1) * y_stride,
+                      uv + (size_t)(j / 2) * uv_stride);
+        }
+        return;
+    }
+    int bh_max = (src_h + out_h - 1) / out_h + 1;
+    if (bh_max > 257) {   /* uint16 column sums would overflow: extreme downscale, not worth a NEON path */
+        fp_convert_scalar(src, src_w, src_h, src_stride, y, y_stride, uv, uv_stride, out_w, out_h, scratch);
+        return;
+    }
+    struct layout l = split(scratch, src_w, out_w);
+    uint16_t *cs = (uint16_t *)l.colsum;
+    int cols = src_w * 3;
+    for (int j = 0; j < out_h; j++) {
+        int ya = (int)((int64_t)j * src_h / out_h), yb = (int)((int64_t)(j + 1) * src_h / out_h);
+        int bh = yb - ya;
+        vsum16(src, src_stride, ya, yb, cols, cs);
+        /* (S + n/2) / n as a multiply: with m = ceil(2^32 / n) and e = m*n - 2^32 < n, floor(x*m / 2^32) ==
+         * floor(x / n) whenever x*e < 2^32. Here x < 256*n, so n <= 4096 is enough. Otherwise divide. */
+        uint64_t recip[MAX_RECIP_BW + 1];
+        for (int bw = 1; bw <= MAX_RECIP_BW; bw++) {
+            uint64_t n = (uint64_t)bw * bh;
+            recip[bw] = n <= 4096 ? ((1ULL << 32) + n - 1) / n : 0;
+        }
+        uint8_t *out = l.rgb + (size_t)(j & 1) * out_w * 3;
+        for (int i = 0; i < out_w; i++) {
+            int xa = l.xb[i], bw = l.xb[i + 1] - xa;
+            const uint16_t *c = cs + xa * 3;
+            uint32_t sr = 0, sg = 0, sb = 0;
+            for (int x = 0; x < bw; x++, c += 3) sr += c[0], sg += c[1], sb += c[2];
+            uint64_t n = (uint64_t)bw * bh, half = n / 2;
+            uint64_t m = bw <= MAX_RECIP_BW ? recip[bw] : 0;
+            if (m) {
+                out[i * 3] = (uint8_t)(((sr + half) * m) >> 32);
+                out[i * 3 + 1] = (uint8_t)(((sg + half) * m) >> 32);
+                out[i * 3 + 2] = (uint8_t)(((sb + half) * m) >> 32);
+            } else {
+                out[i * 3] = (uint8_t)((sr + half) / n);
+                out[i * 3 + 1] = (uint8_t)((sg + half) / n);
+                out[i * 3 + 2] = (uint8_t)((sb + half) / n);
+            }
+        }
+        if (j & 1)
+            pair_neon(l.rgb, l.rgb + (size_t)out_w * 3, out_w, y + (size_t)(j - 1) * y_stride,
+                      y + (size_t)j * y_stride, uv + (size_t)(j / 2) * uv_stride);
+    }
+}
+
+#else
+
+void fp_convert(const uint8_t *src, int src_w, int src_h, int src_stride,
+                uint8_t *y, int y_stride, uint8_t *uv, int uv_stride,
+                int out_w, int out_h, void *scratch)
+{
+    fp_convert_scalar(src, src_w, src_h, src_stride, y, y_stride, uv, uv_stride, out_w, out_h, scratch);
+}
+
+#endif

native/venc/convert.h

@@ -0,0 +1,27 @@
+/* RGB24 -> NV12 picture converter for fp_venc (pure computation, no syscalls). See native/venc/SPEC.md "Converter".
+ * Built for aarch64 (NEON + scalar) and for x86_64 (scalar only; the host unit test loads it with ctypes). */
+#ifndef FP_VENC_CONVERT_H
+#define FP_VENC_CONVERT_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+/* Output size: height = min(max_h, src_h) (max_h <= 0 = src_h), width keeps the aspect; both rounded down to even,
+ * both >= 2. */
+void fp_out_size(int src_w, int src_h, int max_h, int *out_w, int *out_h);
+
+/* Bytes of scratch memory fp_convert/fp_convert_scalar need for these sizes. */
+size_t fp_scratch_size(int src_w, int src_h, int out_w, int out_h);
+
+/* RGB24 (R,G,B bytes) -> NV12 (BT.709, limited range): box-average downscale to out_w x out_h (out_w <= src_w,
+ * out_h <= src_h, both even), then out_w x out_h luma bytes and out_w x out_h/2 interleaved Cb,Cr bytes. */
+void fp_convert_scalar(const uint8_t *src, int src_w, int src_h, int src_stride,
+                       uint8_t *y, int y_stride, uint8_t *uv, int uv_stride,
+                       int out_w, int out_h, void *scratch);
+
+/* Same result, byte for byte; NEON on aarch64, fp_convert_scalar elsewhere. */
+void fp_convert(const uint8_t *src, int src_w, int src_h, int src_stride,
+                uint8_t *y, int y_stride, uint8_t *uv, int uv_stride,
+                int out_w, int out_h, void *scratch);
+
+#endif

native/venc/fp_venc.c

@@ -0,0 +1,858 @@
+/* fp_venc: hardware H.264 encoding of the Steam Frame's SteamVR "headset view" webcam for FramePort's live view.
+ * Source (v4l2loopback, RGB24) -> NV12 (convert.c) -> the SoC's V4L2 stateful encoder -> H.264 Annex B on stdout.
+ * Specification: native/venc/SPEC.md (V4L2: kernel Documentation/userspace-api/media/v4l/dev-encoder.rst). */
+#include "sys.h"
+#include "convert.h"
+#include <linux/videodev2.h>
+#include <drm/drm.h>
+#include <drm/drm_mode.h>
+
+#define SRC_BUFS 3
+#define ENC_BUFS 4
+#define TAG "fp_venc: "
+
+/* ---------------------------------------------------------------- output helpers */
+
+static void say(const char *a, const char *b, long n, int with_n)
+{
+    struct line l = {.n = 0};
+    ls(&l, TAG);
+    ls(&l, a);
+    if (b) ls(&l, b);
+    if (with_n) ln(&l, n);
+    ls(&l, "\n");
+    write_all(2, l.b, (size_t)l.n);
+}
+static void msg(const char *a) { say(a, 0, 0, 0); }
+static void msg_err(const char *what, long err) { say(what, " failed, errno ", -err, 1); }
+static int fail(int code, const char *what, long err)
+{
+    msg_err(what, err);
+    return code;
+}
+
+/* Whole-packet blocking write to stdout. Returns 0, or -1 when the reader is gone (EPIPE etc.). */
+static int out_all(const uint8_t *p, size_t n)
+{
+    while (n) {
+        long r = sys_write(1, p, n);
+        if (r == -EINTR) continue;
+        if (r == -EAGAIN) {   /* stdout happens to be non-blocking: wait instead of spinning */
+            struct pollfd_k f = {1, POLLOUT, 0};
+            sys_ppoll(&f, 1, 0);
+            continue;
+        }
+        if (r <= 0) return -1;
+        p += r;
+        n -= (size_t)r;
+    }
+    return 0;
+}
+
+/* ---------------------------------------------------------------- options */
+
+struct opts {
+    long height, bitrate, peak, fps, max_fps, gop_seconds;
+    const char *source, *encoder;
+    int probe, selftest;
+};
+
+static int parse_args(int argc, char **argv, struct opts *o)
+{
+    o->height = 0, o->bitrate = 3000000, o->peak = 0, o->fps = 0, o->max_fps = 45, o->gop_seconds = 4;
+    o->source = o->encoder = 0;
+    o->probe = o->selftest = 0;
+    for (int i = 1; i < argc; i++) {
+        const char *a = argv[i];
+        long *num = 0;
+        long lo = 1, hi = 0x7fffffff;
+        if (str_eq(a, "--probe")) { o->probe = 1; continue; }
+        if (str_eq(a, "--selftest")) { o->selftest = 1; continue; }
+        if (i + 1 >= argc) return 0;
+        if (str_eq(a, "--source")) { o->source = argv[++i]; continue; }
+        if (str_eq(a, "--encoder")) { o->encoder = argv[++i]; continue; }
+        if (str_eq(a, "--height")) num = &o->height, lo = 2;
+        else if (str_eq(a, "--bitrate")) num = &o->bitrate, lo = 10000;
+        else if (str_eq(a, "--peak")) num = &o->peak, lo = 10000, hi = 245000000;
+        else if (str_eq(a, "--fps")) num = &o->fps, hi = 240;
+        else if (str_eq(a, "--max-fps")) num = &o->max_fps, hi = 240;
+        else if (str_eq(a, "--gop-seconds")) num = &o->gop_seconds, hi = 3600;
+        else return 0;
+        if (!parse_uint(argv[++i], num) || *num < lo || *num > hi) return 0;
+    }
+    return !(o->probe && o->selftest);
+}
+
+static const char *getenv_(char **envp, const char *name)
+{
+    size_t n = str_len(name);
+    for (; envp && *envp; envp++) {
+        const char *e = *envp;
+        size_t i = 0;
+        while (i < n && e[i] == name[i]) i++;
+        if (i == n && e[n] == '=') return e + n + 1;
+    }
+    return 0;
+}
+
+static void *alloc(size_t n)
+{
+    void *p = sys_mmap(0, n, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
+    return mmap_failed(p) ? 0 : p;
+}
+
+/* ---------------------------------------------------------------- converter self-test */
+
+static void fill_image(uint8_t *p, int w, int h, int stride, int kind)
+{
+    uint32_t s = 12345;
+    for (int y = 0; y < h; y++)
+        for (int x = 0; x < w; x++) {
+            uint8_t *q = p + (size_t)y * stride + x * 3;
+            uint8_t r = 0, g = 0, b = 0;
+            switch (kind) {
+            case 0: /* 32-bit LCG noise */
+                s = s * 1664525u + 1013904223u, r = (uint8_t)(s >> 24);
+                s = s * 1664525u + 1013904223u, g = (uint8_t)(s >> 24);
+                s = s * 1664525u + 1013904223u, b = (uint8_t)(s >> 24);
+                break;
+            case 1: r = g = b = (uint8_t)(x * 255 / (w > 1 ? w - 1 : 1)); break;   /* horizontal gradient */
+            case 2: break;                                                    /* black */
+            case 3: r = g = b = 255; break;                                   /* white */
+            case 4: r = 255; break;
+            case 5: g = 255; break;
+            case 6: b = 255; break;
+            default: r = g = b = ((x ^ y) & 1) ? 255 : 0; break;              /* 1-pixel checkerboard */
+            }
+            q[0] = r, q[1] = g, q[2] = b;
+        }
+}
+
+static int selftest(void)
+{
+    /* 1158x648: 3:2 (-> 432) and 3:1 (-> 216) fast paths with columns left over after their 48-pixel steps */
+    static const int sizes[5][2] = {{1920, 1080}, {1922, 1080}, {333, 201}, {64, 64}, {1158, 648}};
+    static const int heights[7] = {0, 720, 480, 360, 100, 432, 216};
+    size_t src_cap = (size_t)(1922 * 3 + 13) * 1080, plane_cap = (size_t)(1922 + 37) * 1080;
+    uint8_t *src = alloc(src_cap), *ya = alloc(plane_cap), *yb = alloc(plane_cap);
+    uint8_t *uva = alloc(plane_cap), *uvb = alloc(plane_cap);
+    void *scratch = alloc(fp_scratch_size(1922, 1080, 1922, 1080) + 4096);
+    if (!src || !ya || !yb || !uva || !uvb || !scratch) return fail(1, "selftest memory", -ENOMEM);
+    int cases = 0;
+    for (int s = 0; s < 5; s++)
+        for (int k = 0; k < 8; k++) {
+            int w = sizes[s][0], h = sizes[s][1], stride = w * 3 + 13;   /* odd stride: catches stride bugs */
+            fill_image(src, w, h, stride, k);
+            for (int hi = 0; hi < 7; hi++) {
+                if (heights[hi] > h) continue;
+                int ow, oh;
+                fp_out_size(w, h, heights[hi], &ow, &oh);
+                int ys = ow + 37, uvs = ow + 21;
+                memset(ya, 0x5a, (size_t)ys * oh), memset(yb, 0x5a, (size_t)ys * oh);
+                memset(uva, 0x5a, (size_t)uvs * oh / 2), memset(uvb, 0x5a, (size_t)uvs * oh / 2);
+                fp_convert_scalar(src, w, h, stride, ya, ys, uva, uvs, ow, oh, scratch);
+                fp_convert(src, w, h, stride, yb, ys, uvb, uvs, ow, oh, scratch);
+                cases++;
+                for (int pl = 0; pl < 2; pl++) {
+                    const uint8_t *a = pl ? uva : ya, *b = pl ? uvb : yb;
+                    int st = pl ? uvs : ys, rows = pl ? oh / 2 : oh;
+                    for (int y = 0; y < rows; y++)
+                        for (int x = 0; x < st; x++) {
+                            if (a[(size_t)y * st + x] == b[(size_t)y * st + x]) continue;
+                            struct line l = {.n = 0};
+                            ls(&l, TAG "selftest mismatch: ");
+                            ln(&l, w), ls(&l, "x"), ln(&l, h), ls(&l, " -> "), ln(&l, ow), ls(&l, "x"), ln(&l, oh);
+                            ls(&l, " image "), ln(&l, k), ls(&l, pl ? " plane UV" : " plane Y");
+                            ls(&l, " x="), ln(&l, x), ls(&l, " y="), ln(&l, y);
+                            ls(&l, " scalar="), ln(&l, a[(size_t)y * st + x]);
+                            ls(&l, " fast="), ln(&l, b[(size_t)y * st + x]), ls(&l, "\n");
+                            write_all(2, l.b, (size_t)l.n);
+                            return 1;
+                        }
+                }
+            }
+        }
+    struct line ok = {.n = 0};
+    ls(&ok, TAG "selftest ok ("), ln(&ok, cases), ls(&ok, " cases)\n");
+    write_all(2, ok.b, (size_t)ok.n);
+    /* Speed of the real path on the real source size. */
+    fill_image(src, 1920, 1080, 5760, 0);
+    static const int timed[4] = {1080, 720, 480, 360};
+    for (int t = 0; t < 4; t++) {
+        int ow, oh;
+        fp_out_size(1920, 1080, timed[t], &ow, &oh);
+        int64_t t0 = now_ns();
+        for (int i = 0; i < 50; i++) fp_convert(src, 1920, 1080, 5760, ya, ow, uva, ow, ow, oh, scratch);
+        struct line l = {.n = 0};
+        ls(&l, TAG "selftest 1920x1080 -> "), ln(&l, oh), ls(&l, ": "), lms(&l, (now_ns() - t0) / 50), ls(&l, " ms\n");
+        write_all(2, l.b, (size_t)l.n);
+    }
+    return 0;
+}
+
+/* ---------------------------------------------------------------- devices */
+
+static int read_small(const char *path, char *buf, int cap)
+{
+    int fd = sys_open(path, O_RDONLY | O_CLOEXEC);
+    if (fd < 0) return -1;
+    long n = sys_read(fd, buf, (size_t)cap - 1);
+    sys_close(fd);
+    if (n < 0) return -1;
+    while (n > 0 && (buf[n - 1] == '\n' || buf[n - 1] == '\r')) n--;
+    buf[n] = 0;
+    return (int)n;
+}
+
+/* "/sys/class/video4linux/video<n>/name" / "/dev/video<n>" */
+static void node_path(char *out, const char *pre, int n, const char *post)
+{
+    struct line l = {.n = 0};
+    ls(&l, pre), ln(&l, n), ls(&l, post);
+    memcpy(out, l.b, (size_t)l.n);
+    out[l.n] = 0;
+}
+
+static uint32_t v4l2_caps(int fd)
+{
+    struct v4l2_capability cap;
+    memset(&cap, 0, sizeof cap);
+    if (sys_ioctl(fd, VIDIOC_QUERYCAP, &cap) < 0) return 0;
+    return (cap.capabilities & V4L2_CAP_DEVICE_CAPS) ? cap.device_caps : cap.capabilities;
+}
+
+static int enc_caps_ok(uint32_t c) { return (c & V4L2_CAP_VIDEO_M2M_MPLANE) && (c & V4L2_CAP_STREAMING); }
+
+static int find_source(char *path)
+{
+    char name[128], sys[96];
+    for (int n = 0; n < 256; n++) {
+        node_path(sys, "/sys/class/video4linux/video", n, "/name");
+        if (read_small(sys, name, sizeof name) >= 0 && str_eq(name, "SteamVR")) {
+            node_path(path, "/dev/video", n, "");
+            return 1;
+        }
+    }
+    return 0;
+}
+
+static int find_encoder(char *path)
+{
+    char link[64];
+    long n = sys_readlink("/dev/video-enc0", link, sizeof link - 1);
+    if (n > 0) {   /* report the real node (/dev/video23), as the PC side shows it */
+        link[n] = 0;
+        struct line l = {.n = 0};
+        if (link[0] != '/') ls(&l, "/dev/");
+        ls(&l, link);
+        memcpy(path, l.b, (size_t)l.n);
+        path[l.n] = 0;
+        return 1;
+    }
+    int fd = sys_open("/dev/video-enc0", O_RDWR | O_CLOEXEC);
+    if (fd >= 0) {
+        sys_close(fd);
+        memcpy(path, "/dev/video-enc0", 16);
+        return 1;
+    }
+    char name[128], sys[96];
+    for (int i = 0; i < 256; i++) {
+        node_path(sys, "/sys/class/video4linux/video", i, "/name");
+        if (read_small(sys, name, sizeof name) < 0 || !str_contains(name, "encoder")) continue;
+        node_path(path, "/dev/video", i, "");
+        fd = sys_open(path, O_RDWR | O_NONBLOCK | O_CLOEXEC);
+        if (fd < 0) continue;
+        int ok = enc_caps_ok(v4l2_caps(fd));
+        sys_close(fd);
+        if (ok) return 1;
+    }
+    return 0;
+}
+
+/* Panel refresh in whole Hz via DRM KMS (read-only ioctls, no master needed); 0 = unknown. */
+static int panel_refresh(void)
+{
+    int fd = sys_open("/dev/dri/card0", O_RDWR | O_CLOEXEC);
+    if (fd < 0) return 0;
+    struct drm_mode_card_res res;
+    uint32_t ids[16];
+    int best = 0;
+    uint64_t best_area = 0;
+    memset(&res, 0, sizeof res);
+    if (sys_ioctl(fd, DRM_IOCTL_MODE_GETRESOURCES, &res) == 0 && res.count_crtcs) {
+        uint32_t n = res.count_crtcs > 16 ? 16 : res.count_crtcs;
+        memset(&res, 0, sizeof res);
+        res.count_crtcs = n;   /* other counts 0: the kernel copies only the arrays we provide room for */
+        res.crtc_id_ptr = (uint64_t)(uintptr_t)ids;
+        if (sys_ioctl(fd, DRM_IOCTL_MODE_GETRESOURCES, &res) == 0) {
+            if (res.count_crtcs < n) n = res.count_crtcs;
+            for (uint32_t i = 0; i < n; i++) {
+                struct drm_mode_crtc c;
+                memset(&c, 0, sizeof c);
+                c.crtc_id = ids[i];
+                if (sys_ioctl(fd, DRM_IOCTL_MODE_GETCRTC, &c) < 0 || !c.mode_valid) continue;
+                uint64_t area = (uint64_t)c.mode.hdisplay * c.mode.vdisplay;
+                uint64_t tot = (uint64_t)c.mode.htotal * c.mode.vtotal;
+                if (area <= best_area || !tot) continue;
+                uint64_t mhz = (uint64_t)c.mode.clock * 1000000 / tot;
+                best_area = area;
+                best = (int)((mhz + 500) / 1000);
+            }
+        }
+    }
+    sys_close(fd);
+    return best;
+}
+
+/* H.264 Table A-1 (MaxMBPS, MaxFS, MaxBR in 1000 bit/s; High profile allows 1.25x MaxBR). */
+static int pick_level(int w, int h, int fps, long bitrate)
+{
+    static const struct { int level; long mbps, fs, br; } t[] = {
+        {V4L2_MPEG_VIDEO_H264_LEVEL_3_1, 108000, 3600, 14000}, {V4L2_MPEG_VIDEO_H264_LEVEL_3_2, 216000, 5120, 20000},
+        {V4L2_MPEG_VIDEO_H264_LEVEL_4_0, 245760, 8192, 20000}, {V4L2_MPEG_VIDEO_H264_LEVEL_4_1, 245760, 8192, 50000},
+        {V4L2_MPEG_VIDEO_H264_LEVEL_4_2, 522240, 8704, 50000}, {V4L2_MPEG_VIDEO_H264_LEVEL_5_0, 589824, 22080, 135000},
+        {V4L2_MPEG_VIDEO_H264_LEVEL_5_1, 983040, 36864, 240000}, {V4L2_MPEG_VIDEO_H264_LEVEL_5_2, 2073600, 36864, 240000},
+    };
+    long fs = (long)((w + 15) / 16) * ((h + 15) / 16);
+    for (unsigned i = 0; i < sizeof t / sizeof t[0]; i++)
+        if (fs <= t[i].fs && fs * fps <= t[i].mbps && bitrate <= t[i].br * 1250) return t[i].level;
+    return V4L2_MPEG_VIDEO_H264_LEVEL_5_2;
+}
+
+static int set_ctrl(int fd, uint32_t id, int32_t value, const char *name, int quiet)
+{
+    struct v4l2_ext_control c;
+    struct v4l2_ext_controls cs;
+    memset(&c, 0, sizeof c);
+    memset(&cs, 0, sizeof cs);
+    c.id = id;
+    c.value = value;
+    cs.which = V4L2_CTRL_WHICH_CUR_VAL;
+    cs.count = 1;
+    cs.controls = &c;
+    int r = sys_ioctl(fd, VIDIOC_S_EXT_CTRLS, &cs);
+    if (r < 0 && !quiet) {
+        struct line l = {.n = 0};
+        ls(&l, TAG "warning: "), ls(&l, name), ls(&l, " refused ("), ln(&l, -r), ls(&l, ")\n");
+        write_all(2, l.b, (size_t)l.n);
+    }
+    return r;
+}
+
+struct src {
+    int fd, w, h, stride;
+    uint8_t *mem[SRC_BUFS];
+    uint32_t len[SRC_BUFS];
+    int held;          /* index of the dequeued (newest) buffer we keep, -1 = none yet */
+    int fresh;         /* the held picture has not been encoded yet */
+};
+
+struct enc {
+    int fd, stride, hpad;
+    uint32_t out_size, cap_size;
+    uint8_t *out_mem[ENC_BUFS], *cap_mem[ENC_BUFS];
+    uint32_t out_len[ENC_BUFS], cap_len[ENC_BUFS];
+    int out_free[ENC_BUFS];
+    long out_pic[ENC_BUFS];   /* which picture each OUTPUT buffer holds (0 = black, -1 = none): a repeat that finds
+                               * its picture already in the buffer skips the conversion (standby, still scenes) */
+};
+
+static int src_open(struct src *s, const char *path)
+{
+    s->held = -1, s->fresh = 0;
+    s->fd = sys_open(path, O_RDWR | O_NONBLOCK | O_CLOEXEC);
+    if (s->fd < 0) return fail(3, "open source", s->fd);
+    uint32_t c = v4l2_caps(s->fd);
+    if (!(c & V4L2_CAP_VIDEO_CAPTURE) || !(c & V4L2_CAP_STREAMING)) return fail(3, "source capabilities", -EINVAL);
+    struct v4l2_format f;
+    memset(&f, 0, sizeof f);
+    f.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+    int r = sys_ioctl(s->fd, VIDIOC_G_FMT, &f);
+    if (r < 0) return fail(3, "source VIDIOC_G_FMT", r);
+    if (f.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) {
+        msg("source pixel format is not RGB24");
+        return 4;
+    }
+    s->w = (int)f.fmt.pix.width, s->h = (int)f.fmt.pix.height;
+    s->stride = f.fmt.pix.bytesperline ? (int)f.fmt.pix.bytesperline : s->w * 3;
+    if (s->w < 2 || s->h < 2 || s->stride < s->w * 3) return fail(4, "source size", -EINVAL);
+    struct v4l2_requestbuffers rb;
+    memset(&rb, 0, sizeof rb);
+    rb.count = SRC_BUFS, rb.type = V4L2_BUF_TYPE_VIDEO_CAPTURE, rb.memory = V4L2_MEMORY_MMAP;
+    r = sys_ioctl(s->fd, VIDIOC_REQBUFS, &rb);
+    /* The driver may grant fewer (the Frame's v4l2loopback has max_buffers=2); two are enough: one held, one filling. */
+    if (r < 0 || rb.count < 2) return fail(3, "source VIDIOC_REQBUFS", r < 0 ? r : -ENOMEM);
+    if (rb.count > SRC_BUFS) rb.count = SRC_BUFS;
+    for (int i = 0; i < (int)rb.count; i++) {
+        struct v4l2_buffer b;
+        memset(&b, 0, sizeof b);
+        b.index = (uint32_t)i, b.type = V4L2_BUF_TYPE_VIDEO_CAPTURE, b.memory = V4L2_MEMORY_MMAP;
+        r = sys_ioctl(s->fd, VIDIOC_QUERYBUF, &b);
+        if (r < 0) return fail(3, "source VIDIOC_QUERYBUF", r);
+        if (b.length < (uint32_t)(s->stride * (s->h - 1) + s->w * 3)) return fail(3, "source buffer size", -EINVAL);
+        s->mem[i] = sys_mmap(0, b.length, PROT_READ, MAP_SHARED, s->fd, b.m.offset);
+        if (mmap_failed(s->mem[i])) return fail(3, "source mmap", (long)s->mem[i]);
+        s->len[i] = b.length;
+        r = sys_ioctl(s->fd, VIDIOC_QBUF, &b);
+        if (r < 0) return fail(3, "source VIDIOC_QBUF", r);
+    }
+    return 0;
+}
+
+/* Drain every ready source buffer, keeping only the newest one. */
+static void src_drain(struct src *s)
+{
+    for (;;) {
+        struct v4l2_buffer b;
+        memset(&b, 0, sizeof b);
+        b.type = V4L2_BUF_TYPE_VIDEO_CAPTURE, b.memory = V4L2_MEMORY_MMAP;
+        if (sys_ioctl(s->fd, VIDIOC_DQBUF, &b) < 0) return;
+        if (b.flags & V4L2_BUF_FLAG_ERROR) {
+            sys_ioctl(s->fd, VIDIOC_QBUF, &b);
+            continue;
+        }
+        if (s->held >= 0) {
+            struct v4l2_buffer q;
+            memset(&q, 0, sizeof q);
+            q.index = (uint32_t)s->held, q.type = V4L2_BUF_TYPE_VIDEO_CAPTURE, q.memory = V4L2_MEMORY_MMAP;
+            sys_ioctl(s->fd, VIDIOC_QBUF, &q);
+        }
+        s->held = (int)b.index;
+        s->fresh = 1;
+    }
+}
+
+/* ts_us: OUTPUT buffers carry their slot time (the encoder copies it to the coded buffer; rate control may use it). */
+static int enc_queue_buf(struct enc *e, uint32_t type, int i, uint32_t used, int64_t ts_us)
+{
+    struct v4l2_plane p;
+    struct v4l2_buffer b;
+    memset(&p, 0, sizeof p);
+    memset(&b, 0, sizeof b);
+    b.index = (uint32_t)i, b.type = type, b.memory = V4L2_MEMORY_MMAP, b.field = V4L2_FIELD_NONE;
+    b.m.planes = &p, b.length = 1;
+    b.timestamp.tv_sec = (long)(ts_us / 1000000), b.timestamp.tv_usec = (long)(ts_us % 1000000);
+    p.bytesused = used;
+    p.length = type == V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE ? e->out_len[i] : e->cap_len[i];
+    return sys_ioctl(e->fd, VIDIOC_QBUF, &b);
+}
+
+static int enc_open(struct enc *e, const char *path, int w, int h, int fps, const struct opts *o)
+{
+    e->fd = sys_open(path, O_RDWR | O_NONBLOCK | O_CLOEXEC);
+    if (e->fd < 0) return fail(4, "open encoder", e->fd);
+    if (!enc_caps_ok(v4l2_caps(e->fd))) return fail(4, "encoder capabilities", -EINVAL);
+
+    /* dev-encoder.rst "Initialization": the coded format first, then the raw format. */
+    struct v4l2_format f;
+    memset(&f, 0, sizeof f);
+    f.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+    f.fmt.pix_mp.pixelformat = V4L2_PIX_FMT_H264;
+    f.fmt.pix_mp.width = (uint32_t)w, f.fmt.pix_mp.height = (uint32_t)h, f.fmt.pix_mp.num_planes = 1;
+    int r = sys_ioctl(e->fd, VIDIOC_S_FMT, &f);
+    if (r < 0) return fail(4, "encoder VIDIOC_S_FMT (H264)", r);
+    if (f.fmt.pix_mp.pixelformat != V4L2_PIX_FMT_H264) {
+        msg("encoder refused H264");
+        return 4;
+    }
+    e->cap_size = f.fmt.pix_mp.plane_fmt[0].sizeimage;
+
+    memset(&f, 0, sizeof f);
+    f.type = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE;
+    f.fmt.pix_mp.pixelformat = V4L2_PIX_FMT_NV12;
+    f.fmt.pix_mp.width = (uint32_t)w, f.fmt.pix_mp.height = (uint32_t)h, f.fmt.pix_mp.num_planes = 1;
+    f.fmt.pix_mp.field = V4L2_FIELD_NONE;
+    f.fmt.pix_mp.colorspace = V4L2_COLORSPACE_REC709, f.fmt.pix_mp.ycbcr_enc = V4L2_YCBCR_ENC_709;
+    f.fmt.pix_mp.quantization = V4L2_QUANTIZATION_LIM_RANGE, f.fmt.pix_mp.xfer_func = V4L2_XFER_FUNC_709;
+    r = sys_ioctl(e->fd, VIDIOC_S_FMT, &f);
+    if (r < 0) return fail(4, "encoder VIDIOC_S_FMT (NV12)", r);
+    if (f.fmt.pix_mp.pixelformat != V4L2_PIX_FMT_NV12 || f.fmt.pix_mp.num_planes != 1)
+    {
+        msg("encoder refused single-plane NV12");
+        return 4;
+    }
+    e->stride = (int)f.fmt.pix_mp.plane_fmt[0].bytesperline;
+    e->hpad = (int)f.fmt.pix_mp.height;
+    e->out_size = f.fmt.pix_mp.plane_fmt[0].sizeimage;
+    if (e->stride < w || e->hpad < h || (uint64_t)e->stride * e->hpad * 3 / 2 > e->out_size)
+        return fail(4, "encoder NV12 layout", -EINVAL);
+
+    /* Visible rectangle (the padded height is not picture). The selection API takes the single-planar type. */
+    struct v4l2_selection sel;
+    memset(&sel, 0, sizeof sel);
+    sel.type = V4L2_BUF_TYPE_VIDEO_OUTPUT, sel.target = V4L2_SEL_TGT_CROP;
+    sel.r.width = (uint32_t)w, sel.r.height = (uint32_t)h;
+    r = sys_ioctl(e->fd, VIDIOC_S_SELECTION, &sel);
+    if (r < 0) {
+        sel.type = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE;
+        sel.r.left = sel.r.top = 0, sel.r.width = (uint32_t)w, sel.r.height = (uint32_t)h;
+        r = sys_ioctl(e->fd, VIDIOC_S_SELECTION, &sel);
+    }
+    if (r < 0) {
+        memset(&sel, 0, sizeof sel);
+        sel.type = V4L2_BUF_TYPE_VIDEO_OUTPUT, sel.target = V4L2_SEL_TGT_CROP;
+        int g = sys_ioctl(e->fd, VIDIOC_G_SELECTION, &sel);
+        if (g < 0 || sel.r.left || sel.r.top || sel.r.width != (uint32_t)w || sel.r.height != (uint32_t)h)
+            return fail(4, "encoder VIDIOC_S_SELECTION", r);
+        msg_err("warning: VIDIOC_S_SELECTION (crop already right)", r);
+    }
+
+    struct v4l2_streamparm parm;
+    memset(&parm, 0, sizeof parm);
+    parm.type = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE;
+    parm.parm.output.timeperframe.numerator = 1, parm.parm.output.timeperframe.denominator = (uint32_t)fps;
+    r = sys_ioctl(e->fd, VIDIOC_S_PARM, &parm);
+    if (r < 0) msg_err("warning: VIDIOC_S_PARM", r);
+
+    set_ctrl(e->fd, V4L2_CID_MPEG_VIDEO_H264_PROFILE, V4L2_MPEG_VIDEO_H264_PROFILE_HIGH, "H264_PROFILE", 0);
+    /* --peak above the bitrate = VBR up to that peak (head turns get the bits they need; CBR blurred them), else CBR */
+    long peak = o->peak > o->bitrate ? o->peak : o->bitrate;
+    set_ctrl(e->fd, V4L2_CID_MPEG_VIDEO_H264_LEVEL, pick_level(w, h, fps, peak), "H264_LEVEL", 0);
+    set_ctrl(e->fd, V4L2_CID_MPEG_VIDEO_BITRATE_MODE,
+             peak > o->bitrate ? V4L2_MPEG_VIDEO_BITRATE_MODE_VBR : V4L2_MPEG_VIDEO_BITRATE_MODE_CBR, "BITRATE_MODE", 0);
+    set_ctrl(e->fd, V4L2_CID_MPEG_VIDEO_BITRATE, (int32_t)o->bitrate, "BITRATE", 0);
+    set_ctrl(e->fd, V4L2_CID_MPEG_VIDEO_BITRATE_PEAK, (int32_t)peak, "BITRATE_PEAK", 0);
+    set_ctrl(e->fd, V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE, 1, "FRAME_RC_ENABLE", 0);
+    set_ctrl(e->fd, V4L2_CID_MPEG_VIDEO_B_FRAMES, 0, "B_FRAMES", 0);
+    set_ctrl(e->fd, V4L2_CID_MPEG_VIDEO_GOP_SIZE, (int32_t)(fps * o->gop_seconds), "GOP_SIZE", 0);
+    set_ctrl(e->fd, V4L2_CID_MPEG_VIDEO_HEADER_MODE, V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME, "HEADER_MODE", 0);
+    set_ctrl(e->fd, V4L2_CID_MPEG_VIDEO_PREPEND_SPSPPS_TO_IDR, 1, "PREPEND_SPSPPS_TO_IDR", 0);
+    set_ctrl(e->fd, V4L2_CID_MPEG_VIDEO_FRAME_SKIP_MODE, V4L2_MPEG_VIDEO_FRAME_SKIP_MODE_DISABLED, "FRAME_SKIP_MODE", 0);
+
+    for (int q = 0; q < 2; q++) {
+        uint32_t type = q ? V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE : V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE;
+        struct v4l2_requestbuffers rb;
+        memset(&rb, 0, sizeof rb);
+        rb.count = ENC_BUFS, rb.type = type, rb.memory = V4L2_MEMORY_MMAP;
+        r = sys_ioctl(e->fd, VIDIOC_REQBUFS, &rb);
+        if (r < 0 || rb.count < ENC_BUFS) return fail(4, "encoder VIDIOC_REQBUFS", r < 0 ? r : -ENOMEM);
+        for (int i = 0; i < ENC_BUFS; i++) {
+            struct v4l2_plane p;
+            struct v4l2_buffer b;
+            memset(&p, 0, sizeof p);
+            memset(&b, 0, sizeof b);
+            b.index = (uint32_t)i, b.type = type, b.memory = V4L2_MEMORY_MMAP, b.m.planes = &p, b.length = 1;
+            r = sys_ioctl(e->fd, VIDIOC_QUERYBUF, &b);
+            if (r < 0) return fail(4, "encoder VIDIOC_QUERYBUF", r);
+            uint8_t *m = sys_mmap(0, p.length, q ? PROT_READ : PROT_READ | PROT_WRITE, MAP_SHARED, e->fd, p.m.mem_offset);
+            if (mmap_failed(m)) return fail(4, "encoder mmap", (long)m);
+            if (q) {
+                e->cap_mem[i] = m, e->cap_len[i] = p.length;
+            } else {
+                if (p.length < e->out_size) return fail(4, "encoder OUTPUT buffer size", -EINVAL);
+                e->out_mem[i] = m, e->out_len[i] = p.length, e->out_free[i] = 1;
+                /* Black, including the padding rows the encoder may read. */
+                memset(m, 16, (size_t)e->stride * e->hpad);
+                memset(m + (size_t)e->stride * e->hpad, 128, (size_t)e->stride * e->hpad / 2);
+            }
+        }
+    }
+    return 0;
+}
+
+/* ---------------------------------------------------------------- streaming */
+
+/* Counters since the start; the timing part (per stats window, reset after each line) says where a slow loop's time
+ * goes: converting pictures, writing coded frames to stdout (ffmpeg not draining the pipe), or waiting for the
+ * encoder to free an OUTPUT buffer. */
+struct stats {
+    long frames, repeats, late, skipped, errors;
+    uint64_t bytes;
+    int64_t conv_ns, conv_max, write_ns, write_max;
+    long convs, writes, nobuf;
+};
+
+/* Dequeue finished OUTPUT buffers (free again) and coded CAPTURE buffers (written to stdout, re-queued).
+ * Returns 1 when the encoder signalled the last buffer, -1 when stdout is gone, else 0. */
+static int enc_reap(struct enc *e, struct stats *st)
+{
+    for (;;) {
+        struct v4l2_plane p;
+        struct v4l2_buffer b;
+        memset(&p, 0, sizeof p);
+        memset(&b, 0, sizeof b);
+        b.type = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE, b.memory = V4L2_MEMORY_MMAP, b.m.planes = &p, b.length = 1;
+        if (sys_ioctl(e->fd, VIDIOC_DQBUF, &b) < 0) break;
+        if (b.index < ENC_BUFS) e->out_free[b.index] = 1;
+    }
+    for (;;) {
+        struct v4l2_plane p;
+        struct v4l2_buffer b;
+        memset(&p, 0, sizeof p);
+        memset(&b, 0, sizeof b);
+        b.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE, b.memory = V4L2_MEMORY_MMAP, b.m.planes = &p, b.length = 1;
+        int r = sys_ioctl(e->fd, VIDIOC_DQBUF, &b);
+        if (r == -EPIPE) return 1;   /* the last buffer was already dequeued (dev-encoder.rst "Drain") */
+        if (r < 0 || b.index >= ENC_BUFS) return 0;
+        int last = (b.flags & V4L2_BUF_FLAG_LAST) != 0;
+        if (b.flags & V4L2_BUF_FLAG_ERROR) {
+            st->errors++;
+        } else if (p.bytesused > p.data_offset && p.bytesused <= e->cap_len[b.index]) {
+            uint32_t n = p.bytesused - p.data_offset;
+            int64_t tw = now_ns();
+            if (out_all(e->cap_mem[b.index] + p.data_offset, n) < 0) return -1;
+            tw = now_ns() - tw;
+            st->write_ns += tw, st->writes++;
+            if (tw > st->write_max) st->write_max = tw;
+            st->bytes += n;
+        }
+        if (last) return 1;
+        enc_queue_buf(e, V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE, (int)b.index, 0, 0);
+    }
+}
+
+static void drain_and_close(struct enc *e, struct src *s, struct stats *st)
+{
+    struct v4l2_encoder_cmd cmd;
+    memset(&cmd, 0, sizeof cmd);
+    cmd.cmd = V4L2_ENC_CMD_STOP;
+    if (sys_ioctl(e->fd, VIDIOC_ENCODER_CMD, &cmd) == 0) {
+        int64_t end = now_ns() + 1000000000;
+        for (;;) {
+            if (enc_reap(e, st) != 0) break;
+            int64_t left = end - now_ns();
+            if (left <= 0) break;
+            struct timespec ts = {left / 1000000000, left % 1000000000};
+            struct pollfd_k f = {e->fd, POLLIN, 0};
+            sys_ppoll(&f, 1, &ts);
+        }
+    }
+    uint32_t t = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE;
+    sys_ioctl(e->fd, VIDIOC_STREAMOFF, &t);
+    t = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+    sys_ioctl(e->fd, VIDIOC_STREAMOFF, &t);
+    t = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+    sys_ioctl(s->fd, VIDIOC_STREAMOFF, &t);
+    sys_close(e->fd);
+    sys_close(s->fd);
+}
+
+static void info_json(struct line *l, const char *enc, const char *srcp, const struct src *s, int ow, int oh,
+                      int refresh, int fps, long bitrate)
+{
+    ls(l, "{\"encoder\":\""), ls(l, enc), ls(l, "\",\"source\":\""), ls(l, srcp);
+    ls(l, "\",\"src\":["), ln(l, s->w), ls(l, ","), ln(l, s->h), ls(l, "],\"out\":["), ln(l, ow), ls(l, ","), ln(l, oh);
+    ls(l, "],\"refresh\":"), ln(l, refresh), ls(l, ",\"fps\":"), ln(l, fps), ls(l, ",\"bitrate\":"), ln(l, bitrate);
+    ls(l, "}\n");
+}
+
+static void stats_line(struct stats *st, int64_t elapsed)
+{
+    struct line l = {.n = 0};
+    ls(&l, TAG "stats frames="), ln(&l, st->frames), ls(&l, " repeats="), ln(&l, st->repeats);
+    ls(&l, " late="), ln(&l, st->late), ls(&l, " skipped="), ln(&l, st->skipped);
+    ls(&l, " kbps="), ln(&l, elapsed > 0 ? (long)(st->bytes * 8 * 1000000 / (uint64_t)elapsed) : 0);
+    if (st->errors) ls(&l, " errors="), ln(&l, st->errors);
+    /* this window: average/max ms per conversion and per stdout write, slots that found no free OUTPUT buffer */
+    ls(&l, " convert_ms="), lms(&l, st->convs ? st->conv_ns / st->convs : 0), ls(&l, "/"), lms(&l, st->conv_max);
+    ls(&l, " write_ms="), lms(&l, st->writes ? st->write_ns / st->writes : 0), ls(&l, "/"), lms(&l, st->write_max);
+    ls(&l, " no_buffer="), ln(&l, st->nobuf);
+    ls(&l, "\n");
+    write_all(2, l.b, (size_t)l.n);
+    st->conv_ns = st->conv_max = st->write_ns = st->write_max = 0;
+    st->convs = st->writes = st->nobuf = 0;
+}
+
+int main(int argc, char **argv, char **envp)
+{
+    struct opts o;
+    if (!parse_args(argc, argv, &o)) {
+        msg("usage: fp_venc [--height N] [--bitrate BPS] [--peak BPS] [--fps N] [--max-fps N] [--gop-seconds N] "
+            "[--source PATH] [--encoder PATH] [--probe | --selftest]");
+        return 2;
+    }
+    if (o.selftest) return selftest();
+    const char *dis = getenv_(envp, "FP_VENC_DISABLE");
+    if (dis && str_eq(dis, "1")) {
+        msg("hardware encoder disabled (FP_VENC_DISABLE=1)");
+        return 4;
+    }
+
+    char src_path[256], enc_path[256];
+    if (o.source) {
+        if (str_len(o.source) >= sizeof src_path) return 2;
+        memcpy(src_path, o.source, str_len(o.source) + 1);
+    } else if (!find_source(src_path)) {
+        msg("no SteamVR headset view device (/sys/class/video4linux/*/name == SteamVR)");
+        return 3;
+    }
+    struct src s;
+    int r = src_open(&s, src_path);
+    if (r) return r;
+
+    if (o.encoder) {
+        if (str_len(o.encoder) >= sizeof enc_path) return 2;
+        memcpy(enc_path, o.encoder, str_len(o.encoder) + 1);
+    } else if (!find_encoder(enc_path)) {
+        msg("no V4L2 hardware encoder found");
+        return 4;
+    }
+
+    int ow, oh;
+    fp_out_size(s.w, s.h, (int)o.height, &ow, &oh);
+    int refresh = panel_refresh();
+    int fps = (int)o.fps;
+    if (!fps) {
+        if (refresh > 0) {
+            int d = (refresh + (int)o.max_fps - 1) / (int)o.max_fps;
+            fps = (refresh + d / 2) / d;
+        } else {
+            fps = 30;
+        }
+    }
+
+    struct enc e;
+    memset(&e, 0, sizeof e);
+    r = enc_open(&e, enc_path, ow, oh, fps, &o);
+    if (r) return r;
+
+    struct line info = {.n = 0};
+    info_json(&info, enc_path, src_path, &s, ow, oh, refresh, fps, o.bitrate);
+    if (o.probe) {
+        write_all(1, info.b, (size_t)info.n);
+        sys_close(e.fd);
+        sys_close(s.fd);
+        return 0;
+    }
+    struct line il = {.n = 0};
+    ls(&il, TAG "info "), ls(&il, info.b);
+    write_all(2, il.b, (size_t)il.n);
+
+    void *scratch = alloc(fp_scratch_size(s.w, s.h, ow, oh));
+    if (!scratch) return fail(4, "scratch memory", -ENOMEM);
+
+    /* Ignore SIGPIPE: a closed stdout becomes EPIPE from write() and we stop quietly. */
+    struct { void *handler; unsigned long flags; void *restorer; uint64_t mask; } sa = {(void *)1, 0, 0, 0};
+    sys6(__NR_rt_sigaction, 13 /* SIGPIPE */, (long)&sa, 0, 8, 0, 0);
+
+    for (int i = 0; i < ENC_BUFS; i++)
+        if ((r = enc_queue_buf(&e, V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE, i, 0, 0)) < 0) return fail(4, "encoder QBUF", r);
+    uint32_t t = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE;
+    if ((r = sys_ioctl(e.fd, VIDIOC_STREAMON, &t)) < 0) return fail(4, "encoder STREAMON (OUTPUT)", r);
+    t = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+    if ((r = sys_ioctl(e.fd, VIDIOC_STREAMON, &t)) < 0) return fail(4, "encoder STREAMON (CAPTURE)", r);
+    t = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+    if ((r = sys_ioctl(s.fd, VIDIOC_STREAMON, &t)) < 0) return fail(3, "source STREAMON", r);
+
+    struct stats st = {0};
+    const int64_t t0 = now_ns(), period = 1000000000 / fps;
+    int64_t next_stats = t0 + 10000000000LL, quiet_src = 0, quiet_enc = 0;
+    long slot = 0;                 /* next slot to submit; due at t0 + slot * 1e9 / fps */
+    long pic = 0;                  /* current picture: 0 = black (no source frame yet), +1 per new source frame */
+    for (int i = 0; i < ENC_BUFS; i++) e.out_pic[i] = -1;
+    int want_key = 0, stdin_open = 1, sent_any = 0, rc = 0;
+
+    for (;;) {
+        int64_t now = now_ns();
+        long due_upto = (long)((now - t0) * fps / 1000000000);   /* last slot whose time has come */
+        if (due_upto - slot + 1 > fps) {   /* > 1 s behind (e.g. SIGSTOP): don't replay it all */
+            say("fell behind; skipping slots: ", 0, due_upto - slot, 1);
+            st.skipped += due_upto - slot;
+            slot = due_upto;
+        }
+        /* Submit every due slot for which an OUTPUT buffer is free. */
+        while (slot <= due_upto) {
+            int i = 0;
+            while (i < ENC_BUFS && !e.out_free[i]) i++;
+            if (i == ENC_BUFS) {
+                st.nobuf++;
+                break;
+            }
+            uint8_t *m = e.out_mem[i];
+            if (s.held >= 0 && s.fresh) pic++;
+            if (e.out_pic[i] != pic) {
+                if (s.held >= 0) {
+                    int64_t tc = now_ns();
+                    fp_convert(s.mem[s.held], s.w, s.h, s.stride, m, e.stride, m + (size_t)e.stride * e.hpad,
+                               e.stride, ow, oh, scratch);
+                    tc = now_ns() - tc;
+                    st.conv_ns += tc, st.convs++;
+                    if (tc > st.conv_max) st.conv_max = tc;
+                } else {   /* no source frame yet: black */
+                    memset(m, 16, (size_t)e.stride * oh);
+                    memset(m + (size_t)e.stride * e.hpad, 128, (size_t)e.stride * oh / 2);
+                }
+                e.out_pic[i] = pic;
+            }
+            if (!s.fresh && sent_any) st.repeats++;
+            s.fresh = 0;
+            if (want_key) set_ctrl(e.fd, V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME, 1, "FORCE_KEY_FRAME", 0), want_key = 0;
+            if ((r = enc_queue_buf(&e, V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE, i, e.out_size, slot * 1000000 / fps)) < 0) {
+                rc = fail(1, "encoder QBUF (OUTPUT)", r);
+                goto stop;
+            }
+            e.out_free[i] = 0;
+            if (now_ns() >= t0 + (slot + 1) * 1000000000 / fps) st.late++;
+            st.frames++, slot++, sent_any = 1;
+        }
+        if (now >= next_stats) {
+            stats_line(&st, now - t0);
+            next_stats += 10000000000LL;
+        }
+
+        /* Wait for the next slot, a source frame, encoder progress or a stdin command. If a slot is already due we
+         * are waiting for a free OUTPUT buffer: the encoder fd's POLLOUT wakes us. */
+        int64_t wait = slot <= due_upto ? period : t0 + slot * 1000000000 / fps - now;
+        if (wait < 0) wait = 0;
+        struct pollfd_k f[3];
+        int nf = 0, isrc = -1, ienc = -1, iin = -1;
+        if (now >= quiet_src) isrc = nf, f[nf++] = (struct pollfd_k){s.fd, POLLIN, 0};
+        if (now >= quiet_enc) ienc = nf, f[nf++] = (struct pollfd_k){e.fd, POLLIN | POLLOUT, 0};
+        if (stdin_open) iin = nf, f[nf++] = (struct pollfd_k){0, POLLIN, 0};
+        /* An fd left out after an error comes back when its quiet time ends. */
+        if (now < quiet_src && quiet_src - now < wait) wait = quiet_src - now;
+        if (now < quiet_enc && quiet_enc - now < wait) wait = quiet_enc - now;
+        struct timespec ts = {wait / 1000000000, wait % 1000000000};
+        int n = sys_ppoll(f, (unsigned)nf, &ts);
+        if (n < 0 && n != -EINTR) {
+            rc = fail(1, "ppoll", n);
+            goto stop;
+        }
+        if (n <= 0) continue;
+        if (isrc >= 0 && f[isrc].revents) {
+            int had = s.held;
+            int was_fresh = s.fresh;
+            src_drain(&s);
+            /* POLLERR without a frame (e.g. the writer is gone): don't spin on it, look again in 100 ms. */
+            if ((f[isrc].revents & (POLLERR | POLLHUP | POLLNVAL)) && s.held == had && s.fresh == was_fresh)
+                quiet_src = now + 100000000;
+        }
+        if (ienc >= 0 && f[ienc].revents) {
+            int k = enc_reap(&e, &st);
+            if (k < 0) goto stop_quiet;
+            if (k > 0) {
+                rc = fail(1, "encoder stopped unexpectedly", -EIO);
+                goto stop;
+            }
+            if (f[ienc].revents & (POLLERR | POLLNVAL)) quiet_enc = now + 2000000;
+        }
+        if (iin >= 0 && f[iin].revents) {
+            if (f[iin].revents & POLLNVAL) {
+                stdin_open = 0;
+            } else {
+                char cmd[64];
+                long got = sys_read(0, cmd, sizeof cmd);
+                if (got == 0) goto stop;            /* EOF: the PC side closed the channel */
+                for (long k = 0; k < got; k++) {
+                    if (cmd[k] == 'k') want_key = 1;
+                    if (cmd[k] == 'q') goto stop;
+                }
+            }
+        }
+    }
+
+stop:
+    drain_and_close(&e, &s, &st);
+    stats_line(&st, now_ns() - t0);
+    return rc;
+stop_quiet:   /* stdout is gone: nothing left to drain into */
+    {
+        uint32_t ty = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE;
+        sys_ioctl(e.fd, VIDIOC_STREAMOFF, &ty);
+        ty = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+        sys_ioctl(e.fd, VIDIOC_STREAMOFF, &ty);
+        sys_close(e.fd);
+        sys_close(s.fd);
+    }
+    return 0;
+}

native/venc/include/sys/time.h

@@ -0,0 +1,17 @@
+/* Minimal stand-in for libc's <sys/time.h>: linux/videodev2.h includes it for struct timeval (v4l2_buffer) and
+ * struct timespec (v4l2_event). There is no libc at build time (fp_venc is freestanding), so the two structs are
+ * declared here with the aarch64 Linux layout (two 64-bit longs each). */
+#ifndef FP_VENC_SYS_TIME_H
+#define FP_VENC_SYS_TIME_H
+
+struct timeval {
+    long tv_sec;
+    long tv_usec;
+};
+
+struct timespec {
+    long tv_sec;
+    long tv_nsec;
+};
+
+#endif

native/venc/sys.c

@@ -0,0 +1,131 @@
+/* Process entry and the few libc pieces fp_venc needs (see sys.h). */
+#include "sys.h"
+
+/* The kernel starts us with sp -> argc, argv[0..argc-1], NULL, envp..., NULL (16-byte aligned). Clear the frame
+ * pointer and link register so backtraces end here, then hand sp to C. */
+__asm__(".text\n"
+        ".global _start\n"
+        ".type _start,%function\n"
+        "_start:\n"
+        "  mov x29, #0\n"
+        "  mov x30, #0\n"
+        "  mov x0, sp\n"
+        "  bl start_c\n"
+        "  brk #0\n");
+
+__attribute__((noreturn, used)) void start_c(long *sp)
+{
+    int argc = (int)sp[0];
+    char **argv = (char **)(sp + 1);
+    char **envp = argv + argc + 1;
+    sys_exit(main(argc, argv, envp));
+}
+
+/* The compiler may emit calls to these for struct copies/zeroing. Byte loops are enough: the hot paths (picture
+ * conversion) never use them. -ffreestanding/-fno-builtin keep clang from turning these loops back into calls. */
+void *memcpy(void *d, const void *s, size_t n)
+{
+    unsigned char *dp = d;
+    const unsigned char *sp = s;
+    while (n--) *dp++ = *sp++;
+    return d;
+}
+
+void *memset(void *d, int c, size_t n)
+{
+    unsigned char *dp = d;
+    while (n--) *dp++ = (unsigned char)c;
+    return d;
+}
+
+void *memmove(void *d, const void *s, size_t n)
+{
+    unsigned char *dp = d;
+    const unsigned char *sp = s;
+    if (dp < sp) {
+        while (n--) *dp++ = *sp++;
+    } else {
+        while (n--) dp[n] = sp[n];
+    }
+    return d;
+}
+
+size_t str_len(const char *s)
+{
+    size_t n = 0;
+    while (s[n]) n++;
+    return n;
+}
+
+int str_eq(const char *a, const char *b)
+{
+    while (*a && *a == *b) a++, b++;
+    return *a == *b;
+}
+
+int str_contains(const char *hay, const char *needle)
+{
+    size_t n = str_len(needle);
+    for (; *hay; hay++) {
+        size_t i = 0;
+        while (i < n && hay[i] == needle[i]) i++;
+        if (i == n) return 1;
+    }
+    return n == 0;
+}
+
+int parse_uint(const char *s, long *out)
+{
+    long v = 0;
+    if (!s || !*s) return 0;
+    for (; *s; s++) {
+        if (*s < '0' || *s > '9') return 0;
+        v = v * 10 + (*s - '0');
+        if (v > 0x7fffffffL) return 0;
+    }
+    *out = v;
+    return 1;
+}
+
+int64_t now_ns(void)
+{
+    struct timespec ts = {0, 0};
+    sys_clock_gettime(1 /* CLOCK_MONOTONIC */, &ts);
+    return (int64_t)ts.tv_sec * 1000000000 + ts.tv_nsec;
+}
+
+void write_all(int fd, const void *b, size_t n)
+{
+    const char *p = b;
+    while (n) {
+        long r = sys_write(fd, p, n);
+        if (r == -EINTR || r == -EAGAIN) continue;
+        if (r <= 0) return;
+        p += r;
+        n -= (size_t)r;
+    }
+}
+
+void ls(struct line *l, const char *s)
+{
+    while (*s && l->n < (int)sizeof(l->b) - 1) l->b[l->n++] = *s++;
+}
+
+void ln(struct line *l, long v)
+{
+    char t[24];
+    int i = 0;
+    unsigned long u = v < 0 ? 0UL - (unsigned long)v : (unsigned long)v;
+    if (v < 0) ls(l, "-");
+    do t[i++] = (char)('0' + u % 10); while ((u /= 10) && i < 23);
+    while (i && l->n < (int)sizeof(l->b) - 1) l->b[l->n++] = t[--i];
+}
+
+void lms(struct line *l, int64_t ns)
+{
+    int64_t us = ns / 1000;
+    ln(l, (long)(us / 1000));
+    ls(l, ".");
+    ls(l, us % 1000 < 100 ? (us % 1000 < 10 ? "00" : "0") : "");
+    ln(l, (long)(us % 1000));
+}

native/venc/sys.h

@@ -0,0 +1,81 @@
+/* fp_venc's whole "libc": raw aarch64 Linux syscalls plus a few helpers. The program is fully static and
+ * freestanding (no libc exists at build time), so everything it needs from the kernel goes through svc #0 here. */
+#ifndef FP_VENC_SYS_H
+#define FP_VENC_SYS_H
+
+#include <stdint.h>
+#include <stddef.h>
+#include <sys/time.h>        /* our stub: struct timespec */
+#include <asm/unistd.h>      /* syscall numbers (asm-generic table) */
+#include <asm/errno.h>
+
+/* open flags (asm-generic values, used by aarch64). Bionic's copy of linux/fcntl.h pulls in libc's bits/ headers, so
+ * the few we need are spelled out here. */
+#define O_RDONLY 00
+#define O_RDWR 02
+#define O_NONBLOCK 04000
+#define O_CLOEXEC 02000000
+#define AT_FDCWD (-100)
+#include <linux/mman.h>      /* PROT_*, MAP_* */
+#include <linux/poll.h>      /* POLL* */
+
+/* Syscalls return the kernel's value: >= 0 success, -errno failure. */
+static inline long sys6(long n, long a, long b, long c, long d, long e, long f)
+{
+    register long x8 __asm__("x8") = n;
+    register long x0 __asm__("x0") = a;
+    register long x1 __asm__("x1") = b;
+    register long x2 __asm__("x2") = c;
+    register long x3 __asm__("x3") = d;
+    register long x4 __asm__("x4") = e;
+    register long x5 __asm__("x5") = f;
+    __asm__ volatile("svc #0" : "+r"(x0) : "r"(x8), "r"(x1), "r"(x2), "r"(x3), "r"(x4), "r"(x5) : "memory", "cc");
+    return x0;
+}
+
+struct pollfd_k { int fd; short events; short revents; };   /* struct pollfd (not in the UAPI headers) */
+
+static inline long sys_read(int fd, void *b, size_t n) { return sys6(__NR_read, fd, (long)b, (long)n, 0, 0, 0); }
+static inline long sys_write(int fd, const void *b, size_t n) { return sys6(__NR_write, fd, (long)b, (long)n, 0, 0, 0); }
+static inline int sys_open(const char *p, int flags) { return (int)sys6(__NR_openat, AT_FDCWD, (long)p, flags, 0, 0, 0); }
+static inline int sys_close(int fd) { return (int)sys6(__NR_close, fd, 0, 0, 0, 0, 0); }
+static inline int sys_ioctl(int fd, unsigned long req, void *arg) { return (int)sys6(__NR_ioctl, fd, (long)req, (long)arg, 0, 0, 0); }
+static inline long sys_readlink(const char *p, char *b, size_t n) { return sys6(__NR_readlinkat, AT_FDCWD, (long)p, (long)b, (long)n, 0, 0); }
+static inline void *sys_mmap(void *a, size_t len, int prot, int flags, int fd, long off)
+{
+    return (void *)sys6(__NR_mmap, (long)a, (long)len, prot, flags, fd, off);
+}
+static inline int sys_munmap(void *a, size_t len) { return (int)sys6(__NR_munmap, (long)a, (long)len, 0, 0, 0, 0); }
+static inline int sys_ppoll(struct pollfd_k *f, unsigned n, const struct timespec *ts)
+{
+    return (int)sys6(__NR_ppoll, (long)f, n, (long)ts, 0, 8, 0);
+}
+static inline int sys_clock_gettime(int clk, struct timespec *ts) { return (int)sys6(__NR_clock_gettime, clk, (long)ts, 0, 0, 0, 0); }
+__attribute__((noreturn)) static inline void sys_exit(int code)
+{
+    for (;;) sys6(__NR_exit_group, code, 0, 0, 0, 0, 0);
+}
+
+/* mmap returns -errno in the pointer on failure. */
+static inline int mmap_failed(void *p) { return (unsigned long)p > (unsigned long)-4096; }
+
+/* Helpers (sys.c). */
+void *memcpy(void *d, const void *s, size_t n);
+void *memset(void *d, int c, size_t n);
+void *memmove(void *d, const void *s, size_t n);
+size_t str_len(const char *s);
+int str_eq(const char *a, const char *b);
+int str_contains(const char *hay, const char *needle);
+int parse_uint(const char *s, long *out);          /* plain decimal, 0..2^31-1; 1 = ok */
+int64_t now_ns(void);                               /* CLOCK_MONOTONIC */
+void write_all(int fd, const void *b, size_t n);   /* best effort (stderr) */
+
+/* A small line builder for stderr/JSON output: no printf here. */
+struct line { char b[600]; int n; };
+void ls(struct line *l, const char *s);
+void ln(struct line *l, long v);
+void lms(struct line *l, int64_t ns);               /* nanoseconds as "<ms>.<3 digits>" */
+
+int main(int argc, char **argv, char **envp);
+
+#endif

scripts/ui_smoke.py

@@ -152,6 +152,40 @@ class FakeTarget:
                         "apk_present": True, "recipe": None, "exe": g.get("exe"),
                         "missing_libraries": ["libwebkit2gtk-4.1.so.0"]}
                        for g in library.games() if g.get("kind") == "linux" and g["package"] == LINUX_APPIMAGE]
+        # GitHub #90: most games on internal storage, the second one on a microSD card
+        sd = {"internal": False, "path": "/run/media/steamos/SD Card", "label": "SD Card"}
+        for i, g in enumerate(self.games):
+            g["drive"] = sd if i == 1 else {"internal": True, "path": "/home/steamos", "label": "Internal storage"}
+            g["drive_missing"] = False
+
+    def drives(self) -> list[dict]:
+        sd_games = sum(1 for g in self.games if not g["drive"]["internal"])
+        return [{"id": "internal", "path": "/home/steamos", "install_dir": "/home/steamos/Applications/quest-frame",
+                 "label": "Internal storage", "fstype": "ext4", "internal": True, "removable": False,
+                 "free_bytes": 312 * 2**30, "total_bytes": 460 * 2**30, "usable": True, "reason": "",
+                 "games": len(self.games) - sd_games},
+                {"id": "/run/media/steamos/SD Card", "path": "/run/media/steamos/SD Card",
+                 "install_dir": "/run/media/steamos/SD Card/FramePort", "label": "SD Card", "fstype": "ext4",
+                 "internal": False, "removable": True, "free_bytes": 187 * 2**30, "total_bytes": 238 * 2**30,
+                 "usable": True, "reason": "", "games": sd_games},
+                {"id": "/run/media/steamos/USB", "path": "/run/media/steamos/USB", "install_dir":
+                 "/run/media/steamos/USB/FramePort", "label": "USB", "fstype": "exfat", "internal": False,
+                 "removable": True, "free_bytes": 50 * 2**30, "total_bytes": 64 * 2**30, "usable": False,
+                 "reason": "exfat can't hold game data (no Unix permissions or symlinks); format the drive in "
+                           "SteamOS to install games on it", "games": 0}]
+
+    def move(self, package, dest, reporter) -> dict:
+        reporter.stage("Move game files")
+        for i in range(5):
+            reporter.progress(i / 4, f"Copying {i / 2:.1f}/2.0 GiB")
+            time.sleep(0.5)
+        return {"state": "done", "package": package}
+
+    def set_desktop_entry(self, package, enabled) -> dict:
+        for g in self.games:
+            if g["package"] == package:
+                g["desktop_entry"] = enabled
+        return {"enabled": enabled}
 
     def describe(self) -> dict:
         return {"hostname": "steamframe", "os": "SteamOS", "os_version": "3.8", "build_id": "20260922",
@@ -182,17 +216,107 @@ class FakeKeyboardSession:
         self.closed = True
 
 
-def open_type_dialog(app: FramePortApp) -> None:
-    """Type on Frame over the Steam Frame page, with one key 'pressed' so the screenshot shows it working."""
-    from types import SimpleNamespace
+class FakeMonitorSession:
+    """--fake-frame: the Monitor tab's stream as synthetic samples, one per second, shaped like a real Quest game on
+    the dev Frame (2026-10-07): 72 fps, the game's Android container, SteamVR/Steam as context. Two minutes are sent
+    at once first, so the charts are full in screenshots. GAME = --game (else the library's first game)."""
 
-    app.navigate(1)
-    time.sleep(1.5)
+    GAME: str | None = None
+    BACKFILL = 120
+    # (name, group, CPU %, GPU %, memory); "GAME" = the game's package
+    PROCS = [("GAME", "game", 9.8, 44.0, 1_350_000_000), ("vrcompositor", "steamvr", 1.4, 9.0, 80_000_000),
+             ("system_server", "game", 1.1, 0.0, 296_000_000), ("XRServiceLoopTh", "steamvr", 0.5, 0.0, 433_000_000),
+             ("steamwebhelper", "steam", 0.4, 0.0, 350_000_000), ("com.android.systemui", "game", 0.1, 0.0,
+                                                                   229_000_000),
+             ("surfaceflinger", "game", 0.1, 0.4, 96_000_000), ("audioserver", "game", 0.1, 0.0, 31_000_000),
+             ("com.android.providers.media.module", "game", 0.1, 0.0, 130_000_000),
+             ("com.android.launcher3", "game", 0.0, 0.0, 194_000_000), ("main", "game", 0.0, 0.0, 178_000_000),
+             ("com.android.settings", "game", 0.0, 0.0, 172_000_000),
+             ("com.android.networkstack.process", "game", 0.0, 0.0, 130_000_000),
+             ("android.ext.services", "game", 0.0, 0.0, 111_000_000)] + \
+            [("vrwebhelper", "steamvr", 0.3, 0.0, 160_000_000 + i * 9_000_000) for i in range(4)]
+
+    def __init__(self, frame, on_sample, on_end=None):
+        import math
+
+        self.math, self.closed, self.on_sample = math, False, on_sample
+        self.static = {"agent": 62, "cores": 8, "gpu_max_mhz": 903, "mem_total": 16 * 1024 ** 3, "fan": True,
+                       "clusters": [{"cpus": [0, 1], "max_mhz": 2265}, {"cpus": [2, 3, 4], "max_mhz": 3148},
+                                    {"cpus": [5, 6], "max_mhz": 2956}, {"cpus": [7], "max_mhz": 3052}],
+                       "temp_groups": ["CPU", "GPU", "Memory", "Battery", "NPU", "Power ICs", "Modem", "Camera"]}
+        self.t = 0
+        threading.Thread(target=self._run, daemon=True).start()
+
+    def _sample(self) -> dict:
+        m, t = self.math, self.t
+        wave = lambda a, p, o=0: a * (1 + m.sin(t / p + o)) / 2  # noqa: E731
+        g = library.game(self.GAME) if self.GAME else (library.games() or [None])[0]
+        game = g or {"package": "com.example.game", "title": "Example Game"}
+        pkg = game["package"]
+        procs = [{"pid": 570799 + i * 37, "ppid": 1, "name": pkg if n == "GAME" else n,
+                  "group": f"game:{pkg}" if grp == "game" else grp, "game": pkg if grp == "game" else None,
+                  "cpu": round(c * (0.85 + wave(0.3, 3, i)), 1), "gpu": round(gp * (0.9 + wave(0.2, 5, i)), 1),
+                  "rss": r, "age": 1500 + t, "uid": 1000, "critical": grp in ("steamvr", "steam"), "locked": False,
+                  "context": grp != "game"}
+                 for i, (n, grp, c, gp, r) in enumerate(self.PROCS)]
+        return {
+            "t": time.time() - max(0, self.BACKFILL - t), "dt": 1.0, "self_ms": 11.5,
+            "cpu": {"total": round(15 + wave(4, 4), 1), "cores": [round(4 + wave(30, 3 + i, i), 1) for i in range(8)],
+                    "mhz": [2265, 1996, 1920, 518]},
+            "gpu": {"busy": round(52 + wave(8, 5), 1), "mhz": 903},
+            "mem": {"total": 15.3 * 1024 ** 3, "avail": int((8.3 - wave(0.15, 9)) * 1024 ** 3),
+                    "swap_total": 7.6 * 1024 ** 3, "swap_free": 7.4 * 1024 ** 3},
+            "psi": {"cpu": 1.0, "memory": 0.0, "io": 0.1},
+            "temps": {"CPU": round(48 + wave(1.5, 11), 1), "GPU": round(46.5 + wave(1, 13), 1), "Memory": 47.1,
+                      "Battery": 27.7, "NPU": 47.3, "Power ICs": 37.0, "Modem": 44.2, "Camera": 46.3},
+            "zones": {"CPU": {"cpu7-top": 48.4, "cpu0": 44.0}, "GPU": {"gpuss-0": 46.5}},
+            "fan": 8500 + int(wave(300, 7)),
+            "power": {"system": round(7.3 + wave(0.6, 4), 2), "cpu": 0.85, "gpu": round(1.0 + wave(0.3, 5), 2),
+                      "npu": 0.1},
+            "battery": {"percent": 95, "status": "Discharging", "plugged": False, "draining": True, "watts": -1.96,
+                        "empty_s": 22440},
+            "net": {"wlan0": [int(2000 + wave(4000, 3)), 1000], "wlanap": [0, 0], "usb0": [0, 0]},
+            "games": [{"package": pkg, "title": game.get("title") or pkg, "kind": "quest", "appid": 1,
+                       "elapsed": 1500 + t, "cpu": 9.4, "gpu": round(44 + wave(6, 5), 1), "mem": 3_390_000_000,
+                       "processes": 87, "fps": round(71.6 + wave(0.6, 2) - (9 if t % 41 == 30 else 0), 1),
+                       "frame_ms": 0.0}],
+            "procs": procs, "filter": "game"}
+
+    def _run(self) -> None:
+        for self.t in range(100000):
+            if self.closed:
+                return
+            self.on_sample(self._sample())
+            if self.t >= self.BACKFILL:  # the first two minutes at once (full charts), then one per second
+                time.sleep(1)
+
+    def set_interval(self, s): pass  # noqa: E704
+    def set_filter(self, w): pass  # noqa: E704
+    def pause(self, p): pass  # noqa: E704
+
+    def kill(self, pid, sig="TERM", force=False):
+        return {"ended": True, "pid": pid}
+
+    def end_game(self, package):
+        return {"ended": True, "via": "steam"}
+
+    def close(self):
+        self.closed = True
+
+
+def open_type_tab(app: FramePortApp) -> None:
+    """The Type on Frame tab, with one key 'pressed' so the screenshot shows it working."""
     app.type_on_frame()
     time.sleep(1.5)
-    dialog = [d for d in app.page._dialogs.controls if d.open][-1]
-    listener = dialog.content.controls[1]
-    listener.on_key_down(SimpleNamespace(key="Enter"))
+    app.keyboard_view.press("Enter")
+
+
+def open_monitor_details(app: FramePortApp) -> None:
+    """The Monitor with its details row open."""
+    app.go("monitor")
+    time.sleep(2)
+    if not app.monitor_view.details.visible:
+        app.monitor_view.toggle_details()
 
 
 LINUX_APPIMAGE = "linux.venera"  # --linux's packages
@@ -287,7 +411,11 @@ def main() -> int:
     ap.add_argument("--docs", action="store_true", help="only the screens used in the docs (Library, --game, Frame)")
     ap.add_argument("--gestures", action="store_true", help="with --fake-frame: real mouse drags (drag-select) and "
                     "right-clicks (menus) in Files, Screenshots and the Library; prints what got selected")
+    ap.add_argument("--only", default=None, help="comma-separated step names to keep (e.g. monitor,monitor-details)")
     ap.add_argument("--linux", action="store_true", help="add two pretend arm64 Linux apps and render their pages")
+    ap.add_argument("--links", action="store_true", help="install links: the Add games menu, the paste dialog, the "
+                    "confirmation for a pretend FrameDrop manifest, Settings → Install links and (with --game) the "
+                    "VR / flat window choice")
     args = ap.parse_args()
     if args.linux:
         add_fake_linux_apps()
@@ -302,13 +430,17 @@ 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")),
-             ("live", lambda a: a.go("live")), ("tools", lambda a: a.go("settings"))]
+             ("live", lambda a: a.go("live")), ("keyboard", lambda a: a.go("keyboard")),
+             ("monitor", lambda a: a.go("monitor")), ("monitor-details", open_monitor_details),
+             ("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)))
         steps += [("share-dialog", lambda a: a.share_config_dialog(game)),
                   ("report-dialog", lambda a: (a.page.pop_dialog(), a.report_problem_dialog(game))),
                   ("custom-art-dialog", lambda a: (a.page.pop_dialog(), a.custom_artwork(game)))]
+        if args.fake_frame:  # GitHub #90: the Move to… dialog (drives load in the background)
+            steps.append(("move-dialog", lambda a: (a.page.pop_dialog(), a.move_game(game))))
         # last: the right-click menu stays open over whatever comes next
         steps.append(("library-menu", lambda a: (a.page.pop_dialog(), a.navigate(0), time.sleep(3),
                                                  a.library_view.open_menu(game))))
@@ -323,7 +455,8 @@ def main() -> int:
                                                  for e in a.files_view.entries[1:3]]))
         steps.append(("screenshots", lambda a: a.go("screenshots")))
         steps.append(("screenshot-viewer", lambda a: a.screenshots_view.viewer(0)))
-        steps.append(("type-on-frame", lambda a: (a.page.pop_dialog(), open_type_dialog(a))))
+        steps.append(("type-on-frame", lambda a: (a.page.pop_dialog(), open_type_tab(a))))
+        steps.append(("monitor", lambda a: a.go("monitor")))
         steps.append(("power-confirm", lambda a: (a.page.pop_dialog(), a.frame_power("restart"))))
     mouse: dict[str, callable] = {}  # step name -> mouse actions (Playwright page) after its screenshot
     if args.gestures:
@@ -381,7 +514,47 @@ def main() -> int:
                  ("linux-folder-customize", lambda a: a.open_game(LINUX_FOLDER, advanced=True)),
                  ("linux-change-program", lambda a: a.choose_exe(LINUX_FOLDER)),
                  ("frame", lambda a: (a.page.pop_dialog(), a.navigate(1))),
-                 ("linux-menu", lambda a: (a.navigate(0), time.sleep(3), a.library_view.open_menu(LINUX_APPIMAGE)))]
+                 ("linux-move", lambda a: a.move_game(LINUX_APPIMAGE) if args.fake_frame else None),
+                 ("linux-menu", lambda a: (a.page.pop_dialog(), a.navigate(0), time.sleep(3),
+                                           a.library_view.open_menu(LINUX_APPIMAGE)))]
+    if args.links:
+        from frameport import deeplink
+        from frameport.ui.views import link_dialog
+
+        fake = deeplink.Manifest("Example Game", [
+            deeplink.ManifestFile("https://cdn.example.com/example-game-arm64.apk", "ab" * 32),
+            deeplink.ManifestFile("https://cdn.example.com/main.1.com.example.game.obb")],
+            "https://example.com/example-game.framedrop.json",
+            description="A puzzle adventure across floating islands: build bridges, bend light and find your way home. "
+                        "Room-scale or seated, with smooth or snap turning.",
+            icon="https://example.com/icon.png")
+        sizes = {fake.files[0].url: 412_000_000, fake.files[1].url: 1_900_000_000}
+        from PIL import Image, ImageDraw
+
+        from frameport.core.paths import user_data_dir
+
+        icon = user_data_dir() / "downloads" / "icons" / "smoke-example.png"  # a stand-in for the downloaded icon
+        icon.parent.mkdir(parents=True, exist_ok=True)
+        im = Image.new("RGBA", (256, 256), (0, 0, 0, 0))
+        ImageDraw.Draw(im).rounded_rectangle((8, 8, 248, 248), 48, fill=(124, 92, 255, 255))
+        ImageDraw.Draw(im).ellipse((72, 72, 184, 184), fill=(255, 214, 102, 255))
+        im.save(icon)
+
+        def add_menu(a):
+            a.navigate(0)
+            time.sleep(2)
+        steps = [("library", add_menu),
+                 ("links-paste", lambda a: a.pick_link()),
+                 ("links-confirm", lambda a: (a.page.pop_dialog(), link_dialog._confirm(a, fake, sizes, False, icon))),
+                 ("links-settings", lambda a: (a.page.pop_dialog(), a.go("settings")))]
+        if game:
+            steps.append(("links-display-mode", lambda a: a.open_game(game, advanced=True)))
+        def add_menu_open(page):
+            page.mouse.click(1194, 94)  # Add games (1280-wide viewport)
+            time.sleep(2)
+            page.screenshot(path=str(args.out / "library-add-menu.png"))
+            page.mouse.click(120, 520)  # outside the menu (Flutter's popup ignores Escape)
+        mouse["library"] = add_menu_open  # tall pages: run with e.g. --viewport 1280x3200
     if args.usb_setup:
         def continue_usb(a):
             dialog = [d for d in a.page._dialogs.controls if d.open and type(d).__name__ == "AlertDialog"][-1]
@@ -439,12 +612,17 @@ def main() -> int:
             steps.append(("game-connected", lambda a: a.open_game(game)))
         if not args.no_test:
             steps.append(("launch-test-job", job))
+    if args.only:  # in the order given (e.g. frame-connected,monitor)
+        by_name = dict(steps)
+        steps = [(n, by_name[n]) for n in args.only.split(",") if n in by_name]
     ready, done = threading.Event(), []
 
     if args.fake_frame:  # never reach a real Frame (start-up auto-connect, discovery, the 30 s poll)
-        from frameport.frame import keyboard
+        from frameport.frame import keyboard, monitor
 
         keyboard.KeyboardSession = FakeKeyboardSession
+        monitor.MonitorSession = FakeMonitorSession
+        FakeMonitorSession.GAME = game  # the game card shows --game (with its artwork)
         FramePortApp.connect = lambda self, *a, **k: None
         FramePortApp.refresh_frame = lambda self, *a, **k: None
 

src/frameport/analysis/detect.py

@@ -16,12 +16,67 @@ UNITY_GGM = "assets/bin/Data/globalgamemanagers"
 IL2CPP_METADATA = "assets/bin/Data/Managed/Metadata/global-metadata.dat"
 
 
-def _read_manifest_info(path: Path) -> tuple[str, str, str, str | None]:
+# Android versions by API level (for messages); the Frame's Lepton container runs Android 11 (API 30)
+ANDROID_VERSIONS = {29: "10", 30: "11", 31: "12", 32: "12L", 33: "13", 34: "14", 35: "15", 36: "16", 37: "17"}
+FRAME_API = 30
+# Quest games declare up to API 32 (Quest's Android 12L) and run on the Frame (OVRPort lowers minSdk to 29; they
+# don't call newer Android classes). From API 33 on, apps call Android 13+ classes at start (GitHub #71/#72: minSdk
+# 34, NoClassDefFoundError android/window/OnBackInvokedCallback, NoSuchMethodError VarHandle.storeStoreFence).
+MAX_RUNNABLE_MIN_SDK = 32
+
+
+def android_version(api: int) -> str:
+    """'14' for API 34."""
+    return ANDROID_VERSIONS.get(api, f"API {api}")
+
+
+def too_new_android(min_sdk: int | None) -> bool:
+    """The APK needs a newer Android than the Frame's Lepton (11): it crashes at start on missing Android classes."""
+    return bool(min_sdk) and min_sdk > MAX_RUNNABLE_MIN_SDK
+
+
+TWA_URL_KEY = "android.support.customtabs.trusted.DEFAULT_URL"
+TWA_ACTIVITY = "com.google.androidbrowserhelper.trusted.LauncherActivity"
+UE_OBB_KEY = ".GameActivity.bHasOBBFiles"  # com.epicgames.ue4.… (UE4) / com.epicgames.unreal.… (UE5)
+
+
+def expects_obb(meta: dict) -> bool:
+    """Unreal packaged the game's content as an OBB (expansion file) and opens it at start."""
+    return any(k.endswith(UE_OBB_KEY) and v in (True, "true", "True") for k, v in meta.items())
+
+
+def _read_manifest_info(path: Path):
+    """(package, versionName, label, main activity, pyaxmlparser APK)."""
     from pyaxmlparser import APK
 
     apk = APK(str(path))
     label = apk.application or apk.package
-    return apk.package, apk.version_name or "", label, apk.get_main_activity()
+    return apk.package, apk.version_name or "", label, apk.get_main_activity(), apk
+
+
+def _resolve_string(apk, value) -> str | None:
+    """A meta-data value: the string itself, or a @string/… reference resolved through resources.arsc."""
+    if isinstance(value, str):
+        return value
+    if apk is None or isinstance(value, bool) or not isinstance(value, int):
+        return None
+    try:
+        res = apk.get_android_resources()
+        for _config, v in (res.get_resolved_res_configs(value) if res else ()):
+            if isinstance(v, str) and v:
+                return v
+    except Exception:  # noqa: BLE001 - a broken resource table only loses the URL
+        pass
+    return None
+
+
+def web_wrapper(meta: dict, manifest_strings: list[str], apk=None) -> dict | None:
+    """A Trusted Web Activity (Bubblewrap, Meta's PWA packaging): the APK only opens a website in a browser app
+    (Meta's com.oculus.browser on Quest), which Lepton doesn't have (GitHub #86). {"url": str | None} or None."""
+    if TWA_URL_KEY not in meta and TWA_ACTIVITY not in manifest_strings:
+        return None
+    url = _resolve_string(apk, meta.get(TWA_URL_KEY))
+    return {"url": url if url and url.startswith(("https://", "http://")) else None}
 
 
 def _unreal_version(z: zipfile.ZipFile, lib: str) -> str | None:
@@ -112,7 +167,7 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
         ggm = z.read(UNITY_GGM) if deep and UNITY_GGM in names else None
         il2cpp_meta = z.read(IL2CPP_METADATA) if deep and IL2CPP_METADATA in names and "libil2cpp.so" in libs else None
 
-    package, version, label, activity = _read_manifest_info(path)
+    package, version, label, activity, apk_info = _read_manifest_info(path)
     libset = set(libs)
     engine = ("Unreal" if libset & {"libUE4.so", "libUnreal.so"} else "Unity" if "libunity.so" in libset
               else "CryEngine" if "libCrySystem.so" in libset else "Other")
@@ -159,6 +214,7 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
     manifest_strings = axml.Axml(manifest).strings()
     features = _features(manifest)
     used_perms, _ = axml.used_and_declared_permissions(manifest)
+    meta = axml.meta_data(manifest)
     return Analysis(
         package=package,
         version=version,
@@ -216,6 +272,13 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
             # a 2D launcher activity that starts a separate VR activity (frame.start_activity)
             "vr_activity": axml.vr_activity(manifest),
             "unity_version": unity_version(ggm, lib_bytes.get("libunity.so")) if engine == "Unity" else None,
+            # the minimum Android version the APK declares (read from the original: OVRPort lowers it to 29)
+            "min_sdk": axml.min_sdk(manifest),
+            # a website in an Android wrapper (TWA): nothing to port
+            "web_wrapper": web_wrapper(meta, manifest_strings, apk_info),
+            # Unreal packaged its content as an OBB (expansion file): without it the game hangs at start (GitHub #85).
+            # (Unity's split-binary builds show no reliable sign in the APK.)
+            "expects_obb": expects_obb(meta),
         },
     )
 

src/frameport/analysis/linux.py

@@ -1,5 +1,5 @@
-"""Native arm64 Linux apps for the Frame (GitHub #31): an AppImage, a folder, or a .zip/.tar.* archive with an
-aarch64 program. Finds the program to start, checks the CPU architecture (x86_64 builds can't run natively) and
+"""Linux apps for the Frame (GitHub #31): an AppImage, a folder, or a .zip/.tar.* archive with an aarch64 program
+(or an x86_64 one, which the Frame runs through FEX). Finds the program to start, checks the CPU architecture and
 whether it's an OpenXR (VR) app. Archives are unpacked once into FramePort's data folder, so installs upload a
 plain folder like PC VR games do."""
 from __future__ import annotations
@@ -147,8 +147,14 @@ def uses_openxr(paths: list[Path]) -> bool:
     return False
 
 
+def runs_on_frame(machine: int | None) -> bool:
+    """aarch64 natively, x86_64 through FEX (x86 translation, slower)."""
+    return machine in (EM_AARCH64, EM_X86_64)
+
+
 def inspect(path: Path) -> dict:
-    """{root, exe (relative to root), appimage, machine, arch_ok, openxr, title, candidates} for an AppImage, a
+    """{root, exe (relative to root), appimage, machine, arch_ok (aarch64: native), openxr, title, candidates} for an
+    AppImage, a
     folder or an archive. Raises ValueError when there's no Linux program in it."""
     path = Path(path)
     if path.is_file() and is_archive(path):
@@ -174,6 +180,11 @@ def inspect(path: Path) -> dict:
     programs = rank_programs(root)
     if not programs:
         raise ValueError(f"no Linux program found in {path.name}")
+    # an arm64 build wins; x86_64 programs only when there is nothing else (they run through FEX on the Frame)
+    for want in (EM_AARCH64, EM_X86_64):
+        if any(m == want for _p, m in programs):
+            programs = [(p, m) for p, m in programs if m == want]
+            break
     appimages = [p for p, _m in programs if is_appimage(p)]
     exe, machine = (appimages[0], elf_machine(appimages[0])) if appimages else programs[0]
     libs = app_libraries(root, exe)
@@ -181,4 +192,4 @@ def inspect(path: Path) -> dict:
     return {"root": str(root), "exe": exe.relative_to(root).as_posix(), "files": None,
             "appimage": is_appimage(exe), "machine": machine, "arch_ok": machine == EM_AARCH64,
             "openxr": uses_openxr([exe] + libs), "title": title,
-            "candidates": [p.relative_to(root).as_posix() for p, m in programs[:20] if m == EM_AARCH64]}
+            "candidates": [p.relative_to(root).as_posix() for p, m in programs[:20] if m == machine]}

src/frameport/apk/axml.py

@@ -15,6 +15,9 @@ RES_XML_START_ELEMENT = 0x0102
 RES_XML_END_ELEMENT = 0x0103
 TYPE_STRING = 0x03
 TYPE_INT_BOOLEAN = 0x12
+TYPE_REFERENCE = 0x01
+TYPE_INT_DEC = 0x10
+TYPE_INT_HEX = 0x11
 ANDROID_NS = "http://schemas.android.com/apk/res/android"
 LAUNCHER = "android.intent.category.LAUNCHER"
 INFO = "android.intent.category.INFO"
@@ -214,6 +217,48 @@ def undeclared_meta_permissions(manifest: bytes) -> list[str]:
     return [p for p in used if p.startswith(("com.oculus.permission.", "horizonos.permission.")) and p not in declared]
 
 
+def min_sdk(manifest: bytes) -> int | None:
+    """<uses-sdk android:minSdkVersion> (None when absent or a preview codename)."""
+    x = Axml(manifest)
+    names = x.strings()
+    for el in x.elements():
+        if el.name != "uses-sdk":
+            continue
+        for a in el.attrs:
+            if a.name < len(names) and names[a.name] == "minSdkVersion":
+                if a.dtype in (TYPE_INT_DEC, TYPE_INT_HEX):
+                    return a.value
+                s = x.attr_str(el, "minSdkVersion")
+                return int(s) if s and s.isdigit() else None
+    return None
+
+
+def meta_data(manifest: bytes) -> dict[str, str | int | bool | None]:
+    """<meta-data android:name android:value|resource> entries: a string, a bool, an int, or a resource id (int)
+    for references (@string/…), None when the value isn't one of those."""
+    x = Axml(manifest)
+    names = x.strings()
+    out: dict = {}
+    for el in x.elements():
+        if el.name != "meta-data":
+            continue
+        key = x.attr_str(el, "name")
+        if not key:
+            continue
+        value = None
+        for a in el.attrs:
+            if a.name >= len(names) or names[a.name] not in ("value", "resource"):
+                continue
+            if a.raw < len(names) or a.dtype == TYPE_STRING:
+                value = x.attr_str(el, names[a.name])
+            elif a.dtype == TYPE_INT_BOOLEAN:
+                value = a.value != 0
+            elif a.dtype in (TYPE_INT_DEC, TYPE_INT_HEX, TYPE_REFERENCE):
+                value = a.value
+        out[key] = value
+    return out
+
+
 def categories(manifest: bytes) -> set[str]:
     x = Axml(manifest)
     return {v for el in x.elements() if el.name == "category" for v in [x.attr_str(el, "name")] if v}

src/frameport/build.py

@@ -10,7 +10,7 @@ from .apk.workspace import ApkWorkspace
 from .core.events import Reporter
 from .core.models import Analysis, BuildResult, Recipe, SourceGame
 from .core.paths import work_dir
-from .patches import base
+from .patches import base, upstream
 from .patches.overport import OVERPORT_PATCHES
 from .tools import overport as overport_tool
 from .validate.static import check_apk
@@ -36,25 +36,28 @@ def overport_ids(recipe: Recipe, alt: bool = False) -> list[str]:
     return ids
 
 
-def apk_patches(recipe: Recipe) -> list[base.Patch]:
-    patches = [base.get(pid) for pid in recipe.patches if base.get(pid).stage == "apk"]
+def apk_patches(selection: dict) -> list[base.Patch]:
+    patches = [base.get(pid) for pid in selection if base.get(pid).stage == "apk"]
     return sorted(patches, key=lambda p: p.order)
 
 
 def apply_frame_fixes(apk_in: Path, apk_out_unsigned: Path, analysis: Analysis, recipe: Recipe,
-                      reporter: Reporter) -> tuple[list[str], list[dict]]:
+                      reporter: Reporter) -> tuple[list[str], list[dict], dict[str, str]]:
+    """Apply the recipe's apk-stage patches; returns (applied ids, checks, workarounds left out because OVRPort's
+    output already has the upstream fix (patches/upstream.py))."""
     applied, checks = [], []
     with ApkWorkspace(apk_in) as ws:
-        for patch in apk_patches(recipe):
+        selection = upstream.resolve(ws, recipe.patches, reporter)
+        for patch in apk_patches(selection.patches):
             reporter.check_cancel()
-            ctx = base.ApkContext(ws, analysis, recipe.params(patch.id), reporter, recipe.patches)
+            ctx = base.ApkContext(ws, analysis, selection.patches.get(patch.id) or {}, reporter, selection.patches)
             if patch.apply(ctx):
                 applied.append(patch.id)
                 reporter.log(f"applied {patch.id}" + (f" ({'; '.join(ctx.notes)})" if ctx.notes else ""))
             for name, ok, detail in patch.validate(ctx):
                 checks.append({"name": name, "ok": ok, "detail": detail})
         ws.write(apk_out_unsigned)
-    return applied, checks
+    return applied, checks, selection.superseded
 
 
 def build(source: SourceGame, analysis: Analysis, recipe: Recipe, outdir: Path, reporter: Reporter,
@@ -73,7 +76,7 @@ def build(source: SourceGame, analysis: Analysis, recipe: Recipe, outdir: Path,
     variants = [("primary", False)] + ([("alt", True)] if recipe.alt_patches and recipe.overport else [])
     alt_copy = Path(source.apk).with_name(f"{pkg}.alt-noforcequit.apk")
     results = {}
-    all_checks, applied = [], []
+    all_checks, applied, superseded = [], [], {}
     try:
         for variant, alt in variants:
             input_apk = alt_copy if converted and alt and alt_copy.exists() else Path(source.apk)
@@ -88,7 +91,9 @@ def build(source: SourceGame, analysis: Analysis, recipe: Recipe, outdir: Path,
                 shutil.copyfile(input_apk, patched)
             reporter.stage(f"Frame fixes ({variant})")
             unsigned = work / f"{pkg}.{variant}.unsigned.apk"
-            applied, checks = apply_frame_fixes(patched, unsigned, analysis, recipe, reporter)
+            applied, checks, left_out = apply_frame_fixes(patched, unsigned, analysis, recipe, reporter)
+            if variant == "primary":
+                superseded = left_out
             patched.unlink(missing_ok=True)
             reporter.stage(f"sign ({variant})")
             final = outdir / (f"{pkg}.apk" if not alt else f"{pkg}.alt-noforcequit.apk")
@@ -106,4 +111,4 @@ def build(source: SourceGame, analysis: Analysis, recipe: Recipe, outdir: Path,
     primary, alt_apk = results["primary"], results.get("alt")
     return BuildResult(pkg, primary, alt_apk, sha256(primary), sha256(alt_apk) if alt_apk else None, applied,
                        all_checks, {"overport": overport_ids(recipe), "alt_overport": overport_ids(recipe, True)
-                                    if alt_apk else None})
+                                    if alt_apk else None, "superseded": superseded})

src/frameport/cli.py

@@ -19,6 +19,7 @@ Errors are one line on stderr; FRAMEPORT_DEBUG=1 shows the traceback.
     frameport diag inspect <zip>                 # re-triage a diagnostics zip (no game files or Frame needed)
     frameport diag report <pkg>                  # zip + prefilled GitHub problem report
     frameport share-recipe <pkg> --status works  # prefilled GitHub issue submitting a working recipe
+    frameport open-link "<install link>"         # FrameDrop button / frameport:// link: download, add, install
 """
 from __future__ import annotations
 
@@ -228,6 +229,8 @@ def scan(path: Path = typer.Argument(..., help="a folder with game backups (APKs
     for g in pipeline.add_path(path, rep):
         r = g["recipe"]
         typer.echo(f"{g['package']:40} {g.get('title', '')[:34]:34} {r['status']:11} {r['source']}")
+        for warning in pipeline.analysis_warnings(g):
+            typer.echo(f"  ! {warning}")
 
 
 @app.command("catalog-update")
@@ -255,6 +258,56 @@ def add_linux(path: Path = typer.Argument(..., help="an arm64 AppImage, a folder
                f"{' (AppImage)' if extra['appimage'] else ''}{' VR' if extra['openxr'] else ''}")
 
 
+@app.command("open-link")
+def open_link(link: str = typer.Argument(..., help="an \"Install with FrameDrop\" button's address, a framedrop:// "
+                                                   "or frameport:// link, a manifest (.json) or an APK/zip/exe URL"),
+              yes: bool = typer.Option(False, "--yes", "-y", help="don't ask before downloading"),
+              no_install: bool = typer.Option(False, help="only download and add to the library"),
+              frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
+              gui: bool = typer.Option(False, help="hand the link to the GUI (started if it isn't running)")):
+    """Install from a link (FrameDrop's button protocol): download, add to the library, install on the Frame."""
+    from . import deeplink
+
+    if gui:
+        from . import urlhandler
+
+        urlhandler.drop_link(link)
+        if not urlhandler.app_running():
+            import subprocess
+
+            subprocess.Popen(urlhandler.start_command(), start_new_session=True, stdin=subprocess.DEVNULL,
+                             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        typer.echo("handed to the FramePort window")
+        return
+    try:
+        m = deeplink.fetch_manifest(deeplink.parse(link))
+    except deeplink.LinkError as exc:
+        raise typer.BadParameter(str(exc)) from None
+    typer.echo(f"{m.name}  (from {m.host or m.source})")
+    if m.description:
+        typer.echo(f"  {m.description[:400]}")
+    for f in m.files:
+        size = deeplink.head_size(f.url)
+        typer.echo(f"  {f.filename}  {f.kind or 'other'}"
+                   f"{f'  {size / 2**20:.0f} MiB' if size else ''}  {'sha256 checked' if f.sha256 else 'no checksum'}")
+    if not yes and not typer.confirm("Only install software from sites you trust. Download and install it?"):
+        raise typer.Exit(1)
+    rep = printing_reporter(verbose=False)
+    path = deeplink.download(m, rep)
+    g = pipeline.add_from_link(m, path, rep, icon=deeplink.fetch_icon(m))
+    pkg = g["package"]
+    typer.echo(f"added {pkg} ({g.get('title')})")
+    if no_install:
+        return
+    target = _target(frame)
+    info = pipeline.build_game(pkg, rep)
+    if not info["ok"]:
+        typer.echo(f"{pkg}: the game didn't pass its checks", err=True)
+        raise typer.Exit(1)
+    pipeline.install_game(pkg, target, rep)
+    typer.echo(f"installed {pkg} on {target.label}")
+
+
 @app.command("list")
 def list_games():
     """The games in the library."""
@@ -278,6 +331,9 @@ def show(package: str, as_json: bool = typer.Option(False, "--json", help=JSON_H
     typer.echo(f"{g.get('title')}  ({pkg} {a['version']})\n  engine {a['engine']}, XR {a['xr']}, {a['graphics']}, "
                f"ABIs {', '.join(a['abis'])}, direct VrApi: {a['direct_vrapi']}")
     typer.echo(f"  status: {r['status']}  recipe source: {r['source']}  {r['notes']}")
+    for warning in pipeline.analysis_warnings(g):
+        if warning not in r["notes"]:
+            typer.echo(f"  ! {warning}")
     from .recommend.engine import visible_patches
 
     shown, hidden = visible_patches(library.analysis_from_dict(a), library.recipe_from_dict(r))
@@ -286,6 +342,8 @@ def show(package: str, as_json: bool = typer.Option(False, "--json", help=JSON_H
         params = r["patches"].get(p.id) or {}
         typer.echo(f"  [{'x' if on else ' '}] {p.id:36} {p.title}{'  ' + json.dumps(params) if params else ''}"
                    f"{'  — ' + r['reasons'][p.id] if on and p.id in r.get('reasons', {}) else ''}")
+    for pid, fix in ((g.get("build") or {}).get("superseded") or {}).items():
+        typer.echo(f"  last build left out {pid}: fixed upstream ({fix})")
     if hidden and not all_:
         typer.echo(f"  ({len(hidden)} patches hidden as not relevant for this game; --all to list them)")
     if r.get("alt_patches"):
@@ -363,13 +421,20 @@ def install(package: Optional[str] = typer.Argument(None), all_: bool = typer.Op
             no_library: bool = typer.Option(False, help="don't add to the Steam library now"),
             to: str = typer.Option("frame", help="frame, or pc (PC VR games only: install on this PC)"),
             apk: Optional[Path] = typer.Option(None, help="install this APK instead of the last build (one game; e.g. "
-                                                          "a test build signed with the game's key)")):
+                                                          "a test build signed with the game's key)"),
+            dest: Optional[str] = typer.Option(None, help="drive for new installs: 'internal' or a drive's path from "
+                                                          "'frameport frame drives' (default: the app's setting); "
+                                                          "installed games stay where they are")):
     """Install games on the Frame (or PC VR games on this PC) and add them to the Steam library."""
     target = _target(frame, password, to)
+    if dest is not None and hasattr(target, "dest"):
+        target.dest = "" if dest == "internal" else dest
     pkgs = _pkgs(package, all_)
     if apk and len(pkgs) != 1:
         raise typer.BadParameter("--apk needs exactly one game")
     for pkg in pkgs:
+        if not apk_only and pipeline.missing_obb(library.game(pkg) or {}):
+            typer.echo(f"{pkg}: warning: " + pipeline.MISSING_OBB_NOTE.format(package=pkg), err=True)
         pipeline.install_game(pkg, target, printing_reporter(False), apk_only, add_to_library=False, apk=apk)
     if not no_library:
         target.add_to_library(pkgs, printing_reporter(False))
@@ -502,6 +567,38 @@ def frame_storage(game: Optional[str] = typer.Option(None, help="also show this
         typer.echo(f"{t['id']:10} {t['android']:45} {t['path']}" + ("  (every app)" if t["shared"] else ""))
 
 
+@frame_app.command("drives")
+def frame_drives(frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
+                 as_json: bool = typer.Option(False, "--json", help=JSON_HELP)):
+    """The Frame's drives (internal storage, a microSD card) games can be installed on or moved to."""
+    from .install import drives
+
+    found = _target(frame).drives()
+    if as_json:
+        typer.echo(json.dumps(found, indent=1))
+        return
+    current = drives.install_dest()
+    for d in found:
+        free = drives.free_text(d) or "?"
+        mark = "*" if (d["internal"] and not current) or current in (d["install_dir"], d["path"]) else " "
+        state = f"{d.get('games', 0)} game(s)" if d.get("usable") else f"can't be used: {d.get('reason')}"
+        typer.echo(f"{mark} {d['label']:20} {d.get('fstype') or '':6} {free:>16}  {state}")
+        if not d["internal"]:
+            typer.echo(f"  {'':20} {d['path']}")
+    typer.echo("* = where new games go (frameport install --dest, or the app's Settings: Frame)")
+
+
+@frame_app.command("move")
+def frame_move(package: str = typer.Argument(..., help="an installed game"),
+               to_: str = typer.Option(..., "--to", help="'internal' or a drive's path from 'frameport frame drives'"),
+               frame: Optional[str] = typer.Option(None, help=FRAME_HELP)):
+    """Move an installed game's files to another drive of the Frame (e.g. the microSD card) or back. Saves, the
+    Steam library entry and settings stay as they are."""
+    pkg = _pkgs(package, False)[0]
+    st = _target(frame).move(pkg, to_, printing_reporter())
+    typer.echo(f"moved to {st.get('base') or st.get('to')}")
+
+
 @frame_app.command("info")
 def frame_info(frame: Optional[str] = typer.Option(None, help=FRAME_HELP)):
     """The Frame's SteamOS build, runtimes, storage and installed games (JSON)."""

src/frameport/deeplink.py

@@ -0,0 +1,380 @@
+"""One-click installs from web pages: the "Install with FrameDrop" button protocol (no Flet).
+
+FrameDrop (framedropvr.com) defined it: a page links to `https://framedropvr.com/install?manifest=<URL>` (or
+`?url=<direct file URL>`), which opens `framedrop://install?manifest=…|url=…`. The manifest is JSON:
+`{"schema": "framedrop.install/v1", "name": "<Steam title>", "files": [{"url": "https://…/x.apk", "sha256": "…"}]}`
+with an arm64 APK or a zipped Linux ARM64 build. FramePort accepts the same links (`framedrop://` when it is the
+system's handler, its own `frameport://`, or the https link pasted into "Install from link…"), follows the same
+rules (https only, http only on this PC, no credentials, no LAN addresses, a URL that ends in a file name) and
+always asks before it downloads anything a web page sent. `urlhandler.py` registers the schemes.
+"""
+from __future__ import annotations
+
+import hashlib
+import ipaddress
+import json
+import re
+import socket
+from dataclasses import dataclass, field
+from pathlib import Path
+from urllib.parse import parse_qs, unquote, urlsplit
+
+from .core.events import Reporter
+
+SCHEMES = ("framedrop", "frameport")
+WEB_HOSTS = ("framedropvr.com", "www.framedropvr.com")
+SCHEMA = "framedrop.install/v1"
+MAX_MANIFEST = 256 << 10
+MAX_FILES = 16
+MAX_DESCRIPTION = 2000
+MAX_ICON = 2 << 20
+LOOPBACK = ("localhost", "127.0.0.1", "[::1]", "::1")
+APK, LINUX, EXE, OBB = "apk", "linux", "exe", "obb"
+LINUX_EXTS = (".zip", ".tar.gz", ".tgz", ".tar.xz", ".txz", ".tar.bz2", ".tar", ".appimage")
+
+
+class LinkError(ValueError):
+    """A link or manifest FramePort won't use (the message says why, in plain words)."""
+
+
+@dataclass
+class InstallRequest:
+    manifest_url: str | None = None
+    file_url: str | None = None
+    local_manifest: str | None = None  # a .framedrop.json dropped on the window
+
+    @property
+    def source(self) -> str:
+        return self.manifest_url or self.file_url or self.local_manifest or ""
+
+
+@dataclass
+class ManifestFile:
+    url: str
+    sha256: str | None = None
+
+    @property
+    def filename(self) -> str:
+        return filename_of(self.url)
+
+    @property
+    def kind(self) -> str | None:
+        return classify(self.filename)
+
+
+@dataclass
+class Manifest:
+    name: str
+    files: list[ManifestFile] = field(default_factory=list)
+    source: str = ""  # the manifest's (or the file's) URL
+    direct: bool = False  # made from a bare file link (the name is only a guess from the file name)
+    # FramePort-only extension (FrameDrop ignores it): "frameport": {"description": "…", "icon": "https://….png"}
+    description: str = ""
+    icon: str | None = None
+
+    @property
+    def host(self) -> str:
+        return (urlsplit(self.source).hostname or "") if "://" in self.source else ""
+
+    @property
+    def main(self) -> ManifestFile:
+        """The file that is installed (an APK first, then a Linux build, then a Windows program)."""
+        for kind in (APK, LINUX, EXE):
+            for f in self.files:
+                if f.kind == kind:
+                    return f
+        raise LinkError("The link has no APK, Linux build (.zip/.tar/AppImage) or Windows program (.exe) to install.")
+
+
+# ------------------------------------------------------------------------------------------------- links
+def filename_of(url: str) -> str:
+    return unquote(urlsplit(url).path.rsplit("/", 1)[-1])
+
+
+def classify(filename: str) -> str | None:
+    name = filename.lower()
+    if name.endswith(".apk"):
+        return APK
+    if name.endswith(".obb"):
+        return OBB
+    if name.endswith(".exe"):
+        return EXE
+    if name.endswith(LINUX_EXTS):
+        return LINUX
+    return None
+
+
+def _private(host: str) -> bool:
+    try:
+        ip = ipaddress.ip_address(host.strip("[]"))
+    except ValueError:
+        return False
+    return ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_reserved or ip.is_multicast or \
+        ip.is_unspecified
+
+
+def check_url(url: str, what: str = "link", resolve: bool = False) -> str:
+    """The URL if FramePort may fetch it, else LinkError. FrameDrop's rules: https (http only on this PC), no
+    user:password, no LAN address, a path that ends in a file name. `resolve` also refuses names that resolve to a LAN
+    address (checked right before a download)."""
+    try:
+        parts = urlsplit(url.strip())
+    except ValueError:
+        raise LinkError(f"The {what} isn't a valid web address.") from None
+    host = (parts.hostname or "").lower()
+    if parts.scheme not in ("https", "http") or not host:
+        raise LinkError(f"The {what} must be an https:// address (got {parts.scheme or 'none'}).")
+    if parts.username or parts.password:
+        raise LinkError(f"The {what} contains a user name or password: FramePort doesn't use those.")
+    loopback = host in LOOPBACK or host == "::1"
+    if parts.scheme == "http" and not loopback:
+        raise LinkError(f"The {what} must use https:// (http:// is only allowed on this PC, for testing).")
+    if parts.scheme == "https" and not loopback and _private(host):
+        raise LinkError(f"The {what} points into a local network ({host}): FramePort only fetches public addresses.")
+    if not parts.path or parts.path.endswith("/") or not filename_of(url):
+        raise LinkError(f"The {what} must end in a file name, not a folder.")
+    if resolve and not loopback and not _private(host):
+        try:
+            addrs = {a[4][0] for a in socket.getaddrinfo(host, parts.port or 443, proto=socket.IPPROTO_TCP)}
+        except OSError:
+            addrs = set()  # the download itself reports the lookup failure
+        if any(_private(a) for a in addrs):
+            raise LinkError(f"{host} resolves to a local network address: FramePort only fetches public addresses.")
+    return url.strip()
+
+
+def parse(text: str) -> InstallRequest:
+    """framedrop://install?…, frameport://install?…, the https://framedropvr.com/install?… button link, a manifest
+    URL (…json) or a direct file URL."""
+    text = (text or "").strip().strip('"').strip("'")
+    if not text:
+        raise LinkError("Paste a link first.")
+    try:
+        parts = urlsplit(text)
+    except ValueError:
+        raise LinkError("That isn't a link FramePort understands.") from None
+    scheme = parts.scheme.lower()
+    if scheme in SCHEMES or (scheme == "https" and (parts.hostname or "").lower() in WEB_HOSTS):
+        action = (parts.netloc or parts.path.strip("/")) if scheme in SCHEMES else parts.path.strip("/")
+        if action.lower().split("/")[0] != "install":
+            raise LinkError("FramePort only understands install links (…/install?manifest=… or ?url=…).")
+        query = parse_qs(parts.query)
+        manifest, file = (query.get("manifest") or [None])[0], (query.get("url") or [None])[0]
+        if manifest:
+            return InstallRequest(manifest_url=check_url(manifest, "manifest address"))
+        if file:
+            return InstallRequest(file_url=check_url(file, "file address"))
+        raise LinkError("The link doesn't say what to install (no manifest= or url=).")
+    if scheme in ("https", "http"):
+        url = check_url(text)
+        name = filename_of(url).lower()
+        if name.endswith(".json"):
+            return InstallRequest(manifest_url=url)
+        if classify(name) in (APK, LINUX, EXE):
+            return InstallRequest(file_url=url)
+        raise LinkError("The link isn't a FramePort/FrameDrop install link, a manifest (.json) or an APK/zip/exe.")
+    if text.lower().endswith(".json") and Path(text).is_file():
+        return InstallRequest(local_manifest=text)
+    raise LinkError("That isn't a link FramePort understands.")
+
+
+def make_link(manifest_url: str | None = None, file_url: str | None = None, scheme: str = "frameport") -> str:
+    from urllib.parse import quote
+
+    key, value = ("manifest", manifest_url) if manifest_url else ("url", file_url)
+    return f"{scheme}://install?{key}={quote(value or '', safe='')}"
+
+
+# ------------------------------------------------------------------------------------------------- manifest
+def title_from_filename(filename: str) -> str:
+    """A readable guess from a file name: "net.sourceforge.opencamera_96.apk" → "Opencamera",
+    "Cool_Game-v1.2.3-arm64-v8a.apk" → "Cool Game" (the real title comes from the build once it's downloaded)."""
+    stem = re.sub(r"(?i)(\.tar)?\.[a-z0-9]{2,8}$", "", filename)
+    stem = re.sub(r"(?i)[-_.](arm64(-v8a)?|aarch64|x86_64|amd64|universal|release|signed|linux|android)\b", "", stem)
+    stem = re.sub(r"(?i)[-_ ]v?\d+(\.\d+)*([-_.]?(beta|alpha|rc)\d*)?$", "", stem)  # a version number at the end
+    if re.fullmatch(r"[a-z][a-z0-9_]*(\.[A-Za-z0-9_]+){2,}", stem):  # an Android package name: its last part
+        stem = stem.rsplit(".", 1)[-1]
+    words = re.sub(r"[-_.]+", " ", stem).strip()
+    if words and words == words.lower():
+        words = " ".join(w[:1].upper() + w[1:] for w in words.split())
+    return words or filename
+
+
+def manifest_from_data(data, source: str = "") -> Manifest:
+    if not isinstance(data, dict):
+        raise LinkError("The manifest isn't a JSON object.")
+    if data.get("schema") != SCHEMA:
+        raise LinkError(f"The manifest's schema is {data.get('schema')!r}; FramePort reads {SCHEMA!r}.")
+    name = data.get("name")
+    if not isinstance(name, str) or not name.strip():
+        raise LinkError("The manifest has no name.")
+    files = data.get("files")
+    if not isinstance(files, list) or not files:
+        raise LinkError("The manifest lists no files.")
+    if len(files) > MAX_FILES:
+        raise LinkError(f"The manifest lists {len(files)} files; FramePort takes at most {MAX_FILES}.")
+    out = []
+    for f in files:
+        if not isinstance(f, dict) or not isinstance(f.get("url"), str):
+            raise LinkError("A file in the manifest has no url.")
+        sha = f.get("sha256")
+        if sha is not None and (not isinstance(sha, str) or not re.fullmatch(r"[0-9a-fA-F]{64}", sha)):
+            sha = None  # FrameDrop's example has a placeholder here; a wrong checksum is ignored like a missing one
+        out.append(ManifestFile(check_url(f["url"], "file address"), sha.lower() if sha else None))
+    m = Manifest(" ".join(name.split())[:120], out, source)
+    m.main  # noqa: B018 - raises when nothing installable is listed
+    extra = data.get("frameport")  # FramePort-only fields; anything wrong in them is ignored (they're optional)
+    if isinstance(extra, dict):
+        desc = extra.get("description")
+        if isinstance(desc, str):
+            m.description = desc.strip()[:MAX_DESCRIPTION]
+        icon = extra.get("icon")
+        if isinstance(icon, str):
+            try:
+                m.icon = check_url(icon, "icon address")
+            except LinkError:
+                pass
+    return m
+
+
+def fetch_manifest(req: InstallRequest) -> Manifest:
+    """The manifest a request names (a direct file link becomes a one-file manifest titled after the file)."""
+    if req.file_url:
+        name = filename_of(req.file_url)
+        m = Manifest(title_from_filename(name), [ManifestFile(req.file_url)], req.file_url, direct=True)
+        m.main  # noqa: B018
+        return m
+    if req.local_manifest:
+        try:
+            raw = Path(req.local_manifest).read_bytes()[:MAX_MANIFEST + 1]
+        except OSError as exc:
+            raise LinkError(f"Can't read {req.local_manifest}: {exc}") from None
+        source = req.local_manifest
+    else:
+        from .core.cache import _session
+
+        url = check_url(req.manifest_url or "", "manifest address", resolve=True)
+        with _session.get(url, stream=True, timeout=20) as resp:
+            resp.raise_for_status()
+            check_url(resp.url, "manifest address")  # after redirects
+            raw = b""
+            for chunk in resp.iter_content(64 << 10):
+                raw += chunk
+                if len(raw) > MAX_MANIFEST:
+                    break
+        source = url
+    if len(raw) > MAX_MANIFEST:
+        raise LinkError("The manifest is too large to be a FrameDrop manifest.")
+    try:
+        data = json.loads(raw.decode("utf-8-sig"))
+    except (UnicodeDecodeError, ValueError):
+        raise LinkError("The manifest isn't valid JSON.") from None
+    return manifest_from_data(data, source)
+
+
+def head_size(url: str) -> int | None:
+    """Content-Length from a HEAD request (None when the server doesn't say)."""
+    from .core.cache import _session
+
+    try:
+        resp = _session.head(url, allow_redirects=True, timeout=10)
+        return int(resp.headers["content-length"]) if resp.ok and "content-length" in resp.headers else None
+    except Exception:  # noqa: BLE001 - only for the confirmation's size column
+        return None
+
+
+def fetch_icon(m: Manifest) -> Path | None:
+    """The manifest's icon (FramePort extension) as a checked PNG in the data folder, or None. Same URL rules as
+    the files; at most 2 MiB; must be an image of at least 32 px."""
+    if not m.icon:
+        return None
+    from io import BytesIO
+
+    from PIL import Image
+
+    from .core.cache import _session
+    from .core.paths import user_data_dir
+
+    try:
+        check_url(m.icon, "icon address", resolve=True)
+        raw = b""
+        with _session.get(m.icon, stream=True, timeout=20) as resp:
+            resp.raise_for_status()
+            check_url(resp.url, "icon address")
+            for chunk in resp.iter_content(64 << 10):
+                raw += chunk
+                if len(raw) > MAX_ICON:
+                    return None
+        with Image.open(BytesIO(raw)) as im:
+            if min(im.size) < 32:
+                return None
+            im = im.convert("RGBA")
+            im.thumbnail((512, 512))
+            out = user_data_dir() / "downloads" / "icons" / (hashlib.sha256(m.icon.encode()).hexdigest()[:16] + ".png")
+            out.parent.mkdir(parents=True, exist_ok=True)
+            im.save(out, "PNG")
+            return out
+    except Exception:  # noqa: BLE001 - the icon is decoration: no icon rather than no install
+        return None
+
+
+# ------------------------------------------------------------------------------------------------- download
+def staging_dir(m: Manifest) -> Path:
+    from .core.paths import user_data_dir
+
+    key = hashlib.sha256(m.source.encode()).hexdigest()[:10]
+    slug = re.sub(r"[^a-z0-9]+", "-", m.name.lower()).strip("-")[:40] or "download"
+    return user_data_dir() / "downloads" / f"{slug}-{key}"
+
+
+def download_file(url: str, dest: Path, reporter: Reporter | None = None, sha256: str | None = None,
+                  label: str = "") -> Path:
+    """Stream one file to dest (via dest.part, removed on failure or cancel), checking its SHA-256 when given."""
+    from .core.cache import _session
+
+    check_url(url, "file address", resolve=True)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_name(dest.name + ".part")
+    h = hashlib.sha256()
+    try:
+        with _session.get(url, stream=True, timeout=60) as resp:
+            resp.raise_for_status()
+            check_url(resp.url, "file address")  # a redirect must follow the same rules
+            total, done = int(resp.headers.get("content-length") or 0), 0
+            with open(tmp, "wb") as f:
+                for chunk in resp.iter_content(1 << 20):
+                    if reporter:
+                        reporter.check_cancel()
+                    f.write(chunk)
+                    h.update(chunk)
+                    done += len(chunk)
+                    if reporter and total:
+                        reporter.progress(done / total, f"{label or dest.name}: {done >> 20} of {total >> 20} MiB")
+        if sha256 and h.hexdigest() != sha256.lower():
+            raise LinkError(f"{dest.name} doesn't match the manifest's checksum (download damaged or file changed).")
+        tmp.replace(dest)
+        return dest
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def download(m: Manifest, reporter: Reporter | None = None) -> Path:
+    """Download every file into a fresh staging folder and return the path to add: the APK (OBB files go into the
+    `obb/` folder next to it, where the APK scan finds them), the Linux build or the Windows program."""
+    import shutil
+
+    folder = staging_dir(m)
+    shutil.rmtree(folder, ignore_errors=True)
+    folder.mkdir(parents=True)
+    main, out = m.main, None
+    for i, f in enumerate(m.files, 1):
+        name = re.sub(r'[\\/:*?"<>|\x00-\x1f]', "_", f.filename) or f"file{i}"
+        sub = "obb" if f.kind == OBB else ("program" if f.kind == EXE and f is main else "")
+        dest = folder / sub / name if sub else folder / name
+        if reporter:
+            reporter.stage("Downloading", f"Downloading {name} ({i} of {len(m.files)})")
+        download_file(f.url, dest, reporter, f.sha256, f"{name} ({i}/{len(m.files)})")
+        if f is main:
+            out = dest
+    return out

src/frameport/frame/monitor.py

@@ -0,0 +1,344 @@
+"""Monitor: a live view of the Frame (CPU/GPU/memory/temperatures/power/battery, the running game, processes) streamed
+by the agent's `_monitor` session as one JSON line per tick over one SSH channel, plus actions on processes and games
+(answered on the same channel). The session runs only while the GUI's Monitor tab is open; the agent ends it at EOF.
+
+The helpers below (History, formatting, levels, sort_filter) are pure so the view stays thin and they are testable."""
+from __future__ import annotations
+
+import itertools
+import json
+import posixpath
+import threading
+from collections import deque
+from collections.abc import Callable
+
+from ..core import applog
+
+MIN_AGENT = 62  # first agent with `_monitor`
+HISTORY = 120   # points per sparkline (2 min at 1 s)
+REPLY_TIMEOUT = 15.0
+
+
+class MonitorUnavailable(RuntimeError):
+    pass
+
+
+class ProcessCritical(RuntimeError):
+    """Ending the process would stop Steam, SteamVR or the desktop: ask the user, then retry with force=True."""
+
+
+class MonitorSession:
+    """One `_monitor` stream. `on_sample(dict)` is called from the reader thread for every sample; `on_end(reason)`
+    once when the stream stops by itself (connection lost, agent ended)."""
+
+    def __init__(self, frame, on_sample: Callable[[dict], None], on_end: Callable[[str], None] | None = None,
+                 timeout: float = 20):
+        self.frame = frame
+        self.on_sample = on_sample
+        self.on_end = on_end
+        self.closed = False
+        self._lock = threading.Lock()
+        self._ids = itertools.count(1)
+        self._waiting: dict[int, list] = {}  # id -> [Event, reply]
+        frame.ensure_agent()
+        remote = posixpath.join(frame.home, ".local/share/frameport/agent/frameport_agent.py")
+        self._stdin, self._stdout, _err = frame.client.exec_command(f"python3 {remote} _monitor", timeout=timeout)
+        first = json.loads(self._stdout.readline() or "{}")
+        if not first.get("ready"):
+            self.close()
+            raise MonitorUnavailable(first.get("error") or "the Frame didn't start the monitor")
+        self.static: dict = first.get("static") or {}
+        self._stdout.channel.settimeout(None)
+        self._thread = threading.Thread(target=self._read, name="frame-monitor", daemon=True)
+        self._thread.start()
+
+    # ----------------------------------------------------------------- stream
+    def _read(self) -> None:
+        reason = "ended"
+        try:
+            for line in self._stdout:
+                if self.closed:
+                    return
+                try:
+                    msg = json.loads(line)
+                except ValueError:
+                    continue
+                if not isinstance(msg, dict):
+                    continue
+                if "reply" in msg:
+                    slot = self._waiting.get(msg.get("reply"))
+                    if slot:
+                        slot[1] = msg
+                        slot[0].set()
+                    continue
+                try:
+                    self.on_sample(msg)
+                except Exception:  # noqa: BLE001 - a view bug must not end the stream
+                    applog.log.exception("monitor: sample handler failed")
+        except Exception as exc:  # noqa: BLE001 - connection lost
+            reason = str(exc) or type(exc).__name__
+        finally:
+            for slot in list(self._waiting.values()):
+                slot[0].set()
+        if not self.closed:
+            self.closed = True
+            if self.on_end:
+                self.on_end(reason)
+
+    def send(self, msg: dict) -> None:
+        with self._lock:
+            if self.closed:
+                return
+            self._stdin.write(json.dumps(msg) + "\n")
+            self._stdin.flush()
+
+    def set_interval(self, seconds: float) -> None:
+        self.send({"interval": seconds})
+
+    def set_filter(self, which: str) -> None:
+        self.send({"procs": which})
+
+    def pause(self, paused: bool) -> None:
+        self.send({"pause": bool(paused)})
+
+    def _request(self, msg: dict, timeout: float = REPLY_TIMEOUT) -> dict:
+        rid = next(self._ids)
+        slot = [threading.Event(), None]
+        self._waiting[rid] = slot
+        try:
+            self.send({**msg, "id": rid})
+            if not slot[0].wait(timeout) or slot[1] is None:
+                raise MonitorUnavailable("the Frame didn't answer" if not self.closed else "the monitor stopped")
+        finally:
+            self._waiting.pop(rid, None)
+        reply = slot[1]
+        if not reply.get("ok"):
+            err = reply.get("error") or "failed"
+            if err.startswith("CRITICAL:"):
+                raise ProcessCritical(err.split(":", 1)[1].strip())
+            raise RuntimeError(err)
+        return reply.get("result") or {}
+
+    def kill(self, pid: int, sig: str = "TERM", force: bool = False) -> dict:
+        """End one process: {"ended": bool, "pid", "name"}. TERM waits up to 3 s on the Frame."""
+        return self._request({"kill": int(pid), "sig": sig, "force": force})
+
+    def end_game(self, package: str) -> dict:
+        """Steam's Exit game, then a direct stop: {"ended": bool, "via": "steam"|"stop"}."""
+        return self._request({"end_game": package}, timeout=30)
+
+    def close(self) -> None:
+        with self._lock:
+            self.closed = True
+            try:
+                self._stdin.channel.shutdown_write()  # EOF: the agent's monitor ends
+                self._stdin.close()
+            except Exception:  # noqa: BLE001 - the connection may be gone already
+                pass
+
+
+# --------------------------------------------------------------------------------------------- pure helpers
+class History:
+    """Rolling series for the sparklines: name -> the last HISTORY points (None = a gap). With a time, values that
+    fall in the same `bucket` (1 s) are averaged into one point, so a chart always covers 2 minutes and moves
+    smoothly whatever the sampling interval (at 0.1 s the newest point is refined ten times a second)."""
+
+    def __init__(self, size: int = HISTORY, bucket: float = 1.0):
+        self.size, self.bucket = size, bucket
+        self.series: dict[str, deque] = {}  # name -> deque of [bucket index | None, sum, count]
+
+    def add(self, name: str, value: float | None, t: float | None = None) -> None:
+        q = self.series.setdefault(name, deque(maxlen=self.size))
+        idx = None if t is None else int(t // self.bucket)
+        last = q[-1] if q else None
+        if idx is not None and last is not None and last[0] == idx:
+            if value is not None:  # same second: refine the newest point
+                last[1] = (last[1] or 0.0) + value
+                last[2] += 1
+            return
+        q.append([idx, value, 1 if value is not None else 0])
+
+    def get(self, name: str) -> list:
+        return [(v / n if n else None) if v is not None else None for _i, v, n in self.series.get(name, ())]
+
+    def clear(self) -> None:
+        self.series.clear()
+
+
+def series_of(sample: dict) -> dict[str, float | None]:
+    """The values one sample adds to the History."""
+    mem = sample.get("mem") or {}
+    total = mem.get("total") or 0
+    temps = sample.get("temps") or {}
+    bat = sample.get("battery") or {}
+    game = (sample.get("games") or [None])[0] or {}
+    extra = {f"temp:{g}": v for g, v in temps.items()}
+    if sample.get("fan") is not None:
+        extra["fan"] = sample["fan"]
+    return {**extra,
+        "cpu": (sample.get("cpu") or {}).get("total"),
+        "gpu": (sample.get("gpu") or {}).get("busy"),
+        "mem": 100.0 * (total - mem.get("avail", 0)) / total if total else None,
+        "temp": max(temps.values()) if temps else None,
+        "power": (sample.get("power") or {}).get("system"),
+        "battery": bat.get("percent"),
+        "fps": game.get("fps"),
+    }
+
+
+def fmt_bytes(n: float | None) -> str:
+    if n is None:
+        return "–"
+    for unit in ("B", "KB", "MB", "GB"):
+        if abs(n) < 1024 or unit == "GB":
+            return f"{n:.0f} {unit}" if unit in ("B", "KB") else f"{n:.1f} {unit}"
+        n /= 1024
+    return f"{n:.1f} GB"
+
+
+def fmt_rate(n: float | None) -> str:
+    return "–" if n is None else fmt_bytes(n) + "/s"
+
+
+def fmt_watts(w: float | None) -> str:
+    if w is None:
+        return "–"
+    return f"{w:.2f} W" if abs(w) < 10 else f"{w:.1f} W"
+
+
+def fmt_duration(s: float | None) -> str:
+    """'1 h 05 min', '12 min', '45 s'."""
+    if s is None:
+        return "–"
+    s = int(s)
+    if s >= 3600:
+        return f"{s // 3600} h {s % 3600 // 60:02d} min"
+    if s >= 60:
+        return f"{s // 60} min"
+    return f"{s} s"
+
+
+def fmt_pct(v: float | None) -> str:
+    return "–" if v is None else f"{v:.0f} %"
+
+
+# (warn, error) thresholds; "low" metrics warn when the value falls below them
+LEVELS = {
+    "cpu": (85, 97), "gpu": (90, 99), "mem": (85, 93), "psi_memory": (10, 30),
+    "temp": (80, 90), "temp_Battery": (45, 50), "fps_ratio": (0.9, 0.75),
+}
+LOW = {"fps_ratio"}
+
+
+def level(metric: str, value: float | None) -> str:
+    """ok | warn | error for a metric's value (unknown metric or no value: ok)."""
+    if value is None or metric not in LEVELS:
+        return "ok"
+    warn, err = LEVELS[metric]
+    if metric in LOW:
+        return "error" if value < err else "warn" if value < warn else "ok"
+    return "error" if value >= err else "warn" if value >= warn else "ok"
+
+
+def temp_level(group: str, value: float | None) -> str:
+    return level(f"temp_{group}" if f"temp_{group}" in LEVELS else "temp", value)
+
+
+SORT_KEYS = ("cpu", "gpu", "rss", "name")
+
+
+def sort_filter(procs: list[dict], query: str = "", key: str = "cpu", descending: bool = True) -> list[dict]:
+    """Processes matching the search (name, PID or game package) in the chosen order."""
+    q = (query or "").strip().lower()
+    if q:
+        procs = [p for p in procs if q in p.get("name", "").lower() or q == str(p.get("pid"))
+                 or q in (p.get("game") or "").lower()]
+    if key == "name":
+        return sorted(procs, key=lambda p: (p.get("name", "").lower(), p.get("pid", 0)), reverse=descending)
+    return sorted(procs, key=lambda p: (p.get(key) or 0, p.get("rss") or 0), reverse=descending)
+
+
+def group_label(group: str) -> str:
+    """'game:<pkg>' -> 'Game'; steam/steamvr/desktop/other as shown in the table."""
+    if group.startswith("game:"):
+        return "Game"
+    return {"steam": "Steam", "steamvr": "SteamVR", "desktop": "Desktop"}.get(group, "Other")
+
+
+def power_split(power: dict) -> list[tuple[str, float]]:
+    """[(label, W)] for the stacked power bar: CPU, GPU, NPU, and the rest of the system rail."""
+    system = power.get("system") or 0.0
+    parts = [(k.upper(), power.get(k) or 0.0) for k in ("cpu", "gpu", "npu")]
+    rest = max(0.0, system - sum(v for _k, v in parts))
+    return [*parts, ("Other", rest)]
+
+
+def battery_line(bat: dict | None) -> str:
+    """'2 h 10 min left · −4.0 W' / 'Charging · full in 35 min' / 'Full'."""
+    if not bat:
+        return "No battery"
+    status = bat.get("status") or ""
+    watts = bat.get("watts")
+    if status == "Full":
+        return "Full"
+    if status == "Charging" or (bat.get("plugged") and not bat.get("draining")):
+        full = bat.get("full_s")
+        return "Charging" + (f" · full in {fmt_duration(full)}" if full and full < 360000 else "")
+    left = bat.get("empty_s")
+    parts = [f"{fmt_duration(left)} left"] if left and left < 360000 else []
+    if watts is not None:
+        parts.append(fmt_watts(abs(watts)))
+    return " · ".join(parts) or status
+
+
+REFRESH_RATES = (72, 80, 90, 96, 108, 120, 144)  # what the Frame's display offers (vrserver.txt)
+
+
+def fps_target(values: list) -> int | None:
+    """The refresh rate a game is presumably aiming for: the lowest Frame rate at or above its best recent fps
+    (with 3 % slack), for the dashed guide on the fps sparkline."""
+    best = max((v for v in values if v is not None), default=None)
+    if best is None:
+        return None
+    return next((r for r in REFRESH_RATES if best <= r * 1.03), REFRESH_RATES[-1])
+
+
+INTERVALS = (0.1, 0.25, 0.5, 1, 2, 5)
+DEFAULT_INTERVAL = 0.5
+
+
+def fmt_interval(s: float) -> str:
+    """0.1 -> "0.1 s", 1 -> "1 s"."""
+    return f"{s:g} s"
+
+
+def group_procs(procs: list[dict], expanded: set | frozenset = frozenset()) -> list[dict]:
+    """Table rows: processes with the same name and the same parent collapse into one group row ("vrwebhelper ×5",
+    summed CPU/GPU/memory, oldest age) at the position of its first member; an expanded group is followed by its
+    members (kind "member"). Single processes stay as they are (kind "proc"). The input order is kept."""
+    groups: dict[tuple, list[dict]] = {}
+    for p in procs:
+        groups.setdefault((p.get("ppid"), p.get("name")), []).append(p)
+    rows, done = [], set()
+    for p in procs:
+        key = (p.get("ppid"), p.get("name"))
+        members = groups[key]
+        if len(members) < 2:
+            rows.append({"kind": "proc", **p})
+            continue
+        if key in done:
+            continue
+        done.add(key)
+        ages = [m["age"] for m in members if m.get("age") is not None]
+        rows.append({"kind": "group", "key": key, "name": p.get("name"), "count": len(members), "pid": None,
+                     "ppid": key[0], "group": p.get("group"), "game": p.get("game"),
+                     "cpu": round(sum(m.get("cpu") or 0 for m in members), 1),
+                     "gpu": round(sum(m.get("gpu") or 0 for m in members), 1),
+                     "rss": sum(m.get("rss") or 0 for m in members), "age": max(ages) if ages else None,
+                     "critical": any(m.get("critical") for m in members),
+                     "locked": all(m.get("locked") for m in members),
+                     "context": all(m.get("context") for m in members), "members": members,
+                     "expanded": key in expanded})
+        if key in expanded:
+            rows += [{"kind": "member", **m} for m in members]
+    return rows

src/frameport/install/drives.py

@@ -0,0 +1,98 @@
+"""Games on another drive of the Frame (a microSD card, GitHub #90): which drives there are, where new games go
+(library setting `install.drive`) and moving an installed game. No Flet here (the CLI and GUI share it).
+
+The agent keeps each game's anchor (launch.sh, deployment.json, artwork) on internal storage and its files in
+`<drive>/FramePort/<package>`; a drive is given by its install dir (or mount point), internal storage by "internal"."""
+from __future__ import annotations
+
+import time
+
+from ..core import library
+from ..core.events import Reporter
+from ..frame.connection import AgentFailed, Frame
+
+SETTING = "install.drive"
+INTERNAL = "internal"
+
+
+def list_drives(frame: Frame) -> list[dict]:
+    """The agent's `drives`: [{id, path, install_dir, label, fstype, internal, removable, free_bytes, total_bytes,
+    usable, reason, games}]."""
+    return frame.agent("drives")["drives"]
+
+
+def install_dest() -> str | None:
+    """Where new games go (None = internal storage)."""
+    value = library.setting(SETTING) or INTERNAL
+    return None if value == INTERNAL else value
+
+
+def set_install_dest(install_dir: str | None) -> None:
+    library.set_setting(SETTING, install_dir or INTERNAL)
+
+
+def free_text(d: dict) -> str:
+    """"112.4 GiB free" ("" when unknown)."""
+    from ..i18n import tr
+
+    free = d.get("free_bytes")
+    return tr("{size:.1f} GiB free").format(size=free / 2**30) if isinstance(free, (int, float)) else ""
+
+
+def drive_text(d: dict) -> str:
+    """"SD Card · 112.4 GiB free" (labels for menus and dropdowns)."""
+    return " · ".join(filter(None, [d.get("label") or d.get("path"), free_text(d)]))
+
+
+def game_drive(dep: dict | None) -> dict | None:
+    """{"internal", "path", "label", "missing"} of an installed game (the agent's list_installed entry), or None for
+    agents before v63."""
+    if not dep or "drive" not in dep:
+        return None
+    return {**dep["drive"], "missing": bool(dep.get("drive_missing"))}
+
+
+def is_on(dep: dict | None, d: dict) -> bool:
+    """The game (list_installed entry) is on drive d (a `drives` entry)."""
+    g = game_drive(dep)
+    if not g:
+        return d.get("internal", False)
+    return bool(g["internal"]) if d.get("internal") else (not g["internal"] and g["path"] == d["path"])
+
+
+def move(frame: Frame, package: str, dest: str, reporter: Reporter, poll: float = 2.0,
+         timeout: float = 6 * 3600, sleep=time.sleep) -> dict:
+    """Move an installed game to `dest` (a drive's install dir or "internal"). The copy runs on the Frame by itself;
+    this follows its progress (a reconnect picks a running move of the same game up again). Cancel works until the
+    copy has started."""
+    reporter.stage("Move game files")
+    st = frame.agent("move_status")
+    if not (st.get("state") == "running" and st.get("package") == package):
+        reporter.check_cancel()
+        try:
+            st = frame.agent("move", package=package, dest=dest)
+        except AgentFailed as exc:
+            # a job that lost the Frame runs again: the move it started may have finished meanwhile
+            if "already there" in str(exc):
+                reporter.check("Game files moved", True, "already there")
+                return {"state": "done", "package": package}
+            raise
+        reporter.log(f"moving {st['from']} → {st['to']} ({st['total_bytes'] / 2**30:.1f} GiB"
+                     + (", same drive" if st.get("same_drive") else "") + ")")
+    end = time.time() + timeout
+    while time.time() < end:
+        st = frame.agent("move_status")
+        if st.get("state") in ("done", "failed"):
+            break
+        total, done = st.get("total_bytes") or 0, st.get("done_bytes") or 0
+        phase = {"copying": "Copying", "verifying": "Checking the copy", "removing": "Removing the old copy"}.get(
+            st.get("phase") or "", "Starting")
+        reporter.progress(done / total if total else 0.0,
+                          f"{phase} {done / 2**30:.1f}/{total / 2**30:.1f} GiB" if total else phase)
+        sleep(poll)
+    else:
+        raise RuntimeError("the move didn't finish in time; it may still be running on the Frame")
+    if st.get("state") != "done":
+        raise RuntimeError(f"moving failed: {st.get('error') or 'unknown error'} (the game stays where it was)")
+    reporter.check("Game files moved", True, st.get("base") or st.get("to") or "")
+    return st

src/frameport/install/installer.py

@@ -113,7 +113,7 @@ def install(frame: Frame, plan: InstallPlan, reporter: Reporter) -> dict:
         tags=_tags(plan.package),
         apk_name=plan.apk.name, settings=ctx.adapter_settings,
         files={k: v.decode() if isinstance(v, bytes) else v for k, v in ctx.files.items()}, env=ctx.env,
-        obb_manifest=manifest or None, flatscreen=_flatscreen(plan.package) or ctx.flatscreen,
+        obb_manifest=manifest or None, flatscreen=show_window(ctx, _flatscreen(plan.package)),
         recipe={"patches": sorted(plan.recipe.patches), "source": plan.recipe.source, "alt": plan.recipe.use_alt},
     )
     reporter.log(f"installed at {result['base']} (Steam shortcut id {result['appid']})")
@@ -227,13 +227,18 @@ class LinuxPlan:
     files: list[str] | None = None  # only these files of root (a lone AppImage), else the whole folder
     appimage: bool = False
     openxr: bool = False
+    x86_64: bool = False  # runs through FEX (installed on the Frame first, like Proton)
+    dest: str | None = None  # a drive's install dir for a new install (GitHub #90); None = internal storage
+    desktop_entry: bool = True  # an entry in Desktop Mode's menu and on its desktop (GitHub #84)
 
 
 def install_linux(frame: Frame, plan: LinuxPlan, reporter: Reporter) -> dict:
     """Upload an arm64 Linux app to the Frame (resumable, unchanged files aren't re-sent); the agent extracts
     AppImages, checks the app's libraries and writes its launcher (GitHub #31)."""
+    if plan.x86_64:
+        ensure_proton(frame, reporter, kind="linux_x86")
     reporter.stage("Prepare Frame")
-    prep = frame.agent("prepare_linux", package=plan.package, title=plan.title)
+    prep = frame.agent("prepare_linux", package=plan.package, title=plan.title, dest=plan.dest)
     if plan.files:
         manifest = {name: (plan.root / name).stat().st_size for name in plan.files}
     else:
@@ -255,9 +260,13 @@ def install_linux(frame: Frame, plan: LinuxPlan, reporter: Reporter) -> dict:
     reporter.stage("Finalize install")
     executables = [rel for rel in manifest if rel != plan.exe and _is_elf(plan.root / rel)][:200]
     result = frame.agent("finalize_linux", package=plan.package, title=plan.title, exe=plan.exe,
-                         appimage=plan.appimage, openxr=plan.openxr, manifests={"app": manifest},
-                         executables=executables, tags=_tags(plan.package), timeout=900)
+                         appimage=plan.appimage, openxr=plan.openxr, x86_64=plan.x86_64, manifests={"app": manifest},
+                         executables=executables, tags=_tags(plan.package), dest=plan.dest,
+                         desktop_entry=plan.desktop_entry, timeout=900)
     reporter.log(f"installed at {result['base']} (Steam shortcut id {result['appid']})")
+    if result.get("desktop_entry"):
+        reporter.check("Desktop Mode entry", True, "in the application menu"
+                       + (" and on the desktop" if result["desktop_entry"].get("desktop") else ""))
     return result
 
 
@@ -269,16 +278,19 @@ def _is_elf(path: Path) -> bool:
         return False
 
 
-def ensure_proton(frame: Frame, reporter: Reporter, tool: str | None = None, timeout: float = 45 * 60) -> dict:
+def ensure_proton(frame: Frame, reporter: Reporter, tool: str | None = None, timeout: float = 45 * 60,
+                  kind: str = "proton") -> dict:
     """Install Proton (ARM64) + its runtime on the Frame without user interaction: the agent writes Steam appmanifest
-    stubs and restarts Steam, which downloads them. Waits until they're installed (progress from the appmanifests)."""
+    stubs and restarts Steam, which downloads them. Waits until they're installed (progress from the appmanifests).
+    kind "linux_x86": FEX + its runtime instead, for x86_64 Linux apps (agent v60)."""
     import time
 
-    st = frame.agent("proton_status", tool=tool)
+    name = "Proton" if kind == "proton" else "FEX (x86 translation)"
+    st = frame.agent("proton_status", tool=tool, kind=kind)
     if st.get("ready"):
         return st["ready"]
-    reporter.stage("Install Proton on the Frame")
-    r = frame.agent("install_proton", mode="unattended", tool=tool)
+    reporter.stage(f"Install {name} on the Frame")
+    r = frame.agent("install_proton", mode="unattended", tool=tool, kind=kind)
     reporter.log(r.get("hint") or f"installing {r.get('tool')}")
     end = time.time() + timeout
     last = None
@@ -287,11 +299,11 @@ def ensure_proton(frame: Frame, reporter: Reporter, tool: str | None = None, tim
         reporter.check_cancel()
         time.sleep(10)
         try:
-            st = frame.agent("proton_status", tool=tool, timeout=60)
+            st = frame.agent("proton_status", tool=tool, kind=kind, timeout=60)
         except Exception:  # SSH can hiccup while Steam restarts
             continue
         if st.get("ready"):
-            reporter.check("Proton installed", True, st["ready"]["display_name"])
+            reporter.check(f"{name} installed", True, st["ready"]["display_name"])
             return st["ready"]
         dl = st.get("download") or {}
         sug = st.get("suggested") or {}
@@ -300,15 +312,15 @@ def ensure_proton(frame: Frame, reporter: Reporter, tool: str | None = None, tim
             # for it now
             asked_runtime = True
             reporter.log("installing the Steam Linux Runtime this Proton needs")
-            frame.agent("install_proton", mode="unattended", tool=tool)
+            frame.agent("install_proton", mode="unattended", tool=tool, kind=kind)
             continue
         if dl.get("total"):
-            reporter.progress(dl["done"] / dl["total"], f"downloading Proton {dl['done'] / 2**20:.0f}/"
+            reporter.progress(dl["done"] / dl["total"], f"downloading {name} {dl['done'] / 2**20:.0f}/"
                                                          f"{dl['total'] / 2**20:.0f} MiB")
         elif dl != last:
             reporter.log("waiting for Steam to start the download…")
         last = dl
-    raise RuntimeError("Proton didn't finish installing on the Frame in time; check Steam's downloads on the Frame")
+    raise RuntimeError(f"{name} didn't finish installing on the Frame in time; check Steam's downloads on the Frame")
 
 
 BIG_FILE = 8 << 20  # bigger files go one by one (resumable); smaller ones are streamed in batches
@@ -394,6 +406,14 @@ def is_flat_windows(package: str) -> bool:
     return bool(((g.get("analysis") or {}).get("extra") or {}).get("flat"))
 
 
+def show_window(ctx: base.InstallContext, automatic: bool) -> bool:
+    """Lepton's flat window for this install: the user's device.display_mode choice, else automatic (an app without VR
+    code), plus device.text_input_window (a VR app's window behind its VR view, for typing)."""
+    if ctx.display == "flat" or ctx.flatscreen:
+        return True
+    return automatic and ctx.display != "vr"
+
+
 def _flatscreen(package: str) -> bool:
     """An Android app without VR: Lepton must show it as a flat window (it never draws through OpenXR)."""
     from ..core import library

src/frameport/install/live_player.py

@@ -29,14 +29,21 @@ PLAYER_HTML = r"""<!doctype html>
 <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="snd" hidden title="Browsers start videos muted: click to hear the Frame. With sound the picture runs about a second behind (the browser buffers audio); muted it's a quarter of a second">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
+const FAR_BEHIND = 2.0, KEEP = 10;  // seconds behind the newest data
+// Catch-up per mode: keep `cushion` s behind the newest data, play at `rate` while more than `catchUp` behind.
+// With sound, Chrome keeps ~0.6 s of audio ahead and stalls below it, so playback settles ~1 s behind whatever we do
+// (measured 2026-10-07 against the Frame: 1.1x catch-up 8 stalls / 30 s, none 1-2, same average lag ~1 s; 50 ms
+// fragments no better). So with sound: no speed-up (stalls are audible), only the jump when > FAR_BEHIND.
+// Muted: ~0.2-0.3 s behind. (window.FP_TUNE overrides these: tests)
+const TUNE = Object.assign({muted: {cushion: 0.3, catchUp: 0.7, rate: 1.1},
+                            sound: {cushion: 0.3, catchUp: Infinity, rate: 1.0}}, window.FP_TUNE || {});
 let session = 0, frames = 0, lastFrames = 0, size = "";
 
 function say(text, state) { msg.textContent = text; dot.className = state || ""; }
@@ -80,9 +87,9 @@ async function run() {
   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;
+      const lag = end - video.currentTime, k = video.muted ? TUNE.muted : TUNE.sound;
+      if (lag > FAR_BEHIND || video.currentTime < sb.buffered.start(0)) video.currentTime = Math.max(end - k.cushion, 0);
+      else video.playbackRate = lag > k.catchUp ? k.rate : lag < k.cushion ? 1.0 : video.playbackRate;
       if (video.paused) video.play().catch(() => {});
     }
     pump();

src/frameport/install/livestream.py

@@ -9,12 +9,19 @@ starts at a keyframe. No image bytes ever go through Flet.
 """
 from __future__ import annotations
 
+import hashlib
 import json
+import logging
+import os
+import posixpath
 import queue
 import struct
 import threading
 import time
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+log = logging.getLogger(__name__)
 
 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)
@@ -204,6 +211,10 @@ class Relay:
         self.started = time.time()
         self.ended: str | None = None  # why the source stopped
         self._splitter = Mp4Splitter()
+        # on_join() asks the source for a keyframe now and says whether it will come (hardware encoder). Then a new
+        # viewer waits for it instead of getting the frames since the last one (seconds old with a long GOP).
+        self.on_join = None
+        self._waiting: set[int] = set()  # id() of client queues that wait for the next keyframe
 
     def feed(self, data: bytes) -> None:
         for kind, chunk in self._splitter.feed(data):
@@ -214,11 +225,15 @@ class Relay:
                     self.video_track = video_track_id(chunk)
                     continue
                 self.frames += 1
-                if fragment_is_keyframe(chunk, self.video_track):
+                key = fragment_is_keyframe(chunk, self.video_track)
+                if key:
                     self.gop = [chunk]
+                    self._waiting.clear()
                 elif self.gop:
                     self.gop.append(chunk)
                 for q in list(self.clients):
+                    if id(q) in self._waiting:
+                        continue
                     try:
                         q.put_nowait(chunk)
                     except queue.Full:  # too slow: drop it, its page reconnects (never block: we hold the lock)
@@ -236,12 +251,20 @@ class Relay:
         q: queue.Queue = queue.Queue(CLIENT_QUEUE)
         with self._lock:
             self.clients.append(q)
+            if self.on_join is None or self.init is None:
+                return self.init, list(self.gop), q
+            self._waiting.add(id(q))  # before asking: the keyframe may come back at once
+        if self.on_join():
+            return self.init, [], q
+        with self._lock:  # no keyframe coming: start from the buffered group as before
+            self._waiting.discard(id(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)
+            self._waiting.discard(id(q))
 
     def status(self) -> dict:
         with self._lock:
@@ -343,9 +366,11 @@ class _Server(ThreadingHTTPServer):
 # 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.
+# recording/Remote Play capture gamescope instead (only the flat Steam UI in VR).
+# Encoding: our own helper `fp_venc` (native/venc, spec in native/venc/SPEC.md) drives the Frame's hardware encoder
+# (qcom-iris, V4L2) - the stock ffmpeg h264_v4l2m2m hangs on it. It emits one H.264 frame per slot of an even fps
+# grid (half/third of the panel rate), so ffmpeg only adds sound and packs fMP4 (`-c:v copy`, `-framerate` = the
+# helper's fps). When the helper isn't there or its `--probe` fails, the old path runs: x264 at 30 fps on the CPU.
 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"
@@ -358,35 +383,86 @@ QUALITY = {  # max height (None = the headset view's own), bitrate
     "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.
+# Hardware path (fp_venc): bit/s targets, VBR up to HW_PEAK x the target. Bits are nearly free there (no CPU cost), and
+# 3 Mbit/s CBR at 720p36 showed heavy compression artifacts in the headset test (2026-10-07): head turns move the whole
+# picture, and CBR blurred exactly those frames.
+HW_BITRATE = {"360p": 1_500_000, "480p": 2_500_000, "720p": 5_000_000, "1080p": 8_000_000, "full": 10_000_000}
+HW_PEAK = 1.5
+VIDEO_INPUT_OFFSET = "-0.25"  # s: ffmpeg's video input vs pulse's late audio (see source_command)
+FPS = 30  # software (x264) path only; the hardware path picks an even fraction of the panel rate
+# Clocks (x264 path): 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
+HELPER = "fp_venc"
+HELPER_REMOTE = ".local/share/frameport/bin/fp_venc"  # under the Frame's home
+# stderr lines the script prints for the PC side: `live: encoder=hardware fps=32` / `live: encoder=software fps=30`
+INFO_PREFIX = "live: "
+
+
+def bitrate_bps(rate: str) -> int:
+    """ffmpeg-style "3M" / "1500k" → bit/s."""
+    mult = {"k": 1_000, "M": 1_000_000}.get(rate[-1:], 1)
+    return int(float(rate[:-1] if mult > 1 else rate) * mult)
 
 
 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)."""
+    Hardware encoder (fp_venc) when it probes fine, else x264. Exit 3 = no headset view device (SteamVR not running).
+    `fps` applies to the x264 path."""
     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")
+    hw_rate = HW_BITRATE.get(quality, HW_BITRATE[DEFAULT_QUALITY])
+    venc_args = (f'--source "$dev" --bitrate {hw_rate} --peak {int(hw_rate * HW_PEAK)}'
+                 + (f" --height {h}" if h else ""))
     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)
+# the PC kills this process group when a stop's stdin EOF doesn't end it (writes blocked on a full pipe)
+echo "{INFO_PREFIX}pgid=$(ps -o pgid= $$ | tr -d ' ')" >&2
 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
+venc=${{FP_VENC:-$HOME/{HELPER_REMOTE}}}
+info=
+[ -x "$venc" ] && info=$("$venc" --probe {venc_args} 2>/dev/null)
+hwfps=$(printf %s "$info" | sed -n 's/.*"fps":\\([0-9][0-9]*\\).*/\\1/p')
+if [ -n "$hwfps" ]; then
+  echo "{INFO_PREFIX}encoder=hardware fps=$hwfps" >&2
+  # fp_venc reads the SSH channel (stdin): "k" = keyframe, EOF = stop; ffmpeg then ends with it (-shortest).
+  # Raw H.264 has no timestamps. The input is stamped on arrival (wall clock, like pulse's audio) so ffmpeg reads both
+  # inputs in step; setts then numbers the frames on fp_venc's fps grid. Measured on the Frame (2026-10-07):
+  # arrival stamps alone bunched frames read together (gaps of 0-10 ms and 45+ ms: dropped-looking frames in the
+  # player); setts alone (no input stamps) held all output ~7 s next to the sound; -framerate is ignored;
+  # -fflags nobuffer lost the first seconds of a still picture's tiny frames; a big probesize waits seconds for one.
+  # frag_keyframe: a requested keyframe starts its own fragment, where a joining viewer can begin.
+  # -itsoffset {VIDEO_INPUT_OFFSET}: ffmpeg paces its inputs against each other, and pulse's audio arrives later than
+  # the wall clock (more while something plays), so the video input counted as "ahead" and ffmpeg stopped reading it
+  # for up to 0.7 s: fp_venc's writes blocked and 1080p dropped frames (owner's test 2026-10-07; busy 1080p replayed
+  # with sound: 20 s took 34-47 s). Shifting the video input back fixes that, but too far makes ffmpeg hold video for
+  # the interleave and release it in clumps (-1 s: output gaps up to 550 ms, a longer, stuttering delay in the
+  # browser, worse with sound on). Measured on the Frame with sound playing: -0.25 s = no stalled writes at busy 1080p
+  # and steady output (gaps 50-150 ms); -0.5 s already clumps (200-250 ms); none = 18 slow writes; PULSE_LATENCY_MSEC
+  # =20 made it worse. Only the input side moves: setts sets the output times, audio and video spans stay equal.
+  "$venc" {venc_args} --fps "$hwfps" | nice -n 10 ffmpeg -nostdin -hide_banner -loglevel error \\
+    -probesize 32 -analyzeduration 0 -use_wallclock_as_timestamps 1 -itsoffset {VIDEO_INPUT_OFFSET} \\
+    -f h264 -i pipe:0 "${{audio[@]}}" \\
+    -c:v copy -bsf:v "setts=ts=N*(1/$hwfps)/TB:duration=(1/$hwfps)/TB" -shortest \\
+    -f mp4 -movflags empty_moov+default_base_moof+frag_keyframe -frag_duration 100000 -
+  exit $?
+fi
+echo "{INFO_PREFIX}encoder=software fps={fps}" >&2
+exec 3<&0
 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} \\
@@ -398,6 +474,59 @@ wait $pid
 """
 
 
+def helper_path() -> Path | None:
+    """The bundled fp_venc (artifacts/linux-arm64-bin), None in builds without it."""
+    from ..core.paths import artifacts_dir
+
+    p = artifacts_dir() / "linux-arm64-bin" / HELPER
+    return p if p.is_file() else None
+
+
+def ensure_helper(frame) -> bool:
+    """Make sure the Frame has this app's fp_venc (sha256 compare, upload when different). False = it doesn't (the
+    stream then uses x264); never raises."""
+    local = helper_path()
+    if local is None:
+        return False
+    try:
+        from ..frame.connection import sh_quote
+
+        remote = f"{frame.home}/{HELPER_REMOTE}"
+        want = hashlib.sha256(local.read_bytes()).hexdigest()
+        _, out, _ = frame.run(f"sha256sum {sh_quote(remote)} 2>/dev/null")
+        if out.split()[:1] == [want]:
+            return True
+        frame.run(f"mkdir -p {sh_quote(posixpath.dirname(remote))}")
+        tmp = f"{remote}.new-{os.getpid()}-{threading.get_ident()}"  # own name: two starts at once don't collide
+        frame.put(local, tmp, resume=False)
+        code, _, err = frame.run(f"chmod 755 {sh_quote(tmp)} && mv -f {sh_quote(tmp)} {sh_quote(remote)}")
+        if code:
+            raise RuntimeError(err.strip())
+        return True
+    except Exception as exc:  # noqa: BLE001
+        log.warning("live view: couldn't put %s on the Frame (%s); using the software encoder", HELPER, exc)
+        return False
+
+
+STOP_GRACE = 2.0  # s to wait for the script to end after stdin EOF before killing its process group
+DROP_WARN = 0.05  # share of a stats window's frame slots that were late or skipped before the panel warns
+
+
+def window_stats(line: str, prev: dict[str, int]) -> tuple[dict[str, int], dict]:
+    """One `fp_venc: stats k=v ...` line (counters since the start) → (its counters, this window's figures:
+    frames, dropped = late + skipped slots, dropping = at least DROP_WARN of the window's slots, kbps)."""
+    counters = {}
+    for kv in line.split():
+        k, _, v = kv.partition("=")
+        if v.isdigit():
+            counters[k] = int(v)
+    d = {k: counters.get(k, 0) - prev.get(k, 0) for k in ("frames", "late", "skipped")}
+    dropped = d["late"] + d["skipped"]
+    slots = d["frames"] + d["skipped"]
+    return counters, {"frames": d["frames"], "dropped": dropped, "kbps": counters.get("kbps", 0),
+                      "dropping": slots > 0 and dropped >= DROP_WARN * slots}
+
+
 class FrameSource:
     """The stdout of `source_command` on the Frame, on its own SSH channel of the existing connection."""
 
@@ -405,8 +534,14 @@ class FrameSource:
         self.frame = frame
         self.quality = quality
         self.chan = None
+        self.info: dict[str, str] = {}  # from the script's `live: k=v ...` stderr lines (encoder, fps)
+        self.stats: dict = {}  # the hardware encoder's last 10 s (window_stats), for the panel
+        self._counters: dict[str, int] = {}
+        self._err = b""
+        self._last_error = ""
 
     def open(self):
+        ensure_helper(self.frame)
         transport = self.frame.client.get_transport()
         if transport is None or not transport.is_active():
             raise ConnectionError("not connected to the Frame")
@@ -416,28 +551,74 @@ class FrameSource:
         self.chan.exec_command("bash -c " + sh_quote(source_command(self.quality)))
         return self
 
+    def _read_stderr(self, final: bool = False) -> None:
+        while self.chan.recv_stderr_ready():
+            self._err += self.chan.recv_stderr(4096)
+        *lines, self._err = self._err.split(b"\n")
+        if final:
+            lines.append(self._err)
+            self._err = b""
+        for raw in lines:
+            line = raw.decode("utf-8", "replace").strip()
+            if line.startswith(INFO_PREFIX):
+                self.info.update(kv.split("=", 1) for kv in line[len(INFO_PREFIX):].split() if "=" in kv)
+            elif line.startswith(("fp_venc: info ", "fp_venc: stats ")):  # stats every 10 s: late/skipped frames
+                log.info("live view: %s", line)
+                if line.startswith("fp_venc: stats "):
+                    self._counters, self.stats = window_stats(line, self._counters)
+            elif line:
+                self._last_error = line
+
     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])
+        self._read_stderr(final=not data)
+        if not data and self._last_error:
+            raise RuntimeError(self._last_error)
         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 request_keyframe(self) -> bool:
+        """Ask the hardware encoder for a keyframe now (a viewer joined). False on the x264 path (no such request:
+        the relay then sends the frames since the last keyframe)."""
+        if self.info.get("encoder") != "hardware" or self.chan is None:
+            return False
+        try:
+            self.chan.sendall(b"k")
+            return True
+        except OSError:
+            return False
+
+    def close(self, grace: float = STOP_GRACE) -> None:
+        """EOF on the script's stdin stops the encoder. But when the stream is backed up, fp_venc sits in a blocked
+        write and never reads stdin, and once the channel is closed nothing drains ffmpeg's output either (found on
+        the Frame at 1080p, 2026-10-07: both left running, holding SteamVR's headset view open). So: wait a moment,
+        then end the script's process group from a second command."""
+        if self.chan is None:
+            return
+        try:
+            self.chan.shutdown_write()
+            deadline = time.time() + grace
+            while not self.chan.exit_status_ready() and time.time() < deadline:
+                while self.chan.recv_ready():  # drain, so a blocked writer can get to stdin
+                    self.chan.recv(65536)
+                time.sleep(0.05)
+            self._read_stderr()
+            pgid = self.info.get("pgid", "")
+            if not self.chan.exit_status_ready() and pgid.isdigit() and int(pgid) > 1:
+                log.info("live view: the stream didn't stop by itself; ending process group %s", pgid)
+                self.frame.run(f"kill -TERM -- -{pgid} 2>/dev/null; sleep 1; kill -KILL -- -{pgid} 2>/dev/null; true")
+        except Exception as exc:  # noqa: BLE001
+            log.warning("live view: stopping the stream on the Frame: %s", exc)
+        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()
+    live = LiveStream(src.open, src.close)
+    live.relay.on_join = src.request_keyframe
+    live.source_info = lambda: {**src.info, "stats": dict(src.stats)}
+    return live.start()
 
 
 class LiveStream:
@@ -456,6 +637,21 @@ class LiveStream:
         self._threads: list[threading.Thread] = []
         self._stop = threading.Event()
         self.on_end = None  # callback(reason) when the source stops by itself
+        # () -> {"encoder": "hardware"|"software", "fps": "32", "stats": window_stats(...)[1]} once the source said so
+        self.source_info = dict
+
+    def status(self) -> dict:
+        """The relay's status + what the source reported (encoder, fps, the encoder's last 10 s: dropped frames)."""
+        out = self.relay.status()
+        info = self.source_info()
+        if info.get("encoder"):
+            out["encoder"] = info["encoder"]
+        if str(info.get("fps", "")).isdigit():
+            out["fps"] = int(info["fps"])
+        stats = info.get("stats") or {}
+        if stats:
+            out["dropped"], out["dropping"] = stats.get("dropped", 0), bool(stats.get("dropping"))
+        return out
 
     @property
     def url(self) -> str:

src/frameport/locales/template.json

@@ -19,9 +19,11 @@
  " · link": "",
  " · not installed yet": "",
  " · on the Frame: ": "",
+ " · on {label}": "",
  " · restart the Frame soon to reset it": "",
  " · Revive provides the Oculus runtime": "",
  " · {human} in files": "",
+ " · {label} not inserted": "",
  " · {queued} more queued": "",
  " · {value:.0f} MiB": "",
  " · {value:.1f} GiB": "",
@@ -56,15 +58,17 @@
  "A game is running on the Frame": "",
  "A game is running on the Frame. Close it in the headset first, then try again.": "",
  "a known blocker": "",
- "A Linux app for arm64 (AppImage, .zip or .tar.gz)": "",
+ "A Linux app (AppImage, .zip or .tar.gz; arm64, or x86_64 through translation)": "",
  "A Meta Quest game (APK). It's rebuilt for the Frame and runs in Lepton, Valve's Android container.": "",
  "A native Linux program built for arm64 (aarch64), like the Frame's own CPU. It's installed unchanged and runs directly on SteamOS (no Android container, no Proton), started from the Frame's Steam library. VR apps use the Frame's OpenXR runtime.": "",
  "A new FramePort version is ready to install": "",
  "A newer known-good config for this game is available (you changed this game's settings, so it wasn't applied by itself).": "",
  "A recipe is the list of patches FramePort applies to a game before installing it. Known-good recipes were tested on a Frame; the others are suggested from the game's engine and VR API. Hover a patch for why it's there.": "",
  "A VR app made for another Android headset. OpenXR apps are translated like Quest games; apps built on a headset maker's own SDK (Pico, HTC Wave) can't run on the Frame.": "",
+ "A web page asked FramePort to install {name}.": "",
  "A Windows game without VR, added with \"Add one game folder…\". On the Frame, Proton runs it as a window (like Steam's own Windows games); it's in the Frame's Steam library.": "",
  "A Windows PC VR game (OpenXR, SteamVR or Oculus). It runs on this PC with SteamVR, or on the Frame with Proton. Oculus-only games also need Revive (Oculus → OpenXR).": "",
+ "A Windows program (.exe)": "",
  "A zip with FramePort's logs, the game's recipe and analysis, launch-test logs and the Frame's runtime details — enough to debug without the game files. IP addresses, host and user names, home folders and Steam ids are replaced by placeholders. Attach it to a GitHub issue.": "",
  "ABIs": "",
  "About": "",
@@ -72,9 +76,10 @@
  "AC Nexus: no AppSW at 72 Hz": "",
  "AC Nexus: no AppSW at 90 Hz": "",
  "Activity": "",
- "Add a Linux app (arm64)…": "",
  "Add a Linux app folder…": "",
+ "Add a Linux app…": "",
  "Add a tag": "",
+ "Add a Windows program (.exe)…": "",
  "Add an APK file": "",
  "Add an APK file…": "",
  "Add games": "",
@@ -87,6 +92,7 @@
  "Add {name}": "",
  "Added automatically (engine, VR API or store genre)": "",
  "Added automatically when needed": "",
+ "Added to Desktop Mode": "",
  "Added {n} game": [
   "",
   ""
@@ -98,6 +104,7 @@
  "Adds a small piece of Meta's platform library that some games need to start.": "",
  "Adds no-op com.oculus.os.AnalyticsEvent / UnifiedTelemetryLogger classes for native code that looks them up through the app class loader (e.g. Nano, NOPE Challenge).": "",
  "Adds OVRPort's OpenXR loader dispatcher and platform loader. Required: without it nothing is translated.": "",
+ "Adds the app to Desktop Mode's application menu and puts an icon on its desktop. Some apps work better there, with a mouse and keyboard, than in Gaming Mode, where Steam Input turns the controllers into a gamepad.": "",
  "Adds the parts that let a Quest game talk to the Steam Frame. Needed for every Quest game.": "",
  "Adds the VR app metadata other launchers expect.": "",
  "Advanced": "",
@@ -105,6 +112,7 @@
  "All at their defaults": "",
  "All games": "",
  "All of FramePort's data on this PC is gone": "",
+ "All {n} {name} processes ended.": "",
  "Allow swapchains larger than 4096 px": "",
  "Allows data backup.": "",
  "Allows reading the game's logs, which helps find problems.": "",
@@ -123,8 +131,10 @@
  "Analyze {title} again": "",
  "Android": "",
  "Android app": "",
+ "Android app (APK)": "",
  "Android app without VR: installed unchanged and shown as a flat window": "",
  "Android VR": "",
+ "Another app": "",
  "Answer the open install question first": "",
  "Any": "",
  "APK": "",
@@ -132,6 +142,7 @@
  "AppImage": "",
  "Apply the suggested patches and reinstall": "",
  "Apps that suggest controller bindings only for Meta's newer profiles (Touch Plus, Touch Pro), which the Frame's runtime rejects (XR_ERROR_PATH_UNSUPPORTED), get the same bindings as oculus/touch_controller instead (components Touch lacks are dropped). Without it such apps get no controller input.": "",
+ "arm64 (runs natively)": "",
  "Artwork for {get}": "",
  "Artwork updated ({src}). The Frame's Steam library still shows the old art.": "",
  "Artwork updated for {get}": "",
@@ -150,6 +161,7 @@
  "Back to library": "",
  "Back up the signing keys ({len}) to {shown_dir} first": "",
  "Banner": "",
+ "Battery": "",
  "Before a swapchain image is handed to the Frame, wait until the game's GPU work on it has finished, for games that hand over images early (an eye flickers or jitters). Costs some frame time. 2 = only after the first 60 s (compare both in one session).": "",
  "Before each Play on this PC, FramePort reads SteamVR's record of the game's last session (frames dropped; frame times from fpsVR if installed). If it dropped frames, it lowers the game's refresh rate to one whose frame budget fits (e.g. 96 → 90 Hz) and turns motion smoothing on, through SteamVR's per-application settings; each later session can step down again. Set a refresh rate or smoothing mode here to choose yourself. Ignored on the Frame.": "",
  "Best guess": "",
@@ -157,8 +169,11 @@
  "Browse and manage files on the Frame (Files tab): upload from this PC, download, rename, delete. Videos, Downloads and Documents are shared by every Quest game (/sdcard/Movies, /sdcard/Download, /sdcard/Documents); each installed game also has its own storage (its /sdcard). Apps find files by browsing folders. Video players that list only their own folder (e.g. 4XVR's Internal Storage = 4XPlayer): upload into that folder in the game's storage.": "",
  "Build page": "",
  "Cable connected.": "",
+ "Camera": "",
+ "can't hold games: {reason}": "",
  "Can't reach your Frame. Make sure it's on, awake and on the same network, then try again.": "",
  "Can't run": "",
+ "Can't use that link: {reason}": "",
  "Cancel": "",
  "Cancel all": "",
  "cancelled": "",
@@ -182,6 +197,9 @@
  "Check that the Frame and this computer are on the same network.": "",
  "Checking this PC…": "",
  "Checking tools…": "",
+ "Checking which app opens these links…": "",
+ "checksum checked": "",
+ "Choose \"Flat window\" if a phone/tablet app shows nothing in the headset, \"VR\" if a VR app opens as a flat window.": "",
  "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.": "",
@@ -215,21 +233,27 @@
  "Connecting the keyboard…": "",
  "Connecting to {value}…": "",
  "Connecting…": "",
+ "Connection lost, reconnecting…": "",
  "Content files from the game's data": "",
  "Continue": "",
+ "Controller input diagnostics (log)": "",
  "Controllers": "",
  "Converts Quest games to OpenXR": "",
  "Copied": "",
+ "Copies the game's files, data and saves to the other drive, checks the copy and then removes the old one. The Steam entry, settings and saves stay valid. The game must be closed. A game on a microSD card only starts while the card is inserted.": "",
  "Copy": "",
  "Copy all": "",
  "Copy failed; select the text instead": "",
  "Copy folder path": "",
  "Copy log": "",
+ "Copy name": "",
  "Copy OVRPlugin if VrApi is present": "",
  "Copy OVRPort libraries": "",
  "Copy path": "",
+ "Copy PID {pid}": "",
  "Couldn't check this PC": "",
  "Couldn't connect: {exc}": "",
+ "Couldn't list the Frame's drives: {error}": "",
  "Couldn't list the screenshots: {exc}": "",
  "Couldn't list {path}: {exc}": "",
  "couldn't load the full image: {exc}": "",
@@ -241,6 +265,9 @@
  "Couldn't use {choice}: {exc}": "",
  "Counts the headset as worn, so games that only move the player while it's worn get head tracking and controls (e.g. BONELAB).": "",
  "Cover": "",
+ "CPU": "",
+ "CPU cores": "",
+ "CPU {cpu} · GPU {gpu} · memory {mem} · {n} processes": "",
  "Create": "",
  "Customize": "",
  "Cylinder layers (curved menus and movie screens, e.g. 4XVR), which the Frame's runtime lacks, are shown as a few flat strips along the curve. 0 = drop them. 360° (equirect) layers can't be shown on the Frame.": "",
@@ -265,6 +292,8 @@
  "Deletes the rollback copies kept from each game's previous install and leftover uploads. The games and saves stay.": "",
  "Delete…": "",
  "Deselect": "",
+ "Desktop": "",
+ "Desktop Mode": "",
  "Details": "",
  "Dev builds let you test fixes before they're released. They're less tested than releases and may have bugs. You get the next release as a normal update (you have {version}).": "",
  "Developer Mode (on the Frame: Settings → System → Developer) lets FramePort find the Frame on your network and connect to it over SSH. The first-time setup command turns it on for you.": "",
@@ -283,6 +312,7 @@
  "Download": "",
  "Download all": "",
  "Download all ({n})…": "",
+ "Download and install": "",
  "Download selected": "",
  "Download to this PC": "",
  "Download to this PC…": "",
@@ -295,6 +325,7 @@
  ],
  "Download {n} screenshots…": "",
  "Downloaded when first needed": "",
+ "Downloaded {name}": "",
  "Downloaded {n} file to {folder}": [
   "",
   ""
@@ -314,6 +345,15 @@
  "Drops Quest-only shared library requirements.": "",
  "Each patch is described in plain words. Turn this on to also see its id, exactly what it changes in the game (useful when reporting a problem) and its parameters.": "",
  "Enabled by you.": "",
+ "End all": "",
+ "End all {n}": "",
+ "End all {n} {name}?": "",
+ "End game": "",
+ "End process": "",
+ "End the whole game": "",
+ "End {name}?": "",
+ "End {title}?": "",
+ "Ending this stops Steam, SteamVR or the desktop": "",
  "Enter the address": "",
  "Enter the Frame's address (e.g. steamos@frame.local or its IP)": "",
  "Environment variables exported by the launcher (e.g. VK_INSTANCE_LAYERS=\"\" to test without Valve's layers).": "",
@@ -322,6 +362,7 @@
  "Every game start on the Frame used to leak one kernel key, and after about 200 launches every game fails to start. FramePort switches that leak off, but keys already used only come back after a restart of the Frame.": "",
  "Every N seconds, saves the left-eye image the game submits (a quarter of its size) as fb_snap_0-7.ppm in the game's files folder on the Frame. Launch tests run without anyone wearing the headset, so the headset view stays black; this shows what the game itself draws. OpenGL ES games only.": "",
  "Every uploaded file is present with the right size.": "",
+ "Every {n}": "",
  "everything in ~ (not seen by games)": "",
  "Everything is up to date": "",
  "Executable": "",
@@ -338,6 +379,7 @@
  "Failed": "",
  "Failed: {error}": "",
  "Fake XR_FB_scene/spatial entities: a guardian-sized room with floor, ceiling and four walls, for mixed-reality games that build their level from the room (e.g. Demeter).": "",
+ "Fan": "",
  "Files": "",
  "Files and environment on the Frame": "",
  "Files and environment variables placed next to the game on the Frame.": "",
@@ -365,9 +407,10 @@
  "folder and everything in it": "",
  "Folder name": "",
  "Folder to upload to the Frame": "",
- "Folder with a Linux app for arm64": "",
+ "Folder with a Linux app": "",
  "Folder with VR games (Android APKs or PC VR games)": "",
  "For apps that only know Quest 3/Pro controllers: without it they get no buttons.": "",
+ "For buttons that do nothing or the wrong thing: logs each controller profile the game suggests bindings for and whether the runtime accepts it (with every path of a rejected one), which profile the runtime reports for each hand (a game without Steam Frame bindings gets SteamVR's Touch remap), OpenXR functions the game looks up that the runtime lacks, and failing input, vibration and performance calls. Each line once. No effect on the game.": "",
  "For games that crash right after you return to them (e.g. after the Steam menu).": "",
  "For games that freeze the Frame when a controller vibrates (e.g. Lucky's Tale). Needs a rebuild.": "",
  "For games that judder or shimmer while you hold your head still (e.g. I Am Cat).": "",
@@ -382,13 +425,22 @@
  "For Unreal games whose models flicker or show through walls and windows on the Frame (e.g. Into The Radius 2). Needs a rebuild.": "",
  "For Vulkan games whose models flicker or vanish while you look at them (e.g. Into The Radius 2). Needs a rebuild.": "",
  "Force enable passthrough": "",
+ "Force kill": "",
+ "Force kill all": "",
+ "Force kill all {n}": "",
+ "Force kill all {n} {name}?": "",
+ "Force kill {name}?": "",
  "Found": "",
+ "fps isn't reported for PC VR and Linux games": "",
+ "fps · target {hz} Hz": "",
+ "fps: waiting for the game's first frames": "",
  "Frame agent": "",
  "Frame battery: charging": "",
  "Frame battery: not charging": "",
  "Frame OpenXR compatibility layer": "",
  "FrameBridge OpenXR adapter": "",
  "FramePort": "",
+ "FramePort can't add {name}: drop an APK, a Linux build (.zip, AppImage), a Windows program (.exe) or a folder": "",
  "FramePort can't replace itself in {value} (no permission): opening the release page to download it": "",
  "FramePort checks GitHub for a new release every few hours and shows it in the sidebar and the Library. \"Update now\" downloads it, checks its checksum (and on Windows its signature), closes FramePort and opens the new version; your games, settings and Frame connection are kept. With automatic install, the download happens in the background and the new version starts next time.": "",
  "FramePort found more than one arm64 program in this app. Pick the one that starts it (helpers such as crash reporters or updaters are the wrong choice).": "",
@@ -414,6 +466,7 @@
  "FramePort's tools, library, artwork and the signing keys of your rebuilt games. Back it up: an update must be signed with the same key, or the game (and its saves) has to be reinstalled.": "",
  "FramePort's translator between the game and the Steam Frame: fills in what the Frame lacks (controllers, room, passthrough). Needed for every converted game.": "",
  "Frames in Developer Mode show up here.": "",
+ "frames per second": "",
  "Free up space": "",
  "Free up space on the Frame": "",
  "Free up space?": "",
@@ -427,8 +480,11 @@
  "Game config files": "",
  "Game configs are up to date": "",
  "Game configs from GitHub: last checked {when}": "",
+ "Game data (.obb) not found": "",
+ "game data (OBB)": "",
  "Game launch capacity": "",
  "Game not found": "",
+ "Game page": "",
  "Game settings": "",
  "Game settings · {title}": "",
  "Game settings. ": "",
@@ -436,6 +492,7 @@
  "Game settings…": "",
  "Game storage": "",
  "Game's choice": "",
+ "Game: the running FramePort game's processes (its Android container or Proton) plus the busiest others. Steam & SteamVR: Steam, SteamVR and the desktop. All: every program of your user on the Frame. A lock marks programs whose end would close Steam, SteamVR or the desktop.": "",
  "Games see this folder as {value}": "",
  "Games that ask the headset for its controller models (Meta's runtime controller models, XR_FB_render_model) get the Steam Frame controllers instead of Quest Touch controllers. The models come from the Frame's own SteamVR and are converted on the Frame at install time. Games that ship their own controller meshes aren't affected. Turning it on needs a rebuild (it adds a small library in front of OVRPort's loader).": "",
  "Generate OVRPort config": "",
@@ -453,8 +510,13 @@
  "GL wrapper: OpenGL ES depth formats (Minecraft)": "",
  "Go to my library": "",
  "Go to System and turn on \"Enable Developer Mode\". A Developer page appears in Settings; nothing else changes, your games and data stay as they are.": "",
+ "GPU": "",
  "Graphics": "",
+ "Group": "",
+ "hardware encoder": "",
  "Hide Android's navigation bar": "",
+ "Hide details": "",
+ "Hide its processes": "",
  "Hide log": "",
  "Hide patches": "",
  "Hide Quest foveation": "",
@@ -467,7 +529,12 @@
  "Higher keeps more detail but uses more memory.": "",
  "Higher looks sharper but needs more power; lower runs smoother. 1.0× is the game's own.": "",
  "Home folder": "",
+ "hottest: {part}": "",
  "How a PC VR game starts: Proton runs the Windows program on the Frame; for Oculus games, Revive translates the Oculus API to OpenXR.": "",
+ "How Lepton runs the app: VR (headless Android, only what the app draws through OpenXR reaches the headset) or a flat window (Lepton's lepton-show-flatscreen marker: the Android window on a screen in the headset, like a phone or tablet app). Automatic uses a flat window for apps without VR code. Choose \"Flat window\" for a 2D app FramePort took for VR (it shows nothing in the headset), \"VR\" for a VR app FramePort took for 2D.": "",
+ "How Lepton shows an Android app: VR (the headset shows what the app draws through OpenXR) or a flat window (a phone/tablet app on a screen in the headset). Automatic picks a window for apps without VR code.": "",
+ "How much of the time the Frame's graphics chip was busy, added up from every program that draws (the game, SteamVR's compositor, Steam). Near 100 % the game can't keep its frame rate.": "",
+ "How often the Frame sends new numbers": "",
  "How often the picture updates. Higher is smoother if the game can keep up.": "",
  "How well the game runs on the Steam Frame. \"Works\" and \"Works with issues\" come from recipes tested on a real Frame. \"Untested\" means FramePort suggested a recipe from the game's engine and VR API that nobody has confirmed yet. \"Can't run\" means there's a known blocker (for example a 32-bit-only game).": "",
  "I played it in the headset with this recipe": "",
@@ -477,15 +544,21 @@
  "If you know the Frame's address.": "",
  "Ignore focus dips up to": "",
  "Image for the {label}": "",
+ "In the menu and on the desktop": "",
  "In your Steam library": "",
  "In your Steam library · launch settings changed — update it": "",
  "Install": "",
  "Install anyway": "",
  "Install dev build": "",
  "Install dev build {version}?": "",
+ "Install from a link": "",
+ "Install from a link…": "",
  "Install it anyway to try it, e.g. with different patches.": "",
  "Install Lepton on the Frame": "",
+ "Install link: {host}": "",
+ "Install links": "",
  "Install missing": "",
+ "Install new games to": "",
  "Install on Frame": "",
  "Install on this PC": "",
  "Install Proton on the Frame": "",
@@ -495,6 +568,7 @@
  "Install the latest dev build…": "",
  "Install updates automatically (downloads in the background, installs when FramePort next starts)": "",
  "Install {len} on this PC": "",
+ "Install {name}?": "",
  "Install {n} on Frame": "",
  "Install {title} anyway?": "",
  "Install {title} on {value}": "",
@@ -507,7 +581,9 @@
  "Installs the app as it is, unpacked on the Frame, with an entry in its Steam library": "",
  "Installs the app as it is, with an entry in the Frame's Steam library": "",
  "Installs the game exactly as it is: no patches (your copy is already patched)": "",
+ "Internal storage": "",
  "into {value}": "",
+ "It belongs to a running game, which may stop with it.": "",
  "It can't be reached (asleep, turned off or out of Wi-Fi). Wake it or turn it on: FramePort continues by itself, and uploads pick up where they stopped.": "",
  "It doesn't run: report…": "",
  "It has a known blocker on the Steam Frame.": "",
@@ -518,6 +594,9 @@
  "It will be closed without saving. Continue?": "",
  "It won't start on the Frame: SteamOS doesn't have these libraries and the app doesn't bring them. Look for a build of the app that includes them, then install that one.": "",
  "It works: share…": "",
+ "it's here now": "",
+ "its drive": "",
+ "Its manifest asks for Android {version} (API {api}); the Frame's Android is 11 (API 30). Apps like this often crash at start, but not always: try it, a launch test tells.": "",
  "Java runtime": "",
  "Java, OVRPort and apksigner are ready.": "",
  "just now": "",
@@ -535,6 +614,7 @@
  "Language packs from the game's files": "",
  "Last build": "",
  "Last launch test: {get} · furthest: {value}": "",
+ "late": "",
  "Later": "",
  "Launch log": "",
  "Launch log · {title}": "",
@@ -568,8 +648,12 @@
  "Lets you read logs/attach. Some Unreal games abort under CheckJNI when debuggable; the Frame 'nodebug' fix undoes it.": "",
  "Lets you type into this app's text fields on the Frame (they'd close at once).": "",
  "Library": "",
+ "Link": "",
  "Linux": "",
+ "Linux app": "",
  "Linux app (arm64)": "",
+ "Linux build": "",
+ "Linux builds must be made for arm64 (x86_64 builds run through translation, slower).": "",
  "Linux VR app · OpenXR": "",
  "Live": "",
  "Live view": "",
@@ -582,6 +666,7 @@
  "Logs details for debugging: composition layers and swapchains, focus changes, play-space creation, pointer vs grip poses, refresh rates. No effect on the game.": "",
  "Logs every Meta Platform SDK request the game makes (user, entitlement, cloud saves, ...) and the messages that answer them, and every 10 s the requests that never got an answer (logcat tag fp_ovrtrace, in launch.log). For games that wait forever on a loading screen (e.g. Vader Immortal after its intro). Changes nothing: every call goes to the real function.": "",
  "Longer for headsets that briefly think they're off your head.": "",
+ "Looking for drives…": "",
  "Looking for Frames on your network…": "",
  "Looking for the Frame on a USB cable (Developer Mode on, USB-C port connected to this computer).": "",
  "Looking for your Frame…": "",
@@ -600,6 +685,8 @@
  "Marks the game as a VR app so headsets show it as one.": "",
  "Maximum": "",
  "Maximum size in pixels of each face of the cube the 360° image is converted to (256–2730). Higher is sharper but uses more GPU memory.": "",
+ "Memory": "",
+ "Memory in use by everything on the Frame. \"Waiting\" is the share of time programs had to wait for memory in the last 10 s: when it climbs, the Frame is running out and may freeze or close a game.": "",
  "Menus and screens": "",
  "Meta Quest": "",
  "Meta XR Audio: skip Quest telemetry class": "",
@@ -611,7 +698,14 @@
  "Mirrored": "",
  "Mixed reality": "",
  "Mixed-reality games that build their level from your room get a simple room with walls.": "",
+ "Modem": "",
+ "Monitor": "",
+ "Monitor is using {pct} % of the Frame's CPU": "",
  "More actions": "",
+ "Move": "",
+ "Move to…": "",
+ "Move {title} to {label}": "",
+ "Move {title} to…": "",
  "Moves where the pointer starts, forward or back.": "",
  "Moves where the pointing ray starts forward (+) or back (−).": "",
  "Multiplies the recommended eye-buffer width and height (0.5–2.0). 1.5 ≈ 2.25× pixels.": "",
@@ -621,26 +715,32 @@
  "Needed by another patch": "",
  "Needs the Oculus Platform (Meta Horizon app) for its license check, which the Frame doesn't have — it crashes at startup there. Play it on this PC.": "",
  "Needs Windows (or WSL on Windows)": "",
+ "Network": "",
  "Neutralises Meta XR Audio's Quest-only calls (Unity/Wwise).": "",
  "never": "",
  "New config applied: use Update on Frame to install it": "",
  "New folder": "",
  "New folder…": "",
  "New Frame? Run one command on it and FramePort does the rest. Did this once already? Your Frame appears under step 2.": "",
+ "New games go to {label}": "",
  "New name": "",
  "Next": "",
  "No": "",
  "No activity": "",
  "no answer from the Frame": "",
  "No artwork could be downloaded from that {source} result; the current artwork stays. Try another one.": "",
+ "no checksum": "",
  "No dev build is published right now": "",
  "No folders to rescan yet: add games with Scan a folder": "",
+ "No Frame is connected: the game is added to your library now and installs once the Frame is connected.": "",
+ "No FramePort game is running. Start one in the headset or with Play, or switch the filter to see everything on the Frame.": "",
  "No Frames found. New Frame? Use first-time setup (step 1). Otherwise make sure Developer Mode is on (Settings → System → Developer) and the Frame is on the same network.": "",
  "No games found in that folder": "",
  "No limit": "",
  "No matching files": "",
  "No new games in {name}": "",
  "No notes.": "",
+ "No process matches.": "",
  "No release notes.": "",
  "No screenshots yet": "",
  "No Unreal crash reporter": "",
@@ -650,14 +750,18 @@
  "None": "",
  "None found": "",
  "Normal": "",
+ "Not connected: {error}": "",
  "Not enough space on the Frame": "",
  "Not enough space on the Frame ({detail}). Remove games you don't play or use Free up space on the Steam Frame page.": "",
  "Not from a FramePort game": "",
  "Not installed": "",
+ "Not needed in the last build, OVRPort fixed it itself: {names}": "",
+ "Not needed in the last build: OVRPort fixed this itself.": "",
  "Not now": "",
  "Not offered by Steam on this Frame yet": "",
  "Not recommended: breaks games that load VrApi through OVRPlugin.": "",
  "Not set up": "",
+ "Not set up yet (FramePort registers itself when it starts).": "",
  "Not streaming": "",
  "Not verified on many games yet: try it if the game doesn't work without it.": "",
  "Notes (what you checked, known issues)": "",
@@ -667,13 +771,16 @@
  "Nothing running. Installs, launch tests and downloads show up here.": "",
  "Nothing to install": "",
  "Nothing to install on the Frame — those Oculus games need PC mode (SteamVR + Revive).": "",
+ "Nothing to install: add the games' .obb files first": "",
  "Nothing to patch: it runs as is.": "",
  "Now {scale:.0%}.": "",
  "Now {scale:.0%}. Changes apply the next time FramePort starts.": "",
  "Now {scale:.0%}; {new:.0%} after restarting FramePort.": "",
+ "NPU": "",
  "Oculus game — needs Revive, which doesn't run on the Frame. Play it on this PC (SteamVR).": "",
  "Oculus OS telemetry class stubs": "",
  "Oculus XR Plugin games render both eyes in one pass (multiview) on Android. If one eye shows only effects or grey (e.g. I Am Cat), rendering each eye in its own pass can fix it, at some GPU cost. Rewrites OculusSettings.GetStereoRenderingMode and its inlined read in OculusLoader.Initialize -> MultiPass in libil2cpp.so (found with Cpp2IL). Try it when one eye is wrong.": "",
+ "Off: these links open whatever app is set up for them, if any.": "",
  "off: {names}": "",
  "Offline": "",
  "Older workaround for upside-down quads: rotates them 180° (quads are single-sided; prefer flip_emul).": "",
@@ -689,10 +796,15 @@
  "One PC VR game folder": "",
  "Only if 360° pictures show wrongly.": "",
  "Only if 360° pictures show wrongly: 1 = upside down, 2 = mirrored, 4 = turned around (add values to combine).": "",
+ "Only install software from sites you trust. FramePort downloads it from {host} and installs it on your Frame.": "",
+ "Only internal storage": "",
  "Open": "",
+ "Open \"Install with FrameDrop\" buttons (framedrop:// links) in FramePort": "",
+ "Open frameport:// links in FramePort": "",
  "Open game": "",
  "Open GitHub issue": "",
  "Open viewer": "",
+ "Open {scheme}:// links with FramePort?": "",
  "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).": "",
@@ -701,6 +813,8 @@
  "OR": "",
  "Or paste text to type it in one go": "",
  "Or turn on Developer Mode on the Frame (Settings → System → Developer): it then shows up under step 2. Open Settings → Developer → Pair new host on the Frame, click Connect there and approve FramePort. That way needs no connection into this computer.": "",
+ "Other": "",
+ "other file": "",
  "Override the guardian depth (0 = use guardian, min 1.5 m).": "",
  "Override the guardian width (0 = use guardian, min 1.5 m).": "",
  "OVRPort converts Quest games from Meta's own VR APIs to standard OpenXR. These are its optional patches.": "",
@@ -714,6 +828,7 @@
  "Package": "",
  "Pairing: on the Frame open Settings → Developer → Pair new host, then approve FramePort.": "",
  "Password (first time only)": "",
+ "Paste the address of an \"Install with FrameDrop\" button (right-click it → Copy link), a FramePort or FrameDrop manifest (.json) or a direct link to an APK, a Linux build (.zip) or a Windows program (.exe).": "",
  "Patch Meta XR Audio": "",
  "Patch Oculus detection for Unity": "",
  "Patch Oculus detection for Unreal": "",
@@ -722,6 +837,8 @@
  "Patches every game of this kind gets (on by default). Customize lists them all.": "",
  "Patches for what the Frame's runtime does differently from a Quest (graphics formats, missing OpenXR extensions, Lepton's launcher requirements).": "",
  "Patches that can't matter for this game (wrong engine or API) are hidden. Show them to force one on anyway.": "",
+ "Pause": "",
+ "Paused": "",
  "Paused: Frame battery low, plug it in": "",
  "Paused: waiting for your Frame": "",
  "PC VR": "",
@@ -730,6 +847,7 @@
  "PC VR games (Proton)": "",
  "PC VR games can run on this PC only with Windows (or WSL on Windows)": "",
  "PC VR games on this PC run through SteamVR, so a headset connected to this PC works with them.": "",
+ "PC VR via Proton": "",
  "PC VR · Oculus": "",
  "PC VR · Proton": "",
  "PC VR —": "",
@@ -741,6 +859,7 @@
  "Picture": "",
  "pictures for the Steam library": "",
  "Pictures you took in the headset (Steam screenshots on the Frame)": "",
+ "PID": "",
  "Platform compat (ovrMessageType_ToString)": "",
  "Play on Frame": "",
  "Play on this PC": "",
@@ -751,11 +870,14 @@
  "Pointer start": "",
  "Pointer turn": "",
  "Points Oculus games at Revive on the Frame.": "",
+ "Power": "",
+ "Power ICs": "",
  "Prepare {title}": "",
  "Pretend room layout": "",
  "Prevents a start-up crash in some Unreal games.": "",
  "Previous": "",
  "Problems and feedback": "",
+ "Processes": "",
  "Program": "",
  "Proton couldn't run a test program (see the log)": "",
  "Proton debug log (Frame)": "",
@@ -770,6 +892,7 @@
  "Puts settings files next to the game on the Frame (e.g. to turn off an unsupported effect).": "",
  "Quality": "",
  "Quest": "",
+ "Quest game": "",
  "Quest games (Lepton)": "",
  "Quest ✓": "",
  "Quest ✓: Lepton is installed, so Quest games can run. PC VR ✓: Proton is installed, so PC VR games can run on the Frame.": "",
@@ -788,6 +911,7 @@
  "Recipe": "",
  "Recipe reset": "",
  "Recipes tested on a real Frame: bundled with FramePort, fetched from the online catalog, and the ones you saved as known-good.": "",
+ "Reconnect": "",
  "Recreate spaces after the first frames (diagnostic).": "",
  "Refresh": "",
  "Refresh rate": "",
@@ -809,6 +933,7 @@
  "Remove VrApi library": "",
  "Remove XR_KHR_composition_layer_depth chains (diagnostic).": "",
  "Remove {title} from the library?": "",
+ "Removed from Desktop Mode": "",
  "Removed the converted copies ({size})": "",
  "Removed {title}": "",
  "Removed {title} and deleted its files on this PC ({size})": "",
@@ -860,6 +985,9 @@
  "Room width": "",
  "Rotate quads 180°": "",
  "Routes OVRPlugin through FramePort's extension shim, which turns Meta's amplitude-envelope vibrations into plain ones: OVRPort's loader reads their nanosecond duration as seconds and allocates gigabytes, freezing the Frame when the game vibrates a controller (e.g. Lucky's Tale's save slots, GitHub #9). Needs a rebuild.": "",
+ "Running": "",
+ "running for {t}": "",
+ "Running now": "",
  "Runs directly — no Revive needed": "",
  "Runs natively on SteamOS, started from the Frame's Steam library": "",
  "Runs Oculus PC games on OpenXR": "",
@@ -887,6 +1015,7 @@
  "Search": "",
  "Search again": "",
  "Search games and tags": "",
+ "Search name, PID or game": "",
  "Search the stores instead": "",
  "Searched a moment ago.": "",
  "Searching…": "",
@@ -911,8 +1040,11 @@
  "Show 360° backgrounds and videos": "",
  "Show advanced settings": "",
  "Show all patches ({len} don't apply to this game)": "",
+ "Show as VR or as a flat window": "",
  "Show curved menus and screens": "",
+ "Show details": "",
  "Show hidden files": "",
+ "Show its processes": "",
  "Show less": "",
  "Show log": "",
  "Show more": "",
@@ -924,6 +1056,7 @@
  "Show technical details (patch ids, exact effects, parameters)": "",
  "Show the app's Android window (for typing)": "",
  "Show video panels": "",
+ "Showing the top {shown} of {n} rows: search to find others.": "",
  "Showing {len} of {n}": "",
  "Shows 3D 360° pictures flat if they look doubled.": "",
  "Shows the Frame's cameras where the game expects passthrough.": "",
@@ -941,7 +1074,9 @@
  "Skips a Quest-only reporting step in Meta's audio library that crashes some games.": "",
  "Skips Meta XR Audio's telemetry under x86_64 ARM translation (emulators). Not needed on the Frame, which runs games natively.": "",
  "Sleep": "",
+ "software encoder": "",
  "Some apps open a flat Android launcher that then starts a separate VR activity (e.g. WiiCompiled). Shown with Lepton's flat window, that window stays in view after the VR part starts. This makes the VR activity the one Lepton starts (its LAUNCHER category), so the app opens in VR with no flat window. Everything only the launcher does (choosing or importing content) is skipped: turn it off for a run when you need the launcher, and turn off \"Show the app's Android window\".": "",
+ "Some developers put an \"Install with FrameDrop\" button on their site (the protocol of the FrameDrop sideloader). FramePort reads the same links: it shows what the link offers, asks, downloads it, adds it to your library and installs it on the Frame. Only https links to public servers are used. Windows and Linux open these links in FramePort; on macOS, paste the link into Add games → Install from a link….": "",
  "Some engines leave the pNext of unused Vulkan attachment references uninitialized. The Frame's driver never reads it, but Lepton always loads Steam's Fossilize shader-cache layer, which follows it and crashes on the first frame (SIGSEGV in libVkLayer_fossilize.so from FVulkanRenderPass, e.g. Deadpool VR). Loads Vulkan through a small shim that keeps valid pointers and drops only unreadable ones or ones pointing at the wrong structure type. It also drops a depth resolve named in a subpass without a depth attachment, which crashes the Frame's driver at the first render pass (e.g. Metro Awakening).": "",
  "Some game folders are already set up for SteamVR: a Revive copy (LibRevive64.dll) next to the game, started by a small loader DLL (e.g. xinput1_3.dll) that Windows loads from the game's folder. Then FramePort starts the game program directly — like double-clicking it — instead of through its own Revive (two Revives conflict; e.g. the Oculus Platform check then fails). On the Frame, Wine is told to use those loader DLLs from the game folder instead of its own.": "",
  "Some games keep content in separate files next to their OBB (e.g. Star Wars: Tales from the Galaxy's Edge: its seasons and sound banks) and ask Meta's platform for them as asset files. OVRPort's platform loader doesn't know them, so the game waits for content that never arrives (black screen after loading). Lists the content files shipped with the game's data (*.pak) as installed and answers their download request at once with the file's path; nothing is copied or downloaded. Shares the language-pack library.": "",
@@ -970,6 +1105,7 @@
  "Steadier head tracking": "",
  "Steady controller input after focus": "",
  "Steam": "",
+ "Steam & SteamVR": "",
  "Steam for Windows not found": "",
  "Steam Frame": "",
  "Steam Frame patches": "",
@@ -989,6 +1125,7 @@
  "Stops some Unreal games from closing themselves right after starting.": "",
  "Stops strict debugging checks that make some games quit.": "",
  "Stops Unreal's crash reporter, which can block the game from starting.": "",
+ "Storage": "",
  "Store details for {n} game": [
   "",
   ""
@@ -1001,6 +1138,7 @@
  "Suggested for this game": "",
  "Swap eyes": "",
  "Swap left/right views (diagnostic).": "",
+ "swap {n}": "",
  "Swapchain format fallback": "",
  "Swaps in an OpenXR OVRPlugin for games that use VrApi through OVRPlugin (older Unity/Unreal).": "",
  "Switch Frame…": "",
@@ -1010,6 +1148,8 @@
  "tall, 600 × 900": "",
  "Team Beef ports: treat the Frame as a Meta headset": "",
  "Team Beef's ports (e.g. Lambda1VR, RTCWQuest) load an OpenXR library named after the headset maker and pick their VR setup by maker; for \"valve\" they stop at start (libopenxr_loader_valve.so not found) or take the Pico path. Adds that library and lets them take the Meta path.": "",
+ "Temperature": "",
+ "Temperatures and fan": "",
  "Test": "",
  "Test Proton on the Frame": "",
  "Text and layout size": "",
@@ -1020,6 +1160,10 @@
  "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 keep up at this quality: {n} frame dropped in the last 10 seconds. Choose a lower quality for a smoother picture.": [
+  "",
+  ""
+ ],
  "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.": "",
@@ -1035,35 +1179,47 @@
  "The Frame went offline: {exc}": "",
  "The Frame's battery is at {pct} % and not charging. Plug it in (a strong charger, not a PC port): long installs can drain it, and FramePort pauses them at {pause} %.": "",
  "The Frame's battery is at {pct} %: installs paused so it doesn't switch off mid-upload. Plug it in; the queue continues by itself.": "",
+ "The Frame's CPU is arm64. Programs built for x86_64 PCs run through FEX, Valve's x86 translator, with the x86 libraries SteamOS ships for it (glibc, Mesa) - the way Steam on the Frame runs x86 Linux games. That works for many programs but is slower: use an arm64 build when there is one.": "",
  "The Frame's desktop password, only needed the first time so FramePort can add its own key. After that it connects with the key.": "",
  "The Frame's Steam couldn't start {title} (Steam error {code}). Please send a problem report so we can see why.": "",
  "The Frame's Steam didn't accept {title}'s library entry, so FramePort added it as \"Devkit Game: …\" instead. Starting it now — put the headset on.": "",
  "The Frame's Steam library still shows the old artwork.": "",
  "the game didn't pass its checks (see the list above)": "",
+ "The game is closed the way Steam's Exit game does it; if it doesn't stop, FramePort stops it. Progress that the game hasn't saved is lost.": "",
  "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 monitor isn't connected.": "",
+ "The monitor shows your Frame's games, load, temperatures and battery live once FramePort is connected to it.": "",
+ "the other app": "",
  "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 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. The Frame's hardware video encoder does the work (if it isn't available, the processor does, which costs a game more); stop the stream 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.": "",
+ "The time the Frame spends collecting these numbers": "",
  "The upload to the Frame was damaged on the way. Try again (a cable or the Frame's hotspot is more reliable than a busy Wi-Fi).": "",
  "The VR runtime games talk to. On the Frame that's SteamVR.": "",
  "These games can't run on the Steam Frame": "",
  "These games check their Oculus license": "",
+ "These games keep their content in a data file (.obb), and none was found next to their APK. Without it they hang at start. Put the .obb files in a folder named like the game's package (or obb/) next to the APK and add the folder again. Tick any you still want to install.": "",
  "These installs need about {need} on the Frame, and it has {free} free. Remove games you don't play (or use Free up space on the Steam Frame page), or install fewer at once.": "",
+ "These links open FramePort.": "",
+ "These links will open FramePort instead of {app}. You can switch back in {app}, or by turning this setting off.": "",
  "They are deleted on the Frame and can't be restored. Steam's own screenshot list may still show them until Steam restarts.": "",
+ "They are part of Steam, SteamVR or the desktop: the headset view or Steam may restart, and anything running in the headset may stop.": "",
  "They use the Oculus Platform SDK, which comes with the Meta Horizon (Oculus) app — it isn't installed on this PC, so they may quit right after starting. FramePort doesn't change how a game checks its license. Untick the ones you'd rather skip.": "",
  "They use the Oculus Platform SDK, which comes with the Meta Horizon (Oculus) app. It doesn't exist on the Steam Frame, so there they crash right at startup (seen with Robo Recall, Lies Beneath and Lone Echo) — play them on this PC. Tick any you still want to try on the Frame.": "",
  "They're Oculus games that need Revive to reach VR, and Revive can't run on the Frame. Play them on this PC instead (Install on this PC — SteamVR + Revive). Tick any you still want to put on the Frame to experiment (they'll likely run flat or crash).": "",
- "This computer's keyboard works as a keyboard on your Frame while this window is open. In the headset, select a text field (in a game or app, in Steam or on the desktop), then type here.": "",
+ "This app looks like a website in an Android wrapper: it opens the site in Meta's browser, which the Frame doesn't have. If nothing opens, use the website in a browser instead.": "",
+ "This computer's keyboard works as a keyboard on your Frame while this tab is open. In the headset, select a text field (in a game or app, in Steam or on the desktop), then type here.": "",
  "This deletes the {what} on the Frame. It can't be undone.": "",
  "This folder is empty. Upload files with the buttons above.": "",
  "This Frame isn't set up for FramePort yet. Run the first-time setup: Steam Frame → Show setup command.": "",
  "This game can't run on the Steam Frame.": "",
  "This game is marked \"Can't run\" on the Steam Frame:": "",
+ "This game's data file (.obb) wasn't found next to the APK. Put the .obb files in a folder named {package} (or obb/) next to the APK and add the folder again; without it the game hangs at start.": "",
  "This game's folder has several programs and FramePort isn't sure which one starts the game. Open the game (or right-click → Change executable) to pick it.": "",
  "this PC": "",
  "This PC (for PC VR games)": "",
@@ -1071,6 +1227,7 @@
  "This PC's disk is full. Free some space and try again.": "",
  "This removes:": "",
  "This source checkout has uncommitted changes: commit or stash them, then update": "",
+ "This system can't send web links to FramePort: use Add games → Install from a link…": "",
  "Tilts the controllers' pointing ray up (+) or down (−), for games whose pointer doesn't hit what you aim at.": "",
  "To finish, close FramePort and delete its program folder.": "",
  "Today": "",
@@ -1102,9 +1259,8 @@
  "Type": "",
  "Type it": "",
  "Type on Frame": "",
- "Type on Frame: use this keyboard on the Frame": "",
- "Type on Frame…": "",
  "Typed it, except characters the Frame's US keyboard layout doesn't have: {chars}": "",
+ "Typing on the Frame works once FramePort is connected to it.": "",
  "ufw is active. Allow the setup port with: sudo ufw allow {port}/tcp (and afterwards: sudo ufw delete allow {port}/tcp)": "",
  "Uninstall": "",
  "Uninstall FramePort": "",
@@ -1160,6 +1316,8 @@
  "Upside down": "",
  "Upside down and mirrored": "",
  "Use controllers": "",
+ "Use FramePort": "",
+ "Use FramePort for these links": "",
  "Use tags to group and filter your library": "",
  "Use the new config": "",
  "Use the repack's launcher (bundled Revive)": "",
@@ -1203,12 +1361,17 @@
  "Waiting for the Frame": "",
  "Waiting for your Frame": "",
  "Waiting for your Frame… (code {code})": "",
+ "waiting {pct} %": "",
  "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)": "",
+ "What the whole Frame draws right now (its main power rail), with the share of the CPU and the graphics chip. Higher power means more heat and a shorter battery.": "",
+ "What your Frame is doing right now": "",
  "What's new": "",
  "Where it's installed": "",
+ "Where new games go on the Frame: its internal storage or another drive, such as a microSD card (in a FramePort folder on it). Games you installed already stay where they are; move one with right-click → Move to…. The launcher and Steam entry always stay on internal storage. Drives formatted as FAT, exFAT or NTFS can't hold games (Android and Proton need Linux file permissions): format the card in SteamOS first.": "",
+ "Where the power goes": "",
  "Where this game's recipe came from: catalog (tested on a Frame), heuristics (suggested by FramePort) or user (changed by you).": "",
  "Which program starts {get}?": "",
  "Which Proton build runs the game on the Frame: the stable Proton (the default: smoother in our tests) or Proton Experimental (gets Valve's ARM64 fixes first; try it when a game doesn't start or runs badly). Also takes any compat tool name from the Frame's ARM64 list.": "",
@@ -1218,6 +1381,7 @@
  "Windows": "",
  "Windows game (Proton)": "",
  "Windows not detected": "",
+ "Windows program": "",
  "Windows treats this network as public and its firewall blocks the Frame. In Windows' network settings set this network to Private (or allow FramePort on public networks when Windows asks).": "",
  "Windows' firewall for WSL blocks the Frame from reaching FramePort. Open the setup command again and allow the change when Windows asks (admin).": "",
  "Windows' firewall for WSL blocks the Frame. Open the setup command again and allow the change when Windows asks (admin).": "",
@@ -1233,6 +1397,7 @@
  "Writes config files into the game's Android/data/<package>/files/ on the Frame, to turn off engine features the Frame doesn't support (e.g. a CryEngine user.cfg with r_variable_rate_shading = 0, as The Climb 2 needs).": "",
  "Writes liboverport.config.so with runtime options.": "",
  "Writes the conversion's settings into the game.": "",
+ "x86_64: runs through FEX (x86 translation, slower; FramePort installs FEX on the Frame)": "",
  "XR_FB_passthrough via ALPHA_BLEND (Frame greyscale cameras).": "",
  "Yes": "",
  "Yes: uses the Frame's OpenXR runtime": "",
@@ -1240,6 +1405,7 @@
  "You already have the latest dev build ({version})": "",
  "You have the latest version as of the last check ({when}).": "",
  "You have {version}. {how}": "",
+ "You pasted a link to {name}.": "",
  "Your copy is used as it is (only the Frame's copy gets launch patches)": "",
  "Your custom recipe": "",
  "your Frame": "",
@@ -1250,11 +1416,13 @@
  "Your own artwork for {title}": "",
  "Your own game files aren't touched.": "",
  "Your own tags (filled) can be anything you like. Outlined tags are added automatically from the engine, VR API and store genres. Filter the library by either.": "",
+ "{app} opens these links on this PC.": "",
  "{count} files · {human}": "",
  "{count} on": "",
  "{display_name} can be installed (about 1 GiB; Steam restarts once)": "",
  "{display_name} installed": "",
  "{display_name} is installed on your Frame": "",
+ "{fps} fps": "",
  "{free:.0f} GiB free · {len} games installed": "",
  "{get} is installed on this PC — launch it from your Steam library or the Play button (SteamVR starts with it)": "",
  "{get} is installed on {where}, but the launch test needs a look": "",
@@ -1264,6 +1432,7 @@
  "{human} · {files} files": "",
  "{int} h ago": "",
  "{int} min ago": "",
+ "{label} (not inserted)": "",
  "{label} ({host}) isn't reachable. Make sure it's switched on and on the same network.": "",
  "{label} removed for {title}.": "",
  "{label} updated for {title}.": "",
@@ -1272,7 +1441,13 @@
  "{len} selected": "",
  "{message} The Frame's Steam library still shows the old art.": "",
  "{n_pc} on this PC": "",
+ "{name} (PID {pid}) is asked to close.": "",
+ "{name} (PID {pid}) stops at once without saving anything.": "",
+ "{name} ended.": "",
+ "{name} is part of Steam, SteamVR or the desktop. Ending it can close the headset view or restart Steam, and anything running in the headset may stop.": "",
+ "{name} is still running.": "",
  "{name} isn't a Linux app (an AppImage, a Linux program or a .zip/.tar archive)": "",
+ "{name}: waiting for your answer": "",
  "{n} file": [
   "",
   ""
@@ -1314,6 +1489,9 @@
   "",
   ""
  ],
+ "{n} of the {name} processes are still running.": "",
+ "{n} processes": "",
+ "{n} processes named {name} with the same parent are ended.": "",
  "{n} screenshot": [
   "",
   ""
@@ -1330,11 +1508,15 @@
  "{on} on your Frame": "",
  "{rate}/s": "",
  "{remaining} more after this": "",
+ "{size:.1f} GiB free": "",
  "{title} couldn't be added to the Frame's Steam library: {why}": "",
+ "{title} ended.": "",
  "{title} failed: {error}": "",
  "{title} is already running on the Frame — put the headset on": "",
  "{title} is already starting — put the headset on": "",
+ "{title} is still running.": "",
  "{title} isn't in the Frame's Steam library yet: adding it (Steam restarts once)": "",
+ "{title} moved to {label}": "",
  "{title} will be in the Frame's Steam library when the game that's running is closed": "",
  "{title} will be in the Frame's Steam library when you're back in Gaming Mode: start it from there": "",
  "{title}: analyzed again": "",
@@ -1342,6 +1524,7 @@
  "{title}: done": "",
  "{title}: launch test {verdict} (furthest: {value})": "",
  "{title}: Steam artwork updated on the Frame": "",
+ "{used} of {total}": "",
  "{user}@{host} · {get} {get2} (build {get3})": "",
  "{value:.0f} MiB": "",
  "{value:.1f} GiB": "",

src/frameport/patches/base.py

@@ -58,6 +58,7 @@ class InstallContext:
     env: dict[str, str]  # extra Lepton env exports
     adapter_settings: dict[str, Any]
     flatscreen: bool = False  # show the app's Android window (Lepton's lepton-show-flatscreen) even for a VR app
+    display: str = ""  # device.display_mode: "vr" / "flat" = the user's choice, "" = automatic (2D apps get a window)
 
 
 class Patch:

src/frameport/patches/frame/haptic_envelope.py

@@ -0,0 +1,63 @@
+"""Detects OVRPort's fix for the haptic-envelope bug, which makes `adapter.haptic_fix` unnecessary.
+
+OVRPort's dispatcher (libopenxr_loader.so) turns XrHapticAmplitudeEnvelopeVibrationFB into 100 Hz samples. Runtimes
+up to 3.4.3-23204ea used the envelope's duration (nanoseconds) as seconds when counting them: one vibration asked for
+gigabytes (Lucky's Tale froze the Frame, BattleSisters was killed for 11 GB). Runtime 3.4.3-aa54c3f converts it first
+(ovrport/app#73): right after the type check for the envelope (XR_TYPE_HAPTIC_AMPLITUDE_ENVELOPE_VIBRATION_FB =
+1000173001) it builds the constant 1e9 (`count * 1e9 / duration` = samples per second), which the buggy code never
+had. Verified in the headset with Lucky's Tale and haptic_fix off (2026-10-07). See patches/upstream.py.
+"""
+from __future__ import annotations
+
+import struct
+
+from ..upstream import UpstreamFix, code_words, constants, find_constant_load, lib_probe, register
+
+DISPATCHER = "libopenxr_loader.so"
+ENVELOPE_TYPE = 1000173001  # XR_TYPE_HAPTIC_AMPLITUDE_ENVELOPE_VIBRATION_FB
+WINDOW = 48  # instructions after the type check that hold the sample count (the fix: 7 after it)
+NS_PER_S = {struct.unpack("<Q", struct.pack("<d", v))[0] for v in (1e9, 1e-9)} | \
+           {struct.unpack("<I", struct.pack("<f", v))[0] for v in (1e9, 1e-9)}
+
+
+def _literals(data: bytes, offsets: list[int], words: list[int]) -> list[int]:
+    """Values loaded PC-relative (LDR literal: GP w/x, SIMD s/d) by the given instructions."""
+    out = []
+    for off, w in zip(offsets, words, strict=True):
+        if w & 0x3B000000 != 0x18000000:  # LDR (literal), GP (V=0) or SIMD (V=1)
+            continue
+        size = {0: 4, 1: 8}.get(w >> 30)  # opc: w / s = 4 bytes, x / d = 8 (q isn't a scalar constant)
+        if size is None:
+            continue
+        imm19 = (w >> 5) & 0x7FFFF
+        target = off + ((imm19 - (1 << 19)) if imm19 & (1 << 18) else imm19) * 4
+        if 0 <= target <= len(data) - size:
+            out.append(int.from_bytes(data[target:target + size], "little"))
+    return out
+
+
+def envelope_duration_fixed(data: bytes) -> bool | None:
+    """True when the dispatcher converts the envelope duration from nanoseconds (OVRPort's fix), False when its
+    envelope code has no such conversion (the bug), None when there's no envelope code to judge."""
+    code = list(code_words(data))
+    offsets, words = [o for o, _ in code], [w for _, w in code]
+    seen = False
+    start = 0
+    while (i := find_constant_load(words[start:], ENVELOPE_TYPE)) is not None:
+        i += start
+        seen = True
+        window = slice(i, i + WINDOW)
+        if NS_PER_S & set(constants(words[window])) or NS_PER_S & set(_literals(data, offsets[window], words[window])):
+            return True
+        start = i + 1
+    return False if seen else None
+
+
+register(UpstreamFix(
+    id="ovrport.haptic_envelope",
+    workaround="adapter.haptic_fix",
+    title="OVRPort converts the vibration envelope's duration from nanoseconds",
+    upstream="ovrport/app#73 (runtime 3.4.3-aa54c3f)",
+    probe=lib_probe(DISPATCHER, envelope_duration_fixed),
+    tracker="#74",
+))

src/frameport/patches/frame/ovr_microphone.py

@@ -7,12 +7,16 @@ Walking Dead: Saints & Sinners Ch. 2) dereferences a NULL stream: SIGSEGV in lib
 seconds after the logo. Meta's own library allows that order. The function is rewritten in place (same size) to return
 0 while no stream is open and behave as before otherwise.
 
-Upstream: Android-XR-Bridge/OVRPort#2, ovrport/app#73; tracked in GitHub #73 (drop this patch once fixed upstream).
+Upstream: Android-XR-Bridge/OVRPort#2, ovrport/app#73; tracked in GitHub #73. OVRPort runtime 3.4.3-aa54c3f checks
+the handle and the stream itself (returns 48000 without one): builds made with it leave this patch out
+(`microphone_checked`, patches/upstream.py).
 """
 from __future__ import annotations
 
 from ...analysis import elf
 from ..base import ApkContext, Patch, Suggestion, register
+from ..upstream import UpstreamFix, lib_probe
+from ..upstream import register as register_upstream_fix
 
 LOADER = "libovrplatformloader.so"
 FUNC = "ovr_Microphone_GetOutputBufferMaxSize"
@@ -31,9 +35,8 @@ def _words(data: bytes | bytearray, off: int, n: int) -> list[int]:
     return [int.from_bytes(data[off + 4 * i:off + 4 * i + 4], "little") for i in range(n)]
 
 
-def guard_microphone(data: bytes) -> bytes | None:
-    """The loader with a NULL-stream check in ovr_Microphone_GetOutputBufferMaxSize, or None if the function isn't
-    OVRPort's unchecked 7-instruction version (already fixed, Meta's library, another OVRPort build)."""
+def _function_offset(data: bytes, size: int) -> int | None:
+    """File offset of FUNC in the loader (None: not an ELF, no such export, or shorter than `size` bytes)."""
     try:
         dynsym = elf._elf(data).get_section_by_name(".dynsym")
     except Exception:  # noqa: BLE001
@@ -41,9 +44,31 @@ def guard_microphone(data: bytes) -> bytes | None:
     found = dynsym.get_symbol_by_name(FUNC) if dynsym is not None else None
     if not found or not found[0]["st_value"]:
         return None
-    vaddr = found[0]["st_value"]
-    off = elf.vaddr_to_offset(elf.load_segments(data), vaddr)
-    if off is None or off + 28 > len(data):
+    off = elf.vaddr_to_offset(elf.load_segments(data), found[0]["st_value"])
+    return off if off is not None and off + size <= len(data) else None
+
+
+def microphone_checked(data: bytes) -> bool | None:
+    """True when OVRPort's GetOutputBufferMaxSize tests something (a cbz/cbnz) before its first call, as the fixed
+    runtime does; False when it is the unchecked version this patch rewrites; None when it can't tell."""
+    if guard_microphone(data) is not None:
+        return False
+    off = _function_offset(data, 48)
+    if off is None:
+        return None
+    for word in _words(data, off, 12):
+        if word & BL_MASK == BL:
+            return None
+        if word & 0x7E000000 == 0x34000000:  # CBZ / CBNZ (32 or 64 bit)
+            return True
+    return None
+
+
+def guard_microphone(data: bytes) -> bytes | None:
+    """The loader with a NULL-stream check in ovr_Microphone_GetOutputBufferMaxSize, or None if the function isn't
+    OVRPort's unchecked 7-instruction version (already fixed, Meta's library, another OVRPort build)."""
+    off = _function_offset(data, 28)
+    if off is None:
         return None
     w = _words(data, off, 7)
     if w[:3] != [STP, MOV_FP, LDR_STREAM] or w[3] & BL_MASK != BL or w[4:] != [SXTW, LDP, RET]:
@@ -88,3 +113,11 @@ class OvrMicrophone(Patch):
 
 
 register(OvrMicrophone)
+register_upstream_fix(UpstreamFix(
+    id="ovrport.microphone_stream",
+    workaround=OvrMicrophone.id,
+    title="OVRPort checks for an unopened microphone stream",
+    upstream="ovrport/app#73 (runtime 3.4.3-aa54c3f)",
+    probe=lib_probe(LOADER, microphone_checked),
+    tracker="#73",
+))

src/frameport/patches/settings.py

@@ -103,6 +103,11 @@ SETTINGS = [
      "For one eye looking wrong (e.g. a jittering right eye): logs each eye's submitted pose against a fresh one, the "
      "eye-to-eye relation and when each eye's image was released, also into framebridge.log in the game's storage "
      "(some games stop Android's log early). No effect on the game."),
+    ("input_diag", "int", 0, "Controller input diagnostics (log)",
+     "For buttons that do nothing or the wrong thing: logs each controller profile the game suggests bindings for and "
+     "whether the runtime accepts it (with every path of a rejected one), which profile the runtime reports for each "
+     "hand (a game without Steam Frame bindings gets SteamVR's Touch remap), OpenXR functions the game looks up that "
+     "the runtime lacks, and failing input, vibration and performance calls. Each line once. No effect on the game."),
     ("release_wait", "int", 0, "Wait for the game's GPU before showing an image",
      "Before a swapchain image is handed to the Frame, wait until the game's GPU work on it has finished, for games "
      "that hand over images early (an eye flickers or jitters). Costs some frame time. 2 = only after the first 60 s "
@@ -276,7 +281,7 @@ UI: dict[str, dict] = {
     **{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", "rect_clamp", "gl_hide_msrtt", "strip_color_bias", "snapshot",
-        "strip_depth", "respace_kick", "layer_debug", "eye_debug", "release_wait", "vk_hide_fdm")},
+        "strip_depth", "respace_kick", "layer_debug", "eye_debug", "input_diag", "release_wait", "vk_hide_fdm")},
 }
 
 
@@ -451,6 +456,25 @@ class Foveation(Patch):
         ctx.env.update(self.ENV.get(ctx.params.get("mode") or "", {}))
 
 
+class DisplayMode(Patch):
+    id = "device.display_mode"
+    title = "Show as VR or as a flat window"
+    description = ("How Lepton runs the app: VR (headless Android, only what the app draws through OpenXR reaches the "
+                   "headset) or a flat window (Lepton's lepton-show-flatscreen marker: the Android window on a screen "
+                   "in the headset, like a phone or tablet app). Automatic uses a flat window for apps without VR "
+                   "code. "
+                   "Choose \"Flat window\" for a 2D app FramePort took for VR (it shows nothing in the headset), "
+                   "\"VR\" for a VR app FramePort took for 2D.")
+    category = "device"
+    needs_vr = False
+    stage = "install"
+    params = [Param("mode", "str", "", "vr or flat (empty = automatic)")]
+    CHOICES = (("", "Automatic"), ("vr", "VR"), ("flat", "Flat window"))
+
+    def install(self, ctx: InstallContext) -> None:
+        ctx.display = ctx.params.get("mode") if ctx.params.get("mode") in ("vr", "flat") else ""
+
+
 class TextInputWindow(Patch):
     id = "device.text_input_window"
     title = "Show the app's Android window (for typing)"
@@ -481,4 +505,5 @@ register(DeviceFiles)
 register(LeptonEnv)
 register(HideNavBar)
 register(TextInputWindow)
+register(DisplayMode)
 register(Foveation)

src/frameport/patches/summaries.py

@@ -82,6 +82,8 @@ SUMMARIES = {
     "device.hide_navbar": "Hides Android's back/home/recents buttons, which cover the app's own buttons.",
     "device.text_input_window": "Lets typing reach this app: Steam's on-screen keyboard or your computer's keyboard "
                                 "(VR is unaffected).",
+    "device.display_mode": "Choose \"Flat window\" if a phone/tablet app shows nothing in the headset, \"VR\" if a VR "
+                           "app opens as a flat window.",
     "device.lepton_env": "Extra settings for the Android container (for testing).",
     "device.foveation": "Try \"Fixed\" or \"Off\" if one eye shimmers or jitters while menus look fine.",
     # PC VR

src/frameport/patches/upstream.py

@@ -0,0 +1,152 @@
+"""Upstream fixes that make one of our workarounds unnecessary, applied per build.
+
+Several patches work around bugs in what OVRPort puts into a converted APK (its closed-source runtime libraries, its
+CLI). When upstream fixes such a bug, users don't all get the fix at once: OVRPort downloads runtime builds into its
+workspace and each conversion uses whichever one it picks, so one library can hold games built with the old and the
+new runtime. A version number doesn't help either (runtime builds are named `<version>-<commit>`, the commit part is
+unordered). So each fix is detected in the converted APK itself: a probe looks at the bytes OVRPort produced, and when
+it finds the upstream fix, the build leaves the workaround out.
+
+The recipe is never changed: it still asks for the fix (`adapter.haptic_fix` on), the build decides how to provide it.
+A build made with an old runtime keeps the workaround; the next build with a fixed runtime drops it by itself, and a
+build made with a later runtime that regressed would get the workaround back. Builds record what was left out
+(`build.superseded`), the installer leaves those out of settings.conf too, and the build log says why.
+
+Add one: write a probe (True = the upstream fix is there, False = the bug is there, None = can't tell, e.g. the library
+is missing or looks different) and `register(UpstreamFix(...))` in the workaround's own module. Only True drops the
+workaround, so a probe that can't recognise newer code errs on the safe side. Then update the workaround's tracker
+issue (`upstream` label). FRAMEPORT_KEEP_WORKAROUNDS=1 keeps every workaround (to compare builds).
+"""
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..apk.workspace import ApkWorkspace
+    from ..core.events import Reporter
+
+Probe = Callable[["ApkWorkspace"], "bool | None"]
+
+
+@dataclass(frozen=True)
+class UpstreamFix:
+    id: str  # e.g. "ovrport.haptic_envelope"
+    workaround: str  # the patch id this fix makes unnecessary, e.g. "adapter.haptic_fix"
+    title: str  # what upstream fixed, for the build log
+    upstream: str  # where it was fixed, e.g. "ovrport/app#73 (runtime 3.4.3-aa54c3f)"
+    probe: Probe
+    tracker: str = ""  # our tracking issue, e.g. "#74"
+
+
+REGISTRY: dict[str, UpstreamFix] = {}
+
+
+def register(fix: UpstreamFix) -> UpstreamFix:
+    if not fix.id or fix.id in REGISTRY:
+        raise ValueError(f"bad or duplicate upstream fix id {fix.id!r}")
+    REGISTRY[fix.id] = fix
+    return fix
+
+
+def lib_probe(library: str, check: Callable[[bytes], bool | None]) -> Probe:
+    """A probe that runs `check` on one of the APK's native libraries (None when the APK doesn't have it)."""
+    def probe(ws: ApkWorkspace) -> bool | None:
+        return check(ws.read_lib(library)) if ws.abi and ws.has(ws.lib(library)) else None
+
+    return probe
+
+
+@dataclass
+class Resolution:
+    patches: dict  # the selection this build applies
+    superseded: dict[str, str] = field(default_factory=dict)  # workaround patch id -> upstream fix id
+    found: dict[str, bool | None] = field(default_factory=dict)  # upstream fix id -> probe result (for the log)
+
+
+def resolve(ws: ApkWorkspace, patches: dict, reporter: Reporter | None = None) -> Resolution:
+    """Leave out the workarounds whose upstream fix is in this (converted) APK."""
+    from . import base
+
+    base.load_all()
+    res = Resolution(dict(patches))
+    if os.environ.get("FRAMEPORT_KEEP_WORKAROUNDS"):
+        return res
+    for fix in REGISTRY.values():
+        if fix.workaround not in patches:
+            continue
+        try:
+            found = fix.probe(ws)
+        except Exception as e:  # noqa: BLE001  (a probe that breaks must not break the build: keep the workaround)
+            found = None
+            if reporter:
+                reporter.log(f"upstream fix check {fix.id} failed ({e}); keeping {fix.workaround}")
+        res.found[fix.id] = found
+        if found:
+            res.patches.pop(fix.workaround, None)
+            res.superseded[fix.workaround] = fix.id
+            if reporter:
+                reporter.log(f"not needed: {fix.workaround} ({fix.title}, fixed upstream in {fix.upstream})")
+    return res
+
+
+def without_superseded(patches: dict, superseded) -> dict:
+    """A recipe's selection minus the workarounds a build left out (for the install of that build)."""
+    return {pid: params for pid, params in patches.items() if pid not in (superseded or ())}
+
+
+# ---------------------------------------------------------------- arm64 helpers for probes
+
+def code_words(data: bytes):
+    """(file offset, instruction word) for every word of the library's executable sections."""
+    from ..analysis import elf
+
+    for sec in elf._elf(data).iter_sections():
+        if sec["sh_type"] == "SHT_PROGBITS" and sec["sh_flags"] & 0x4:  # SHF_EXECINSTR
+            start, size = sec["sh_offset"], sec["sh_size"]
+            for off in range(start, start + size - 3, 4):
+                yield off, int.from_bytes(data[off:off + 4], "little")
+
+
+def move_wide(word: int) -> tuple[str, int, int, int, int] | None:
+    """Decode MOVZ/MOVK/MOVN: (kind, sf, rd, imm16, shift) or None."""
+    kinds = {0x52800000: "movz", 0x72800000: "movk", 0x12800000: "movn"}
+    kind = kinds.get(word & 0x7F800000)
+    if kind is None:
+        return None
+    return kind, word >> 31, word & 31, (word >> 5) & 0xFFFF, ((word >> 21) & 3) * 16
+
+
+def constants(words) -> list[int]:
+    """Every value a register holds after each MOVZ/MOVK/MOVN in a run of instruction words (how compilers build
+    64-bit constants such as doubles: movz + movk)."""
+    regs: dict[int, int] = {}
+    out = []
+    for w in words:
+        mw = move_wide(w)
+        if mw is None:
+            continue
+        kind, sf, rd, imm, shift = mw
+        mask = (1 << 64) - 1 if sf else (1 << 32) - 1
+        if kind == "movz":
+            regs[rd] = imm << shift
+        elif kind == "movn":
+            regs[rd] = ~(imm << shift) & mask
+        else:
+            regs[rd] = (regs.get(rd, 0) & ~(0xFFFF << shift) | imm << shift) & mask
+        out.append(regs[rd])
+    return out
+
+
+def find_constant_load(words: list[int], value: int) -> int | None:
+    """Index of the first MOVZ/MOVN that starts building `value` (32-bit) in its register, followed by the MOVK that
+    completes it within the next few instructions."""
+    for i, w in enumerate(words):
+        mw = move_wide(w)
+        if mw is None or mw[0] == "movk":
+            continue
+        if value in constants(words[i:i + 4]):
+            return i
+    return None

src/frameport/pipeline.py

@@ -9,6 +9,7 @@ PC (Revive + local Steam) or on the Frame (Proton + Revive).
 """
 from __future__ import annotations
 
+import dataclasses
 import threading
 import time
 from pathlib import Path
@@ -21,6 +22,7 @@ from .core import library
 from .core.events import Reporter
 from .core.models import Recipe, SourceGame
 from .core.paths import output_dir
+from .patches import upstream
 from .recommend import engine
 from .sources import quest_dump, rift_dump
 from .targets.base import Target
@@ -284,9 +286,33 @@ def is_linux(entry: dict) -> bool:
     return entry.get("kind") == "linux"
 
 
+def analysis_warnings(entry: dict) -> list[str]:
+    """Blockers read from a Quest/Android game's APK, for the CLI (the game page shows them as callouts)."""
+    if is_rift(entry) or is_linux(entry) or not entry.get("analysis"):
+        return []
+    out = engine.blocker_notes(library.analysis_from_dict(entry["analysis"]))
+    if missing_obb(entry):
+        out.append(MISSING_OBB_NOTE.format(package=entry.get("package", "<package>")))
+    return out
+
+
+MISSING_OBB_NOTE = ("This game's data file (.obb) wasn't found next to the APK. Put the .obb files in a folder named "
+                    "{package} (or obb/) next to the APK and add the folder again; without it the game hangs at start.")
+
+
+def missing_obb(entry: dict) -> bool:
+    """A Quest game whose APK expects an OBB (analysis expects_obb: Unreal's bHasOBBFiles) but no data folder was
+    found next to it (GitHub #85: TRIANGLE STRATEGY hung silently after OVRPlugin's JNI_OnLoad). Library fields
+    only: no disk access (used by the game page)."""
+    if is_rift(entry) or is_linux(entry):
+        return False
+    extra = (entry.get("analysis") or {}).get("extra") or {}
+    return bool(extra.get("expects_obb")) and not (entry.get("data_dir") and entry.get("data_bytes") != 0)
+
+
 def add_linux_app(path: Path | str, reporter: Reporter | None = None, exe: str | None = None) -> dict:
-    """Add an arm64 Linux app to the library (no conversion: it's installed as it is). `exe` overrides the program
-    FramePort picked (relative to the app's folder)."""
+    """Add a Linux app to the library (no conversion: it's installed as it is): arm64, or x86_64 (run through FEX on
+    the Frame). `exe` overrides the program FramePort picked (relative to the app's folder)."""
     from .analysis import linux
     from .core.models import Recipe
 
@@ -294,18 +320,22 @@ def add_linux_app(path: Path | str, reporter: Reporter | None = None, exe: str |
     info = linux.inspect(path)
     if exe:
         info["exe"] = exe
-    if not info["arch_ok"]:
-        arch = "x86_64" if info["machine"] == linux.EM_X86_64 else f"machine {info['machine']}"
-        raise ValueError(f"{path.name} is built for {arch}, not arm64 (aarch64): it can't run on the Frame. Look for "
-                         "an aarch64/arm64 download of it.")
+    x86 = info["machine"] == linux.EM_X86_64
+    if not linux.runs_on_frame(info["machine"]):
+        raise ValueError(f"{path.name} is built for machine {info['machine']}, not arm64 (aarch64) or x86_64: it "
+                         "can't run on the Frame. Look for an aarch64/arm64 download of it.")
+    if x86 and reporter:
+        reporter.log(f"{path.name} is an x86_64 build: the Frame runs it through FEX (x86 translation; an arm64 "
+                     "build runs faster if there is one)")
     package = f"linux.{linux.slug(info['title'])}"
     if reporter:
         reporter.log(f"{info['title']}: program {info['exe']}{' (AppImage)' if info['appimage'] else ''}"
                      f"{', OpenXR (VR)' if info['openxr'] else ''}")
     recipe = Recipe(package=package, title=info["title"], overport=False, as_is=True, source="heuristics")
     analysis = {"package": package, "label": info["title"], "engine": "Linux", "xr": "OpenXR" if info["openxr"]
-                else "none", "abis": ["arm64-v8a"], "libs": [], "extra": {**info, "vr_kind": "openxr" if info["openxr"]
-                                                                            else "none", "source": str(path)}}
+                else "none", "abis": ["x86_64" if x86 else "arm64-v8a"], "libs": [],
+                "extra": {**info, "vr_kind": "openxr" if info["openxr"] else "none", "x86_64": x86,
+                          "source": str(path)}}
     old = library.game(package) or {}
     root = Path(info["root"])
     try:  # what an install uploads (the library's size sort, the Frame's free-space check)
@@ -331,13 +361,103 @@ def add_linux_app(path: Path | str, reporter: Reporter | None = None, exe: str |
     return library.game(package)
 
 
+USER_FOLDERS = ("Downloads", "Desktop", "Documents", "Download")
+
+
+def _shared_folder(folder: Path) -> bool:
+    """A folder a lone program shouldn't take with it to the Frame: home, a user folder (Downloads…) or a drive root."""
+    folder = folder.resolve()
+    if folder.parent == folder or (str(folder).startswith("/mnt/") and str(folder).rstrip("/").count("/") <= 2):
+        return True
+    if folder == Path.home() or folder.name in USER_FOLDERS:
+        return True
+    try:
+        from .core import winhost
+
+        prof = winhost.env_path("USERPROFILE") if winhost.available() else None
+        return bool(prof) and (folder == prof or folder.parent == prof and folder.name in USER_FOLDERS)
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def add_windows_exe(exe: Path | str, reporter: Reporter | None = None) -> dict:
+    """Add one Windows program (.exe): a game folder whose program is that exe, run by Proton on the Frame (flat
+    unless a VR runtime is found). A program in Downloads, the home folder or a drive root is copied alone into
+    FramePort's data folder first, so an install doesn't upload everything next to it."""
+    import shutil
+
+    from .core.paths import user_data_dir
+
+    exe = Path(exe)
+    if exe.suffix.lower() != ".exe" or not exe.is_file():
+        raise ValueError(f"{exe.name} isn't a Windows program (.exe)")
+    folder = exe.parent
+    if _shared_folder(folder):
+        from .analysis import linux
+
+        folder = user_data_dir() / "windows-apps" / linux.slug(exe.stem)
+        folder.mkdir(parents=True, exist_ok=True)
+        if not (folder / exe.name).exists() or (folder / exe.name).stat().st_size != exe.stat().st_size:
+            if reporter:
+                reporter.log(f"copying {exe.name} into {folder} (it sits in a shared folder)")
+            shutil.copy2(exe, folder / exe.name)
+    entry = add_rift_game(folder, reporter, exe=exe.name, force=True, art=True)
+    if entry is None:
+        raise ValueError(f"{exe.name} couldn't be added")
+    return library.upsert_game(entry["package"], exe_confirmed=True)
+
+
+def add_from_link(manifest, path: Path, reporter: Reporter | None = None, icon: Path | None = None) -> dict:
+    """Add a build downloaded from an install link (deeplink.download) to the library: an APK (with any OBB files
+    next to it), a Linux build or a Windows program. A manifest's name becomes the title (FrameDrop: "name is what
+    shows up in Steam"); a direct file link keeps the title FramePort finds."""
+    from . import deeplink
+
+    kind = deeplink.classify(path.name)
+    if kind == deeplink.APK:
+        added = add_path(path, reporter, art=True)
+        if not added:
+            raise ValueError(f"{path.name} couldn't be read as an Android app")
+        entry = added[0]
+    elif kind == deeplink.LINUX:
+        entry = add_linux_app(path, reporter)
+    elif kind == deeplink.EXE:
+        entry = add_windows_exe(path, reporter)
+    else:
+        raise ValueError(f"FramePort can't install {path.name}")
+    pkg = entry["package"]
+    fields = {"link": {"source": manifest.source, "name": manifest.name, "time": time.time()}}
+    if not manifest.direct:  # a manifest (not a bare file link) names it
+        fields.update(title=manifest.name, title_locked=True)
+    # FramePort's manifest extension: a description where no store has one, the icon unless the user picked one
+    details = dict(library.game(pkg).get("details") or {})
+    if manifest.description and not details.get("description"):
+        details.update(description=manifest.description, sources=[*(details.get("sources") or []), "link"])
+        fields["details"] = details
+    library.upsert_game(pkg, **fields)
+    if icon:
+        from .artwork import fetch, sources
+
+        try:
+            if not (fetch.artwork_dir(pkg) / fetch.PICKED).exists():  # the user's own pick stays
+                sources.apply_custom(pkg, "icon", icon)
+        except Exception as exc:  # noqa: BLE001 - artwork is optional
+            if reporter:
+                reporter.log(f"icon from the link not used: {exc}")
+    return library.game(pkg)
+
+
 def install_linux(package: str, target: Target, reporter: Reporter, add_to_library: bool = True) -> dict:
     entry = library.game(package)
     extra = (entry.get("analysis") or {}).get("extra") or {}
     result = target.install_linux(package, steam_title(entry), Path(entry["game_dir"]), entry["exe"],
                                   extra.get("files"), bool(extra.get("appimage")), bool(extra.get("openxr")),
-                                  reporter)
-    if result.get("missing_libraries"):
+                                  reporter, x86_64=bool(extra.get("x86_64")),
+                                  desktop_entry=entry.get("desktop_entry", True) is not False)
+    if extra.get("x86_64"):
+        reporter.check("x86 translation", True, "runs through FEX on SteamOS's x86 system (its libraries come from "
+                                                 "there; not checked ahead)")
+    elif result.get("missing_libraries"):
         reporter.check("Libraries on the Frame", False, "missing: " + ", ".join(result["missing_libraries"]) +
                        " (SteamOS doesn't have them and the app doesn't bundle them: it won't start)")
     else:
@@ -523,7 +643,8 @@ def build_game(package: str, reporter: Reporter, outdir: Path | None = None) ->
     art, store_title = artwork.fetch(package, res.apk)
     build_info = {"apk": str(res.apk), "alt_apk": str(res.alt_apk) if res.alt_apk else None, "sha256": res.sha256,
                   "alt_sha256": res.alt_sha256, "applied": res.applied, "checks": res.checks, "ok": res.ok,
-                  "overport": res.meta.get("overport"), "recipe_fp": recipe_fingerprint(entry["recipe"])}
+                  "overport": res.meta.get("overport"), "recipe_fp": recipe_fingerprint(entry["recipe"]),
+                  "superseded": res.meta.get("superseded") or {}}
     library.upsert_game(package, build=build_info, title=entry.get("title") or store_title)
     return build_info
 
@@ -546,6 +667,8 @@ def install_game(package: str, target: Target, reporter: Reporter, apk_only: boo
     if not test_build and not apk.exists():  # the converted copy was removed after an earlier install: make it again
         build_game(package, reporter)
         return install_game(package, target, reporter, apk_only, add_to_library)
+    if not test_build and b.get("superseded"):  # workarounds this build left out (upstream fixed): not in settings.conf
+        recipe = dataclasses.replace(recipe, patches=upstream.without_superseded(recipe.patches, b["superseded"]))
     data_dir = Path(entry["data_dir"]) if entry.get("data_dir") else None
     title = steam_title(entry)
     result = target.install(package, title, apk, data_dir, recipe, reporter, apk_only)
@@ -707,6 +830,10 @@ def install_rift(package: str, target: Target, reporter: Reporter, add_to_librar
 
 def test_game(package: str, target: Target, reporter: Reporter, seconds: int = 45) -> dict:
     result, log = target.launch_test(package, reporter, seconds)
+    if missing_obb(library.game(package) or {}):
+        from .validate.triage import add_missing_obb
+
+        add_missing_obb(result)
     from .core.paths import user_data_dir
 
     logs = user_data_dir() / "logs"

src/frameport/recommend/engine.py

@@ -80,6 +80,7 @@ def suggest(analysis: Analysis, use_catalog: bool = True) -> Recipe:
             recipe.status = "unsupported"
             recipe.notes = f"No 64-bit ARM code ({', '.join(analysis.abis)}): the Steam Frame can't run it."
         if not rift:
+            _static_blockers(analysis, recipe)
             _non_quest(analysis, recipe)
     if not rift and not entry and (analysis.extra or {}).get("frame_patched"):
         # already has FramePort's adapter (e.g. a PATCHED/ build): installing it unchanged is the safe default
@@ -177,6 +178,39 @@ def warnings(recipe: Recipe) -> list[str]:
     return out
 
 
+def android_version_note(analysis: Analysis) -> str | None:
+    """'Its manifest asks for Android 14 (API 34)…' when the APK's minimum Android is newer than the Frame's."""
+    from ..analysis.detect import FRAME_API, android_version, too_new_android
+
+    min_sdk = (analysis.extra or {}).get("min_sdk")
+    if not too_new_android(min_sdk):
+        return None
+    return (f"Its manifest asks for Android {android_version(min_sdk)} (API {min_sdk}); the Frame's Android is "
+            f"{android_version(FRAME_API)} (API {FRAME_API}). Apps like this often crash at start on newer Android "
+            "parts, but not always: a launch test tells.")
+
+
+def web_wrapper_note(analysis: Analysis) -> str | None:
+    """A Trusted Web Activity: the APK only opens a website in Meta's browser (analysis.detect.web_wrapper)."""
+    ww = (analysis.extra or {}).get("web_wrapper")
+    if not ww:
+        return None
+    where = f"open {ww['url']} in a browser instead" if ww.get("url") else "open the website in a browser instead"
+    return (f"This app looks like a website in an Android wrapper (Trusted Web Activity): it opens the site in "
+            f"Meta's browser, which the Frame doesn't have. If nothing opens, {where}.")
+
+
+def blocker_notes(analysis: Analysis) -> list[str]:
+    """Warnings read from the APK's manifest that it may not run on the Frame (whatever the recipe says). Only
+    warnings: the manifest alone never marks a game unsupported (owner's rule); a launch test's triage decides."""
+    return [n for n in (android_version_note(analysis), web_wrapper_note(analysis)) if n]
+
+
+def _static_blockers(analysis: Analysis, recipe: Recipe) -> None:
+    for note in blocker_notes(analysis):
+        recipe.notes = _add(recipe.notes, note)
+
+
 def _non_quest(analysis: Analysis, recipe: Recipe) -> None:
     """Android apps that aren't Meta Quest apps (analysis.detect.vr_kind)."""
     kind = analysis.vr_kind

src/frameport/sources/quest_dump.py

@@ -3,7 +3,10 @@
 Accepted layouts:
   <folder>/<something>.apk [+ <folder>/<package>/ (OBB or raw asset data)]   e.g. common downloader layouts
   <folder>/<package>.apk + <folder>/obb/                                       FramePort/PATCHED output layout
+  <folder>/x.apk + <folder>/obb/<package>/ or Android/obb/<package>/          backups with an obb folder
+  <game>/apk/x.apk + <game>/obb/<package>/                                     SideQuest-style backups (one game)
   a single .apk file
+(find_data_dir has the details.)
 """
 from __future__ import annotations
 
@@ -39,11 +42,91 @@ def _is_apk(path: Path) -> bool:
         return False
 
 
+OBB_FOLDERS = ("obb", "obbs")
+
+
+def _subdirs(d: Path) -> list[Path]:
+    try:
+        return sorted(p for p in d.iterdir() if p.is_dir() and not p.name.startswith(("_", ".")))
+    except OSError:
+        return []
+
+
+def _child(d: Path, name: str) -> Path | None:
+    """d/name, matching the name's case loosely (backups come from Windows: 'OBB', a lower-case package folder)."""
+    exact = d / name
+    if exact.is_dir():
+        return exact
+    return next((p for p in _subdirs(d) if p.name.lower() == name.lower()), None)
+
+
+def _nonempty(d: Path | None) -> bool:
+    try:
+        return bool(d) and d.is_dir() and any(d.iterdir())
+    except OSError:
+        return False
+
+
+def _has_obb(d: Path) -> bool:
+    try:
+        return any(p.suffix.lower() == ".obb" and p.is_file() for p in d.iterdir())
+    except OSError:
+        return False
+
+
+def _package_dir_below(d: Path, pkg: str, depth: int, skip: Path | None = None, other_games: bool = False) \
+        -> Path | None:
+    """A folder named like the package holding .obb files, at most `depth` levels below d. other_games: skip
+    folders with APKs of their own (a neighbouring game folder, e.g. another version of the same game)."""
+    for sub in _subdirs(d):
+        if skip is not None and sub == skip:
+            continue
+        if sub.name.lower() == pkg.lower():
+            if _has_obb(sub):
+                return sub
+            continue
+        if depth > 1 and not (other_games and any(sub.glob("*.apk"))):
+            found = _package_dir_below(sub, pkg, depth - 1)
+            if found:
+                return found
+    return None
+
+
+def find_data_dir(apk_dir: Path, pkg: str | None) -> Path | None:
+    """The folder whose contents go to Android/obb/<package>/ (so the folder holding the .obb files themselves):
+      <apk dir>/<package>/                       downloader layouts
+      <apk dir>/obb/<package>/ or <apk dir>/obb/  FramePort/PATCHED output, backups with an obb folder
+      a <package> folder with .obb files up to 3 levels below the APK's folder (e.g. Android/obb/<package>/) or 2
+      below its parent (SideQuest-style backups: <game>/apk/x.apk + <game>/obb/<package>/; the parent's folders
+      with APKs of their own are other games and are skipped)."""
+    own = _child(apk_dir, pkg) if pkg else None
+    if _nonempty(own):
+        return own
+    for obb in (_child(apk_dir, name) for name in OBB_FOLDERS):
+        if obb is None:
+            continue
+        inner = _child(obb, pkg) if pkg else None
+        if _nonempty(inner):
+            return inner
+        if _nonempty(obb):
+            return obb
+    if not pkg:
+        return None
+    found = _package_dir_below(apk_dir, pkg, 3)
+    if found is None and apk_dir.parent != apk_dir:
+        found = _package_dir_below(apk_dir.parent, pkg, 2, skip=apk_dir, other_games=True)
+    return found
+
+
+# a folder that only holds the APK inside a game folder (<game>/apk/x.apk + <game>/obb/…): the game is the parent
+APK_FOLDERS = ("apk", "apks")
+
+
 def from_path(path: Path) -> SourceGame | None:
     path = Path(path)
     if path.is_file() and path.suffix.lower() == ".apk":
         pkg = _package_of(path)
-        data = next((d for d in (path.parent / (pkg or ""), path.parent / "obb") if pkg and d.is_dir()), None)
+        data = find_data_dir(path.parent, pkg) if pkg else None
         return SourceGame(display_name(path.stem), path, data, path.parent)
     if not path.is_dir():
         return None
@@ -53,12 +136,9 @@ def from_path(path: Path) -> SourceGame | None:
     primary = [a for a in apks if ".alt-" not in a.name]
     apk = primary[0] if primary else apks[0]
     pkg = _package_of(apk)
-    data = None
-    for cand in ((path / pkg) if pkg else None, path / "obb"):
-        if cand and cand.is_dir() and any(cand.iterdir()):
-            data = cand
-            break
-    return SourceGame(display_name(path.name), apk, data, path, [a for a in apks if a != apk])
+    data = find_data_dir(path, pkg)
+    game_dir = path.parent if path.name.lower() in APK_FOLDERS else path
+    return SourceGame(display_name(game_dir.name), apk, data, game_dir, [a for a in apks if a != apk])
 
 
 def _no_quest_games_below(d: Path) -> bool:
@@ -77,7 +157,8 @@ def _other_folders(d: Path, game: SourceGame) -> list[Path]:
     except OSError:
         return []
     own = {game.data_dir.resolve()} if game.data_dir else set()
-    return [p for p in subs if p.resolve() not in own and p.name.lower() not in ("obb", "android")]
+    own |= set(game.data_dir.resolve().parents) if game.data_dir else set()  # e.g. Android/ of Android/obb/<pkg>
+    return [p for p in subs if p.resolve() not in own and p.name.lower() not in (*OBB_FOLDERS, "android")]
 
 
 def scan(root: Path, depth: int = 5) -> list[SourceGame]:

src/frameport/targets/base.py

@@ -33,8 +33,9 @@ class Target(ABC):
         """Start an installed game for playing, through the target's Steam (Steam library shortcut)."""
         raise NotImplementedError(f"{self.label} can't launch games")
 
-    def install_linux(self, package, title, root, exe, files, appimage, openxr, reporter) -> dict:
-        """Install a native arm64 Linux app (only the Frame runs them)."""
+    def install_linux(self, package, title, root, exe, files, appimage, openxr, reporter, x86_64=False,
+                      desktop_entry=True) -> dict:
+        """Install a Linux app (only the Frame runs them; x86_64 ones through FEX)."""
         raise NotImplementedError(f"{self.label} can't install Linux apps")
 
     def collect_diag(self, package: str | None = None) -> dict:

src/frameport/targets/frame_lepton.py

@@ -7,7 +7,7 @@ from pathlib import Path
 from ..core.events import Reporter
 from ..core.models import Recipe
 from ..frame.connection import Frame, FrameTarget, sh_quote
-from ..install import installer
+from ..install import drives, installer
 from ..validate import device
 from .base import Target
 
@@ -19,6 +19,12 @@ class FrameLeptonTarget(Target):
         self.target = target
         self.frame = Frame(target, password)
         self.label = target.label
+        self.dest: str | None = None  # where new games go; None = the library setting (drives.install_dest)
+
+    def install_dest(self) -> str | None:
+        """A drive's install dir for new installs (GitHub #90), None = internal storage. Reinstalls stay where the
+        game is (the agent keeps an installed game's folder)."""
+        return self.dest if self.dest is not None else drives.install_dest()
 
     def connect(self) -> FrameLeptonTarget:
         if self.frame.client is not None and not self.frame.alive():
@@ -34,7 +40,7 @@ class FrameLeptonTarget(Target):
         return self.connect().frame.agent("list_installed")["games"]
 
     def install(self, package, title, apk: Path, data_dir, recipe: Recipe, reporter: Reporter, apk_only=False):
-        plan = installer.InstallPlan(package, title, apk, data_dir, recipe, apk_only)
+        plan = installer.InstallPlan(package, title, apk, data_dir, recipe, apk_only, dest=self.install_dest())
         return installer.install(self.connect().frame, plan, reporter)
 
     def add_to_library(self, packages, reporter):
@@ -60,13 +66,27 @@ class FrameLeptonTarget(Target):
 
     def install_pcvr(self, package, title, game_dir, exe, recipe, reporter, **extra):
         plan = installer.PcvrPlan(package, title, Path(game_dir), exe, recipe, extra.get("revive_dir"),
-                                  extra.get("exe_sha256"), extra.get("revive_version"), extra.get("art_lookup"))
+                                  extra.get("exe_sha256"), extra.get("revive_version"), extra.get("art_lookup"),
+                                  dest=self.install_dest())
         return installer.install_pcvr(self.connect().frame, plan, reporter)
 
-    def install_linux(self, package, title, root, exe, files, appimage, openxr, reporter):
-        plan = installer.LinuxPlan(package, title, Path(root), exe, files, appimage, openxr)
+    def install_linux(self, package, title, root, exe, files, appimage, openxr, reporter, x86_64=False,
+                      desktop_entry=True):
+        plan = installer.LinuxPlan(package, title, Path(root), exe, files, appimage, openxr, x86_64,
+                                   dest=self.install_dest(), desktop_entry=desktop_entry)
         return installer.install_linux(self.connect().frame, plan, reporter)
 
+    def drives(self) -> list[dict]:
+        return drives.list_drives(self.connect().frame)
+
+    def move(self, package: str, dest: str, reporter: Reporter) -> dict:
+        """Move an installed game's files to another drive (or back to internal storage: dest "internal")."""
+        return drives.move(self.connect().frame, package, dest, reporter)
+
+    def set_desktop_entry(self, package: str, enabled: bool) -> dict:
+        """A Linux app's Desktop Mode entry on or off (GitHub #84)."""
+        return self.connect().frame.agent("desktop_entry", package=package, enabled=enabled)
+
     def proton_status(self, tool: str | None = None) -> dict:
         return self.connect().frame.agent("proton_status", tool=tool)
 

src/frameport/ui/app.py

@@ -33,8 +33,34 @@ NAV = [("library", tr("Library"), ft.Icons.GRID_VIEW_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),
+       ("keyboard", tr("Type on Frame"), ft.Icons.KEYBOARD_ROUNDED),
+       ("monitor", tr("Monitor"), ft.Icons.MONITOR_HEART_OUTLINED),
        ("settings", tr("Settings"), ft.Icons.TUNE_ROUNDED)]
 POLL_SECONDS = 30
+_link_state = {"owner": None, "thread": None, "closing": False}  # install links go to the newest window session
+
+
+def _stop_link_watch() -> None:
+    """The window is closing: no more heartbeats, so a link clicked now starts FramePort again (a heartbeat left
+    behind made the handler script think the closed window would take it)."""
+    from .. import urlhandler
+
+    _link_state["closing"] = True
+    urlhandler.stop_heartbeat()
+
+
+def _watch_links() -> None:
+    """Heartbeat for the link handler scripts (FramePort runs) + hand queued install links to the window."""
+    from .. import urlhandler
+
+    while not _link_state["closing"]:
+        urlhandler.heartbeat()
+        app = _link_state["owner"]
+        if app is not None:
+            for link in urlhandler.take_links():
+                applog.log.info("install link received")
+                app.page.run_thread(app.open_install_link, link, True)
+        time.sleep(1)
 
 
 
@@ -72,13 +98,18 @@ class FramePortApp:
         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.keyboard_view = None  # likewise (views/keyboard.KeyboardView): its keyboard exists only while it's shown
+        self.monitor_view = None  # likewise (views/monitor.MonitorView): its stream runs only while it's shown
+        self._typing_on_frame = False
         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
-                                   self.stop_live())  # and stop a live view (it would keep the Frame encoding)
+                                   self.stop_live(),  # and stop a live view (it would keep the Frame encoding)
+                                   self.stop_keyboard(), self.stop_monitor(),
+                                   _link_state.update(owner=None) if _link_state["owner"] is self else None)
         from .updater import Updater
 
         self.updater = Updater(self)  # new FramePort releases (sidebar card, Library bar, one-click update)
@@ -131,12 +162,24 @@ class FramePortApp:
         threading.Thread(target=self._backfill_covers, daemon=True).start()
         self.updater.start()
         self.run_bg(self._refresh_catalog)  # confirmed game configs from GitHub main (no release needed)
+        _link_state["owner"] = self
+        if _link_state["thread"] is None:
+            import atexit
+
+            from .. import urlhandler
+
+            _link_state["thread"] = threading.Thread(target=_watch_links, daemon=True)
+            _link_state["thread"].start()
+            atexit.register(_stop_link_watch)
+            self.run_bg(urlhandler.apply_setting)  # framedrop:// + frameport:// → FramePort (Settings → General)
 
     # ================================================================== shell
     def _on_window_event(self, e) -> None:
         """Remember the window's size and position (once a resize/move ends; not while maximized or full screen) and
         whether it is maximized."""
         win, change = self.page.window, None
+        if e.type == ft.WindowEventType.CLOSE:
+            _stop_link_watch()  # also when maximized (that returns below)
         if e.type in (ft.WindowEventType.MAXIMIZE, ft.WindowEventType.UNMAXIMIZE):
             change = {"maximized": e.type == ft.WindowEventType.MAXIMIZE}
         elif win.maximized or win.full_screen:
@@ -208,16 +251,10 @@ class FramePortApp:
         self._conn_bat = ft.Container(ft.Row([self._conn_bat_icon, self._conn_bat_text], spacing=T.px(2), tight=True,
                                              vertical_alignment=ft.CrossAxisAlignment.CENTER), visible=False)
         self._conn_extra = ft.Container(C.meta(""), visible=False, tooltip=C.tip(C.HELP["frame_summary"]))
-        # compact (no button padding) and next to the name: as a separate column it squeezed "Quest ✓  PC VR ✓"
-        self._conn_type = ft.IconButton(ft.Icons.KEYBOARD_ROUNDED, icon_size=T.px(16), icon_color=T.TEXT_2,
-                                        tooltip=tr("Type on Frame: use this keyboard on the Frame"), visible=False,
-                                        on_click=lambda e: self.type_on_frame(), padding=0,
-                                        width=T.px(22), height=T.px(22),
-                                        style=ft.ButtonStyle(shape=ft.RoundedRectangleBorder(radius=T.px(6))))
         self.conn_card.content = ft.Container(ft.Row([
             ft.Stack([ft.Icon(ft.Icons.VIEW_IN_AR_ROUNDED, size=T.px(22), color=T.TEXT_2),
                       ft.Container(self._conn_dot, right=0, bottom=0)], width=T.px(24), height=T.px(24)),
-            ft.Column([ft.Row([ft.Container(self._conn_name, expand=True), self._conn_bat, self._conn_type],
+            ft.Column([ft.Row([ft.Container(self._conn_name, expand=True), self._conn_bat],
                               spacing=T.px(6), vertical_alignment=ft.CrossAxisAlignment.CENTER),
                        self._conn_line, self._conn_extra], spacing=1, expand=True),
         ], spacing=T.S3), padding=T.S3, border_radius=T.RADIUS_SM, bgcolor=T.SURFACE, ink=True,
@@ -286,7 +323,6 @@ class FramePortApp:
         self._conn_line.color = color
         bat = (self.frame_info or {}).get("battery") if st == "connected" else None
         self._conn_bat.visible = bool(bat)
-        self._conn_type.visible = st == "connected"
         self.power_row.visible = st == "connected"
         if bat:
             from .battery import charging, icon, low
@@ -320,6 +356,10 @@ class FramePortApp:
         # another page or game starts at the top
         if not (route == "game" and self.route[:1] == ("game",) and self.route[1:2] == args[:1]):
             self.game_scroll = 0.0
+        if self.route[0] == "keyboard" and route != "keyboard":
+            self.stop_keyboard()  # leaving the tab removes the virtual keyboard from the Frame
+        if self.route[0] == "monitor" and route != "monitor":
+            self.stop_monitor()  # leaving the tab ends the Frame's monitor stream
         self.route = (route, *args)
         self.render()
 
@@ -358,6 +398,18 @@ class FramePortApp:
                 if self.live_view is None:
                     self.live_view = LiveView(self)
                 view = self.live_view.mount()
+            elif kind == "keyboard":
+                from .views.keyboard import KeyboardView
+
+                if self.keyboard_view is None:
+                    self.keyboard_view = KeyboardView(self)
+                view = self.keyboard_view.mount()
+            elif kind == "monitor":
+                from .views.monitor import MonitorView
+
+                if self.monitor_view is None:
+                    self.monitor_view = MonitorView(self)
+                view = self.monitor_view.mount()
             elif kind == "settings":
                 view = SettingsView(self).build()
             else:
@@ -390,6 +442,16 @@ class FramePortApp:
         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()
+        elif self.route[0] == "keyboard" and (self.keyboard_view is None or self.keyboard_view.root is None
+                                              or self.keyboard_view.stopped or self.frame_state != "connected"):
+            if self.frame_state != "connected":
+                self.stop_keyboard()
+            self.render()
+        elif self.route[0] == "monitor" and (self.monitor_view is None or self.monitor_view.root is None
+                                             or self.monitor_view.stopped or self.frame_state != "connected"):
+            if self.frame_state != "connected":
+                self.stop_monitor()
+            self.render()
         else:
             self._refresh_sidebar()
 
@@ -397,6 +459,14 @@ class FramePortApp:
         if self.live_view is not None:
             self.live_view.stop()
 
+    def stop_keyboard(self) -> None:
+        if self.keyboard_view is not None:
+            self.keyboard_view.stop()
+
+    def stop_monitor(self) -> None:
+        if self.monitor_view is not None:
+            self.monitor_view.stop()
+
     def open_game(self, package: str, advanced: bool = False, show_all: bool = False) -> None:
         self.go("game", package, advanced, show_all)
 
@@ -435,7 +505,7 @@ class FramePortApp:
             self.toast(tr("Copy failed; select the text instead"), error=True)
 
     def _on_key(self, e: ft.KeyboardEvent) -> None:
-        if getattr(self, "_typing_on_frame", False):
+        if self._typing_on_frame:
             return  # Type on Frame is open: Esc and shortcuts belong to the Frame
         if e.key == "Escape" and self.activity.open:
             self.show_activity(False)
@@ -722,7 +792,7 @@ class FramePortApp:
                     out.append((tr("Add videos and files…"), ft.Icons.VIDEO_LIBRARY_OUTLINED,
                                 lambda e: self.go("files", pkg)))
                 if on_frame:
-                    out.append((tr("Type on Frame…"), ft.Icons.KEYBOARD_ROUNDED, lambda e: self.type_on_frame()))
+                    out.append((tr("Type on Frame"), ft.Icons.KEYBOARD_ROUNDED, lambda e: self.type_on_frame()))
                 if not rift and not linux:
                     out.append((tr("Analyze again"), ft.Icons.MANAGE_SEARCH_ROUNDED, lambda e: self.reanalyze(pkg)))
                 if on_frame:
@@ -748,6 +818,8 @@ class FramePortApp:
                 C.install_state(g, self.frame_info) in ("installed", "outdated"):
             out.append((tr("Update Steam art on Frame"), ft.Icons.WALLPAPER_ROUNDED,
                         lambda e: self.update_steam_art(pkg)))
+            if C.frame_drive(g, self.frame_info) is not None:  # agent v63+: games can live on a microSD card
+                out.append((tr("Move to…"), ft.Icons.DRIVE_FILE_MOVE_OUTLINED, lambda e: self.move_game(pkg)))
         out.append((tr("Refresh store details"), ft.Icons.SYNC_ROUNDED, lambda e: self.refresh_details(pkg)))
         if not job and not linux:
             out.append((tr("Rebuild only (no install)") if not rift else tr("Check game files"), ft.Icons.BUILD_ROUNDED,
@@ -844,11 +916,11 @@ class FramePortApp:
         def ask_frame_oculus():
             # Installing an Oculus/LibOVR Rift game on the Frame: warn that it needs Revive (which can't run there)
             if to != "frame":
-                return ask_license()
+                return ask_obb()
             oculus = [g for g in games if g.get("kind") == "rift"
                       and "pcvr.revive" in (g.get("recipe") or {}).get("patches", {})]
             if not oculus:
-                return ask_license()
+                return ask_obb()
             boxes = {g["package"]: ft.Checkbox(label=self._title(g["package"]), value=False, active_color=T.ACCENT)
                      for g in oculus}
             pick = C.one_choice()
@@ -863,7 +935,7 @@ class FramePortApp:
                                   "those Oculus games need PC mode (SteamVR + Revive)."))
                     finished()
                     return
-                ask_license()
+                ask_obb()
             self.page.show_dialog(ft.AlertDialog(
                 title=ft.Text(tr("These games can't run on the Steam Frame"), weight=ft.FontWeight.W_600),
                 content=ft.Container(ft.Column([
@@ -877,6 +949,39 @@ class FramePortApp:
                 actions=[C.ghost(tr("Cancel"), on_click=pick(cancel)),
                          C.primary(tr("Continue"), on_click=pick(ok))]))
 
+        def ask_obb():
+            # the game expects a data file (.obb) that wasn't found next to its APK: it would hang at start (#85)
+            missing = [g for g in games if pipeline.missing_obb(g)]
+            if not missing:
+                return ask_license()
+            boxes = {g["package"]: ft.Checkbox(label=self._title(g["package"]), value=False, active_color=T.ACCENT)
+                     for g in missing}
+            pick = C.one_choice()
+
+            def ok(e):
+                nonlocal games
+                self.page.pop_dialog()
+                keep = {p for p, b in boxes.items() if b.value}
+                games = [g for g in games if g not in missing or g["package"] in keep]
+                if not games:
+                    self.toast(tr("Nothing to install: add the games' .obb files first"))
+                    finished()
+                    return
+                ask_license()
+            self.page.show_dialog(ft.AlertDialog(
+                title=ft.Text(tr("Game data (.obb) not found"), weight=ft.FontWeight.W_600),
+                content=ft.Container(ft.Column([
+                    C.body(tr("These games keep their content in a data file (.obb), and none was found next to "
+                              "their APK. Without it they hang at start. Put the .obb files in a folder named like "
+                              "the game's package (or obb/) next to the APK and add the folder again. Tick any you "
+                              "still want to install.")),
+                    *boxes.values()], spacing=T.S2, tight=True, scroll=ft.ScrollMode.AUTO), width=T.px(520),
+                    height=T.px(min(150 + 36 * len(boxes), 480))),  # fits the list; scrolls when long
+                bgcolor=T.SURFACE_2, shape=ft.RoundedRectangleBorder(radius=T.RADIUS),
+                modal=True, on_dismiss=pick(closed),
+                actions=[C.ghost(tr("Cancel"), on_click=pick(cancel)),
+                         C.primary(tr("Continue"), on_click=pick(ok))]))
+
         def ask_license():
             from ..core import winhost
 
@@ -1165,6 +1270,69 @@ class FramePortApp:
             return tr("{title}: Steam artwork updated on the Frame").format(title=self._title(pkg))
         return self.submit(tr("Update Steam art: {title}").format(title=self._title(pkg)), run, pkg, "art")
 
+    def move_game(self, pkg: str) -> None:
+        """Move to…: pick another drive of the Frame (microSD card, internal storage) for an installed game; the copy
+        runs as a Frame job (GitHub #90)."""
+        from ..install import drives
+
+        title = self._title(pkg)
+        here = C.frame_drive(library.game(pkg) or {"package": pkg}, self.frame_info)
+        group = ft.RadioGroup(content=ft.Column([C.meta(tr("Looking for drives…"))], spacing=T.S2))
+        go = C.primary(tr("Move"), ft.Icons.DRIVE_FILE_MOVE_OUTLINED, disabled=True)
+        found: dict[str, dict] = {}
+
+        def picked(e):
+            go.disabled = not group.value
+            C.update(go)
+
+        group.on_change = picked
+
+        def fill():
+            try:
+                listed = self._target_for("frame").drives()
+            except Exception as exc:  # noqa: BLE001
+                group.content.controls = [C.meta(tr("Couldn't list the Frame's drives: {error}")
+                                                 .format(error=explain(exc)))]
+                C.update(group)
+                return
+            rows = []
+            for d in listed:
+                key = drives.INTERNAL if d["internal"] else d["install_dir"]
+                current = drives.is_on({"drive": here}, d) if here else d["internal"]
+                found[key] = d
+                note = tr("it's here now") if current else \
+                    (d.get("reason") or "") if not d.get("usable") else drives.free_text(d)
+                rows.append(ft.Row([
+                    ft.Radio(value=key, active_color=T.ACCENT, disabled=current or not d.get("usable")),
+                    ft.Icon(ft.Icons.SD_CARD_ROUNDED if d.get("removable") else ft.Icons.STORAGE_ROUNDED,
+                            size=T.px(18), color=T.TEXT_2),
+                    ft.Column([C.body(tr("Internal storage") if d["internal"] else d["label"], T.TEXT),
+                               C.meta(note)], spacing=T.px(2), expand=True),
+                ], spacing=T.S2))
+            group.content.controls = rows or [C.meta(tr("Only internal storage"))]
+            C.update(group)
+
+        def start(e):
+            dest = group.value
+            if not dest:
+                return
+            self.page.pop_dialog()
+            label = tr("Internal storage") if dest == drives.INTERNAL else found.get(dest, {}).get("label", dest)
+
+            def run(job: Job):
+                self._target_for("frame").move(pkg, dest, job.reporter)
+                return tr("{title} moved to {label}").format(title=title, label=label)
+            self.submit(tr("Move {title} to {label}").format(title=title, label=label), run, pkg, "tool-frame")
+
+        go.on_click = start
+        self.page.show_dialog(ft.AlertDialog(
+            title=ft.Text(tr("Move {title} to…").format(title=title), weight=ft.FontWeight.W_600),
+            content=ft.Container(ft.Column([C.body(C.HELP["move_game"]), group], spacing=T.S3, tight=True),
+                                 width=T.px(460)),
+            bgcolor=T.SURFACE_2, shape=ft.RoundedRectangleBorder(radius=T.RADIUS),
+            actions=[C.ghost(tr("Cancel"), on_click=lambda e: self.page.pop_dialog()), go]))
+        self.run_bg(fill)
+
     def build_game(self, pkg: str) -> Job:
         def run(job: Job):
             info = pipeline.build_game(pkg, job.reporter)
@@ -1372,13 +1540,71 @@ class FramePortApp:
             if f.path:
                 self.scan(f.path)
 
+    async def pick_windows_exe(self, e=None):
+        files = await ft.FilePicker().pick_files(dialog_title=tr("A Windows program (.exe)"), allow_multiple=True,
+                                                 allowed_extensions=["exe"])
+        for f in files or []:
+            if f.path:
+                self.add_windows_exe(f.path)
+
+    def add_windows_exe(self, path: str) -> Job:
+        """One Windows program: run by Proton on the Frame (flat unless it has VR), like "Add one game folder…"."""
+        def run(job: Job):
+            job.reporter.stage("Looking at the program")
+            g = pipeline.add_windows_exe(path, job.reporter)
+            try:
+                from ..artwork import thumbs
+
+                thumbs.prewarm(g["package"])
+            except Exception:  # noqa: BLE001 - artwork is optional
+                pass
+            library.set_setting("ui.welcome_done", True)
+            self.open_game(g["package"])
+            return tr("Added {title}").format(title=g.get("title"))
+        return self.submit(tr("Add {name}").format(name=Path(path).name), run, None, "task")
+
+    def pick_link(self, e=None) -> None:
+        from .views.link_dialog import show_paste_dialog
+
+        show_paste_dialog(self)
+
+    def open_install_link(self, text: str, from_web: bool = False) -> None:
+        """A framedrop:// / frameport:// link (from a web page's button) or a pasted one: ask, download, install."""
+        from .views.link_dialog import open_link
+
+        if from_web and not self.page.web:
+            try:
+                self.page.run_task(self.page.window.to_front)
+            except Exception:  # noqa: BLE001
+                pass
+        open_link(self, text, pasted=not from_web)
+
+    def add_dropped(self, paths: list[str]) -> None:
+        """Files dropped on the Library: APKs, Linux builds, Windows programs, folders, FrameDrop manifests."""
+        from . import dropped
+
+        for kind, path in dropped.route(paths):
+            if kind == "apk":
+                self.scan(path)
+            elif kind == "linux":
+                self.add_linux(path)
+            elif kind == "exe":
+                self.add_windows_exe(path)
+            elif kind == "manifest":
+                self.open_install_link(path)
+            elif kind == "folder":
+                self.scan(path)
+            else:
+                self.toast(tr("FramePort can't add {name}: drop an APK, a Linux build (.zip, AppImage), a Windows "
+                              "program (.exe) or a folder").format(name=Path(path).name), error=True)
+
     async def pick_linux_app(self, e=None):
         """An AppImage or an archive (.zip/.tar.*) with an arm64 Linux app. Any file can be picked: AppImages often
         have no extension."""
         from ..analysis import linux
 
-        files = await ft.FilePicker().pick_files(dialog_title=tr("A Linux app for arm64 (AppImage, .zip or .tar.gz)"),
-                                                 allow_multiple=True)
+        title = tr("A Linux app (AppImage, .zip or .tar.gz; arm64, or x86_64 through translation)")
+        files = await ft.FilePicker().pick_files(dialog_title=title, allow_multiple=True)
         for f in files or []:
             if not f.path:
                 continue
@@ -1389,17 +1615,17 @@ class FramePortApp:
                            .format(name=Path(f.path).name), error=True)
 
     async def pick_linux_folder(self, e=None):
-        path = await ft.FilePicker().get_directory_path(dialog_title=tr("Folder with a Linux app for arm64"))
+        path = await ft.FilePicker().get_directory_path(dialog_title=tr("Folder with a Linux app"))
         if path:
             self.add_linux(path)
 
     def add_linux(self, path: str) -> Job:
-        """Add a native arm64 Linux app (GitHub #31) in the background, then open its page."""
+        """Add a Linux app (GitHub #31; arm64, or x86_64 through FEX) in the background, then open its page."""
         name = Path(path).name
 
         def run(job: Job):
             job.reporter.stage("Looking at the app")
-            g = pipeline.add_linux_app(path, job.reporter)  # ValueError (e.g. an x86_64 build): the job fails with it
+            g = pipeline.add_linux_app(path, job.reporter)  # ValueError (not a Linux program): the job fails with it
             pkg = g["package"]
             try:
                 from ..artwork import thumbs
@@ -1539,9 +1765,7 @@ class FramePortApp:
         C.confirm(self.page, heading, text, label, go, danger=action != "sleep" or force)
 
     def type_on_frame(self) -> None:
-        from .views.type_dialog import show_type_dialog
-
-        show_type_dialog(self)
+        self.go("keyboard")
 
     def choose_exe(self, pkg: str) -> None:
         from .views.exe_dialog import show_exe_dialog
@@ -1856,6 +2080,8 @@ class FramePortApp:
 
     def disconnect(self):
         self.stop_live()
+        self.stop_keyboard()
+        self.stop_monitor()
         if self.target:
             try:
                 self.target.close()
@@ -2054,6 +2280,16 @@ def serialize_flet_updates() -> None:
 
 
 def main(argv=None):
+    import sys
+
+    from .. import urlhandler
+
+    args = list(sys.argv[1:] if argv is None else argv)
+    links = [a for a in args if "://" in a or a.lower().endswith(".json")]
+    for link in links:  # `frameport-gui <install link>` (source/wheel installs; bundles go through the handler script)
+        urlhandler.drop_link(link)
+    if links and urlhandler.app_running():
+        return  # the open window takes it
     applog.setup("gui")
     serialize_flet_updates()
     from ..core import library

src/frameport/ui/components.py

@@ -29,6 +29,22 @@ def _deployment(game: dict, frame_info: dict | None) -> dict | None:
     return next((d for d in (frame_info or {}).get("installed", []) if d.get("package") == game.get("package")), None)
 
 
+def frame_drive(game: dict, frame_info: dict | None) -> dict | None:
+    """The drive the game is installed on ({internal, path, label, missing}), None if not installed / old agent."""
+    from ..install.drives import game_drive
+
+    return game_drive(_deployment(game, frame_info))
+
+
+def drive_note(drive: dict | None) -> str:
+    """" · on SD Card" / " · SD Card not inserted" for a game on another drive, "" on internal storage."""
+    if not drive or drive.get("internal"):
+        return ""
+    if drive.get("missing"):
+        return tr(" · {label} not inserted").format(label=drive.get("label") or tr("its drive"))
+    return tr(" · on {label}").format(label=drive.get("label") or "")
+
+
 def settings_diff(game: dict, frame_info: dict | None) -> tuple[list[str], list[str]] | None:
     """(patches turned on, patches turned off) in the app since the Frame's copy was installed; None if the same (or
     unknown: installs from before FramePort recorded their recipe)."""
@@ -87,7 +103,9 @@ def install_state(game: dict, frame_info: dict | None) -> str | None:
     if frame_info is None:
         return None
     dep = _deployment(game, frame_info)
-    if not dep or dep.get("apk_present") is False:  # no record, or the game files are gone (half uninstalled)
+    # no record, or the game files are gone (half uninstalled); a game on a microSD card that isn't inserted now is
+    # still installed (GitHub #90)
+    if not dep or (dep.get("apk_present") is False and not dep.get("drive_missing")):
         return "missing"
     b = game.get("build") or {}
     built = {b.get("sha256"), b.get("alt_sha256")} - {None}
@@ -454,3 +472,152 @@ def is_media_player(g: dict) -> bool:
     patches = ((g.get("recipe") or {}).get("patches") or {})
     exts = ((g.get("analysis") or {}).get("extra") or {}).get("xr_layer_exts") or []
     return "adapter.equirect_emul" in patches or any(e.startswith("XR_KHR_composition_layer_equirect") for e in exts)
+
+
+# ------------------------------------------------------------------------------------------ charts
+def spark_points(values: list, width: float, height: float, lo: float = 0.0, hi: float | None = None,
+                 slots: int | None = None, pad: float = 2.0) -> list[list[tuple[float, float]]]:
+    """Runs of (x, y) points for a sparkline: the newest value at the right edge, one slot per value (`slots` fixes
+    the spacing so a young series grows from the right), None = a gap. y grows downwards (canvas coordinates)."""
+    n = slots or len(values)
+    if n < 2 or width <= 0 or height <= 0:
+        return []
+    real = [v for v in values if v is not None]
+    if hi is None:
+        hi = max(real, default=lo + 1.0)
+    span = (hi - lo) or 1.0
+    step = width / (n - 1)
+    x0 = width - step * (len(values) - 1)
+    runs, run = [], []
+    for i, v in enumerate(values):
+        if v is None:
+            if run:
+                runs.append(run)
+            run = []
+            continue
+        frac = min(1.0, max(0.0, (v - lo) / span))
+        run.append((x0 + i * step, pad + (height - 2 * pad) * (1.0 - frac)))
+    if run:
+        runs.append(run)
+    return runs
+
+
+class Sparkline:
+    """A small line chart with a soft area fill (Flet canvas, built into Flet: no charts extension). Created once;
+    set() replaces only the paths' elements, so a tick sends a small patch. Fills its width (on_resize)."""
+
+    def __init__(self, color: str = T.ACCENT, height: int = 36, slots: int = 120, lo: float = 0.0,
+                 hi: float | None = None, min_slots: int = 30, fit: float | None = None):
+        import flet.canvas as cv
+
+        self.cv, self.slots, self.min_slots, self.lo, self.hi = cv, slots, min_slots, lo, hi
+        self.fit = fit  # zoom to the data: a scale of at least this span around it (temperatures, fan speed)
+        self.width, self.height = 0.0, T.px(height)
+        self.values: list = []
+        self.target: float | None = None
+        self.area = cv.Path([], paint=ft.Paint(color=T.soft(color, 0.16), style=ft.PaintingStyle.FILL))
+        self.line = cv.Path([], paint=ft.Paint(color=color, stroke_width=T.px(1.6), style=ft.PaintingStyle.STROKE,
+                                               stroke_join=ft.StrokeJoin.ROUND, stroke_cap=ft.StrokeCap.ROUND))
+        self.guide = cv.Path([], paint=ft.Paint(color=T.soft(T.TEXT_3, 0.6), stroke_width=1,
+                                                style=ft.PaintingStyle.STROKE, stroke_dash_pattern=[3, 3]))
+        self.control = cv.Canvas([self.area, self.guide, self.line], height=self.height, expand=True,
+                                 on_resize=self._resized)
+
+    def _resized(self, e) -> None:
+        self.width, self.height = e.width, e.height or self.height
+        self._draw()
+        update(self.control)
+
+    def set_color(self, color: str) -> None:
+        self.line.paint.color = color
+        self.area.paint.color = T.soft(color, 0.16)
+
+    def set(self, values: list, hi: float | None = None, target: float | None = None) -> None:
+        """New values (oldest first); hi overrides the top of the scale; target draws a dashed guide (e.g. 72 fps)."""
+        self.values, self.target = list(values)[-self.slots:], target
+        if hi is not None:
+            self.hi = hi
+        self._draw()
+
+    def _draw(self) -> None:
+        cv, w, h = self.cv, self.width, self.height
+        lo, hi = self.lo, self.hi
+        real = [v for v in self.values if v is not None]
+        if self.fit is not None and real:
+            mid, span = (max(real) + min(real)) / 2, max(self.fit, (max(real) - min(real)) * 1.3)
+            lo, hi = mid - span / 2, mid + span / 2
+        elif hi is None:
+            hi = max(real + [self.target or 0, self.lo + 1.0]) * 1.1
+        # the time window starts at min_slots points and widens to `slots` as data comes in (a new chart isn't a
+        # sliver at the right edge for its first minute)
+        runs = spark_points(self.values, w, h, lo, hi, max(self.min_slots, min(self.slots, len(self.values))))
+        line, area = [], []
+        for run in runs:
+            line.append(cv.Path.MoveTo(*run[0]))
+            line += [cv.Path.LineTo(x, y) for x, y in run[1:]]
+            area += [cv.Path.MoveTo(run[0][0], h), *[cv.Path.LineTo(x, y) for x, y in run],
+                     cv.Path.LineTo(run[-1][0], h), cv.Path.Close()]
+        self.line.elements, self.area.elements = line, area
+        guide = []
+        if self.target is not None and w > 0:
+            y = spark_points([self.target, self.target], w, h, lo, hi)[0][0][1]
+            guide = [cv.Path.MoveTo(0, y), cv.Path.LineTo(w, y)]
+        self.guide.elements = guide
+
+
+class MeterBar:
+    """A thin horizontal bar of coloured segments (per-core load, power split); widths are fractions of the bar."""
+
+    def __init__(self, colors: list[str], height: int = 6):
+        self.segments = [ft.Container(bgcolor=c, expand=0, height=T.px(height)) for c in colors]
+        self.rest = ft.Container(expand=1000, height=T.px(height))
+        self.control = ft.Container(ft.Row([*self.segments, self.rest], spacing=0), bgcolor=T.SURFACE_3,
+                                    border_radius=T.px(height), height=T.px(height),
+                                    clip_behavior=ft.ClipBehavior.HARD_EDGE)
+
+    def set(self, fractions: list[float]) -> None:
+        """Fractions (0..1) per segment; the rest of the bar stays empty. Expand weights are integers (per mille)."""
+        total = 0
+        for seg, f in zip(self.segments, fractions, strict=False):
+            seg.expand = max(0, int(round(min(1.0, max(0.0, f)) * 1000)))
+            seg.visible = seg.expand > 0
+            total += seg.expand
+        self.rest.expand = max(1, 1000 - total)
+
+
+class LoopUpdater:
+    """update() for controls changed on a background thread that Flet doesn't know (e.g. an SSH reader): the patch is
+    sent from Flet's event loop. Flet 1.0's desktop connection queues outgoing messages on an asyncio.Queue with
+    put_nowait, which from a foreign thread doesn't wake the loop: the window only showed such updates after the next
+    UI event (the Monitor stayed empty until a click, its charts jumped in bursts). Updates requested while one is
+    pending are merged into it, so a fast stream can't pile up work on the loop."""
+
+    def __init__(self, page: ft.Page):
+        import threading
+
+        self.page = page
+        self._lock = threading.Lock()
+        self._pending: dict[int, ft.Control] = {}
+        self._scheduled = False
+
+    def __call__(self, *controls: ft.Control) -> None:
+        with self._lock:
+            for c in controls:
+                self._pending[id(c)] = c
+            if self._scheduled:
+                return
+            self._scheduled = True
+        try:
+            self.page.run_task(self._flush)
+        except Exception:  # noqa: BLE001 - no event loop (tests, shutting down): update right here
+            self._flush_now()
+
+    async def _flush(self) -> None:
+        self._flush_now()
+
+    def _flush_now(self) -> None:
+        with self._lock:
+            items = list(self._pending.values())
+            self._pending.clear()
+            self._scheduled = False
+        update(*items)

src/frameport/ui/dropped.py

@@ -0,0 +1,51 @@
+"""What to do with files dropped on the Library window (no Flet, tested directly)."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+MAX_LOOK = 5000  # entries looked at in a dropped folder before deciding
+
+
+def _folder_kind(folder: Path) -> str:
+    """"folder" (APKs or a Windows game: scanned like "Scan a folder") or "linux" (Linux programs only)."""
+    from ..analysis import linux
+
+    elf = False
+    seen = 0
+    for root, dirs, files in os.walk(folder):
+        if len(Path(root).relative_to(folder).parts) >= 3:
+            dirs[:] = []
+        for name in files:
+            seen += 1
+            low = name.lower()
+            if low.endswith((".apk", ".exe")):
+                return "folder"
+            if not elf and ("." not in name or low.endswith(".appimage")):
+                elf = linux.elf_machine(Path(root) / name) is not None or linux.is_appimage(Path(root) / name)
+            if seen > MAX_LOOK:
+                return "linux" if elf else "folder"
+    return "linux" if elf else "folder"
+
+
+def route(paths: list[str]) -> list[tuple[str, str]]:
+    """[(kind, path)] with kind apk | linux | exe | manifest | folder | unknown."""
+    from ..analysis import linux
+
+    out = []
+    for raw in paths:
+        p = Path(raw)
+        low = p.name.lower()
+        if p.is_dir():
+            out.append((_folder_kind(p), raw))
+        elif low.endswith(".apk"):
+            out.append(("apk", raw))
+        elif low.endswith(".exe"):
+            out.append(("exe", raw))
+        elif low.endswith(".json"):
+            out.append(("manifest", raw))
+        elif p.is_file() and linux.looks_like_linux_app(p):
+            out.append(("linux", raw))
+        else:
+            out.append(("unknown", raw))
+    return out

src/frameport/ui/help.py

@@ -65,6 +65,17 @@ HELP: dict[str, str] = _Translated({
     "launch_test": "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.",
+    "install_links": "Some developers put an \"Install with FrameDrop\" button on their site (the protocol of the "
+                     "FrameDrop sideloader). FramePort reads the same links: it shows what the link offers, asks, "
+                     "downloads it, adds it to your library and installs it on the Frame. Only https links to "
+                     "public servers are used. Windows and Linux open these links in FramePort; on macOS, paste the "
+                     "link into Add games → Install from a link….",
+    "linux_x86": "The Frame's CPU is arm64. Programs built for x86_64 PCs run through FEX, Valve's x86 translator, "
+                 "with the x86 libraries SteamOS ships for it (glibc, Mesa) - the way Steam on the Frame runs x86 "
+                 "Linux games. That works for many programs but is slower: use an arm64 build when there is one.",
+    "flatscreen": "How Lepton shows an Android app: VR (the headset shows what the app draws through OpenXR) or a "
+                  "flat window (a phone/tablet app on a screen in the headset). Automatic picks a window for apps "
+                  "without VR code.",
     "uninstall": "Removes the game from the Frame. Saves are kept, so a reinstall picks up where you left off.",
     "experimental": "Not verified on many games yet: try it if the game doesn't work without it.",
     "abis": "The CPU types the game ships code for. The Frame runs only 64-bit ARM (arm64-v8a); 32-bit-only games "
@@ -118,6 +129,17 @@ HELP: dict[str, str] = _Translated({
                   "Storage = 4XPlayer): upload into that folder in the game's storage.",
     "free_space": "Deletes the rollback copies kept from each game's previous install and leftover uploads. The "
                   "games and saves stay.",
+    "install_drive": "Where new games go on the Frame: its internal storage or another drive, such as a microSD card "
+                     "(in a FramePort folder on it). Games you installed already stay where they are; move one with "
+                     "right-click → Move to…. The launcher and Steam entry always stay on internal storage. Drives "
+                     "formatted as FAT, exFAT or NTFS can't hold games (Android and Proton need Linux file "
+                     "permissions): format the card in SteamOS first.",
+    "move_game": "Copies the game's files, data and saves to the other drive, checks the copy and then removes the "
+                 "old one. The Steam entry, settings and saves stay valid. The game must be closed. A game on a "
+                 "microSD card only starts while the card is inserted.",
+    "desktop_entry": "Adds the app to Desktop Mode's application menu and puts an icon on its desktop. Some apps work "
+                     "better there, with a mouse and keyboard, than in Gaming Mode, where Steam Input turns the "
+                     "controllers into a gamepad.",
     "adapter_settings": "Sharpness, refresh rate, controllers, menus and more for this game. Changes are used the "
                         "next time it starts.",
     "frame_summary": "Quest ✓: Lepton is installed, so Quest games can run. PC VR ✓: Proton is installed, so PC VR "
@@ -139,4 +161,14 @@ HELP: dict[str, str] = _Translated({
     "diag_bundle": "A zip with FramePort's logs, the game's recipe and analysis, launch-test logs and the Frame's "
                    "runtime details — enough to debug without the game files. IP addresses, host and user names, "
                    "home folders and Steam ids are replaced by placeholders. Attach it to a GitHub issue.",
+    "monitor_gpu": "How much of the time the Frame's graphics chip was busy, added up from every program that draws "
+                   "(the game, SteamVR's compositor, Steam). Near 100 % the game can't keep its frame rate.",
+    "monitor_pressure": "Memory in use by everything on the Frame. \"Waiting\" is the share of time programs had to "
+                        "wait for memory in the last 10 s: when it climbs, the Frame is running out and may freeze or "
+                        "close a game.",
+    "monitor_power": "What the whole Frame draws right now (its main power rail), with the share of the CPU and the "
+                     "graphics chip. Higher power means more heat and a shorter battery.",
+    "monitor_filter": "Game: the running FramePort game's processes (its Android container or Proton) plus the busiest "
+                      "others. Steam & SteamVR: Steam, SteamVR and the desktop. All: every program of your user on "
+                      "the Frame. A lock marks programs whose end would close Steam, SteamVR or the desktop.",
 })

src/frameport/ui/views/frame.py

@@ -7,7 +7,8 @@ from typing import TYPE_CHECKING
 import flet as ft
 
 from ...core import library
-from ...i18n import tr
+from ...errors import explain
+from ...i18n import tr, tr_n
 from .. import components as C
 from .. import theme as T
 from ..battery import label as battery_label
@@ -82,6 +83,64 @@ class FrameView:
         return C.section(tr("Ready to play"), C.card(ft.Column(rows, spacing=0),
                                                      padding=ft.Padding(T.S4, T.S2, T.S4, T.S2)))
 
+    def storage(self, info: dict) -> ft.Control:
+        """Drives games can go on (GitHub #90) and where new games go. The list comes from the Frame in the
+        background."""
+        from ...install import drives
+
+        app = self.app
+        current = drives.install_dest()
+        pick = ft.Dropdown(label=tr("Install new games to"), value=current or drives.INTERNAL, width=T.px(380),
+                           dense=True, border_color=T.BORDER, text_size=T.T_BODY, disabled=True,
+                           options=[ft.DropdownOption(key=drives.INTERNAL, text=tr("Internal storage"))])
+        rows = ft.Column([C.meta(tr("Looking for drives…"))], spacing=T.px(6))
+
+        def choose(e):
+            value = e.control.value or drives.INTERNAL
+            drives.set_install_dest(None if value == drives.INTERNAL else value)
+            label = next((o.text for o in pick.options if o.key == value), value)
+            app.toast(tr("New games go to {label}").format(label=label))
+
+        pick.on_select = choose
+
+        def name(d: dict) -> str:
+            return tr("Internal storage") if d["internal"] else d["label"]
+
+        def fill():
+            try:
+                found = app.target.drives() if app.target else []
+            except Exception as exc:  # noqa: BLE001 - shown in place of the list
+                rows.controls = [C.meta(tr("Couldn't list the Frame's drives: {error}").format(error=explain(exc)))]
+                C.update(rows)
+                return
+            opts, lines = [], []
+            for d in found:
+                free = drives.free_text(d)
+                if d.get("usable"):
+                    opts.append(ft.DropdownOption(key=drives.INTERNAL if d["internal"] else d["install_dir"],
+                                                  text=" · ".join(filter(None, [name(d), free]))))
+                state = tr_n("{n} game", "{n} games", d.get("games", 0)) if d.get("usable") else \
+                    tr("can't hold games: {reason}").format(reason=d.get("reason") or "")
+                lines.append(ft.Row([
+                    ft.Icon(ft.Icons.SD_CARD_ROUNDED if d.get("removable") else ft.Icons.STORAGE_ROUNDED,
+                            size=T.px(18), color=T.TEXT_2 if d.get("usable") else T.TEXT_3),
+                    C.body(name(d), T.TEXT if d.get("usable") else T.TEXT_3, expand=True),
+                    C.meta(" · ".join(filter(None, [d.get("fstype"), free, state]))),
+                ], spacing=T.S2))
+            if current and not any(o.key == current for o in opts):  # the chosen card isn't inserted now
+                label = current.rstrip("/").rsplit("/", 2)[-2] if current.rstrip("/").endswith("/FramePort") \
+                    else current
+                opts.append(ft.DropdownOption(key=current, text=tr("{label} (not inserted)").format(label=label)))
+            pick.options = opts or pick.options
+            pick.disabled = len(opts) < 2
+            rows.controls = lines or [C.meta(tr("Only internal storage"))]
+            C.update(pick)
+            C.update(rows)
+
+        app.run_bg(fill)
+        return C.section(tr("Storage"), C.card(ft.Column([pick, rows], spacing=T.S3), padding=T.S4),
+                         help="install_drive")
+
     def installed(self, info: dict) -> ft.Control:
         """The list fills in the background (icon thumbnails may need creating the first time)."""
         items = info.get("installed") or []
@@ -105,6 +164,7 @@ class FrameView:
             return spacer
 
         from ...artwork import thumbs
+        from ...install.drives import game_drive as drive_of
         from .files_dialog import show_files_dialog
         from .library import display_title, twins
 
@@ -121,7 +181,9 @@ class FrameView:
             sub = (tr("PC VR · Proton") + (tr(" + Revive") if d.get("revive") else "")) if pcvr else \
                 (C.platform(games[pkg])[0] if in_lib else tr("Linux") if d.get("kind") == "linux" else tr("Quest"))
             sub += (tr(" · {value:.1f} GiB").format(value=size / 2**30) if size >= 2**30
-                    else tr(" · {value:.0f} MiB").format(value=size / 2**20))
+                    else tr(" · {value:.0f} MiB").format(value=size / 2**20)) if size or not d.get("drive_missing") \
+                else ""
+            sub += C.drive_note(drive_of(d))
             title = display_title(games[pkg], tw) if in_lib else (d.get("title") or pkg)
             rows.append(ft.Container(ft.Row([
                 C.art_fill(art, radius=T.px(8), width=T.px(44), height=T.px(44)),
@@ -391,5 +453,5 @@ class FrameView:
             return self.wizard()
         return ft.Column([
             app.top_bar(tr("Steam Frame"), tr("Your headset, what it's ready for and what's installed")),
-            self.device_card(info), self.readiness(info), self.installed(info),
+            self.device_card(info), self.readiness(info), self.storage(info), self.installed(info),
         ], spacing=T.S5, scroll=ft.ScrollMode.AUTO, expand=True)

src/frameport/ui/views/game.py

@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING
 import flet as ft
 
 from ... import pipeline
+from ...analysis.detect import android_version, too_new_android
 from ...artwork import thumbs
 from ...core import library
 from ...i18n import tr, tr_n
@@ -168,6 +169,10 @@ class GameView:
         rift_platform = self.rift and (g["analysis"].get("extra") or {}).get("platform_sdk")
         frame_color = (T.TEXT_3 if (rift_oculus or rift_platform) and not frame_ok else
                        T.OK if st == "installed" else T.WARN if st == "outdated" else T.TEXT_3)
+        drive = C.frame_drive(g, app.frame_info) if frame_ok else None  # a microSD card (GitHub #90)
+        frame_line += C.drive_note(drive)
+        if drive and drive.get("missing"):
+            frame_color = T.WARN
         frame_sub = (tr("Oculus game — needs Revive, which doesn't run on the Frame. Play it on this PC (SteamVR).")
                      if rift_oculus else
                      tr("Needs the Oculus Platform (Meta Horizon app) for its license check, which the Frame doesn't "
@@ -269,7 +274,32 @@ class GameView:
                 C.body(tr("The Frame's Steam library still shows the old artwork."), T.TEXT, expand=True),
                 C.secondary(tr("Update Steam art on Frame"), ft.Icons.IMAGE_OUTLINED,
                             lambda e: self.app.update_steam_art(pkg))]), "info", ft.Icons.IMAGE_OUTLINED))
-        if recipe.status == "unsupported":
+        min_sdk = extra.get("min_sdk")
+        too_new = not self.rift and not self.linux and too_new_android(min_sdk)
+        if too_new:
+            # whatever the recipe says: the manifest asks for a newer Android (a warning only, a launch test decides)
+            out.append(C.callout(tr("Its manifest asks for Android {version} (API {api}); the Frame's Android is 11 "
+                                    "(API 30). Apps like this often crash at start, but not always: try it, a "
+                                    "launch test tells.").format(version=android_version(min_sdk), api=min_sdk),
+                                 "warn", ft.Icons.PHONELINK_ERASE_ROUNDED))
+        if pipeline.missing_obb(g):
+            out.append(C.callout(tr("This game's data file (.obb) wasn't found next to the APK. Put the .obb files "
+                                    "in a folder named {package} (or obb/) next to the APK and add the folder again; "
+                                    "without it the game hangs at start.").format(package=pkg), "error",
+                                 ft.Icons.FOLDER_OFF_ROUNDED))
+        web = (extra.get("web_wrapper") or None) if not self.rift and not self.linux else None
+        if web:
+            out.append(C.callout(ft.Column([
+                C.body(tr("This app looks like a website in an Android wrapper: it opens the site in Meta's "
+                          "browser, which the Frame doesn't have. If nothing opens, use the website in a browser "
+                          "instead."), T.TEXT)]
+                + ([C.meta(web["url"], T.TEXT_2, selectable=True)] if web.get("url") else []), spacing=T.px(4)),
+                "warn", ft.Icons.LANGUAGE_ROUNDED))
+        static = " ".join(engine.blocker_notes(library.analysis_from_dict(g["analysis"]))) \
+            if (too_new or web) else ""
+        if static and recipe.notes.strip() == static:
+            pass  # the recipe's note says the same (shown above)
+        elif recipe.status == "unsupported":
             out.append(C.callout(recipe.notes or tr("This game can't run on the Steam Frame."), "error"))
         elif recipe.notes and not (self.rift and extra.get("platform_sdk")):
             out.append(C.callout(recipe.notes, "info"))
@@ -431,15 +461,33 @@ class GameView:
             C.kv(tr("Program"), ft.Row([C.body(g.get("exe") or "", T.TEXT, selectable=True)]
                                        + ([change] if change else []), spacing=T.S2, wrap=True)),
             C.kv(tr("AppImage"), tr("Yes") if extra.get("appimage") else tr("No"), "appimage"),
+            C.kv(tr("CPU"), tr("x86_64: runs through FEX (x86 translation, slower; FramePort installs FEX on the "
+                               "Frame)") if extra.get("x86_64") else tr("arm64 (runs natively)"), "linux_x86"),
             C.kv(tr("VR (OpenXR)"), tr("Yes: uses the Frame's OpenXR runtime") if vr else
                  tr("No: a 2D app")),
             C.kv(tr("Source"), extra.get("source") or g.get("game_dir") or ""),
+            C.kv(tr("Desktop Mode"), C.switch(tr("In the menu and on the desktop"),
+                                              value=g.get("desktop_entry", True) is not False,
+                                              on_change=self.set_desktop_entry), "desktop_entry"),
         ]
         return C.section(tr("What FramePort will do"), C.card(ft.Column([
             ft.Row([ft.Icon(ft.Icons.TERMINAL_ROUNDED, color=T.PC, size=T.px(18)),
                     C.body(lead, T.TEXT, weight=ft.FontWeight.W_500, expand=True)], spacing=T.S2),
             *rows], spacing=T.S3)), help="linux_app")
 
+    def set_desktop_entry(self, e) -> None:
+        """A Linux app's Desktop Mode entry (GitHub #84): kept with the game, applied on the Frame at once when it's
+        installed there (else at the next install)."""
+        app, pkg, on = self.app, self.package, bool(e.control.value)
+
+        def work():
+            library.upsert_game(pkg, desktop_entry=on)
+            if app.frame_state == "connected" and app.target and \
+                    C.install_state(self.g, app.frame_info) in ("installed", "outdated"):
+                app.target.set_desktop_entry(pkg, on)
+            app.toast(tr("Added to Desktop Mode") if on else tr("Removed from Desktop Mode"))
+        app.run_bg(work)
+
     def recipe_summary(self) -> ft.Control:
         if self.linux:
             return self.linux_summary()
@@ -513,6 +561,9 @@ class GameView:
         state = {"recipe": recipe}
         warn = C.body("", T.WARN)
         technical = bool(library.setting("ui.patch_details", False))  # remembered for every game
+        # workarounds the last build left out because OVRPort's output already had the fix (patches/upstream.py)
+        superseded = (g.get("build") or {}).get("superseded") or {}
+        upstream_note = tr("Not needed in the last build: OVRPort fixed this itself.")
 
         def save(r):
             r.source = "user"
@@ -572,12 +623,16 @@ class GameView:
 
                     vals = recipe_values(g)
                     changed = sum(1 for k, v in vals.items() if v != default(k))
+                    fixed = [base.get(pid).title for pid in superseded if pid.startswith("adapter.")]
+                    fixed_note = [C.meta(tr("Not needed in the last build, OVRPort fixed it itself: {names}").format(
+                        names=", ".join(tr(t) for t in fixed)), T.TEXT_3)] if fixed else []
                     sections.append(C.card(ft.Row([
                         ft.Column([ft.Row([C.body(CATEGORY_TITLES[cat], T.TEXT, weight=ft.FontWeight.W_600),
                                            C.help_icon("cat_adapter")], spacing=T.S2),
                                    C.meta(tr_n("{n} setting changed from the default",
                                                "{n} settings changed from the default", changed) if changed
-                                          else tr("All at their defaults"))], spacing=T.px(2), expand=True),
+                                          else tr("All at their defaults")), *fixed_note], spacing=T.px(2),
+                                  expand=True),
                         C.secondary(tr("Change settings…"), ft.Icons.TUNE_ROUNDED,
                                     lambda e: app.settings_dialog(package)),
                     ], spacing=T.S3), padding=ft.Padding(T.S4, T.S3, T.S4, T.S3)))
@@ -594,6 +649,8 @@ class GameView:
                     shown = tr(reason).replace("overport", "OVRPort") if technical else \
                         plain_reason(reason, p.default_on)
                     sub.insert(0, C.meta(shown, T.ACCENT))
+                if on and p.id in superseded:
+                    sub.append(C.meta(upstream_note, T.TEXT_3))
                 extra = None
                 choices = getattr(p, "CHOICES", None)
                 if choices:  # a plain choice instead of a switch + text field (e.g. Proton: Experimental / Stable)

src/frameport/ui/views/keyboard.py

@@ -0,0 +1,161 @@
+"""Type on Frame: this computer's keyboard becomes a keyboard on the Frame while the tab is open (frame/keyboard.py).
+Keys go to whatever has focus on the Frame: an app's text field, Steam, the desktop, a PC game.
+
+Persistent like the other tabs: the virtual keyboard is created when the tab is shown and removed when another tab is
+opened or the Frame disconnects (app.go / app.disconnect call stop()), so no keyboard lingers on the Frame.
+"""
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import TYPE_CHECKING
+
+import flet as ft
+
+from ...errors import explain
+from ...i18n import tr
+from .. import components as C
+from .. import theme as T
+
+if TYPE_CHECKING:
+    from ..app import FramePortApp
+
+
+class KeyboardView:
+    def __init__(self, app: FramePortApp):
+        self.app = app
+        self.session = None  # frame.keyboard.KeyboardSession while the tab is open
+        self._connecting = False
+        self._gen = 0  # bumped by stop(): a connect that finishes after the tab was left closes its session
+        self.stopped = True  # by stop() (tab left, Frame gone): the next mount connects again
+        self.root = None
+        self.status = C.meta("")
+        self.last = ft.Text("", size=T.px(28), weight=ft.FontWeight.W_600, color=T.ACCENT)
+        hint = C.body(tr("Click here, then type. Everything you type goes to the Frame (Esc and shortcuts too)."),
+                      T.TEXT)
+        self.pad = ft.Container(ft.Column([hint, self.last], spacing=T.S2,
+                                          horizontal_alignment=ft.CrossAxisAlignment.CENTER),
+                                padding=T.S5, border_radius=T.RADIUS, bgcolor=T.BG, border=ft.Border.all(1, T.BORDER),
+                                alignment=ft.Alignment.CENTER, height=T.px(180), ink=True,
+                                on_click=lambda e: self.focus_keys())
+        self.listener = ft.KeyboardListener(self.pad, autofocus=True, on_key_down=self._forward("down"),
+                                            on_key_up=self._forward("up"), on_key_repeat=self._forward("repeat"))
+        self.paste = ft.TextField(hint_text=tr("Or paste text to type it in one go"), expand=True, dense=True,
+                                  border_color=T.BORDER, on_submit=self._send_text)
+        self.reconnect = C.secondary(tr("Reconnect"), ft.Icons.REFRESH_ROUNDED, lambda e: self.start())
+
+    # ---------------------------------------------------------------- building
+    def mount(self) -> ft.Control:
+        app = self.app
+        heading, sub = tr("Type on Frame"), tr("Use this computer's keyboard on the Frame")
+        if not (app.target and app.frame_state == "connected"):
+            return ft.Column([
+                app.top_bar(heading, sub),
+                C.empty_state(ft.Icons.KEYBOARD_ROUNDED, tr("Connect your Frame first"),
+                              tr("Typing on the Frame works once FramePort is connected to it."),
+                              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.status, self.reconnect], spacing=T.S3,
+                           vertical_alignment=ft.CrossAxisAlignment.CENTER),
+                    self.listener,
+                    ft.Row([self.paste, C.secondary(tr("Type it"), ft.Icons.SEND_ROUNDED, self._send_text)],
+                           spacing=T.S2),
+                ], spacing=T.S3)),
+                C.callout(tr("This computer's keyboard works as a keyboard on your Frame while this tab is open. In "
+                             "the headset, select a text field (in a game or app, in Steam or on the desktop), then "
+                             "type here.")),
+            ], spacing=T.S4, horizontal_alignment=ft.CrossAxisAlignment.STRETCH)
+        self.start()
+        return self.root
+
+    def _set_status(self, text: str, color: str, update: bool = True) -> None:
+        self.status.value, self.status.color = text, color
+        self.reconnect.visible = color == T.ERROR
+        if update:
+            C.update(self.status, self.reconnect)
+
+    # ---------------------------------------------------------------- session
+    def start(self) -> None:
+        """Connect the virtual keyboard (in the background) unless it is connected or connecting."""
+        self.app._typing_on_frame = True  # app._on_key leaves Esc / Ctrl+F alone: they go to the Frame
+        self.stopped = False
+        if self.session is not None or self._connecting:
+            return
+        self._connecting = True
+        self._set_status(tr("Connecting the keyboard…"), T.TEXT_2, update=self.root is not None)
+        gen, target = self._gen, self.app.target
+        self.app.run_bg(self._connect, gen, target)
+
+    def _connect(self, gen: int, target) -> None:
+        from ...frame.keyboard import KeyboardSession
+
+        try:
+            session = KeyboardSession(target.frame)
+        except Exception as exc:  # noqa: BLE001
+            self._connecting = False
+            if gen == self._gen:
+                self._fail(exc)
+            return
+        self._connecting = False
+        if gen != self._gen:  # the tab was left while connecting
+            session.close()
+            return
+        self.session = session
+        self._set_status(tr("Keyboard connected to {label}.").format(label=target.label), T.OK)
+        self.focus_keys()
+
+    def stop(self) -> None:
+        """Remove the keyboard from the Frame (leaving the tab, disconnecting, closing the app)."""
+        self._gen += 1
+        self.stopped = True
+        self.app._typing_on_frame = False
+        session, self.session = self.session, None
+        if session is not None:
+            session.close()
+
+    def _fail(self, exc) -> None:
+        session, self.session = self.session, None
+        if session is not None:
+            session.close()
+        self._set_status(tr("Keyboard disconnected: {error}").format(error=explain(exc)), T.ERROR)
+
+    # ---------------------------------------------------------------- input
+    def _forward(self, action: str):
+        def handler(e):
+            s = self.session
+            if s is None:
+                return
+            try:
+                if s.key(e.key, action) and action == "down":
+                    self.last.value = e.key if len(e.key) > 1 else e.key.upper()
+                    C.update(self.last)
+            except Exception as exc:  # noqa: BLE001 - the connection dropped
+                self._fail(exc)
+        return handler
+
+    def press(self, key: str) -> None:
+        """Simulate a key press (ui_smoke screenshots)."""
+        self.listener.on_key_down(SimpleNamespace(key=key))
+
+    def focus_keys(self) -> None:
+        try:
+            self.app.page.run_task(self.listener.focus)
+        except Exception:  # noqa: BLE001
+            pass
+
+    def _send_text(self, e=None) -> None:
+        s, text = self.session, self.paste.value or ""
+        if s is None or not text:
+            return
+
+        def work():
+            skipped = s.text(text)
+            self.paste.value = ""
+            C.update(self.paste)
+            self.focus_keys()
+            if skipped:
+                self.app.toast(tr("Typed it, except characters the Frame's US keyboard layout doesn't have: {chars}")
+                               .format(chars=skipped), error=True)
+        self.app.run_bg(work)

src/frameport/ui/views/library.py

@@ -225,8 +225,12 @@ class LibraryView:
                                     icon=ft.Icons.CREATE_NEW_FOLDER_ROUNDED, on_click=app.pick_game_folder),
                    ft.PopupMenuItem(content=ft.Text(tr("Add an APK file…")), icon=ft.Icons.ANDROID_ROUNDED,
                                     on_click=app.pick_apk),
+                   ft.PopupMenuItem(content=ft.Text(tr("Add a Windows program (.exe)…")),
+                                    icon=ft.Icons.DESKTOP_WINDOWS_ROUNDED, on_click=app.pick_windows_exe),
+                   ft.PopupMenuItem(content=ft.Text(tr("Install from a link…")), icon=ft.Icons.LINK_ROUNDED,
+                                    on_click=app.pick_link),
                    ft.PopupMenuItem(),  # divider: native Linux apps (GitHub #31)
-                   ft.PopupMenuItem(content=ft.Text(tr("Add a Linux app (arm64)…")), icon=ft.Icons.TERMINAL_ROUNDED,
+                   ft.PopupMenuItem(content=ft.Text(tr("Add a Linux app…")), icon=ft.Icons.TERMINAL_ROUNDED,
                                     on_click=app.pick_linux_app),
                    ft.PopupMenuItem(content=ft.Text(tr("Add a Linux app folder…")), icon=ft.Icons.FOLDER_ROUNDED,
                                     on_click=app.pick_linux_folder)],
@@ -247,13 +251,28 @@ class LibraryView:
                                         alignment=ft.MainAxisAlignment.END,
                                         vertical_alignment=ft.CrossAxisAlignment.CENTER), expand=3)],
                    vertical_alignment=ft.CrossAxisAlignment.CENTER, spacing=T.S3),
-            self.update_bar, self.resume_bar, self.hint, self.filters, self.body, self.sel_bar,
+            self.update_bar, self.resume_bar, self.hint, self.filters, self._drop_area(self.body), self.sel_bar,
         ], expand=True, spacing=T.S4)
         # skeleton cards until the first batch arrives
         n = min(len(library.games()), 15)
         self.grid.controls = [ft.Container(bgcolor=T.SURFACE, border_radius=T.RADIUS, border=ft.Border.all(1, T.BORDER),
                                            opacity=0.6) for _ in range(n)]
 
+    def _drop_area(self, content: ft.Control) -> ft.Control:
+        """APKs, Linux builds, Windows programs, folders and FrameDrop manifests dragged in from the file manager are
+        added (packaged app only: flet-dropzone, see files.dropzone_available)."""
+        from .files import dropzone_available
+
+        if not dropzone_available():
+            return content
+        import flet_dropzone as ftd
+
+        def dropped(e):
+            paths = [f.path for f in e.files if f.path and not f.path.startswith("blob:")]
+            if paths:
+                self.app.add_dropped(paths)
+        return ftd.Dropzone(content=content, expand=True, on_dropped=dropped)
+
     # ---------------------------------------------------------------- public
     def mount(self) -> ft.Control:
         self._update_hint()

src/frameport/ui/views/link_dialog.py

@@ -0,0 +1,138 @@
+"""Install links ("Install with FrameDrop" buttons, frameport:// links, pasted links): read the manifest, ask the user,
+download, add to the library and install on the Frame. The protocol itself is in deeplink.py (no Flet)."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import flet as ft
+
+from ... import deeplink, pipeline
+from ...core import library
+from ...i18n import fmt_size, tr
+from .. import components as C
+from .. import theme as T
+
+if TYPE_CHECKING:
+    from ..app import FramePortApp
+    from ..jobs import Job
+
+
+
+def kind_label(kind: str | None) -> str:
+    return {deeplink.APK: tr("Android app (APK)"), deeplink.LINUX: tr("Linux build"),
+            deeplink.EXE: tr("Windows program"), deeplink.OBB: tr("game data (OBB)")}.get(kind or "", tr("other file"))
+
+
+def show_paste_dialog(app: FramePortApp) -> None:
+    """Add games → "Install from link…": paste a FrameDrop/FramePort button link, a manifest or a file URL."""
+    field = ft.TextField(label=tr("Link"), hint_text="https://framedropvr.com/install?manifest=…", autofocus=True,
+                         width=T.px(560), border_color=T.BORDER)
+
+    def go(e=None):
+        text = (field.value or "").strip()
+        if not text:
+            return
+        app.page.pop_dialog()
+        open_link(app, text, pasted=True)
+    field.on_submit = go
+    app.page.show_dialog(ft.AlertDialog(
+        title=ft.Text(tr("Install from a link")), bgcolor=T.SURFACE_2,
+        content=ft.Column([
+            C.body(tr("Paste the address of an \"Install with FrameDrop\" button (right-click it → Copy link), a "
+                      "FramePort or FrameDrop manifest (.json) or a direct link to an APK, a Linux build (.zip) or a "
+                      "Windows program (.exe).")),
+            ft.Row([field, C.help_icon("install_links")]),
+        ], tight=True, spacing=T.S3, width=T.px(600)),
+        actions=[C.ghost(tr("Cancel"), on_click=lambda e: app.page.pop_dialog()),
+                 C.primary(tr("Continue"), ft.Icons.ARROW_FORWARD_ROUNDED, on_click=go)]))
+
+
+def open_link(app: FramePortApp, text: str, pasted: bool = False) -> None:
+    """A link from a web page (framedrop://, frameport://) or pasted: read what it offers in the background, then ask
+    before anything is downloaded."""
+    try:
+        req = deeplink.parse(text)
+    except deeplink.LinkError as exc:
+        app.toast(tr("Can't use that link: {reason}").format(reason=str(exc)), error=True)
+        return
+
+    def run(job: Job):
+        job.reporter.stage("Reading the install link")
+        m = deeplink.fetch_manifest(req)
+        sizes = {f.url: deeplink.head_size(f.url) for f in m.files}
+        icon = deeplink.fetch_icon(m)  # FramePort's manifest extension (None without one)
+        app.page.run_thread(lambda: _confirm(app, m, sizes, pasted, icon))
+        return tr("{name}: waiting for your answer").format(name=m.name)
+    app.submit(tr("Install link: {host}").format(host=_host(req.source)), run, None, "task")
+
+
+def _host(url: str) -> str:
+    from urllib.parse import urlsplit
+
+    return (urlsplit(url).hostname or url) if "://" in url else url
+
+
+def _header(m: deeplink.Manifest, icon) -> ft.Control | None:
+    """The manifest's icon and description (FramePort-only fields), when it has them."""
+    from ...artwork import thumbs
+
+    if not icon and not m.description:
+        return None
+    text = m.description if len(m.description) <= 400 else m.description[:400].rsplit(" ", 1)[0] + "…"
+    parts = []
+    if icon:
+        parts.append(ft.Image(src=thumbs.asset_url(icon), width=T.px(64), height=T.px(64), fit=ft.BoxFit.CONTAIN,
+                              border_radius=T.RADIUS_SM))
+    if text:
+        parts.append(ft.Container(C.body(text, T.TEXT, selectable=True), expand=True))
+    return ft.Row(parts, spacing=T.S3, vertical_alignment=ft.CrossAxisAlignment.START)
+
+
+def _confirm(app: FramePortApp, m: deeplink.Manifest, sizes: dict, pasted: bool, icon=None) -> None:
+    rows = []
+    header = _header(m, icon)
+    if header:
+        rows.append(header)
+    for f in m.files:
+        size = sizes.get(f.url)
+        # the file name on its own line (long names end in "…", the full name on hover), the facts below it
+        rows.append(ft.Column([
+            C.body(f.filename, T.TEXT, weight=ft.FontWeight.W_500, max_lines=1, overflow=ft.TextOverflow.ELLIPSIS,
+                   tooltip=f.filename),
+            C.meta(" · ".join(p for p in (kind_label(f.kind), fmt_size(size) if size else "",
+                                          tr("checksum checked") if f.sha256 else tr("no checksum")) if p)),
+        ], spacing=T.px(2), tight=True))
+    frame = app.frame_state == "connected"
+    notes = [C.callout(tr("Only install software from sites you trust. FramePort downloads it from {host} and "
+                          "installs it on your Frame.").format(host=m.host or _host(m.source)), "warn")]
+    if not frame:
+        notes.append(C.callout(tr("No Frame is connected: the game is added to your library now and installs once "
+                                  "the Frame is connected."), "info"))
+    if m.main.kind == deeplink.LINUX:
+        notes.append(C.body(tr("Linux builds must be made for arm64 (x86_64 builds run through translation, slower)."),
+                            T.TEXT_3))
+    heading = tr("Install {name}?").format(name=m.name)
+    intro = tr("You pasted a link to {name}.") if pasted else tr("A web page asked FramePort to install {name}.")
+    C.confirm(app.page, heading, intro.format(name=m.name), tr("Download and install"),
+              lambda: download_and_install(app, m, icon),
+              extra=ft.Column([*rows, *notes], spacing=T.S2, tight=True))
+
+
+def download_and_install(app: FramePortApp, m: deeplink.Manifest, icon=None) -> Job:
+    def run(job: Job):
+        rep = job.reporter
+        path = deeplink.download(m, rep)
+        rep.stage("Adding to the library")
+        g = pipeline.add_from_link(m, path, rep, icon=icon)
+        pkg = g["package"]
+        try:
+            from ...artwork import thumbs
+
+            thumbs.prewarm(pkg)
+        except Exception:  # noqa: BLE001 - artwork is optional
+            pass
+        library.set_setting("ui.welcome_done", True)
+        app.open_game(pkg)
+        app.page.run_thread(lambda: app.install(pkg, "frame"))  # asks the usual install questions, then queues it
+        return tr("Downloaded {name}").format(name=g.get("title") or m.name)
+    return app.submit(tr("Download {name}").format(name=m.name), run, None, "task")

src/frameport/ui/views/live.py

@@ -26,7 +26,7 @@ QUALITIES = [("360p", tr("360p (lightest)")), ("480p", "480p"), ("720p", tr("720
 
 
 def status_text(st: dict) -> str:
-    """One line for the relay's status (livestream.Relay.status)."""
+    """One line for the stream's status (livestream.LiveStream.status)."""
     if st.get("ended"):
         return tr("Stopped: {why}").format(why=st["ended"])
     if not st.get("ready"):
@@ -34,6 +34,10 @@ def status_text(st: dict) -> str:
     parts = [tr("Live")]
     if st.get("width"):
         parts.append(f"{st['width']}×{st['height']}")
+    if st.get("fps"):
+        parts.append(tr("{fps} fps").format(fps=st["fps"]))
+    if st.get("encoder"):
+        parts.append(tr("hardware encoder") if st["encoder"] == "hardware" else tr("software encoder"))
     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
@@ -41,6 +45,16 @@ def status_text(st: dict) -> str:
     return " · ".join(parts)
 
 
+def health_text(st: dict) -> str:
+    """A warning when the Frame dropped frames in the encoder's last 10 s (hardware encoder only), else ""."""
+    if not st.get("dropping") or st.get("ended"):
+        return ""
+    return tr_n("The Frame can't keep up at this quality: {n} frame dropped in the last 10 seconds. "
+                "Choose a lower quality for a smoother picture.",
+                "The Frame can't keep up at this quality: {n} frames dropped in the last 10 seconds. "
+                "Choose a lower quality for a smoother picture.", st.get("dropped") or 0)
+
+
 def default_quality() -> str:
     from ...install.livestream import DEFAULT_QUALITY
 
@@ -65,6 +79,7 @@ class LiveView:
         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)
+        self._push = None  # components.LoopUpdater (updates from background threads; a direct update dropped patches)
 
     # ---------------------------------------------------------------- building
     def mount(self) -> ft.Control:
@@ -92,8 +107,8 @@ class LiveView:
                              "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 Frame's hardware video encoder does the work (if it isn't available, the "
+                             "processor does, which costs a game more); stop the stream when you're done.")),
             ], spacing=T.S4, horizontal_alignment=ft.CrossAxisAlignment.STRETCH)
         self._refresh(update=False)
         self._ensure_ticker()
@@ -106,20 +121,24 @@ class LiveView:
             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()
+            st = live.status()
             ok = running and st.get("ready")
-            self.dot.bgcolor = T.OK if ok else T.ERROR if st.get("ended") else T.WARN
+            warning = health_text(st) if ok else ""
+            self.dot.bgcolor = T.WARN if warning else 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.detail.value = (warning if ok else "" if 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)
+        if update:  # called from the ticker / start / stream-end threads: send through Flet's event loop
+            if self._push is None:
+                self._push = C.LoopUpdater(self.app.page)
+            self._push(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():

src/frameport/ui/views/monitor.py

@@ -0,0 +1,746 @@
+"""Monitor: a live view of the Frame — the running game (fps, CPU/GPU/memory), CPU, GPU, memory, temperatures, power
+and battery with 2-minute sparklines, and its processes (end or kill one, end a game). Streamed by the agent's
+`_monitor` session (frame/monitor.py) only while the tab is shown: app.go / app.disconnect / closing the window call
+stop(), and the agent ends the stream at EOF, so nothing keeps running on the Frame.
+
+Built once and updated in place (CLAUDE.md performance rules): a tick changes values, colours and sparkline paths;
+the process table is a fixed pool of rows re-bound to the newest data, so clicks and menus keep working."""
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING
+
+import flet as ft
+
+from ...errors import explain
+from ...frame import monitor as M
+from ...i18n import tr
+from .. import components as C
+from .. import theme as T
+
+if TYPE_CHECKING:
+    from ..app import FramePortApp
+
+ROWS = 50            # process rows shown at most (the agent sends up to 150; the search narrows them)
+DETAIL_HEIGHT = 250  # the three detail cards share one height (px at 100 %)
+RETRY_SECONDS = 5    # reconnect after the stream was lost, while the tab is open
+LEVEL_COLOR = {"ok": T.TEXT, "warn": T.WARN, "error": T.ERROR}
+GROUP_COLOR = {"Game": T.ACCENT, "Steam": T.INFO, "SteamVR": T.PC, "Desktop": T.TEXT_2, "Other": T.TEXT_3}
+CLUSTER_COLORS = (T.INFO, T.ACCENT, T.PC, T.OK)
+POWER_COLORS = (T.INFO, T.ACCENT, T.PC, T.TEXT_3)  # CPU, GPU, NPU, other
+
+
+def label(name: str) -> str:
+    """The shown (translated) name of a process group or sensor group from the stream (literal tr() calls so
+    scripts/i18n_extract.py finds them)."""
+    return {"Game": tr("Game"), "Steam": tr("Steam"), "SteamVR": tr("SteamVR"), "Desktop": tr("Desktop"),
+            "Other": tr("Other"), "CPU": tr("CPU"), "GPU": tr("GPU"), "Memory": tr("Memory"),
+            "Battery": tr("Battery"), "NPU": tr("NPU"), "Power ICs": tr("Power ICs"), "Modem": tr("Modem"),
+            "Camera": tr("Camera"), "Storage": tr("Storage")}.get(name, name)
+
+
+class Tile:
+    """One metric: label, big value, a sub-line and a 2-minute sparkline."""
+
+    def __init__(self, label: str, icon: str, color: str, hi: float | None = None, help_key: str | None = None):
+        self.color = color
+        self.value = ft.Text("–", size=T.px(26), weight=ft.FontWeight.W_600, color=T.TEXT)
+        self.sub = C.meta("", max_lines=1, overflow=ft.TextOverflow.ELLIPSIS)
+        self.spark = C.Sparkline(color, height=34, hi=hi)
+        row = ft.Row([ft.Icon(icon, size=T.px(16), color=color), C.meta(label)], spacing=T.S2,
+                     vertical_alignment=ft.CrossAxisAlignment.CENTER)
+        if help_key:
+            row.controls.append(C.help_icon(help_key, 14))
+        head = ft.Container(row, height=T.px(22))
+        self.control = C.card(ft.Column([head, self.value, self.sub, self.spark.control], spacing=T.px(4)),
+                              padding=T.S3, col={"xs": 12, "sm": 6, "md": 4, "xl": 2})
+
+    def set(self, value: str, sub: str, series: list, lvl: str = "ok", target: float | None = None) -> None:
+        self.value.value, self.sub.value = value, sub
+        self.value.color = LEVEL_COLOR[lvl]
+        self.spark.set_color(self.color if lvl == "ok" else LEVEL_COLOR[lvl])
+        self.spark.set(series, target=target)
+
+
+class ProcRow:
+    """A pooled process row: created once, bound to whichever process is shown at its position."""
+
+    def __init__(self, view: MonitorView):
+        self.view, self.proc = view, None
+        self.lock = ft.Icon(ft.Icons.LOCK_OUTLINE_ROUNDED, size=T.px(14), color=T.WARN, visible=False,
+                            tooltip=tr("Ending this stops Steam, SteamVR or the desktop"))
+        self.chevron = ft.Icon(ft.Icons.CHEVRON_RIGHT_ROUNDED, size=T.px(16), color=T.TEXT_2, visible=False)
+        self.indent = ft.Container(width=T.px(22), visible=False)
+        self.name = ft.Text("", size=T.T_BODY, color=T.TEXT, max_lines=1, overflow=ft.TextOverflow.ELLIPSIS)
+        self.pid = C.meta("")
+        self.group = ft.Text("", size=T.T_SMALL, weight=ft.FontWeight.W_600)
+        self.group_box = ft.Container(self.group, border_radius=T.px(20),
+                                      padding=ft.Padding(T.px(8), T.px(2), T.px(8), T.px(2)))
+        self.cpu, self.gpu, self.mem, self.age = (ft.Text("", size=T.T_BODY, color=T.TEXT_2,
+                                                          text_align=ft.TextAlign.RIGHT) for _ in range(4))
+        dots = ft.GestureDetector(ft.Icon(ft.Icons.MORE_HORIZ_ROUNDED, size=T.px(18), color=T.TEXT_2),
+                                  on_tap_down=lambda e: self.view.open_menu(self.proc, e.global_position),
+                                  mouse_cursor=ft.MouseCursor.CLICK)
+        cells = [ft.Container(ft.Row([self.indent, self.chevron, self.lock, self.name], spacing=T.px(6), tight=True),
+                              expand=True),
+                 ft.Container(self.pid, width=T.px(70)), ft.Container(self.group_box, width=T.px(96)),
+                 ft.Container(self.cpu, width=T.px(64)), ft.Container(self.gpu, width=T.px(64)),
+                 ft.Container(self.mem, width=T.px(84)), ft.Container(self.age, width=T.px(76)),
+                 ft.Container(dots, width=T.px(32), alignment=ft.Alignment.CENTER)]
+        self.box = ft.Container(ft.Row(cells, spacing=T.S2, vertical_alignment=ft.CrossAxisAlignment.CENTER),
+                                padding=ft.Padding(T.S3, T.px(6), T.S2, T.px(6)), border_radius=T.RADIUS_SM,
+                                on_hover=self._hover, on_click=self._click)
+        self.control = ft.GestureDetector(self.box, visible=False,
+                                          on_secondary_tap_down=lambda e: self.view.open_menu(self.proc,
+                                                                                              e.global_position))
+
+    def _click(self, e) -> None:
+        if self.proc and self.proc.get("kind") == "group":  # a group row opens / closes its processes
+            self.view.toggle_group(self.proc)
+
+    def _hover(self, e) -> None:
+        self.box.bgcolor = T.SURFACE_2 if e.data in (True, "true") else None
+        C.update(self.box)
+
+    def bind(self, p: dict | None) -> None:
+        self.proc = p
+        self.control.visible = p is not None
+        if p is None:
+            return
+        kind = p.get("kind", "proc")
+        group_name = M.group_label(p.get("group", ""))
+        color = GROUP_COLOR[group_name]
+        self.chevron.visible, self.indent.visible = kind == "group", kind == "member"
+        if kind == "group":
+            self.chevron.name = ft.Icons.EXPAND_MORE_ROUNDED if p.get("expanded") else ft.Icons.CHEVRON_RIGHT_ROUNDED
+        self.name.value = f"{p.get('name', '')}  ×{p['count']}" if kind == "group" else p.get("name", "")
+        self.name.color = T.TEXT_3 if p.get("context") else T.TEXT
+        self.name.tooltip = p.get("game") or None
+        self.pid.value = tr("{n} processes").format(n=p["count"]) if kind == "group" else str(p.get("pid"))
+        self.group.value, self.group.color = label(group_name), color
+        self.group_box.bgcolor = T.soft(color, 0.12)
+        self.lock.visible = bool(p.get("critical") or p.get("locked"))
+        self.lock.color = T.TEXT_3 if p.get("locked") else T.WARN
+        self.cpu.value = f"{p.get('cpu', 0):.1f} %"
+        self.cpu.color = LEVEL_COLOR[M.level("cpu", p.get("cpu"))] if p.get("cpu", 0) >= 1 else T.TEXT_2
+        self.gpu.value = f"{p['gpu']:.0f} %" if p.get("gpu") else "–"
+        self.mem.value = M.fmt_bytes(p.get("rss"))
+        self.age.value = M.fmt_duration(p.get("age"))
+
+
+class MonitorView:
+    def __init__(self, app: FramePortApp):
+        self.app = app
+        self.session = None          # frame.monitor.MonitorSession while the tab is open
+        self._connecting = False
+        self._gen = 0                # bumped by stop(): a connect that finishes after the tab was left closes itself
+        self.stopped = True
+        self.root = None
+        self.history = M.History()
+        self.static: dict = {}
+        self.procs: list[dict] = []
+        self.sort_key, self.descending = "cpu", True
+        self.paused = False
+        self.games_meta: dict[str, dict] = {}  # package -> {"art": url | None, "in_library": bool}
+        self.game_pkg: str | None = None
+        self.last_games: list[dict] = []
+        self.last_sample: dict | None = None
+        self.expanded: set = set()   # process groups shown open: (parent pid, name)
+        self.push = None             # components.LoopUpdater: updates from the stream's thread
+        self._build()
+
+    # ---------------------------------------------------------------- building
+    def _build(self) -> None:
+        self.live_dot = C.dot(T.TEXT_3, T.px(8))
+        self.live_text = C.meta(tr("Connecting…"))
+        self.live = ft.Container(ft.Row([self.live_dot, self.live_text], spacing=T.S2, tight=True),
+                                 bgcolor=T.SURFACE_3, border_radius=T.px(20),
+                                 padding=ft.Padding(T.px(10), T.px(5), T.px(12), T.px(5)))
+        self.overhead = C.meta("")
+        self.interval = ft.Dropdown(value=f"{M.DEFAULT_INTERVAL:g}", dense=True, width=T.px(150),
+                                    border_color=T.BORDER, text_size=T.T_BODY,
+                                    options=[ft.DropdownOption(f"{s:g}", tr("Every {n}").format(n=M.fmt_interval(s)))
+                                             for s in M.INTERVALS],
+                                    on_select=self._set_interval, tooltip=tr("How often the Frame sends new numbers"))
+        self.pause_btn = C.icon_btn(ft.Icons.PAUSE_ROUNDED, tr("Pause"), lambda e: self.toggle_pause())
+        self.reconnect = C.secondary(tr("Reconnect"), ft.Icons.REFRESH_ROUNDED, lambda e: self.start())
+        self.reconnect.visible = False
+
+        # the running game
+        self.game_art = ft.Container(width=T.px(96), height=T.px(96), border_radius=T.RADIUS_SM,
+                                     bgcolor=T.SURFACE_2)
+        self.game_title = ft.Text("", size=T.px(20), weight=ft.FontWeight.W_600, color=T.TEXT, max_lines=1,
+                                  overflow=ft.TextOverflow.ELLIPSIS)
+        self.game_sub = C.meta("")
+        self.game_fps = ft.Text("–", size=T.px(40), weight=ft.FontWeight.W_700, color=T.TEXT)
+        self.game_fps_sub = C.meta(tr("frames per second"))
+        self.game_spark = C.Sparkline(T.OK, height=48)
+        self.game_stats = C.body("", T.TEXT_2)
+        self.end_btn = C.secondary(tr("End game"), ft.Icons.STOP_CIRCLE_OUTLINED, lambda e: self.ask_end_game())
+        self.page_btn = C.ghost(tr("Game page"), ft.Icons.OPEN_IN_NEW_ROUNDED,
+                                lambda e: self.game_pkg and self.app.open_game(self.game_pkg))
+        self.game_card = C.card(ft.Row([
+            self.game_art,
+            ft.Column([C.pill(tr("Running now"), T.OK, ft.Icons.PLAY_ARROW_ROUNDED), self.game_title, self.game_sub,
+                       self.game_stats, ft.Row([self.end_btn, self.page_btn], spacing=T.S2)],
+                      spacing=T.px(6), expand=3),
+            ft.Column([ft.Row([self.game_fps, self.game_fps_sub], spacing=T.S2,
+                              vertical_alignment=ft.CrossAxisAlignment.END),
+                       self.game_spark.control], spacing=T.px(4), expand=2,
+                      horizontal_alignment=ft.CrossAxisAlignment.STRETCH),
+        ], spacing=T.S4, vertical_alignment=ft.CrossAxisAlignment.CENTER), padding=T.S4, visible=False,
+            bgcolor=T.soft(T.ACCENT, 0.06))
+        self.game_card.border = ft.Border.all(1, T.soft(T.ACCENT, 0.35))
+
+        # metric tiles
+        self.t_cpu = Tile(tr("CPU"), ft.Icons.MEMORY_ROUNDED, T.INFO, hi=100)
+        self.t_gpu = Tile(tr("GPU"), ft.Icons.VIEW_IN_AR_ROUNDED, T.ACCENT, hi=100, help_key="monitor_gpu")
+        self.t_mem = Tile(tr("Memory"), ft.Icons.STORAGE_ROUNDED, T.PC, hi=100, help_key="monitor_pressure")
+        self.t_temp = Tile(tr("Temperature"), ft.Icons.THERMOSTAT_ROUNDED, T.WARN)
+        self.t_power = Tile(tr("Power"), ft.Icons.BOLT_ROUNDED, T.OK, help_key="monitor_power")
+        self.t_bat = Tile(tr("Battery"), ft.Icons.BATTERY_STD_ROUNDED, T.OK, hi=100)
+        self.tiles = ft.ResponsiveRow([t.control for t in (self.t_cpu, self.t_gpu, self.t_mem, self.t_temp,
+                                                            self.t_power, self.t_bat)],
+                                      spacing=T.S3, run_spacing=T.S3)
+
+        # details (filled once the stream says how many cores / which sensors the Frame has)
+        self.cores = ft.Column(spacing=T.px(6))
+        self.temps = ft.ResponsiveRow(spacing=T.S2, run_spacing=T.S2)
+        self.power_bar = C.MeterBar(list(POWER_COLORS), height=10)
+        self.power_legend = ft.Row(spacing=T.S4, run_spacing=T.S2, wrap=True)
+        self.net = ft.Column(spacing=T.px(4))
+        self.core_bars: list[tuple[C.MeterBar, ft.Text]] = []
+        self.temp_boxes: dict[str, tuple[ft.Text, C.Sparkline]] = {}  # group (or "fan") -> value, chart
+        self.legend_texts: list[ft.Text] = []
+        self.net_texts: dict[str, ft.Text] = {}
+        h = T.px(DETAIL_HEIGHT)
+        self.details = ft.ResponsiveRow([
+            C.card(ft.Column([C.meta(tr("CPU cores")), self.cores], spacing=T.S2), padding=T.S3, height=h,
+                   col={"xs": 12, "md": 6, "xl": 3}),
+            C.card(ft.Column([C.meta(tr("Temperatures and fan")), self.temps], spacing=T.S2), padding=T.S3,
+                   height=h, col={"xs": 12, "md": 6, "xl": 6}),
+            C.card(ft.Column([C.meta(tr("Where the power goes")), self.power_bar.control, self.power_legend,
+                              ft.Container(height=T.px(4)), C.meta(tr("Network")), self.net], spacing=T.S2),
+                   padding=T.S3, height=h, col={"xs": 12, "md": 6, "xl": 3}),
+        ], spacing=T.S3, run_spacing=T.S3, visible=False)
+        self.details_btn = C.ghost(tr("Show details"), ft.Icons.EXPAND_MORE_ROUNDED, lambda e: self.toggle_details())
+
+        # processes
+        self.filter = ft.SegmentedButton(
+            segments=[ft.Segment("game", label=tr("Game")), ft.Segment("steam", label=tr("Steam & SteamVR")),
+                      ft.Segment("all", label=tr("All"))],
+            selected=["game"], show_selected_icon=False, on_change=self._set_filter)
+        self.search = ft.TextField(hint_text=tr("Search name, PID or game"), dense=True, width=T.px(240),
+                                   border_color=T.BORDER, prefix_icon=ft.Icons.SEARCH_ROUNDED,
+                                   on_change=lambda e: self._bind_rows(update=True))
+        self.sort_btns: dict[str, ft.TextButton] = {}
+        left, right = ft.Alignment.CENTER_LEFT, ft.Alignment.CENTER_RIGHT
+        header_cells = [ft.Container(self._sort_btn("name", tr("Name")), expand=True, alignment=left),
+                        ft.Container(C.meta(tr("PID")), width=T.px(70), alignment=left),
+                        ft.Container(C.meta(tr("Group")), width=T.px(96), alignment=left),
+                        ft.Container(self._sort_btn("cpu", tr("CPU")), width=T.px(64), alignment=right),
+                        ft.Container(self._sort_btn("gpu", tr("GPU")), width=T.px(64), alignment=right),
+                        ft.Container(self._sort_btn("rss", tr("Memory")), width=T.px(84), alignment=right),
+                        ft.Container(C.meta(tr("Running")), width=T.px(76), alignment=right),
+                        ft.Container(width=T.px(32))]
+        self.header = ft.Container(ft.Row(header_cells, spacing=T.S2), padding=ft.Padding(T.S3, 0, T.S2, T.px(4)),
+                                   border=ft.Border(bottom=ft.BorderSide(1, T.BORDER)))
+        self.rows = [ProcRow(self) for _ in range(ROWS)]
+        self.proc_note = C.meta("")
+        self.no_game = C.callout(tr("No FramePort game is running. Start one in the headset or with Play, or switch "
+                                    "the filter to see everything on the Frame."), icon=ft.Icons.SPORTS_ESPORTS_ROUNDED)
+        self.no_game.visible = False
+        self.menu = ft.ContextMenu(content=C.card(ft.Column(
+            [self.header, ft.Column([r.control for r in self.rows], spacing=0), self.proc_note],
+            spacing=T.px(4)), padding=T.S2), secondary_trigger=None, tertiary_trigger=None)
+        self._update_sort_labels()
+
+    def _sort_btn(self, key: str, label: str) -> ft.TextButton:
+        b = ft.TextButton(label, on_click=lambda e, k=key: self.set_sort(k),
+                          style=ft.ButtonStyle(padding=0, color=T.TEXT_3,
+                                               text_style=ft.TextStyle(size=T.T_META, weight=ft.FontWeight.W_600)))
+        self.sort_btns[key] = b
+        return b
+
+    def mount(self) -> ft.Control:
+        app = self.app
+        heading, sub = tr("Monitor"), tr("What your Frame is doing right now")
+        if not (app.target and app.frame_state == "connected"):
+            return ft.Column([
+                app.top_bar(heading, sub),
+                C.empty_state(ft.Icons.MONITOR_HEART_OUTLINED, tr("Connect your Frame first"),
+                              tr("The monitor shows your Frame's games, load, temperatures and battery live once "
+                                 "FramePort is connected to it."),
+                              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, [self.overhead, self.live, self.reconnect, self.interval, self.pause_btn]),
+                self.game_card,
+                self.tiles,
+                ft.Row([self.details_btn], alignment=ft.MainAxisAlignment.START),
+                self.details,
+                C.section(tr("Processes"), ft.Row([self.filter, self.search], spacing=T.S3, wrap=True,
+                                                  run_spacing=T.S2, alignment=ft.MainAxisAlignment.SPACE_BETWEEN),
+                          self.no_game, self.menu, help="monitor_filter"),
+                ft.Container(height=T.S5),
+            ], spacing=T.S4, scroll=ft.ScrollMode.AUTO, expand=True)
+        self.start()
+        return self.root
+
+    # ---------------------------------------------------------------- session
+    def start(self) -> None:
+        self.stopped = False
+        if self.session is not None or self._connecting:
+            return
+        self._connecting = True
+        self._set_live(tr("Connecting…"), T.TEXT_3, update=self.root is not None)
+        gen, target = self._gen, self.app.target
+        self.app.run_bg(self._connect, gen, target)
+
+    def _connect(self, gen: int, target) -> None:
+        try:
+            session = M.MonitorSession(target.frame, lambda s, g=gen: self._on_sample(g, s),
+                                       lambda why, g=gen: self._on_end(g, why))
+        except Exception as exc:  # noqa: BLE001
+            self._connecting = False
+            if gen == self._gen:
+                self._set_live(tr("Not connected: {error}").format(error=explain(exc)), T.ERROR)
+            return
+        self._connecting = False
+        if gen != self._gen:  # the tab was left while connecting
+            session.close()
+            return
+        self.session = session
+        if session.static != self.static:
+            self.static = session.static
+            self._build_static()
+        if self.interval.value != f"{M.DEFAULT_INTERVAL:g}":
+            session.set_interval(float(self.interval.value))
+        if self.filter.selected != ["game"]:
+            session.set_filter(self.filter.selected[0])
+        if self.paused:
+            session.pause(True)
+        self._set_live(tr("Live"), T.OK)
+
+    def _on_end(self, gen: int, why: str) -> None:
+        if gen != self._gen:
+            return
+        self.session = None
+        self._set_live(tr("Connection lost, reconnecting…"), T.WARN)
+        timer = threading.Timer(RETRY_SECONDS, lambda: gen == self._gen and not self.stopped and self.start())
+        timer.daemon = True
+        timer.start()
+
+    def stop(self) -> None:
+        """End the stream (leaving the tab, disconnecting, closing the app)."""
+        self._gen += 1
+        self.stopped = True
+        session, self.session = self.session, None
+        if session is not None:
+            session.close()
+
+    def _set_live(self, text: str, color: str, update: bool = True) -> None:
+        self.live_text.value, self.live_dot.bgcolor = text, color
+        self.reconnect.visible = color == T.ERROR
+        if update:
+            C.update(self.live, self.reconnect)
+
+    def _set_interval(self, e) -> None:
+        if self.session:
+            self.session.set_interval(float(self.interval.value))
+
+    def toggle_pause(self) -> None:
+        self.paused = not self.paused
+        if self.session:
+            self.session.pause(self.paused)
+        self.pause_btn.icon = ft.Icons.PLAY_ARROW_ROUNDED if self.paused else ft.Icons.PAUSE_ROUNDED
+        self.pause_btn.tooltip = tr("Resume") if self.paused else tr("Pause")
+        self._set_live(tr("Paused") if self.paused else tr("Live"), T.TEXT_3 if self.paused else T.OK, update=False)
+        C.update(self.pause_btn, self.live)
+
+    def toggle_details(self) -> None:
+        self.details.visible = not self.details.visible
+        if self.details.visible and self.last_sample:  # fill it now, not at the next tick
+            self._apply_details(self.last_sample)
+        self.details_btn.content = tr("Hide details") if self.details.visible else tr("Show details")
+        self.details_btn.icon = ft.Icons.EXPAND_LESS_ROUNDED if self.details.visible else ft.Icons.EXPAND_MORE_ROUNDED
+        C.update(self.details, self.details_btn)
+
+    def _set_filter(self, e) -> None:
+        which = (self.filter.selected or ["game"])[0]
+        if self.session:
+            self.session.set_filter(which)
+
+    def set_sort(self, key: str) -> None:
+        if self.sort_key == key:
+            self.descending = not self.descending
+        else:
+            self.sort_key, self.descending = key, key != "name"
+        self._update_sort_labels()
+        self._bind_rows(update=True)
+        C.update(*self.sort_btns.values())
+
+    def _update_sort_labels(self) -> None:
+        names = {"name": tr("Name"), "cpu": tr("CPU"), "gpu": tr("GPU"), "rss": tr("Memory")}
+        for key, b in self.sort_btns.items():
+            arrow = (" ↓" if self.descending else " ↑") if key == self.sort_key else ""
+            b.content = names[key] + arrow
+            b.style.color = T.TEXT if key == self.sort_key else T.TEXT_3
+
+    # ---------------------------------------------------------------- static layout from the Frame
+    def _build_static(self) -> None:
+        st = self.static
+        colors = {}
+        for i, cl in enumerate(st.get("clusters") or []):
+            for cpu in cl.get("cpus") or []:
+                colors[cpu] = CLUSTER_COLORS[i % len(CLUSTER_COLORS)]
+        self.core_bars = []
+        rows = []
+        for cpu in range(st.get("cores") or 0):
+            bar, val = C.MeterBar([colors.get(cpu, T.INFO)], height=6), C.meta("", width=T.px(42),
+                                                                                text_align=ft.TextAlign.RIGHT)
+            self.core_bars.append((bar, val))
+            rows.append(ft.Row([C.meta(f"{cpu}", width=T.px(16)), ft.Container(bar.control, expand=True), val],
+                               spacing=T.S2, vertical_alignment=ft.CrossAxisAlignment.CENTER))
+        self.cores.controls = rows
+        self.temp_boxes = {}
+        boxes = []
+        names = [(g, label(g), T.WARN) for g in st.get("temp_groups") or []]
+        if st.get("fan"):
+            names.append(("fan", tr("Fan"), T.INFO))
+        for key, name, color in names:
+            value = ft.Text("–", size=T.T_BODY, weight=ft.FontWeight.W_600, color=T.TEXT)
+            spark = C.Sparkline(color, height=18, min_slots=60, fit=600.0 if key == "fan" else 4.0)
+            self.temp_boxes[key] = (value, spark)
+            head = ft.Row([C.meta(name), value], alignment=ft.MainAxisAlignment.SPACE_BETWEEN)
+            boxes.append(ft.Container(ft.Column([head, spark.control], spacing=T.px(2), tight=True),
+                                      bgcolor=T.SURFACE_2, border_radius=T.RADIUS_SM, col={"xs": 6, "sm": 4},
+                                      padding=ft.Padding(T.px(10), T.px(6), T.px(10), T.px(6))))
+        self.temps.controls = boxes
+        self.legend_texts = []
+        legend = []
+        for color, name in zip(POWER_COLORS, ("CPU", "GPU", "NPU", tr("Other")), strict=True):
+            t = C.meta(f"{name} –")
+            self.legend_texts.append(t)
+            legend.append(ft.Row([C.dot(color, T.px(8)), t], spacing=T.px(6), tight=True))
+        self.power_legend.controls = legend
+        self.net.controls, self.net_texts = [], {}
+        # through the event loop like the ticks: sent directly from this (connect) thread, the patch adding these
+        # boxes could arrive after a tick's patch for them ("dropped a patch for unknown control")
+        self._updater()(self.cores, self.temps, self.power_legend, self.net)
+
+    def _updater(self):
+        """The one components.LoopUpdater of this view: every update from the stream's threads goes through it, in
+        order, on Flet's event loop."""
+        if self.push is None:
+            self.push = C.LoopUpdater(self.app.page)
+        return self.push
+
+    # ---------------------------------------------------------------- samples
+    def _on_sample(self, gen: int, s: dict) -> None:
+        if gen != self._gen or self.root is None:
+            return
+        self.last_sample = s
+        for name, value in M.series_of(s).items():
+            self.history.add(name, value, s.get("t"))
+        changed = [self._apply_tiles(s), self._apply_game(s), self._apply_details(s)]
+        if "procs" in s:
+            self.procs = s.get("procs") or []
+            changed.append(self._bind_rows(update=False))
+        cpu_share = (s.get("self_ms") or 0) / 10 / max(1.0, s.get("dt") or 1.0) / max(1, self.static.get("cores", 1))
+        self.overhead.value = tr("Monitor is using {pct} % of the Frame's CPU").format(pct=f"{cpu_share:.2f}")
+        self.overhead.tooltip = tr("The time the Frame spends collecting these numbers")
+        self._updater()(self.overhead, *[c for group in changed for c in group])
+
+    def _apply_tiles(self, s: dict) -> list:
+        h, st = self.history, self.static
+        cpu = s.get("cpu") or {}
+        mhz = cpu.get("mhz") or []
+        clocks = " · ".join(f"{m / 1000:.1f}" for m in mhz) + (" GHz" if mhz else "")
+        self.t_cpu.set(M.fmt_pct(cpu.get("total")), clocks, h.get("cpu"), M.level("cpu", cpu.get("total")))
+        gpu = s.get("gpu") or {}
+        gmax = st.get("gpu_max_mhz")
+        sub = f"{gpu.get('mhz')} / {gmax} MHz" if gpu.get("mhz") is not None and gmax else ""
+        self.t_gpu.set(M.fmt_pct(gpu.get("busy")), sub, h.get("gpu"), M.level("gpu", gpu.get("busy")))
+        mem = s.get("mem") or {}
+        total, used = mem.get("total") or 0, (mem.get("total") or 0) - (mem.get("avail") or 0)
+        psi = (s.get("psi") or {}).get("memory")
+        swap = (mem.get("swap_total") or 0) - (mem.get("swap_free") or 0)
+        sub = tr("{used} of {total}").format(used=M.fmt_bytes(used), total=M.fmt_bytes(total))
+        if swap > 64 * 1024 ** 2:
+            sub += " · " + tr("swap {n}").format(n=M.fmt_bytes(swap))
+        if psi:
+            sub += " · " + tr("waiting {pct} %").format(pct=f"{psi:.0f}")
+        lvl = max((M.level("mem", 100.0 * used / total if total else None), M.level("psi_memory", psi)),
+                  key=("ok", "warn", "error").index)
+        self.t_mem.set(M.fmt_pct(100.0 * used / total if total else None), sub, h.get("mem"), lvl)
+        temps = s.get("temps") or {}
+        hot = max(temps.items(), key=lambda kv: kv[1]) if temps else None
+        sub = tr("hottest: {part}").format(part=label(hot[0])) if hot else ""
+        lvl = max((M.temp_level(g, v) for g, v in temps.items()), key=("ok", "warn", "error").index, default="ok")
+        self.t_temp.set(f"{hot[1]:.0f} °C" if hot else "–", sub, h.get("temp"), lvl)
+        pw = s.get("power") or {}
+        self.t_power.set(M.fmt_watts(pw.get("system")),
+                         " · ".join(f"{k.upper()} {M.fmt_watts(pw.get(k))}" for k in ("cpu", "gpu") if k in pw),
+                         h.get("power"))
+        bat = s.get("battery")
+        lvl = "error" if bat and bat.get("percent", 100) <= 10 and bat.get("draining") else \
+            "warn" if bat and bat.get("percent", 100) <= 20 and bat.get("draining") else "ok"
+        self.t_bat.set(M.fmt_pct(bat.get("percent")) if bat else "–", M.battery_line(bat), h.get("battery"), lvl)
+        self.t_bat.color = T.OK if bat and bat.get("plugged") else T.INFO
+        return [t.control for t in (self.t_cpu, self.t_gpu, self.t_mem, self.t_temp, self.t_power, self.t_bat)]
+
+    def _game_meta(self, pkg: str) -> dict:
+        meta = self.games_meta.get(pkg)
+        if meta is None:  # once per game, on the stream's thread (library + thumbnail lookups are file I/O)
+            from ...artwork import thumbs
+            from ...core import library
+            from .library import CARD_ART
+
+            entry = library.game(pkg)
+            meta = {"in_library": entry is not None,
+                    "art": thumbs.url(pkg, CARD_ART, wait=False) if entry else None}
+            self.games_meta[pkg] = meta
+        return meta
+
+    def _apply_game(self, s: dict) -> list:
+        games = s.get("games") or []
+        self.last_games = games
+        game = games[0] if games else None
+        was = self.game_card.visible
+        self.game_card.visible = game is not None
+        self.no_game.visible = game is None and (self.filter.selected or ["game"])[0] == "game"
+        if game is None:
+            if self.game_pkg is not None:
+                self.game_pkg = None
+                self.history.series.pop("fps", None)
+            return [self.game_card, self.no_game] if was else [self.no_game]
+        pkg = game["package"]
+        if pkg != self.game_pkg:
+            self.game_pkg = pkg
+            meta = self._game_meta(pkg)
+            # once per game (not per tick): its artwork, by asset URL
+            self.game_art.content = C.art_fill(meta["art"], radius=T.RADIUS_SM, width=T.px(96), height=T.px(96))
+            self.page_btn.visible = meta["in_library"]
+        kind = {"pcvr": tr("PC VR via Proton"), "linux": tr("Linux app")}.get(game.get("kind"), tr("Quest game"))
+        self.game_title.value = game.get("title") or pkg
+        self.game_sub.value = " · ".join(x for x in (kind, tr("running for {t}").format(
+            t=M.fmt_duration(game.get("elapsed"))) if game.get("elapsed") is not None else "") if x)
+        self.game_stats.value = tr("CPU {cpu} · GPU {gpu} · memory {mem} · {n} processes").format(
+            cpu=M.fmt_pct(game.get("cpu")), gpu=M.fmt_pct(game.get("gpu")), mem=M.fmt_bytes(game.get("mem")),
+            n=game.get("processes", 0))
+        fps = game.get("fps")
+        series = self.history.get("fps")
+        target = M.fps_target(series)
+        ratio = fps / target if fps and target else None
+        lvl = M.level("fps_ratio", ratio)
+        self.game_fps.value = f"{fps:.0f}" if fps is not None else "–"
+        self.game_fps.color = LEVEL_COLOR[lvl] if fps is not None else T.TEXT_3
+        if game.get("kind") in ("pcvr", "linux"):
+            self.game_fps_sub.value = tr("fps isn't reported for PC VR and Linux games")
+        elif fps is None:
+            self.game_fps_sub.value = tr("fps: waiting for the game's first frames")
+        else:
+            ms = game.get("frame_ms")
+            self.game_fps_sub.value = tr("fps · target {hz} Hz").format(hz=target) + (
+                f" · {ms:.1f} ms " + tr("late") if ms and ms >= 0.5 else "")
+        self.game_spark.set_color(T.OK if lvl == "ok" else LEVEL_COLOR[lvl])
+        self.game_spark.set(series, target=target, hi=(target or 72) * 1.15)
+        return [self.game_card, self.no_game]
+
+    def _apply_details(self, s: dict) -> list:
+        if not self.details.visible:
+            return []
+        out = []
+        cores = (s.get("cpu") or {}).get("cores") or []
+        for (bar, val), pct in zip(self.core_bars, cores, strict=False):
+            bar.set([pct / 100.0])
+            val.value = f"{pct:.0f} %"
+            out += [bar.control, val]
+        temps = s.get("temps") or {}
+        zones = s.get("zones")
+        for key, (text, spark) in self.temp_boxes.items():
+            if key == "fan":
+                fan = s.get("fan")
+                text.value = f"{fan} rpm" if fan is not None else "–"
+                spark.set(self.history.get("fan"))
+            else:
+                v = temps.get(key)
+                lvl = M.temp_level(key, v)
+                text.value = f"{v:.1f} °C" if v is not None else "–"
+                text.color = LEVEL_COLOR[lvl]
+                spark.set_color(T.WARN if lvl == "ok" else LEVEL_COLOR[lvl])
+                spark.set(self.history.get(f"temp:{key}"))
+                if zones and key in zones:
+                    text.tooltip = "\n".join(f"{z}: {c:.1f} °C" for z, c in sorted(zones[key].items()))
+            out += [text, spark.control]
+        split = M.power_split(s.get("power") or {})
+        total = sum(w for _n, w in split) or 1.0
+        self.power_bar.set([w / total for _n, w in split])
+        for t, (name, w) in zip(self.legend_texts, split, strict=False):
+            t.value = f"{label(name)} {M.fmt_watts(w)}"
+        out += [self.power_bar.control, *self.legend_texts]
+        net = s.get("net") or {}
+        new = [k for k in net if k not in self.net_texts]
+        for k in new:
+            self.net_texts[k] = C.meta("")
+            self.net.controls.append(self.net_texts[k])
+        for k, (rx, tx) in net.items():
+            self.net_texts[k].value = f"{k}  ↓ {M.fmt_rate(rx)}  ↑ {M.fmt_rate(tx)}"
+        out += [self.net] if new else list(self.net_texts.values())
+        return out
+
+    def _bind_rows(self, update: bool = True) -> list:
+        procs = M.sort_filter(self.procs, self.search.value or "", self.sort_key, self.descending)
+        rows = M.group_procs(procs, self.expanded)
+        for row, p in zip(self.rows, rows + [None] * ROWS, strict=False):
+            row.bind(p)
+        total = len(self.procs)
+        if len(rows) > ROWS:
+            self.proc_note.value = tr("Showing the top {shown} of {n} rows: search to find others.").format(
+                shown=ROWS, n=len(rows))
+        elif self.search.value and not procs:
+            self.proc_note.value = tr("No process matches.")
+        else:
+            self.proc_note.value = tr("{n} processes").format(n=total) if total else ""
+        controls = [r.control for r in self.rows] + [self.proc_note]
+        if update:
+            C.update(*controls)
+        return controls
+
+    # ---------------------------------------------------------------- actions
+    def toggle_group(self, row: dict) -> None:
+        """Open or close a process group (same name, same parent) in the table."""
+        key = row.get("key")
+        if key is None:
+            return
+        self.expanded.symmetric_difference_update({key})
+        self._bind_rows(update=True)
+
+    def open_menu(self, p: dict | None, position=None) -> None:
+        if not p:
+            return
+        name, pid = p.get("name", "?"), p.get("pid")
+        actions: list = []
+        if p.get("kind") == "group":
+            n = p["count"]
+            actions.append((tr("Hide its processes") if p.get("expanded") else tr("Show its processes"),
+                            ft.Icons.UNFOLD_MORE_ROUNDED, lambda e: self.toggle_group(p)))
+            if not p.get("locked"):
+                actions += [None, (tr("End all {n}").format(n=n), ft.Icons.CLOSE_ROUNDED,
+                                   lambda e: self.ask_kill(p, "TERM")),
+                            (tr("Force kill all {n}").format(n=n), ft.Icons.DANGEROUS_OUTLINED,
+                             lambda e: self.ask_kill(p, "KILL"))]
+            if p.get("game"):
+                actions += [None, (tr("End the whole game"), ft.Icons.STOP_CIRCLE_OUTLINED,
+                                   lambda e: self.ask_end_game(p["game"]))]
+            actions += [None, (tr("Copy name"), ft.Icons.CONTENT_COPY_ROUNDED, lambda e: self.app.copy(name))]
+            self.menu.items = C.menu_items(actions)
+            C.update(self.menu)
+            self.app.page.run_task(self.menu.open, global_position=position)
+            return
+        if not p.get("locked"):
+            actions += [(tr("End process"), ft.Icons.CLOSE_ROUNDED, lambda e: self.ask_kill(p, "TERM")),
+                        (tr("Force kill"), ft.Icons.DANGEROUS_OUTLINED, lambda e: self.ask_kill(p, "KILL"))]
+        if p.get("game"):
+            actions += [None, (tr("End the whole game"), ft.Icons.STOP_CIRCLE_OUTLINED,
+                               lambda e: self.ask_end_game(p["game"]))]
+        actions += [None, (tr("Copy PID {pid}").format(pid=pid), ft.Icons.CONTENT_COPY_ROUNDED,
+                           lambda e: self.app.copy(str(pid))),
+                    (tr("Copy name"), ft.Icons.CONTENT_COPY_ROUNDED, lambda e: self.app.copy(name))]
+        self.menu.items = C.menu_items(actions)
+        C.update(self.menu)
+        self.app.page.run_task(self.menu.open, global_position=position)
+
+    def ask_kill(self, p: dict, sig: str) -> None:
+        name, pid = p.get("name", "?"), p.get("pid")
+        if p.get("kind") == "group":
+            n = p["count"]
+            heading = (tr("Force kill all {n} {name}?") if sig == "KILL" else tr("End all {n} {name}?")).format(
+                n=n, name=name)
+            text = tr("{n} processes named {name} with the same parent are ended.").format(n=n, name=name)
+            if p.get("critical"):
+                text += " " + tr("They are part of Steam, SteamVR or the desktop: the headset view or Steam may "
+                                 "restart, and anything running in the headset may stop.")
+            C.confirm(self.app.page, heading, text, tr("Force kill all") if sig == "KILL" else tr("End all"),
+                      lambda: self.app.run_bg(self._kill, p, sig), danger=True)
+            return
+        if p.get("critical"):
+            heading = tr("End {name}?").format(name=name)
+            text = tr("{name} is part of Steam, SteamVR or the desktop. Ending it can close the headset view or "
+                      "restart Steam, and anything running in the headset may stop.").format(name=name)
+        elif sig == "KILL":
+            heading = tr("Force kill {name}?").format(name=name)
+            text = tr("{name} (PID {pid}) stops at once without saving anything.").format(name=name, pid=pid)
+        else:
+            heading = tr("End {name}?").format(name=name)
+            text = tr("{name} (PID {pid}) is asked to close.").format(name=name, pid=pid)
+            if p.get("game"):
+                text += " " + tr("It belongs to a running game, which may stop with it.")
+        label = tr("Force kill") if sig == "KILL" else tr("End process")
+        C.confirm(self.app.page, heading, text, label, lambda: self.app.run_bg(self._kill, p, sig),
+                  danger=sig == "KILL" or bool(p.get("critical")))
+
+    def _kill(self, p: dict, sig: str) -> None:
+        session = self.session
+        if session is None:
+            self.app.toast(tr("The monitor isn't connected."), error=True)
+            return
+        name = p.get("name", "?")
+        if p.get("kind") == "group":
+            left = []
+            for m in p.get("members") or []:
+                try:
+                    if not session.kill(m["pid"], sig, force=True).get("ended"):  # confirmed for the whole group
+                        left.append(m["pid"])
+                except Exception:  # noqa: BLE001 - one refusal (gone, system) doesn't stop the others
+                    left.append(m["pid"])
+            if left:
+                self.app.toast(tr("{n} of the {name} processes are still running.").format(n=len(left), name=name),
+                               action=None if sig == "KILL" else tr("Force kill"),
+                               on_action=None if sig == "KILL" else lambda e: self.app.run_bg(self._kill, p, "KILL"))
+            else:
+                self.app.toast(tr("All {n} {name} processes ended.").format(n=p["count"], name=name))
+            return
+        try:
+            res = session.kill(p["pid"], sig, force=bool(p.get("critical")))
+        except M.ProcessCritical:  # the table was older than the Frame's view of it
+            res = session.kill(p["pid"], sig, force=True)
+        except Exception as exc:  # noqa: BLE001
+            self.app.toast(explain(exc), error=True)
+            return
+        if res.get("ended"):
+            self.app.toast(tr("{name} ended.").format(name=name))
+        else:
+            self.app.toast(tr("{name} is still running.").format(name=name), action=tr("Force kill"),
+                           on_action=lambda e: self.app.run_bg(self._kill, p, "KILL"))
+
+    def ask_end_game(self, pkg: str | None = None) -> None:
+        pkg = pkg or self.game_pkg
+        if not pkg:
+            return
+        title = next((g.get("title") for g in self.last_games if g.get("package") == pkg), None) or pkg
+        C.confirm(self.app.page, tr("End {title}?").format(title=title),
+                  tr("The game is closed the way Steam's Exit game does it; if it doesn't stop, FramePort stops it. "
+                     "Progress that the game hasn't saved is lost."),
+                  tr("End game"), lambda: self.app.run_bg(self._end_game, pkg, title), danger=True)
+
+    def _end_game(self, pkg: str, title: str) -> None:
+        session = self.session
+        if session is None:
+            self.app.toast(tr("The monitor isn't connected."), error=True)
+            return
+        self.end_btn.disabled = True
+        C.update(self.end_btn)
+        try:
+            res = session.end_game(pkg)
+        except Exception as exc:  # noqa: BLE001
+            self.app.toast(explain(exc), error=True)
+            return
+        finally:
+            self.end_btn.disabled = False
+            C.update(self.end_btn)
+        if res.get("ended"):
+            self.app.toast(tr("{title} ended.").format(title=title))
+        else:
+            self.app.toast(tr("{title} is still running.").format(title=title), error=True)

src/frameport/ui/views/settings.py

@@ -165,6 +165,66 @@ class SettingsView:
                      on_change=toggle),
         ], spacing=T.S2)
 
+    def links_card(self) -> ft.Control:
+        """Settings → Install links: one switch per scheme — framedrop:// ("Install with FrameDrop" buttons on web
+        pages) and frameport:// (FramePort's own links) open FramePort (urlhandler)."""
+        from ... import urlhandler
+
+        app = self.app
+        rows = {}
+        last: dict = {}
+
+        def show(st: dict | None):
+            last.clear()
+            last.update(st or {})
+            for scheme, (_switch, state, take) in rows.items():
+                take.visible = False
+                if not last.get("supported", True):
+                    state.value = tr("This system can't send web links to FramePort: use Add games → Install from a "
+                                     "link…")
+                elif not urlhandler.enabled(scheme):
+                    state.value = tr("Off: these links open whatever app is set up for them, if any.")
+                elif last.get(scheme) == "other":
+                    state.value = tr("{app} opens these links on this PC.").format(
+                        app=last.get(f"{scheme}_by") or tr("Another app"))
+                    take.visible = True
+                elif last.get(scheme) == "ours":
+                    state.value = tr("These links open FramePort.")
+                else:
+                    state.value = tr("Not set up yet (FramePort registers itself when it starts).")
+            C.update(*[c for r in rows.values() for c in r[1:]])
+
+        def toggle(scheme):
+            def changed(e):
+                on = bool(e.control.value)
+                app.run_bg(lambda: show(urlhandler.set_enabled(scheme, on)))
+            return changed
+
+        def force(scheme):
+            def clicked(e):
+                other = last.get(f"{scheme}_by") or tr("the other app")
+                C.confirm(app.page, tr("Open {scheme}:// links with FramePort?").format(scheme=scheme),
+                          tr("These links will open FramePort instead of {app}. You can switch back in {app}, or by "
+                             "turning this setting off.").format(app=other),
+                          tr("Use FramePort"), lambda: app.run_bg(lambda: show(urlhandler.register([scheme],
+                                                                                                    force=True))))
+            return clicked
+
+        labels = {"framedrop": tr("Open \"Install with FrameDrop\" buttons (framedrop:// links) in FramePort"),
+                  "frameport": tr("Open frameport:// links in FramePort")}
+        controls = []
+        for scheme in urlhandler.SCHEMES:
+            switch = C.switch(labels[scheme], value=urlhandler.enabled(scheme), on_change=toggle(scheme))
+            state = C.meta(tr("Checking which app opens these links…"))
+            take = C.secondary(tr("Use FramePort for these links"), ft.Icons.LINK_ROUNDED, on_click=force(scheme))
+            take.visible = False
+            rows[scheme] = (switch, state, take)
+            controls.append(ft.Column([switch, ft.Container(ft.Column([state, take], spacing=T.S2),
+                                                            padding=ft.Padding(T.px(4), 0, 0, 0))],
+                                      spacing=T.px(4)))
+        app.run_bg(lambda: show(urlhandler.status()))
+        return ft.Column(controls, spacing=T.S4)
+
     def appearance(self) -> ft.Control:
         from ...core import library
 
@@ -260,6 +320,7 @@ class SettingsView:
                                                        shape=ft.RoundedRectangleBorder(radius=T.RADIUS_SM))),
             ], spacing=T.S3, horizontal_alignment=ft.CrossAxisAlignment.START))),
             C.section(tr("Installing"), C.card(self.installing(), padding=T.S4), help="launch_test"),
+            C.section(tr("Install links"), C.card(self.links_card(), padding=T.S4), help="install_links"),
             C.section(tr("Appearance"), C.card(self.appearance(), padding=T.S4), help="ui_scale"),
             C.section(tr("About"), C.card(ft.Column([
                 C.kv(tr("Version"), ver),

src/frameport/ui/views/type_dialog.py

@@ -1,117 +0,0 @@
-"""Type on Frame: this computer's keyboard becomes a keyboard on the Frame while the dialog is open (frame/keyboard.py).
-Keys go to whatever has focus on the Frame: an app's text field, Steam, the desktop, a PC game."""
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-import flet as ft
-
-from ...errors import explain
-from ...i18n import tr
-from .. import components as C
-from .. import theme as T
-
-if TYPE_CHECKING:
-    from ..app import FramePortApp
-
-
-def show_type_dialog(app: FramePortApp) -> None:
-    target = app.target
-    if target is None or app.frame_state != "connected":
-        app.toast(tr("Connect your Frame first"), error=True)
-        return
-    state = {"session": None, "closed": False}
-    status = C.meta(tr("Connecting the keyboard…"))
-    last = ft.Text("", size=T.px(28), weight=ft.FontWeight.W_600, color=T.ACCENT)
-    hint = C.body(tr("Click here, then type. Everything you type goes to the Frame (Esc and shortcuts too)."), T.TEXT)
-
-    def forward(action):
-        def handler(e):
-            s = state["session"]
-            if s is None or state["closed"]:
-                return
-            try:
-                if s.key(e.key, action) and action == "down":
-                    last.value = e.key if len(e.key) > 1 else e.key.upper()
-                    C.update(last)
-            except Exception as exc:  # noqa: BLE001 - the connection dropped
-                fail(exc)
-        return handler
-
-    pad = ft.Container(ft.Column([hint, last], spacing=T.S2, horizontal_alignment=ft.CrossAxisAlignment.CENTER),
-                       padding=T.S5, border_radius=T.RADIUS, bgcolor=T.BG, border=ft.Border.all(1, T.BORDER),
-                       alignment=ft.Alignment.CENTER, height=T.px(150), ink=True)
-    listener = ft.KeyboardListener(pad, autofocus=True, on_key_down=forward("down"), on_key_up=forward("up"),
-                                   on_key_repeat=forward("repeat"))
-    pad.on_click = lambda e: focus_keys()
-    paste = ft.TextField(hint_text=tr("Or paste text to type it in one go"), expand=True, dense=True,
-                         border_color=T.BORDER, on_submit=lambda e: send_text(None))
-
-    def focus_keys():
-        try:
-            app.page.run_task(listener.focus)
-        except Exception:  # noqa: BLE001
-            pass
-
-    def send_text(e):
-        s, text = state["session"], paste.value or ""
-        if s is None or not text:
-            return
-
-        def work():
-            skipped = s.text(text)
-            paste.value = ""
-            C.update(paste)
-            focus_keys()
-            if skipped:
-                app.toast(tr("Typed it, except characters the Frame's US keyboard layout doesn't have: {chars}")
-                          .format(chars=skipped), error=True)
-        app.run_bg(work)
-
-    def fail(exc):
-        status.value = tr("Keyboard disconnected: {error}").format(error=explain(exc))
-        status.color = T.ERROR
-        C.update(status)
-
-    def close(e=None):
-        state["closed"] = True
-        app._typing_on_frame = False
-        s = state["session"]
-        if s is not None:
-            s.close()
-        if e is not None:
-            app.page.pop_dialog()
-
-    pick = C.one_choice()
-    app._typing_on_frame = True  # app._on_key leaves Esc / Ctrl+F alone: they go to the Frame
-    app.page.show_dialog(ft.AlertDialog(
-        modal=True, bgcolor=T.SURFACE_2, shape=ft.RoundedRectangleBorder(radius=T.RADIUS),
-        title=ft.Row([ft.Icon(ft.Icons.KEYBOARD_ROUNDED, color=T.ACCENT),
-                      ft.Text(tr("Type on Frame"), weight=ft.FontWeight.W_600)], spacing=T.S2),
-        content=ft.Column([
-            C.body(tr("This computer's keyboard works as a keyboard on your Frame while this window is open. In the "
-                      "headset, select a text field (in a game or app, in Steam or on the desktop), then type here."),
-                   T.TEXT_2),
-            listener,
-            ft.Row([paste, C.secondary(tr("Type it"), ft.Icons.SEND_ROUNDED, send_text)], spacing=T.S2),
-            status,
-        ], tight=True, spacing=T.S3, width=T.px(560)),
-        on_dismiss=pick(lambda e: close()),
-        actions=[C.primary(tr("Done"), ft.Icons.CHECK_ROUNDED, on_click=pick(close))]))
-
-    def connect():
-        from ...frame.keyboard import KeyboardSession
-
-        try:
-            state["session"] = KeyboardSession(target.frame)
-        except Exception as exc:  # noqa: BLE001
-            fail(exc)
-            return
-        if state["closed"]:  # closed while connecting
-            state["session"].close()
-            return
-        status.value = tr("Keyboard connected to {label}.").format(label=target.label)
-        status.color = T.OK
-        C.update(status)
-        focus_keys()
-    app.run_bg(connect)

src/frameport/urlhandler.py

@@ -0,0 +1,419 @@
+"""Makes FramePort the system's handler of `framedrop://` and `frameport://` links (no Flet; see deeplink.py).
+
+The handler is never FramePort's own executable: a `flet build` bundle treats any command-line argument as a
+developer page URL (the Flutter host would try to connect to "framedrop://…"). The registered command runs a small
+script instead (PowerShell on Windows, sh on Linux and WSL) that drops the link into `<data>/links/` and starts
+FramePort unless it is already running (its heartbeat file is fresh). The running app takes links from that folder
+(`take_links`), so a click while FramePort is open reaches the open window.
+
+Settings `links.framedrop` / `links.frameport` (default on, Settings → Install links; skipped with FRAMEPORT_HOME
+or FRAMEPORT_NO_LINK_HANDLER). A scheme that already belongs to another program (FrameDrop) is only taken over when
+the user says so (`register(force=True)`); turning the setting off removes FramePort's registration only where
+FramePort is the handler.
+"""
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from .core import applog, winhost
+from .core.paths import user_data_dir, write_atomic
+from .deeplink import SCHEMES
+
+HEARTBEAT_EVERY = 2.0  # seconds between the app's heartbeat touches
+TAKEN_WAIT = 4  # seconds a handler script waits for a running FramePort to take the link before starting one
+FRESH = 10.0  # a heartbeat younger than this = FramePort runs
+STARTING = 30  # seconds the handler script waits for an app it started before starting another
+MAX_LINK_AGE = 600  # links older than this (FramePort never came up) are dropped unopened
+MARK = "frameport-link-handler"  # in every command FramePort registers (how it recognises its own)
+DESKTOP_FILE = "frameport-links.desktop"
+
+
+def links_dir() -> Path:
+    return user_data_dir() / "links"
+
+
+def heartbeat_file() -> Path:
+    return user_data_dir() / "gui.alive"
+
+
+def starting_file() -> Path:
+    return user_data_dir() / "gui.starting"
+
+
+def script_path(kind: str) -> Path:
+    return user_data_dir() / ("frameport-link-handler.ps1" if kind == "ps1" else "frameport-link-handler.sh")
+
+
+# ------------------------------------------------------------------------------------------- running app side
+def heartbeat() -> None:
+    """Called by the running GUI every HEARTBEAT_EVERY seconds."""
+    path = heartbeat_file()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.touch()
+        starting_file().unlink(missing_ok=True)
+    except OSError:
+        pass
+
+
+def stop_heartbeat() -> None:
+    heartbeat_file().unlink(missing_ok=True)
+
+
+def app_running(now: float | None = None) -> bool:
+    try:
+        return (now or time.time()) - heartbeat_file().stat().st_mtime < FRESH
+    except OSError:
+        return False
+
+
+def drop_link(uri: str) -> Path:
+    """Queue a link for the GUI (what the handler scripts do; also `frameport-gui <link>` and tests)."""
+    folder = links_dir()
+    folder.mkdir(parents=True, exist_ok=True)
+    name = f"{time.time_ns()}-{os.getpid()}.link"
+    write_atomic(folder / name, uri.strip())
+    return folder / name
+
+
+def take_links(now: float | None = None) -> list[str]:
+    """Links waiting in the inbox, oldest first; each is removed (stale ones unopened)."""
+    folder = links_dir()
+    if not folder.is_dir():
+        return []
+    now = now or time.time()
+    out = []
+    for f in sorted(folder.glob("*.link")):
+        try:
+            text = f.read_text(encoding="utf-8", errors="replace").strip()
+            age = now - f.stat().st_mtime
+            f.unlink()
+        except OSError:
+            continue
+        if text and age < MAX_LINK_AGE:
+            out.append(text[:8192])
+    return out
+
+
+# ------------------------------------------------------------------------------------------- start command
+def start_command() -> list[str]:
+    """How to start this FramePort's GUI without arguments (bundle executable, else this Python)."""
+    from . import updates
+
+    root = updates.bundle_root()
+    if root:
+        if sys.platform == "darwin":
+            return ["open", str(root)]
+        return [str(updates.running_executable())]
+    exe = Path(sys.executable)
+    if sys.platform == "win32" and exe.name.lower() == "python.exe" and (exe.parent / "pythonw.exe").exists():
+        exe = exe.parent / "pythonw.exe"  # no console window
+    return [str(exe), "-m", "frameport.ui.app"]
+
+
+def _ps_quote(s: str) -> str:
+    return "'" + s.replace("'", "''") + "'"
+
+
+def ps1_script(data: Path, cmd: list[str]) -> str:
+    links, alive, starting = data / "links", data / "gui.alive", data / "gui.starting"
+    args = ", ".join(_ps_quote(a) for a in cmd[1:]) or ""
+    start = (f"Start-Process -FilePath {_ps_quote(cmd[0])}" + (f" -ArgumentList @({args})" if args else ""))
+    return f"""# {MARK}: written by FramePort. Queues a framedrop:// or frameport:// link, starts FramePort if needed.
+param([string]$Link)
+$ErrorActionPreference = 'SilentlyContinue'
+if (-not $Link) {{ exit 0 }}
+$links = {_ps_quote(str(links))}
+New-Item -ItemType Directory -Force -Path $links | Out-Null
+$name = [string][DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds() + '-' + $PID
+[IO.File]::WriteAllText((Join-Path $links ($name + '.tmp')), $Link)
+$queued = Join-Path $links ($name + '.link')
+Move-Item -Force (Join-Path $links ($name + '.tmp')) $queued
+function Age($p) {{ if (Test-Path $p) {{ ((Get-Date) - (Get-Item $p).LastWriteTime).TotalSeconds }} else {{ 1e9 }} }}
+# a fresh heartbeat may be a window that was just closed: only trust it once that window took the link
+if ((Age {_ps_quote(str(alive))}) -lt {int(FRESH)}) {{
+    for ($i = 0; $i -lt {TAKEN_WAIT * 4}; $i++) {{
+        if (-not (Test-Path $queued)) {{ exit 0 }}
+        Start-Sleep -Milliseconds 250
+    }}
+}}
+if ((Age {_ps_quote(str(starting))}) -lt {STARTING}) {{ exit 0 }}
+Set-Content -Path {_ps_quote(str(starting))} -Value $PID
+{start}
+"""
+
+
+def sh_script(data: Path, cmd: list[str]) -> str:
+    q = shlex.quote
+    links, alive, starting = data / "links", data / "gui.alive", data / "gui.starting"
+    return f"""#!/bin/sh
+# {MARK}: written by FramePort. Queues a framedrop:// or frameport:// link and starts FramePort if needed.
+[ -n "$1" ] || exit 0
+mkdir -p {q(str(links))}
+name="$(date +%s%N 2>/dev/null || date +%s)-$$"
+queued={q(str(links))}/"$name.link"
+printf '%s' "$1" > {q(str(links))}/"$name.tmp" && mv -f {q(str(links))}/"$name.tmp" "$queued"
+age() {{ [ -e "$1" ] && echo $(( $(date +%s) - $(stat -c %Y "$1") )) || echo 1000000000; }}
+# a fresh heartbeat may be a window that was just closed: only trust it once that window took the link
+if [ "$(age {q(str(alive))})" -lt {int(FRESH)} ]; then
+    i=0
+    while [ $i -lt {TAKEN_WAIT * 4} ]; do [ -e "$queued" ] || exit 0; sleep 0.25; i=$((i + 1)); done
+fi
+[ "$(age {q(str(starting))})" -lt {STARTING} ] && exit 0
+echo $$ > {q(str(starting))}
+nohup setsid {" ".join(q(a) for a in cmd)} >/dev/null 2>&1 &
+exit 0
+"""
+
+
+# ------------------------------------------------------------------------------------------- registration
+def platform_kind() -> str | None:
+    """windows | wsl (Windows browser → wsl.exe → this Linux) | linux | None (macOS: Flet can't receive links)."""
+    if sys.platform == "win32":
+        return "windows"
+    if winhost.is_wsl():
+        return "wsl"
+    if sys.platform.startswith("linux"):
+        return "linux"
+    return None
+
+
+def handler_command(kind: str) -> str:
+    """The open command written to the registry / .desktop file (%1 / %u = the link)."""
+    if kind == "windows":
+        system32 = Path(os.environ.get("SystemRoot", r"C:\Windows")) / "System32"
+        ps = system32 / "WindowsPowerShell/v1.0/powershell.exe"
+        # conhost --headless: no console window at all (-WindowStyle Hidden alone still flashes one for a moment)
+        host = f'"{system32 / "conhost.exe"}" --headless ' if (system32 / "conhost.exe").exists() else ""
+        return (f'{host}"{ps}" -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File '
+                f'"{script_path("ps1")}" "%1"')
+    if kind == "wsl":
+        distro = os.environ.get("WSL_DISTRO_NAME", "")
+        wsl = r"C:\Windows\System32\wsl.exe"
+        return f'"{wsl}" ' + (f'-d "{distro}" ' if distro else "") + f'-e sh "{script_path("sh")}" "%1"'
+    return f"sh {shlex.quote(str(script_path('sh')))} %u"
+
+
+def _write_script(kind: str) -> None:
+    data = user_data_dir()
+    data.mkdir(parents=True, exist_ok=True)
+    if kind == "windows":
+        write_atomic(script_path("ps1"), ps1_script(data, start_command()))
+    else:
+        path = script_path("sh")
+        write_atomic(path, sh_script(data, start_command()))
+        path.chmod(0o755)
+
+
+# Windows registry (native winreg, or reg.exe from WSL)
+def _reg_key(scheme: str) -> str:
+    return rf"HKCU\Software\Classes\{scheme}"
+
+
+def windows_handler(scheme: str) -> str | None:
+    """The command Windows runs for scheme:// links (None = no handler for this user or machine)."""
+    for root in ("HKCU", "HKLM"):
+        cmd = winhost.reg_query(rf"{root}\Software\Classes\{scheme}\shell\open\command", "")
+        if cmd:
+            return cmd
+    return None
+
+
+def _reg_set(scheme: str, command: str) -> None:
+    key = _reg_key(scheme)
+    if sys.platform == "win32":
+        import winreg
+
+        sub = key.partition("\\")[2]
+        with winreg.CreateKey(winreg.HKEY_CURRENT_USER, sub) as k:
+            winreg.SetValueEx(k, "", 0, winreg.REG_SZ, f"URL:{scheme} (FramePort)")
+            winreg.SetValueEx(k, "URL Protocol", 0, winreg.REG_SZ, "")
+        with winreg.CreateKey(winreg.HKEY_CURRENT_USER, sub + r"\shell\open\command") as k:
+            winreg.SetValueEx(k, "", 0, winreg.REG_SZ, command)
+        return
+    reg = winhost.system32("reg.exe")
+    for args in (["add", key, "/ve", "/d", f"URL:{scheme} (FramePort)", "/f"],
+                 ["add", key, "/v", "URL Protocol", "/d", "", "/f"],
+                 ["add", key + r"\shell\open\command", "/ve", "/d", command, "/f"]):
+        r = winhost.run_win([reg, *args])
+        if r.returncode:
+            raise OSError(f"reg.exe {' '.join(args[:2])} failed: {(r.stderr or r.stdout).strip()}")
+
+
+def _reg_delete(scheme: str) -> None:
+    key = _reg_key(scheme)
+    if sys.platform == "win32":
+        import winreg
+
+        sub = key.partition("\\")[2]
+        for part in (r"\shell\open\command", r"\shell\open", r"\shell", ""):
+            try:
+                winreg.DeleteKey(winreg.HKEY_CURRENT_USER, sub + part)
+            except OSError:
+                pass
+        return
+    winhost.run_win([winhost.system32("reg.exe"), "delete", key, "/f"])
+
+
+# Linux desktop (xdg)
+def _desktop_path() -> Path:
+    base = Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local/share")
+    return base / "applications" / DESKTOP_FILE
+
+
+def desktop_entry(command: str, schemes=SCHEMES) -> str:
+    mimes = "".join(f"x-scheme-handler/{s};" for s in schemes)
+    return ("[Desktop Entry]\nType=Application\nName=FramePort (install links)\n"
+            f"Comment={MARK}\nExec={command}\nNoDisplay=true\nTerminal=false\nMimeType={mimes}\n")
+
+
+def _desktop_schemes() -> list[str]:
+    """The schemes FramePort's .desktop file lists now."""
+    try:
+        text = _desktop_path().read_text(encoding="utf-8")
+    except OSError:
+        return []
+    return [s for s in SCHEMES if f"x-scheme-handler/{s};" in text]
+
+
+def linux_handler(scheme: str) -> str | None:
+    """The .desktop file that opens scheme:// links (None = none, or xdg-mime isn't installed)."""
+    if not shutil.which("xdg-mime"):
+        return None
+    try:
+        r = subprocess.run(["xdg-mime", "query", "default", f"x-scheme-handler/{scheme}"], capture_output=True,
+                           text=True, timeout=10)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return r.stdout.strip() or None
+
+
+# public API
+def current_handler(scheme: str) -> str | None:
+    kind = platform_kind()
+    if kind in ("windows", "wsl"):
+        return windows_handler(scheme)
+    if kind == "linux":
+        return linux_handler(scheme)
+    return None
+
+
+def is_ours(handler: str | None) -> bool:
+    return bool(handler) and (MARK in handler or handler == DESKTOP_FILE)
+
+
+def status() -> dict:
+    """{scheme: "ours" | "other" | "none"}, "<scheme>_by" (the other program, e.g. FrameDrop) and "supported" (False
+    on macOS)."""
+    out: dict = {"supported": platform_kind() is not None}
+    if not out["supported"]:
+        return out
+    for s in SCHEMES:
+        h = current_handler(s)
+        out[s] = "ours" if is_ours(h) else ("other" if h else "none")
+        if h and not is_ours(h):
+            out[f"{s}_by"] = _program_name(h)
+    return out
+
+
+def _program_name(handler: str) -> str:
+    """"FrameDrop" for FrameDrop's handler, else the program's file name (a .desktop file's name on Linux)."""
+    if "framedrop" in handler.lower() and "frameport" not in handler.lower():
+        return "FrameDrop"
+    first = handler.split('"')[1] if handler.startswith('"') and handler.count('"') >= 2 else handler.split()[0]
+    return Path(first.replace("\\", "/")).stem or first
+
+
+def enabled(scheme: str) -> bool:
+    """Settings → Install links: one switch per scheme (`links.framedrop`, `links.frameport`; default on)."""
+    from .core import library
+
+    return bool(library.setting(f"links.{scheme}", True))
+
+
+def set_enabled(scheme: str, on: bool) -> dict:
+    """Turn one scheme on or off and apply it now. Returns status()."""
+    from .core import library
+
+    library.set_setting(f"links.{scheme}", bool(on))
+    return register([scheme]) if on else unregister([scheme])
+
+
+def register(schemes=None, force: bool = False) -> dict:
+    """Register FramePort for these schemes (default: the enabled ones). Without `force`, a scheme another program
+    handles is left alone. Returns status() afterwards."""
+    kind = platform_kind()
+    if not kind:
+        return status()
+    schemes = [s for s in (schemes if schemes is not None else [s for s in SCHEMES if enabled(s)]) if s in SCHEMES]
+    if not schemes:
+        return status()
+    _write_script(kind)
+    command = handler_command(kind)
+    if kind in ("windows", "wsl"):
+        for s in schemes:
+            h = windows_handler(s)
+            if force or not h or is_ours(h):
+                if h != command:
+                    _reg_set(s, command)
+    else:
+        path = _desktop_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        listed = sorted(set(_desktop_schemes()) | set(schemes), key=SCHEMES.index)
+        write_atomic(path, desktop_entry(command, listed))
+        if shutil.which("xdg-mime"):
+            for s in schemes:
+                h = linux_handler(s)
+                if force or not h or is_ours(h):
+                    subprocess.run(["xdg-mime", "default", DESKTOP_FILE, f"x-scheme-handler/{s}"],
+                                   capture_output=True, timeout=10)
+        _update_desktop_db()
+    applog.log.info("link handler registered for %s (%s, force=%s)", ", ".join(schemes), kind, force)
+    return status()
+
+
+def _update_desktop_db() -> None:
+    if shutil.which("update-desktop-database"):
+        subprocess.run(["update-desktop-database", str(_desktop_path().parent)], capture_output=True, timeout=20)
+
+
+def unregister(schemes=None) -> dict:
+    """Remove FramePort's registration for these schemes (default: both) where FramePort is the handler (another
+    program's stays)."""
+    kind = platform_kind()
+    schemes = [s for s in (schemes if schemes is not None else SCHEMES) if s in SCHEMES]
+    if kind in ("windows", "wsl"):
+        for s in schemes:
+            if is_ours(windows_handler(s)):
+                _reg_delete(s)
+    elif kind == "linux":
+        keep = [s for s in _desktop_schemes() if s not in schemes]
+        if keep:
+            write_atomic(_desktop_path(), desktop_entry(handler_command(kind), keep))
+        else:
+            _desktop_path().unlink(missing_ok=True)
+        _update_desktop_db()
+    applog.log.info("link handler removed for %s (%s)", ", ".join(schemes), kind)
+    return status()
+
+
+def apply_setting() -> dict | None:
+    """At GUI start: register the enabled schemes (never taking one from another program) and remove FramePort's
+    registration of the disabled ones. Errors are logged, never raised (links are a convenience)."""
+    # an isolated data dir (FRAMEPORT_HOME: tests, screenshots) never takes over the user's link handler
+    if os.environ.get("FRAMEPORT_NO_LINK_HANDLER") or os.environ.get("FRAMEPORT_HOME") or not platform_kind():
+        return None
+    try:
+        off = [s for s in SCHEMES if not enabled(s)]
+        if off:
+            unregister(off)
+        return register()
+    except Exception as exc:  # noqa: BLE001
+        applog.log.warning("link handler: %s", exc)
+        return None

src/frameport/validate/triage.py

@@ -119,6 +119,21 @@ def triage(log: str, state: str = "UNKNOWN", package: str | None = None, crash:
     return res
 
 
+MISSING_OBB = ("The game keeps its content in a data file (.obb) and none was installed: FramePort found no .obb "
+               "files next to its APK. Unreal games then stop right after start without an error (GitHub #85). Put "
+               "the .obb files in a folder named like the package (or obb/) next to the APK, add the folder again "
+               "and reinstall.")
+
+
+def add_missing_obb(res: TriageResult) -> TriageResult:
+    """A launch test of a game whose APK expects an OBB that wasn't installed (from the library, not the log: the
+    game logs nothing about it). Only when it sent no frames: an OBB from an earlier install may still be there."""
+    if res.fps is None and not any(f.id == "missing-obb" for f in res.findings):
+        res.findings.insert(0, Finding("missing-obb", "fatal", MISSING_OBB, [],
+                                       "analysis: the APK expects an OBB (Unreal bHasOBBFiles); no data folder"))
+    return res
+
+
 LOGCAT_TIME = re.compile(r"^\d\d-\d\d (\d\d):(\d\d):(\d\d)\.(\d{3})")
 
 

tests/conftest.py

@@ -24,7 +24,7 @@ def isolated_home(tmp_path, monkeypatch):
 
 # ---------------------------------------------------------------------------------------------- AXML builder
 def build_axml(elements, strings_extra=()):
-    """elements: list of ("start", name, [(attr, kind, value)]) / ("end", name). kind: "str" | "bool".
+    """elements: list of ("start", name, [(attr, kind, value)]) / ("end", name). kind: "str" | "bool" | "int" | "ref".
     Produces a UTF-16 string-pool binary XML like aapt does (enough for our editor)."""
     ns = "http://schemas.android.com/apk/res/android"
     pool = []
@@ -61,6 +61,9 @@ def build_axml(elements, strings_extra=()):
             for a, kind, v in e[2]:
                 if kind == "str":
                     attrs += struct.pack("<IIIHBBI", idx(ns), idx(a), idx(v), 8, 0, 0x03, idx(v))
+                elif kind in ("int", "ref"):  # decimal integer / resource reference (@string/…)
+                    attrs += struct.pack("<IIIHBBI", idx(ns), idx(a), 0xFFFFFFFF, 8, 0, 0x10 if kind == "int" else 0x01,
+                                         v)
                 else:
                     attrs += struct.pack("<IIIHBBI", idx(ns), idx(a), 0xFFFFFFFF, 8, 0, 0x12, 0xFFFFFFFF if v else 0)
             ext = struct.pack("<IIHHHHHH", 0xFFFFFFFF, idx(e[1]), 20, 20, len(e[2]), 0, 0, 0)

tests/fixtures/src/fakeruntime.S

@@ -0,0 +1,94 @@
+// Test fixture for patches/upstream.py probes: the two OVRPort runtime functions ovrport/app#73 fixed, as runtime
+// 3.4.3-23204ea has them (default) and as 3.4.3-aa54c3f does (-DFIXED); same instruction sequences as those builds.
+// Build: aarch64-linux-android29-clang -shared -fPIC -nostdlib fakeruntime.S -o ../libfakeruntime_old_arm64.so
+//        aarch64-linux-android29-clang -shared -fPIC -nostdlib -DFIXED fakeruntime.S -o ../libfakeruntime_fixed_arm64.so
+    .text
+    .globl AAudioStream_getFramesPerBurst
+    .type AAudioStream_getFramesPerBurst, %function
+AAudioStream_getFramesPerBurst:
+    ldr w0, [x0]
+    ret
+    .size AAudioStream_getFramesPerBurst, .-AAudioStream_getFramesPerBurst
+
+// libopenxr_loader.so: the dispatcher's XrHapticAmplitudeEnvelopeVibrationFB -> 100 Hz samples (x20 = the struct:
+// +16 duration in ns, +24 amplitudeCount)
+    .globl fake_envelope_samples
+    .type fake_envelope_samples, %function
+fake_envelope_samples:
+    ldr w8, [x20]
+    mov w9, #28105
+    movk w9, #15261, lsl #16      // XR_TYPE_HAPTIC_AMPLITUDE_ENVELOPE_VIBRATION_FB
+    cmp w8, w9
+    b.ne 1f
+    ldr w9, [x20, #24]
+#ifdef FIXED
+    mov x8, #225833675390976
+    ldr d1, [x20, #16]
+    movk x8, #16845, lsl #48      // 1e9
+    ucvtf d0, w9
+    fmov d2, x8
+    scvtf d1, d1
+    mov w8, #1120403456           // 100.0f
+    fmul d0, d0, d2
+    fmov s2, w8
+    fdiv d0, d0, d1
+    ucvtf s1, w9
+    fmul s1, s1, s2
+    fcvt s0, d0
+    fdiv s0, s1, s0
+#else
+    ldr x8, [x20, #16]
+    ucvtf s0, w9
+    scvtf s1, x8
+    mov w8, #1120403456
+    fmov s2, w8
+    fdiv s1, s0, s1
+    fmul s0, s0, s2
+    fdiv s0, s0, s1
+#endif
+    fcvtzu w21, s0
+1:
+    ret
+    .size fake_envelope_samples, .-fake_envelope_samples
+
+// libovrplatformloader.so
+    .globl ovr_Microphone_GetOutputBufferMaxSize
+    .type ovr_Microphone_GetOutputBufferMaxSize, %function
+ovr_Microphone_GetOutputBufferMaxSize:
+#ifdef FIXED
+    stp x29, x30, [sp, #-32]!
+    stp x20, x19, [sp, #16]
+    mov x29, sp
+    cbz x0, 3f
+    ldr x8, [x0, #24]
+    mov w19, #48000
+    cbz x8, 2f
+    mov x20, x0
+    mov x0, x8
+    bl AAudioStream_getFramesPerBurst
+    cmp w0, w19
+    b.hi 2f
+    ldr x0, [x20, #24]
+    bl AAudioStream_getFramesPerBurst
+    sxtw x19, w0
+2:
+    mov x0, x19
+    ldp x20, x19, [sp, #16]
+    ldp x29, x30, [sp], #32
+    ret
+3:
+    mov w19, #48000
+    mov x0, x19
+    ldp x20, x19, [sp, #16]
+    ldp x29, x30, [sp], #32
+    ret
+#else
+    stp x29, x30, [sp, #-16]!
+    mov x29, sp
+    ldr x0, [x0, #0x18]
+    bl AAudioStream_getFramesPerBurst
+    sxtw x0, w0
+    ldp x29, x30, [sp], #16
+    ret
+#endif
+    .size ovr_Microphone_GetOutputBufferMaxSize, .-ovr_Microphone_GetOutputBufferMaxSize

tests/test_agent.py

@@ -1459,3 +1459,37 @@ def test_dashboard_worker_keeps_watching_for_two_minutes(monkeypatch, tmp_path):
 
     sig = inspect.signature(a.dashboard_worker)
     assert sig.parameters["window"].default == 120 and sig.parameters["max_hides"].default == 10
+
+
+def test_linux_x86_apps_run_through_fex(monkeypatch, tmp_path):
+    """x86_64 Linux apps: FEX is found in the compat list like Proton, and the launcher starts the program through
+    the tool's command chain with STEAM_COMPAT_DATA_PATH set; no ldd check (it can't read x86 programs)."""
+    import shutil
+
+    a = load_agent(monkeypatch, tmp_path)
+    apps = fake_steam_tools(a, tmp_path)
+    tools = a.arm64_compat_tools()
+    tools["fex"] = {"appid": 3127680, "display_name": "FEX-Emu", "from_oslist": "linux", "require_tool_appid": 4185400}
+    a.arm64_compat_tools = lambda: tools
+    assert [t["name"] for t in a.linux_x86_tools()] == ["fex"]  # the runtimes aren't translators
+    st = a.cmd_proton_status({"kind": "linux_x86"})
+    assert st["ready"] is None and st["suggested"]["name"] == "fex"
+    assert a.cmd_proton_status({})["ready"]["name"] == "proton_11-arm64"  # Proton unchanged
+    (apps / "common/FEX").mkdir(parents=True)
+    (apps / "common/FEX/toolmanifest.vdf").write_text(
+        '"manifest"\n{\n  "commandline" "/fex-compat-tool %verb%"\n  "require_tool_appid" "4185400"\n}\n')
+    (apps / "appmanifest_3127680.acf").write_text(
+        '"AppState"\n{\n\t"appid"\t\t"3127680"\n\t"name"\t\t"FEX"\n\t"StateFlags"\t\t"4"\n'
+        '\t"installdir"\t\t"FEX"\n}\n')
+    assert a.cmd_proton_status({"kind": "linux_x86"})["ready"]["name"] == "fex"
+    prep = a.cmd_prepare_linux({"package": "linux.thing", "title": "Thing"})
+    shutil.copy("/bin/true", os.path.join(prep["incoming"], "app", "thing"))
+    monkeypatch.setattr(a, "missing_libraries", lambda *x: pytest.fail("ldd on an x86 program"))
+    res = a.cmd_finalize_linux({"package": "linux.thing", "title": "Thing", "exe": "thing", "x86_64": True})
+    assert res["missing_libraries"] == [] and a.deployment("linux.thing")["x86_64"] is True
+    text = open(os.path.join(prep["anchor"], "launch.sh")).read()
+    line = next(x for x in text.splitlines() if "launch.log" in x and "_v2-entry-point" in x)
+    assert line.index("_v2-entry-point") < line.index("fex-compat-tool") < line.index("app/thing")
+    data = os.path.join(prep["base"], "compatdata")
+    assert f"export STEAM_COMPAT_DATA_PATH={data}" in text and f"mkdir -p {data}" in text  # FEX exits without it
+    assert text.index("STEAM_COMPAT_DATA_PATH") < text.index("fex-compat-tool")

tests/test_axml.py

@@ -76,3 +76,63 @@ def test_start_activity_moves_launcher_to_the_vr_activity():
     # only those two attribute values changed: the rest parses as before
     assert axml.Axml(fixed).attr_str(next(e for e in axml.Axml(fixed).elements() if e.name == "manifest"),
                                      "package") == "org.x.game"
+
+
+def _sdk_manifest(min_sdk):
+    from conftest import build_axml
+
+    return build_axml([
+        ("start", "manifest", [("package", "str", "org.x.app")]),
+        ("start", "uses-sdk", [("minSdkVersion", "int", min_sdk), ("targetSdkVersion", "int", 34)]),
+        ("end", "uses-sdk"),
+        ("end", "manifest"),
+    ])
+
+
+def test_min_sdk(quest_manifest):
+    assert axml.min_sdk(_sdk_manifest(34)) == 34
+    assert axml.min_sdk(_sdk_manifest(29)) == 29
+    assert axml.min_sdk(quest_manifest) is None  # no uses-sdk element
+
+
+def _twa_manifest(value_kind, value):
+    from conftest import build_axml
+
+    return build_axml([
+        ("start", "manifest", [("package", "str", "dev.pages.mahjong_vr.twa")]),
+        ("start", "uses-sdk", [("minSdkVersion", "int", 23)]),
+        ("end", "uses-sdk"),
+        ("start", "application", []),
+        ("start", "meta-data", [("name", "str", "asset_statements"), ("resource", "ref", 0x7F0F0001)]),
+        ("end", "meta-data"),
+        ("start", "activity", [("name", "str", "com.google.androidbrowserhelper.trusted.LauncherActivity")]),
+        ("start", "meta-data", [("name", "str", "android.support.customtabs.trusted.DEFAULT_URL"),
+                                ("value", value_kind, value)]),
+        ("end", "meta-data"),
+        ("start", "meta-data", [("name", "str", "com.example.flag"), ("value", "bool", True)]),
+        ("end", "meta-data"),
+        ("end", "activity"),
+        ("end", "application"),
+        ("end", "manifest"),
+    ])
+
+
+def test_meta_data_and_web_wrapper(tmp_path):
+    import zipfile
+
+    from frameport.analysis.detect import analyze, web_wrapper
+
+    m = _twa_manifest("str", "https://mahjong-vr.pages.dev/")
+    meta = axml.meta_data(m)
+    assert meta == {"asset_statements": 0x7F0F0001, "android.support.customtabs.trusted.DEFAULT_URL":
+                    "https://mahjong-vr.pages.dev/", "com.example.flag": True}
+    assert web_wrapper(meta, axml.Axml(m).strings()) == {"url": "https://mahjong-vr.pages.dev/"}
+    # @string/launchUrl (Bubblewrap) without a resource table: still a wrapper, URL unknown
+    ref = _twa_manifest("ref", 0x7F0F0002)
+    assert web_wrapper(axml.meta_data(ref), axml.Axml(ref).strings()) == {"url": None}
+    assert web_wrapper({}, ["com.example.Main"]) is None
+    apk = tmp_path / "twa.apk"
+    with zipfile.ZipFile(apk, "w") as z:
+        z.writestr("AndroidManifest.xml", m)
+    a = analyze(apk)
+    assert a.extra["web_wrapper"] == {"url": "https://mahjong-vr.pages.dev/"} and a.extra["min_sdk"] == 23

tests/test_deeplink.py

@@ -0,0 +1,299 @@
+"""Install links ("Install with FrameDrop" buttons, frameport:// links): parsing, the safety rules, manifests,
+downloads, the handler scripts and their inbox, drop routing, and the VR / flat window choice."""
+import hashlib
+import json
+import os
+import subprocess
+import threading
+import time
+import zipfile
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import quote
+
+import pytest
+
+from frameport import deeplink, urlhandler
+from frameport.deeplink import LinkError
+
+MANIFEST = "https://cdn.example.com/game.framedrop.json"
+
+
+# ------------------------------------------------------------------------------------------------- links
+@pytest.mark.parametrize("link", [
+    f"framedrop://install?manifest={quote(MANIFEST, safe='')}",
+    f"frameport://install?manifest={quote(MANIFEST, safe='')}",
+    f"https://framedropvr.com/install?manifest={quote(MANIFEST, safe='')}",
+    f"https://framedropvr.com/install/?manifest={MANIFEST}",
+    MANIFEST,
+    f'  "framedrop://install?manifest={quote(MANIFEST, safe="")}"  ',
+])
+def test_link_forms_name_the_manifest(link):
+    assert deeplink.parse(link).manifest_url == MANIFEST
+
+
+def test_direct_file_links():
+    url = "https://github.com/x/y/releases/download/v1/Game-arm64.apk"
+    assert deeplink.parse(f"framedrop://install?url={quote(url, safe='')}").file_url == url
+    assert deeplink.parse(url).file_url == url
+    assert deeplink.parse(deeplink.make_link(file_url=url)).file_url == url
+
+
+@pytest.mark.parametrize("url, reason", [
+    ("http://cdn.example.com/x.apk", "https"),
+    ("https://user:pw@cdn.example.com/x.apk", "password"),
+    ("https://192.168.1.20/x.apk", "local network"),
+    ("https://10.0.0.1/x.apk", "local network"),
+    ("https://[fe80::1]/x.apk", "local network"),
+    ("https://cdn.example.com/builds/", "file name"),
+    ("file:///C:/x.apk", "https"),
+    ("ftp://cdn.example.com/x.apk", "https"),
+])
+def test_unsafe_urls_are_refused(url, reason):
+    with pytest.raises(LinkError, match=reason):
+        deeplink.check_url(url)
+    with pytest.raises(LinkError):
+        deeplink.parse(f"framedrop://install?url={quote(url, safe='')}")
+
+
+def test_http_only_on_this_pc():
+    for host in ("localhost", "127.0.0.1", "[::1]"):
+        assert deeplink.check_url(f"http://{host}:8000/x.apk")
+
+
+def test_other_links_are_refused():
+    for bad in ("framedrop://uninstall?url=https%3A%2F%2Fa.com%2Fx.apk", "framedrop://install",
+                "https://example.com/page.html", "nonsense", ""):
+        with pytest.raises(LinkError):
+            deeplink.parse(bad)
+
+
+def test_names_resolving_to_a_lan_are_refused(monkeypatch):
+    monkeypatch.setattr(deeplink.socket, "getaddrinfo", lambda *a, **k: [(0, 0, 0, "", ("192.168.0.5", 443))])
+    with pytest.raises(LinkError, match="resolves"):
+        deeplink.check_url("https://evil.example.com/x.apk", resolve=True)
+
+
+# ------------------------------------------------------------------------------------------------- manifests
+def test_manifest_validation():
+    m = deeplink.manifest_from_data({"schema": "framedrop.install/v1", "name": "  My   Game ", "extra": 1, "files": [
+        {"url": "https://cdn.example.com/My%20Game-arm64.apk", "sha256": "AB" * 32},
+        {"url": "https://cdn.example.com/main.1.com.my.game.obb", "sha256": "optional-but-better"}]})
+    assert m.name == "My Game" and m.main.filename == "My Game-arm64.apk" and m.main.sha256 == "ab" * 32
+    assert m.files[1].kind == deeplink.OBB and m.files[1].sha256 is None  # FrameDrop's placeholder text
+    for bad in ({}, {"schema": "framedrop.install/v2", "name": "x", "files": [{"url": "https://a.com/x.apk"}]},
+                {"schema": "framedrop.install/v1", "files": [{"url": "https://a.com/x.apk"}]},
+                {"schema": "framedrop.install/v1", "name": "x", "files": []},
+                {"schema": "framedrop.install/v1", "name": "x", "files": [{"url": "https://a.com/readme.txt"}]},
+                {"schema": "framedrop.install/v1", "name": "x", "files": [{"url": "http://a.com/x.apk"}]}):
+        with pytest.raises(LinkError):
+            deeplink.manifest_from_data(bad)
+
+
+def test_direct_link_manifest_and_titles():
+    m = deeplink.fetch_manifest(deeplink.InstallRequest(file_url="https://a.com/dl/Cool_Game-1.2-arm64-v8a.apk"))
+    assert m.direct and m.main.kind == deeplink.APK and m.name == "Cool Game"
+    assert deeplink.classify("thing-linux-arm64.tar.gz") == deeplink.LINUX
+    assert deeplink.classify("Tool.AppImage") == deeplink.LINUX and deeplink.classify("Setup.EXE") == deeplink.EXE
+
+
+def test_local_manifest_file(tmp_path):
+    f = tmp_path / "game.framedrop.json"
+    f.write_text(json.dumps({"schema": "framedrop.install/v1", "name": "Local",
+                             "files": [{"url": "https://a.com/x.zip"}]}))
+    req = deeplink.parse(str(f))
+    assert req.local_manifest == str(f) and deeplink.fetch_manifest(req).main.kind == deeplink.LINUX
+
+
+@pytest.fixture
+def server(tmp_path):
+    """A web server on 127.0.0.1 (http is allowed there) serving tmp_path/www."""
+    www = tmp_path / "www"
+    www.mkdir()
+    httpd = ThreadingHTTPServer(("127.0.0.1", 0), partial(SimpleHTTPRequestHandler, directory=str(www)))
+    httpd.RequestHandlerClass.log_message = lambda *a: None
+    threading.Thread(target=httpd.serve_forever, daemon=True).start()
+    yield www, f"http://127.0.0.1:{httpd.server_address[1]}"
+    httpd.shutdown()
+
+
+def test_fetch_and_download_a_manifest(server):
+    www, base = server
+    apk, obb = b"PK\x03\x04 fake apk" * 1000, b"obb data" * 500
+    (www / "Game-arm64.apk").write_bytes(apk)
+    (www / "main.1.com.x.game.obb").write_bytes(obb)
+    (www / "game.framedrop.json").write_text(json.dumps({"schema": "framedrop.install/v1", "name": "Game", "files": [
+        {"url": f"{base}/Game-arm64.apk", "sha256": hashlib.sha256(apk).hexdigest()},
+        {"url": f"{base}/main.1.com.x.game.obb"}]}))
+    m = deeplink.fetch_manifest(deeplink.parse(f"framedrop://install?manifest={quote(base + '/game.framedrop.json')}"))
+    assert m.name == "Game" and m.host == "127.0.0.1" and not m.direct
+    path = deeplink.download(m)
+    assert path.name == "Game-arm64.apk" and path.read_bytes() == apk
+    assert (path.parent / "obb" / "main.1.com.x.game.obb").read_bytes() == obb  # where the APK scan finds OBBs
+
+
+def test_checksum_mismatch_leaves_nothing(server):
+    www, base = server
+    (www / "x.apk").write_bytes(b"real")
+    m = deeplink.manifest_from_data({"schema": "framedrop.install/v1", "name": "X",
+                                     "files": [{"url": f"{base}/x.apk", "sha256": "00" * 32}]}, f"{base}/m.json")
+    with pytest.raises(LinkError, match="checksum"):
+        deeplink.download(m)
+    assert not list(deeplink.staging_dir(m).rglob("*.apk*"))
+
+
+def test_oversized_manifest_is_refused(server):
+    www, base = server
+    (www / "big.json").write_bytes(b" " * (deeplink.MAX_MANIFEST + 10))
+    with pytest.raises(LinkError, match="too large"):
+        deeplink.fetch_manifest(deeplink.InstallRequest(manifest_url=f"{base}/big.json"))
+
+
+def test_add_from_link_names_the_game(tmp_path):
+    """A manifest's name becomes the (locked) title; the link is remembered on the entry."""
+    from frameport import pipeline
+    from frameport.analysis import linux
+
+    head = bytearray(64)
+    head[:4], head[4], head[5] = b"\x7fELF", 2, 1
+    head[18:20] = linux.EM_AARCH64.to_bytes(2, "little")
+    z = tmp_path / "tool-linux-arm64.zip"
+    with zipfile.ZipFile(z, "w") as f:
+        f.writestr("tool/tool", bytes(head))
+    m = deeplink.Manifest("Nice Tool", [deeplink.ManifestFile("https://a.com/tool-linux-arm64.zip")],
+                          "https://a.com/tool.framedrop.json")
+    g = pipeline.add_from_link(m, z)
+    assert g["title"] == "Nice Tool" and g["title_locked"] and g["link"]["source"] == m.source
+
+
+# ------------------------------------------------------------------------------------------------- handler
+def test_inbox_and_heartbeat():
+    assert not urlhandler.app_running()
+    urlhandler.heartbeat()
+    assert urlhandler.app_running() and not urlhandler.app_running(time.time() + urlhandler.FRESH + 1)
+    urlhandler.drop_link("framedrop://install?url=a")
+    old = urlhandler.drop_link("frameport://old")
+    os.utime(old, (time.time() - urlhandler.MAX_LINK_AGE - 5,) * 2)
+    assert urlhandler.take_links() == ["framedrop://install?url=a"]  # the stale one is dropped unopened
+    assert urlhandler.take_links() == []
+
+
+@pytest.mark.skipif(not os.path.exists("/bin/sh") or os.name == "nt", reason="needs sh")
+def test_sh_handler_queues_and_starts_once(tmp_path):
+    from frameport.core.paths import user_data_dir
+
+    data = user_data_dir()
+    data.mkdir(parents=True, exist_ok=True)
+    marker = tmp_path / "started"
+    script = tmp_path / "h.sh"
+    script.write_text(urlhandler.sh_script(data, ["sh", "-c", f"echo x >> '{marker}'"]))
+    link = "framedrop://install?manifest=https%3A%2F%2Fa.com%2Fm.json&x='$(touch /tmp/pwned)'"
+    subprocess.run(["sh", str(script), link], check=True, timeout=20)
+    assert urlhandler.take_links() == [link]  # stored as text, never run
+    for _ in range(50):
+        if marker.exists():
+            break
+        time.sleep(0.1)
+    assert marker.exists()
+    subprocess.run(["sh", str(script), "frameport://second"], check=True, timeout=20)
+    time.sleep(1)
+    assert marker.read_text().count("x") == 1  # "starting" marker: not started twice
+    urlhandler.heartbeat()  # running app: just queue
+    subprocess.run(["sh", str(script), "frameport://third"], check=True, timeout=20)
+    assert urlhandler.take_links() == ["frameport://second", "frameport://third"]
+
+
+def test_ps1_script_and_commands(monkeypatch):
+    from frameport.core.paths import user_data_dir
+
+    text = urlhandler.ps1_script(user_data_dir(), [r"C:\Apps\FramePort\FramePort.exe"])
+    assert urlhandler.MARK in text and "Start-Process -FilePath 'C:\\Apps\\FramePort\\FramePort.exe'" in text
+    assert "param([string]$Link)" in text and "-ArgumentList" not in text
+    assert '"%1"' in urlhandler.handler_command("windows") and urlhandler.is_ours(urlhandler.handler_command("windows"))
+    monkeypatch.setenv("WSL_DISTRO_NAME", "Ubuntu")
+    assert '-d "Ubuntu" -e sh' in urlhandler.handler_command("wsl")
+    entry = urlhandler.desktop_entry("sh x %u", ["framedrop"])
+    assert "x-scheme-handler/framedrop;" in entry and "frameport;" not in entry
+
+
+def test_windows_registration_per_scheme(monkeypatch):
+    """Each scheme on its own; a scheme FrameDrop owns is only taken with force; off removes only FramePort's."""
+    reg = {"framedrop": '"C:\\Program Files\\FrameDrop\\FrameDrop.exe" "%1"'}
+    monkeypatch.setattr(urlhandler, "platform_kind", lambda: "windows")
+    monkeypatch.setattr(urlhandler, "windows_handler", lambda s: reg.get(s))
+    monkeypatch.setattr(urlhandler, "_reg_set", lambda s, cmd: reg.__setitem__(s, cmd))
+    monkeypatch.setattr(urlhandler, "_reg_delete", lambda s: reg.pop(s, None))
+    st = urlhandler.register()
+    assert st["framedrop"] == "other" and st["framedrop_by"] == "FrameDrop" and st["frameport"] == "ours"
+    assert urlhandler.register(["framedrop"], force=True)["framedrop"] == "ours"
+    st = urlhandler.set_enabled("framedrop", False)
+    assert st["framedrop"] == "none" and st["frameport"] == "ours" and not urlhandler.enabled("framedrop")
+    reg["framedrop"] = '"C:\\FrameDrop.exe" "%1"'
+    assert urlhandler.unregister()["framedrop"] == "other"  # another program's registration stays
+
+
+def test_isolated_homes_never_register(monkeypatch):
+    called = []
+    monkeypatch.setattr(urlhandler, "register", lambda *a, **k: called.append(1))
+    assert urlhandler.apply_setting() is None and not called  # FRAMEPORT_HOME is set by the tests
+
+
+# ------------------------------------------------------------------------------------------------- drops, display
+def test_drop_routing(tmp_path):
+    from frameport.analysis import linux
+    from frameport.ui import dropped
+
+    head = bytearray(64)
+    head[:4], head[4], head[5] = b"\x7fELF", 2, 1
+    head[18:20] = linux.EM_AARCH64.to_bytes(2, "little")
+    (tmp_path / "apks").mkdir()
+    (tmp_path / "apks" / "a.apk").write_bytes(b"PK")
+    (tmp_path / "linuxapp" / "bin").mkdir(parents=True)
+    (tmp_path / "linuxapp" / "bin" / "app").write_bytes(bytes(head))
+    (tmp_path / "prog").write_bytes(bytes(head))
+    for name in ("x.apk", "Setup.exe", "m.framedrop.json", "notes.txt", "a.zip"):
+        (tmp_path / name).write_bytes(b"PK" if name.endswith(".zip") else b"x")
+    got = dict((os.path.basename(p), k) for k, p in dropped.route(
+        [str(tmp_path / n) for n in ("apks", "linuxapp", "prog", "x.apk", "Setup.exe", "m.framedrop.json",
+                                     "notes.txt", "a.zip")]))
+    assert got == {"apks": "folder", "linuxapp": "linux", "prog": "linux", "x.apk": "apk", "Setup.exe": "exe",
+                   "m.framedrop.json": "manifest", "notes.txt": "unknown", "a.zip": "linux"}
+
+
+def test_display_mode_choice():
+    from frameport.core.models import Recipe
+    from frameport.install.installer import install_context, show_window
+
+    def ctx(mode=None, text_window=False):
+        patches = {"device.display_mode": {"mode": mode}} if mode is not None else {}
+        if text_window:
+            patches["device.text_input_window"] = {}
+        return install_context(Recipe(package="com.x", patches=patches))
+    assert show_window(ctx(), automatic=True) and not show_window(ctx(), automatic=False)
+    assert show_window(ctx("flat"), automatic=False)  # a 2D app FramePort took for VR
+    assert not show_window(ctx("vr"), automatic=True)  # a VR app FramePort took for 2D
+    assert show_window(ctx("vr", text_window=True), automatic=True)  # typing still needs the window
+
+
+def test_cli_open_link_downloads_and_adds(server):
+    """`frameport open-link <link> --yes --no-install`: the same flow as the GUI, without the Frame."""
+    from typer.testing import CliRunner
+
+    from frameport.analysis import linux
+    from frameport.cli import app
+    from frameport.core import library
+
+    www, base = server
+    head = bytearray(64)
+    head[:4], head[4], head[5] = b"\x7fELF", 2, 1
+    head[18:20] = linux.EM_AARCH64.to_bytes(2, "little")
+    with zipfile.ZipFile(www / "viewer-linux-arm64.zip", "w") as z:
+        z.writestr("viewer/viewer", bytes(head))
+    (www / "v.framedrop.json").write_text(json.dumps({"schema": "framedrop.install/v1", "name": "Viewer",
+                                                      "files": [{"url": f"{base}/viewer-linux-arm64.zip"}]}))
+    link = deeplink.make_link(manifest_url=f"{base}/v.framedrop.json", scheme="framedrop")
+    r = CliRunner().invoke(app, ["open-link", link, "--yes", "--no-install"])
+    assert r.exit_code == 0, r.output
+    assert "added linux." in r.output and any(g.get("title") == "Viewer" for g in library.games())
+    r = CliRunner().invoke(app, ["open-link", "framedrop://install?url=http%3A%2F%2Fevil.com%2Fx.apk", "--yes"])
+    assert r.exit_code != 0 and "https" in r.output

tests/test_drives.py

@@ -0,0 +1,416 @@
+"""Agent: games on another drive (microSD, GitHub #90) and Desktop Mode entries for Linux apps (GitHub #84)."""
+import importlib.util
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+AGENT = Path(__file__).resolve().parents[1] / "agent" / "frameport_agent.py"
+
+
+def load(monkeypatch, tmp_path, extra_mounts=()):
+    """The agent with HOME = <tmp>/home, removable drives under <tmp>/media and a fake /proc/mounts."""
+    home = tmp_path / "home"
+    home.mkdir(exist_ok=True)
+    monkeypatch.setenv("HOME", str(home))
+    spec = importlib.util.spec_from_file_location("frameport_agent", AGENT)
+    a = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(a)
+    media = tmp_path / "media"
+    (media / "steamos" / "SD Card").mkdir(parents=True, exist_ok=True)
+    (media / "steamos" / "STICK").mkdir(parents=True, exist_ok=True)
+    (media / "steamos" / "RO").mkdir(parents=True, exist_ok=True)
+    sd = str(media / "steamos" / "SD Card").replace(" ", "\\040")
+    table = tmp_path / "mounts"
+    table.write_text("/dev/nvme0n1p8 / btrfs rw,relatime 0 0\n"
+                     f"/dev/mmcblk0p1 {sd} ext4 rw,nosuid,nodev,relatime 0 0\n"
+                     f"/dev/sda1 {media}/steamos/STICK exfat rw,nosuid,nodev 0 0\n"
+                     f"/dev/sdb1 {media}/steamos/RO ext4 ro,nosuid 0 0\n"
+                     "proc /proc proc rw 0 0\n" + "".join(extra_mounts))
+    monkeypatch.setattr(a, "PROC_MOUNTS", str(table))
+    monkeypatch.setattr(a, "MEDIA_ROOT", str(media))
+    monkeypatch.setattr(a, "container_running", lambda appid: False)
+    monkeypatch.setattr(a, "pcvr_pids", lambda base: [])
+    monkeypatch.setattr(a, "as_owner", lambda: [])
+    return a
+
+
+def sd_dir(tmp_path):
+    return tmp_path / "media" / "steamos" / "SD Card"
+
+
+def quest_install(a, pkg="com.x.y", dest=None):
+    """A Quest game as finalize leaves it (no Lepton needed: written by hand like the agent would)."""
+    prep = a.cmd_prepare({"package": pkg, "title": "Game", "dest": dest})
+    base = Path(prep["base"])
+    (base / "lepton-app" / "obb").mkdir(parents=True)
+    (base / "lepton-app" / "game.apk").write_bytes(b"apk" * 100)
+    (base / "lepton-app" / "obb" / "main.obb").write_bytes(b"o" * 5000)
+    saves = base / "lepton-data" / "external" / "Android" / "data" / pkg / "files"
+    saves.mkdir(parents=True)
+    (saves / "save.dat").write_text("progress")
+    shutil.rmtree(base / "incoming")
+    anchor = Path(prep["anchor"])
+    anchor.mkdir(parents=True, exist_ok=True)
+    (anchor / "artwork").mkdir(exist_ok=True)
+    (anchor / "artwork" / "icon.png").write_bytes(b"png")
+    a.write_launcher(str(anchor), str(base), pkg, "Game", prep["appid"], "/lepton/lepton", {"X": "1"})
+    (anchor / "deployment.json").write_text(json.dumps({"package": pkg, "appid": int(prep["appid"]),
+                                                        "base": str(base), "title": "Game"}))
+    return prep
+
+
+def test_drives_lists_internal_and_removable_drives(monkeypatch, tmp_path):
+    a = load(monkeypatch, tmp_path)
+    drives = {d["label"]: d for d in a.cmd_drives({})["drives"]}
+    assert set(drives) == {"Internal storage", "SD Card", "STICK", "RO"}
+    internal = drives["Internal storage"]
+    assert internal["internal"] and internal["install_dir"] == a.ANCHORS and internal["usable"]
+    assert internal["fstype"] == "btrfs" and internal["free_bytes"] > 0
+    sd = drives["SD Card"]
+    assert sd["usable"] and sd["removable"] and sd["fstype"] == "ext4"
+    assert sd["path"] == str(sd_dir(tmp_path)) and sd["install_dir"] == str(sd_dir(tmp_path) / "FramePort")
+    assert not drives["STICK"]["usable"] and "exfat" in drives["STICK"]["reason"]
+    assert not drives["RO"]["usable"] and "read-only" in drives["RO"]["reason"]
+
+
+def test_steam_library_on_another_drive_is_listed(monkeypatch, tmp_path):
+    lib = tmp_path / "games"
+    (lib / "steamapps").mkdir(parents=True)
+    a = load(monkeypatch, tmp_path, [f"/dev/sdc1 {lib} ext4 rw 0 0\n"])
+    steamapps = Path(a.STEAM) / "steamapps"
+    steamapps.mkdir(parents=True)
+    (steamapps / "libraryfolders.vdf").write_text(f'"libraryfolders" {{ "1" {{ "path" "{lib}" }} }}')
+    drives = {d["path"]: d for d in a.list_drives()}
+    assert drives[str(lib)]["steam_library"] and drives[str(lib)]["install_dir"] == str(lib / "FramePort")
+
+
+def test_resolve_dest_never_falls_back_to_internal_storage(monkeypatch, tmp_path):
+    a = load(monkeypatch, tmp_path)
+    for internal in (None, "", "internal", a.ANCHORS):
+        assert a.resolve_dest(internal) == a.ANCHORS
+    assert a.resolve_dest(str(sd_dir(tmp_path))) == str(sd_dir(tmp_path) / "FramePort")  # the mount point
+    assert (sd_dir(tmp_path) / "FramePort").is_dir()
+    with pytest.raises(a.AgentError, match="exfat"):
+        a.resolve_dest(str(tmp_path / "media/steamos/STICK/FramePort"))
+    with pytest.raises(a.AgentError, match="read-only"):
+        a.resolve_dest(str(tmp_path / "media/steamos/RO"))
+    with pytest.raises(a.AgentError, match="isn't inserted"):  # an SD card that was taken out
+        a.resolve_dest(str(tmp_path / "media/steamos/OLDCARD/FramePort"))
+    assert not (tmp_path / "media/steamos/OLDCARD").exists()
+
+
+def test_new_games_go_to_the_chosen_drive_and_keep_their_base(monkeypatch, tmp_path):
+    a = load(monkeypatch, tmp_path)
+    dest = str(sd_dir(tmp_path) / "FramePort")
+    prep = quest_install(a, dest=dest)
+    assert prep["base"] == os.path.join(dest, "com.x.y") and prep["anchor"].startswith(a.ANCHORS)
+    assert prep["free_bytes"] > 0
+    # a reinstall keeps the game where it is, whatever the default is now
+    again = a.cmd_prepare({"package": "com.x.y", "title": "Game", "dest": None})
+    assert again["base"] == prep["base"] and again["installed"]
+    games = a.cmd_list_installed({})["games"]
+    assert games[0]["drive"] == {"internal": False, "path": str(sd_dir(tmp_path)), "label": "SD Card"}
+    assert games[0]["drive_missing"] is False and games[0]["apk_present"]
+    assert {d["label"]: d["games"] for d in a.cmd_drives({})["drives"]}["SD Card"] == 1
+    # Linux apps and PC VR games take dest too
+    p = a.cmd_prepare_linux({"package": "linux.tool", "title": "Tool", "dest": dest})
+    assert p["base"] == os.path.join(dest, "linux.tool")
+
+
+def test_missing_sd_card(monkeypatch, tmp_path):
+    a = load(monkeypatch, tmp_path)
+    prep = quest_install(a, dest=str(sd_dir(tmp_path) / "FramePort"))
+    (tmp_path / "mounts").write_text("/dev/nvme0n1p8 / btrfs rw 0 0\n")  # card taken out
+    game = a.cmd_list_installed({})["games"][0]
+    assert game["drive_missing"] is True and game["drive"]["label"] == "SD Card"
+    with pytest.raises(a.AgentError, match="isn't inserted"):
+        a.cmd_prepare({"package": "com.x.y", "title": "Game"})
+    with pytest.raises(a.AgentError, match="isn't inserted"):
+        a.cmd_launch({"package": "com.x.y"})
+    with pytest.raises(a.AgentError, match="isn't inserted"):
+        a.cmd_move({"package": "com.x.y", "dest": "internal", "detach": False})
+    assert Path(prep["base"]).exists()
+
+
+@pytest.mark.parametrize("same_drive", [True, False])
+def test_move_quest_game_to_sd_and_back(monkeypatch, tmp_path, same_drive):
+    a = load(monkeypatch, tmp_path)
+    monkeypatch.setattr(a, "same_device", lambda x, y: same_drive)
+    prep = quest_install(a)
+    anchor = Path(prep["anchor"])
+    assert prep["base"] == str(anchor)  # internal storage: the files live next to the launcher
+    os.symlink("/nonexistent/elsewhere", anchor / "lepton-app" / "outside-link")
+    dest = str(sd_dir(tmp_path))
+    r = a.cmd_move({"package": "com.x.y", "dest": dest, "detach": False})
+    assert r["state"] == "done", r
+    new = sd_dir(tmp_path) / "FramePort" / "com.x.y"
+    assert (new / "lepton-app" / "obb" / "main.obb").stat().st_size == 5000
+    assert (new / "lepton-data/external/Android/data/com.x.y/files/save.dat").read_text() == "progress"
+    assert os.readlink(new / "lepton-app" / "outside-link") == "/nonexistent/elsewhere"
+    # the anchor keeps its own files only
+    assert sorted(os.listdir(anchor)) == ["artwork", "deployment.json", "launch.sh"]
+    dep = a.deployment("com.x.y")
+    assert dep["base"] == str(new) and dep["moved"]["from"] == str(anchor)
+    text = (anchor / "launch.sh").read_text()
+    assert f"app_dir='{new}'" in text and "export X=1" in text
+    assert subprocess.run(["bash", "-n", str(anchor / "launch.sh")]).returncode == 0
+    assert a.cmd_move_status({})["state"] == "done"
+    with pytest.raises(a.AgentError, match="already there"):
+        a.cmd_move({"package": "com.x.y", "dest": dest, "detach": False})
+    # and back to internal storage: the drive's empty FramePort folder goes
+    r = a.cmd_move({"package": "com.x.y", "dest": "internal", "detach": False})
+    assert r["state"] == "done", r
+    assert (anchor / "lepton-app" / "game.apk").exists() and not (sd_dir(tmp_path) / "FramePort").exists()
+    assert a.deployment("com.x.y")["base"] == str(anchor)
+    assert f"app_dir={anchor}\n" in (anchor / "launch.sh").read_text()
+
+
+def test_move_refusals(monkeypatch, tmp_path):
+    a = load(monkeypatch, tmp_path)
+    quest_install(a)
+    with pytest.raises(a.AgentError, match="exfat"):
+        a.cmd_move({"package": "com.x.y", "dest": str(tmp_path / "media/steamos/STICK"), "detach": False})
+    monkeypatch.setattr(a, "container_running", lambda appid: True)
+    with pytest.raises(a.AgentError, match="running"):
+        a.cmd_move({"package": "com.x.y", "dest": str(sd_dir(tmp_path)), "detach": False})
+    monkeypatch.setattr(a, "container_running", lambda appid: False)
+    monkeypatch.setattr(a, "same_device", lambda x, y: False)
+    monkeypatch.setattr(a, "_space", lambda path: (100 << 20, 1 << 40))  # 100 MiB free < headroom
+    with pytest.raises(a.AgentError, match="not enough space"):
+        a.cmd_move({"package": "com.x.y", "dest": str(sd_dir(tmp_path)), "detach": False})
+    with pytest.raises(a.AgentError, match="not installed"):
+        a.cmd_move({"package": "com.not.there", "dest": "internal", "detach": False})
+    assert a.deployment("com.x.y")["base"] == os.path.join(a.ANCHORS, "com.x.y")
+
+
+def test_failed_copy_leaves_the_game_where_it_was(monkeypatch, tmp_path):
+    a = load(monkeypatch, tmp_path)
+    monkeypatch.setattr(a, "same_device", lambda x, y: False)
+    prep = quest_install(a)
+    real = a.tree_stats
+    monkeypatch.setattr(a, "tree_stats", lambda root, names: (real(root, names)[0], 1) if "SD" in root
+                        else real(root, names))  # the copy comes up short
+    r = a.cmd_move({"package": "com.x.y", "dest": str(sd_dir(tmp_path)), "detach": False})
+    assert r["state"] == "failed" and "doesn't match" in r["error"]
+    assert a.deployment("com.x.y")["base"] == prep["base"]
+    assert (Path(prep["base"]) / "lepton-app" / "game.apk").exists()
+    assert not (sd_dir(tmp_path) / "FramePort" / "com.x.y").exists()
+    assert f"app_dir={prep['base']}\n" in (Path(prep["anchor"]) / "launch.sh").read_text()
+
+
+def test_move_detaches_through_systemd_run(monkeypatch, tmp_path):
+    a = load(monkeypatch, tmp_path)
+    quest_install(a)
+    calls = []
+    monkeypatch.setattr(a, "run", lambda cmd, **kw: calls.append(cmd) or
+                        subprocess.CompletedProcess(cmd, 0, "", "") if cmd[0] == "systemd-run" else
+                        subprocess.run(cmd, capture_output=True, text=True))
+    r = a.cmd_move({"package": "com.x.y", "dest": str(sd_dir(tmp_path))})
+    assert r["started"] and r["to"].endswith("FramePort/com.x.y")
+    cmd = next(c for c in calls if c[0] == "systemd-run")
+    assert "_move_worker" in cmd and json.loads(cmd[-1])["package"] == "com.x.y"
+    assert a.cmd_move_status({})["state"] == "running"
+
+
+def test_replace_path_keeps_shell_quoting_valid(monkeypatch, tmp_path):
+    a = load(monkeypatch, tmp_path)
+    old, new = "/home/steamos/Applications/quest-frame/rift.x", "/run/media/steamos/SD/FramePort/rift.x"
+    text = (f"base={old}\ncd {old}/game\nexec proton run {old}/revive/ReviveInjector.exe /openxr "
+            f"'Z:\\home\\steamos\\Applications\\quest-frame\\rift.x\\game\\G.exe' >>\"$base/launch.log\"\n"
+            f"other={old}2/x\n")
+    out = a.replace_path(text, old, new)
+    assert f"base={new}\n" in out and f"cd {new}/game" in out and f"{new}/revive/ReviveInjector.exe" in out
+    assert "'Z:\\run\\media\\steamos\\SD\\FramePort\\rift.x\\game\\G.exe'" in out
+    assert f"other={old}2/x" in out  # another folder that only starts the same
+    with pytest.raises(a.AgentError):  # an unquoted path can't become one that needs quotes
+        a.replace_path(text, old, "/run/media/steamos/SD Card/FramePort/rift.x")
+    spaced = "/run/media/steamos/SD Card/FramePort/rift.x"
+    assert a.replace_path(f"base='{spaced}'\n", spaced, old) == f"base='{old}'\n"
+
+
+def test_symlinks_into_the_old_folder_follow_the_move(monkeypatch, tmp_path):
+    a = load(monkeypatch, tmp_path)
+    old, new = tmp_path / "old", tmp_path / "new"
+    (new / "game").mkdir(parents=True)
+    os.symlink(str(old / "revive" / "LibReviveXR64.dll"), new / "game" / "LibOVRRT64_1.dll")
+    os.symlink("../drive_c", new / "game" / "relative")
+    assert a.retarget_symlinks(str(new), ["game"], str(old), str(new)) == 1
+    assert os.readlink(new / "game" / "LibOVRRT64_1.dll") == str(new / "revive" / "LibReviveXR64.dll")
+    assert os.readlink(new / "game" / "relative") == "../drive_c"
+
+
+def linux_install(a, tmp_path, pkg="linux.true", title="True Tool", tags=None, dest=None, **extra):
+    prep = a.cmd_prepare_linux({"package": pkg, "title": title, "dest": dest})
+    app_in = os.path.join(prep["incoming"], "app", "bin")
+    os.makedirs(app_in)
+    shutil.copy("/bin/true", os.path.join(app_in, "true"))
+    size = os.path.getsize(os.path.join(app_in, "true"))
+    os.makedirs(os.path.join(prep["base"], "incoming-artwork"))
+    Path(prep["base"], "incoming-artwork", "icon.png").write_bytes(b"png")
+    res = a.cmd_finalize_linux({"package": pkg, "title": title, "exe": "bin/true", "tags": tags or [],
+                                "manifests": {"app": {"bin/true": size}}, "env": {"APP_MODE": "1"}, "dest": dest,
+                                **extra})
+    return prep, res
+
+
+def test_linux_app_moves_with_its_launcher(monkeypatch, tmp_path):
+    a = load(monkeypatch, tmp_path)
+    monkeypatch.setattr(a, "same_device", lambda x, y: False)
+    prep, _ = linux_install(a, tmp_path)
+    r = a.cmd_move({"package": "linux.true", "dest": str(sd_dir(tmp_path)), "detach": False})
+    assert r["state"] == "done", r
+    new = sd_dir(tmp_path) / "FramePort" / "linux.true"
+    text = (Path(prep["anchor"]) / "launch.sh").read_text()
+    assert f"'{new}/app/bin/true'" in text and "export APP_MODE=1" in text and prep["base"] not in text
+    assert subprocess.run(["bash", "-n", str(Path(prep["anchor"]) / "launch.sh")]).returncode == 0
+    assert (new / "app" / "bin" / "true").exists() and not (Path(prep["anchor"]) / "app").exists()
+
+
+def test_pc_vr_game_moves_with_its_prefix_and_launcher(monkeypatch, tmp_path):
+    """PC VR: the launcher is written again from the install record (env + game args kept since agent v63), the
+    Proton prefix moves with the game and the LibOVRRT redirect follows."""
+    from test_agent import fake_steam_tools
+
+    a = load(monkeypatch, tmp_path)
+    fake_steam_tools(a, Path(a.HOME))
+    monkeypatch.setattr(a, "same_device", lambda x, y: False)
+    prep = a.cmd_prepare_pcvr({"package": "rift.game", "title": "Rift Game"})
+    inc = Path(prep["incoming"])
+    (inc / "game/UEGame.exe").write_bytes(b"MZexe")
+    (inc / "revive/ReviveInjector.exe").write_bytes(b"MZ")
+    (inc / "revive/LibReviveXR64.dll").write_bytes(b"MZdll")
+    a.cmd_finalize_pcvr({"package": "rift.game", "title": "Rift Game", "exe": "UEGame.exe", "libovr_redirect": True,
+                         "manifests": {"game": {"UEGame.exe": 5},
+                                       "revive": {"ReviveInjector.exe": 2, "LibReviveXR64.dll": 5}},
+                         "env": {"FOO": "bar"}, "game_args": ["-vrmode"]})
+    base = Path(prep["base"])
+    (base / "compatdata/pfx/drive_c").mkdir(parents=True)
+    (base / "compatdata/pfx/drive_c/save.sav").write_text("saved")
+    assert os.path.islink(base / "game/LibOVRRT64_1.dll")
+    r = a.cmd_move({"package": "rift.game", "dest": str(sd_dir(tmp_path)), "detach": False})
+    assert r["state"] == "done", r
+    new = sd_dir(tmp_path) / "FramePort" / "rift.game"
+    assert (new / "compatdata/pfx/drive_c/save.sav").read_text() == "saved"
+    assert os.readlink(new / "game/LibOVRRT64_1.dll") == str(new / "revive/LibReviveXR64.dll")
+    text = (Path(prep["anchor"]) / "launch.sh").read_text()
+    assert f"{base}/game" not in text and f"{base}/revive" not in text  # (the play log stays in the anchor)
+    assert "export FOO=bar" in text and "-vrmode" in text
+    assert f"base='{new}'" in text
+    assert subprocess.run(["bash", "-n", str(Path(prep["anchor"]) / "launch.sh")]).returncode == 0
+
+
+def test_cleanup_and_purge_on_a_drive(monkeypatch, tmp_path):
+    a = load(monkeypatch, tmp_path)
+    monkeypatch.setattr(a, "stop_steam", lambda: True)
+    monkeypatch.setattr(a, "start_steam", lambda s: None)
+    fp = sd_dir(tmp_path) / "FramePort"
+    prep = quest_install(a, dest=str(fp))
+    (fp / "com.old.game").mkdir()  # left by an earlier install
+    (fp / "com.old.game" / "x").write_bytes(b"1234")
+    assert a.cmd_cleanup({"paths": [str(fp / "com.old.game")]})["freed_bytes"] == 4
+    for bad in (prep["base"], str(fp), str(fp / "com.x.y" / "lepton-data"), str(sd_dir(tmp_path))):
+        with pytest.raises(a.AgentError):
+            a.cmd_cleanup({"paths": [bad]})
+    a.purge_worker(json.dumps({"keep_saves": False, "status": str(tmp_path / "st.json")}))
+    assert json.loads((tmp_path / "st.json").read_text())["state"] == "done"
+    assert not fp.exists() and sd_dir(tmp_path).exists()
+
+
+# ------------------------------------------------------------------------------------------ Desktop Mode (#84)
+def test_linux_app_gets_a_desktop_mode_entry(monkeypatch, tmp_path):
+    a = load(monkeypatch, tmp_path)
+    (Path(a.HOME) / "Desktop").mkdir()
+    prep, res = linux_install(a, tmp_path, title='Odd "Name" 100%', tags=["Linux", "Puzzle"])
+    menu = Path(a.HOME) / ".local/share/applications/frameport-true.desktop"
+    desk = Path(a.HOME) / "Desktop/frameport-true.desktop"
+    assert res["desktop_entry"]["menu"] == str(menu) and res["desktop_entry"]["desktop"] == str(desk)
+    text = menu.read_text()
+    assert text == desk.read_text() and os.access(desk, os.X_OK)
+    lines = dict(line.split("=", 1) for line in text.splitlines()[1:])
+    assert lines["Name"] == 'Odd "Name" 100%' and lines["Categories"] == "Game;"
+    assert lines["Exec"] == f'env FRAMEPORT_DESKTOP=1 "{prep["anchor"]}/launch.sh"'
+    assert lines["Icon"] == f"{prep['anchor']}/artwork/icon.png" and lines["X-FramePort-Package"] == "linux.true"
+    assert lines["Terminal"] == "false"
+    # nothing changes when it is refreshed again; an app without game tags is a utility
+    assert a.refresh_desktop_entries() == []
+    linux_install(a, tmp_path, pkg="linux.editor", title="Editor")
+    assert "Categories=Utility;" in (Path(a.HOME) / ".local/share/applications/frameport-editor.desktop").read_text()
+    # uninstall removes both files
+    a.cmd_uninstall({"package": "linux.true", "keep_data": False})
+    assert not menu.exists() and not desk.exists()
+
+
+def test_exec_quoting():
+    spec = importlib.util.spec_from_file_location("frameport_agent", AGENT)
+    a = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(a)
+    assert a.desktop_exec_arg('/a b/$x`"\\%') == '"/a b/\\\\$x\\\\`\\\\"\\\\\\\\%%"'
+    assert a.desktop_value("two\nlines\\") == "two lines\\\\"
+    assert a.desktop_file_name("linux.My App!") == "frameport-My-App.desktop"
+
+
+def test_desktop_entry_switch_and_refresh(monkeypatch, tmp_path):
+    a = load(monkeypatch, tmp_path)
+    linux_install(a, tmp_path, desktop_entry=False)
+    menu = Path(a.HOME) / ".local/share/applications/frameport-true.desktop"
+    assert not menu.exists() and a.deployment("linux.true")["desktop_entry"] is False
+    assert a.refresh_desktop_entries() == []  # off stays off
+    r = a.cmd_desktop_entry({"package": "linux.true", "enabled": True})
+    assert r["enabled"] and menu.exists()
+    a.cmd_desktop_entry({"package": "linux.true", "enabled": False})
+    assert not menu.exists()
+    # an install from before agent v63 (no desktop_entry field) gets one with the host fixes; stale ones go
+    dep_path = Path(a.ANCHORS) / "linux.true" / "deployment.json"
+    raw = json.loads(dep_path.read_text())
+    raw.pop("desktop_entry")
+    dep_path.write_text(json.dumps(raw))
+    stale = menu.parent / "frameport-gone.desktop"
+    stale.write_text("[Desktop Entry]\nX-FramePort-Package=linux.gone\n")
+    (menu.parent / "frameport-links.desktop").write_text("[Desktop Entry]\nName=not an app entry\n")
+    assert "Desktop Mode entries (2)" in a.ensure_host_fixes()
+    assert menu.exists() and not stale.exists() and (menu.parent / "frameport-links.desktop").exists()
+    with pytest.raises(a.AgentError):
+        a.cmd_desktop_entry({"package": "com.not.linux", "enabled": True})
+
+
+def test_linux_launcher_from_desktop_mode(monkeypatch, tmp_path):
+    """Started from Desktop Mode (FRAMEPORT_DESKTOP=1) the launcher's parent exits at once: the app must keep running,
+    and the desktop's display is used instead of Steam's."""
+    a = load(monkeypatch, tmp_path)
+    prep, _ = linux_install(a, tmp_path)
+    text = (Path(prep["anchor"]) / "launch.sh").read_text()
+    assert '[[ -n "${FRAMEPORT_DESKTOP:-}" ]] && parent=1' in text
+    assert 'if [[ -z "${FRAMEPORT_DESKTOP:-}" && -z "${DISPLAY:-}" ]]; then' in text
+    # older launchers are upgraded in place
+    old = text.replace('[[ -n "${FRAMEPORT_DESKTOP:-}" ]] && parent=1\n', "").replace(
+        'if [[ -z "${FRAMEPORT_DESKTOP:-}" && -z "${DISPLAY:-}" ]]; then', 'if [[ -z "${DISPLAY:-}" ]]; then')
+    old = old.replace("# Started from Desktop Mode's menu (FRAMEPORT_DESKTOP=1, GitHub #84) the desktop's own session "
+                      "is used.\n", "")
+    assert "FRAMEPORT_DESKTOP" not in old
+    (Path(prep["anchor"]) / "launch.sh").write_text(old)
+    assert "linux.true" in a.upgrade_launchers()
+    new = (Path(prep["anchor"]) / "launch.sh").read_text()
+    assert '[[ -n "${FRAMEPORT_DESKTOP:-}" ]] && parent=1' in new and "FRAMEPORT_DESKTOP:-}\" && -z" in new
+    assert subprocess.run(["bash", "-n", str(Path(prep["anchor"]) / "launch.sh")]).returncode == 0
+    # the watchdog: a parent that exits ends the app, unless started from the desktop
+    script = tmp_path / "app.sh"
+    script.write_text("#!/bin/sh\nsleep 6\necho finished >" + str(tmp_path / "out") + "\n")
+    script.chmod(0o755)
+    program = os.path.join(prep["base"], "app", "bin", "true")
+    assert program in new
+    body = new.replace(program, str(script))
+    launcher = tmp_path / "l.sh"
+    launcher.write_text(body)
+    launcher.chmod(0o755)
+    env = dict(os.environ, FRAMEPORT_DESKTOP="1", DISPLAY=":9")
+    subprocess.run(["bash", "-c", f"{launcher} & exit 0"], env=env, timeout=20)
+    import time
+
+    deadline = time.time() + 15
+    while time.time() < deadline and not (tmp_path / "out").exists():
+        time.sleep(0.5)
+    assert (tmp_path / "out").read_text().strip() == "finished"

tests/test_heuristics.py

@@ -73,3 +73,22 @@ def test_enabled_patch_is_never_hidden():
     r.patches["frame.vrapi_bridge"] = {}
     shown, _ = engine.visible_patches(a, r)
     assert "frame.vrapi_bridge" in {p.id for p in shown}
+
+
+def test_newer_android_than_the_frames_only_warns():
+    """GitHub #71/#72: minSdk 34 apps crash at start on Android 13+ classes; Lepton runs Android 11."""
+    _, r = suggest(extra={"size": 1, "min_sdk": 34})
+    assert r.status != "unsupported"  # the manifest alone never decides (a launch test does)
+    assert "asks for Android 14 (API 34)" in r.notes and "Android is 11 (API 30)" in r.notes
+    # Quest games declare up to 32 (Quest's Android 12L) and run (16 catalog games do)
+    for ok in (None, 23, 29, 32):
+        _, r = suggest(extra={"size": 1, "min_sdk": ok})
+        assert r.status != "unsupported" and "asks for Android" not in r.notes
+
+
+def test_web_wrapper_only_warns():
+    """GitHub #86: a Trusted Web Activity opens a website in Meta's browser; there's nothing to port."""
+    _, r = suggest(extra={"size": 1, "web_wrapper": {"url": "https://mahjong-vr.pages.dev/"}})
+    assert r.status != "unsupported" and "open https://mahjong-vr.pages.dev/ in a browser" in r.notes
+    _, r = suggest(extra={"size": 1, "web_wrapper": {"url": None}})
+    assert r.status != "unsupported" and "website" in r.notes

tests/test_input_diag.py

@@ -0,0 +1,155 @@
+"""FrameBridge's controller-input diagnostics (native/adapter/input_diag.c), compiled for this host with a small C
+harness that stands in for the adapter (lookup, path strings, result names, logging) and for the runtime.
+Opt-in (FRAMEPORT_NATIVE_TESTS=1, -m native): needs the OpenXR headers in native/.cache (from native/build.py)."""
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+INC = next(iter((ROOT / "native/.cache").glob("openxr-*")), None)
+CC = shutil.which("cc") or shutil.which("clang")
+pytestmark = [pytest.mark.native, pytest.mark.skipif(
+    not os.environ.get("FRAMEPORT_NATIVE_TESTS") or not INC or not CC,
+    reason="set FRAMEPORT_NATIVE_TESTS=1 (needs the OpenXR headers from native/build.py and a host C compiler)")]
+
+HARNESS = r"""
+#define XR_EXTENSION_PROTOTYPES
+#include <openxr/openxr.h>
+#include <pthread.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#define LOG(...) (fprintf(stderr, __VA_ARGS__), fputc('\n', stderr))
+static XrInstance active_instance = (XrInstance)(uintptr_t)1;
+static int input_diag;
+static char paths[16][XR_MAX_PATH_LENGTH];
+static int path_count;
+static XRAPI_ATTR XrResult XRAPI_CALL fake_string_to_path(XrInstance i, const char *s, XrPath *out) {
+    (void)i;
+    for (int k = 0; k < path_count; ++k) if (!strcmp(paths[k], s)) { *out = (XrPath)(k + 1); return XR_SUCCESS; }
+    snprintf(paths[path_count], XR_MAX_PATH_LENGTH, "%s", s);
+    *out = (XrPath)++path_count;
+    return XR_SUCCESS;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL fake_path_to_string(XrInstance i, XrPath p, uint32_t cap, uint32_t *n,
+                                                          char *out) {
+    (void)i;
+    if (!p || p > (XrPath)path_count) return XR_ERROR_PATH_INVALID;
+    *n = (uint32_t)snprintf(out, cap, "%s", paths[p - 1]) + 1;
+    return XR_SUCCESS;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL fake_result_to_string(XrInstance i, XrResult r, char *out) {
+    (void)i;
+    const char *name = r == XR_ERROR_PATH_UNSUPPORTED ? "XR_ERROR_PATH_UNSUPPORTED"
+                     : r == XR_ERROR_NAME_INVALID ? "XR_ERROR_NAME_INVALID"
+                     : r == XR_ERROR_FUNCTION_UNSUPPORTED ? "XR_ERROR_FUNCTION_UNSUPPORTED" : NULL;
+    if (!name) return XR_ERROR_VALIDATION_FAILURE;
+    snprintf(out, XR_MAX_RESULT_STRING_SIZE, "%s", name);
+    return XR_SUCCESS;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL fake_create_action(XrActionSet set, const XrActionCreateInfo *info,
+                                                         XrAction *action) {
+    (void)set; *action = XR_NULL_HANDLE;
+    return strchr(info->actionName, ' ') ? XR_ERROR_NAME_INVALID : XR_SUCCESS;
+}
+static PFN_xrVoidFunction lookup(XrInstance i, const char *name) {
+    (void)i;
+    if (!strcmp(name, "xrPathToString")) return (PFN_xrVoidFunction)fake_path_to_string;
+    if (!strcmp(name, "xrResultToString")) return (PFN_xrVoidFunction)fake_result_to_string;
+    if (!strcmp(name, "xrCreateAction")) return (PFN_xrVoidFunction)fake_create_action;
+    return NULL;
+}
+#include "input_diag.c"
+#define CHECK(c) do { if (!(c)) { fprintf(stderr, "FAILED line %d: %s\n", __LINE__, #c); return 1; } } while (0)
+int main(int argc, char **argv) {
+    (void)argv;
+    if (argc > 1) {  // more distinct findings than DIAG_MAX: the rest is dropped, with one line saying so
+        input_diag = 1;
+        char name[32];
+        for (int i = 0; i < 600; ++i) {
+            snprintf(name, sizeof(name), "xrMissing%d", i);
+            input_diag_lookup(active_instance, name, XR_ERROR_FUNCTION_UNSUPPORTED, NULL);
+            input_diag_lookup(active_instance, name, XR_ERROR_FUNCTION_UNSUPPORTED, NULL);
+        }
+        return 0;
+    }
+    XrPath touch, plus, left, right, proximity, a;
+    fake_string_to_path(0, "/interaction_profiles/oculus/touch_controller", &touch);
+    fake_string_to_path(0, "/interaction_profiles/meta/touch_controller_plus", &plus);
+    fake_string_to_path(0, "/user/hand/left", &left);
+    fake_string_to_path(0, "/user/hand/right", &right);
+    fake_string_to_path(0, "/user/hand/left/input/thumb_resting_surfaces/proximity", &proximity);
+    fake_string_to_path(0, "/user/hand/right/input/a/click", &a);
+    XrActionSuggestedBinding bindings[2] = {{XR_NULL_HANDLE, proximity}, {XR_NULL_HANDLE, a}};
+    XrInteractionProfileSuggestedBinding s = {XR_TYPE_INTERACTION_PROFILE_SUGGESTED_BINDING, NULL, plus, 2, bindings};
+
+    input_diag_suggested(active_instance, &s, XR_ERROR_PATH_UNSUPPORTED, fake_path_to_string);  // off: nothing
+    input_diag_lookup(active_instance, "xrCreateBodyTrackerFB", XR_ERROR_FUNCTION_UNSUPPORTED, NULL);
+    input_diag = 1;
+    input_diag_suggested(active_instance, &s, XR_ERROR_PATH_UNSUPPORTED, fake_path_to_string);
+    input_diag_suggested(active_instance, &s, XR_ERROR_PATH_UNSUPPORTED, fake_path_to_string);  // once
+    s.interactionProfile = touch;
+    input_diag_suggested(active_instance, &s, XR_SUCCESS, fake_path_to_string);
+    input_diag_current_profile(left, touch);
+    input_diag_current_profile(left, touch);  // once
+    input_diag_current_profile(right, XR_NULL_PATH);
+
+    PFN_xrCreateAction create = (PFN_xrCreateAction)input_diag_hook("xrCreateAction");
+    CHECK(create && input_diag_hook("xrStringToPath") && !input_diag_hook("xrEndFrame"));
+    XrActionCreateInfo info = {XR_TYPE_ACTION_CREATE_INFO};
+    XrAction action;
+    snprintf(info.actionName, sizeof(info.actionName), "trigger pull");
+    CHECK(create(XR_NULL_HANDLE, &info, &action) == XR_ERROR_NAME_INVALID);
+    CHECK(create(XR_NULL_HANDLE, &info, &action) == XR_ERROR_NAME_INVALID);  // once
+    snprintf(info.actionName, sizeof(info.actionName), "trigger_pull");
+    CHECK(create(XR_NULL_HANDLE, &info, &action) == XR_SUCCESS);  // success: nothing
+
+    input_diag_lookup(active_instance, "xrCreateBodyTrackerFB", XR_ERROR_FUNCTION_UNSUPPORTED, NULL);
+    input_diag_lookup(active_instance, "xrCreateBodyTrackerFB", XR_ERROR_FUNCTION_UNSUPPORTED, NULL);  // once
+    input_diag_lookup(XR_NULL_HANDLE, "xrCreateInstance", XR_ERROR_FUNCTION_UNSUPPORTED, NULL);  // no instance yet
+    input_diag_lookup(active_instance, "xrSyncActions", XR_SUCCESS, (PFN_xrVoidFunction)fake_create_action);
+    return 0;
+}
+"""
+
+EXPECTED = [
+    "input_diag: unsupported: interaction profile /interaction_profiles/meta/touch_controller_plus -> "
+    "XR_ERROR_PATH_UNSUPPORTED (2 bindings):",
+    "input_diag:   /user/hand/left/input/thumb_resting_surfaces/proximity",
+    "input_diag:   /user/hand/right/input/a/click",
+    "input_diag: bindings: /interaction_profiles/oculus/touch_controller accepted (2 paths)",
+    "input_diag: bindings: /user/hand/left uses /interaction_profiles/oculus/touch_controller",
+    "input_diag: bindings: /user/hand/right uses none",
+    "input_diag: unsupported: xrCreateAction -> XR_ERROR_NAME_INVALID (trigger pull)",
+    "input_diag: unsupported: function xrCreateBodyTrackerFB not provided by the runtime "
+    "(XR_ERROR_FUNCTION_UNSUPPORTED)",
+]
+
+
+@pytest.fixture(scope="module")
+def harness(tmp_path_factory):
+    d = tmp_path_factory.mktemp("input_diag")
+    (d / "harness.c").write_text(HARNESS)
+    subprocess.run([CC, "-std=c11", "-D_GNU_SOURCE", "-Wall", "-Wextra", "-Werror", "-Wno-unused-function",
+                    "-Wno-missing-field-initializers", "-pthread", "-I", str(INC),
+                    "-I", str(ROOT / "native/adapter"),
+                    str(d / "harness.c"), "-o", str(d / "harness")], check=True)
+    return d / "harness"
+
+
+def test_logs_each_finding_once_and_nothing_when_off(harness):
+    p = subprocess.run([str(harness)], capture_output=True, text=True)
+    assert p.returncode == 0, p.stderr
+    assert p.stderr.splitlines() == EXPECTED
+
+
+def test_stops_after_512_distinct_findings(harness):
+    p = subprocess.run([str(harness), "flood"], capture_output=True, text=True)
+    lines = p.stderr.splitlines()
+    assert p.returncode == 0 and len(lines) == 513
+    assert lines[511].startswith("input_diag: unsupported: function xrMissing511 ")
+    assert lines[512] == "input_diag: 512 distinct findings, logging no more"

tests/test_install_drives.py

@@ -0,0 +1,138 @@
+"""PC side of games on another drive (GitHub #90) and Linux apps' Desktop Mode entries (GitHub #84)."""
+from pathlib import Path
+
+import pytest
+
+from frameport.core import library
+from frameport.core.events import Cancelled, Reporter
+from frameport.frame.connection import FrameTarget
+from frameport.install import drives, installer
+from frameport.targets.frame_lepton import FrameLeptonTarget
+
+
+class FakeFrame:
+    """Answers agent commands from a script: {command: reply or [replies] or callable(args)}."""
+
+    def __init__(self, replies):
+        self.replies, self.calls = replies, []
+
+    def agent(self, command, timeout=None, **args):
+        self.calls.append((command, args))
+        r = self.replies[command]
+        if callable(r):
+            return r(args)
+        if isinstance(r, list):
+            return r.pop(0) if len(r) > 1 else r[0]
+        return r
+
+
+def test_install_dest_setting():
+    assert drives.install_dest() is None
+    drives.set_install_dest("/run/media/steamos/SD/FramePort")
+    assert drives.install_dest() == "/run/media/steamos/SD/FramePort"
+    assert library.setting(drives.SETTING) == "/run/media/steamos/SD/FramePort"
+    drives.set_install_dest(None)
+    assert drives.install_dest() is None and library.setting(drives.SETTING) == "internal"
+    t = FrameLeptonTarget(FrameTarget("frame.local", "steamos", 22))
+    drives.set_install_dest("/run/media/steamos/SD/FramePort")
+    assert t.install_dest() == "/run/media/steamos/SD/FramePort"
+    t.dest = ""  # frameport install --dest internal
+    assert t.install_dest() == ""
+
+
+def test_linux_install_passes_dest_and_desktop_entry(monkeypatch, tmp_path):
+    (tmp_path / "app").mkdir()
+    (tmp_path / "app" / "tool").write_bytes(b"#!/bin/sh\n")
+    monkeypatch.setattr(installer, "upload_steam_art", lambda *a, **k: None)
+    monkeypatch.setattr(installer, "_tags", lambda pkg: [])
+    frame = FakeFrame({"prepare_linux": {"existing": {"app": {"tool": 10}}, "free_bytes": 1 << 40,
+                                         "incoming": "/x/incoming", "base": "/sd/FramePort/linux.tool"},
+                       "finalize_linux": {"base": "/sd/FramePort/linux.tool", "appid": 1,
+                                          "desktop_entry": {"menu": "/m", "desktop": "/d"}}})
+    plan = installer.LinuxPlan("linux.tool", "Tool", tmp_path / "app", "tool", dest="/sd/FramePort",
+                               desktop_entry=False)
+    rep = Reporter()
+    checks = []
+    rep.subscribe(lambda ev: ev.kind == "check" and checks.append(ev.data["name"]))
+    installer.install_linux(frame, plan, rep)
+    assert frame.calls[0] == ("prepare_linux", {"package": "linux.tool", "title": "Tool", "dest": "/sd/FramePort"})
+    fin = dict(frame.calls)["finalize_linux"]
+    assert fin["dest"] == "/sd/FramePort" and fin["desktop_entry"] is False
+    assert "Desktop Mode entry" in checks
+
+
+def test_move_follows_the_agents_progress():
+    status = [{"state": "none"},
+              {"state": "running", "package": "com.x.y", "phase": "copying", "done_bytes": 1 << 30,
+               "total_bytes": 2 << 30},
+              {"state": "running", "package": "com.x.y", "phase": "verifying", "done_bytes": 2 << 30,
+               "total_bytes": 2 << 30},
+              {"state": "done", "package": "com.x.y", "base": "/sd/FramePort/com.x.y"}]
+    frame = FakeFrame({"move_status": status,
+                       "move": {"started": True, "from": "/home/a", "to": "/sd/FramePort/com.x.y",
+                                "total_bytes": 2 << 30}})
+    rep = Reporter()
+    seen = []
+    rep.subscribe(lambda ev: ev.kind == "progress" and seen.append((round(ev.fraction, 2), ev.message)))
+    st = drives.move(frame, "com.x.y", "/sd/FramePort", rep, sleep=lambda s: None)
+    assert st["state"] == "done"
+    assert ("move", {"package": "com.x.y", "dest": "/sd/FramePort"}) in frame.calls
+    assert seen[0] == (0.5, "Copying 1.0/2.0 GiB") and seen[1][1].startswith("Checking the copy")
+
+
+def test_move_picks_up_a_running_move_and_reports_failures():
+    frame = FakeFrame({"move_status": [{"state": "running", "package": "com.x.y", "total_bytes": 0},
+                                       {"state": "failed", "error": "the copy doesn't match"}],
+                       "move": lambda a: pytest.fail("a running move of the same game isn't started again")})
+    with pytest.raises(RuntimeError, match="doesn't match"):
+        drives.move(frame, "com.x.y", "internal", Reporter(), sleep=lambda s: None)
+    # a retried job (the Frame was lost) whose move finished meanwhile
+    from frameport.frame.connection import AgentFailed
+
+    def already(a):
+        raise AgentFailed("Game is already there")
+    frame = FakeFrame({"move_status": {"state": "done", "package": "com.x.y"}, "move": already})
+    assert drives.move(frame, "com.x.y", "internal", Reporter(), sleep=lambda s: None)["state"] == "done"
+    # cancelled before the copy started: nothing is asked of the Frame
+    frame = FakeFrame({"move_status": {"state": "none"}, "move": lambda a: pytest.fail("started")})
+    rep = Reporter()
+    rep.cancelled.set()
+    with pytest.raises(Cancelled):
+        drives.move(frame, "com.x.y", "internal", rep, sleep=lambda s: None)
+
+
+def test_drive_helpers():
+    d_int = {"internal": True, "path": "/home/steamos", "label": "Internal storage", "free_bytes": 12.5 * 2**30}
+    d_sd = {"internal": False, "path": "/run/media/steamos/SD", "label": "SD", "free_bytes": None}
+    assert drives.drive_text(d_int) == "Internal storage · 12.5 GiB free" and drives.drive_text(d_sd) == "SD"
+    on_sd = {"drive": {"internal": False, "path": "/run/media/steamos/SD", "label": "SD"}, "drive_missing": True}
+    assert drives.game_drive(on_sd)["missing"] is True and drives.game_drive({"package": "x"}) is None
+    assert drives.is_on(on_sd, d_sd) and not drives.is_on(on_sd, d_int)
+    assert drives.is_on({"package": "old agent"}, d_int)
+
+
+def test_target_switches_a_desktop_entry(monkeypatch):
+    t = FrameLeptonTarget(FrameTarget("frame.local", "steamos", 22))
+    t.frame = FakeFrame({"desktop_entry": lambda a: {"enabled": a["enabled"]}})
+    monkeypatch.setattr(t, "connect", lambda: t)
+    assert t.set_desktop_entry("linux.tool", False) == {"enabled": False}
+    assert t.frame.calls == [("desktop_entry", {"package": "linux.tool", "enabled": False})]
+
+
+def test_pipeline_passes_the_desktop_entry_choice(monkeypatch):
+    from frameport import pipeline
+
+    library.upsert_game("linux.tool", kind="linux", title="Tool", game_dir=str(Path("/apps/tool")), exe="tool",
+                        desktop_entry=False, analysis={"extra": {}})
+    got = {}
+
+    class T:
+        label = "Frame"
+
+        def install_linux(self, *a, **k):
+            got.update(k)
+            return {}
+
+    monkeypatch.setattr(pipeline, "steam_title", lambda e: "Tool")
+    pipeline.install_linux("linux.tool", T(), Reporter(), add_to_library=False)
+    assert got["desktop_entry"] is False

tests/test_install_links_extra.py

@@ -0,0 +1,202 @@
+"""Install links, continued (test_deeplink.py has the main cases): cancelled downloads, FrameDrop's placeholder
+checksum, which file a manifest installs, naming the program that owns a scheme, lone Windows programs."""
+import threading
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+
+import pytest
+
+from frameport import deeplink, pipeline, urlhandler
+from frameport.core import library
+from frameport.core.events import Cancelled, Reporter
+
+APK = "https://cdn.example.com/game-arm64.apk"
+
+
+class _Server(ThreadingHTTPServer):
+    def handle_error(self, request, client_address):  # the cancelled download closes the connection mid-file
+        pass
+
+
+class _Handler(SimpleHTTPRequestHandler):
+    def log_message(self, *args):
+        pass
+
+
+def test_cancel_removes_the_partial_file(tmp_path):
+    www = tmp_path / "www"
+    www.mkdir()
+    (www / "big.apk").write_bytes(b"x" * (3 << 20))
+    httpd = _Server(("127.0.0.1", 0), partial(_Handler, directory=str(www)))
+    threading.Thread(target=httpd.serve_forever, daemon=True).start()
+    try:
+        rep = Reporter()
+        rep.cancelled.set()
+        dest = tmp_path / "out" / "big.apk"
+        with pytest.raises(Cancelled):
+            deeplink.download_file(f"http://127.0.0.1:{httpd.server_address[1]}/big.apk", dest, rep)
+        assert not dest.exists() and not dest.with_name("big.apk.part").exists()
+    finally:
+        httpd.shutdown()
+
+
+def test_placeholder_checksum_is_ignored():
+    """FrameDrop's documented example has "sha256": "optional-but-better"."""
+    m = deeplink.manifest_from_data({"schema": deeplink.SCHEMA, "name": "G",
+                                     "files": [{"url": APK, "sha256": "optional-but-better"}]})
+    assert m.main.sha256 is None
+
+
+def test_main_file_prefers_the_apk():
+    m = deeplink.manifest_from_data({"schema": deeplink.SCHEMA, "name": "G", "files": [
+        {"url": "https://c.example.com/main.1.g.obb"}, {"url": "https://c.example.com/tool.exe"}, {"url": APK}]})
+    assert m.main.url == APK
+
+
+def test_status_names_the_other_program(monkeypatch):
+    handlers = {"framedrop": r'"C:\Program Files\FrameDrop\FrameDrop.exe" "%1"',
+                "frameport": f'"powershell.exe" -File "{urlhandler.MARK}.ps1" "%1"'}
+    monkeypatch.setattr(urlhandler, "platform_kind", lambda: "windows")
+    monkeypatch.setattr(urlhandler, "windows_handler", handlers.get)
+    st = urlhandler.status()
+    assert st["framedrop"] == "other" and st["framedrop_by"] == "FrameDrop" and st["frameport"] == "ours"
+
+
+def test_desktop_entry_lists_only_the_enabled_schemes():
+    entry = urlhandler.desktop_entry("sh /x.sh %u", ["frameport"])
+    assert "MimeType=x-scheme-handler/frameport;\n" in entry and "framedrop" not in entry.split("MimeType")[1]
+
+
+def test_lone_exe_in_downloads_is_copied_alone(tmp_path, monkeypatch):
+    downloads = tmp_path / "Downloads"
+    downloads.mkdir()
+    (downloads / "huge-unrelated.iso").write_bytes(b"x")
+    exe = downloads / "Tool.exe"
+    exe.write_bytes(b"MZ")
+    seen = {}
+
+    def fake_add(folder, reporter=None, exe=None, force=False, art=False):
+        seen.update(folder=folder, exe=exe, force=force)
+        return library.upsert_game("rift.tool", kind="rift", title="Tool", exe=exe)
+    monkeypatch.setattr(pipeline, "add_rift_game", fake_add)
+    g = pipeline.add_windows_exe(exe)
+    assert seen["exe"] == "Tool.exe" and seen["force"] and g["exe_confirmed"]
+    assert seen["folder"] != downloads and sorted(p.name for p in seen["folder"].iterdir()) == ["Tool.exe"]
+
+
+def test_exe_in_its_own_folder_keeps_the_folder(tmp_path, monkeypatch):
+    game = tmp_path / "Games" / "Tool"
+    game.mkdir(parents=True)
+    (game / "Tool.exe").write_bytes(b"MZ")
+    seen = {}
+    monkeypatch.setattr(pipeline, "add_rift_game", lambda folder, *a, **k: seen.update(folder=folder) or
+                        library.upsert_game("rift.tool", kind="rift"))
+    pipeline.add_windows_exe(game / "Tool.exe")
+    assert seen["folder"] == game
+
+
+def test_not_an_exe_is_refused(tmp_path):
+    p = tmp_path / "setup.msi"
+    p.write_bytes(b"x")
+    with pytest.raises(ValueError, match="isn't a Windows program"):
+        pipeline.add_windows_exe(p)
+
+
+# ------------------------------------------------------------------------------------------------- titles
+@pytest.mark.parametrize("name, title", [
+    ("net.sourceforge.opencamera_96.apk", "Opencamera"), ("Cool_Game-v1.2.3-arm64-v8a.apk", "Cool Game"),
+    ("com.example.MyGame.apk", "MyGame"), ("SuperTuxKart-1.4-linux-x86_64.tar.xz", "SuperTuxKart"),
+    ("thing-linux-aarch64.tar.gz", "Thing")])
+def test_titles_from_file_names(name, title):
+    assert deeplink.title_from_filename(name) == title
+
+
+# ------------------------------------------------------------------------------------------------- FramePort fields
+def _manifest(extra):
+    return deeplink.manifest_from_data({"schema": deeplink.SCHEMA, "name": "G", "files": [{"url": APK}],
+                                        "frameport": extra})
+
+
+def test_frameport_fields():
+    m = _manifest({"description": "  A game.  ", "icon": "https://cdn.example.com/icon.png"})
+    assert m.description == "A game." and m.icon == "https://cdn.example.com/icon.png"
+
+
+@pytest.mark.parametrize("extra", [{"icon": "http://cdn.example.com/i.png"}, {"icon": "https://10.0.0.1/i.png"},
+                                   {"description": 5, "icon": 7}, "not a dict"])
+def test_bad_frameport_fields_are_ignored(extra):
+    m = _manifest(extra)
+    assert m.icon is None and m.description == ""
+
+
+def test_long_description_is_cut():
+    assert len(_manifest({"description": "x" * 5000}).description) == deeplink.MAX_DESCRIPTION
+
+
+def _serve(tmp_path):
+    www = tmp_path / "www"
+    www.mkdir(exist_ok=True)
+    httpd = _Server(("127.0.0.1", 0), partial(_Handler, directory=str(www)))
+    threading.Thread(target=httpd.serve_forever, daemon=True).start()
+    return httpd, www, f"http://127.0.0.1:{httpd.server_address[1]}"
+
+
+def test_icon_is_fetched_and_checked(tmp_path):
+    from PIL import Image
+
+    httpd, www, base = _serve(tmp_path)
+    try:
+        Image.new("RGB", (128, 96), "red").save(www / "icon.jpg")
+        Image.new("RGB", (16, 16), "red").save(www / "tiny.png")
+        (www / "junk.png").write_bytes(b"not an image")
+        m = deeplink.Manifest("G", [deeplink.ManifestFile(APK)], icon=f"{base}/icon.jpg")
+        icon = deeplink.fetch_icon(m)
+        assert icon and icon.suffix == ".png" and Image.open(icon).size == (128, 96)
+        for bad in ("tiny.png", "junk.png", "missing.png"):
+            m.icon = f"{base}/{bad}"
+            assert deeplink.fetch_icon(m) is None
+    finally:
+        httpd.shutdown()
+
+
+def test_description_fills_missing_details_only(monkeypatch, tmp_path):
+    path = tmp_path / "Tool.exe"
+    path.write_bytes(b"MZ")
+    library.upsert_game("rift.tool", kind="rift", details={"sources": []})  # no store description
+    monkeypatch.setattr(pipeline, "add_windows_exe", lambda p, r=None: library.game("rift.tool"))
+    m = deeplink.Manifest("Tool", [deeplink.ManifestFile("https://c.example.com/Tool.exe")], "https://c.example.com/t.json",
+                          description="Does things.")
+    g = pipeline.add_from_link(m, path)
+    assert g["details"]["description"] == "Does things." and g["title"] == "Tool" and g["title_locked"]
+    library.upsert_game("rift.tool", details={"description": "From the store."})
+    assert pipeline.add_from_link(m, path)["details"]["description"] == "From the store."
+
+
+# ------------------------------------------------------------------------------------------------- handler scripts
+def test_scripts_wait_for_the_open_window_to_take_the_link():
+    """A heartbeat left by a window that was just closed must not swallow the link (seen on Windows)."""
+    from pathlib import Path
+
+    ps1 = urlhandler.ps1_script(Path("C:/fp"), ["C:/FramePort/FramePort.exe"])
+    assert "Test-Path $queued" in ps1 and ps1.index("Test-Path $queued") < ps1.index("Start-Process")
+    sh = urlhandler.sh_script(Path("/fp"), ["/usr/bin/python3", "-m", "frameport.ui.app"])
+    assert '[ -e "$queued" ] || exit 0' in sh and sh.index("$queued") < sh.index("setsid")
+
+
+def test_sh_handler_starts_the_app_when_a_stale_heartbeat_never_takes_the_link(tmp_path):
+    import subprocess
+
+    data = tmp_path / "data"
+    data.mkdir()
+    (data / "gui.alive").touch()  # fresh, but nobody takes links
+    marker = tmp_path / "started"
+    script = tmp_path / "h.sh"
+    script.write_text(urlhandler.sh_script(data, ["touch", str(marker)]))
+    subprocess.run(["sh", str(script), "frameport://install?url=x"], timeout=20, check=True)
+    for _ in range(40):
+        if marker.exists():
+            break
+        import time
+
+        time.sleep(0.1)
+    assert marker.exists() and len(list((data / "links").glob("*.link"))) == 1

tests/test_linux_apps.py

@@ -1,4 +1,4 @@
-"""Native arm64 Linux apps (GitHub #31): detection of AppImages, folders and archives."""
+"""Linux apps (GitHub #31; arm64, x86_64 through FEX): detection of AppImages, folders and archives."""
 import tarfile
 import zipfile
 
@@ -26,11 +26,28 @@ def test_appimage_detection_and_title(tmp_path):
     assert not info["openxr"]
 
 
-def test_x86_64_builds_are_refused(tmp_path):
+def test_x86_64_builds_run_through_fex(tmp_path):
     p = tmp_path / "Thing-1.0-x86_64.AppImage"
     p.write_bytes(elf(linux.EM_X86_64, appimage=True))
-    with pytest.raises(ValueError, match="x86_64"):
-        pipeline.add_linux_app(p)
+    g = pipeline.add_linux_app(p)
+    extra = g["analysis"]["extra"]
+    assert extra["x86_64"] and g["analysis"]["abis"] == ["x86_64"]
+    other = tmp_path / "riscv-tool"
+    other.write_bytes(elf(243))
+    with pytest.raises(ValueError, match="machine 243"):
+        pipeline.add_linux_app(other)
+
+
+def test_arm64_program_wins_over_x86_64(tmp_path):
+    root = tmp_path / "Both"
+    (root / "x86").mkdir(parents=True)
+    (root / "x86" / "Both").write_bytes(elf(linux.EM_X86_64, extra=b"\0" * 4096))  # bigger: ranked first by size
+    (root / "Both").write_bytes(elf(linux.EM_AARCH64))
+    info = linux.inspect(root)
+    assert info["exe"] == "Both" and info["arch_ok"] and info["candidates"] == ["Both"]
+    (root / "Both").unlink()
+    info = linux.inspect(root)
+    assert info["exe"] == "x86/Both" and info["machine"] == linux.EM_X86_64 and not info["arch_ok"]
 
 
 def test_archive_program_ranking_and_openxr(tmp_path):

tests/test_livestream.py

@@ -243,5 +243,253 @@ def test_relay_with_audio():
 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
+    audio = cmd[cmd.index("audio=(-thread_queue_size"):cmd.index("fi\n", cmd.index("audio=(-thread_queue_size"))]
+    assert "-ts mono2abs" in cmd and "-use_wallclock_as_timestamps" not in audio  # both on pulse's wall clock
+    # (the hardware path stamps its raw H.264 input with the wall clock; the pulse input never gets that flag)
     assert "aresample=async=1" in cmd
+
+
+# ------------------------------------------------------------------------------------------------ hardware encoder
+def _fake_tools(tmp_path, probe_exit=0, fps=32):
+    """A headset-view device, a fake fp_venc (probe JSON / copies stdin to stdout) and a fake ffmpeg (logs its args,
+    reads its stdin to the end)."""
+    dev = tmp_path / "video99"
+    dev.mkdir()
+    (dev / "name").write_text("SteamVR\n")
+    bindir = tmp_path / "bin"
+    bindir.mkdir()
+    venc = bindir / "fp_venc"
+    venc.write_text("#!/bin/sh\n"
+                    f'echo "$@" >> {tmp_path}/venc.args\n'
+                    'case " $* " in *" --probe "*)\n'
+                    f'  [ {probe_exit} = 0 ] || exit {probe_exit}\n'
+                    f'  echo \'{{"encoder":"/dev/video23","fps":{fps},"bitrate":3000000}}\'; exit 0;;\n'
+                    "esac\n"
+                    "exec cat\n")
+    ffmpeg = bindir / "ffmpeg"
+    ffmpeg.write_text("#!/bin/sh\n"
+                      f'echo "$@" > {tmp_path}/ffmpeg.args\n'
+                      "exec cat > /dev/null\n")
+    for f in (venc, ffmpeg):
+        f.chmod(0o755)
+    env = {"PATH": f"{bindir}:/usr/bin:/bin", "FP_VENC": str(venc)}
+    return env
+
+
+def _run_script(tmp_path, env, quality="720p"):
+    script = L.source_command(quality).replace("/sys/class/video4linux", str(tmp_path))
+    return subprocess.Popen(["bash", "-c", script], stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                            stderr=subprocess.PIPE, env=env)
+
+
+@pytest.mark.skipif(not shutil.which("bash"), reason="needs bash")
+def test_source_command_hardware_path(tmp_path):
+    p = _run_script(tmp_path, _fake_tools(tmp_path, fps=32))
+    p.stdin.write(b"k")  # a keyframe request reaches the encoder (here: copied on to ffmpeg)
+    p.stdin.flush()
+    time.sleep(0.5)
+    assert p.poll() is None
+    p.stdin.close()  # the SSH channel closing ends the encoder, then ffmpeg
+    assert p.wait(timeout=5) == 0
+    assert b"live: encoder=hardware fps=32" in p.stderr.read()
+    args = (tmp_path / "ffmpeg.args").read_text()
+    assert "-f h264 -i pipe:0" in args and "-c:v copy" in args and "libx264" not in args
+    assert "-use_wallclock_as_timestamps 1" in args and "nobuffer" not in args  # read in step with pulse's audio
+    assert "setts=ts=N*(1/32)/TB" in args  # output timestamps on fp_venc's 32 fps grid (no bunched frames)
+    assert "-itsoffset -0.25 -f h264 -i pipe:0" in args  # video not "ahead" of pulse, not held for interleaving
+    assert "+frag_keyframe" in args  # a requested keyframe starts a fragment (where a new viewer begins)
+    venc_calls = (tmp_path / "venc.args").read_text().splitlines()
+    assert venc_calls[0].startswith("--probe ") and "--height 720" in venc_calls[0]
+    assert "--bitrate 5000000 --peak 7500000" in venc_calls[0]  # hardware 720p: VBR, 1.5x peak
+    assert "--fps 32" in venc_calls[1] and "--probe" not in venc_calls[1]
+
+
+@pytest.mark.skipif(not shutil.which("bash"), reason="needs bash")
+def test_source_command_full_quality_has_no_height(tmp_path):
+    p = _run_script(tmp_path, _fake_tools(tmp_path), quality="full")
+    p.stdin.close()
+    p.wait(timeout=5)
+    assert "--height" not in (tmp_path / "venc.args").read_text()
+
+
+@pytest.mark.skipif(not shutil.which("bash"), reason="needs bash")
+def test_source_command_falls_back_to_x264(tmp_path):
+    p = _run_script(tmp_path, _fake_tools(tmp_path, probe_exit=4))  # hardware encoder not usable
+    time.sleep(0.5)
+    p.stdin.close()
+    p.wait(timeout=5)
+    assert b"live: encoder=software fps=30" in p.stderr.read()
+    args = (tmp_path / "ffmpeg.args").read_text()
+    assert "libx264" in args and "-f v4l2" in args
+    assert len((tmp_path / "venc.args").read_text().splitlines()) == 1  # only the probe ran
+
+
+def test_bitrate_bps():
+    assert [L.bitrate_bps(r) for _, r in L.QUALITY.values()] == [1_000_000, 1_500_000, 3_000_000, 6_000_000,
+                                                                 10_000_000]
+
+
+def test_relay_viewer_waits_for_requested_keyframe():
+    r = L.Relay()
+    asked = []
+    r.on_join = lambda: asked.append(1) or True
+    r.feed(init_segment() + fragment(True, seq=1) + fragment(False, seq=2))
+    init, gop, q = r.subscribe()
+    assert asked and init == init_segment() and gop == []  # no stale group: the requested keyframe comes next
+    r.feed(fragment(False, seq=3))  # still before the keyframe: not for this viewer
+    r.feed(fragment(True, seq=4) + fragment(False, seq=5))
+    assert q.get_nowait() == fragment(True, seq=4)
+    assert q.get_nowait() == fragment(False, seq=5)
+
+
+def test_relay_without_keyframe_request_sends_gop():
+    r = L.Relay()
+    r.on_join = lambda: False  # x264 path: no way to ask
+    r.feed(init_segment() + fragment(True, seq=1) + fragment(False, seq=2))
+    _, gop, q = r.subscribe()
+    assert gop == [fragment(True, seq=1), fragment(False, seq=2)]
+    r.feed(fragment(False, seq=3))
+    assert q.get_nowait() == fragment(False, seq=3)
+
+
+class _Chan:
+    def __init__(self, data: bytes, err: bytes):
+        self.data, self.err, self.sent = [data, b""], err, b""
+
+    def recv(self, n):
+        return self.data.pop(0) if self.data else b""
+
+    def recv_stderr_ready(self):
+        return bool(self.err)
+
+    def recv_stderr(self, n):
+        out, self.err = self.err[:n], self.err[n:]
+        return out
+
+    def sendall(self, b):
+        self.sent += b
+
+
+def test_frame_source_reads_info_and_errors():
+    src = L.FrameSource(frame=None, quality="720p")
+    src.chan = _Chan(b"mp4", b"live: encoder=hardware fps=36\nfp_venc: stats frames=1\nffmpeg: broken pipe")
+    assert not src.request_keyframe()  # nothing known yet
+    assert src.read(10) == b"mp4"
+    assert src.info == {"encoder": "hardware", "fps": "36"}
+    assert src.request_keyframe() and src.chan.sent == b"k"
+    with pytest.raises(RuntimeError, match="broken pipe"):  # the last stderr line explains the end
+        src.read(10)
+    src = L.FrameSource(frame=None, quality="720p")  # encoder stats only go to the log; an encoder error explains
+    src.chan = _Chan(b"", b"fp_venc: encoder QBUF (OUTPUT) failed, errno 22\nfp_venc: stats frames=9 late=0\n")
+    with pytest.raises(RuntimeError, match="QBUF"):
+        src.read(10)
+
+
+def test_live_stream_status_has_encoder():
+    live = L.LiveStream(lambda: _Source(b""))
+    try:
+        live.source_info = lambda: {"encoder": "hardware", "fps": "32"}
+        st = live.status()
+        assert st["encoder"] == "hardware" and st["fps"] == 32
+    finally:
+        live.server.server_close()
+
+
+class _Frame:
+    home = "/home/steamos"
+
+    def __init__(self, remote_sum: str):
+        self.remote_sum, self.cmds, self.puts = remote_sum, [], []
+
+    def run(self, cmd, **kw):
+        self.cmds.append(cmd)
+        if cmd.startswith("sha256sum"):
+            return 0, f"{self.remote_sum}  x\n" if self.remote_sum else "", ""
+        return 0, "", ""
+
+    def put(self, local, remote, **kw):
+        self.puts.append(remote)
+
+
+def test_ensure_helper_uploads_only_when_different(tmp_path, monkeypatch):
+    import hashlib
+
+    exe = tmp_path / "fp_venc"
+    exe.write_bytes(b"\x7fELF test")
+    monkeypatch.setattr(L, "helper_path", lambda: exe)
+    same = _Frame(hashlib.sha256(exe.read_bytes()).hexdigest())
+    assert L.ensure_helper(same) and not same.puts
+    other = _Frame("0" * 64)
+    assert L.ensure_helper(other)
+    assert len(other.puts) == 1 and other.puts[0].startswith("/home/steamos/.local/share/frameport/bin/fp_venc.new-")
+    assert any("chmod 755" in c and "mv -f" in c and other.puts[0] in c for c in other.cmds)
+    monkeypatch.setattr(L, "helper_path", lambda: None)
+    assert not L.ensure_helper(_Frame(""))  # a build without the helper: software encoder
+
+
+def test_status_text_names_encoder():
+    from frameport.ui.views.live import status_text
+
+    line = status_text({"ready": True, "width": 1280, "height": 720, "fps": 32, "encoder": "hardware",
+                        "bytes": 1000, "seconds": 1, "viewers": 1})
+    assert "32 fps" in line and "hardware encoder" in line
+
+
+def test_window_stats_and_panel_warning():
+    c, w = L.window_stats("fp_venc: stats frames=320 repeats=5 late=0 skipped=0 kbps=4900", {})
+    assert w == {"frames": 320, "dropped": 0, "kbps": 4900, "dropping": False}
+    c, w = L.window_stats("fp_venc: stats frames=528 repeats=140 late=172 skipped=104 kbps=6627", c)
+    assert w["frames"] == 208 and w["dropped"] == 276 and w["dropping"]  # the owner's 1080p run
+    c, w = L.window_stats("fp_venc: stats frames=846 repeats=140 late=176 skipped=104 kbps=6600", c)
+    assert w["dropped"] == 4 and not w["dropping"]  # a few late slots in 10 s: no warning
+    from frameport.ui.views.live import health_text
+
+    assert "lower quality" in health_text({"dropping": True, "dropped": 276})
+    assert health_text({"dropping": False, "dropped": 4}) == "" and health_text({}) == ""
+
+
+class _StopChan:
+    def __init__(self, exits: bool):
+        self.exits, self.closed, self.eof = exits, False, False
+
+    def shutdown_write(self):
+        self.eof = True
+
+    def exit_status_ready(self):
+        return self.exits
+
+    def recv_ready(self):
+        return False
+
+    def recv_stderr_ready(self):
+        return False
+
+    def close(self):
+        self.closed = True
+
+
+def test_stop_kills_a_stuck_stream():
+    """fp_venc blocked in a write never sees stdin EOF: after the grace time its process group is ended."""
+    frame = _Frame("")
+    src = L.FrameSource(frame, "1080p")
+    src.chan, src.info = _StopChan(exits=False), {"pgid": "4321"}
+    src.close(grace=0.1)
+    assert src.chan.eof and src.chan.closed
+    assert any("kill -TERM -- -4321" in c for c in frame.cmds)
+    frame = _Frame("")
+    src = L.FrameSource(frame, "1080p")
+    src.chan, src.info = _StopChan(exits=True), {"pgid": "4321"}
+    src.close(grace=0.1)
+    assert not any("kill" in c for c in frame.cmds)  # stopped by itself: nothing to kill
+
+
+def test_status_has_dropped_frames():
+    live = L.LiveStream(lambda: _Source(b""))
+    try:
+        live.source_info = lambda: {"encoder": "hardware", "fps": "32", "stats": {"dropped": 9, "dropping": True}}
+        st = live.status()
+        assert st["dropped"] == 9 and st["dropping"]
+        live.source_info = lambda: {"encoder": "software", "fps": "30", "stats": {}}
+        assert "dropping" not in live.status()  # x264 path: no stats
+    finally:
+        live.server.server_close()

tests/test_monitor.py

@@ -0,0 +1,239 @@
+"""Monitor client: the `_monitor` line protocol (samples, replies, end of stream) and the pure helpers."""
+import io
+import json
+import queue
+import threading
+import time
+from types import SimpleNamespace
+
+import pytest
+
+from frameport.frame import monitor as M
+
+
+class _Chan:
+    def __init__(self):
+        self.shut = False
+
+    def settimeout(self, t):
+        pass
+
+    def shutdown_write(self):
+        self.shut = True
+
+
+class _In(io.StringIO):
+    def __init__(self, on_line=None):
+        super().__init__()
+        self.channel = _Chan()
+        self.on_line = on_line
+
+    def write(self, s):
+        n = super().write(s)
+        if self.on_line:
+            for line in s.splitlines():
+                self.on_line(json.loads(line))
+        return n
+
+    def close(self):
+        pass
+
+
+class _Out:
+    """stdout of the SSH channel: lines are fed by the test; None ends it, an exception breaks it."""
+
+    def __init__(self):
+        self.q = queue.Queue()
+        self.channel = _Chan()
+
+    def feed(self, obj):
+        self.q.put(obj if obj is None or isinstance(obj, Exception) else json.dumps(obj) + "\n")
+
+    def readline(self):
+        item = self.q.get(timeout=5)
+        return item or ""
+
+    def __iter__(self):
+        while True:
+            item = self.q.get(timeout=5)
+            if item is None:
+                return
+            if isinstance(item, Exception):
+                raise item
+            yield item
+
+
+def _session(ready=None, on_line=None):
+    out = _Out()
+    out.feed(ready if ready is not None else {"ready": 1, "static": {"agent": 60, "cores": 8}})
+    stdin = _In(on_line)
+    client = SimpleNamespace(exec_command=lambda cmd, timeout=None: (stdin, out, None))
+    frame = SimpleNamespace(client=client, home="/home/steamos", ensure_agent=lambda: None)
+    samples, ended = [], []
+    return frame, stdin, out, samples, ended
+
+
+def test_stream_samples_controls_and_close():
+    frame, stdin, out, samples, ended = _session()
+    s = M.MonitorSession(frame, samples.append, ended.append)
+    assert s.static == {"agent": 60, "cores": 8}
+    out.feed({"t": 1, "cpu": {"total": 5}})
+    out.feed("not json")  # ignored
+    out.feed({"t": 2})
+    deadline = time.time() + 5
+    while len(samples) < 2 and time.time() < deadline:
+        time.sleep(0.01)
+    assert [x["t"] for x in samples] == [1, 2]
+    s.set_interval(2)
+    s.set_filter("all")
+    s.pause(True)
+    s.close()
+    out.feed(None)
+    assert [json.loads(x) for x in stdin.getvalue().splitlines()] == [{"interval": 2}, {"procs": "all"},
+                                                                     {"pause": True}]
+    assert stdin.channel.shut and s.closed
+    s._thread.join(5)
+    assert ended == []  # closed by us: no "ended" callback
+    s.set_interval(5)  # after close: ignored
+    assert len(stdin.getvalue().splitlines()) == 3
+
+
+def test_replies_kill_end_game_and_critical():
+    holder = {}
+
+    def answer(msg):  # the "agent": answers each request on stdout
+        out = holder["out"]
+        if msg.get("kill") == 101 and not msg.get("force"):
+            out.feed({"reply": msg["id"], "ok": False, "error": "CRITICAL: vrcompositor"})
+        elif msg.get("kill") == 1:
+            out.feed({"reply": msg["id"], "ok": False, "error": "systemd (1) is part of the system"})
+        elif "kill" in msg:
+            out.feed({"reply": msg["id"], "ok": True, "result": {"ended": True, "pid": msg["kill"],
+                                                                 "sig": msg["sig"], "force": msg["force"]}})
+        elif "end_game" in msg:
+            out.feed({"reply": msg["id"], "ok": True, "result": {"ended": True, "via": "steam"}})
+    frame, stdin, out, samples, ended = _session(on_line=answer)
+    holder["out"] = out
+    s = M.MonitorSession(frame, samples.append, ended.append)
+    assert s.kill(42) == {"ended": True, "pid": 42, "sig": "TERM", "force": False}
+    assert s.kill(101, "KILL", force=True)["force"] is True
+    with pytest.raises(M.ProcessCritical, match="vrcompositor"):
+        s.kill(101)
+    with pytest.raises(RuntimeError, match="part of the system"):
+        s.kill(1)
+    assert s.end_game("com.x.y") == {"ended": True, "via": "steam"}
+    s.close()
+    out.feed(None)
+
+
+def test_stream_lost_calls_on_end_and_unblocks_requests():
+    frame, stdin, out, samples, ended = _session()
+    s = M.MonitorSession(frame, samples.append, ended.append)
+    result = {}
+
+    def ask():
+        try:
+            s.kill(5)
+        except M.MonitorUnavailable as exc:
+            result["err"] = str(exc)
+    t = threading.Thread(target=ask)
+    t.start()
+    time.sleep(0.1)
+    out.feed(OSError("Socket is closed"))
+    t.join(5)
+    s._thread.join(5)
+    assert ended == ["Socket is closed"] and s.closed
+    assert "stopped" in result["err"]
+
+
+def test_refused_by_an_old_agent():
+    frame, *_ = _session(ready={"ok": False, "error": "usage: frameport_agent.py <...>"})
+    with pytest.raises(M.MonitorUnavailable, match="usage"):
+        M.MonitorSession(frame, lambda s: None)
+
+
+def test_history_and_series():
+    h = M.History(size=3)
+    for v in (1, 2, None, 4):
+        h.add("cpu", v)
+    assert h.get("cpu") == [2, None, 4] and h.get("nope") == []
+    s = {"cpu": {"total": 12.5}, "gpu": {"busy": None}, "mem": {"total": 1000, "avail": 250},
+         "temps": {"CPU": 50.0, "GPU": 61.5}, "power": {"system": 6.2}, "battery": {"percent": 80},
+         "games": [{"fps": 71.9}]}
+    assert M.series_of(s) == {"cpu": 12.5, "gpu": None, "mem": 75.0, "temp": 61.5, "power": 6.2, "battery": 80,
+                              "fps": 71.9, "temp:CPU": 50.0, "temp:GPU": 61.5}
+    assert M.series_of({**s, "fan": 8200})["fan"] == 8200
+
+
+def test_history_buckets_by_time():
+    """Several samples within one second become one (averaged) point: 2 minutes of chart at any interval."""
+    h = M.History(size=3)
+    for t, v in ((10.0, 2), (10.5, 4), (11.2, 6), (11.9, None), (12.0, 1), (13.0, 5)):
+        h.add("cpu", v, t)
+    assert h.get("cpu") == [6.0, 1.0, 5.0]  # 10 s = (2+4)/2 rolled out of the 3-point window
+    h.add("x", None, 1.0)
+    assert h.get("x") == [None]
+
+
+def test_group_procs():
+    procs = [{"pid": 1, "ppid": 10, "name": "vrwebhelper", "cpu": 1.0, "gpu": 0, "rss": 5, "age": 30},
+             {"pid": 2, "ppid": 99, "name": "steam", "cpu": 0.8, "gpu": 0, "rss": 9, "age": 50},
+             {"pid": 3, "ppid": 10, "name": "vrwebhelper", "cpu": 0.5, "gpu": 2, "rss": 7, "age": 40,
+              "critical": True},
+             {"pid": 4, "ppid": 11, "name": "vrwebhelper", "cpu": 0.1, "gpu": 0, "rss": 1, "age": 5}]
+    rows = M.group_procs(procs)
+    assert [r["kind"] for r in rows] == ["group", "proc", "proc"]
+    g = rows[0]
+    assert g["name"] == "vrwebhelper" and g["count"] == 2 and g["cpu"] == 1.5 and g["gpu"] == 2 and g["rss"] == 12
+    assert g["age"] == 40 and g["critical"] and not g["expanded"] and rows[2]["pid"] == 4  # other parent: alone
+    rows = M.group_procs(procs, {(10, "vrwebhelper")})
+    assert [(r["kind"], r.get("pid")) for r in rows] == [("group", None), ("member", 1), ("member", 3),
+                                                         ("proc", 2), ("proc", 4)]
+    assert M.fmt_interval(0.25) == "0.25 s" and M.fmt_interval(1) == "1 s" and M.DEFAULT_INTERVAL in M.INTERVALS
+    assert M.series_of({})["fps"] is None and M.series_of({})["mem"] is None
+
+
+def test_formatting():
+    assert M.fmt_bytes(512) == "512 B" and M.fmt_bytes(2048) == "2 KB"
+    assert M.fmt_bytes(5 * 1024 ** 2) == "5.0 MB" and M.fmt_bytes(16 * 1024 ** 3) == "16.0 GB"
+    assert M.fmt_bytes(None) == "–" and M.fmt_rate(2048) == "2 KB/s"
+    assert M.fmt_watts(3.558) == "3.56 W" and M.fmt_watts(12.34) == "12.3 W"
+    assert M.fmt_duration(45) == "45 s" and M.fmt_duration(720) == "12 min" and M.fmt_duration(3900) == "1 h 05 min"
+    assert M.fmt_pct(33.4) == "33 %" and M.fmt_pct(None) == "–"
+
+
+def test_levels():
+    assert M.level("cpu", 50) == "ok" and M.level("cpu", 90) == "warn" and M.level("cpu", 99) == "error"
+    assert M.level("temp", 79.9) == "ok" and M.level("temp", 85) == "warn" and M.level("temp", 90) == "error"
+    assert M.temp_level("Battery", 46) == "warn" and M.temp_level("GPU", 46) == "ok"
+    assert M.level("fps_ratio", 1.0) == "ok" and M.level("fps_ratio", 0.8) == "warn"
+    assert M.level("fps_ratio", 0.5) == "error"
+    assert M.level("unknown", 1e9) == "ok" and M.level("cpu", None) == "ok"
+
+
+def test_sort_filter_and_labels():
+    procs = [{"pid": 1, "name": "steam", "cpu": 5, "rss": 10, "game": None, "gpu": 0},
+             {"pid": 22, "name": "com.game", "cpu": 40, "rss": 5, "game": "com.ex.game", "gpu": 30},
+             {"pid": 3, "name": "Xwayland", "cpu": 5, "rss": 50, "game": None, "gpu": 2}]
+    assert [p["pid"] for p in M.sort_filter(procs)] == [22, 3, 1]
+    assert [p["pid"] for p in M.sort_filter(procs, key="name", descending=False)] == [22, 1, 3]
+    assert [p["pid"] for p in M.sort_filter(procs, "ex.game")] == [22]
+    assert [p["pid"] for p in M.sort_filter(procs, "3")] == [3]  # a PID matches exactly
+    assert M.group_label("game:com.x") == "Game" and M.group_label("steamvr") == "SteamVR"
+    assert M.group_label("other") == "Other"
+
+
+def test_power_split_and_battery_line():
+    split = M.power_split({"system": 6.0, "cpu": 1.5, "gpu": 2.0, "npu": 0.1})
+    assert split == [("CPU", 1.5), ("GPU", 2.0), ("NPU", 0.1), ("Other", pytest.approx(2.4))]
+    assert M.battery_line(None) == "No battery"
+    assert M.battery_line({"status": "Discharging", "draining": True, "empty_s": 7800, "watts": -4.0}) == \
+        "2 h 10 min left · 4.00 W"
+    assert M.battery_line({"status": "Charging", "plugged": True, "full_s": 2100}) == "Charging · full in 35 min"
+    assert M.battery_line({"status": "Full"}) == "Full"
+
+
+def test_fps_target():
+    assert M.fps_target([]) is None and M.fps_target([None]) is None
+    assert M.fps_target([50.0, 71.9, 72.4]) == 72 and M.fps_target([88.0, 90.1]) == 90
+    assert M.fps_target([200]) == 144

tests/test_monitor_agent.py

@@ -0,0 +1,358 @@
+"""The agent's Monitor stream (`_monitor`): readers against a fake /proc + /sys tree, process grouping, kill safety."""
+import io
+import json
+import os
+import subprocess
+import sys
+import threading
+import time
+
+import pytest
+from test_agent import AGENT, load_agent
+
+GAME = "com.example.game"
+APPID = 2541636856
+
+
+def w(path, text):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text)
+
+
+def proc(root, pid, comm, ppid, cpu=0, start=100, rss=1000, cmdline=None, fds=None, cgroup=None):
+    d = root / "proc" / str(pid)
+    stat = f"{pid} ({comm}) S {ppid} 1 1 0 -1 0 0 0 0 0 {cpu} 0 0 0 20 0 1 0 {start} 100000 {rss} 0"
+    w(d / "stat", stat)
+    w(d / "cmdline", "\0".join(cmdline or [comm]) + "\0")
+    w(d / "status", f"Name:\t{comm}\nState:\tS (sleeping)\n")
+    if cgroup:
+        w(d / "cgroup", f"0::{cgroup}\n")
+    (d / "fd").mkdir(parents=True, exist_ok=True)
+    for fd, (target, ns) in (fds or {}).items():
+        os.symlink(target, d / "fd" / str(fd))
+        w(d / "fdinfo" / str(fd), f"pos:\t0\ndrm-driver:\tmsm\ndrm-engine-gpu:\t{ns} ns\ndrm-cycles-gpu:\t0\n")
+
+
+def set_cpu(root, pid, cpu):
+    p = root / "proc" / str(pid) / "stat"
+    f = p.read_text().split(" ")
+    f[13] = str(cpu)  # utime (field 14)
+    p.write_text(" ".join(f))
+
+
+def set_gpu(root, pid, fd, ns):
+    w(root / "proc" / str(pid) / "fdinfo" / str(fd), f"drm-driver:\tmsm\ndrm-engine-gpu:\t{ns} ns\n")
+
+
+def frame_tree(root, home):
+    """A small Frame: 2 clusters, GPU devfreq, thermal zones, power rails, fan, battery, one running Quest game."""
+    p = root / "proc"
+    w(p / "stat", "cpu  100 0 100 800 0 0 0 0 0 0\ncpu0 50 0 50 400 0 0 0 0 0 0\n"
+                  "cpu1 50 0 50 400 0 0 0 0 0 0\nintr 1\nbtime 1000\n")
+    w(p / "meminfo", "MemTotal:       16000000 kB\nMemFree:  1 kB\nMemAvailable:    8000000 kB\n"
+                     "SwapTotal:       8000000 kB\nSwapFree:        7000000 kB\n")
+    for k in ("cpu", "memory", "io"):
+        w(p / "pressure" / k, "some avg10=2.50 avg60=1.00 avg300=0.00 total=1\n"
+                              "full avg10=0.00 avg60=0 avg300=0 total=0\n")
+    w(p / "net" / "dev", "Inter-|   Receive\n face |bytes\n    lo: 5 0 0 0 0 0 0 0 5 0 0 0 0 0 0 0\n"
+                         "  wlan0: 1000 0 0 0 0 0 0 0 2000 0 0 0 0 0 0 0\n")
+    s = root / "sys"
+    for i, (cpus, mx, cur) in enumerate((("0", 2265600, 1248000), ("1", 3148800, 1708800))):
+        d = s / "devices/system/cpu/cpufreq" / f"policy{i}"
+        w(d / "related_cpus", cpus + "\n")
+        w(d / "cpuinfo_max_freq", f"{mx}\n")
+        w(d / "scaling_cur_freq", f"{cur}\n")
+    g = s / "class/devfreq/3d00000.gpu"
+    w(g / "name", "3d00000.gpu\n")
+    w(g / "cur_freq", "231000000\n")
+    w(g / "max_freq", "903000000\n")
+    w(s / "class/devfreq/1d84000.ufshc/name", "1d84000.ufshc\n")
+    for i, (kind, mc) in enumerate((("cpu0-thermal", 41000), ("cpu7-top-thermal", 52500), ("gpuss-0-thermal", 47000),
+                                    ("max1720x_bat_7-36", 23200), ("aoss0-thermal", 30000))):
+        w(s / f"class/thermal/thermal_zone{i}/type", kind + "\n")
+        w(s / f"class/thermal/thermal_zone{i}/temp", f"{mc}\n")
+    h = s / "class/hwmon/hwmon51"
+    for i, (label, uw) in enumerate((("apc0", 500000), ("apc1", 250000), ("gfx", 1500000), ("vph", 6000000),
+                                     ("unused", 8), ("bob", 160000)), 1):
+        w(h / f"power{i}_label", label + "\n")
+        w(h / f"power{i}_input", f"{uw}\n")
+    w(s / "class/hwmon/hwmon50/fan1_input", "8200\n")
+    b = root / "power_supply/max1720x_bat_7-36"
+    for k, v in {"type": "Battery", "capacity": "80", "status": "Discharging", "current_now": "-500000",
+                 "voltage_now": "8000000", "time_to_empty_now": "7200", "cycle_count": "7", "temp": "233",
+                 "health": "Good", "charge_full": "2698000", "charge_full_design": "2730000"}.items():
+        w(b / k, v + "\n")
+    w(root / "power_supply/usb/type", "USB\n")
+    w(root / "power_supply/usb/online", "0\n")
+    cg = s / "fs/cgroup/user.slice/libpod-abc.scope"
+    w(cg / "memory.current", "2000000000\n")
+    w(cg / "cpu.stat", "usage_usec 1000000\n")
+    w(s / "fs/cgroup/user.slice/app.slice/memory.current", "1\n")
+    # a Quest game: launch.sh (Steam's reaper) + the podman container (conmon → Android init → the game)
+    base = home / "Applications/quest-frame" / GAME
+    w(base / "deployment.json", json.dumps({"package": GAME, "appid": APPID, "title": "Example Game",
+                                            "kind": "quest"}))
+    w(base / "launch.log", "x\n10-07 02:00:14.554  1183  1212 I FrameBridge: pacing: 71.9 fps, displayTime vs "
+                           "predicted: avg 0.10 ms, max 0.00 ms\n")
+    proc(root, 1, "systemd", 0)
+    proc(root, 2, "kthreadd", 0)
+    proc(root, 3, "kworker/0:0", 2)
+    proc(root, 100, "steam", 1, cpu=10, fds={5: ("/dev/dri/renderD128", 0)})
+    proc(root, 101, "vrcompositor", 1, fds={7: ("/dev/dri/renderD128", 1000), 9: ("/dev/dri/renderD128", 0)})
+    launcher = str(home / "Applications/quest-frame" / GAME / "launch.sh")
+    proc(root, 200, "launch.sh", 100, cmdline=["/bin/bash", launcher])
+    proc(root, 300, "conmon", 1, cmdline=["/usr/bin/conmon", "-n", f"lepton-steamlaunch-{APPID}"],
+         cgroup="/user.slice/app.slice")
+    proc(root, 301, "init", 300, cgroup="/user.slice/libpod-abc.scope/container")
+    # Android names its processes after the package's last 15 characters (the kernel's comm limit)
+    proc(root, 302, "lus4xvrplayerov", 301, cpu=50, fds={3: ("/dev/kgsl-3d0", 5000)},
+         cgroup="/user.slice/libpod-abc.scope/container", cmdline=["cn.vr4p.oculus4xvrplayerov"])
+    proc(root, 400, "bash", 1, cmdline=["bash", "-c", "sleep 9"])
+    return base
+
+
+@pytest.fixture
+def fa(monkeypatch, tmp_path):
+    """The agent with PROC/SYS/POWER_SUPPLY pointing at a fake Frame."""
+    home = tmp_path / "home"
+    home.mkdir()
+    a = load_agent(monkeypatch, home)
+    root = tmp_path / "frame"
+    frame_tree(root, home)
+    monkeypatch.setattr(a, "PROC", str(root / "proc"))
+    monkeypatch.setattr(a, "SYS", str(root / "sys"))
+    monkeypatch.setattr(a, "POWER_SUPPLY", str(root / "power_supply"))
+    a.ROOT = root
+    return a
+
+
+def monitor(fa):
+    clock = {"t": 100.0}
+    m = fa.Monitor(clock=lambda: clock["t"])
+    return m, clock
+
+
+def test_static_and_readers(fa):
+    m, _ = monitor(fa)
+    st = m.static()
+    assert st["agent"] == fa.AGENT_VERSION and st["cores"] == 2 and st["gpu_max_mhz"] == 903
+    assert st["clusters"] == [{"cpus": [0], "max_mhz": 2265}, {"cpus": [1], "max_mhz": 3148}]
+    assert st["rails"] == ["apc0", "apc1", "gfx", "vph"]  # "unused"/"bob" aren't read (each read is an I2C transfer)
+    assert st["temp_groups"] == ["CPU", "GPU", "Battery"] and st["fan"] is True
+    s = m.sample(wall=2000.0)
+    assert s["temps"] == {"CPU": 52.5, "GPU": 47.0, "Battery": 23.2}
+    assert s["zones"]["CPU"] == {"cpu0": 41.0, "cpu7-top": 52.5}
+    assert s["power"]["system"] == 6.0 and s["power"]["cpu"] == 0.75 and s["power"]["gpu"] == 1.5
+    assert s["fan"] == 8200 and s["cpu"]["mhz"] == [1248, 1708]
+    assert s["mem"] == {"total": 16000000 * 1024, "avail": 8000000 * 1024, "swap_total": 8000000 * 1024,
+                        "swap_free": 7000000 * 1024}
+    assert s["psi"] == {"cpu": 2.5, "memory": 2.5, "io": 2.5}
+    b = s["battery"]
+    assert b["percent"] == 80 and b["watts"] == -4.0 and b["draining"] and not b["plugged"]
+    assert b["empty_s"] == 7200 and b["cycles"] == 7 and b["temp"] == 23.3 and b["health"] == "Good"
+    assert s["gpu"] == {"busy": None, "mhz": 231}  # no delta yet
+    assert "disk" in s and s["self_ms"] >= 0
+
+
+def test_cpu_gpu_net_deltas(fa):
+    m, clock = monitor(fa)
+    m.sample(wall=2000.0)
+    p = fa.ROOT / "proc"
+    w(p / "stat", "cpu  200 0 100 900 0 0 0 0 0 0\ncpu0 100 0 50 450 0 0 0 0 0 0\n"
+                  "cpu1 100 0 50 450 0 0 0 0 0 0\nbtime 1000\n")
+    w(p / "net" / "dev", "a\nb\n  wlan0: 3000 0 0 0 0 0 0 0 2500 0 0 0 0 0 0 0\n")
+    set_gpu(fa.ROOT, 302, 3, 5000 + 250_000_000)   # 25 % of 1 s
+    set_gpu(fa.ROOT, 101, 7, 1000 + 100_000_000)   # 10 %
+    clock["t"] += 1.0
+    s = m.sample(wall=2001.0)
+    assert s["cpu"]["total"] == 50.0 and s["cpu"]["cores"] == [50.0, 50.0]
+    assert s["net"] == {"wlan0": [2000, 500]}
+    assert s["gpu"]["busy"] == 35.0
+
+
+def test_processes_games_and_filters(fa):
+    m, clock = monitor(fa)
+    s = m.sample(wall=2000.0)
+    names = {p["pid"]: p for p in m.procs}
+    assert 3 not in names and 2 not in names  # kernel threads
+    assert {names[pid]["game"] for pid in (200, 300, 301, 302)} == {GAME}
+    assert names[100]["group"] == "steam" and names[101]["group"] == "steamvr" and names[400]["group"] == "other"
+    assert names[302]["name"] == "cn.vr4p.oculus4xvrplayerov"  # the full name, not the truncated comm
+    assert names[101]["critical"] and names[1]["locked"]
+    # default filter: the game's processes + the busiest others as context
+    shown = s["procs"]
+    assert s["filter"] == "game"
+    assert {p["pid"] for p in shown if p["game"]} == {200, 300, 301, 302}
+    assert all(p.get("context") for p in shown if not p["game"]) and len([p for p in shown if not p["game"]]) == 3
+    m.filter = "steam"
+    assert {p["pid"] for p in m.filtered()} == {100, 101}
+    m.filter = "all"
+    assert len(m.filtered()) == len(m.procs)
+    # game card: fps from the pacing line, memory from the container's cgroup (not conmon's), process count
+    g = s["games"][0]
+    assert g["package"] == GAME and g["title"] == "Example Game" and g["appid"] == APPID
+    assert g["fps"] == 71.9 and g["frame_ms"] == 0.1 and g["mem"] == 2000000000 and g["processes"] == 4
+    # next scan: CPU % per process + the container cgroup's CPU %
+    set_cpu(fa.ROOT, 302, 50 + 100)  # 100 jiffies in 1 s = 1 core of 2 → 50 %
+    clock["t"] += 1.0
+    m.sample(wall=2001.0)  # odd tick: no process scan (GPU and container CPU % are still per tick)
+    set_gpu(fa.ROOT, 302, 3, 5000 + 250_000_000)
+    w(fa.ROOT / "sys/fs/cgroup/user.slice/libpod-abc.scope/cpu.stat", "usage_usec 1500000\n")  # 0.5 s of 2 cores
+    clock["t"] += 1.0
+    s = m.sample(wall=2002.0)
+    game = next(p for p in s["procs"] if p["pid"] == 302)
+    # the table averages GPU over the 2 s since the last scan (250 ms busy); the game card shows the last tick
+    assert game["cpu"] == 25.0 and game["gpu"] == 12.5
+    assert s["games"][0]["cpu"] == 25.0 and s["games"][0]["gpu"] == 25.0
+
+
+def test_pacing_tail_is_incremental_and_goes_stale(fa):
+    m, clock = monitor(fa)
+    base = str(fa.ROOT.parent / "home/Applications/quest-frame" / GAME)
+    assert m.fps(base, 100.0) == (71.9, 0.1)
+    with open(os.path.join(base, "launch.log"), "a") as f:
+        f.write("I FrameBridge: pacing: 45.0 fps, displayTime vs predicted: avg 2.00 ms, max 0.00 ms\n")
+    assert m.fps(base, 101.0) == (45.0, 2.0)
+    assert m.fps(base, 120.0) == (None, None)  # no line for 15 s: loading or ended
+    open(os.path.join(base, "launch.log"), "w").write("I FrameBridge: pacing: 72.0 fps\n")  # a new launch
+    assert m.fps(base, 121.0) == (72.0, None)
+
+
+def test_kill_safety(fa):
+    m, _ = monitor(fa)
+    m.sample(wall=2000.0)
+    with pytest.raises(fa.AgentError, match="system"):
+        m.kill(1)
+    with pytest.raises(fa.AgentError, match="CRITICAL: vrcompositor"):
+        m.kill(101)
+    assert m.kill(999) == {"ended": True, "pid": 999, "note": "already gone"}
+
+
+def test_kill_other_user_only_inside_a_game(fa, monkeypatch):
+    m = fa.Monitor(uid=12345)  # nothing in the fake tree belongs to this user
+    m.sample(wall=2000.0)
+    with pytest.raises(fa.AgentError, match="another user"):
+        m.kill(400)
+
+
+def test_kill_real_process(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    m = a.Monitor()
+    with pytest.raises(a.AgentError):
+        m.kill(os.getpid())  # its own process tree (the SSH session) is never ended
+    child = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(30)"])
+    try:
+        res = m.kill(child.pid, "TERM")
+        assert res["ended"] is True and res["pid"] == child.pid
+    finally:
+        child.kill()
+        child.wait()
+
+
+def test_end_game_steam_then_stop(fa, monkeypatch):
+    calls, state = [], {"running": True}
+    monkeypatch.setattr(fa, "devkit_gameid", lambda pkg: None)
+    monkeypatch.setattr(fa, "container_running", lambda appid: state["running"])
+    monkeypatch.setattr(fa, "steam_js", lambda expr, timeout=5: calls.append(expr))
+
+    def stop(args):
+        calls.append(("stop", args["package"]))
+        state["running"] = False
+        return {"stopped": True}
+    monkeypatch.setattr(fa, "cmd_stop", stop)
+    res = fa.monitor_end_game(GAME, wait=0.2)
+    assert calls[0] == f"SteamClient.Apps.TerminateApp('{fa.steam_gameid(APPID)}', false)"
+    assert calls[1] == ("stop", GAME) and res == {"ended": True, "via": "stop", "package": GAME}
+    # Steam's Exit game was enough: no podman kill
+    calls.clear()
+    monkeypatch.setattr(fa, "steam_js", lambda expr, timeout=5: state.update(running=False))
+    state["running"] = True
+    assert fa.monitor_end_game(GAME, wait=0.2)["via"] == "steam"
+    state["running"] = False  # already gone: nothing is sent to Steam
+    assert fa.monitor_end_game(GAME, wait=0.2) == {"ended": True, "via": None, "package": GAME, "note": "not running"}
+    with pytest.raises(fa.AgentError, match="bad package"):
+        fa.monitor_end_game("x y")
+
+
+class FakeMon:
+    def __init__(self):
+        self.filter, self.n = "game", 0
+
+    def static(self):
+        return {"agent": 60}
+
+    def sample(self):
+        self.n += 1
+        return {"n": self.n, "filter": self.filter}
+
+    def kill(self, pid, sig="TERM", force=False):
+        if pid == 1:
+            raise RuntimeError("nope")
+        return {"ended": True, "pid": pid, "sig": sig, "force": force}
+
+
+def test_session_protocol(fa):
+    r, wfd = os.pipe()
+    stdin, writer = os.fdopen(r), os.fdopen(wfd, "w")
+    out = io.StringIO()
+    mon = FakeMon()
+    t = threading.Thread(target=fa.monitor_session, args=(stdin, out, mon), daemon=True)
+    t.start()
+
+    def lines():
+        return [json.loads(x) for x in out.getvalue().splitlines()]
+    writer.write(json.dumps({"procs": "all"}) + "\n" + json.dumps({"interval": 5}) + "\n"
+                 + json.dumps({"id": 7, "kill": 42, "sig": "KILL", "force": True}) + "\n"
+                 + json.dumps({"id": 8, "kill": 1}) + "\n" + "not json\n")
+    writer.flush()
+    deadline = time.time() + 5
+    while time.time() < deadline and len([x for x in lines() if "reply" in x]) < 2:
+        time.sleep(0.02)
+    writer.close()  # EOF ends the session
+    t.join(5)
+    assert not t.is_alive()
+    got = lines()
+    assert got[0] == {"ready": 1, "static": {"agent": 60}}
+    assert mon.filter == "all"
+    replies = {x["reply"]: x for x in got if "reply" in x}
+    assert replies[7] == {"reply": 7, "ok": True, "result": {"ended": True, "pid": 42, "sig": "KILL", "force": True}}
+    assert replies[8]["ok"] is False and "nope" in replies[8]["error"]
+    assert any(x.get("filter") == "all" for x in got if "n" in x)  # a fresh sample after the filter change
+
+
+def test_monitor_cli_ends_at_eof(tmp_path):
+    """`_monitor` on the real machine: ready line, a sample, and exit once stdin closes."""
+    p = subprocess.Popen([sys.executable, str(AGENT), "_monitor"], stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                         text=True, env={"HOME": str(tmp_path), "PATH": "/usr/bin:/bin"})
+    ready = json.loads(p.stdout.readline())
+    sample = json.loads(p.stdout.readline())
+    p.stdin.close()
+    assert p.wait(timeout=10) == 0
+    assert ready["ready"] == 1 and ready["static"]["cores"] >= 1
+    assert "cpu" in sample and "mem" in sample and "procs" in sample
+
+
+def test_power_cluster_rails_every_5_s(fa):
+    """System + GPU rails every tick; the CPU cluster rails (I2C reads) every 5 s."""
+    m, clock = monitor(fa)
+    assert m.sample(wall=2000.0)["power"]["cpu"] == 0.75
+    h = fa.ROOT / "sys/class/hwmon/hwmon51"
+    w(h / "power1_input", "1500000\n")  # apc0
+    w(h / "power4_input", "9000000\n")  # vph
+    clock["t"] += 1.0
+    s = m.sample(wall=2001.0)
+    assert s["power"]["system"] == 9.0 and s["power"]["cpu"] == 0.75
+    clock["t"] += 4.0
+    assert m.sample(wall=2005.0)["power"]["cpu"] == 1.75
+
+
+def test_fast_ticks_scan_processes_every_2_s(fa):
+    """At 0.1-0.5 s intervals the sensors are read every tick but processes only every 2 s (the expensive part)."""
+    m, clock = monitor(fa)
+    assert "procs" in m.sample(wall=2000.0)
+    seen = []
+    for _ in range(8):
+        clock["t"] += 0.25
+        seen.append("procs" in m.sample(wall=2000.0 + clock["t"] - 100.0))
+    assert seen == [False] * 7 + [True]
+    assert 0.1 in fa.MON_INTERVALS and fa.MON_DEFAULT_INTERVAL == 0.5

tests/test_patches.py

@@ -156,7 +156,6 @@ def test_per_game_session_settings_are_off_unless_selected():
         assert patch.detect(_analysis()) is None
 
 
-
 def test_vk_hide_fdm_is_a_per_game_unreal_setting():
     """Metro Awakening: Unreal's Vulkan isn't always detected, so it's offered for every Unreal game; off by default."""
     from frameport.patches.settings import UI
@@ -166,6 +165,17 @@ def test_vk_hide_fdm_is_a_per_game_unreal_setting():
     assert not patch.applies(_analysis(engine="Unity"))
     assert "vk_hide_fdm" not in adapter_settings({}) and UI["vk_hide_fdm"]["group"] == "troubleshooting"
 
+
+def test_input_diag_is_an_off_by_default_diagnostic():
+    from frameport.patches.settings import UI
+
+    patch = base.get("adapter.input_diag")
+    assert patch.default == 0 and patch.applies(_analysis()) and patch.detect(_analysis()) is None
+    assert "input_diag" not in adapter_settings({})  # existing builds are unchanged
+    assert adapter_settings({"adapter.input_diag": {"value": 1}})["input_diag"] == 1
+    assert UI["input_diag"]["group"] == "troubleshooting" and UI["input_diag"]["level"] == "advanced"
+
+
 def test_detect_direct_vrapi_suggests_bridge_and_shim():
     a = _analysis(xr="VrApi", direct_vrapi=True, uses_glad_gl=True, graphics="GLES or unknown", package="x.y.unknown")
     from frameport.recommend import engine
@@ -479,7 +489,7 @@ def test_an_already_converted_apk_is_not_converted_again(tmp_path, monkeypatch):
     used = []
     monkeypatch.setattr(build.overport_tool, "patch", lambda *a, **k: (_ for _ in ()).throw(AssertionError("OVRPort")))
     monkeypatch.setattr(build, "apply_frame_fixes",
-                        lambda src, out, *a: (used.append(src.read_bytes()), out.write_bytes(b"u"), ([], []))[2])
+                        lambda src, out, *a: (used.append(src.read_bytes()), out.write_bytes(b"u"), ([], [], {}))[2])
     monkeypatch.setattr(build.sign, "sign", lambda src, dst, pkg: dst.write_bytes(b"signed"))
     monkeypatch.setattr(build, "check_apk", lambda *a, **k: [])
     analysis = _analysis(package="com.x", is_overport_output=True)

tests/test_quest_dump.py

@@ -0,0 +1,140 @@
+"""Finding Quest games and their data (OBB) folders on disk (sources/quest_dump.py)."""
+import zipfile
+from pathlib import Path
+
+import pytest
+
+from frameport.sources import quest_dump
+
+
+@pytest.fixture(autouse=True)
+def package_from_file_name(monkeypatch):
+    monkeypatch.setattr(quest_dump, "_package_of", lambda apk: Path(apk).stem.split("_")[0])
+
+
+def apk(path: Path) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(path, "w") as z:
+        z.writestr("AndroidManifest.xml", b"x")
+    return path
+
+
+def obb(folder: Path, name: str = "main.1.com.x.game.obb") -> Path:
+    folder.mkdir(parents=True, exist_ok=True)
+    (folder / name).write_bytes(b"o")
+    return folder
+
+
+def test_existing_layouts(tmp_path):
+    a = tmp_path / "Game A v1 -TAG"
+    apk(a / "com.x.game.apk")
+    obb(a / "com.x.game")
+    g = quest_dump.from_path(a)
+    assert (g.name, g.data_dir, g.origin) == ("Game A v1", a / "com.x.game", a)
+    b = tmp_path / "patched"
+    apk(b / "com.x.game.apk")
+    obb(b / "obb")
+    assert quest_dump.from_path(b).data_dir == b / "obb"
+    assert quest_dump.from_path(b / "com.x.game.apk").data_dir == b / "obb"  # a single APK file
+    c = tmp_path / "no data"
+    apk(c / "com.x.game.apk")
+    assert quest_dump.from_path(c).data_dir is None
+
+
+@pytest.mark.parametrize("data", ["obb/com.x.game", "OBB/com.x.game", "obbs/com.x.game", "Android/obb/com.x.game",
+                                  "backup/com.x.game"])
+def test_package_folder_below_the_apk(tmp_path, data):
+    """The data folder is the one holding the .obb files (its contents go to Android/obb/<package>/)."""
+    game = tmp_path / "Game"
+    apk(game / "com.x.game.apk")
+    obb(game / data)
+    found = quest_dump.scan(tmp_path)
+    assert len(found) == 1 and found[0].data_dir == game / data and found[0].name == "Game"
+
+
+@pytest.mark.parametrize("apk_folder", ["apk", "APKs"])
+def test_sidequest_style_backup_is_one_game(tmp_path, apk_folder):
+    game = tmp_path / "Backups" / "Some Game"
+    apk(game / apk_folder / "com.x.game.apk")
+    obb(game / "obb" / "com.x.game")
+    found = quest_dump.scan(tmp_path / "Backups")
+    assert len(found) == 1
+    g = found[0]
+    assert (g.name, g.origin, g.data_dir) == ("Some Game", game, game / "obb" / "com.x.game")
+    assert quest_dump.from_path(g.apk).data_dir == game / "obb" / "com.x.game"  # the APK file alone too
+
+
+def test_other_games_obb_is_never_taken(tmp_path):
+    """A neighbouring folder with its own APK is another game (e.g. another version): its data stays its own."""
+    v1, v2 = tmp_path / "Game v1", tmp_path / "Game v2"
+    apk(v1 / "com.x.game.apk")
+    apk(v2 / "com.x.game.apk")
+    obb(v2 / "data" / "com.x.game")
+    found = {g.origin.name: g for g in quest_dump.scan(tmp_path)}
+    assert found["Game v1"].data_dir is None
+    assert found["Game v2"].data_dir == v2 / "data" / "com.x.game"
+
+
+def test_package_folder_without_obb_files_is_ignored_when_searched(tmp_path):
+    game = tmp_path / "Game"
+    apk(game / "apk" / "com.x.game.apk")
+    (game / "saves" / "com.x.game").mkdir(parents=True)
+    (game / "saves" / "com.x.game" / "save.dat").write_bytes(b"s")
+    assert quest_dump.from_path(game / "apk").data_dir is None
+
+
+# ------------------------------------------------------------------ a game that expects an OBB (GitHub #85)
+def test_expects_obb_from_unreals_manifest_flag():
+    from frameport.analysis.detect import expects_obb
+
+    assert expects_obb({"com.epicgames.ue4.GameActivity.bHasOBBFiles": True})
+    assert expects_obb({"com.epicgames.unreal.GameActivity.bHasOBBFiles": "true"})  # UE5's name
+    assert not expects_obb({"com.epicgames.ue4.GameActivity.bHasOBBFiles": False})
+    assert not expects_obb({"com.epicgames.ue4.GameActivity.bVerifyOBBOnStartUp": True})
+
+
+def test_analysis_reads_the_obb_flag(tmp_path):
+    from conftest import build_axml
+
+    from frameport.analysis.detect import analyze
+
+    manifest = build_axml([
+        ("start", "manifest", [("package", "str", "com.x.game")]),
+        ("start", "application", []),
+        ("start", "meta-data", [("name", "str", "com.epicgames.ue4.GameActivity.bHasOBBFiles"),
+                                ("value", "bool", True)]),
+        ("end", "meta-data"),
+        ("end", "application"),
+        ("end", "manifest"),
+    ])
+    p = tmp_path / "game.apk"
+    with zipfile.ZipFile(p, "w") as z:
+        z.writestr("AndroidManifest.xml", manifest)
+    assert analyze(p).extra["expects_obb"] is True
+
+
+def _entry(**kw):
+    e = {"package": "com.x.game", "analysis": {"extra": {"expects_obb": True}}, "data_dir": None, "data_bytes": 0}
+    e.update(kw)
+    return e
+
+
+def test_missing_obb_is_flagged_before_install_and_in_launch_tests():
+    from frameport import pipeline
+    from frameport.validate.triage import TriageResult, add_missing_obb
+
+    assert pipeline.missing_obb(_entry())
+    assert not pipeline.missing_obb(_entry(data_dir="/games/x/com.x.game", data_bytes=10))
+    assert not pipeline.missing_obb(_entry(data_dir="/games/x/com.x.game", data_bytes=None))  # older entries
+    assert not pipeline.missing_obb(_entry(analysis={"extra": {"expects_obb": False}}))
+    assert not pipeline.missing_obb(_entry(kind="rift"))
+    from test_patches import _analysis
+
+    analysis = _analysis(package="com.x.game", engine="Unreal", extra={"size": 1, "expects_obb": True}).to_dict()
+    [note] = pipeline.analysis_warnings(_entry(analysis=analysis))
+    assert "folder named com.x.game" in note and "hangs at start" in note
+    # the launch test: the game logs nothing about it, so the finding comes from the library
+    r = add_missing_obb(TriageResult("RUNNING", "Lepton started"))
+    assert [f.id for f in r.findings] == ["missing-obb"] and r.verdict == "fail"
+    running = TriageResult("RUNNING", "Submitting frames", fps=72.0)  # an OBB from an earlier install is there
+    assert not add_missing_obb(running).findings and running.verdict == "pass"

tests/test_triage.py

@@ -77,6 +77,17 @@ def test_rejected_controller_profile_is_information_only():
     assert triage(log, "RUNNING", "com.example.game").verdict == "pass"
 
 
+def test_failed_input_call_logged_by_input_diag():
+    log = LOG_OK + ("09-28 17:39:02.400  1147  1174 I FrameBridge: input_diag: unsupported: xrCreateAction -> "
+                    "XR_ERROR_NAME_INVALID (trigger pull)\n")
+    r = triage(log, "RUNNING", "com.example.game")
+    f = {x.id: x for x in r.findings}
+    assert f["input-call-failed"].severity == "warning" and r.verdict == "pass"
+    accepted = LOG_OK + ("09-28 17:39:02.400  1147  1174 I FrameBridge: input_diag: bindings: "
+                         "/interaction_profiles/oculus/touch_controller accepted (30 paths)\n")
+    assert "input-call-failed" not in {x.id for x in triage(accepted, "RUNNING", "com.example.game").findings}
+
+
 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
@@ -144,3 +155,35 @@ def test_avatar_driver_missing():
            "driver (-1)!\n10-06 18:42:51.351  1130  1158 F OVRAvatar-Loader: DisplayErrorAndExit: Failed to launch "
            "SystemActivities\n")
     assert triage(log, "EXITED", "ru.targem.blazerush").suggestions() == ["frame.avatar_stub"]
+
+
+def test_x86_linux_program_without_fex():
+    from frameport.validate import triage
+
+    log = "launch.sh: line 20: /home/steamos/Applications/quest-frame/linux.x/app/x: cannot execute binary file: " \
+          "Exec format error\n"
+    assert "linux-x86-no-fex" in [f.id for f in triage.triage(log).findings]
+
+
+def test_android_too_new_signatures():
+    """GitHub #71 (XTADIUM) and #72 (NBA): minSdk 34 apps on Lepton's Android 11."""
+    for line in (
+        "10-06 20:11:02.123  4211  4211 E AndroidRuntime: java.lang.NoClassDefFoundError: Failed resolution of: "
+        "Landroid/window/OnBackInvokedCallback;",
+        "10-06 20:11:02.123  4211  4230 E AndroidRuntime: java.lang.NoSuchMethodError: No static method "
+        "storeStoreFence()V in class Ljava/lang/invoke/VarHandle; or its super classes",
+    ):
+        r = triage(line + "\n", "EXITED")
+        assert [f.id for f in r.findings] == ["android-too-new"] and r.verdict == "fail"
+    assert not triage("E AndroidRuntime: java.lang.NoClassDefFoundError: Lcom/example/Foo;\n", "EXITED").findings
+
+
+def test_web_wrapper_signature():
+    """GitHub #86 (Mahjong Table VR): a TWA looking for Meta's browser."""
+    log = ("10-06 18:02:11.100  3301  3301 D TWALauncherActivity: Using URL from Manifest "
+           "(https://mahjong-vr.pages.dev/).\n"
+           "10-06 18:02:11.120  3301  3301 D TwaLauncher: Creating TwaLauncher for com.oculus.browser\n"
+           "10-06 18:02:11.130  3301  3301 W PackageIdentity: android.content.pm.PackageManager$"
+           "NameNotFoundException: com.oculus.browser\n")
+    r = triage(log, "EXITED")
+    assert {f.id for f in r.findings} == {"web-wrapper"} and r.verdict == "fail"

tests/test_ui_state.py

@@ -174,6 +174,23 @@ def test_install_state_tracks_patch_settings():
     assert C.install_state(g, {"installed": []}) == "missing"
 
 
+def test_game_on_a_missing_sd_card_is_still_installed():
+    """GitHub #90: a game whose microSD card is out has no files to see, but it is installed (not "Not installed")."""
+    from frameport.ui import components as C
+
+    sd = {"internal": False, "path": "/run/media/steamos/SD", "label": "SD"}
+    gone = frame({"package": "com.x", "sha256": "a", "apk_present": False, "drive": sd, "drive_missing": True})
+    assert install_state(game("a"), gone) == "installed"
+    assert C.drive_note(C.frame_drive(game("a"), gone)) == " · SD not inserted"
+    here = frame({"package": "com.x", "sha256": "a", "apk_present": True, "drive": sd, "drive_missing": False})
+    assert C.drive_note(C.frame_drive(game("a"), here)) == " · on SD"
+    internal = frame({"package": "com.x", "sha256": "a", "drive": {"internal": True, "path": "/home/steamos",
+                                                                     "label": "Internal storage"}})
+    assert C.drive_note(C.frame_drive(game("a"), internal)) == ""
+    assert C.frame_drive(game("a"), frame({"package": "com.x"})) is None  # an agent before v63
+    assert install_state(game("a"), frame({"package": "com.x", "sha256": "a", "apk_present": False})) == "missing"
+
+
 def test_library_writes_from_many_threads_are_not_lost():
     """Every thread's change survives (library.json read-modify-write used to race between jobs and the UI)."""
     import threading

tests/test_upstream.py

@@ -0,0 +1,145 @@
+"""Upstream fixes replacing our workarounds per build (patches/upstream.py)."""
+import struct
+import zipfile
+from pathlib import Path
+
+import pytest
+
+from frameport import build
+from frameport.core.events import Reporter
+from frameport.core.models import Analysis, Recipe
+from frameport.patches import base, upstream
+from frameport.patches.frame.haptic_envelope import envelope_duration_fixed
+from frameport.patches.frame.ovr_microphone import microphone_checked
+
+FIXTURES = Path(__file__).with_name("fixtures")
+OLD = (FIXTURES / "libfakeruntime_old_arm64.so").read_bytes()  # OVRPort runtime 3.4.3-23204ea's code
+FIXED = (FIXTURES / "libfakeruntime_fixed_arm64.so").read_bytes()  # 3.4.3-aa54c3f's
+
+
+class FakeWs:
+    abi = "arm64-v8a"
+
+    def __init__(self, libs):
+        self.libs = libs
+
+    def lib(self, name):
+        return f"lib/{self.abi}/{name}"
+
+    def has(self, path):
+        return path.rsplit("/", 1)[-1] in self.libs
+
+    def read_lib(self, name):
+        return self.libs[name]
+
+
+class Log(Reporter):
+    def __init__(self):
+        super().__init__()
+        self.lines = []
+
+    def log(self, msg, *a, **k):
+        self.lines.append(msg)
+
+
+@pytest.fixture
+def temp_fix():
+    added = []
+
+    def add(**kw):
+        fix = upstream.register(upstream.UpstreamFix(**{"title": "t", "upstream": "u", **kw}))
+        added.append(fix.id)
+        return fix
+
+    yield add
+    for fid in added:
+        upstream.REGISTRY.pop(fid, None)
+
+
+def test_move_wide_constants():
+    # mov x8, #0xcd6500000000 ; movk x8, #0x41cd, lsl #48  (1e9 as a double)
+    words = [0xD2800000 | 2 << 21 | 0xCD65 << 5 | 8, 0xF2800000 | 3 << 21 | 0x41CD << 5 | 8]
+    assert struct.pack("<Q", upstream.constants(words)[-1]) == struct.pack("<d", 1e9)
+    assert upstream.move_wide(0xD503201F) is None  # nop
+    # mov w9, #0x6dc9 ; nop ; movk w9, #0x3b9d, lsl #16
+    words = [0x52800000 | 0x6DC9 << 5 | 9, 0xD503201F, 0x72A00000 | 0x3B9D << 5 | 9]
+    assert upstream.find_constant_load(words, 1000173001) == 0
+    assert upstream.find_constant_load(words[1:], 1000173001) is None  # the movk alone isn't a load
+
+
+def test_haptic_probe_tells_old_and_fixed_runtime_apart():
+    assert envelope_duration_fixed(OLD) is False
+    assert envelope_duration_fixed(FIXED) is True
+    assert envelope_duration_fixed((FIXTURES / "libfakemicrophone_arm64.so").read_bytes()) is None  # no envelope code
+
+
+def test_microphone_probe_tells_old_and_fixed_runtime_apart():
+    assert microphone_checked(OLD) is False
+    assert microphone_checked(FIXED) is True
+    assert microphone_checked((FIXTURES / "libfakeoverport_arm64.so").read_bytes()) is None  # no such function
+
+
+def test_known_fixes_are_registered_for_existing_workarounds():
+    base.load_all()
+    fixes = {f.id: f for f in upstream.REGISTRY.values()}
+    assert fixes["ovrport.haptic_envelope"].workaround == "adapter.haptic_fix"
+    assert fixes["ovrport.microphone_stream"].workaround == "frame.ovr_microphone"
+    for fix in fixes.values():
+        assert fix.workaround in base.REGISTRY, fix.id
+
+
+def test_resolve_drops_workarounds_only_when_the_fix_is_found():
+    recipe = {"frame.adapter": {}, "adapter.haptic_fix": {"value": 1}, "frame.ovr_microphone": {}}
+    log = Log()
+    res = upstream.resolve(FakeWs({"libopenxr_loader.so": FIXED, "libovrplatformloader.so": OLD}), recipe, log)
+    assert res.superseded == {"adapter.haptic_fix": "ovrport.haptic_envelope"}
+    assert "adapter.haptic_fix" not in res.patches and "frame.ovr_microphone" in res.patches
+    assert "adapter.haptic_fix" in recipe  # the recipe itself is unchanged
+    assert any("not needed: adapter.haptic_fix" in line for line in log.lines)
+    # libraries missing (can't tell) or the old runtime: every workaround stays
+    assert upstream.resolve(FakeWs({}), recipe).patches == recipe
+    assert upstream.resolve(FakeWs({"libopenxr_loader.so": OLD, "libovrplatformloader.so": OLD}),
+                            recipe).superseded == {}
+
+
+def test_resolve_keeps_the_workaround_when_a_probe_breaks(temp_fix):
+    temp_fix(id="test.broken", workaround="adapter.swap_eyes", probe=lambda ws: 1 / 0)
+    log = Log()
+    res = upstream.resolve(FakeWs({}), {"adapter.swap_eyes": {"value": 1}}, log)
+    assert "adapter.swap_eyes" in res.patches and not res.superseded
+    assert any("test.broken failed" in line for line in log.lines)
+
+
+def test_resolve_can_be_switched_off(temp_fix, monkeypatch):
+    temp_fix(id="test.always", workaround="adapter.swap_eyes", probe=lambda ws: True)
+    assert upstream.resolve(FakeWs({}), {"adapter.swap_eyes": {}}).superseded == {"adapter.swap_eyes": "test.always"}
+    monkeypatch.setenv("FRAMEPORT_KEEP_WORKAROUNDS", "1")
+    assert upstream.resolve(FakeWs({}), {"adapter.swap_eyes": {}}).superseded == {}
+
+
+def test_without_superseded():
+    assert upstream.without_superseded({"a": {}, "b": {"x": 1}}, {"a": "fix"}) == {"b": {"x": 1}}
+    assert upstream.without_superseded({"a": {}}, None) == {"a": {}}
+
+
+@pytest.mark.parametrize("runtime, xrshim", [(OLD, True), (FIXED, False)])
+def test_build_leaves_out_the_haptic_workaround_with_a_fixed_runtime(tmp_path, monkeypatch, runtime, xrshim):
+    from frameport.patches.frame import adapter
+
+    apk = tmp_path / "in.apk"
+    with zipfile.ZipFile(apk, "w") as z:
+        z.writestr("lib/arm64-v8a/libopenxr_loader.so", runtime)
+        z.writestr("lib/arm64-v8a/libopenxr_loader_generic.so", b"loader")
+    monkeypatch.setattr(adapter, "artifact", lambda abi, name: b"artifact " + name.encode())
+    recipe = Recipe("com.x", patches={"frame.adapter": {}, "adapter.haptic_fix": {"value": 1}})
+    analysis = Analysis(package="com.x", version="1", label="X", abis=["arm64-v8a"], engine="Unity", xr="OpenXR",
+                        graphics="Vulkan", direct_vrapi=False, libs=["libOVRPlugin.so"], launcher_activity=None,
+                        has_info_category=True, meta_permissions=[], uses_glad_gl=False, unity_msaa_levels=0,
+                        oculus_os_classes=False, is_overport_output=False, debuggable=False, extra={})
+    applied, _checks, superseded = build.apply_frame_fixes(apk, tmp_path / "out.apk", analysis, recipe, Log())
+    assert applied == ["frame.adapter"]
+    assert superseded == ({} if xrshim else {"adapter.haptic_fix": "ovrport.haptic_envelope"})
+    with zipfile.ZipFile(tmp_path / "out.apk") as z:
+        settings = z.read("lib/arm64-v8a/libframe_settings.so").decode()
+        assert ("lib/arm64-v8a/libframe_xrshim.so" in z.namelist()) == xrshim
+    assert ("haptic_fix=1" in settings) == xrshim

tests/test_venc.py

@@ -0,0 +1,137 @@
+"""The live view's picture converter (native/venc/convert.c: RGB24 → NV12 with a box downscale, BT.709 limited
+range), compiled for this host and compared byte for byte with a Python reference written from native/venc/SPEC.md.
+The NEON path is checked against the scalar one on the Frame itself (`fp_venc --selftest`).
+Opt-in (FRAMEPORT_NATIVE_TESTS=1, -m native): needs the NDK in native/.cache (from native/build.py)."""
+import ctypes as C
+import os
+import platform
+import random
+import subprocess
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+CLANG = next(iter((ROOT / "native/.cache").glob("ndk-*/toolchains/llvm/prebuilt/*/bin/clang")), None)
+pytestmark = [pytest.mark.native, pytest.mark.skipif(
+    not os.environ.get("FRAMEPORT_NATIVE_TESTS") or not CLANG or platform.machine() != "x86_64",
+    reason="set FRAMEPORT_NATIVE_TESTS=1 (needs the NDK from native/build.py on an x86_64 host)")]
+
+
+@pytest.fixture(scope="module")
+def conv(tmp_path_factory):
+    out = tmp_path_factory.mktemp("venc") / "convert.so"
+    subprocess.run([str(CLANG), "--target=x86_64-linux-gnu", "-ffreestanding", "-nostdlibinc", "-fno-stack-protector",
+                    "-fno-builtin", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror", "-shared", "-nostdlib",
+                    "-fuse-ld=lld", str(ROOT / "native/venc/convert.c"), "-o", str(out)], check=True)
+    lib = C.CDLL(str(out))
+    lib.fp_scratch_size.restype = C.c_size_t
+    return lib
+
+
+# ---------------------------------------------------------------- reference (SPEC.md "Output size", "Converter")
+def out_size(src_w, src_h, max_h):
+    h = min(max_h if max_h > 0 else src_h, src_h) & ~1
+    return (src_w * h // src_h) & ~1, h
+
+
+def reference(rgb: bytes, sw: int, sh: int, ow: int, oh: int):
+    def px(x, y):
+        i = (y * sw + x) * 3
+        return rgb[i], rgb[i + 1], rgb[i + 2]
+
+    scaled = []
+    for j in range(oh):
+        y0, y1 = j * sh // oh, (j + 1) * sh // oh
+        row = []
+        for i in range(ow):
+            x0, x1 = i * sw // ow, (i + 1) * sw // ow
+            n = (x1 - x0) * (y1 - y0)
+            s = [0, 0, 0]
+            for y in range(y0, y1):
+                for x in range(x0, x1):
+                    p = px(x, y)
+                    s[0] += p[0]
+                    s[1] += p[1]
+                    s[2] += p[2]
+            row.append(tuple((v + n // 2) // n for v in s))
+        scaled.append(row)
+    clamp = lambda v, lo, hi: max(lo, min(hi, v))  # noqa: E731
+    y_plane = bytes(clamp(16 + ((47 * r + 157 * g + 16 * b + 128) >> 8), 16, 235)
+                    for row in scaled for r, g, b in row)
+    uv = bytearray()
+    for j in range(0, oh, 2):
+        for i in range(0, ow, 2):
+            r, g, b = ((scaled[j][i][c] + scaled[j][i + 1][c] + scaled[j + 1][i][c] + scaled[j + 1][i + 1][c] + 2) >> 2
+                       for c in range(3))
+            uv.append(clamp(128 + ((-26 * r - 86 * g + 112 * b + 128) >> 8), 16, 240))
+            uv.append(clamp(128 + ((112 * r - 102 * g - 10 * b + 128) >> 8), 16, 240))
+    return y_plane, bytes(uv)
+
+
+def run(conv, rgb: bytes, sw: int, sh: int, max_h: int, fn="fp_convert"):
+    ow, oh = C.c_int(), C.c_int()
+    conv.fp_out_size(sw, sh, max_h, C.byref(ow), C.byref(oh))
+    ow, oh = ow.value, oh.value
+    assert (ow, oh) == out_size(sw, sh, max_h)
+    pad = 7  # strides wider than the picture, to catch stride bugs
+    src_stride, ys, uvs = sw * 3 + 5, ow + pad, ow + pad
+    src = C.create_string_buffer(b"".join(rgb[r * sw * 3:(r + 1) * sw * 3] + b"\xee" * 5 for r in range(sh)))
+    y = C.create_string_buffer(b"\x01" * (ys * oh))
+    uv = C.create_string_buffer(b"\x01" * (uvs * oh // 2))
+    scratch = C.create_string_buffer(max(1, conv.fp_scratch_size(sw, sh, ow, oh)))
+    getattr(conv, fn)(src, sw, sh, src_stride, y, ys, uv, uvs, ow, oh, scratch)
+    yb, uvb = y.raw, uv.raw
+    y_plane = b"".join(yb[r * ys:r * ys + ow] for r in range(oh))
+    uv_plane = b"".join(uvb[r * uvs:r * uvs + ow] for r in range(oh // 2))
+    assert all(yb[r * ys + ow:(r + 1) * ys] == b"\x01" * pad for r in range(oh))  # padding untouched
+    return (ow, oh), y_plane, uv_plane
+
+
+def solid(w, h, rgb):
+    return bytes(rgb) * (w * h)
+
+
+def noise(w, h, seed=1):
+    r = random.Random(seed)
+    return bytes(r.randrange(256) for _ in range(w * h * 3))
+
+
+@pytest.mark.parametrize("rgb,y,cb,cr", [((0, 0, 0), 16, 128, 128), ((255, 255, 255), 235, 128, 128),
+                                         ((255, 0, 0), 63, 102, 240), ((0, 255, 0), 172, 42, 26),
+                                         ((0, 0, 255), 32, 240, 118)])
+def test_solid_colours(conv, rgb, y, cb, cr):
+    (ow, oh), yp, uvp = run(conv, solid(16, 8, rgb), 16, 8, 0)
+    assert set(yp) == {y} and set(uvp[0::2]) == {cb} and set(uvp[1::2]) == {cr}
+    assert reference(solid(16, 8, rgb), 16, 8, ow, oh) == (yp, uvp)
+
+
+@pytest.mark.parametrize("sw,sh,max_h", [(64, 48, 0), (64, 48, 24), (64, 48, 32), (64, 48, 10), (37, 23, 0),
+                                         (37, 23, 16), (66, 40, 30), (30, 90, 36)])
+@pytest.mark.parametrize("fn", ["fp_convert", "fp_convert_scalar"])
+def test_matches_reference(conv, sw, sh, max_h, fn):
+    rgb = noise(sw, sh, seed=sw * sh + max_h)
+    (ow, oh), yp, uvp = run(conv, rgb, sw, sh, max_h, fn)
+    assert (yp, uvp) == reference(rgb, sw, sh, ow, oh)
+
+
+def test_box_average_of_two_by_two(conv):
+    # a 4x2 image of 2x2 blocks: left block black/white checker → grey 128 (rounded), right block pure red
+    rgb = bytes([0, 0, 0, 255, 255, 255, 255, 0, 0, 255, 0, 0,
+                 255, 255, 255, 0, 0, 0, 255, 0, 0, 255, 0, 0])
+    (ow, oh), yp, uvp = run(conv, rgb, 4, 2, 2)  # max height 2 = unchanged size
+    assert (ow, oh) == (4, 2) and (yp, uvp) == reference(rgb, 4, 2, 4, 2)
+    big = b"".join(rgb[r * 12:(r + 1) * 12] for r in (0, 1)) * 2  # 4x4: rows 0,1,0,1
+    (ow, oh), yp, uvp = run(conv, big, 4, 4, 2)
+    assert (ow, oh) == (2, 2)
+    assert yp[0] == 16 + ((47 * 128 + 157 * 128 + 16 * 128 + 128) >> 8) and yp[1] == 63
+
+
+def test_output_sizes(conv):
+    for (sw, sh, mh), want in {(1920, 1080, 360): (640, 360), (1920, 1080, 480): (852, 480),
+                               (1920, 1080, 720): (1280, 720), (1920, 1080, 1080): (1920, 1080),
+                               (1920, 1080, 0): (1920, 1080), (1920, 1080, 4000): (1920, 1080),
+                               (1921, 1081, 0): (1918, 1080)}.items():
+        ow, oh = C.c_int(), C.c_int()
+        conv.fp_out_size(sw, sh, mh, C.byref(ow), C.byref(oh))
+        assert (ow.value, oh.value) == want == out_size(sw, sh, mh)