Merge origin/main into ui-refresh

BONELAB 1.2974 / Sniper Elite VR / Star Wars Pinball VR fixes (pac_hints, unreal_ovrp_entrypoints, unreal_gl_shim, ovrpshim settings, ANALYSIS_VERSION 3) and catalog entries. Only conflict: the generated locales/template.json (regenerated). Agent stays v66 (main didn't bump it).
Deleting a screenshot also removes Steam's stereo copy (<name>_vr.jpg) that VR screenshots get
2026-10-09 05:00:41 +02:00 · 2026-10-08 22:38:32 -04:00 · 2026-10-08 22:33:39 -04:00 · 2026-10-08 22:22:53 -04:00 · 2026-10-08 22:09:23 -04:00 · 2026-10-08 22:08:29 -04:00
191 changed files with 20774 additions and 1473 deletions
@@ -10,8 +10,20 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
 ## Layout
 - `src/frameport/` — Python package. `pipeline.py` is the API the CLI (`cli.py`) and GUI (`ui/`, Flet 1.0) share.
  - `ui/` — `app.py` shell (sidebar with Frame connection + activity cards, routing, actions, 30 s connection poll),
-    `theme.py` (dark design tokens; change colours/spacing only there), `components.py` (pill, card, callout,
-    status_row, art_fill, confirm, `update()` = safe update: in Flet 1.0 reading `.page` of an unmounted control
+    `theme.py` (design tokens; change colours/spacing only there. Dark-only colour themes (owner: no light mode):
+    built-ins `portal` (default), `portal_oled` (true black) and `original` (the old violet; alias `classic`). Portal =
+    the logo's dichotomy: orange ACCENT = main action + selection, blue SECONDARY = secondary (outlined) buttons,
+    progress, switch tracks, PC; `dual` themes add the blue→orange sidebar edge, two-colour wordmark (`C.wordmark`) and
+    selected-tab fade (`C.portal_gradient`). Installable theme files `<data>/themes/*.json` (docs/THEMES.md: name,
+    base, dual, any subset of `T.TOKENS`; refused if light/unreadable, `T.ThemeError`), Settings → Appearance: cards
+    switch live via `app.restyle()` (rebuilds the shell, drops cached views; setting `ui.theme`), "Install theme
+    file…", "Copy this theme as a file", bin icon removes. Read tokens as `T.NAME` when building — never as a default argument or module-level constant (they
+    keep the import-time theme; module maps refill through `T.on_change`, `tests/test_theme.py` checks defaults)),
+    `glyphs.py` + `icons/` (the logo `logo.svg`/`logo-solid.svg` = a monitor that comes out of a tilted portal as the
+    Frame, and 24 px line glyphs `fp:frame|port|patch|container|test|pc|sync|live|shot|keys|recipe|link`, copied into
+    the assets dir and shown as tinted `ft.Image`s: pass `G.FRAME` … wherever an icon goes, `C.as_icon` / the button
+    helpers handle both kinds; `src/assets/icon.png` = the bundles' app icon), `components.py` (pill, card, callout,
+    checklist, art_fill, confirm, `update()` = safe update: in Flet 1.0 reading `.page` of an unmounted control
    raises), `jobs.py` (background FIFO job queue, one at a time, cancel via Reporter; no Flet), `views/`
    (library: search/filters/tags/sort as pure tested helpers; game: hero + one-click install, patches under
    "Customize"; frame: device + readiness + installed, or connect wizard; files: the Frame's file manager (persistent
@@ -28,13 +40,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).
@@ -42,6 +65,14 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    await a FilePicker) must be coroutine functions or go through `page.run_task`: Flet doesn't await a lambda's
    coroutine (the Files row Download button silently did nothing). `ui_smoke.py --fake-frame --gestures` drives real
    mouse drags/right-clicks.
+    Live Frame data comes from one app-owned `app.monitor_hub` (`frame/monitor_hub.py`): subscribers name modules +
+    interval, the hub runs one agent `_monitor` stream (union of modules, fastest interval; per-module collection
+    needs agent v65), reconnects after a lost stream and stops it when nobody subscribes; `_poll` retries an "error".
+    Subscribers: "monitor" (the Monitor tab, everything, only while shown) and "card" = the sidebar's live Frame card
+    (`ui/frame_card.py` helpers: battery ring, "now playing" row with fps + 2-min sparkline → click opens Monitor;
+    games + battery every 5 s, paused while a job's stage is "Upload…", only while connected and setting
+    `ui.live_frame_card` (Settings → Appearance, default on) is on; else the battery comes from the 30 s poll).
+    ui_smoke injects `FakeMonitorSession` as the hub's `session_factory`.
    User tags live in library entries (`tags`), filters in library setting `ui.library`.
    **Performance rules** (the app froze before): never put image bytes in controls — artwork is served by URL from the
    GUI assets dir (= user data dir; `ft.run(assets_dir=…)`), as thumbnails (`artwork/thumbs.py`, Pillow); the
@@ -50,16 +81,45 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    **Never recreate clickable controls on progress ticks** (sidebar, activity tiles): update their properties —
    replacing them 5×/s swallowed clicks (couldn't leave the Library during an upload).
    Labelled switches: `C.switch(label, …)` (Material's default label colour is dark on our dark theme).
+    Cover cards (Library grid + shelf): `library.card_hover`/`hover_motion` (lift, art zoom inside the clipped frame,
+    radial `scrim`, accent-tinted shadow) and `C.CoverButton` (frosted round button, accent under the pointer; Play =
+    blue then orange ring ripple + "Starting on Frame…" pill for STARTING_S; its `.status` layer must sit *below*
+    the button in the Stack, else it takes the clicks); the game page's Play turns into "Starting on …" with a spinner
+    (`GameView._starting`). Reduce motion: no lift/zoom/rings. Filled buttons use a glyph's `-solid` variant
+    (`glyphs.solid`, e.g. `frame-solid.svg`: the outline glyph faded into the orange).
+    Empty states (`C.empty_state(..., features=[(icon, heading, sentence)])`): with features the portal is bigger, a
+    soft portal light (`C.portal_glow`) fills the screen and `C.feature_row` says what the screen will show (the
+    not-connected Files/Screenshots/Live/Type/Monitor tabs and the empty Library); the idle Live view is a framed
+    "screen" with its own Start button + `live_features()`, Type on Frame shows `keyboard_tips()` under the box.
+    Setup checklists (Frame → Ready to play, Settings → Tools / This PC) = `C.checklist([C.Check(ok, title, detail,
+    help, fix=(label, icon, handler), extra=control)])`: ok True/False/"warn"/None (= spinner); the fix button shows
+    inline only while an item isn't ready — wire existing actions only. Motion: `app.body` holds an
+    `ft.AnimatedSwitcher` (`app._show_view`): a new route gets a new wrapper (150 ms fade), a same-route redraw swaps
+    the wrapper's content (no animation; persistent views just remount); the wordmark's portal (`wordmark().data`)
+    pulses once when frame_state turns "connected"; both off with setting `ui.reduce_motion` (Settings → Appearance
+    "Reduce motion", `app.reduce_motion`). Settings has a fixed index column (`settings.SECTIONS` order, Appearance
+    first, Remove FramePort last): entries scroll the section column via `scroll_to(scroll_key=…)` (sections wrapped
+    in Containers with `ft.ScrollKey`), the header stays; `app.settings_view.show_section(key)` (ui_smoke
+    `settings-index`).
    Help hints: wording for non-obvious terms lives in `ui/help.py` (`HELP`); show it with `C.help_icon(key)` or the
-    `help=` argument of `section`/`status_row`/`kv`, tooltips via `C.tip()` (wraps). Game actions for the Library
-    right-click menu (one `ft.ContextMenu` around the grid, filled on right-click) and the game page's "…" menu come
-    from `app.game_actions()`. Picking art (`sources.apply_choice`) downloads into a staging dir and keeps the old
+    `help=` argument of `section`/`kv` (`C.Check` help key), tooltips via `C.tip()` (wraps). Game actions for the Library
+    right-click menu (one `ft.ContextMenu` around the grid, filled on right-click; short: `menus.quick_menu`, key actions
+    + "More actions…" = the game page with its full "…" menu opened from code, `app.open_game_menu`) and the game
+    page's "…" menu (`menus.menu_sections` quick=False, sectioned) come from `app.game_actions()`. Picking art (`sources.apply_choice`) downloads into a staging dir and keeps the old
    art if nothing came back; "Update Steam art on Frame" re-sends the art set to the game's anchor (agent ≥ 12).
    Patch descriptions/reasons describe the general case, naming games only as "e.g. …".
  - Installs: queued/cancelled/failed ones are remembered (library setting `ui.installs`) → Library "Resume" bar;
    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 +171,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 +200,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).
@@ -165,9 +238,15 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
    signed, `ready.json`); `apply()` writes + starts detached `apply.ps1`/`apply.sh` (wait for pid → Windows: copy over,
    replaced files kept in `updates/<ver>/previous` because the zip has no top folder; macOS/Linux: mv to `.old` + swap,
    rollback, `xattr -dr` quarantine → relaunch; `<data>/logs/update.log`). `ui/updater.py`: background check (10 s,
-    then 6 h), sidebar card (hidden control, toggled), Library bar (`library_bar`), notes dialog (`ft.Markdown`), job
+    then 6 h), sidebar card (hidden control, toggled), Library bar (`library_bar`), changelog dialog, job
    `app-update` that restarts only when no other job is active, `apply_pending_at_start()` in `main()` for
-    "Install updates automatically"; Settings → Updates. CLI: `--version`, `frameport update [--check (exit 10)]
+    "Install updates automatically"; Settings → Updates. Changelog: `updates.fetch_changelog` (releases list,
+    `app-releases.json`, same 6 h cache, offline → cached / []) → `ChangelogEntry` (`whats_new()` keeps only the tag
+    message's "What's new" part: CI's intro, update hint and release-footer.md stripped); `between`/`changelog_for`
+    (installed < v ≤ offered, dev entry only when on/choosing dev, skipped versions included), `recent_history`;
+    the update/dev dialogs show one collapsible section per version (`_changes_column`, newest open); after an update
+    `pending_news` (setting `update.last_seen_version`; first start only records it; offline → retried next start)
+    → Library "was updated" bar → "See what's new…"; Settings → Updates "What's new…" = recent history. CLI: `--version`, `frameport update [--check (exit 10)]
    [--yes]`, once-a-day stderr hint read from the cache only (`refresh_cache()` in a daemon thread writes no
    settings, to avoid read-modify-write races). `scripts/update_smoke.py <archive>` runs the real extract + swap script
    (no relaunch) — CI runs it on all three OS with the archive it just built.
@@ -505,7 +584,7 @@ recipe keeps it on). I Am Cat works with issues (judder; scale 0.8 no help). Rob
 libroblox, also with the Vulkan shim). Installs skip the Steam restart when the shortcut is unchanged and wait while a
 game runs (agent v37). New default fixes in FramePort's code reach games already in a library: after every app update
 `library._follow_catalog` re-derives each non-user recipe once (setting `recipes.app_version`; tests switch it off via
-`library.REFRESH_ON_UPDATE`); analysis fields added later still need a re-analysis. Troubleshooting techniques: docs/PLAYBOOK.md "Debugging techniques". Unity `boot.config` "vulkan" substring mislabels GLES games as Vulkan
+`library.REFRESH_ON_UPDATE`). Analysis fields added later: **bump `analysis/detect.ANALYSIS_VERSION`** (stored as `analysis.extra.analysis_version`); older entries whose APK is still there are analysed again at the GUI's start (background thread, not a job: ~8 s per 900 MB APK) and before a build (`pipeline.refresh_analyses`, GitHub #104); only `analysis`/`suggested` change, user recipes stay; an unreadable APK gets `analysis_failed` = the version (not retried until the next bump). Troubleshooting techniques: docs/PLAYBOOK.md "Debugging techniques". Unity `boot.config` "vulkan" substring mislabels GLES games as Vulkan
 (I Am Cat ran GLES); OVRPlugin's "Unavailable OpenXR extension: XR_FB_scene" is routine (no longer triaged).
 **Round 4 (2026-10-04):** XR_KHR_android_surface_swapchain is listed by the Frame's runtime but returns
 FUNCTION_UNSUPPORTED → adapter `surface_emul` (default on, `native/adapter/surface_swapchain.c`): an ordinary runtime
@@ -613,6 +692,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`)
@@ -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
@@ -94,7 +109,7 @@ will attempt to guess key patches. If you find a new config that works for an ap

 **[List of tested games](docs/GAMES.md)**

-**Tested something? Share it.** In FramePort open the game → **…** → **Share working config…** (it fills in the
+**Tested something? Share it.** In FramePort open the game → **…** → **Share working recipe…** (it fills in the
 recipe for you) or **Report a problem…** (attaches a diagnostics zip with personal data removed). Without the app:
 [share a working config](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml) · [report a problem](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml). Shared configs become built-in recipes for everyone.

@@ -1,16 +1,17 @@
 e7554c6343ee2989b0a273ee6230e65c25bfe6499eefd00de19f5f0fee58754f  ./arm64-v8a/libfp_langpack.so
-98a99cefe93079268d9158b23fa8ad5c7ade8e54c0d31526892635625eb3ef04  ./arm64-v8a/libfp_ovrp.so
+321da502e0f8f46f0880aad39fe6b84bdef88f925164568814cf704a1b31a577  ./arm64-v8a/libfp_ovrp.so
 40defdaddcda53bd2649eb48076fae1622bfc2bfc88e9e03c94fc8b45af2a4f2  ./arm64-v8a/libfp_ovrtrace.so
 7522a7cfb236e48d3442d418c4820cd37760a9627c6bdef80fb0df82df5fd826  ./arm64-v8a/libfp_vk.so
 383054f8b3b41dde76d062c71856cd3163655e50009c08454bc1793f393ead65  ./arm64-v8a/libfpg.so
-06c8a17b37cb1513fdfeba87ece457a02097bb22dd0a3a3a8719fb8fea16b52a  ./arm64-v8a/libframe_xrshim.so
-9f5ba793d1804728394a8fe9e83028e13f1bc939b558892e7beb5c3662317259  ./arm64-v8a/libglshim.so
-d7709fe953a3170467ec0c53e6b715833014512fbd8d91803a9cb2aecf0961ad  ./arm64-v8a/libopenxr_loader_generic.so
+8a8f6b1da8952cb3933a5b53558424a5fc56043b2527a16bb6dd62a00d2de01a  ./arm64-v8a/libframe_xrshim.so
+fc559dbe0b87eecc3641256837293260cefb7c2ce7b21d808d10edd2a2dba9fc  ./arm64-v8a/libglshim.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
@@ -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
@@ -0,0 +1,21 @@
+package: com.FourPlayersStudio.Retronika
+title: Retronika
+status: works
+tested_version: 3.2.601
+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: 290bfda3969547d5f1ff621ab5a8be9dd322fc9eee6b243c863576d4ff5b4b81
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261006.6173745'
+  agent: 59
+  issue: 97
+source_hint: Retronika
@@ -4,14 +4,25 @@ tested_version: '1.03'
 source_hint: Sniper Elite VR
 engine: Unity
 xr: VrApi
-status: unsupported
-notes: 'GPU hang (zink: DEVICE LOST) even with MSAA off.'
-details: Legacy VrApi via OVRPlugin.
+status: works
+notes: Plays with controllers that follow the hands (owner's headset test, Quest 1 build 35713).
+details: 'Unity 2019.4 on its built-in Oculus VR (no Oculus XR Plugin). Its legacy frame loop never waited for frames
+  (GPU hang, zink: DEVICE LOST) and Unity reported only Go controllers: frame.unity_oculus_check. Its frame wait then
+  deadlocked at the Init scene (Unity skipped beginning a frame) and the physics-step pose update located the
+  controllers in the past (hands lagged): both fixed in that patch (revision 5), switched on for this game by ovrp_begin_gate and ovrp_hold_physics. Grabbing an object in the tutorial
+  vibrates the controller; OVRPort''s envelope conversion then allocated ~1 GB/s until the memory cap ended the game:
+  haptic_fix. The Quest 1 build has no arraysources_assets.hd, which the game loads on the Frame (it detects a Quest
+  2) and then skips the .sd bundle: textures are missing unless the .sd file is also present under the .hd name in the
+  game''s obb folder.'
 frame:
 - frame.unity_no_msaa
+- frame.unity_oculus_check
+adapter:
+  haptic_fix: 1
+  ovrp_begin_gate: 1
+  ovrp_hold_physics: 1
 pcvr_alternative: Sniper Elite VR (Steam PC VR). Winter Warrior (Quest) works on the Frame.
 verified:
-  date: '2026-09-28'
-  overport_cli: 1.2.3
-  overport_runtime: 3.4.3-23204ea
-  known_good_sha256: e80883eb6945e267a375edf0ffd789268686440819add9d4dee9fdbdf466cbe4
+  date: '2026-10-07'
+updated: '2026-10-07'
+min_app: 0.12.1
@@ -1,20 +1,25 @@
 package: com.StressLevelZero.BONELAB
 title: BONELAB
-status: issues
-notes: 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.
-details: The game runs (72 fps), but its player body stayed frozen - no head tracking, the controllers stuck to the
+status: works
+notes: Builds 1.2068 and 1.2974 play (owner's headset tests). One recipe serves both builds - 1.2068 needs frame.unity_user_presence (head tracking and controls); 1.2974 also needs
+  frame.slz_vulkan_hooks (72 fps after about 35 s of shader prewarming), which changes nothing on 1.2068.
+details: Both builds - the game runs (72 fps), but its player body stayed frozen - no head tracking, the controllers stuck to the
  model, no buttons - although OpenXR input and OVRPlugin's poses were fine. A few seconds after start (when Unity
  switches XR loaders) OVRPlugin reports the worn headset as not worn (ovrp_GetUserPresent2 -> 0), and BONELAB's
  Marrow rig only follows the player while Unity's HMD device reports UserPresence (OpenControllerRig checks
-  XRHMD.IsUserPresent every frame). frame.unity_user_presence reports the headset as worn. Build 1.2974 crashed
-  earlier in vkCreateInstance from the game's own Vulkan hooks (libSLZQuestNative.so); not retested.
-tested_version: 1.2068.34555
+  XRHMD.IsUserPresent every frame). frame.unity_user_presence reports the headset as worn. Build 1.2974 only - it adds Stress
+  Level Zero's graphics plugin (libSLZQuestNative.so), which hooks Unity's Vulkan start-up (vkCreateInstance/
+  vkCreateDevice) and vkCreateSampler; on the Frame its vkCreateInstance wrapper calls an invalid pointer right after
+  OVRPlugin's pre-init instance is destroyed (a jump to 0, into an unloaded library, or a hang). frame.slz_vulkan_hooks
+  switches its two registrations off, so Unity starts Vulkan itself; the plugin's pipeline cache isn't used.
+tested_version: 1.2974.57485
 engine: Unity
 xr: OpenXR
 frame:
 - frame.unity_user_presence
+- frame.slz_vulkan_hooks
 verified:
-  date: '2026-10-06'
-updated: '2026-10-06'
+  date: '2026-10-08'
+updated: '2026-10-08'
 source_hint: BONELAB
+min_app: 0.12.1
@@ -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
@@ -0,0 +1,23 @@
+package: com.VR_HOT.VR_HOT_Quest
+title: VR HOT Quest
+status: works
+tested_version: 0.8.8.1
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  controller_models: 1
+  haptic_fix: 1
+verified:
+  date: '2026-10-08'
+  known_good_sha256: c321606c536eba1673572a9f44fd9e20d2cb5bd9609d536189e6ad7057b9cd67
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 59
+  issue: 98
+source_hint: VR-HOT-Quest-0.8.8.1
@@ -0,0 +1,25 @@
+package: com.YourCompany.SWP_VR
+title: Star Wars Pinball VR
+tested_version: '1.4'
+source_hint: Star Wars Pinball VR
+engine: Unreal
+xr: VrApi
+status: works
+notes: Plays (owner's headset test); one short audio hiccup seen.
+details: 'Unreal 4.25 (GLES) built against OVRPlugin 1.44. Four Frame problems in a row: Zink crashed on Unreal''s
+  multisampled render-to-texture (fault addr 0x10000 on the RHIThread): frame.unreal_gl_shim, which keeps Unreal''s
+  multiview and draws those passes single-sampled; OVRPort''s OVRPlugin lacks ovrp_GetPTWNear, so Unreal''s Oculus
+  module never started VR (then a null pointer in GetMultiViewSceneColor): frame.unreal_ovrp_entrypoints; the engine''s
+  OpenSSL assembly has unpaired return-address checks the Frame''s CPU enforces (SIGILL on the HttpManager thread):
+  frame.pac_hints. Needs its OBB (main.10765).'
+frame:
+- frame.unreal_gl_shim
+- frame.unreal_ovrp_entrypoints
+- frame.pac_hints
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-08'
+  issue: 83
+updated: '2026-10-08'
+min_app: 0.12.1
@@ -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
@@ -0,0 +1,22 @@
+package: com.cloudheadgames.pistolwhip
+title: Pistol Whip
+status: works
+notes: 120 HZ
+tested_version: 1.6.0.2
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-08'
+  known_good_sha256: ebd97af54c59d59d473c98492c1bb26ce6059b7e59f27a08acfc5ada23d0b774
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261006.6173745'
+  agent: 59
+  issue: 100
+source_hint: Pistol Whip
@@ -0,0 +1,22 @@
+package: com.curif.AgeOfJoy
+title: AgeOfJoy
+status: works
+tested_version: '1.0'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-08'
+  known_good_sha256: 9780e71e417b86290147c67c83755305801d8957909734c717a519034edefdf9
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261006.6173745'
+  agent: 59
+  issue: 103
+source_hint: AgeOfJoy 05 rc30
@@ -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
@@ -8,16 +8,41 @@ 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
    diagnosis: Unity's render thread crashed inside the Frame's GL driver (Mesa/Zink); the picture freezes or stays grey. Known triggers - an OVROverlay copy (try "Unity - skip OVROverlay layers", e.g. The Room VR), MSAA switched on at runtime, a GPU hang (zink DEVICE LOST).
    suggest: [frame.unity_no_overlay_copy, frame.unity_runtime_msaa_off]
+  - id: unreal-msrtt-crash
+    pattern: 'fault addr 0x10000 in tid \d+ \((RHIThread|RenderThread)'
+    severity: fatal
+    diagnosis: The game's render thread jumped to address 0x10000 inside the Frame's GL driver (Mesa/Zink) a few seconds after start. Zink looks up a render-pass cache slot past its end when a game renders through multisampled render-to-texture (Unreal's mobile MSAA, e.g. Star Wars Pinball VR). Load the GL shim, which hides that extension.
+    suggest: [frame.unreal_gl_shim, frame.unity_gl_shim]
+  - id: pac-unpaired
+    pattern: 'ILL_ILLOPN\), fault addr 0x[0-9a-f]+ \(\*pc=0xd50323bf\)'
+    severity: fatal
+    diagnosis: The game crashed on a return-address check (autiasp) its code never signed. The Quest's CPU ignores these checks, the Steam Frame's enforces them; some OpenSSL assembly in game engines has such unpaired checks (e.g. Star Wars Pinball VR on its first network connection, thread HttpManager).
+    suggest: [frame.pac_hints]
  - id: swapchain-rect-invalid
    pattern: 'xrEndFrame failed -25\b'
    severity: fatal
@@ -79,6 +104,12 @@ signatures:
    diagnosis: Unity didn't start its Oculus VR device (older Unity checks for Meta's system apps first), so the game
      runs as a hidden 2D app.
    suggest: [frame.unity_oculus_check]
+  - id: unity-frame-not-begun
+    pattern: 'frame loop shim: frame \d+: the last waited frame wasn.t begun'
+    severity: info
+    diagnosis: Unity skipped beginning a frame (typically while it activates a scene); FramePort's frame wait didn't
+      wait for that frame instead of blocking the game. A few at each scene load are normal.
+    suggest: []
  - id: sdl-no-clipboard
    pattern: 'ClipboardManager\.addPrimaryClipChangedListener|SDLClipboardHandler\.<init>'
    severity: fatal
@@ -91,6 +122,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
@@ -208,6 +245,12 @@ signatures:
      voice chat a few seconds after the logo).
    suggest: [frame.ovr_microphone]
    supersedes: [native-crash]
+  - id: slz-vulkan-hook-crash
+    pattern: 'SLZ Graphics plugin loading![\s\S]{0,20000}?E CRASH   : .*pc  0000000000000000'
+    severity: fatal
+    diagnosis: Stress Level Zero's graphics plugin (libSLZQuestNative.so) hooks Unity's Vulkan start-up and calls an invalid function there on the Frame (e.g. BONELAB 1.2974); the game crashes or hangs before its first frame.
+    suggest: [frame.slz_vulkan_hooks]
+    supersedes: [java-crash, native-crash]
  - id: native-crash
    pattern: 'Fatal signal (\d+) \(SIG[A-Z]+\)'
    severity: fatal
@@ -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`.
@@ -6,7 +6,7 @@ Other games get suggested patches from detection rules; each suggestion states i
 switched on or off under **Customize**: described in plain words, with **Show technical details** for the exact
 effect of each patch.

-Tried an untested game? Its page asks how it runs; **Share working config…** opens a prefilled GitHub issue so your
+Tried an untested game? Its page asks how it runs; **Share working recipe…** opens a prefilled GitHub issue so your
 recipe can join the built-in catalog for everyone.

 ![Patches](images/patches.png)
@@ -2,7 +2,7 @@

 Two ways users feed results back, both without a GitHub token:

- **Share working config** (game menu, `frameport share-recipe <pkg>`): saves the recipe as a user catalog entry and
+- **Share working recipe** (game menu, `frameport share-recipe <pkg>`): saves the recipe as a user catalog entry and
  opens a prefilled issue from `.github/ISSUE_TEMPLATE/working-config.yml`. A maintainer checks it and adds the label
  `catalog-accepted`. Then `.github/workflows/catalog-from-issue.yml` runs `scripts/catalog_from_issue.py`, which reads
  only the YAML block, validates it, and writes `catalog/games/<pkg>.yaml`, and the workflow opens a PR.
@@ -24,7 +24,7 @@ Games/                                  ← scan this folder (Add games → Scan
  as alternates.
 - **Scanning:** pick the folder that contains the game folders (`Games/` above) to add them all, or one game's folder
  to add just that game. FramePort looks up to 5 levels deep.
- **A single game:** Add games → Add an APK file… works with a lone APK too. Its data is found when the data folder sits next
+- **A single game:** Add games → Add an APK… works with a lone APK too. Its data is found when the data folder sits next
  to the APK, named as above.

 Not sure of the package name? Look at the OBB file names: `main.<version>.<package name>.obb`. Or add the APK
@@ -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,24 @@
 - 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.
+- Linux apps' own icons (GitHub #99, agent v64): finalize_linux (and every refresh of the menu entries) copies the
+  app's icon to `<anchor>/artwork/app-icon.{png,svg}`: an AppImage's `squashfs-root/.DirIcon` (usually a symlink),
+  else the `Icon=` of its top-level `.desktop` file (a folder app: the first `.desktop` within 3 levels) looked up
+  next to it, in `(usr/)share/icons/hicolor/*/apps/` and `(usr/)share/pixmaps/`; the biggest PNG ≥128 px, else an
+  SVG, else the biggest PNG. Symlinks are resolved and must stay inside the app folder; absolute and `../` names
+  are ignored. Precedence for the menu entry's `Icon=` and the Steam shortcut's icon: the user's chosen/store icon
+  (`artwork/.icon-source` = `custom`, written by the PC with every art upload) > the app's own (Steam: PNG only) >
+  FramePort's placeholder (`artwork/icon.*`). `StartupWMClass=` is copied from the app's `.desktop` file (Plasma's
+  task bar matches the window to the entry). A PNG ≤1 MiB goes back to the PC (finalize result `app_icon.png`,
+  base64) and becomes the library's icon when the game has none and nothing was picked (`.app-icon` marker = its
+  sha256, no `.picked`); folder apps get it on the PC at add time (`analysis/linux.find_icon`). Not yet seen in
+  Desktop Mode on the device.

 ## 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 +177,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 +242,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.
@@ -1,6 +1,6 @@
 # Tested games

-Games tested on the Steam Frame with FramePort's recipes. Games not listed here may work too: FramePort suggests patches for them, and a working config can be shared from the app (**Share working config…**).
+Games tested on the Steam Frame with FramePort's recipes. Games not listed here may work too: FramePort suggests patches for them, and a working recipe can be shared from the app (**Share working recipe…**).
 Tested a game? [Share a working config](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml) or [report a problem](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml) (in the app: the game's **…** menu does both and fills in the details).
 Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.

@@ -8,6 +8,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 |---|---|---|---|
 | 4XVR Video Player | Quest | ✅ Works |  |
 | Accounting+ | Quest | ✅ Works |  |
+| AgeOfJoy | Quest | ✅ Works |  |
 | AllInOneSports | Quest | ✅ Works |  |
 | Asgard's Wrath 2 | Quest | ✅ Works |  |
 | BAM | Quest | ✅ Works |  |
@@ -20,6 +21,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Beat Saber (co-existence build) | Quest | ✅ Works |  |
 | Blade & Sorcery: Nomad | Quest | ✅ Works |  |
 | BodyCombat | Quest | ✅ Works |  |
+| BONELAB | Quest | ✅ Works |  |
 | Carve Snowboarding | Quest | ✅ Works |  |
 | Cook-Out | Quest | ✅ Works |  |
 | Creed | Quest | ✅ Works |  |
@@ -27,6 +29,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 |  |
@@ -48,13 +51,19 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | NOPE CHALLENGE | Quest | ✅ Works |  |
 | palazzo_santacruz | Quest | ✅ Works |  |
 | Path of the Warrior | Quest | ✅ Works |  |
+| Pistol Whip | Quest | ✅ Works |  |
 | PowerWash Simulator VR | Quest | ✅ Works |  |
 | QuestCraft | Quest | ✅ Works |  |
+| Retronika | 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 | Quest | ✅ Works |  |
 | Sniper Elite VR: Winter Warrior | Quest | ✅ Works |  |
 | Space Pirate Trainer Quest | Quest | ✅ Works |  |
+| Star Wars Pinball VR | Quest | ✅ Works |  |
 | Stremio | Quest | ✅ Works |  |
 | SUPERHOT VR | PC VR | ✅ Works |  |
 | SUPERHOT VR | Quest | ✅ Works |  |
@@ -62,15 +71,17 @@ 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 |  |
+| VR HOT Quest | Quest | ✅ Works |  |
 | VR4 | Quest | ✅ Works |  |
 | Wallace & Gromit in The Grand Getaway | Quest | ✅ Works |  |
 | Waltz of the Wizard: Extended Edition | Quest | ✅ Works |  |
 | Wander | Quest | ✅ Works |  |
 | 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. |
@@ -84,5 +95,4 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Journey of the Gods | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |
 | Roblox | Quest | ❌ Doesn't run | Crashes on its first VR frame on the Frame. |
 | Shadow Point | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |
-| Sniper Elite VR | Quest | ❌ Doesn't run | GPU hang (zink: DEVICE LOST) even with MSAA off. |
 | Sports Scramble (Santa Cruz) | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |
@@ -85,13 +85,51 @@ 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…** 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 → Add 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. For your page there's an "Install with FramePort" button:
+  [INSTALL_BUTTON.md](INSTALL_BUTTON.md). 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 +140,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): 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 +151,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
@@ -140,7 +191,7 @@ Command line: `frameport update` (`--check` only checks, exit code 10 = update a
 ## PC VR games

 PC VR games are Windows VR games (OpenXR, SteamVR or Oculus). Scan a folder of them (one folder per game) or use
-**Add games → Add one game folder…**. FramePort finds the game's program and asks when there is more than one
+**Add games → Add a PC game folder…**. FramePort finds the game's program and asks when there is more than one
 candidate. **Already patched** on a game page installs a copy unchanged. Oculus-only games need Revive: FramePort uses
 an installed Revive, or downloads a portable copy.

@@ -151,23 +202,30 @@ an installed Revive, or downloads a portable copy.
  on the game page.
 - Games that use the Oculus Platform SDK check the licence through the Oculus app, so they run on the PC only.

-**Windows games without VR:** **Add games → Add one game folder…** with the game's folder (pick the program that
+**Windows games without VR:** **Add games → Add a PC game folder…** with the game's folder (pick the program that
 starts it if asked). FramePort installs it on the Frame and Proton runs it as a window, like Steam's own Windows games;
 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)
@@ -192,7 +250,7 @@ Command line: `frameport frame send <files> --dest videos` (`frameport frame sto

 ## Sharing a working game, reporting a problem

- **Share working config…** (game menu): opens a prefilled GitHub issue with the game's patches and settings. Accepted
+- **Share working recipe…** (game menu): opens a prefilled GitHub issue with the game's patches and settings. Accepted
  configs become built-in recipes. Untested games ask on their page once they've been installed or tested: **It
  works**, **It has issues** or **It doesn't run**.
 - **Report a problem…** (game menu, or Settings → Problems and feedback): saves a diagnostics zip to Documents (logs,
@@ -207,12 +265,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 |

@@ -0,0 +1,99 @@
+# "Install with FramePort" button
+
+A button for web pages and READMEs that opens a game straight in FramePort. Clicking it hands FramePort an install
+link; FramePort shows what it would download and asks before it does anything (see
+[Install links](INSTALL.md#install-links-install-with-framedrop-buttons)).
+
+<p>
+  <img src="badges/install-with-frameport-animated.svg" alt="Install with FramePort" width="216" height="60">
+</p>
+
+## Files
+
+All files are in [`docs/badges/`](badges/). Each SVG is self-contained (no external fonts or images), 216 × 60.
+
+| File | Use it for |
+|---|---|
+| [`install-with-frameport.svg`](badges/install-with-frameport.svg) | Everywhere. No motion. |
+| [`install-with-frameport-animated.svg`](badges/install-with-frameport-animated.svg) | GitHub READMEs and other pages that only allow images. The glow plays by itself every 6 seconds: blue swells from the left, the portal between "Frame" and "Port" flares, then orange swells on the right. |
+| [`install-with-frameport-hover.svg`](badges/install-with-frameport-hover.svg) | Websites where you can paste HTML. The glow brightens and the middle portal lights up while the pointer is on the button. It only reacts to the mouse when the SVG code is placed in the page itself (see below). |
+| [`install-with-frameport@2x.png`](badges/install-with-frameport@2x.png) | Places without SVG support (some forums, email). 432 × 120; show it at 216 × 60. |
+
+Both animated versions stop moving for visitors who turn on reduced motion in their system settings.
+
+## The link
+
+The button links to an install link, which names either a manifest or one file:
+
+```
+frameport://install?manifest=<URL-encoded https address of a manifest .json>
+frameport://install?url=<URL-encoded https address of an .apk, a Linux build (.zip, .tar.*, .AppImage) or a Windows .exe>
+```
+
+The manifest is the FrameDrop format, which FramePort reads as it is:
+
+```json
+{
+  "schema": "framedrop.install/v1",
+  "name": "My Game",
+  "files": [{ "url": "https://example.com/my-game.apk", "sha256": "<64 hex digits>" }],
+  "frameport": { "description": "One sentence about the game.", "icon": "https://example.com/icon.png" }
+}
+```
+
+`name` becomes the game's title in Steam. `sha256` is optional but recommended: FramePort checks the download
+against it. The `frameport` object is optional and ignored by FrameDrop; its icon and description are shown in the
+install question. Only public `https://` addresses are accepted.
+
+To build a link from Python: `frameport.deeplink.make_link(manifest_url="https://…/my-game.json")`.
+
+## On a website
+
+Image version (any page):
+
+```html
+<a href="frameport://install?manifest=https%3A%2F%2Fexample.com%2Fmy-game.json">
+  <img src="install-with-frameport.svg" alt="Install with FramePort" width="216" height="60">
+</a>
+```
+
+Hover version: paste the contents of `install-with-frameport-hover.svg` inside the link instead of the `<img>`, and
+give the link an accessible name:
+
+```html
+<a href="frameport://install?manifest=https%3A%2F%2Fexample.com%2Fmy-game.json" aria-label="Install with FramePort">
+  <svg …>…</svg>  <!-- the whole file -->
+</a>
+```
+
+Host the files yourself, or load them from jsDelivr, which serves them with the right content type:
+`https://cdn.jsdelivr.net/gh/spoopyghosty0/frameport@main/docs/badges/install-with-frameport.svg` (replace `main`
+with a release tag such as `v0.12.0` to pin a version; jsDelivr caches `@main` for up to 12 hours).
+
+## In a GitHub README
+
+GitHub removes links that don't start with `https://` or `http://` from READMEs, so a `frameport://` link there is
+not clickable. Link the button to an `https://` page instead, for example your release page with instructions, or
+FrameDrop's install page, which opens `framedrop://` links (FramePort opens those too while Settings → Install links
+→ `framedrop://` is on):
+
+```markdown
+[![Install with FramePort](https://cdn.jsdelivr.net/gh/spoopyghosty0/frameport@main/docs/badges/install-with-frameport-animated.svg)](https://framedropvr.com/install?manifest=https%3A%2F%2Fexample.com%2Fmy-game.json)
+```
+
+Use the animated or still SVG; the hover version doesn't react inside a README, because GitHub shows SVGs as
+images.
+
+## If a visitor doesn't have FramePort
+
+A `frameport://` link does nothing visible (or shows the browser's "no app for this link" message) when FramePort
+isn't installed. Put a line next to the button such as "Needs [FramePort](https://github.com/spoopyghosty0/frameport)
+on Windows or Linux." On macOS, web pages can't hand links to FramePort yet: users paste the link into Add games →
+Add from a link….
+
+## Usage rules
+
+- Keep the alt text "Install with FramePort".
+- Don't recolor, stretch, crop or redraw the button, and don't show it smaller than 40 px tall.
+- Leave some space around it (at least 8 px) so it doesn't touch other buttons.
+- It works on light and dark pages as it is; there is no light version.
@@ -13,6 +13,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 ## Startup failures (visible in launch.log)
 | Symptom | Cause | Fix |
 |---|---|---|
+| A launch test suggests a fix (e.g. triage `sdl-no-clipboard` → `frame.sdl_clipboard`) but the game page doesn't show it / lists it as not applicable; or a game added long ago lacks warnings newer ones get (Android version, web wrapper, missing OBB) (GitHub #104, Dramatic Shape) | the library entry was analysed by an older FramePort: the analysis field the patch reads (`sdl_java`, `min_sdk`, `web_wrapper`, `expects_obb`, …) is missing, so `applies()` is false | entries whose `analysis.extra.analysis_version` is below `detect.ANALYSIS_VERSION` are analysed again at the GUI's start (background) and before a build (`pipeline.refresh_analyses`); by hand: game menu → "Analyze again", then Update on Frame. An unreadable APK is marked `analysis_failed` (retried after the next version bump). Adding an analysis field: bump `ANALYSIS_VERSION` |
 | One eye (usually the right) shimmers or jitters in the 3D view while menus and panels look steady; pacing is clean (GitHub #69, e.g. RTCWQuest, Moss) | Valve's eye-tracked foveation layer (`VALVE_fdm_injection`) moves its low-density regions with each eye's gaze, and the right eye's gaze filter restarts often (`CEyePoseUKF R: Large dt … Bootstrapped` in `~/.local/share/Steam/logs/eyetracking.txt`) | Customize → "Eye-tracked foveation (Valve)" (`device.foveation`): **Fixed** (`FDM_DEBUG=disable_offsets`, keeps the GPU saving) or **Off** (`VK_INSTANCE_LAYERS=""`); catalog field `foveation:` |
 | A Unity OpenXR game closes right after the OpenXR instance is created: `F VrApiLoader: vrapi_SetPropertyInt was called before vrapi_Initialize()!`, SIGABRT on UnityMain (GitHub #62, Jurassic World Aftermath) | the APK still ships Meta's VrApi loader; OVRPlugin (1.89, on OpenXR) calls it without starting VrApi and Meta's loader aborts. The VrApi bridge can't replace it (39 of the loader's 114 functions: OVRPlugin wouldn't link) | `frame.vrapi_stub` (same exports, each returns 0); triage `vrapi-before-init` |
 | A VrApi game exits at once: `UnsatisfiedLinkError … dlopen failed: cannot locate symbol "vrapi_PollEvent"` (GitHub #57, BlazeRush) | the engine imports a VrApi function the VrApi bridge didn't implement | the bridge has `vrapi_PollEvent`, `RecenterPose`, `SetDisplayRefreshRate`, `GetSystemPropertyFloatArray` (rebuild the game); the static check "VrApi functions resolvable" names any other missing one; triage `vrapi-symbol-missing` |
@@ -21,7 +22,11 @@ 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, Sniper Elite VR's tutorial grab: memory grows ~1 GB/s until the kill) | 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); also reached from Unity's legacy `ovrp_SetControllerHaptics`; perf page faults all in `libopenxr_loader.so` `xrApplyHapticFeedback` | `adapter.haptic_fix` (envelope → one plain vibration in `native/xrshim`; PCM vibrations (`XrHapticPcmVibrationFB`) are converted the same way). 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) |
+| A Linux app (AppImage) shows no/FramePort's placeholder icon in Desktop Mode or Steam (GitHub #99) | before agent v64 only FramePort's art set's icon was used, and a lone AppImage has no store art | connect FramePort once (agent v64 copies the app's `.DirIcon` / `.desktop` `Icon=` to `<anchor>/artwork/app-icon.*` and refreshes the menu entry); reinstall to also get it into the library + Steam shortcut. Still the placeholder: check `<base>/app/squashfs-root/.DirIcon` and the `.desktop` file's `Icon=` (an icon outside the app folder or only an XPM isn't used); a chosen icon (`artwork/.icon-source` = `custom`) always wins |
 | 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 +34,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 +47,19 @@ 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) |
+| Game hangs at start / never loads although its .obb files are right there: next to the APK, in an `obb` folder beside an `apk` folder inside a `<package>` folder, or a SideQuest backup (`<timestamp>_<versionCode>.apk`) (GitHub #85, #91) | No folder named after the package, so the folder-layout checks found nothing and no OBB was uploaded | `quest_dump.find_data` then looks for the files by name, `(main\|patch).<versionCode>.<package>.obb` (any case), in the APK's folder, its parent and up to 3 levels below each (folders with their own APKs are other games); prefers the folder and files of the APK's own versionCode, else the newest older, else any version. When that folder also holds other things (the APK itself, other games' OBBs), the library entry gets `data_files` and only those files are uploaded, counted and deleted with the game. Add the folder again |
+| 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 count too (`extra.unity_split`, `analysis/unity_split.py`): an XR-plugin build (Oculus XR Plugin / Unity OpenXR library) without `assets/bin/Data/UnitySubsystems/` in the APK, or BuildSettings listing more scenes than the APK has `levelN` files (globalgamemanagers loose or read from the head of data.unity3d); exact on the 48 Unity APKs of the dumps (13 split, 17 full games; OBBs of full builds are asset bundles or sound banks) |
 | `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 |
@@ -68,14 +79,20 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Batman: Arkham Shadow closes during smoke-bomb effects; later input-tree corruption | Meta XR Audio Wwise deletes queued metadata still referenced by the current audio frame, then writes through the stale pointer | FrameBridge automatically retires metadata after current-frame references disappear, for the verified AArch64 SDK build only; see [AUDIO_METADATA.md](AUDIO_METADATA.md) |
 | Game stays on a loading or "Waiting" box although it reached FOCUSED; log `FrameBridge: xrEndFrame failed -25` then no more `pacing:` lines (e.g. PowerWash Simulator on some Frames, GitHub #39) | The eye image rect ends a few pixels past its swapchain (Unity rounds the swapchain width, the runtime's recommended size differs per Frame); SteamVR rejects every frame with XR_ERROR_SWAPCHAIN_RECT_INVALID | FrameBridge clamps every projection/quad image rect to its swapchain (`rect_clamp`, default on since 0.11.0; log `rect_clamp: view N image rect clamped`): rebuild + reinstall the game |
 | Game (Unity, GLES) freezes, `zink: DEVICE LOST` | multisampled render-to-texture hangs the GPU | `frame.unity_no_msaa`; if it persists: unfixable → PC version |
+| Unreal GLES game crashes ~3 s after start: `Fatal signal 11 … fault addr 0x10000 in tid … (RHIThread)`, `#01 … libgallium_dri.so` (GitHub #83 Star Wars Pinball VR, triage `unreal-msrtt-crash`) | Unreal's mobile MSAA renders through multisampled render-to-texture; Zink's `find_rp_state` then indexes `rendering_state_cache[6]` one past its end (sample count ≥ 32) and calls a junk hash function (0x10000). Mesa bug (no bounds check) | `frame.unreal_gl_shim` (GL shim with `gl_hide_msrtt`, multiview kept for Unreal: Unreal 4.25 only enables multiview with GL_OVR_multiview, GL_OVR_multiview2 **and** GL_OVR_multiview_multisampled_render_to_texture, so the shim keeps the last one visible for Unreal and maps glFramebufferTextureMultisampleMultiviewOVR to the single-sampled glFramebufferTextureMultiviewOVR; log `multiview multisampled render-to-texture (N samples) drawn single-sampled`) |
+| Crash with `SIGILL (ILL_ILLOPN)` and `*pc=0xd50323bf` (autiasp), e.g. on Unreal's HttpManager thread (GitHub #83 Star Wars Pinball VR, triage `pac-unpaired`) | The engine's OpenSSL ARMv8 assembly has autiasp without a matching paciasp (libUE4.so: 38 paciasp, 40 autiasp; Poly1305 NEON). Quest CPUs treat PAC hints as NOPs, the Frame's CPU checks them | `frame.pac_hints`: in a library with unpaired counts every paciasp/autiasp becomes a NOP (in place) |
+| Unreal game (OVRPlugin) never starts VR: launch.log has `OVRPlugin: JNI_OnLoad` but never `CompositorOpenXR::PreInitialize`, no OpenXR session, then a crash a few seconds in (e.g. Star Wars Pinball VR, UE 4.25: null pointer in `FSceneRenderer::GetMultiViewSceneColor`, GitHub #83) | Unreal's Oculus module looks up every `ovrp_*` function of the OVRPlugin it was built against (`InitializeOculusPluginWrapper`, all ANDed); OVRPort's OpenXR OVRPlugin lacks a few old ones (UE 4.25 / OVRPlugin 1.44: `ovrp_GetPTWNear`), so the wrapper fails and OculusHMD is never pre-initialised | `frame.unreal_ovrp_entrypoints` (suggested when analysis `unreal_ovrp_lookups` name functions the shipped OVRPlugin lacks): generated `libfp_ovrpstubs.so` (DT_NEEDED of libOVRPlugin.so; dlsym on the plugin's handle searches its dependencies) with a stand-in per missing name returning ovrpFailure (-1000); build note lists the names |
 | Only the Android home screen shows; the log has Unity's VR device as `None` (e.g. Accounting+, Unity 2017) | Unity 2017–2018 built-in Oculus support starts VR only when `com.oculus.systemactivities` is installed; Lepton has no Meta system apps, so Unity falls back to non-VR | `frame.unity_oculus_check`: that package name in libunity.so → `android`, plus `native/ovrpshim` (libfp_ovrp.so): Unity 2017's legacy frame loop (`ovrp_Update2`/`ovrp_BeginFrame`) never calls `ovrp_WaitToBeginFrame`, so without the shim no `xrWaitFrame` happens, `CompositorOpenXR::Update … outside of frame bounds` floods the log and the dashboard freezes. With it: log `ovrp frame loop shim: waited for frame N`, ~71 fps. Accounting+ then stops at "press any button" although its OVRInput gets clean input (`INPUT_PROBE` in the patch logs connected controllers/buttons/input focus per call) — unresolved |
 | Black flat window, then a GPU hang: kernel `hangcheck detected gpu lockup` (offending task the game), `zink: DEVICE LOST`, Unity render-thread crash; `outside of frame bounds` thousands of times a second (e.g. BattleSisters, Unity 2019.4) | Unity 2019 on its built-in VR (no `libOculusXRPlugin.so`) uses the same legacy frame loop as Unity 2017: no `xrWaitFrame`, the render thread floods the GPU | `frame.unity_oculus_check` adds the ovrpshim frame wait for these too (revision 2) |
+| Unity built-in VR game (with `frame.unity_oculus_check`) freezes at a scene switch: the log stops after `Boot: Activating Scene: …`, the process stays alive, every thread sleeps (e.g. Sniper Elite VR, Unity 2019.4) | The shim's `xrWaitFrame` blocks until the previously waited frame is begun; Unity skipped beginning it at the scene switch and its render thread then waited for the main thread (gdb: UnityMain in vrclient `CSxrSession::StartNextFrame` ← `ovrp_WaitToBeginFrame` ← `fpov_Update2`). OVRPlugin also only begins the frame index it waited for | `frame.unity_oculus_check` revision 5: libunity.so's `ovrp_BeginFrame`/`ovrp_EndFrame` go through the shim, which waits ≤ 50 ms for the last waited frame to begin, else skips the wait (log `the last waited frame wasn't begun`), and gives a begin/end of another index the waited one |
+| Unity built-in VR game: the hands/weapons trail the controllers by centimetres when moving (headset fine, 72 fps), e.g. Sniper Elite VR | Unity's physics-step `ovrp_Update2` (prediction 0) makes OVRPlugin locate the nodes at the monotonic clock's "now", the XrTime base on a Quest but 0.05–0.9 s behind the Frame's XrTime; the runtime extrapolates backwards and the render-step reads after it get those poses too. A larger prediction is capped by OVRPlugin (~0.07 s) | `frame.unity_oculus_check` revision 5 holds the physics-step update back: both steps read the render update's display-time poses |
 | Unreal game stuck on a loading image after the intro, frames keep coming (72 fps), no crash (e.g. Vader Immortal) | suspect: a Meta Platform SDK request no message ever answers | diagnostics: `frame.ovr_trace` (opt-in) logs every `ovr_*` call, the answers `ovr_PopMessage` returns and every 10 s the unanswered requests (`fp_ovrtrace` in launch.log). Never fake an entitlement answer |
 | Own-engine game crashes in `libVkLayer_fossilize.so` (Fossilize's recording thread, e.g. Roblox) | same as Deadpool VR: uninitialised pointers in what Fossilize records | `frame.vk_sanitize` now also covers own-engine libraries that load `libvulkan.so` by name |
 | Crash right after the game gets focus, in `vrclient.so … UpdateActionStateInternal` / `sxr_xrSyncActions` (e.g. Myst) | a race in the Frame runtime's input code on the first sync after focus (not every launch) | adapter `sync_guard` (input syncs one at a time with event polling, paused 250 ms after FOCUSED) |
 | 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 +102,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 → Add 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) |
@@ -101,16 +120,27 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | View vibrates even when holding still after `frame.unity_multipass` (I Am Cat) | poses/times are consistent, but two passes on Zink make every frame one period late, and the game clamps its physics step to 10 ms | not fixed (scale 0.8 didn't help); next ideas: fix multiview instead, or the game's fixed timestep |
 | Game freezes / pauses for 0.5-2 s now and then, no flicker (e.g. Blade & Sorcery, Lucky's Tale) | the headset's wear sensor flickers off while worn (`logs/eyetracking.txt` `HMD off, stopping eye tracking` … `HMD on`), the Frame turns it into a focus loss and Quest games that pause on focus loss pause | adapter `focus_hold` (on by default since 2026-10-05, dips up to `focus_hold_ms` = 5000 ms are hidden; longer ones still pause) |
 | Minor glitches on some objects (Myst, Unreal Vulkan) | unknown; not application space warp (turning it off changed nothing and ran worse) | unresolved |
-| Graphics crash in vkCreateInstance with pc == fault address, from the game's own Vulkan hooks (BONELAB 1.2974 `libSLZQuestNative`) | a pointer into memory freed with OVRPlugin's pre-init OpenXR instance; not the runtime (vrclient.so) or Fossilize being unloaded (keeping both loaded with RTLD_NODELETE didn't help) | unresolved |
+| Unity game crashes or hangs right as Vulkan starts, after `SLZ Graphics plugin loading!` and OVRPlugin's pre-init `xrDestroyInstance`: SIGSEGV with pc 0 (or pc == fault address in an unloaded library), x16/x23 in `libSLZQuestNative.so` (BONELAB 1.2974) | Stress Level Zero's graphics plugin hooks Unity's Vulkan start-up (IUnityGraphicsVulkanV2 interception: vkCreateInstance/vkCreateDevice) and vkCreateSampler; its vkCreateInstance wrapper calls an invalid pointer on the Frame | `frame.slz_vulkan_hooks` (its two registrations become no-ops; Unity starts Vulkan itself; ~35 s of shader prewarming without its pipeline cache) |
 | Unity game shows a picture but the player body is frozen: no head tracking, the controllers stay on the model, no buttons, although OpenXR input works (BONELAB 1.2068, Oculus XR Plugin) | OVRPlugin reports the headset as not worn (`ovrp_GetUserPresent2` → 0) a few seconds after start, and the game's rig only follows a present user (Marrow `XRHMD.IsUserPresent` = Unity's HMD `UserPresence`) | `frame.unity_user_presence` (the Oculus XR Plugin's lookup → `libfp_ovrp.so`, reports present; log `user presence: OVRPlugin 0 …`) |
 | Unreal 5 game crashes at its first render pass, backtrace `vulkan.freedreno.so` ← `libVkLayer_fossilize.so` ← `libfp_vk.so (create_render_pass2)` (Metro Awakening) | a subpass without a depth attachment names a depth/stencil resolve attachment; the Frame's Turnip reads the missing depth attachment (NULL) | the Vulkan shim drops that resolve (always, FramePort after 0.11.0; log `dropped the depth resolve of subpass N (no depth attachment)`); triage `unreal-vulkan-driver-crash` |
 | 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).
@@ -126,6 +156,14 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
  touching new memory (`perf script -F comm,tid,ip,dso`); `-t <tid> -F 499` samples one thread. Map IL2CPP
  addresses with a full Cpp2IL diffable-cs dump (method `Offset` = address − the r-xp mapping of libil2cpp.so).
  Sample memory per mapping name from `/proc/<pid>/smaps` (`[anon:libc_malloc]` = native heap).
+- Hangs (every thread asleep): backtraces of all threads with gdb. Root inside the Lepton container may ptrace the
+  game (the host's `ptrace_scope` 1 doesn't apply there) and the guest has `gdbserver64`; `debuggerd -b` fails (no
+  tombstoned). Copy every mapped library to a local sysroot (`podman exec <container> cat /proc/<pid>/maps`, then
+  `tar -chf - -T <list>` through `podman exec -i`; the app's own libs from the installed `lepton-app/game.apk` at their
+  `/data/app/…/lib/arm64` path), then on the PC: `gdb -batch -ex "set sysroot <dir>" -ex "target remote | ssh
+  steamos@<frame> podman exec -i lepton-steamlaunch-<appid> gdbserver64 - --attach <pid in the container>" -ex
+  "thread apply all bt 25" -ex detach` (`set sysroot target:` makes gdbserver assert in linux_mntns_readlink).
+  `/proc/<pid>/task/*/syscall` (read inside the container) shows each thread's syscall and pc without a debugger.
 - Unity catches native crashes itself: no debuggerd backtrace in Lepton's logcat-crash.log, but a
  `tombstone_00` in the game's `Android/data/<pkg>/files/` with the memory map (map pc/lr/registers to libraries).
 - Focus losses: the game sees FOCUSED→VISIBLE→SYNCHRONIZED (OVRPlugin `[XR_SESSION]`, FrameBridge `focus_hold:`
@@ -0,0 +1,61 @@
+# Themes
+
+FramePort comes with three colour themes, all dark:
+
+| Theme | Look |
+|---|---|
+| **Portal** (default) | The logo's two portals: orange for actions and the current selection, blue for secondary actions, progress and the PC side. |
+| **Portal (OLED)** | Portal on true black, for OLED screens. |
+| **Original** | FramePort's first look, with a violet accent. |
+
+Switch in **Settings → Appearance**. The change applies at once.
+
+## Your own theme
+
+A theme is a small JSON file. To make one:
+
+1. In **Settings → Appearance**, pick the theme closest to what you want and click **Copy this theme as a file**.
+2. Paste it into a text editor and save it as `something.json`.
+3. Change the name and the colours you want different. You can delete every colour you keep: missing colours come
+   from the `base` theme.
+4. Back in **Settings → Appearance**, click **Install theme file…** and choose the file. FramePort checks it,
+   switches to it and keeps a copy in its data folder (`themes/`), so you can delete the original.
+
+To remove an installed theme, click the bin icon on its card.
+
+### Format
+
+```json
+{
+  "name": "Ember & Ice",
+  "base": "portal",
+  "dual": true,
+  "colors": {
+    "ACCENT": "#FF5A36",
+    "SECONDARY": "#5CE1E6"
+  }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `name` | Shown on the theme's card (up to 40 characters). |
+| `base` | The built-in theme that fills in every colour the file leaves out: `portal` (default), `portal_oled` or `original`. |
+| `dual` | `true`: two-colour touches like Portal's (blue-to-orange sidebar edge, two-colour "FramePort", the selected tab's fade, blue secondary buttons). `false`: one accent, like Original. Default: the base's. |
+| `colors` | Any of the colours below, as `#RRGGBB` or `#RGB`. Names may be upper or lower case. |
+
+| Colour | Used for |
+|---|---|
+| `BG` | Window background |
+| `SIDEBAR` | Sidebar and activity panel |
+| `SURFACE`, `SURFACE_2`, `SURFACE_3` | Cards; raised and hovered parts; inputs and chips |
+| `BORDER`, `BORDER_STRONG` | Outlines |
+| `TEXT`, `TEXT_2`, `TEXT_3` | Main text; secondary text; captions and disabled text |
+| `ACCENT`, `ACCENT_SOFT`, `ON_ACCENT` | Main buttons and the current selection; its tint; text on it |
+| `SECONDARY`, `SECONDARY_SOFT` | Secondary buttons, progress, switch tracks; its tint |
+| `OK`, `WARN`, `ERROR`, `INFO` | Status: works, needs attention, failed, information |
+| `PC` | PC VR games and "on this PC" |
+
+FramePort refuses a theme file it can't show well, and says why: a light window background (FramePort is dark only),
+text that's hard to read on cards, an unknown colour name or a value that isn't a colour. An example is in
+[`themes/example-theme.json`](themes/example-theme.json).
@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="216" height="60" viewBox="0 0 216 60" role="img" aria-label="Install with FramePort"><title>Install with FramePort</title><style>.fp-wb,.fp-wo{transform-box:view-box}
+.fp-wb{transform-origin:0 0;animation:fp-wb 6s ease-in-out infinite}
+.fp-wo{transform-origin:216px 0;animation:fp-wo 6s ease-in-out infinite}
+.fp-core{animation:fp-core 6s ease-in-out infinite}
+@keyframes fp-wb{0%,10%,100%{opacity:.45;transform:scaleX(1)}32%{opacity:1;transform:scaleX(1.5)}54%{opacity:.3;transform:scaleX(1)}}
+@keyframes fp-core{0%,28%,100%{opacity:0}42%{opacity:1}60%{opacity:0}}
+@keyframes fp-wo{0%,38%,100%{opacity:.6;transform:scaleX(1)}60%{opacity:1;transform:scaleX(1.4)}84%{opacity:.6;transform:scaleX(1)}}
+@media (prefers-reduced-motion:reduce){.fp-wb,.fp-wo,.fp-core{animation:none!important}}</style><defs>
+  <linearGradient id="fab" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".46"/><stop offset=".55" stop-color="#3AA8FF" stop-opacity="0"/></linearGradient>
+  <linearGradient id="fao" x1="0" y1="0" x2="1" y2="0"><stop offset=".45" stop-color="#FF8A1F" stop-opacity="0"/><stop offset="1" stop-color="#FF8A1F" stop-opacity=".34"/></linearGradient>
+  <radialGradient id="far" gradientUnits="userSpaceOnUse" cx="122" cy="39" r="46" gradientTransform="translate(122 39) scale(1 .62) translate(-122 -39)"><stop offset="0" stop-color="#FFE2BD" stop-opacity=".42"/><stop offset=".25" stop-color="#FF8A1F" stop-opacity=".2"/><stop offset=".6" stop-color="#3AA8FF" stop-opacity=".08"/><stop offset="1" stop-color="#3AA8FF" stop-opacity="0"/></radialGradient>
+  <clipPath id="fac"><rect x="1" y="1" width="214" height="58" rx="11.5"/></clipPath></defs>
+  <rect x=".5" y=".5" width="215" height="59" rx="12" fill="#0D0E12" stroke="#2A2D37"/>
+  <g clip-path="url(#fac)"><rect class="fp-wb" x="1" y="1" width="214" height="58" fill="url(#fab)" opacity=".45"/><rect class="fp-wo" x="1" y="1" width="214" height="58" fill="url(#fao)" opacity=".6"/><rect class="fp-core" x="1" y="1" width="214" height="58" fill="url(#far)" opacity="0"/></g>
+  <g transform="translate(10 10) scale(0.625)">
+  <defs><linearGradient id="fal0" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".18"/><stop offset=".5" stop-color="#3AA8FF" stop-opacity="0"/><stop offset=".5" stop-color="#FF8A1F" stop-opacity="0"/><stop offset="1" stop-color="#FF8A1F" stop-opacity=".18"/></linearGradient>
+  <linearGradient id="fal1" gradientUnits="userSpaceOnUse" x1="26" y1="0" x2="38" y2="0"><stop offset=".3" stop-color="#3AA8FF"/><stop offset=".7" stop-color="#FF8A1F"/></linearGradient>
+  <clipPath id="fal2"><polygon points="-30,-30 49.145,-30 8.855,94 -30,94"/></clipPath><clipPath id="fal3"><polygon points="55.145,-30 94,-30 94,94 14.855,94"/></clipPath></defs>
+  <rect width="64" height="64" rx="15" fill="#101218"/><rect width="64" height="64" rx="15" fill="url(#fal0)"/>
+  <g clip-path="url(#fal2)"><path d="M34 15H9a3 3 0 0 0-3 3v20a3 3 0 0 0 3 3h25z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"/><rect class="fp-scr" x="10.5" y="19.5" width="24" height="17" rx="1" fill="#3AA8FF" fill-opacity="0.35"/><path d="M18 41v6M11 47h14" stroke="#ECEDF3" stroke-width="3" stroke-linecap="round"/></g>
+  <g clip-path="url(#fal3)"><path d="M56.5 31.5H58.5" stroke="#ECEDF3" stroke-width="3.4" stroke-linecap="round"/><path d="M22 21h27a8 8 0 0 1 8 8v5a8 8 0 0 1-8 8H48.65a3 3 0 0 1-2.6-1.5l-1-1.7a.9.9 0 0 0-1.6 0l-1 1.7a3 3 0 0 1-2.6 1.5H22z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"/><g class="fp-lens"><ellipse cx="39.5" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"/><ellipse cx="49" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"/></g></g>
+  <g transform="rotate(18 32 32)"><g class="fp-ptl"><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="#08090C" stroke="#08090C" stroke-width="5.8"/><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="none" stroke="url(#fal1)" stroke-opacity=".25" stroke-width="6.46" class="fp-halo"/><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="url(#fal1)" fill-opacity="0.14" stroke="url(#fal1)" stroke-width="3.4"/></g></g></g>
+  <text x="60" y="25" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="9.5" font-weight="600" letter-spacing="1.4" fill="#A7ABB7">INSTALL WITH</text>
+  <text x="60" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#FF8A1F" textLength="53.1" lengthAdjust="spacingAndGlyphs">Frame</text>
+  <g transform="translate(115.25999999999999 29.36) scale(0.8035714285714286)"><g class="fp-ptl"><defs><linearGradient id="fawr" gradientUnits="userSpaceOnUse" x1="2" y1="0" x2="14" y2="0"><stop offset=".3" stop-color="#FF8A1F"/><stop offset=".7" stop-color="#3AA8FF"/></linearGradient></defs>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="none" stroke="url(#fawr)" stroke-opacity=".35" stroke-width="5" class="fp-halo"/>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="#0D0E12" stroke="url(#fawr)" stroke-width="2.6"/></g></g>
+  <text x="130.27714285714285" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#3AA8FF" textLength="36.9" lengthAdjust="spacingAndGlyphs">Port</text></svg>
@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="216" height="60" viewBox="0 0 216 60" role="img" aria-label="Install with FramePort"><title>Install with FramePort</title><style>.fp-wb,.fp-wo{transform-box:view-box;transition:opacity .5s ease,transform .7s cubic-bezier(.2,.8,.2,1)}
+.fp-wb{transform-origin:0 0}.fp-wo{transform-origin:216px 0}
+.fp-core{transition:opacity .6s ease}
+svg:hover .fp-wb{opacity:1;transform:scaleX(1.4)}svg:hover .fp-wo{opacity:1;transform:scaleX(1.3)}
+svg:hover .fp-core{opacity:1}
+@media (prefers-reduced-motion:reduce){.fp-wb,.fp-wo,.fp-core{transition:none!important}}</style><defs>
+  <linearGradient id="fhb" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".46"></stop><stop offset=".55" stop-color="#3AA8FF" stop-opacity="0"></stop></linearGradient>
+  <linearGradient id="fho" x1="0" y1="0" x2="1" y2="0"><stop offset=".45" stop-color="#FF8A1F" stop-opacity="0"></stop><stop offset="1" stop-color="#FF8A1F" stop-opacity=".34"></stop></linearGradient>
+  <radialGradient id="fhr" gradientUnits="userSpaceOnUse" cx="122" cy="39" r="46" gradientTransform="translate(122 39) scale(1 .62) translate(-122 -39)"><stop offset="0" stop-color="#FFE2BD" stop-opacity=".42"></stop><stop offset=".25" stop-color="#FF8A1F" stop-opacity=".2"></stop><stop offset=".6" stop-color="#3AA8FF" stop-opacity=".08"></stop><stop offset="1" stop-color="#3AA8FF" stop-opacity="0"></stop></radialGradient>
+  <clipPath id="fhc"><rect x="1" y="1" width="214" height="58" rx="11.5"></rect></clipPath></defs>
+  <rect x=".5" y=".5" width="215" height="59" rx="12" fill="#0D0E12" stroke="#2A2D37"></rect>
+  <g clip-path="url(#fhc)"><rect class="fp-wb" x="1" y="1" width="214" height="58" fill="url(#fhb)" opacity=".45"></rect><rect class="fp-wo" x="1" y="1" width="214" height="58" fill="url(#fho)" opacity=".6"></rect><rect class="fp-core" x="1" y="1" width="214" height="58" fill="url(#fhr)" opacity="0"></rect></g>
+  <g transform="translate(10 10) scale(0.625)">
+  <defs><linearGradient id="fhl0" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".18"></stop><stop offset=".5" stop-color="#3AA8FF" stop-opacity="0"></stop><stop offset=".5" stop-color="#FF8A1F" stop-opacity="0"></stop><stop offset="1" stop-color="#FF8A1F" stop-opacity=".18"></stop></linearGradient>
+  <linearGradient id="fhl1" gradientUnits="userSpaceOnUse" x1="26" y1="0" x2="38" y2="0"><stop offset=".3" stop-color="#3AA8FF"></stop><stop offset=".7" stop-color="#FF8A1F"></stop></linearGradient>
+  <clipPath id="fhl2"><polygon points="-30,-30 49.145,-30 8.855,94 -30,94"></polygon></clipPath><clipPath id="fhl3"><polygon points="55.145,-30 94,-30 94,94 14.855,94"></polygon></clipPath></defs>
+  <rect width="64" height="64" rx="15" fill="#101218"></rect><rect width="64" height="64" rx="15" fill="url(#fhl0)"></rect>
+  <g clip-path="url(#fhl2)"><path d="M34 15H9a3 3 0 0 0-3 3v20a3 3 0 0 0 3 3h25z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"></path><rect class="fp-scr" x="10.5" y="19.5" width="24" height="17" rx="1" fill="#3AA8FF" fill-opacity="0.35"></rect><path d="M18 41v6M11 47h14" stroke="#ECEDF3" stroke-width="3" stroke-linecap="round"></path></g>
+  <g clip-path="url(#fhl3)"><path d="M56.5 31.5H58.5" stroke="#ECEDF3" stroke-width="3.4" stroke-linecap="round"></path><path d="M22 21h27a8 8 0 0 1 8 8v5a8 8 0 0 1-8 8H48.65a3 3 0 0 1-2.6-1.5l-1-1.7a.9.9 0 0 0-1.6 0l-1 1.7a3 3 0 0 1-2.6 1.5H22z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"></path><g class="fp-lens"><ellipse cx="39.5" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"></ellipse><ellipse cx="49" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"></ellipse></g></g>
+  <g transform="rotate(18 32 32)"><g class="fp-ptl"><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="#08090C" stroke="#08090C" stroke-width="5.8"></ellipse><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="none" stroke="url(#fhl1)" stroke-opacity=".25" stroke-width="6.46" class="fp-halo"></ellipse><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="url(#fhl1)" fill-opacity="0.14" stroke="url(#fhl1)" stroke-width="3.4"></ellipse></g></g></g>
+  <text x="60" y="25" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="9.5" font-weight="600" letter-spacing="1.4" fill="#A7ABB7">INSTALL WITH</text>
+  <text x="60" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#FF8A1F" textLength="53.1" lengthAdjust="spacingAndGlyphs">Frame</text>
+  <g transform="translate(115.25999999999999 29.36) scale(0.8035714285714286)"><g class="fp-ptl"><defs><linearGradient id="fhwr" gradientUnits="userSpaceOnUse" x1="2" y1="0" x2="14" y2="0"><stop offset=".3" stop-color="#FF8A1F"></stop><stop offset=".7" stop-color="#3AA8FF"></stop></linearGradient></defs>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="none" stroke="url(#fhwr)" stroke-opacity=".35" stroke-width="5" class="fp-halo"></ellipse>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="#0D0E12" stroke="url(#fhwr)" stroke-width="2.6"></ellipse></g></g>
+  <text x="130.27714285714285" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#3AA8FF" textLength="36.9" lengthAdjust="spacingAndGlyphs">Port</text></svg>
@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="216" height="60" viewBox="0 0 216 60" role="img" aria-label="Install with FramePort"><title>Install with FramePort</title><defs>
+  <linearGradient id="fsb" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".46"/><stop offset=".55" stop-color="#3AA8FF" stop-opacity="0"/></linearGradient>
+  <linearGradient id="fso" x1="0" y1="0" x2="1" y2="0"><stop offset=".45" stop-color="#FF8A1F" stop-opacity="0"/><stop offset="1" stop-color="#FF8A1F" stop-opacity=".34"/></linearGradient>
+  <radialGradient id="fsr" gradientUnits="userSpaceOnUse" cx="122" cy="39" r="46" gradientTransform="translate(122 39) scale(1 .62) translate(-122 -39)"><stop offset="0" stop-color="#FFE2BD" stop-opacity=".42"/><stop offset=".25" stop-color="#FF8A1F" stop-opacity=".2"/><stop offset=".6" stop-color="#3AA8FF" stop-opacity=".08"/><stop offset="1" stop-color="#3AA8FF" stop-opacity="0"/></radialGradient>
+  <clipPath id="fsc"><rect x="1" y="1" width="214" height="58" rx="11.5"/></clipPath></defs>
+  <rect x=".5" y=".5" width="215" height="59" rx="12" fill="#0D0E12" stroke="#2A2D37"/>
+  <g clip-path="url(#fsc)"><rect class="fp-wb" x="1" y="1" width="214" height="58" fill="url(#fsb)" opacity=".45"/><rect class="fp-wo" x="1" y="1" width="214" height="58" fill="url(#fso)" opacity=".6"/><rect class="fp-core" x="1" y="1" width="214" height="58" fill="url(#fsr)" opacity="0"/></g>
+  <g transform="translate(10 10) scale(0.625)">
+  <defs><linearGradient id="fsl0" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".18"/><stop offset=".5" stop-color="#3AA8FF" stop-opacity="0"/><stop offset=".5" stop-color="#FF8A1F" stop-opacity="0"/><stop offset="1" stop-color="#FF8A1F" stop-opacity=".18"/></linearGradient>
+  <linearGradient id="fsl1" gradientUnits="userSpaceOnUse" x1="26" y1="0" x2="38" y2="0"><stop offset=".3" stop-color="#3AA8FF"/><stop offset=".7" stop-color="#FF8A1F"/></linearGradient>
+  <clipPath id="fsl2"><polygon points="-30,-30 49.145,-30 8.855,94 -30,94"/></clipPath><clipPath id="fsl3"><polygon points="55.145,-30 94,-30 94,94 14.855,94"/></clipPath></defs>
+  <rect width="64" height="64" rx="15" fill="#101218"/><rect width="64" height="64" rx="15" fill="url(#fsl0)"/>
+  <g clip-path="url(#fsl2)"><path d="M34 15H9a3 3 0 0 0-3 3v20a3 3 0 0 0 3 3h25z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"/><rect class="fp-scr" x="10.5" y="19.5" width="24" height="17" rx="1" fill="#3AA8FF" fill-opacity="0.35"/><path d="M18 41v6M11 47h14" stroke="#ECEDF3" stroke-width="3" stroke-linecap="round"/></g>
+  <g clip-path="url(#fsl3)"><path d="M56.5 31.5H58.5" stroke="#ECEDF3" stroke-width="3.4" stroke-linecap="round"/><path d="M22 21h27a8 8 0 0 1 8 8v5a8 8 0 0 1-8 8H48.65a3 3 0 0 1-2.6-1.5l-1-1.7a.9.9 0 0 0-1.6 0l-1 1.7a3 3 0 0 1-2.6 1.5H22z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"/><g class="fp-lens"><ellipse cx="39.5" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"/><ellipse cx="49" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"/></g></g>
+  <g transform="rotate(18 32 32)"><g class="fp-ptl"><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="#08090C" stroke="#08090C" stroke-width="5.8"/><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="none" stroke="url(#fsl1)" stroke-opacity=".25" stroke-width="6.46" class="fp-halo"/><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="url(#fsl1)" fill-opacity="0.14" stroke="url(#fsl1)" stroke-width="3.4"/></g></g></g>
+  <text x="60" y="25" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="9.5" font-weight="600" letter-spacing="1.4" fill="#A7ABB7">INSTALL WITH</text>
+  <text x="60" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#FF8A1F" textLength="53.1" lengthAdjust="spacingAndGlyphs">Frame</text>
+  <g transform="translate(115.25999999999999 29.36) scale(0.8035714285714286)"><g class="fp-ptl"><defs><linearGradient id="fswr" gradientUnits="userSpaceOnUse" x1="2" y1="0" x2="14" y2="0"><stop offset=".3" stop-color="#FF8A1F"/><stop offset=".7" stop-color="#3AA8FF"/></linearGradient></defs>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="none" stroke="url(#fswr)" stroke-opacity=".35" stroke-width="5" class="fp-halo"/>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="#0D0E12" stroke="url(#fswr)" stroke-width="2.6"/></g></g>
+  <text x="130.27714285714285" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#3AA8FF" textLength="36.9" lengthAdjust="spacingAndGlyphs">Port</text></svg>
@@ -0,0 +1,13 @@
+{
+  "name": "Ember & Ice",
+  "base": "portal",
+  "dual": true,
+  "colors": {
+    "ACCENT": "#FF5A36",
+    "ACCENT_SOFT": "#3A1710",
+    "SECONDARY": "#5CE1E6",
+    "SECONDARY_SOFT": "#0E3033",
+    "PC": "#5CE1E6",
+    "INFO": "#5CE1E6"
+  }
+}
@@ -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
@@ -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);
 }

@@ -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)));
+}
@@ -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;
@@ -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]()
@@ -30,8 +30,13 @@ static void (*real_glGetIntegerv)(GLenum, GLint *);
 static __eglMustCastToProperFunctionPointerType (*real_eglGetProcAddress)(const char *);
 static pthread_once_t once = PTHREAD_ONCE_INIT;

-static int hide_multiview = -1;  // -1: not set (Unity keeps multiview, everything else hides it)
+static int hide_multiview = -1;  // -1: not set (Unity and Unreal keep multiview, everything else hides it)
 static int hide_msrtt = 1;
+// Unreal (4.25) only turns on its mobile multiview when GL_OVR_multiview, GL_OVR_multiview2 AND
+// GL_OVR_multiview_multisampled_render_to_texture are all there (FOpenGLES::ProcessExtensions). Hiding the last one
+// with the MSRTT extensions switched Unreal's multiview off, so for Unreal it stays visible and its function draws
+// single-sampled (glFramebufferTextureMultiviewOVR), like the EXT stand-ins below.
+static int unreal;

 static void read_conf_file(const char *path) {
    FILE *f = fopen(path, "r");
@@ -335,12 +340,21 @@ static void init(void) {
    real_glGetStringi = gles ? dlsym(gles, "glGetStringi") : NULL;
    real_glGetIntegerv = gles ? dlsym(gles, "glGetIntegerv") : NULL;
    real_eglGetProcAddress = egl ? dlsym(egl, "eglGetProcAddress") : NULL;
-    if (hide_multiview < 0) {  // Unity renders multiview itself and only needs MSRTT hidden
-        void *unity = dlopen("libunity.so", RTLD_NOW | RTLD_NOLOAD);
-        hide_multiview = unity ? 0 : 1;
-        if (unity) dlclose(unity);
+    static const char *const engines[] = {"libunity.so", "libUE4.so", "libUnreal.so"};
+    int engine_found = 0;
+    for (unsigned i = 0; i < sizeof engines / sizeof *engines && !engine_found; i++) {
+        void *engine = dlopen(engines[i], RTLD_NOW | RTLD_NOLOAD);
+        if (engine) {
+            engine_found = 1;
+            unreal = i > 0;
+            dlclose(engine);
+        }
    }
-    LOG("GL shim active: hide_multiview=%d hide_msrtt=%d", hide_multiview, hide_msrtt);
+    // Unity and Unreal render multiview themselves and only need MSRTT hidden
+    if (hide_multiview < 0) hide_multiview = !engine_found;
+    unreal = unreal && hide_msrtt && !hide_multiview;  // only matters while MSRTT is hidden and multiview kept
+    LOG("GL shim active: hide_multiview=%d hide_msrtt=%d%s", hide_multiview, hide_msrtt,
+        unreal ? " (Unreal: multiview MSRTT kept, drawn single-sampled)" : "");
 }

 static int is_hidden(const char *name) {
@@ -349,7 +363,8 @@ static int is_hidden(const char *name) {
            if (!strcmp(name, hidden_multiview[i])) return 1;
    if (hide_msrtt)
        for (size_t i = 0; i < sizeof(hidden_msrtt) / sizeof(hidden_msrtt[0]); ++i)
-            if (!strcmp(name, hidden_msrtt[i])) return 1;
+            if (!strcmp(name, hidden_msrtt[i]))
+                return !(unreal && !strcmp(name, "GL_OVR_multiview_multisampled_render_to_texture"));
    return 0;
 }

@@ -416,6 +431,14 @@ static void plain_rbsms(GLenum target, GLsizei samples, GLenum format, GLsizei w
    (void)samples;
    if (r_plain_rbs) r_plain_rbs(target, format, width, height);
 }
+static PFN_FTMV r_plain_ftmv;
+static int mv_msrtt_logged;
+static void plain_ftmsmv(GLenum target, GLenum attachment, GLuint texture, GLint level, GLsizei samples,
+                         GLint base, GLsizei views) {
+    if (!mv_msrtt_logged++)
+        LOG("GL shim: multiview multisampled render-to-texture (%d samples) drawn single-sampled", (int)samples);
+    if (r_plain_ftmv) r_plain_ftmv(target, attachment, texture, level, base, views);
+}

 __attribute__((visibility("default"))) __eglMustCastToProperFunctionPointerType eglGetProcAddress(const char *name) {
    pthread_once(&once, init);
@@ -432,6 +455,10 @@ __attribute__((visibility("default"))) __eglMustCastToProperFunctionPointerType
        return name[2] == 'F' ? (__eglMustCastToProperFunctionPointerType)plain_ft2dms
                              : (__eglMustCastToProperFunctionPointerType)plain_rbsms;
    }
+    if (unreal && !strcmp(name, "glFramebufferTextureMultisampleMultiviewOVR")) {
+        if (!r_plain_ftmv) r_plain_ftmv = (PFN_FTMV)real_eglGetProcAddress("glFramebufferTextureMultiviewOVR");
+        return (__eglMustCastToProperFunctionPointerType)plain_ftmsmv;
+    }
 #ifdef GLSHIM_TRACE  // build with -DGLSHIM_TRACE for eye-buffer / draw / error tracing
    WRAP("glFramebufferTextureMultiviewOVR", real_ftmv, w_ftmv)
    WRAP("glFramebufferTextureMultisampleMultiviewOVR", real_ftmsmv, w_ftmsmv)
@@ -9,10 +9,14 @@
 //
 // FramePort renames the "ovrp_Update2" lookup in libunity.so to "fpov_Update2" (same length) and adds this library to
 // libOVRPlugin.so's DT_NEEDED, so Unity's dlsym on the plugin finds this function: it waits for the frame first (once
-// per frame index, render step only), then calls the real ovrp_Update2.
+// per frame index, render step only), then calls the real ovrp_Update2 (render step; the physics step: see below).
 #include <android/log.h>
 #include <dlfcn.h>
 #include <pthread.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>

 #define TAG "FrameBridge"
 #define EXPORT __attribute__((visibility("default")))
@@ -25,31 +29,168 @@ static PFN_Update2 real_update2;
 static PFN_WaitToBeginFrame real_wait;
 static pthread_once_t once = PTHREAD_ONCE_INIT;

+// Per-game settings (the same sources as FrameBridge and the GL shim, later ones winning): the frame-begin gate and
+// the held-back physics update below were needed by Sniper Elite VR; in Unity 2019 games (BattleSisters) holding the
+// physics update back made the hands lag and the gate made loading screens stutter, so both are off unless the recipe
+// turns them on (ovrp_begin_gate=1, ovrp_hold_physics=1).
+static int begin_gate, hold_physics;
+
+static void read_conf_file(const char *path) {
+    FILE *f = fopen(path, "r");
+    if (!f) return;
+    char line[256];
+    while (fgets(line, sizeof(line), f)) {
+        if (!strncmp(line, "ovrp_begin_gate=", 16)) begin_gate = atoi(line + 16);
+        if (!strncmp(line, "ovrp_hold_physics=", 18)) hold_physics = atoi(line + 18);
+    }
+    fclose(f);
+}
+
+static void read_conf(void) {
+    Dl_info info;
+    char path[600];
+    if (dladdr((void *)read_conf, &info) && info.dli_fname) {
+        const char *slash = strrchr(info.dli_fname, '/');
+        if (slash && slash - info.dli_fname < 500) {
+            snprintf(path, sizeof(path), "%.*s/libframe_settings.so", (int)(slash - info.dli_fname), info.dli_fname);
+            read_conf_file(path);
+        }
+    }
+    char pkg[256] = {0};
+    FILE *f = fopen("/proc/self/cmdline", "r");
+    if (f) {
+        size_t n = fread(pkg, 1, sizeof(pkg) - 1, f);
+        fclose(f);
+        pkg[n] = 0;
+    }
+    char *colon = strchr(pkg, ':');
+    if (colon) *colon = 0;
+    if (*pkg && !strchr(pkg, '/')) {
+        snprintf(path, sizeof(path), "/sdcard/Android/data/%s/files/framebridge.conf", pkg);
+        read_conf_file(path);
+    }
+    const char *env = getenv("FRAMEBRIDGE_CONFIG");
+    if (env && *env) read_conf_file(env);
+}
+
 static void init(void) {
+    read_conf();
    void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
    if (!ovrp) ovrp = dlopen("libOVRPlugin.so", RTLD_NOW);
    if (ovrp) {
        real_update2 = (PFN_Update2)dlsym(ovrp, "ovrp_Update2");
        real_wait = (PFN_WaitToBeginFrame)dlsym(ovrp, "ovrp_WaitToBeginFrame");
    }
-    LOG("ovrp frame loop shim: ovrp_Update2 %s, ovrp_WaitToBeginFrame %s", real_update2 ? "OK" : "MISSING",
-        real_wait ? "OK" : "MISSING");
+    LOG("ovrp frame loop shim: ovrp_Update2 %s, ovrp_WaitToBeginFrame %s, begin gate %d, hold physics %d",
+        real_update2 ? "OK" : "MISSING", real_wait ? "OK" : "MISSING", begin_gate, hold_physics);
 }

 #define STEP_RENDER (-1)  // ovrpStep_Render

 static void mouse_click_frame(void);  // below: controller presses as Unity mouse clicks

+// xrWaitFrame blocks until the frame waited for before it has begun (xrBeginFrame). Unity begins frames on its render
+// thread, which sometimes skips one (scene activation) and then waits for the main thread: our next wait never
+// returned (Sniper Elite VR hung at its Init scene, main thread in SteamVR's CSxrSession::StartNextFrame, render
+// thread idle). FramePort also renames libunity.so's "ovrp_BeginFrame"/"ovrp_EndFrame" lookups to the functions below.
+// Once a begin has come through, the main thread first waits (≤ BEGIN_TIMEOUT_MS) for the last waited frame to begin
+// and skips this frame's wait if it doesn't (normally the render thread begins it within a frame: pacing unchanged).
+// OVRPlugin only begins the frame index it waited for (else "outside of frame bounds" and no xrBeginFrame, after which
+// the next wait blocked for good), so a begin of another index while a wait is outstanding becomes a begin of the
+// waited index, and the matching end follows it.
+#define BEGIN_TIMEOUT_MS 50
+static pthread_mutex_t begin_lock = PTHREAD_MUTEX_INITIALIZER;
+static pthread_cond_t begin_cond = PTHREAD_COND_INITIALIZER;
+static int begin_hooked;     // fpov_BeginFrame has been called: the gate is armed
+static int outstanding = -1; // frame index waited for and not begun yet, else -1 (under begin_lock)
+static int remap_from = -1, remap_to = -1;  // the last begin that was given the waited index (for its end)
+
+static int last_wait_begun(int frame_index) {
+    if (!begin_gate) return 1;
+    pthread_mutex_lock(&begin_lock);
+    struct timespec until;
+    clock_gettime(CLOCK_REALTIME, &until);
+    until.tv_nsec += BEGIN_TIMEOUT_MS * 1000000L;
+    if (until.tv_nsec >= 1000000000L) until.tv_sec++, until.tv_nsec -= 1000000000L;
+    while (begin_hooked && outstanding >= 0)
+        if (pthread_cond_timedwait(&begin_cond, &begin_lock, &until)) break;
+    int ok = !begin_hooked || outstanding < 0;
+    if (ok) outstanding = frame_index;
+    pthread_mutex_unlock(&begin_lock);
+    return ok;
+}
+
+// Unity's physics step updates OVRPlugin's poses with prediction 0 ("now"). OVRPlugin takes "now" from the monotonic
+// clock, which is the XrTime base on a Quest but not on the Frame (its XrTime ran 0.05-0.9 s ahead), so it located
+// every node that much in the past (the runtime extrapolates backwards), and the render-step reads after it got those
+// poses too: the game's hands trailed the controllers by several centimetres whenever they moved (Sniper Elite VR). A
+// larger prediction doesn't reach (OVRPlugin caps it at ~0.07 s), so the physics update isn't passed on: OVRPlugin
+// keeps the render update's display-time poses for the whole frame (physics and render reads agree).
+#define STEP_PHYSICS 0
+
 EXPORT int fpov_Update2(int step, int frame_index, double prediction_seconds) {
    pthread_once(&once, init);
-    static int last_waited = -1, logged;
+    static int last_waited = -1, rendered, logged, skipped, last_result;
    if (step == STEP_RENDER && real_wait && frame_index != last_waited) {
        last_waited = frame_index;
-        int r = real_wait(frame_index);
-        if (logged++ < 3) LOG("ovrp frame loop shim: waited for frame %d: %d", frame_index, r);
+        if (last_wait_begun(frame_index)) {
+            int r = real_wait(frame_index);
+            if (logged++ < 3) LOG("ovrp frame loop shim: waited for frame %d: %d", frame_index, r);
+        } else if (skipped++ < 20 || skipped % 1000 == 0) {
+            LOG("ovrp frame loop shim: frame %d: the last waited frame wasn't begun within %d ms, not waiting "
+                "(%d times)", frame_index, BEGIN_TIMEOUT_MS, skipped);
+        }
        mouse_click_frame();
    }
-    return real_update2 ? real_update2(step, frame_index, prediction_seconds) : -1000;  // ovrpFailure
+    if (hold_physics && step == STEP_PHYSICS && rendered) return last_result;  // see above: keeps the display-time poses
+    int r = real_update2 ? real_update2(step, frame_index, prediction_seconds) : -1000;  // ovrpFailure
+    if (step == STEP_RENDER) rendered = 1, last_result = r;
+    return r;
+}
+
+// Unity's legacy ovrp_BeginFrame(frameIndex) / ovrp_EndFrame(frameIndex) on the render thread; further arguments
+// (older plugins) are passed on as they are
+typedef int (*PFN_FrameCall)(long, long, long, long);
+
+static PFN_FrameCall ovrp_fn(const char *name) {
+    void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
+    PFN_FrameCall fn = ovrp ? (PFN_FrameCall)dlsym(ovrp, name) : 0;
+    LOG("ovrp frame loop shim: %s %s", name, fn ? "OK" : "MISSING");
+    return fn;
+}
+
+EXPORT int fpov_BeginFrame(long frame, long b, long c, long d) {
+    static PFN_FrameCall real;
+    static int logged;
+    pthread_once(&once, init);  // the settings (begin_gate) before the first begin
+    if (!real) real = ovrp_fn("ovrp_BeginFrame");
+    pthread_mutex_lock(&begin_lock);
+    long index = frame;
+    if (begin_gate && outstanding >= 0 && outstanding != (int)frame) {
+        index = outstanding;
+        remap_from = (int)frame, remap_to = outstanding;
+    } else {
+        remap_from = remap_to = -1;
+    }
+    pthread_mutex_unlock(&begin_lock);
+    int r = real ? real(index, b, c, d) : -1000;
+    if (index != frame && logged++ < 20)
+        LOG("ovrp frame loop shim: begin frame %ld as waited frame %ld: %d", frame, index, r);
+    pthread_mutex_lock(&begin_lock);
+    begin_hooked = 1;
+    outstanding = -1;  // the waited frame (if any) is begun now
+    pthread_cond_broadcast(&begin_cond);
+    pthread_mutex_unlock(&begin_lock);
+    return r;
+}
+
+EXPORT int fpov_EndFrame(long frame, long b, long c, long d) {
+    static PFN_FrameCall real;
+    if (!real) real = ovrp_fn("ovrp_EndFrame");
+    pthread_mutex_lock(&begin_lock);
+    if ((int)frame == remap_from) frame = remap_to;
+    pthread_mutex_unlock(&begin_lock);
+    return real ? real(frame, b, c, d) : -1000;
 }

 // ---------------------------------------------------------------- input diagnostics (pass-through)
@@ -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.
@@ -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
@@ -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
@@ -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;
+}
@@ -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
@@ -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));
+}
@@ -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
@@ -11,8 +11,9 @@
 // Haptics (GitHub #9, found by Klownicle in Lucky's Tale): overport's dispatcher converts an
 // XrHapticAmplitudeEnvelopeVibrationFB with its nanosecond duration taken as seconds, so one vibration allocates an
 // enormous sample buffer and the Frame runs out of memory and freezes. The shim hands OVRPlugin its own
-// xrApplyHapticFeedback, which turns such an envelope into a plain XrHapticVibration (same duration, its peak
-// amplitude) before the dispatcher sees it. Everything else passes through unchanged.
+// xrApplyHapticFeedback, which turns such an envelope into a plain XrHapticVibration (same duration, its RMS
+// amplitude) before the dispatcher sees it; PCM vibrations (XrHapticPcmVibrationFB) are converted the same way.
+// Everything else passes through unchanged.
 // Upstream: ovrport/app#73; tracked in FramePort GitHub #74.
 #include <openxr/openxr.h>
 #include <android/log.h>
@@ -69,6 +70,23 @@ static XRAPI_ATTR XrResult XRAPI_CALL apply_haptic_feedback(XrSession session, c
                                "vibration %.2f", env->amplitudeCount, (long long)env->duration, plain.amplitude);
        return overport_haptics(session, info, (const XrHapticBaseHeader *)&plain);
    }
+    if (feedback && feedback->type == XR_TYPE_HAPTIC_PCM_VIBRATION_FB) {
+        // the other buffered form goes through the same conversion: a plain vibration as long as the samples (all
+        // consumed), with their RMS
+        const XrHapticPcmVibrationFB *pcm = (const XrHapticPcmVibrationFB *)feedback;
+        double sum = 0.0;
+        for (uint32_t i = 0; pcm->buffer && i < pcm->bufferSize; ++i)
+            sum += (double)pcm->buffer[i] * pcm->buffer[i];
+        float rms = pcm->bufferSize ? (float)sqrt(sum / pcm->bufferSize) : 0.0f;
+        XrDuration duration = pcm->sampleRate > 0 ? (XrDuration)(pcm->bufferSize / pcm->sampleRate * 1e9) : 0;
+        XrHapticVibration plain = {XR_TYPE_HAPTIC_VIBRATION, NULL, duration > 0 ? duration : XR_MIN_HAPTIC_DURATION,
+                                   XR_FREQUENCY_UNSPECIFIED, rms > 1.0f ? 1.0f : rms};
+        if (pcm->samplesConsumed) *pcm->samplesConsumed = pcm->bufferSize;
+        if (haptics_logged++ < 3)
+            __android_log_print(ANDROID_LOG_INFO, TAG, "extension shim: haptic PCM (%u samples at %.0f Hz) -> "
+                                "vibration %.2f", pcm->bufferSize, pcm->sampleRate, plain.amplitude);
+        return overport_haptics(session, info, (const XrHapticBaseHeader *)&plain);
+    }
    return overport_haptics(session, info, feedback);
 }

@@ -22,6 +22,10 @@ dependencies = [
    "flet>=1.0",
    "flet-desktop>=1.0",
    "flet-dropzone>=0.4.0",  # drag-and-drop uploads in the Files tab (packaged app only; Apache-2.0)
+    # the live view inside the window (media_kit/libmpv; Apache-2.0). Not on Linux: there the plugin links libmpv.so.1
+    # and a bundle with it wouldn't start without that library (Linux plays in an mpv window or the browser instead).
+    # flet-video pins flet exactly: keep it at the installed flet's version.
+    "flet-video==1.0.2; sys_platform != 'linux'",
    "paramiko>=3.4",
    "zeroconf>=0.132",
    "psutil>=5.9",
@@ -35,7 +35,7 @@ def render() -> str:
        rows.append(f"| {e.title} | {platform} | {STATUS[e.status]} | {note} |")
    return ("# Tested games\n\n"
            "Games tested on the Steam Frame with FramePort's recipes. Games not listed here may work too: FramePort "
-            "suggests patches for them, and a working config can be shared from the app (**Share working config…**).\n"
+            "suggests patches for them, and a working recipe can be shared from the app (**Share working recipe…**).\n"
            f"Tested a game? [Share a working config]({SHARE}) or [report a problem]({REPORT}) (in the app: the game's "
            "**…** menu does both and fills in the details).\n"
            "Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.\n\n"
@@ -0,0 +1,413 @@
+#!/usr/bin/env python3
+"""Record short clips of the real GUI's animations (web mode, a pretend Frame) for a showcase page: the install
+transit, the live Frame card, navigation, selection and theme switching. One browser context per clip (Playwright's
+video recorder), converted to MP4 + a poster JPG with ffmpeg.
+
+    FRAMEPORT_HOME=<a test data dir> python scripts/demo_record.py --out /tmp/clips [--game <package>] [--only transit]
+
+Reuses ui_smoke's fakes (FakeTarget, FakeMonitorSession, …): nothing reaches a real Frame. Mouse positions are for
+the 1440x900 window at UI scale 1.0 (the same as ui_smoke --gestures).
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import queue
+import random
+import shutil
+import subprocess
+import sys
+import threading
+import time
+import traceback
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+import flet as ft  # noqa: E402
+import ui_smoke  # noqa: E402
+from ui_smoke import FakeMonitorSession, attach_fake_frame, install_fakes  # noqa: E402
+
+from frameport.core import library  # noqa: E402
+from frameport.ui import components as C  # noqa: E402
+from frameport.ui.app import FramePortApp  # noqa: E402
+
+PORT = ui_smoke.PORT
+W, H = 1440, 900
+FFMPEG = shutil.which("ffmpeg") or "/usr/bin/ffmpeg"
+ERRORS: list[str] = []
+APPS: queue.Queue = queue.Queue()  # one FramePortApp per browser session (= per clip)
+
+# sidebar tabs (x, y) at 1440x900
+TAB = {"library": (100, 110), "frame": (100, 152), "files": (100, 194), "screenshots": (100, 236),
+       "live": (100, 278), "keyboard": (100, 320), "monitor": (100, 362), "settings": (100, 404)}
+NOWHERE = (130, 520)  # the sidebar's empty part: nothing hovered
+
+
+class LiveMonitorSession(FakeMonitorSession):
+    """The fake stream, livelier for the live-card clip: a sample every 0.6 s and a frame rate with a few-second
+    stutter now and then (also in the two minutes sent first), so the card's sparkline (5 s points) has a shape and
+    visibly moves."""
+
+    def _sample(self) -> dict:
+        s = super()._sample()
+        t = self.t
+        fps = 72 - abs(random.gauss(0, 0.8))
+        if (t // 8) % 3 == 1:  # 8 samples of stutter in every 24
+            fps = 56 + 6 * abs(((t % 8) - 4) / 4) + random.uniform(-1.5, 1.5)
+        for g in s["games"]:
+            g["fps"] = round(fps, 1)
+        return s
+
+    def _run(self) -> None:
+        self.t = 0
+        while not self.closed and self.t < 100000:
+            self.on_sample(self._sample())
+            if self.t >= self.BACKFILL:
+                time.sleep(0.6)
+            self.t += 1
+
+
+def ui(app: FramePortApp, fn, *args) -> None:
+    """Run an app action, logging (not raising) errors so one broken step doesn't end the recording."""
+    try:
+        fn(*args)
+    except Exception:  # noqa: BLE001
+        ERRORS.append(traceback.format_exc())
+
+
+# ------------------------------------------------------------------ scenarios
+# each: (setup(app) before the clip starts, play(app, page) = the clip, poster time in s)
+
+def transit_setup(game):
+    def run(app):
+        app.open_game(game)
+        time.sleep(1)
+        app.show_activity(True)
+    return run
+
+
+def transit_play(game):
+    """A pretend install through the real JobManager: every stage the real one reports, with an upload ticking."""
+    def run(job):
+        rep = job.reporter
+
+        def stage(name, secs, logs=()):
+            rep.stage(name)
+            for line in logs:
+                rep.log(line)
+            time.sleep(secs)
+        stage("Patching the game", 0.9)
+        stage("OVRPort (primary)", 1.2, ["overport patch --version=latest"])
+        stage("Frame fixes (primary)", 1.0, ["frame.ovrstubs", "frame.vk_sanitize"])
+        stage("sign (primary)", 0.7)
+        rep.stage("validate (primary)")
+        for name in ("APK signature", "64-bit libraries", "OpenXR loader"):
+            rep.check(name, True)
+            time.sleep(0.25)
+        time.sleep(0.2)
+        stage("Prepare Frame", 0.7)
+        total = 1.42e9
+        rep.stage("Upload APK")
+        apk_part = 0.42
+        steps = 14
+        for i in range(1, steps + 1):
+            f = apk_part * i / steps
+            speed = 34.0 + random.uniform(0, 4)
+            left = (1 - f) * total / (speed * 1e6)
+            rep.progress(f, "com.BithellGames.Arcsmith.apk", speed=f"{speed:.1f} MB/s · ~{left:.0f} s left")
+            time.sleep(0.22)
+        rep.stage("Upload data (3 files)")
+        for i in range(1, steps + 1):
+            f = apk_part + (1 - apk_part) * i / steps
+            speed = 34.0 + random.uniform(0, 4)
+            left = (1 - f) * total / (speed * 1e6)
+            rep.progress(f, f"main.{120 + i // 5}.com.BithellGames.Arcsmith.obb",
+                         speed=f"{speed:.1f} MB/s · ~{left:.0f} s left" if f < 1 else f"{speed:.1f} MB/s")
+            time.sleep(0.22)
+        stage("Artwork for the Steam library", 0.8)
+        stage("Finalize install", 0.9)
+        stage("Add to Steam library", 0.8)
+        stage("Launch test (headless)", 1.8, ["process alive", "OpenXR session created", "frames paced: 72 fps"])
+        job.summary = {"verdict": "pass", "findings": []}
+        rep.stage("Launch test: passed")
+        time.sleep(0.5)
+        return "Arcsmith is ready on your Frame: put the headset on and launch it from your Steam library"
+
+    def play(app, page):
+        time.sleep(1.0)
+        app.submit(f"Install {app._title(game)} on Frame", run, game, "install", to="frame")
+        deadline = time.time() + 40
+        while time.time() < deadline and any(j.active for j in app.jobs.jobs):
+            time.sleep(0.3)
+        time.sleep(1.8)  # done: the cover arrives, the toast
+    return play
+
+
+def live_setup(app):
+    # disconnected-looking: no target, state "none" (the fake isn't attached yet)
+    app.target, app.frame_info, app.frame_state = None, None, "none"
+    app.go("library")
+
+
+def live_play(app, page):
+    time.sleep(1.2)
+    app.frame_state = "connecting"
+    app._refresh_sidebar()
+    time.sleep(1.0)
+    attach_fake_frame(app, LiveMonitorSession)
+    app.refresh_view()
+    app._refresh_sidebar()
+    time.sleep(14)
+
+
+def navigation_setup(app):
+    app.go("library")
+
+
+def navigation_play(app, page):
+    m = page.mouse
+    time.sleep(0.8)
+    for tab in ("frame", "files", "monitor", "settings", "library"):
+        m.move(*TAB[tab], steps=8)
+        time.sleep(0.25)
+        m.click(*TAB[tab])
+        time.sleep(1.3)
+    # type to search: an empty part of the header, then the keyboard
+    m.move(480, 60, steps=6)
+    m.click(480, 60)
+    time.sleep(0.4)
+    page.keyboard.type("arc", delay=160)
+    time.sleep(1.6)
+    page.keyboard.press("Escape")
+    time.sleep(1.2)
+    # the "On your Frame" shelf's first card: lift + Play
+    m.move(403, 268, steps=12)
+    time.sleep(1.6)
+    # a grid card's menu
+    m.move(360, 540, steps=10)
+    time.sleep(0.6)
+    m.click(360, 540, button="right")
+    time.sleep(0.9)
+    for dy in (20, 60, 100, 140, 180):
+        m.move(400, 540 + dy, steps=5)
+        time.sleep(0.35)
+    page.keyboard.press("Escape")
+    time.sleep(0.4)
+    m.move(*NOWHERE, steps=8)
+    time.sleep(1.0)
+
+
+def cards_setup(app):
+    app.go("library")
+
+
+def cards_play(game):
+    """Library cards: the shelf, a few grid cards under the pointer, a Play button lit and pressed (portal rings,
+    "Starting on Frame…"), then a game page: Play → "Starting on Frame…", and another's Install on Frame."""
+    def play(app, page):
+        m = page.mouse
+        time.sleep(0.6)
+        m.move(403, 268, steps=14)  # the shelf's first card
+        time.sleep(1.2)
+        m.move(403, 252, steps=6)  # onto its button
+        time.sleep(1.0)
+        for x in (357, 550, 742, 550):  # across the grid's first row
+            m.move(x, 430, steps=14)
+            time.sleep(0.9)
+        m.move(357, 440, steps=12)
+        time.sleep(0.8)
+        m.move(357, 497, steps=8)  # the first card's Play button
+        time.sleep(1.0)
+        m.click(357, 497)
+        time.sleep(3.0)
+        m.move(*NOWHERE, steps=10)
+        time.sleep(1.0)
+        installed = next((g["package"] for g in library.games() if g["package"] != game
+                          and C.install_state(g, app.frame_info) == "installed"), None)
+        if installed:
+            ui(app, app.open_game, installed)
+            time.sleep(1.6)
+            m.move(375, 306, steps=12)  # the hero's Play on Frame
+            time.sleep(0.8)
+            m.click(375, 306)
+            time.sleep(2.6)
+        ui(app, app.open_game, game)  # not installed: Install on Frame (the filled Frame glyph)
+        time.sleep(1.6)
+        m.move(375, 306, steps=12)
+        time.sleep(1.8)
+        m.move(*NOWHERE, steps=10)
+        time.sleep(0.6)
+    return play
+
+
+def selection_setup(app):
+    app.go("files")
+
+
+def selection_play(app, page):
+    m = page.mouse
+    time.sleep(0.8)
+    m.move(900, 320, steps=10)  # a row: its checkbox and actions fade in
+    time.sleep(1.4)
+    m.move(900, 268, steps=6)
+    time.sleep(0.5)
+    m.down()
+    for pt in ((900, 320), (900, 372)):
+        m.move(*pt, steps=20)
+        time.sleep(0.4)
+    m.up()
+    time.sleep(1.2)
+    m.move(900, 320, steps=5)
+    time.sleep(0.3)
+    m.click(900, 320, button="right")
+    time.sleep(0.8)
+    for dy in (20, 68, 116):
+        m.move(960, 320 + dy, steps=5)
+        time.sleep(0.4)
+    page.keyboard.press("Escape")
+    time.sleep(0.6)
+    m.move(*TAB["screenshots"], steps=10)
+    m.click(*TAB["screenshots"])
+    time.sleep(2.2)
+    for x in (410, 680, 946):  # hover the first row
+        m.move(x, 275, steps=10)
+        time.sleep(0.6)
+    for x in (305, 573):  # select two
+        m.move(x, 227, steps=10)
+        time.sleep(0.4)
+        m.click(x, 227)
+        time.sleep(0.8)
+    m.move(700, 760, steps=10)
+    time.sleep(1.5)
+
+
+def themes_setup(app):
+    app.go("settings")
+
+
+def themes_play(app, page):
+    m = page.mouse
+    time.sleep(1.0)
+    for x, y in ((838, 268), (1090, 268), (587, 420), (587, 275)):  # Portal (OLED), Original, Ember & Ice, Portal
+        m.move(x, y, steps=12)
+        time.sleep(0.3)
+        m.click(x, y)
+        time.sleep(2.4)
+    m.move(*TAB["library"], steps=12)
+    m.click(*TAB["library"])
+    time.sleep(3.0)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out", type=Path, required=True)
+    ap.add_argument("--game", default=None)
+    ap.add_argument("--only", default=None, help="comma-separated clip names (transit,live-card,navigation,…)")
+    ap.add_argument("--crf", type=int, default=26)
+    ap.add_argument("--width", type=int, default=W, help="scale the MP4 to this width (e.g. 1280)")
+    ap.add_argument("--keep-raw", action="store_true", help="keep Playwright's .webm recordings in <out>/raw")
+    args = ap.parse_args()
+    game = args.game or (library.games()[0]["package"] if library.games() else None)
+    if not game:
+        print("the library is empty: nothing to show", file=sys.stderr)
+        return 2
+    library.set_setting("ui.theme", "portal")
+    from frameport.ui import theme as T
+    from frameport.ui.app import assets_dir, themes_dir
+
+    T.set_scale(1.0)
+    T.load_user_themes(themes_dir())
+    install_fakes(game)
+    # the transit last: the job queue is shared by every session, and its finished install would show in the
+    # sidebar's activity card of the clips after it
+    scenarios = [("live-card", live_setup, live_play, 4.0),
+                 ("navigation", navigation_setup, navigation_play, 0.5),
+                 ("cards", cards_setup, cards_play(game), 11.0),
+                 ("selection", selection_setup, selection_play, 3.5),
+                 ("themes", themes_setup, themes_play, 3.0),
+                 ("transit", transit_setup(game), transit_play(game), 9.0)]
+    if args.only:
+        keep = args.only.split(",")
+        scenarios = [s for s in scenarios if s[0] in keep]
+    out, raw = args.out, args.out / "raw"
+    out.mkdir(parents=True, exist_ok=True)
+    raw.mkdir(exist_ok=True)
+
+    def app_main(page: ft.Page):
+        try:
+            app = FramePortApp(page)
+            attach_fake_frame(app)
+        except Exception:  # noqa: BLE001
+            ERRORS.append("startup: " + traceback.format_exc())
+            return
+        APPS.put(app)
+
+    def convert(webm: Path, name: str, start: float, length: float, poster_at: float) -> None:
+        mp4, jpg = out / f"{name}.mp4", out / f"{name}.jpg"
+        scale = [] if args.width == W else ["-vf", f"scale={args.width}:-2:flags=lanczos"]
+        subprocess.run([FFMPEG, "-y", "-loglevel", "error", "-ss", f"{start:.2f}", "-i", str(webm),
+                        "-t", f"{length:.2f}", *scale, "-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf",
+                        str(args.crf), "-preset", "slow", "-movflags", "+faststart", "-an", str(mp4)], check=True)
+        subprocess.run([FFMPEG, "-y", "-loglevel", "error", "-ss", f"{min(poster_at, length - 0.2):.2f}", "-i",
+                        str(mp4), "-frames:v", "1", "-q:v", "3", str(jpg)], check=True)
+        print(f"CLIP {name}: {length:.1f} s, {mp4.stat().st_size / 1e6:.2f} MB", flush=True)
+
+    def recorder():
+        import socket
+
+        from playwright.sync_api import sync_playwright
+
+        for _ in range(90):
+            try:
+                socket.create_connection(("127.0.0.1", PORT), timeout=1).close()
+                break
+            except OSError:
+                time.sleep(1)
+        time.sleep(2)
+        try:
+            with sync_playwright() as p:
+                browser = p.chromium.launch(args=["--use-gl=swiftshader", "--enable-unsafe-swiftshader"])
+                for name, setup, play, poster in scenarios:
+                    while not APPS.empty():  # sessions from elsewhere (a browser the web mode opened)
+                        APPS.get_nowait()
+                    ctx = browser.new_context(viewport={"width": W, "height": H}, record_video_dir=str(raw),
+                                              record_video_size={"width": W, "height": H})
+                    page = ctx.new_page()
+                    t0 = time.monotonic()
+                    page.goto(f"http://127.0.0.1:{PORT}", wait_until="networkidle", timeout=120_000)
+                    app = APPS.get(timeout=120)
+                    time.sleep(2)  # the first screen + web fonts
+                    ui(app, setup, app)
+                    time.sleep(3.5)  # the scenario's first view painted, cards loaded
+                    page.mouse.move(*NOWHERE)
+                    start = time.monotonic() - t0
+                    try:
+                        play(app, page)
+                    except Exception:  # noqa: BLE001
+                        ERRORS.append(f"{name}: " + traceback.format_exc())
+                    length = time.monotonic() - t0 - start
+                    video = page.video
+                    ctx.close()  # flushes the video
+                    webm = Path(video.path())
+                    target = raw / f"{name}.webm"
+                    webm.replace(target)
+                    convert(target, name, start + 0.2, length, poster)
+                    library.set_setting("ui.theme", "portal")  # the next session starts in Portal again
+                browser.close()
+        except Exception:  # noqa: BLE001
+            ERRORS.append("browser: " + traceback.format_exc())
+        if not args.keep_raw:
+            shutil.rmtree(raw, ignore_errors=True)
+        for e in ERRORS:
+            print("ERROR", e, flush=True)
+        os._exit(1 if ERRORS else 0)
+
+    threading.Thread(target=recorder, daemon=True).start()
+    ft.run(app_main, view=ft.AppView.WEB_BROWSER, port=PORT, assets_dir=assets_dir())
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -69,6 +69,9 @@ def main() -> int:
                   "--add-data", f"{DATA}{sep}frameport/_data",
                   # translations (data files PyInstaller doesn't pick up from the imports)
                   "--add-data", f"{ROOT / 'src/frameport/locales'}{sep}frameport/locales",
+                   # the logo and the GUI's own glyphs (SVG)
+                   "--add-data", f"{ROOT / 'src/frameport/ui/icons'}{sep}frameport/ui/icons",
+                   "--icon", str(ROOT / "src/assets/icon.png"),
                   "--distpath", str(ROOT / "dist"), "--yes"]
            if TARGET == "linux":
                cmd.append("--onedir")  # a folder: the bundle check sees the agent source, the archive the app
@@ -70,7 +70,11 @@ class FakeFS:
        owners = [(g["package"], g.get("title") or g["package"], arts) for g, arts, _real in games[:3]]
        spare = games[3][1] if len(games) > 3 else []  # SteamVR's own shots (taken outside a FramePort game)
        owners.append((None, "SteamVR", spare))
+        # the same days layout at any time of day (6 shots on the first day, 4 on the one before; --gestures drags
+        # across the first row): shortly after midnight the shots start the evening before
        now, shots = time.time(), []
+        if time.localtime(now).tm_hour < 5:
+            now -= (time.localtime(now).tm_hour + 1) * 3600
        for i in range(10):
            t = now - i * 2400 - (86400 if i >= 6 else 0)
            name = time.strftime("%Y%m%d%H%M%S", time.localtime(t)) + "_1.jpg"
@@ -152,6 +156,44 @@ 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 launch(self, pkg: str) -> dict:
+        """Play: Steam on the pretend Frame starts the game (the "Starting … put the headset on" toast)."""
+        return {"via": "shortcut", "steam": {"result": "started", "lines": []}}
+
+    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 +224,163 @@ 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:
+        self.t = 0
+        while not self.closed and self.t < 100000:
+            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)
+            self.t += 1
+
+    def set_modules(self, m):
+        # the hub asks for everything when the Monitor tab subscribes (the Frame card started the stream): send the
+        # two minutes again so its charts are full in screenshots too
+        if m == "all":
+            self.t = 0
+        return True
+
+    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
+
+
+FAKE_INSTALL_STAGES = ["Patching the game", "OVRPort (primary)", "Frame fixes (primary)", "sign (primary)",
+                       "validate (primary)", "Prepare Frame", "Upload APK"]
+
+
+def start_fake_install(app: FramePortApp, package: str) -> None:
+    """A running install job of `package` that reports the real stage names up to the upload (62 %) and then waits
+    (it never ends: the smoke run exits with it)."""
+    from frameport.ui.jobs import Job
+
+    hold, reached = threading.Event(), threading.Event()
+
+    def run(job):
+        for stage in FAKE_INSTALL_STAGES:
+            job.reporter.stage(stage)
+        time.sleep(0.3)  # past the job queue's notification throttle
+        job.reporter.progress(0.62, "com.example.apk", speed="36.4 MB/s · ~1 min left")
+        reached.set()
+        hold.wait()
+
+    app.jobs.submit(Job(f"Install {app._title(package)} on Frame", run, package, "install"))
+    reached.wait(10)
+
+
+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 fake_live_stream(app: FramePortApp) -> None:
+    """The Live view while streaming: a local ffmpeg test picture through the real relay (no Frame needed). Web mode
+    has no in-window player, so it's shown as playing in the browser (the bar's streaming layout)."""
+    import shutil
+    import subprocess
+
+    from frameport.install.livestream import LiveStream
+
+    view = app.live_view
+    if view is None or shutil.which("ffmpeg") is None:
+        return
+    src = ["ffmpeg", "-loglevel", "error", "-re", "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30",
+           "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-c:v", "libx264", "-preset", "ultrafast",
+           "-g", "30", "-pix_fmt", "yuv420p", "-c:a", "aac", "-f", "mp4",
+           "-movflags", "empty_moov+default_base_moof+frag_keyframe", "-frag_duration", "100000", "-"]
+    proc = subprocess.Popen(src, stdout=subprocess.PIPE)
+    view.live = LiveStream(lambda: proc.stdout, proc.terminate).start()
+    view.mode = "browser"
+    view._refresh()
+
+
+def stop_fake_live(app: FramePortApp) -> None:
+    if app.live_view is not None and app.live_view.live is not None:
+        app.live_view.stop()
+
+
+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
@@ -225,18 +413,44 @@ def add_fake_linux_apps() -> None:
    pipeline.add_linux_app(app)


-STEP_SECONDS = 4  # per screen (the screenshot is taken ~3 s in)
+def install_fakes(game: str | None, monitor_session=None) -> None:
+    """--fake-frame: never reach a real Frame (start-up auto-connect, discovery, the 30 s poll); Type on Frame and
+    the Monitor stream are fakes. `game` = the Monitor's game card (with its artwork)."""
+    from frameport.frame import keyboard, monitor
+
+    keyboard.KeyboardSession = FakeKeyboardSession
+    monitor.MonitorSession = monitor_session or FakeMonitorSession
+    FakeMonitorSession.GAME = game
+    FramePortApp.connect = lambda self, *a, **k: None
+    FramePortApp.refresh_frame = lambda self, *a, **k: None


-def driver(app: FramePortApp, steps: list[tuple[str, callable]], ready: threading.Event, done_step: list):
+def attach_fake_frame(app: FramePortApp, monitor_session=None) -> None:
+    """Connect `app` to a FakeTarget (the shared monitor stream, used by the Monitor tab and the Frame card, too)."""
+    app.monitor_hub.session_factory = monitor_session or FakeMonitorSession
+    app.target = FakeTarget()
+    app.frame_info, app.frame_state = app.target.describe(), "connected"
+
+
+PAINT_SECONDS = 3  # after a step, before its screenshot: Flutter paints (and a view's content loads)
+STEP_TIMEOUT = 240  # the longest a step may wait for its screenshot (a crashed browser mustn't hang the run)
+
+
+def driver(app: FramePortApp, steps: list[tuple[str, callable]], ready: threading.Event, shot_done: threading.Event,
+           done_step: list):
+    """Runs one step, hands it to the shooter ("ready") and waits until its screenshot and mouse actions are done
+    ("shot_done") before the next one: so a screenshot always shows its own step, however long the shooter takes."""
    for name, action in steps:
        try:
            action(app)
        except Exception:  # noqa: BLE001
            ERRORS.append(f"{name}: {traceback.format_exc()}")
        done_step.append(name)
+        shot_done.clear()
        ready.set()
-        time.sleep(STEP_SECONDS)
+        if not shot_done.wait(STEP_TIMEOUT):
+            ERRORS.append(f"{name}: no screenshot within {STEP_TIMEOUT} s, stopping")
+            return


 def find_button(root, text: str):
@@ -276,7 +490,8 @@ def main() -> int:
    ap.add_argument("--no-test", action="store_true", help="with --frame: skip the launch-test job")
    ap.add_argument("--scale", type=float, default=1.0, help="UI scale to render at (e.g. 1.5)")
    ap.add_argument("--viewport", default="1280x820", help="browser size, e.g. 2560x1440")
-    ap.add_argument("--update", action="store_true", help="pretend a new FramePort release exists (update UI)")
+    ap.add_argument("--update", action="store_true", help="pretend a new FramePort release exists (update UI: "
+                    "changelog dialog, what's new bar + dialog, Settings changelog)")
    ap.add_argument("--fake-frame", action="store_true", help="pretend a Steam Frame is connected (no device needed)")
    ap.add_argument("--hover", default=None, help="x,y: move the mouse there before the Library screenshot")
    ap.add_argument("--install-questions", nargs="+", metavar="PKG", default=None,
@@ -286,14 +501,18 @@ def main() -> int:
                    "(a Frame cabled to this PC) and screenshot what follows")
    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")
+                    "right-clicks (menus) in Files, Screenshots and the Library; prints what got selected "
+                    "(positions for --viewport 1440x900)")
+    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")
+    ap.add_argument("--themes", action="store_true", help="Settings' theme picker, then switch every theme while "
+                    "running (Library and --game in each)")
    args = ap.parse_args()
    if args.linux:
        add_fake_linux_apps()
-    global STEP_SECONDS
-    if args.hover:
-        STEP_SECONDS = 7
    from frameport.ui import theme

    theme.set_scale(args.scale)
@@ -302,15 +521,25 @@ 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")), ("live-streaming", fake_live_stream),
+             ("keyboard", lambda a: (stop_fake_live(a), a.go("keyboard"))),
+             ("monitor", lambda a: a.go("monitor")), ("monitor-details", open_monitor_details),
+             ("tools", lambda a: a.go("settings")),
+             # the index on the left: "This PC" scrolls the page there
+             ("settings-index", lambda a: a.page.run_task(a.settings_view.show_section, "pc"))]
    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)))]
+        # a pretend install of --game, mid-upload: the transit in the sidebar, the game page and Activity
+        steps += [("transit-game", lambda a: (a.page.pop_dialog(), start_fake_install(a, game), a.open_game(game))),
+                  ("transit-activity", lambda a: a.show_activity(True))]
+        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),
+        steps.append(("library-menu", lambda a: (a.show_activity(False), a.navigate(0), time.sleep(3),
                                                 a.library_view.open_menu(game))))
    if args.docs:
        steps = [("library", lambda a: a.navigate(0))]
@@ -323,12 +552,66 @@ 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:
-        STEP_SECONDS = 14  # the mouse actions run after each step's screenshot, before the next step
+    # step name -> mouse actions (Playwright page) after its screenshot, then a "-mouse" screenshot unless the
+    # actions return True (they saved their own picture, e.g. an opened menu)
+    mouse: dict[str, callable] = {}
+    hover: dict[str, tuple[float, float]] = {}  # step name -> where the mouse rests for its screenshot
+    if args.hover:
+        hover["library"] = tuple(float(v) for v in args.hover.split(","))
+    if not args.docs and args.viewport == "1440x900":  # menus that open from buttons (positions at this size)
+        def open_and_shoot(x, y, name):
+            def run(page):
+                page.mouse.click(x, y)
+                time.sleep(2)
+                page.screenshot(path=str(args.out / f"{name}.png"))
+                page.mouse.click(1420, 880)  # outside the menu (Flutter's popup ignores Escape)
+                return True
+            return run
+        mouse["library"] = open_and_shoot(1354, 54, "library-add-menu")
+        # type to search: click an empty part of the header, then type (the "-mouse" shot shows "arc" + the matches)
+        steps.insert(1, ("library-typed", lambda a: a.library_view.clear_search()))
+        def typed(page):
+            page.mouse.click(480, 60)
+            time.sleep(0.5)
+            page.keyboard.type("arc", delay=120)
+            if args.fake_frame:  # the matches' cover buttons: Install (Arcsmith, not installed), Update (Pinball FX)
+                time.sleep(PAINT_SECONDS)
+                for name, pt in (("library-install-hover", (742, 215)), ("library-install-button", (742, 276)),
+                                 ("library-update-button", (357, 276))):
+                    page.mouse.move(*pt, steps=8)
+                    time.sleep(1.2)
+                    page.screenshot(path=str(args.out / f"{name}.png"))
+                page.mouse.move(1300, 700)
+        mouse["library-typed"] = typed
+        steps.insert(2, ("library-cleared", lambda a: a.library_view.clear_search()))
+        if args.fake_frame:  # the "On your Frame" shelf's first card, hovered: its Play button shows
+            steps.insert(3, ("library-shelf-hover", lambda a: None))
+            hover["library-shelf-hover"] = (403, 268)
+            # the grid's first card: hovered (lift, zoom, the glass button), the pointer on its button, then Play:
+            # the portal rings mid-ripple and the "Starting on Frame…" pill
+            steps.insert(4, ("library-card-hover", lambda a: None))
+            hover["library-card-hover"] = (357, 420)
+            steps.insert(5, ("library-card-button", lambda a: None))
+            hover["library-card-button"] = (357, 497)

+            def launch(page):
+                page.mouse.move(357, 497)
+                time.sleep(1.2)
+                page.mouse.click(357, 497)
+                for i in range(6):  # the launch, frame by frame (rings, then the pill)
+                    time.sleep(0.15)
+                    page.screenshot(path=str(args.out / f"library-play-launch-{i}.png"))
+                time.sleep(1.0)
+                page.screenshot(path=str(args.out / "library-play-starting.png"))
+                page.mouse.move(130, 520)
+                return True
+            mouse["library-card-button"] = launch
+        if game:
+            mouse["game"] = open_and_shoot(491, 306, "game-more-menu")  # the hero's "…"
+    if args.gestures:  # the mouse actions run after each step's screenshot, before the next step
        def drag(*points):
            def run(page):
                page.mouse.move(*points[0])
@@ -365,11 +648,12 @@ def main() -> int:
                 "files-dragged": right_click(900, 320),                      # a selected one: "… 3 items"
                 "files-menu": lambda page: (escape(page), time.sleep(0.5), right_click(900, 600)(page)),
                 "files-space-menu": escape,
-                 "screenshots": drag((680, 280), (950, 280), (950, 430)),     # 3 shots
-                 "screenshots-dragged": right_click(950, 430),
+                 "screenshots": drag((400, 300), (680, 300), (950, 300)),     # 3 shots (the first row)
+                 "screenshots-dragged": right_click(950, 300),
                 "screenshots-menu": escape,
-                 "library": drag((360, 300), (560, 300), (760, 300)),        # 3 cards, select mode on
-                 "library-dragged": drag((560, 300), (760, 300))}             # from a selected card: deselects 2
+                 # the grid's first row (below the "On your Frame" shelf)
+                 "library": drag((360, 560), (560, 560), (760, 560)),        # 3 cards, select mode on
+                 "library-dragged": drag((560, 560), (760, 560))}             # from a selected card: deselects 2
    if args.linux:
        def linux_filter(a, value):
            a.navigate(0)
@@ -381,7 +665,68 @@ 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)
+
+        steps = [("library", lambda a: a.navigate(0)),
+                 ("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)
+            return True
+        # tall pages: run with e.g. --viewport 1280x3200 (at 1440x900 the tour's own Add games click is kept)
+        mouse.setdefault("library", add_menu_open)
+    if args.themes:
+        from frameport.ui import theme as T
+        from frameport.ui.app import themes_dir
+
+        T.load_user_themes(themes_dir())  # installed theme files are switched through too
+
+        def switch(name):
+            def run(a):
+                library.set_setting("ui.theme", name)  # what the picker does
+                a.restyle(name)
+            return run
+
+        def appearance(a):
+            """Settings: Appearance is its first section."""
+            a.go("settings")
+        steps = [("appearance", appearance)]
+        for name in [n for n in T.THEMES if n != T.THEME] + [T.THEME]:
+            steps.append((f"{name}-switched", switch(name)))
+            steps.append((f"{name}-appearance", appearance))
+            steps.append((f"{name}-library", lambda a: a.navigate(0)))
+            if game:
+                steps.append((f"{name}-game", lambda a: a.open_game(game)))
    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]
@@ -409,14 +754,48 @@ def main() -> int:
        steps = [("library", lambda a: a.navigate(0)), ("questions", open_questions),
                 ("after-1st-double", double_click), ("after-2nd-double", double_click), ("end", report)]
    if args.update:
-        from frameport import updates
+        from frameport import __version__, updates

+        notes = ("FramePort v9.9.9: Windows (x64), macOS (Apple Silicon) and Linux (x64, ARM64).\n\n## What's new\n\n"
+                 "- Self-update test release: the update dialog shows every version since yours\n"
+                 "- **Bold** and `code` in notes, and a [link](https://example.invalid)\n- A third bullet\n\n"
+                 "Already have FramePort? It offers this update itself (Library → **Update now**).\n\n## Install\n\n"
+                 "- footer that the changelog leaves out\n")
        fake = updates.Update(version="9.9.9", tag="v9.9.9", page="https://example.invalid", asset=None, asset_url=None,
-                              sums_url=None, wheel_url=None,
-                              notes="## What's new\n- Self-update test release\n- **Bold** and `code` in notes")
+                              sums_url=None, wheel_url=None, notes=notes, published="2026-10-08T10:00:00Z")
+        major, minor, _patch = updates.parse_version(__version__)[:3]
+        older = f"{major}.{max(minor - 1, 0)}"
+
+        def entry(version, date, body):
+            return updates.ChangelogEntry(version=version, tag=f"v{version}", date=date, title=f"FramePort v{version}",
+                                          body=body, page="https://example.invalid",
+                                          dev=updates.is_dev_version(version))
+        fake_log = [updates.entry_from_update(fake),
+                    entry("9.9.8", "2026-10-06", "- Install links from FrameDrop buttons\n- Faster uploads over USB"),
+                    entry("9.9.7", "2026-10-04", "- Monitor tab with live Frame stats"),
+                    entry(__version__, "2026-10-02", "- The version you have: **Live view** with sound\n"
+                                                     "- Files tab: drag and drop\n- Smaller fixes"),
+                    entry(f"{older}.3", "2026-09-30", "- Proton defaults to the newest stable build"),
+                    entry(f"{older}.2", "2026-09-28", "- Language packs")]
+        updates.fetch_changelog = lambda force=False, need=None: list(fake_log)  # no GitHub in screenshots
+
+        def news(a):
+            a.updater._set(None)
+            a.updater.news = updates.recent_history(fake_log, n=3)
+            a.navigate(0)
+            a.refresh_view()
+
+        def settings_updates(a):
+            a.go("settings")
+            # once the page is mounted: scrolling an unmounted column does nothing
+            threading.Timer(1.0, lambda: a.page.run_task(a.settings_view.show_section, "updates")).start()
        steps += [("update-banner", lambda a: (a.updater._set(fake), a.navigate(0))),
                  ("update-dialog", lambda a: a.updater.show_dialog()),
-                  ("update-settings", lambda a: (a.page.pop_dialog(), a.go("settings")))]
+                  ("update-settings", lambda a: (a.page.pop_dialog(), settings_updates(a))),
+                  ("update-whats-new-bar", lambda a: news(a)),
+                  ("update-whats-new-dialog", lambda a: a.updater.show_news()),
+                  ("update-settings-changelog", lambda a: (a.page.pop_dialog(), settings_updates(a),
+                                                           a.updater.show_history()))]
    if args.frame:
        from frameport.frame.connection import parse_target

@@ -439,53 +818,70 @@ def main() -> int:
            steps.append(("game-connected", lambda a: a.open_game(game)))
        if not args.no_test:
            steps.append(("launch-test-job", job))
-    ready, done = threading.Event(), []
+    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]
+    # a first screen while the web fonts load: shot before that, text measured with a fallback font wrapped or
+    # overlapped ("Q / uest", a check mark over its pill's text); its picture is 00-warmup.png. Settings, not the
+    # Library: opening the Library twice restarts its card loading and the next shot caught it empty
+    steps.insert(0, ("warmup", lambda a: a.go("settings")))
+    ready, shot_done, done = threading.Event(), 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
-
-        keyboard.KeyboardSession = FakeKeyboardSession
-        FramePortApp.connect = lambda self, *a, **k: None
-        FramePortApp.refresh_frame = lambda self, *a, **k: None
+        install_fakes(game)

    def app_main(page: ft.Page):
        try:
            app = FramePortApp(page)
            if args.fake_frame:
-                app.target = FakeTarget()
-                app.frame_info, app.frame_state = app.target.describe(), "connected"
+                attach_fake_frame(app)
        except Exception:  # noqa: BLE001
            ERRORS.append("startup: " + traceback.format_exc())
            return
-        threading.Thread(target=driver, args=(app, steps, ready, done), daemon=True).start()
+        threading.Thread(target=driver, args=(app, steps, ready, shot_done, done), daemon=True).start()

    def shooter():
+        # wait until the app's web server listens (a fixed 6 s was too short with another smoke run on the machine)
+        import socket
+
        from playwright.sync_api import sync_playwright

-        time.sleep(6)
+        for _ in range(90):
+            try:
+                socket.create_connection(("127.0.0.1", PORT), timeout=1).close()
+                break
+            except OSError:
+                time.sleep(1)
+        time.sleep(2)
        try:
            with sync_playwright() as p:
                browser = p.chromium.launch(args=["--use-gl=swiftshader", "--enable-unsafe-swiftshader"])
                page = browser.new_page(viewport={"width": vw, "height": vh})
                page.goto(f"http://127.0.0.1:{PORT}", wait_until="networkidle", timeout=120_000)
-                shot = 0
-                deadline = time.time() + 240 + 8 * len(steps)
-                while len(done) < len(steps) and time.time() < deadline:
-                    if ready.wait(1):
-                        ready.clear()
-                        name = done[-1]
-                        time.sleep(3)  # let Flutter paint
-                        if args.hover and name == "library":
-                            hx, hy = (float(v) for v in args.hover.split(","))
-                            page.mouse.move(hx, hy)
+                shot = handled = 0
+                while handled < len(steps):  # one hand-off per step (see driver)
+                    if not ready.wait(STEP_TIMEOUT):
+                        ERRORS.append(f"browser: no step after {done[-1] if done else 'start'} "
+                                      f"within {STEP_TIMEOUT} s")
+                        break
+                    ready.clear()
+                    name = done[-1]
+                    try:
+                        time.sleep(PAINT_SECONDS)
+                        if name in hover:
+                            page.mouse.move(*hover[name])
                            time.sleep(1.5)
                        page.screenshot(path=str(args.out / f"{shot:02d}-{name}.png"))
                        shot += 1
-                        if name in mouse:
-                            mouse[name](page)
-                            time.sleep(2)
+                        if name in hover:
+                            page.mouse.move(130, 520)  # the sidebar's empty part: nothing left hovered
+                        if name in mouse and mouse[name](page) is not True:
+                            time.sleep(PAINT_SECONDS)  # e.g. typed search: the matching cards fade in
                            page.screenshot(path=str(args.out / f"{shot:02d}-{name}-mouse.png"))
                            shot += 1
+                    finally:
+                        handled += 1
+                        shot_done.set()
                browser.close()
        except Exception:  # noqa: BLE001
            ERRORS.append("browser: " + traceback.format_exc())
@@ -9,19 +9,84 @@ from pathlib import Path
 from ..apk import axml
 from ..core.models import Analysis
 from . import elf
+from .unity_split import split_build as unity_split_build

 logging.getLogger("pyaxmlparser").setLevel(logging.ERROR)

 UNITY_GGM = "assets/bin/Data/globalgamemanagers"
 IL2CPP_METADATA = "assets/bin/Data/Managed/Metadata/global-metadata.dat"

+# The version of what analyze() stores (Analysis.extra["analysis_version"]). BUMP IT whenever analyze() gains a field
+# or detects something differently that patches/heuristics read: library entries analysed by an older FramePort are
+# then analysed again in the background at the next start (pipeline.refresh_analyses), so their new patches are
+# offered (GitHub #104: entries from before `sdl_java` never got frame.sdl_clipboard). Entries without it are 0.
+# 1: sdl_java, min_sdk, web_wrapper, expects_obb, vr_activity, unity_version (2026-10)
+# 2: unity_split (a Unity split-binary build expects an OBB too: expects_obb) (2026-10)
+# 3: unreal_ovrp_lookups (the OVRPlugin functions Unreal's Oculus module looks up: frame.unreal_ovrp_entrypoints)
+ANALYSIS_VERSION = 3

-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:
@@ -111,8 +176,10 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
                if "assets/bin/Data/boot.config" in names else "")
        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
+        # a Unity split build: the rest of the game is in a zip OBB (analysis/unity_split.py)
+        unity_split = "libunity.so" in libs and unity_split_build(z, names, ggm, deep)

-    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 +226,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,
@@ -178,6 +246,7 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
        is_overport_output=is_overport,
        debuggable=bool(axml.Axml(manifest).get_bool("application", "debuggable")),
        extra={
+            "analysis_version": ANALYSIS_VERSION,
            "frame_patched": "libframe_settings.so" in libset,  # already has FramePort's FrameBridge adapter
            # Team Beef's TBXR ports pick their OpenXR path by headset maker (frame.tbxr_vendor): their libraries
            # the game asks Meta's platform for asset files (content shipped as separate files, frame.asset_files)
@@ -216,10 +285,37 @@ 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), or a Unity split build keeps all but its first
+            # scene in one: without it the game hangs at start (GitHub #85, #92)
+            "expects_obb": expects_obb(meta) or unity_split,
+            "unity_split": unity_split,
+            # Unreal's Oculus module needs every OVRPlugin function it looks up (frame.unreal_ovrp_entrypoints)
+            "unreal_ovrp_lookups": (ovrp_lookups(lib_bytes.get(engine_lib.rsplit("/", 1)[1], b""))
+                                    if engine_lib and "libOVRPlugin.so" in libset else []),
        },
    )


+def ovrp_lookups(data: bytes) -> list[str]:
+    """The OVRPlugin function names (`ovrp_*` strings) an engine library holds: Unreal's Oculus module looks each one
+    up with dlsym in libOVRPlugin.so and gives up on VR when any is missing (FOculusHMDModule::
+    InitializeOculusPluginWrapper)."""
+    names, at = set(), data.find(b"\0ovrp_")
+    while at >= 0:
+        end = data.find(b"\0", at + 1)
+        if end < 0:
+            break
+        name = data[at + 1:end]
+        if re.fullmatch(rb"ovrp_[A-Za-z0-9_]+", name):
+            names.add(name.decode())
+        at = data.find(b"\0ovrp_", end)
+    return sorted(names)
+
+
 def unity_text_fields(metadata: bytes) -> list[str]:
    """The Unity text field classes an IL2CPP game contains (names from its global-metadata.dat string table)."""
    out = []
@@ -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
@@ -102,6 +102,60 @@ def _desktop_name(root: Path) -> str | None:
    return None


+def _png_width(path: Path) -> int | None:
+    try:
+        with open(path, "rb") as f:
+            head = f.read(24)
+    except OSError:
+        return None
+    if head[:8] != b"\x89PNG\r\n\x1a\n" or len(head) < 24:
+        return None
+    return int.from_bytes(head[16:20], "big")
+
+
+def find_icon(root: Path) -> Path | None:
+    """The app's own icon in a folder (GitHub #99): the Icon= of its bundled .desktop file, looked up next to the
+    file, in (usr/)share/icons/hicolor/<size>/apps and (usr/)share/pixmaps, or a top-level .DirIcon; the biggest PNG
+    (the PC can't draw SVG icons; the Frame's agent uses those for Desktop Mode). Nothing outside `root` (symlinks
+    are resolved and checked). AppImages are read on the Frame instead (their files are compressed)."""
+    root = Path(root)
+    try:
+        real_root = root.resolve()
+    except OSError:
+        return None
+    paths = [root / ".DirIcon"]
+    desktops = [p for p in sorted(root.rglob("*.desktop"))[:5] if len(p.relative_to(root).parts) <= 4]
+    for desktop in desktops:
+        m = re.search(r"^Icon=(.+)$", desktop.read_text(encoding="utf-8", errors="replace"), re.M)
+        name = m.group(1).strip() if m else ""
+        if not name or name.startswith("/") or ".." in name.split("/"):
+            continue
+        stem = re.sub(r"\.(png|svg|xpm)$", "", name, flags=re.I)
+        bases = [root] + [d for d in desktop.parents if d != root and real_root in d.resolve().parents]
+        for base in bases:
+            paths += [base / name, base / f"{stem}.png"]
+            for share in (base / "usr" / "share", base / "share"):
+                paths += sorted(share.glob(f"icons/hicolor/*/apps/{glob_escape(stem)}.png"))
+                paths.append(share / "pixmaps" / f"{stem}.png")
+        break
+    best: tuple[int, Path] | None = None
+    for p in paths:
+        try:
+            real = p.resolve()
+            if real_root not in real.parents or not real.is_file() or real.stat().st_size > 4 << 20:
+                continue
+        except OSError:
+            continue
+        width = _png_width(real)
+        if width and (best is None or width > best[0]):
+            best = (width, real)
+    return best[1] if best else None
+
+
+def glob_escape(text: str) -> str:
+    return re.sub(r"([*?\[])", r"[\1]", text)
+
+
 def rank_programs(root: Path) -> list[tuple[Path, int]]:
    """(ELF program, machine) candidates, best first: the .desktop Exec= name, then a name like the folder's, then
    shallow and big ones. Libraries (*.so*) are never programs."""
@@ -147,8 +201,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 +234,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 +246,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]}
@@ -24,12 +24,21 @@ def _elf_hash(name: bytes) -> int:
    return h


-def build_stub_library(symbols: list[str], soname: str = "libovrstubs.so", abi: str = "arm64-v8a") -> bytes:
+def build_stub_library(symbols: list[str], soname: str = "libovrstubs.so", abi: str = "arm64-v8a",
+                       result: int = 0) -> bytes:
+    """`result`: what every function returns (a 32-bit int; arm64 only for values other than 0), e.g. OVRPlugin's
+    ovrpFailure (-1000) for stand-ins whose callers must not trust untouched output arguments."""
    is64 = abi == "arm64-v8a"
    symbols = sorted(set(symbols))
+    if result and not (is64 and -0x10000 <= result <= 0xFFFF):
+        raise ValueError(f"stub result {result} not supported for {abi}")
    if is64:
        machine, ehsize, phentsize, shentsize, symsize, dynsize = 183, 64, 56, 64, 24, 16  # EM_AARCH64
        body = struct.pack("<II", 0xD2800000, 0xD65F03C0)  # mov x0, #0 ; ret
+        if result > 0:  # movz w0, #result ; ret
+            body = struct.pack("<II", 0x52800000 | result << 5, 0xD65F03C0)
+        elif result < 0:  # movn w0, #~result ; ret  (w0 = result)
+            body = struct.pack("<II", 0x12800000 | (~result & 0xFFFF) << 5, 0xD65F03C0)
    else:
        machine, ehsize, phentsize, shentsize, symsize, dynsize = 40, 52, 32, 40, 16, 8  # EM_ARM
        body = struct.pack("<II", 0xE3A00000, 0xE12FFF1E)  # mov r0, #0 ; bx lr
@@ -0,0 +1,152 @@
+"""Unity "split application binary" builds: the APK keeps the first scene, the rest of the game is a zip OBB
+(main.<versionCode>.<package>.obb holding assets/bin/Data/...). Without it the game starts into nothing.
+
+Two signs, either is enough (checked against 48 Unity APKs, 30 games: all 13 split builds flagged, none of the 17 full
+builds, whose OBBs, where they have one, are asset bundles or sound banks):
+  A  an XR-plugin build (Oculus XR Plugin / Unity OpenXR library) without assets/bin/Data/UnitySubsystems/ in the APK:
+     the split moves the UnitySubsystems manifests into the OBB; full XR-plugin builds always have them (zip names only;
+     the only sign for split builds with one scene, e.g. BONELAB)
+  B  the build settings list more scenes than the APK has level files (a split keeps level0 only). The scene list
+     comes from globalgamemanagers (loose, or the node of data.unity3d: only the bundle's head and the blocks up to it
+     are read, a few hundred KB of a file that can be hundreds of MB)
+"""
+from __future__ import annotations
+
+import lzma
+import re
+import struct
+import zipfile
+
+DATA = "assets/bin/Data/"
+XR_PLUGIN_LIBS = ("libOculusXRPlugin.so", "libUnityOpenXR.so")
+LEVEL = re.compile(re.escape(DATA) + r"level(\d+)(?:\.|$)")
+MAX_NODE = 64 * 2**20  # globalgamemanagers is 0.1-3 MB; a larger node isn't read
+
+
+def xr_plugin_without_subsystems(names: list[str]) -> bool:
+    """Sign A (zip names only)."""
+    xr_plugin = any(n.startswith("lib/") and n.rsplit("/", 1)[-1] in XR_PLUGIN_LIBS for n in names)
+    return xr_plugin and not any(n.startswith(DATA + "UnitySubsystems/") for n in names)
+
+
+def _cstr(f) -> bytes:
+    out = bytearray()
+    while (c := f.read(1)) not in (b"\0", b""):
+        out += c
+    return bytes(out)
+
+
+def _decompress(data: bytes, kind: int, size: int) -> bytes:
+    if kind == 0:
+        return data
+    if kind in (2, 3):  # LZ4 / LZ4HC
+        import lz4.block
+
+        return lz4.block.decompress(data, uncompressed_size=size)
+    if kind == 1:  # LZMA: 5 bytes of properties, then raw LZMA1
+        props, dict_size = data[0], struct.unpack("<I", data[1:5])[0]
+        dec = lzma.LZMADecompressor(lzma.FORMAT_RAW, filters=[{
+            "id": lzma.FILTER_LZMA1, "dict_size": dict_size, "lc": props % 9, "lp": (props // 9) % 5,
+            "pb": props // 45}])
+        return dec.decompress(data[5:], size)
+    raise ValueError(f"unknown compression {kind}")
+
+
+class _Counting:
+    """A forward-only stream that knows its position (zip member streams have no reliable tell())."""
+
+    def __init__(self, f):
+        self.f, self.pos = f, 0
+
+    def read(self, n: int) -> bytes:
+        b = self.f.read(n)
+        self.pos += len(b)
+        return b
+
+    def align(self, n: int = 16) -> None:
+        if self.pos % n:
+            self.read(n - self.pos % n)
+
+
+def bundle_node(stream, want: str = "globalgamemanagers") -> tuple[list[str], bytes | None]:
+    """(node names, bytes of node `want`) of a UnityFS bundle, reading only up to the end of that node. ([], None)
+    for anything else (old formats, block info at the end of the file)."""
+    f = _Counting(stream)
+    if f.read(8) != b"UnityFS\0":
+        return [], None
+    version = struct.unpack(">I", f.read(4))[0]
+    _cstr(f), _cstr(f)
+    _size, csize, usize, flags = struct.unpack(">qIII", f.read(20))
+    if version >= 7:
+        f.align()
+    if flags & 0x80:  # block info at the end of the file
+        return [], None
+    info = _decompress(f.read(csize), flags & 0x3F, usize)
+    off = 16  # data hash
+    (nblocks,) = struct.unpack(">i", info[off:off + 4])
+    off += 4
+    blocks = []
+    for _ in range(nblocks):
+        blocks.append(struct.unpack(">IIH", info[off:off + 10]))
+        off += 10
+    (nnodes,) = struct.unpack(">i", info[off:off + 4])
+    off += 4
+    nodes = []
+    for _ in range(nnodes):
+        node_off, node_size, _flags = struct.unpack(">qqI", info[off:off + 20])
+        off += 20
+        end = info.index(b"\0", off)
+        nodes.append((info[off:end].decode("utf-8", "replace"), node_off, node_size))
+        off = end + 1
+    if flags & 0x200:  # padding before the first block
+        f.align()
+    names = [n[0] for n in nodes]
+    target = next((n for n in nodes if n[0] == want), None)
+    if target is None or target[2] > MAX_NODE:
+        return names, None
+    need = target[1] + target[2]
+    out = bytearray()
+    for u, c, bf in blocks:
+        if len(out) >= need:
+            break
+        out += _decompress(f.read(c), bf & 0x3F, u)
+    return names, bytes(out[target[1]:need])
+
+
+def build_scene_count(ggm: bytes) -> int | None:
+    """Number of scenes in the build settings (BuildSettings.scenes) of a globalgamemanagers file."""
+    try:
+        import UnityPy
+
+        for obj in UnityPy.load(ggm).objects:
+            if obj.type.name == "BuildSettings":
+                return len(obj.read_typetree().get("scenes") or [])
+    except Exception:  # noqa: BLE001 - unreadable/unknown version: no answer
+        return None
+    return None
+
+
+def more_scenes_than_levels(z: zipfile.ZipFile, names: list[str], ggm: bytes | None = None) -> bool:
+    """Sign B. ggm: the loose globalgamemanagers when already read."""
+    nameset = set(names)
+    levels: set[int] = set()
+    if ggm is None and DATA + "globalgamemanagers" in nameset:
+        ggm = z.read(DATA + "globalgamemanagers")
+    if ggm is not None:
+        levels = {int(m.group(1)) for n in names if (m := LEVEL.match(n))}
+    elif DATA + "data.unity3d" in nameset:
+        try:
+            with z.open(DATA + "data.unity3d") as raw:
+                nodes, ggm = bundle_node(raw)
+        except Exception:  # noqa: BLE001
+            return False
+        levels = {int(m.group(1)) for n in nodes if (m := re.fullmatch(r"level(\d+)", n))}
+    if ggm is None:
+        return False
+    scenes = build_scene_count(ggm)
+    return scenes is not None and scenes > len(levels)
+
+
+def split_build(z: zipfile.ZipFile, names: list[str], ggm: bytes | None = None, deep: bool = True) -> bool:
+    """The APK of a Unity split build (its OBB holds the rest of the game). Without `deep` only sign A."""
+    return xr_plugin_without_subsystems(names) or (deep and more_scenes_than_levels(z, names, ggm))
@@ -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}
@@ -304,6 +304,68 @@ def apply_custom(package: str, kind: str, path: str | Path) -> Path:
    return out


+# A Linux app's own icon (GitHub #99: from its .desktop file / AppImage), applied automatically: no PICKED marker, and
+# APP_ICON records which icon.* it is, so a later pick (store art, the user's own) is told apart from it.
+APP_ICON = ".app-icon"
+APP_ICON_MIN_PX = 16
+
+
+def _sha256(path: Path) -> str:
+    import hashlib
+
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def icon_source(package: str) -> str:
+    """What the game's icon artwork is: "custom" (the user's pick, store art or an install link's icon), "app" (the
+    Linux app's own icon, applied automatically) or "generated" (no icon: Steam's is composed or a placeholder). The
+    Frame's agent puts the app's own icon first unless this says "custom"."""
+    d = fetch.artwork_dir(package)
+    icon = next(iter(sorted(d.glob("icon.*"))), None)
+    if icon is None:
+        return "generated"
+    marker = d / APP_ICON
+    try:
+        if marker.read_text(encoding="utf-8").strip() == _sha256(icon):
+            return "app"
+    except OSError:
+        pass
+    return "custom"
+
+
+def apply_app_icon(package: str, data: bytes) -> Path | None:
+    """Store a Linux app's own icon (PNG/JPEG bytes) as the game's icon when it has none and nothing was picked (the
+    user's choice and store art always stay). Not marked as the user's pick. Returns the stored file, or None when
+    nothing changed."""
+    import io
+
+    from PIL import Image, UnidentifiedImageError
+
+    d = fetch.artwork_dir(package)
+    if (d / fetch.PICKED).exists() or icon_source(package) == "custom":
+        return None
+    try:
+        with Image.open(io.BytesIO(data)) as im:
+            im.load()
+            im = im.copy()
+    except (OSError, UnidentifiedImageError, Image.DecompressionBombError):
+        return None
+    if min(im.size) < APP_ICON_MIN_PX:
+        return None
+    if max(im.size) > 1024:
+        im.thumbnail((1024, 1024), Image.LANCZOS)
+    tmp = d / ".app-icon.tmp"
+    im.convert("RGBA").save(tmp, "PNG", optimize=True)
+    out = d / "icon.png"
+    if out.exists() and out.read_bytes() == tmp.read_bytes():
+        tmp.unlink()
+        return None
+    _drop_kind(d, "icon")
+    tmp.replace(out)
+    (d / APP_ICON).write_text(_sha256(out), encoding="utf-8")
+    return out
+
+
 def remove_custom(package: str, kind: str) -> None:
    """Remove one kind of artwork (the Steam set then composes it from the other kinds, or uses a placeholder)."""
    if kind not in CUSTOM_KINDS:
@@ -110,3 +110,65 @@ def prewarm(package: str) -> None:
        src = pick(package, kinds)
        if src:
            thumb(src, width, src.stem)
+    compute_tint(package)
+
+
+# ------------------------------------------------------------------------------------------ cover tint
+TINT_ART = ("portrait", "square", "cover", "icon")  # the library card's art (the cover people recognise)
+_tints: dict[str, str | None] = {}  # package -> "#rrggbb" (None: no art / no usable colour)
+
+
+def tint_from_rgb(rgb: tuple[int, int, int]) -> str:
+    """A cover's dominant colour made to sit on the dark background: lightness 0.35-0.55, saturation at most 0.55."""
+    import colorsys
+
+    h, lum, s = colorsys.rgb_to_hls(*(max(0, min(255, c)) / 255 for c in rgb))
+    r, g, b = colorsys.hls_to_rgb(h, min(0.55, max(0.35, lum)), min(0.55, s))
+    return "#{:02x}{:02x}{:02x}".format(*(round(c * 255) for c in (r, g, b)))
+
+
+def dominant_rgb(colors: list[tuple[int, tuple[int, int, int]]]) -> tuple[int, int, int] | None:
+    """The most common clearly coloured entry of [(count, rgb)] (saturation ≥ 0.25, neither near black nor near
+    white); else the most common one overall. None for an empty list."""
+    import colorsys
+
+    def colourful(rgb) -> bool:
+        _, lum, s = colorsys.rgb_to_hls(*(c / 255 for c in rgb))
+        return s >= 0.25 and 0.12 <= lum <= 0.88
+    ranked = [rgb for _, rgb in sorted(colors, key=lambda c: -c[0])]
+    return next((rgb for rgb in ranked if colourful(rgb)), ranked[0] if ranked else None)
+
+
+def compute_tint(package: str) -> str | None:
+    """The cover's tint, cached next to the thumbnails (t_tint_<sha8>.json, named after its source like a thumbnail)
+    and in memory. Image work: call from a background thread (render paths use cached_tint)."""
+    import json
+
+    src = pick(package, TINT_ART)
+    value = None
+    if src:
+        out = src.parent / f"t_tint_{_digest(src)}.json"
+        try:
+            value = json.loads(out.read_text(encoding="utf-8")).get("tint")
+        except (OSError, ValueError, AttributeError):
+            try:
+                from PIL import Image
+
+                with Image.open(thumb(src, 400, src.stem)) as im:
+                    small = im.convert("RGB").resize((48, 48))
+                q = small.quantize(colors=8)
+                pal = q.getpalette() or []
+                rgb = dominant_rgb([(n, tuple(pal[i * 3:i * 3 + 3])) for n, i in (q.getcolors() or [])])
+                value = tint_from_rgb(rgb) if rgb else None
+                for old in src.parent.glob("t_tint_*.json"):
+                    old.unlink(missing_ok=True)
+                out.write_text(json.dumps({"tint": value}), encoding="utf-8")
+            except Exception:  # noqa: BLE001  (unreadable image: no tint)
+                value = None
+    _tints[package] = value
+    return value
+
+
+def cached_tint(package: str) -> tuple[bool, str | None]:
+    """(known, tint) from memory only (no I/O, for render paths); known=False: compute_tint hasn't run yet."""
+    return (package in _tints, _tints.get(package))
@@ -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})
@@ -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)."""
@@ -120,9 +120,10 @@ def _refresh_data_fields(g: dict, a: dict) -> bool:
        return False
    from ..analysis import langpacks

+    data = g.get("data_dir") if g.get("data_files") is None else None  # expansion files only: no packs
    try:
-        extra.setdefault("lang_packs", langpacks.find_tags(g.get("data_dir")))
-        extra.setdefault("asset_files", langpacks.find_content_files(g.get("data_dir")))
+        extra.setdefault("lang_packs", langpacks.find_tags(data))
+        extra.setdefault("asset_files", langpacks.find_content_files(data))
    except OSError:
        return False
    return True
@@ -15,11 +15,21 @@ class SourceGame:
    data_dir: Path | None = None  # folder whose contents go to Android/obb/<package>/
    origin: Path | None = None  # the folder the game was found in
    alt_apks: list[Path] = field(default_factory=list)
+    # only these files of data_dir are the game's data (expansion files found by name, e.g. next to the APK); None =
+    # everything below data_dir
+    data_files: list[str] | None = None

    def data_bytes(self) -> int:
-        if not self.data_dir or not self.data_dir.is_dir():
-            return 0
-        return sum(p.stat().st_size for p in self.data_dir.rglob("*") if p.is_file())
+        return sum(data_manifest(self.data_dir, self.data_files).values())
+
+
+def data_manifest(data_dir: Path | None, files: list[str] | None = None) -> dict[str, int]:
+    """{path relative to data_dir: size} of a game's data: every file below data_dir, or only `files` (names in it)."""
+    if not data_dir or not data_dir.is_dir():
+        return {}
+    if files is not None:
+        return {name: (data_dir / name).stat().st_size for name in sorted(files) if (data_dir / name).is_file()}
+    return {p.relative_to(data_dir).as_posix(): p.stat().st_size for p in sorted(data_dir.rglob("*")) if p.is_file()}


@dataclass
@@ -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
@@ -0,0 +1,358 @@
+"""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`
+MIN_AGENT_MODULES = 65  # first agent that takes {"modules": [...]} (collects only what's asked for)
+MODULES = ("games", "procs", "cpu", "gpu", "mem", "temps", "power", "battery", "net", "disk")  # agent MON_MODULES
+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)})
+
+    @property
+    def supports_modules(self) -> bool:
+        return int(self.static.get("agent") or 0) >= MIN_AGENT_MODULES
+
+    def set_modules(self, modules) -> bool:
+        """Ask the agent to collect only these modules (an iterable of MODULES names, or "all"). False (nothing sent)
+        when the agent is older than MIN_AGENT_MODULES: it keeps sending everything."""
+        if not self.supports_modules:
+            return False
+        self.send({"modules": "all" if modules == "all" else sorted(modules)})
+        return True
+
+    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
@@ -0,0 +1,327 @@
+"""MonitorHub: one app-owned `_monitor` stream shared by every place that shows live Frame data (the Monitor tab, the
+sidebar's live Frame card). Subscribers name the modules they need and how often; the hub runs at most one
+MonitorSession with the union of the active subscribers' modules and the fastest interval, reconfigures it when
+subscribers change, fans every sample out, reconnects every RETRY_SECONDS after the stream was lost and stops it when
+nobody (unpaused) is left. No Flet here: callbacks run on the session's reader thread or the hub's own threads.
+
+States passed to `on_state(name, state, detail)`: "connecting", "live", "lost" (detail = why; a retry is scheduled),
+"error" (detail = the exception; no automatic retry, `reconnect()` tries again)."""
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+
+from ..core import applog
+from . import monitor as M
+
+RETRY_SECONDS = 5.0  # reconnect after the stream was lost, while someone subscribes
+ALL = "all"
+
+
+@dataclass
+class Subscriber:
+    name: str
+    modules: frozenset | str  # MODULES names or "all"
+    interval: float
+    on_sample: Callable[[dict], None]
+    on_state: Callable[[str, str, object], None] | None = None
+    paused: bool = False
+
+
+def norm_modules(modules) -> frozenset | str:
+    if modules is None or modules == ALL:
+        return ALL
+    if isinstance(modules, str):
+        return frozenset({modules})
+    return frozenset(modules)
+
+
+def snap_interval(seconds: float) -> float:
+    """The agent only takes M.INTERVALS: the slowest one that is at least as fast as asked."""
+    fits = [i for i in M.INTERVALS if i <= seconds + 1e-9]
+    return float(max(fits) if fits else M.INTERVALS[0])
+
+
+def merge(subs: Iterable[Subscriber]) -> tuple[frozenset | str | None, float | None]:
+    """(modules, interval) one stream needs for the active (unpaused) subscribers: the union of their modules ("all"
+    if any wants everything) and the fastest interval. (None, None) when nobody is active."""
+    active = [s for s in subs if not s.paused]
+    if not active:
+        return None, None
+    if any(s.modules == ALL for s in active):
+        modules: frozenset | str = ALL
+    else:
+        modules = frozenset().union(*(s.modules for s in active))
+    return modules, snap_interval(min(s.interval for s in active))
+
+
+def _timer(delay: float, fn: Callable[[], None]):
+    t = threading.Timer(delay, fn)
+    t.daemon = True
+    t.start()
+    return t
+
+
+def _thread(fn: Callable[[], None]) -> None:
+    threading.Thread(target=fn, name="monitor-hub-connect", daemon=True).start()
+
+
+class MonitorHub:
+    def __init__(self, get_target: Callable[[], object], session_factory=M.MonitorSession,
+                 retry_seconds: float = RETRY_SECONDS, spawn: Callable = _thread, timer: Callable = _timer):
+        self.get_target = get_target
+        self.session_factory = session_factory
+        self.retry_seconds = retry_seconds
+        self._spawn = spawn
+        self._timer = timer
+        self._lock = threading.RLock()
+        self._subs: dict[str, Subscriber] = {}
+        self.session = None
+        self.static: dict = {}
+        self.state, self.detail = "idle", None
+        self._gen = 0
+        self._connecting = False
+        self._pending = None  # generation whose connect waits for the lock to be released
+        self._retry = None
+        self._applied: tuple = (ALL, M.DEFAULT_INTERVAL)  # what the live session runs with
+        self._filter = "game"
+        self._stream_paused = False
+        self.closed = False
+
+    # ---------------------------------------------------------------- subscribers
+    def subscribe(self, name: str, modules, interval: float, on_sample: Callable[[dict], None],
+                  on_state: Callable[[str, str, object], None] | None = None) -> None:
+        with self._lock:
+            self._subs[name] = Subscriber(name, norm_modules(modules), float(interval), on_sample, on_state)
+            note = self._reconcile()
+        self._after(note, name)
+
+    def update(self, name: str, modules=None, interval: float | None = None) -> None:
+        with self._lock:
+            sub = self._subs.get(name)
+            if sub is None:
+                return
+            if modules is not None:
+                sub.modules = norm_modules(modules)
+            if interval is not None:
+                sub.interval = float(interval)
+            note = self._reconcile()
+        self._after(note)
+
+    def unsubscribe(self, name: str) -> None:
+        with self._lock:
+            if self._subs.pop(name, None) is None:
+                return
+            note = self._reconcile()
+        self._after(note)
+
+    def pause(self, name: str, paused: bool = True) -> None:
+        """A paused subscriber gets no samples and doesn't count towards the stream's modules/interval."""
+        with self._lock:
+            sub = self._subs.get(name)
+            if sub is None or sub.paused == bool(paused):
+                return
+            sub.paused = bool(paused)
+            note = self._reconcile()
+        self._after(note, None if paused else name)
+
+    def subscribed(self, name: str) -> bool:
+        return name in self._subs
+
+    def reconnect(self) -> None:
+        """Try again now (after an "error", or when the Frame connection came back)."""
+        with self._lock:
+            if self.session is not None or self._connecting or self.closed:
+                return
+            self._cancel_retry()
+            note = self._reconcile()
+        self._after(note)
+
+    def close(self) -> None:
+        with self._lock:
+            self.closed = True
+            self._subs.clear()
+            self._stop()
+
+    # ---------------------------------------------------------- pass-through actions
+    def set_filter(self, which: str) -> None:
+        """The process filter ("game" | "steam" | "all"); kept for reconnects."""
+        with self._lock:
+            self._filter = which
+            session = self.session
+        if session is not None:
+            session.set_filter(which)
+
+    def pause_stream(self, paused: bool) -> None:
+        """Pause the agent's samples for every subscriber (the stream stays open; kept for reconnects)."""
+        with self._lock:
+            self._stream_paused = bool(paused)
+            session = self.session
+        if session is not None:
+            session.pause(bool(paused))
+
+    def _live(self):
+        session = self.session
+        if session is None:
+            raise M.MonitorUnavailable("the monitor isn't connected")
+        return session
+
+    def kill(self, pid: int, sig: str = "TERM", force: bool = False) -> dict:
+        return self._live().kill(pid, sig, force)
+
+    def end_game(self, package: str) -> dict:
+        return self._live().end_game(package)
+
+    # ---------------------------------------------------------------- internals
+    def _reconcile(self) -> list:
+        """Start, stop or reconfigure the stream for the current subscribers. Called with the lock held; returns the
+        state notifications to send once it's released."""
+        if self.closed:
+            return []
+        modules, interval = merge(self._subs.values())
+        if modules is None:
+            self._stop()
+            return []
+        if self.session is not None:
+            self._configure(self.session, modules, interval)
+            return []
+        if self._connecting or self._retry is not None:
+            return []
+        return self._start()
+
+    def _configure(self, session, modules, interval) -> None:
+        old_modules, old_interval = self._applied
+        try:
+            if interval != old_interval:
+                session.set_interval(interval)
+            if modules != old_modules:
+                session.set_modules(modules)
+        except Exception:  # noqa: BLE001 - the stream ending is reported through on_end
+            applog.log.exception("monitor hub: reconfigure failed")
+        self._applied = (modules, interval)
+
+    def _start(self) -> list:
+        self._connecting = True
+        self._set_state("connecting", None)
+        self._pending = self._gen  # connected by _after() once the lock is released
+        return self._targets()
+
+    def _connect(self, gen: int) -> None:
+        try:
+            target = self.get_target()
+            if target is None:
+                raise M.MonitorUnavailable("not connected to a Frame")
+            session = self.session_factory(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
+            with self._lock:
+                if gen != self._gen:
+                    return
+                self._connecting = False
+                self._set_state("error", exc)
+                note = self._targets()
+            self._notify(note)
+            return
+        with self._lock:
+            self._connecting = False
+            modules, interval = merge(self._subs.values())
+            if gen != self._gen or self.closed or modules is None:  # nobody left while connecting
+                stale = True
+            else:
+                stale = False
+                self.session = session
+                self.static = getattr(session, "static", {}) or {}
+                self._applied = (ALL, M.DEFAULT_INTERVAL)  # the agent's defaults
+                self._configure(session, modules, interval)
+                if self._filter != "game":
+                    session.set_filter(self._filter)
+                if self._stream_paused:
+                    session.pause(True)
+                self._set_state("live", None)
+                note = self._targets()
+        if stale:
+            session.close()
+            return
+        self._notify(note)
+
+    def _on_sample(self, gen: int, sample: dict) -> None:
+        if gen != self._gen:
+            return
+        for sub in [s for s in list(self._subs.values()) if not s.paused]:
+            try:
+                sub.on_sample(sample)
+            except Exception:  # noqa: BLE001 - one subscriber's bug must not starve the others
+                applog.log.exception("monitor hub: subscriber %s failed", sub.name)
+
+    def _on_end(self, gen: int, why: str) -> None:
+        with self._lock:
+            if gen != self._gen or self.closed:
+                return
+            self.session = None
+            if merge(self._subs.values())[0] is None:
+                return
+            self._set_state("lost", why)
+            note = self._targets()
+            self._retry = self._timer(self.retry_seconds, lambda: self._retry_now(gen))
+        self._notify(note)
+
+    def _retry_now(self, gen: int) -> None:
+        with self._lock:
+            if gen != self._gen or self.closed:
+                return
+            self._retry = None
+            note = self._reconcile()
+        self._after(note)
+
+    def _cancel_retry(self) -> None:
+        if self._retry is not None:
+            try:
+                self._retry.cancel()
+            except Exception:  # noqa: BLE001
+                pass
+            self._retry = None
+
+    def _stop(self) -> None:
+        """No active subscriber: end the stream (and anything pending). Lock held."""
+        self._gen += 1
+        self._connecting = False
+        self._cancel_retry()
+        session, self.session = self.session, None
+        self.state, self.detail = "idle", None
+        if session is not None:
+            try:
+                session.close()
+            except Exception:  # noqa: BLE001
+                pass
+
+    def _set_state(self, state: str, detail) -> None:
+        self.state, self.detail = state, detail
+
+    def _targets(self) -> list:
+        return [(s, self.state, self.detail) for s in self._subs.values() if not s.paused and s.on_state]
+
+    def _tell(self, name: str) -> None:
+        """Bring one (new or resumed) subscriber up to date with the stream's state."""
+        sub = self._subs.get(name)
+        if sub and sub.on_state and not sub.paused and self.state != "idle":
+            self._notify([(sub, self.state, self.detail)])
+
+    def _after(self, note: list, name: str | None = None) -> None:
+        """Outside the lock: send state notifications (or bring `name` up to date), then start a queued connect."""
+        if note:
+            self._notify(note)
+        elif name is not None:
+            self._tell(name)
+        with self._lock:
+            gen, self._pending = self._pending, None
+        if gen is not None:
+            self._spawn(lambda: self._connect(gen))
+
+    @staticmethod
+    def _notify(note: list) -> None:
+        for sub, state, detail in note:
+            try:
+                sub.on_state(sub.name, state, detail)
+            except Exception:  # noqa: BLE001
+                applog.log.exception("monitor hub: state handler of %s failed", sub.name)
@@ -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
@@ -10,7 +10,7 @@ from pathlib import Path
 from ..artwork import fetch as artwork
 from ..build import sha256
 from ..core.events import Reporter
-from ..core.models import Recipe
+from ..core.models import Recipe, data_manifest
 from ..frame.connection import Frame, sh_quote
 from ..patches import base
 from ..patches.settings import adapter_settings
@@ -25,6 +25,7 @@ class InstallPlan:
    recipe: Recipe
    apk_only: bool = False  # reuse the data already on the Frame
    dest: str | None = None
+    data_files: list[str] | None = None  # only these files of data_dir (SourceGame.data_files); None = all of it


 def install_context(recipe: Recipe) -> base.InstallContext:
@@ -38,10 +39,8 @@ def install_context(recipe: Recipe) -> base.InstallContext:
    return ctx


-def local_data_manifest(data_dir: Path | None) -> dict[str, int]:
-    if not data_dir or not data_dir.is_dir():
-        return {}
-    return {p.relative_to(data_dir).as_posix(): p.stat().st_size for p in sorted(data_dir.rglob("*")) if p.is_file()}
+def local_data_manifest(data_dir: Path | None, files: list[str] | None = None) -> dict[str, int]:
+    return data_manifest(data_dir, files)


 class Speed:
@@ -74,7 +73,7 @@ def install(frame: Frame, plan: InstallPlan, reporter: Reporter) -> dict:
    if not prep.get("lepton"):
        raise RuntimeError("Lepton is not installed on the Frame (Setup → Install Lepton)")
    incoming = prep["incoming"]
-    manifest = {} if plan.apk_only else local_data_manifest(plan.data_dir)
+    manifest = {} if plan.apk_only else local_data_manifest(plan.data_dir, plan.data_files)
    existing = prep["existing_obb"]
    to_send = [rel for rel, size in manifest.items() if existing.get(rel) != size]
    need = sum(manifest[r] for r in to_send) + (0 if prep["same_apk"] else plan.apk.stat().st_size)
@@ -113,7 +112,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 +226,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 +259,14 @@ 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']})")
+    apply_app_icon(frame, plan.package, prep.get("anchor"), result, reporter)
+    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
@@ -412,9 +432,46 @@ def upload_steam_art(frame: Frame, package: str, base: str, reporter: Reporter)
    frame.run(f"rm -rf {sh_quote(remote_art)} && mkdir -p {sh_quote(remote_art)}")
    for kind, f in art.items():
        frame.put(f, posixpath.join(remote_art, f"{kind}{f.suffix}"), resume=False)
+    send_icon_source(frame, package, remote_art)
    reporter.check("Steam artwork", bool(art) or None, ", ".join(sorted(art)) or "none found")


+def send_icon_source(frame: Frame, package: str, remote_art: str) -> None:
+    """Tell the agent what the art set's icon is (artwork/.icon-source, agent v64): a Linux app's own icon is used
+    for its Desktop Mode entry and Steam shortcut unless the user chose one ("custom")."""
+    from ..artwork.sources import icon_source
+
+    frame.run(f"printf %s {sh_quote(icon_source(package))} > {sh_quote(posixpath.join(remote_art, '.icon-source'))}")
+
+
+def apply_app_icon(frame: Frame, package: str, anchor: str | None, result: dict, reporter: Reporter) -> None:
+    """A Linux app's own icon the agent found in its files (GitHub #99) becomes the library's icon when the game has
+    none (no user pick, no store icon); the Frame's art set is then sent again so Steam's art shows it too."""
+    import base64
+
+    from ..artwork import sources, steam
+
+    icon = result.get("app_icon") or {}
+    if icon:
+        reporter.log(f"the app's own icon: {icon.get('file')}")
+    if not icon.get("png") or not anchor:
+        return
+    try:
+        stored = sources.apply_app_icon(package, base64.b64decode(icon["png"]))
+        if not stored:
+            return
+        steam.ensure_cover(package)
+        art = steam.steam_set_for(package)
+    except Exception as exc:  # noqa: BLE001 - artwork is optional
+        reporter.log(f"the app's own icon wasn't used for the library: {exc}")
+        return
+    remote = posixpath.join(anchor, "artwork")
+    for kind, f in art.items():
+        frame.put(f, posixpath.join(remote, f"{kind}{f.suffix}"), resume=False)
+    send_icon_source(frame, package, remote)
+    reporter.check("App icon", True, "the app's own icon is used for the library")
+
+
 def update_steam_art(frame: Frame, package: str, reporter: Reporter) -> dict:
    """Replace an installed game's Steam library art with the current artwork (after the user picked new art):
    the art set goes to the game's anchor, then the shortcut is rewritten (Steam restarts once)."""
@@ -433,6 +490,7 @@ def update_steam_art(frame: Frame, package: str, reporter: Reporter) -> dict:
    frame.run(f"rm -rf {sh_quote(remote)} && mkdir -p {sh_quote(remote)}")
    for kind, f in art.items():
        frame.put(f, posixpath.join(remote, f"{kind}{f.suffix}"), resume=False)
+    send_icon_source(frame, package, remote)
    reporter.check("Steam artwork", True, ", ".join(sorted(art)))
    return add_to_steam(frame, [package], reporter)

@@ -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();
@@ -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:
@@ -295,6 +318,7 @@ class _Handler(BaseHTTPRequestHandler):
            self._send(503, relay.ended.encode(), "text/plain")
            return
        init, gop, q = relay.subscribe()
+        sent, why, t0 = 0, "the stream ended", time.time()
        try:
            deadline = time.time() + 30
            while init is None:  # the source hasn't sent its init segment yet
@@ -312,6 +336,9 @@ class _Handler(BaseHTTPRequestHandler):
            self._chunk(init)
            for f in gop:
                self._chunk(f)
+            sent = len(gop)
+            agent = self.headers.get("User-Agent", "?")[:60]
+            log.info("live view: viewer joined (%s)", agent)
            while True:
                try:
                    f = q.get(timeout=5)
@@ -319,14 +346,18 @@ class _Handler(BaseHTTPRequestHandler):
                    if relay.ended:
                        break
                    continue
-                if f is None:
+                if f is None:  # finish() or dropped for lagging CLIENT_QUEUE fragments behind
+                    why = "the stream ended" if relay.ended else "it fell too far behind"
                    break
                self._chunk(f)
+                sent += 1
            self.wfile.write(b"0\r\n\r\n")
-        except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError, OSError):
-            pass
+        except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError, OSError) as exc:
+            why = f"it disconnected ({type(exc).__name__})"
        finally:
            relay.unsubscribe(q)
+        if init is not None:
+            log.info("live view: viewer left after %.1f s, %d fragments: %s", time.time() - t0, sent, why)

    def _chunk(self, data: bytes) -> None:
        self.wfile.write(f"{len(data):x}\r\n".encode() + data + b"\r\n")
@@ -343,9 +374,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 +391,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 +482,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 +542,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 +559,81 @@ 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."""
+    client = getattr(frame, "client", None)
+    transport = client.get_transport() if client is not None else None
+    if transport is None or not transport.is_active():
+        # (e.g. the Frame slept: without this, the helper upload failed with "'NoneType' object has no attribute
+        # 'exec_command'" and the start went on with the software encoder)
+        raise ConnectionError("The Frame isn't connected (it may be asleep): connect it again on the Steam Frame "
+                              "page, then start the live view")
    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 +652,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:
@@ -149,3 +149,10 @@ def delete(frame, shots: list[dict]) -> int:
        for kind in ("thumb", "full"):
            (cache_dir(frame) / _cache_name(s, kind)).unlink(missing_ok=True)
    return len(r.get("deleted") or [])
+
+
+def take(frame, wait: float = 8) -> dict:
+    """Take a headset screenshot on the Frame (agent v66 `take_screenshot`: OpenVR's RequestScreenshot +
+    SubmitScreenshot, saved by Steam under SteamVR like one taken in the headset): {taken, path, reason, hmd}.
+    reason "steamvr" = SteamVR isn't running, "capture" = nothing captured (the headset sleeps)."""
+    return frame.agent("take_screenshot", wait=wait)
@@ -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:
@@ -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",
+))
@@ -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",
+))
@@ -0,0 +1,99 @@
+"""Unpaired pointer-authentication hints (PAC) in a game's native libraries.
+
+paciasp signs the return address on function entry and autiasp checks it before returning. Both are HINT
+instructions: CPUs without pointer authentication (the Quest's) execute them as NOPs, the Steam Frame's CPU checks
+them and raises SIGILL (ILL_ILLOPN at an autiasp) when a check fails. Some OpenSSL ARMv8 assembly built into game
+engines has an autiasp without the matching paciasp (e.g. Star Wars Pinball VR's libUE4.so: 38 paciasp, 40 autiasp,
+the crash in the Poly1305 NEON code on Unreal's HttpManager thread), so the game dies as soon as it opens a TLS
+connection. Only libraries whose PAC hints come from hand-written assembly are changed: compiler-protected code
+signs almost every function and has several autiasp per paciasp where a function has several returns (OVRPort's
+libopenxr_loader_generic.so: 1084 paciasp, 1114 autiasp, 7092 ret; stripping it hung OVRPlugin's start-up), while an
+engine without branch protection has a few dozen hints among hundreds of thousands of returns (libUE4.so: 38 among
+342581). So a library is changed when its counts differ and its paciasp are under 0.2 % of its ret instructions; then
+every paciasp/autiasp becomes a NOP (the same 4 bytes in place) and the code behaves as on the Quest. The combined
+forms (retaa/retab, pacibsp/autibsp) aren't touched; a library using them is left alone."""
+from __future__ import annotations
+
+from ...analysis import elf
+from ..base import ApkContext, Patch, register
+
+PACIASP = (0xD503233F).to_bytes(4, "little")
+AUTIASP = (0xD50323BF).to_bytes(4, "little")
+NOP = (0xD503201F).to_bytes(4, "little")
+RET = (0xD65F03C0).to_bytes(4, "little")
+MAX_ASM_SHARE = 0.002  # paciasp per ret: above this the library is compiler-protected (left alone)
+COMBINED = tuple(w.to_bytes(4, "little") for w in (0xD65F0BFF, 0xD65F0FFF, 0xD503237F, 0xD50323FF))  # retaa/b, *ibsp
+
+
+def _exec_ranges(data: bytes) -> list[tuple[int, int]]:
+    """File ranges of the executable PT_LOAD segments."""
+    import io
+
+    from elftools.elf.elffile import ELFFile
+
+    e = ELFFile(io.BytesIO(data))
+    return [(s["p_offset"], s["p_offset"] + s["p_filesz"]) for s in e.iter_segments()
+            if s["p_type"] == "PT_LOAD" and s["p_flags"] & 1]
+
+
+def _find(data: bytes, word: bytes, ranges) -> list[int]:
+    out = []
+    for lo, hi in ranges:
+        i = data.find(word, lo, hi)
+        while i >= 0:
+            if i % 4 == 0:
+                out.append(i)
+            i = data.find(word, i + 1, hi)
+    return out
+
+
+def unpaired(data: bytes) -> tuple[list[int], list[int]] | None:
+    """(paciasp offsets, autiasp offsets) when a library's counts differ, else None."""
+    if not elf.is_elf(data):
+        return None
+    ranges = _exec_ranges(data)
+    pac, aut = _find(data, PACIASP, ranges), _find(data, AUTIASP, ranges)
+    if len(pac) == len(aut) or any(_find(data, w, ranges) for w in COMBINED):
+        return None
+    if len(pac) > MAX_ASM_SHARE * max(len(_find(data, RET, ranges)), 1):
+        return None  # compiler-protected (several returns per signed function), not hand-written assembly
+    return pac, aut
+
+
+class PacHints(Patch):
+    id = "frame.pac_hints"
+    title = "Unpaired pointer-authentication checks"
+    description = ("Some engines contain assembly (e.g. OpenSSL's) that checks a return-address signature it never "
+                   "made. The Quest's CPU ignores those checks, the Steam Frame's enforces them: the game crashes with "
+                   "SIGILL as soon as it uses that code, e.g. on its first network connection (Star Wars Pinball "
+                   "VR). In a library with unpaired checks, the signing and checking instructions become no-ops.")
+    order = 47
+    revision = 1
+
+    def applies(self, a):
+        return "arm64-v8a" in a.abis
+
+    def detect(self, a):
+        return None  # reading every engine library at analysis time is too slow; triage (pac-unpaired) suggests it
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a":
+            return False
+        changed = False
+        for lib in ws.libs():
+            data = ws.read_lib(lib)
+            found = unpaired(data)
+            if not found:
+                continue
+            pac, aut = found
+            out = bytearray(data)
+            for off in pac + aut:
+                out[off:off + 4] = NOP
+            ws.put(ws.lib(lib), bytes(out))
+            ctx.notes.append(f"{lib}: {len(pac)} paciasp / {len(aut)} autiasp turned into NOPs (unpaired)")
+            changed = True
+        return changed
+
+
+register(PacHints)
@@ -0,0 +1,132 @@
+"""BONELAB 1.2974 (and other Stress Level Zero builds) ship libSLZQuestNative.so, a Unity native plugin that hooks
+Unity's Vulkan start-up (IUnityGraphicsVulkanV2 interception: its vkCreateInstance/vkCreateDevice wrappers raise the
+API version, enable device features and check its pipeline cache) and replaces Unity's vkCreateSampler (anisotropy
+<= 4, LOD bias -0.25). On the Frame its vkCreateInstance wrapper calls through an invalid pointer right after
+OVRPlugin's pre-init OpenXR instance is destroyed: a jump into an unloaded library, to address 0, or a hang, depending
+on the run. The plugin's two registrations with Unity are turned into no-ops (in place, 4 bytes each), so Unity runs
+Vulkan itself; the plugin still loads. Its sampler hook must go too: without the device hook it never learns the real
+vkCreateSampler."""
+from __future__ import annotations
+
+import struct
+
+from ...analysis import elf
+from ..base import ApkContext, Patch, Suggestion, register
+
+LIB = "libSLZQuestNative.so"
+ON_LOAD = "RenderAPI_Vulkan_OnPluginLoad"  # registers the Vulkan-init interception
+GFX_INIT = "_ZN8PluginVk12GfxEventInitEv"  # PluginVk::GfxEventInit: InterceptVulkanAPI("vkCreateSampler", hook)
+SAMPLER = b"vkCreateSampler\0"
+NOP = 0xD503201F
+MOV_X1_XZR, MOV_W2_WZR = 0xAA1F03E1, 0x2A1F03E2  # AddInterceptInitialization(func, userdata = NULL, flags = 0)
+
+
+def _is_blr(insn: int) -> bool:
+    return insn & 0xFFFFFC1F == 0xD63F0000
+
+
+def _x0_address(data: bytes, segs, at: int, back: int = 8) -> int | None:
+    """The address `adrp xN, page` + `add x0, xN, #imm` puts in x0 within `back` instructions before `at`."""
+    for i in range(1, back):
+        add_va = at - 4 * i
+        add_off = elf.vaddr_to_offset(segs, add_va)
+        if add_off is None:
+            return None
+        add = struct.unpack_from("<I", data, add_off)[0]
+        if add & 0xFFC0001F != 0x91000000:  # add x0, xN, #imm12 (no shift)
+            continue
+        rn, imm12 = (add >> 5) & 0x1F, (add >> 10) & 0xFFF
+        for j in range(i + 1, back + 4):
+            adrp_off = elf.vaddr_to_offset(segs, at - 4 * j)
+            if adrp_off is None:
+                return None
+            adrp = struct.unpack_from("<I", data, adrp_off)[0]
+            if adrp & 0x9F000000 == 0x90000000 and adrp & 0x1F == rn:
+                imm = ((adrp >> 5) & 0x7FFFF) << 2 | (adrp >> 29) & 3
+                if imm & (1 << 20):
+                    imm -= 1 << 21
+                return ((at - 4 * j) & ~0xFFF) + (imm << 12) + imm12
+        return None
+    return None
+
+
+def _function(data: bytes, name: str) -> tuple[int, int] | None:
+    sec = elf._elf(data).get_section_by_name(".dynsym")
+    for sym in (sec.get_symbol_by_name(name) or []) if sec else []:
+        if sym["st_value"] and sym["st_size"]:
+            return sym["st_value"], sym["st_size"]
+    return None
+
+
+def find_registrations(data: bytes) -> list[int]:
+    """File offsets of the plugin's two `blr` registrations (interception, vkCreateSampler), [] when not this plugin."""
+    segs = elf.load_segments(data)
+    sampler = data.find(b"\0" + SAMPLER) + 1
+    on_load, gfx_init = _function(data, ON_LOAD), _function(data, GFX_INIT)
+    if not on_load or not gfx_init or sampler <= 0:
+        return []
+    out = []
+    for (start, size), wanted in ((on_load, "intercept"), (gfx_init, "sampler")):
+        for va in range(start, start + size, 4):
+            off = elf.vaddr_to_offset(segs, va)
+            if off is None or not _is_blr(struct.unpack_from("<I", data, off)[0]):
+                continue
+            prev = [struct.unpack_from("<I", data, o)[0] for k in range(1, 5)
+                    if va - 4 * k >= start and (o := elf.vaddr_to_offset(segs, va - 4 * k)) is not None]
+            if wanted == "intercept" and MOV_X1_XZR in prev and MOV_W2_WZR in prev:
+                out.append(off)
+                break
+            # the string lives in the first (read-only) segment, where file offset == address
+            if wanted == "sampler" and _x0_address(data, segs, va) == sampler:
+                out.append(off)
+                break
+    return out if len(out) == 2 else []
+
+
+class SlzVulkanHooks(Patch):
+    id = "frame.slz_vulkan_hooks"
+    title = "Stress Level Zero: let Unity start Vulkan itself"
+    description = ("Stress Level Zero's graphics plugin (libSLZQuestNative.so, e.g. BONELAB 1.2974) hooks Unity's "
+                   "Vulkan start-up and its texture samplers. On the Frame the hook calls an invalid function while "
+                   "Vulkan starts, and the game crashes or hangs before the first frame. The plugin's two hooks are "
+                   "switched off, so Unity starts Vulkan itself. Its pipeline cache isn't used: the first start "
+                   "spends about half a minute prewarming shaders.")
+    order = 47
+    revision = 1
+
+    def applies(self, a):
+        return "arm64-v8a" in a.abis and LIB in a.libs
+
+    def detect(self, a):
+        if self.applies(a):
+            return Suggestion(True, "Stress Level Zero's graphics plugin crashes Unity's Vulkan start-up on the Frame "
+                                    "(e.g. BONELAB 1.2974).")
+        return None
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        name = ws.lib(LIB)
+        if ws.abi != "arm64-v8a" or not ws.has(name):
+            return False
+        data = ws.read(name)
+        sites = find_registrations(data)
+        if not sites:
+            return False
+        buf = bytearray(data)
+        for off in sites:
+            struct.pack_into("<I", buf, off, NOP)
+        ws.put(name, bytes(buf))
+        ctx.notes.append(f"{LIB}: Vulkan interception and vkCreateSampler hook switched off "
+                         f"({', '.join(hex(o) for o in sites)})")
+        return True
+
+    def validate(self, ctx: ApkContext):
+        ws = ctx.ws
+        name = ws.lib(LIB)
+        if not ws.has(name):
+            return []
+        left = find_registrations(ws.read(name))
+        return [("SLZ Vulkan hooks off", not left, "" if not left else "still registered")]
+
+
+register(SlzVulkanHooks)
@@ -16,6 +16,10 @@ ALWAYS_THERE = "android"
 # Unity's legacy frame loop never calls ovrp_WaitToBeginFrame: its ovrp_Update2 lookup goes to native/ovrpshim
 SHIM = "libfp_ovrp.so"
 UPDATE, SHIM_UPDATE = "ovrp_Update2", "fpov_Update2"
+# the shim follows Unity's frame begins/ends so its frame wait never blocks for a frame Unity didn't begin (Sniper Elite
+# VR deadlocked at a scene switch: xrWaitFrame waits for the previous frame's xrBeginFrame)
+BEGIN, SHIM_BEGIN = "ovrp_BeginFrame", "fpov_BeginFrame"
+END, SHIM_END = "ovrp_EndFrame", "fpov_EndFrame"
 # Unity creates its XR controller devices for the hand nodes OVRPlugin reports present (logged/fixed by the shim)
 NODE, SHIM_NODE = "ovrp_GetNodePresent", "fpov_GetNodePresent"
 # input diagnostics (off): the C# P/Invoke names in libil2cpp.so pointed at the shim's wrappers, which log what they
@@ -76,13 +80,19 @@ class UnityOculusCheck(Patch):
                   "libunity.so at \"android\", which always exists. Games on Unity's built-in VR (2017–2018, and 2019 "
                   "without the Oculus XR Plugin) also get the frame wait their legacy frame loop never makes "
                   "(libfp_ovrp.so calls ovrp_WaitToBeginFrame before ovrp_Update2; without it no frame starts, the "
-                   "dashboard freezes or the GPU hangs). The shim also counts a newly pressed trigger or A/B/X/Y as a "
-                   "mouse click (Input.GetMouseButtonDown), which Go-era screens wait for (e.g. Accounting+'s motion "
+                   "dashboard freezes or the GPU hangs). Per game, the settings ovrp_begin_gate (a freeze at the first "
+                   "scene switch) and ovrp_hold_physics (hands trailing the controllers) switch on two more frame-loop "
+                   "fixes (e.g. Sniper Elite VR). The shim also "
+                   "counts a newly pressed trigger or A/B/X/Y as a mouse click (Input.GetMouseButtonDown), which "
+                   "Go-era screens wait for (e.g. Accounting+'s motion "
                   "warning) and which Lepton never delivers.")
    order = 45
    # 2: frame wait also for Unity 2019 without the Oculus XR Plugin; 3: controller presses as mouse clicks
    # (ovrpshim); 4: Unity 2019's Oculus device-model checks (Touch controllers on Lepton)
-    revision = 4
+    # 5: frame begins gate the frame wait (no deadlock when Unity skips a frame); physics-step pose
+    # updates kept from OVRPlugin (they located poses in the past: hands lagged); both only with the per-game settings
+    # ovrp_begin_gate / ovrp_hold_physics (BattleSisters' hands lagged with them)
+    revision = 5

    @staticmethod
    def _major(a) -> int:
@@ -117,6 +127,11 @@ class UnityOculusCheck(Patch):
            return False
        data, loops = elf.replace_rodata_string(data, UPDATE, SHIM_UPDATE) if self.legacy_loop(ctx.analysis) \
            else (data, 0)
+        if loops:
+            data, begins = elf.replace_rodata_string(data, BEGIN, SHIM_BEGIN)
+            if begins:  # the end goes with it: a begin the shim gave the waited frame's index ends with that index
+                data, _ = elf.replace_rodata_string(data, END, SHIM_END)
+                ctx.notes.append(f"libunity.so: {BEGIN}/{END} -> {SHIM_BEGIN}/{SHIM_END}")
        if loops and self._major(ctx.analysis) >= 2019:  # Accounting+ (2017) reads OVRInput: works without
            data, models = oculus_model_checks(data)
            if models:
@@ -0,0 +1,120 @@
+"""OVRPlugin functions Unreal looks up that OVRPort's OVRPlugin lacks.
+
+Unreal's Oculus module (FOculusHMDModule::InitializeOculusPluginWrapper) looks up every `ovrp_*` function of the
+OVRPlugin version it was built against with dlsym on libOVRPlugin.so's handle and ANDs the results: one missing name
+and the wrapper fails, OculusHMD never pre-initialises, no OpenXR session starts and the game later crashes without an
+HMD (e.g. Star Wars Pinball VR, UE 4.25 built against OVRPlugin 1.44: OVRPort's OpenXR OVRPlugin has no
+ovrp_GetPTWNear). OVRPort replaces the plugin, so the names come from the engine library and are compared with the
+plugin the build ships. Each missing one gets a stand-in that returns ovrpFailure (-1000), so callers take their "not
+supported" path and never read untouched output arguments. The stand-ins live in a generated library that
+libOVRPlugin.so loads (DT_NEEDED): dlsym on a library's handle also searches its dependencies, and the plugin's own
+functions are found first, so a later OVRPort that adds a function wins over its stand-in. The engine library stays
+byte-identical."""
+from __future__ import annotations
+
+from ...analysis import elf
+from ...analysis.detect import ovrp_lookups
+from ...analysis.stubgen import build_stub_library
+from ..base import ApkContext, Patch, Suggestion, register
+
+PLUGIN = "libOVRPlugin.so"
+STUBS = "libfp_ovrpstubs.so"
+ENGINE_LIBS = ("libUE4.so", "libUnreal.so")
+OVRP_FAILURE = -1000  # ovrpResult ovrpFailure
+# fallback before OVRPort downloaded a runtime (nothing to compare with yet): names its OpenXR OVRPlugin (3.4.3) is
+# known to lack that Unreal builds look up. The build itself always compares with the plugin it ships.
+KNOWN_MISSING = ("ovrp_GetPTWNear",)
+
+
+def _shipped_exports(abi: str) -> set[str] | None:
+    """Exports of the newest OVRPort runtime's libOVRPlugin.so, cached per file version (None: none downloaded)."""
+    from ...tools import overport
+
+    path = overport.runtime_lib(PLUGIN, abi)
+    if not path:
+        return None
+    st = path.stat()
+    key = (str(path), st.st_mtime_ns, st.st_size)
+    if _cache.get("key") != key:
+        _cache.update(key=key, exports=elf.dyn_symbols(path.read_bytes(), True))
+    return _cache["exports"]
+
+
+_cache: dict = {}
+
+
+def missing_lookups(lookups, plugin_exports) -> list[str]:
+    return sorted(set(lookups) - set(plugin_exports))
+
+
+class UnrealOvrpEntrypoints(Patch):
+    id = "frame.unreal_ovrp_entrypoints"
+    title = "Unreal: stand-ins for OVRPlugin functions OVRPort lacks"
+    description = ("Unreal's Oculus module looks up every OVRPlugin function it was built against and starts no VR "
+                   "when one is missing; OVRPort's OpenXR OVRPlugin lacks some old ones (e.g. ovrp_GetPTWNear, which "
+                   "Unreal 4.25 builds like Star Wars Pinball VR look up). The game then never starts an OpenXR "
+                   "session and crashes a few seconds in. Adds a generated library to libOVRPlugin.so with a stand-in "
+                   "for each missing function that reports failure (ovrpFailure), so Unreal's Oculus support starts. "
+                   "The functions OVRPort has are untouched.")
+    order = 46
+
+    def applies(self, a):
+        return a.engine == "Unreal" and PLUGIN in a.libs and "arm64-v8a" in a.abis
+
+    def detect(self, a):
+        lookups = (a.extra or {}).get("unreal_ovrp_lookups") or []
+        if not self.applies(a) or not lookups:
+            return None
+        exports = _shipped_exports("arm64-v8a")
+        if exports is None:
+            missing = sorted(set(lookups) & set(KNOWN_MISSING))
+        else:
+            missing = missing_lookups(lookups, exports)
+        if not missing:
+            return None
+        return Suggestion(True, f"Unreal looks up OVRPlugin function(s) OVRPort's OVRPlugin lacks: "
+                                f"{', '.join(missing[:6])}{' …' if len(missing) > 6 else ''}. Without them Unreal "
+                                "starts no VR.")
+
+    def _missing(self, ctx: ApkContext) -> list[str]:
+        ws = ctx.ws
+        lookups = (ctx.analysis.extra or {}).get("unreal_ovrp_lookups")
+        if not lookups:  # analysed by an older FramePort: read the engine library itself
+            engine = next((ws.lib(n) for n in ENGINE_LIBS if ws.has(ws.lib(n))), None)
+            lookups = ovrp_lookups(ws.read(engine)) if engine else []
+        return missing_lookups(lookups, elf.dyn_symbols(ws.read_lib(PLUGIN), True))
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a" or not ws.has(ws.lib(PLUGIN)):
+            return False
+        missing = self._missing(ctx)
+        if not missing:
+            return False
+        plugin = ws.read_lib(PLUGIN)
+        stubs = build_stub_library(missing, STUBS, ws.abi, result=OVRP_FAILURE)
+        changed = False
+        if STUBS not in elf.needed(plugin):
+            ws.put(ws.lib(PLUGIN), elf.add_needed(plugin, STUBS))
+            changed = True
+        if not ws.has(ws.lib(STUBS)) or ws.read_lib(STUBS) != stubs:
+            ws.put(ws.lib(STUBS), stubs)
+            changed = True
+        if changed:
+            ctx.notes.append(f"{len(missing)} OVRPlugin stand-in(s) returning ovrpFailure: {', '.join(missing)}")
+        return changed
+
+    def validate(self, ctx):
+        ws = ctx.ws
+        if not ws.has(ws.lib(PLUGIN)):
+            return []
+        plugin = ws.read_lib(PLUGIN)
+        exports = set(elf.dyn_symbols(plugin, True))
+        if STUBS in elf.needed(plugin) and ws.has(ws.lib(STUBS)):
+            exports |= elf.dyn_symbols(ws.read_lib(STUBS), True)
+        lookups = (ctx.analysis.extra or {}).get("unreal_ovrp_lookups") or []
+        unresolved = missing_lookups(lookups, exports)
+        return [("OVRPlugin functions Unreal looks up resolvable", not unresolved, ", ".join(unresolved[:5]))]
+
+
+register(UnrealOvrpEntrypoints)
@@ -108,6 +108,31 @@ class UnityGlShim(GlShim):
        return a.engine == "Unity" and "GLES" in a.graphics and "arm64-v8a" in a.abis


+class UnrealGlShim(GlShim):
+    id = "frame.unreal_gl_shim"
+    title = "GL shim for Unreal (no multisampled render-to-texture)"
+    description = (
+        "Loads the GL shim into an Unreal GLES game and hides GL_EXT_multisampled_render_to_texture. Unreal's mobile "
+        "MSAA renders through multisampled render-to-texture, and the Frame's GL driver (Mesa/Zink) can crash on it: "
+        "SIGSEGV with fault address 0x10000 in libgallium_dri.so on the RHIThread a few seconds after start (Zink "
+        "looks up a render-pass cache slot past its end, e.g. Star Wars Pinball VR). Hidden, Unreal renders without "
+        "that path. Unreal's multiview stays on: Unreal only uses it when GL_OVR_multiview_multisampled_render_to_"
+        "texture is listed too, so for Unreal the shim keeps that one visible and draws its multiview MSAA "
+        "attachments single-sampled (glFramebufferTextureMultiviewOVR).")
+    order = 62
+    requires = ()
+    experimental = False
+
+    def detect(self, a):
+        # not suggested from the APK alone: most Unreal GLES games run without it; the launch test's triage
+        # (unreal-msrtt-crash) and catalog recipes turn it on
+        return None
+
+    def applies(self, a):
+        return a.engine == "Unreal" and "GLES" in a.graphics and "arm64-v8a" in a.abis
+
+
 register(VrApiBridge)
 register(GlShim)
 register(UnityGlShim)
+register(UnrealGlShim)
@@ -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 "
@@ -164,6 +169,14 @@ SETTINGS = [
     "fragment-density-map foveation when the driver offers it and expects the density map from the headset, which the "
     "Frame doesn't provide: image views and barriers for a missing image, then a crash in the Frame's Vulkan driver "
     "(e.g. Metro Awakening). Valve's own foveation layer isn't affected."),
+    ("ovrp_begin_gate", "int", 0, "Unity frame loop: wait for skipped frames",
+     "Unity's built-in Oculus frame loop (frame.unity_oculus_check): before each frame wait, wait up to 50 ms for the "
+     "last waited frame to begin and skip the wait if it doesn't. Fixes a freeze at the first scene switch (e.g. "
+     "Sniper Elite VR); in other games it can make loading screens stutter."),
+    ("ovrp_hold_physics", "int", 0, "Unity frame loop: keep display-time poses",
+     "Unity's built-in Oculus frame loop (frame.unity_oculus_check): don't pass Unity's physics-step pose update on, "
+     "so the hands use the frame's display-time poses. Fixes hands trailing the controllers in some games (e.g. Sniper "
+     "Elite VR); in others it makes the hands lag (e.g. BattleSisters)."),
    ("gl_hide_multiview", "int", 1, "GL shim: hide multiview",
     "GL shim only: hide GL_OVR_multiview so all passes use single-view shaders. For GLES games whose multiview "
     "shaders fail on single-view render targets (e.g. Path of the Warrior)."),
@@ -171,7 +184,8 @@ SETTINGS = [


 # settings that need a new build, not only new settings files: the Vulkan shim learned vk_shader_fix in 0.6.4 and
-# vk_query_slots and vk_spec_fixes in 0.10.0
+# vk_query_slots and vk_spec_fixes in 0.10.0. haptic_fix stays at 2 although the shim also converts PCM vibrations
+# since 0.12.1: no game is known to need that, and a bump would mark every OVRPlugin game's build outdated
 REVISIONS = {"vk_shader_fix": 2, "vk_query_slots": 3, "vk_spec_fixes": 2, "haptic_fix": 2, "pose_consistency": 2}

 # How the "Game settings" dialog shows each setting to non-technical users: group, level (common settings are always
@@ -276,7 +290,8 @@ 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",
+        "ovrp_begin_gate", "ovrp_hold_physics")},
 }


@@ -335,6 +350,8 @@ class AdapterSetting(Patch):
            "swapchain_fix": ap.is_gles,
            "gl_hide_multiview": lambda a: a.direct_vrapi and ap.is_gles(a),
            "gl_hide_msrtt": ap.is_gles,
+            "ovrp_begin_gate": lambda a: a.engine == "Unity" and "libOVRPlugin.so" in a.libs,
+            "ovrp_hold_physics": lambda a: a.engine == "Unity" and "libOVRPlugin.so" in a.libs,
            "vk_shader_fix": lambda a: a.engine == "Unreal",  # read by the Vulkan shim, which only Unreal games get
            "vk_hide_fdm": lambda a: a.engine == "Unreal",  # Unreal's Vulkan isn't always detected (Metro Awakening)
            "vk_query_slots": lambda a: a.engine == "Unreal" and ap.is_vulkan(a),
@@ -451,6 +468,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 +517,5 @@ register(DeviceFiles)
 register(LeptonEnv)
 register(HideNavBar)
 register(TextInputWindow)
+register(DisplayMode)
 register(Foveation)
@@ -44,6 +44,12 @@ SUMMARIES = {
                       "Frame's graphics driver accepts.",
    "frame.unity_gl_shim": "Stops a grey or frozen screen in Unity games that turn on anti-aliasing while running "
                           "(e.g. The Room VR).",
+    "frame.unreal_gl_shim": "Stops a crash a few seconds after start in Unreal games whose anti-aliasing the Frame's "
+                            "graphics driver can't handle (e.g. Star Wars Pinball VR).",
+    "frame.unreal_ovrp_entrypoints": "Lets older Unreal games start VR although the converted VR plugin lacks a few "
+                                     "functions they look for (e.g. Star Wars Pinball VR).",
+    "frame.pac_hints": "Stops a crash on the Frame's CPU in games whose code has unpaired security checks the Quest "
+                       "ignores (e.g. Star Wars Pinball VR's first network connection).",
    "frame.unity_no_overlay_copy": "Stops a grey screen crash in some Unity games by skipping their overlay "
                                   "layers (e.g. The Room VR's screen fades).",
    "frame.nodebug": "Stops strict debugging checks that make some games quit.",
@@ -54,6 +60,8 @@ SUMMARIES = {
                       "waiting for a download that never comes.",
    "frame.ovr_trace": "For troubleshooting: records the game's requests to Meta's platform services and which ones "
                       "never get an answer.",
+    "frame.slz_vulkan_hooks": "Lets Unity start the graphics itself instead of Stress Level Zero's plugin, "
+                              "which crashes on the Frame (e.g. BONELAB 1.2974).",
    "frame.unity_user_presence": "Counts the headset as worn, so games that only move the player while it's worn "
                                 "get head tracking and controls (e.g. BONELAB).",
    "frame.unity_no_msaa": "Turns off a smoothing setting that crashes some older Unity games on the Frame.",
@@ -82,6 +90,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
@@ -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
@@ -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)
@@ -323,21 +353,114 @@ def add_linux_app(path: Path | str, reporter: Reporter | None = None, exe: str |
        from .artwork import fetch

        fetch.artwork_dir(package)
-        from .artwork import steam
+        from .artwork import sources, steam

+        icon = None if info["files"] else linux.find_icon(root)  # a lone AppImage's icon comes from the Frame
+        if icon:
+            sources.apply_app_icon(package, icon.read_bytes())
        steam.ensure_cover(package)  # placeholder art (name on a colour) until the user picks some
    except Exception:  # noqa: BLE001 - artwork is optional
        pass
    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:
@@ -352,12 +475,13 @@ def add_game(src: SourceGame, reporter: Reporter | None = None) -> dict:
    if reporter:
        reporter.log(f"analyzing {src.apk.name}")
    a = analyze(src.apk, data_bytes=src.data_bytes())
-    a.extra["lang_packs"] = langpacks.find_tags(src.data_dir)
-    a.extra["asset_files"] = langpacks.find_content_files(src.data_dir)
+    a.extra["lang_packs"] = langpacks.find_tags(_data_folder(src))
+    a.extra["asset_files"] = langpacks.find_content_files(_data_folder(src))
    recipe = engine.suggest(a)
    return library.upsert_game(
        a.package, title=recipe.title or a.label, name=src.name, apk=str(src.apk),
-        data_dir=str(src.data_dir) if src.data_dir else None, data_bytes=src.data_bytes(), origin=str(src.origin),
+        data_dir=str(src.data_dir) if src.data_dir else None, data_files=src.data_files, data_bytes=src.data_bytes(),
+        origin=str(src.origin),
        analysis=a.to_dict(), recipe=library.recipe_to_dict(recipe), suggested=library.recipe_to_dict(recipe),
        status=recipe.status,
    )
@@ -367,25 +491,110 @@ def reanalyze(package: str, reporter: Reporter | None = None) -> dict:
    """Read a Quest/Android game's APK again (e.g. after FramePort learned to detect something new). The suggestion is
    refreshed; the recipe too unless the user changed it (then their choices stay)."""
    entry = library.game(package)
-    if entry is None or is_rift(entry):
+    if entry is None or is_rift(entry) or is_linux(entry):
        raise ValueError("only Quest/Android games can be analyzed again")
+    return _store_analysis(package, _analyze_entry(entry, reporter))
+
+
+def _analyze_entry(entry: dict, reporter: Reporter | None = None):
    src = source_of(entry)
    if reporter:
        reporter.log(f"analyzing {src.apk.name}")
    a = analyze(src.apk, data_bytes=src.data_bytes())
-    a.extra["lang_packs"] = langpacks.find_tags(src.data_dir)
-    a.extra["asset_files"] = langpacks.find_content_files(src.data_dir)
+    a.extra["lang_packs"] = langpacks.find_tags(_data_folder(src))
+    a.extra["asset_files"] = langpacks.find_content_files(_data_folder(src))
+    return a
+
+
+def _store_analysis(package: str, a) -> dict:
+    """Replace only the entry's analysis and suggestion; the recipe follows unless it is the user's own (tags, art,
+    title, builds and installs are untouched)."""
    suggested = engine.suggest(a)
-    keep = library.recipe_from_dict(entry["recipe"]).source == "user"
-    return library.upsert_game(package, analysis=a.to_dict(), suggested=library.recipe_to_dict(suggested),
-                               **({} if keep else {"recipe": library.recipe_to_dict(suggested),
-                                                   "status": suggested.status}))
+
+    def change(g: dict) -> None:
+        g["analysis"] = a.to_dict()
+        g["suggested"] = library.recipe_to_dict(suggested)
+        g.pop("analysis_failed", None)
+        # checked under the library lock: the user may have saved a recipe while the APK was read
+        if library.recipe_from_dict(g.get("recipe") or {"package": package}).source != "user":
+            g["recipe"] = library.recipe_to_dict(suggested)
+            g["status"] = suggested.status
+    return library.update_game(package, change)
+
+
+def analysis_outdated(entry: dict) -> bool:
+    """A Quest/Android entry analysed by an older FramePort (fields newer patches depend on are missing) whose APK is
+    still there, and whose re-analysis didn't already fail for this analysis version. Rift/Linux entries: no."""
+    from .analysis.detect import ANALYSIS_VERSION
+
+    a = entry.get("analysis")
+    if not isinstance(a, dict) or not entry.get("apk") or is_rift(entry) or is_linux(entry):
+        return False
+    if str(a.get("package") or "").startswith("rift."):
+        return False
+    if ((a.get("extra") or {}).get("analysis_version") or 0) >= ANALYSIS_VERSION:
+        return False
+    if entry.get("analysis_failed") == ANALYSIS_VERSION:
+        return False
+    try:
+        return Path(entry["apk"]).is_file()  # on a drive that isn't connected now: tried again at a later start
+    except OSError:
+        return False
+
+
+def outdated_analyses() -> list[str]:
+    return [g["package"] for g in library.games() if analysis_outdated(g)]
+
+
+def refresh_analyses(packages: list[str] | None = None, reporter: Reporter | None = None) -> int:
+    """Analyse again the entries an older FramePort analysed (see detect.ANALYSIS_VERSION): runs in the background at
+    start (GUI) and before a build (CLI and GUI). Only the APK analysis (no OVRPort, no Cpp2IL). An APK that can't be
+    read leaves the entry as it was and is marked, so it isn't read again at every start. Returns how many changed."""
+    from .analysis.detect import ANALYSIS_VERSION
+
+    todo = outdated_analyses() if packages is None else \
+        [p for p in packages if analysis_outdated(library.game(p) or {})]
+    done = 0
+    for i, pkg in enumerate(todo):
+        entry = library.game(pkg)
+        if entry is None or not analysis_outdated(entry):
+            continue
+        if reporter:
+            reporter.check_cancel()
+            reporter.progress(i / len(todo), entry.get("title") or pkg)
+        try:
+            a = _analyze_entry(entry, reporter)
+        except Exception as exc:  # noqa: BLE001 - unreadable APK: keep the old analysis, don't retry every start
+            if reporter:
+                reporter.log(f"{pkg}: couldn't analyze the APK again: {exc}")
+            library.update_game(pkg, lambda g: g.__setitem__("analysis_failed", ANALYSIS_VERSION))
+            continue
+        if a.package != pkg:  # a different APK at that path now: leave the entry alone
+            library.update_game(pkg, lambda g: g.__setitem__("analysis_failed", ANALYSIS_VERSION))
+            continue
+        _store_analysis(pkg, a)
+        done += 1
+    return done
+
+
+def _data_folder(src: SourceGame) -> Path | None:
+    """The data folder when all of it is the game's data (language packs and content files are looked for there);
+    None when only expansion files found by name are (that folder also holds other things, e.g. the APK)."""
+    return None if src.data_files is not None else src.data_dir
+
+
+def data_paths(entry: dict) -> list[Path]:
+    """A Quest game's data on this PC: its data folder, or only its expansion files when those were found by name."""
+    if not entry.get("data_dir"):
+        return []
+    d = Path(entry["data_dir"])
+    return [d / n for n in entry["data_files"]] if entry.get("data_files") is not None else [d]


 def source_of(entry: dict) -> SourceGame:
    return SourceGame(entry.get("name") or entry["package"], Path(entry["apk"]),
                      Path(entry["data_dir"]) if entry.get("data_dir") else None,
-                      Path(entry["origin"]) if entry.get("origin") else None)
+                      Path(entry["origin"]) if entry.get("origin") else None, data_files=entry.get("data_files"))


 def set_recipe(package: str, recipe: Recipe) -> None:
@@ -393,12 +602,7 @@ def set_recipe(package: str, recipe: Recipe) -> None:


 def reset_recipe(package: str) -> Recipe:
-    if is_rift(library.game(package) or {}):
-        entry = library.game(package)
-        a = library.analysis_from_dict(entry["analysis"])
-        recipe = engine.suggest(a)
-        set_recipe(package, recipe)
-        return recipe
+    """Back to the suggested recipe (catalog or heuristics) for the game's analysis (Quest and Rift alike)."""
    entry = library.game(package)
    recipe = engine.suggest(library.analysis_from_dict(entry["analysis"]))
    set_recipe(package, recipe)
@@ -507,6 +711,8 @@ def _build_lock(package: str) -> threading.Lock:


 def build_game(package: str, reporter: Reporter, outdir: Path | None = None) -> dict:
+    if analysis_outdated(library.game(package) or {}):  # analysed by an older FramePort: new fields first
+        refresh_analyses([package], reporter)
    entry = library.game(package)
    if is_linux(entry):  # nothing to convert: installed as it is
        return {"ok": True, "linux": True}
@@ -523,7 +729,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,9 +753,12 @@ 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)
+    result = target.install(package, title, apk, data_dir, recipe, reporter, apk_only,
+                            data_files=entry.get("data_files"))
    if add_to_library:
        target.add_to_library([package], reporter)
    _record_install(package, target.label, {"apk": str(apk), "result": result, "time": time.time()})
@@ -582,13 +792,14 @@ def local_game_files(package: str) -> list[Path]:
    elif is_linux(g):
        paths += linux_local_files(g)
    else:
-        paths += [Path(p) for p in (g.get("apk"), g.get("data_dir")) if p]
+        paths += [Path(g["apk"])] if g.get("apk") else []
+        paths += data_paths(g)
    b = g.get("build") or {}
    out = output_dir().resolve()
    paths += [Path(b[k]) for k in ("apk", "alt_apk") if b.get(k) and out in Path(b[k]).resolve().parents]
    others = [o for o in library.games() if o.get("package") != package]
    used = [Path(p).resolve() for o in others if not is_linux(o)
-            for p in (o.get("apk"), o.get("data_dir"), o.get("game_dir")) if p]
+            for p in (o.get("apk"), o.get("game_dir"), *data_paths(o)) if p]
    used += [p.resolve() for o in others if is_linux(o) for p in linux_local_files(o)]  # (lone AppImages: the file)

    def shared(p: Path) -> bool:  # the same path, a path inside it, or a folder around it belongs to another game
@@ -707,6 +918,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"
@@ -307,7 +307,7 @@ TOGGLED_DEVICE = ("device.text_input_window",)

 def entry_from_library(g: dict, status: str | None = None, notes: str | None = None,
                       verified: dict | None = None) -> CatalogEntry:
-    """A catalog recipe from a library entry (what "Save as known-good" and "Share working config" publish)."""
+    """A catalog recipe from a library entry (what "Save as known-good" and "Share working recipe" publish)."""
    import time

    from ..core import library
@@ -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
@@ -3,10 +3,17 @@
 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)
+  <folder>/x.apk + (main|patch).<versionCode>.<package>.obb anywhere nearby    found by file name (next to the APK,
+                                                                               <package>/apk/ + <package>/obb/, ...)
  a single .apk file
+(find_data has the details.)
 """
 from __future__ import annotations

+import contextvars
+import os
 import re
 import zipfile
 from pathlib import Path
@@ -22,13 +29,23 @@ def display_name(folder_name: str) -> str:
    return re.sub(r'[<>:"/\\|?*]', "_", TAG.sub("", folder_name).strip())


-def _package_of(apk: Path) -> str | None:
+def _apk_ids(apk: Path) -> tuple[str | None, int | None]:
+    """(package, versionCode) from the APK's manifest; None for what can't be read."""
    try:
        from pyaxmlparser import APK

-        return APK(str(apk)).package
+        a = APK(str(apk))
    except Exception:
-        return None
+        return None, None
+    try:
+        vc = int(a.version_code)
+    except (TypeError, ValueError):
+        vc = None
+    return a.package, vc
+
+
+def _package_of(apk: Path) -> str | None:
+    return _apk_ids(apk)[0]


 def _is_apk(path: Path) -> bool:
@@ -39,12 +56,185 @@ def _is_apk(path: Path) -> bool:
        return False


+OBB_FOLDERS = ("obb", "obbs")
+
+
+# folder listings, kept while scan() runs: every game of a collection searches its neighbours (slow on NTFS drives)
+_LISTINGS: contextvars.ContextVar[dict | None] = contextvars.ContextVar("quest_dump_listings", default=None)
+
+
+def _list(d: Path) -> list[tuple[Path, bool]]:
+    """(entry, is a folder) in d, sorted; [] when it can't be read."""
+    cache = _LISTINGS.get()
+    if cache is not None and d in cache:
+        return cache[d]
+    try:
+        with os.scandir(d) as it:
+            out = sorted((Path(e.path), e.is_dir()) for e in it)
+    except OSError:
+        out = []
+    if cache is not None:
+        cache[d] = out
+    return out
+
+
+def _subdirs(d: Path) -> list[Path]:
+    return [p for p, is_dir in _list(d) if is_dir and not p.name.startswith(("_", "."))]
+
+
+def _has_apks(d: Path) -> bool:
+    return any(p.suffix.lower() == ".apk" and not is_dir for p, is_dir in _list(d))
+
+
+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:
+    return any(p.suffix.lower() == ".obb" and not is_dir for p, is_dir in _list(d))
+
+
+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 _has_apks(sub)):
+            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
+
+
+# Android's expansion file names: main.<versionCode>.<package>.obb, patch.<versionCode>.<package>.obb
+OBB_NAME = re.compile(r"^(main|patch)\.(\d+)\.(.+)\.obb$", re.IGNORECASE)
+
+
+def _named_obbs(d: Path, pkg: str) -> list[tuple[str, int, Path]]:
+    """(kind, versionCode, file) of the package's expansion files directly in d."""
+    out = []
+    for f, is_dir in _list(d):
+        m = OBB_NAME.match(f.name)
+        if m and m.group(3).lower() == pkg.lower() and not is_dir:
+            out.append((m.group(1).lower(), int(m.group(2)), f))
+    return out
+
+
+def _obb_folders(apk_dir: Path, pkg: str, depth: int = 3) -> list[tuple[Path, list[tuple[str, int, Path]]]]:
+    """Folders holding the package's expansion files by name, nearest first: the APK's own folder, the folders below
+    it, its parent, then the parent's other folders (each up to `depth` levels). Folders with APKs of their own are
+    other games (e.g. another version of this one) and aren't searched."""
+    found: list[tuple[Path, list]] = []
+
+    def visit(d: Path) -> None:
+        obbs = _named_obbs(d, pkg)
+        if obbs:
+            found.append((d, obbs))
+
+    def below(d: Path, level: int, skip: Path | None = None) -> None:
+        for sub in _subdirs(d):
+            if sub == skip or _has_apks(sub):
+                continue
+            visit(sub)
+            if level > 1:
+                below(sub, level - 1)
+
+    visit(apk_dir)
+    below(apk_dir, depth)
+    parent = apk_dir.parent
+    if parent != apk_dir:
+        visit(parent)
+        below(parent, depth, skip=apk_dir)
+    return found
+
+
+def _pick_obbs(obbs: list[tuple[str, int, Path]], version_code: int | None) -> list[Path]:
+    """The expansion files for this APK: per kind (main, patch) the newest one not newer than the APK's versionCode
+    (expansion files keep the versionCode they were introduced with, so that's its own one when there is one); only
+    when there is none at all, the newest ones (another version of the game's files: better than nothing)."""
+    usable = [o for o in obbs if version_code is not None and o[1] <= version_code] or obbs
+    picked = []
+    for kind in ("main", "patch"):
+        same = sorted((vc, f) for k, vc, f in usable if k == kind)
+        if same:
+            picked.append(same[-1][1])
+    return picked
+
+
+def find_data(apk_dir: Path, pkg: str | None, version_code: int | None = None) -> tuple[Path | None, list[str] | None]:
+    """(data folder, files) for the APK in apk_dir. files is None when the whole folder is the game's data (the
+    layouts of _find_data_dir), else the names of the expansion files to send from it (found by file name, e.g.
+    lying next to the APK: the APK and anything else in that folder stay on the PC)."""
+    data = _find_data_dir(apk_dir, pkg)
+    if data is not None or not pkg:
+        return data, None
+    folders = _obb_folders(apk_dir, pkg)
+    if not folders:
+        return None, None
+    d, obbs = next((f for f in folders if any(vc == version_code for _, vc, _ in f[1])), folders[0])
+    files = _pick_obbs(obbs, version_code)
+    everything = {p.name for p, _ in _list(d)}
+    names = [f.name for f in files]
+    return d, (None if everything == set(names) else names)
+
+
+def find_data_dir(apk_dir: Path, pkg: str | None, version_code: int | None = None) -> Path | None:
+    return find_data(apk_dir, pkg, version_code)[0]
+
+
+# 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)
-        return SourceGame(display_name(path.stem), path, data, path.parent)
+        pkg, vc = _apk_ids(path)
+        data, files = find_data(path.parent, pkg, vc)
+        return SourceGame(display_name(path.stem), path, data, path.parent, data_files=files)
    if not path.is_dir():
        return None
    apks = sorted(p for p in path.glob("*.apk") if _is_apk(p))
@@ -52,13 +242,10 @@ def from_path(path: Path) -> SourceGame | None:
        return 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])
+    pkg, vc = _apk_ids(apk)
+    data, files = find_data(path, pkg, vc)
+    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], files)


 def _no_quest_games_below(d: Path) -> bool:
@@ -77,7 +264,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]:
@@ -111,5 +299,9 @@ def scan(root: Path, depth: int = 5) -> list[SourceGame]:
    if root.is_file():
        g = from_path(root)
        return [g] if g else []
-    walk(root, 0)
+    token = _LISTINGS.set({})
+    try:
+        walk(root, 0)
+    finally:
+        _LISTINGS.reset(token)
    return found
@@ -21,7 +21,7 @@ class Target(ABC):

    @abstractmethod
    def install(self, package: str, title: str, apk: Path, data_dir: Path | None, recipe: Recipe,
-                reporter: Reporter, apk_only: bool = False) -> dict: ...
+                reporter: Reporter, apk_only: bool = False, data_files: list[str] | None = None) -> dict: ...

    @abstractmethod
    def add_to_library(self, packages: list[str], reporter: Reporter) -> dict: ...
@@ -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:
@@ -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():
@@ -33,8 +39,10 @@ class FrameLeptonTarget(Target):
    def installed(self) -> list[dict]:
        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)
+    def install(self, package, title, apk: Path, data_dir, recipe: Recipe, reporter: Reporter, apk_only=False,
+                data_files=None):
+        plan = installer.InstallPlan(package, title, apk, data_dir, recipe, apk_only, dest=self.install_dest(),
+                                     data_files=data_files)
        return installer.install(self.connect().frame, plan, reporter)

    def add_to_library(self, packages, reporter):
@@ -60,13 +68,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)

@@ -141,7 +141,7 @@ class PcReviveTarget(Target):
        return out

    # ------------------------------------------------------------------ install
-    def install(self, package, title, apk, data_dir, recipe, reporter, apk_only=False):
+    def install(self, package, title, apk, data_dir, recipe, reporter, apk_only=False, data_files=None):
        raise NotImplementedError("Quest (APK) games install on the Steam Frame, not on the PC")

    def install_pcvr(self, package, title, game_dir, exe, recipe: Recipe, reporter: Reporter, **extra):
@@ -71,3 +71,23 @@ def patch(apk: Path, outdir: Path, name: str, patches: list[str], reporter: Repo
    if p.returncode or not target.exists():
        raise RuntimeError(f"OVRPort failed (exit {p.returncode}); see log")
    return target
+
+
+def runtime_lib(name: str, abi: str = "arm64-v8a") -> Path | None:
+    """A library of the newest OVRPort runtime in the workspace (what `patch --version=latest` ships, e.g.
+    libOVRPlugin.so), or None before OVRPort downloaded one. Newest = first in the workspace's installed.json (the
+    release tracker's order), else the most recently unpacked runtime folder."""
+    import json
+
+    root = user_data_dir() / "overport-workspace" / "libraries"
+    if not root.is_dir():
+        return None
+    order: list[str] = []
+    try:
+        releases = json.loads((root.parent / "installed.json").read_text()).get("releases") or []
+        order = [str(r.get("version")) for r in releases if isinstance(r, dict)]
+    except (OSError, ValueError, AttributeError):
+        pass
+    found = [d for d in root.iterdir() if (d / "lib" / abi / name).is_file()]
+    found.sort(key=lambda d: (order.index(d.name) if d.name in order else len(order), -d.stat().st_mtime))
+    return found[0] / "lib" / abi / name if found else None