Notes: the jni build override and re-tagging a failed release build

Build: override jni to 1.1.0 instead (jni_flutter 1.0.4 also generates bindings that require jni ^1.1.0; Flet's template pins 1.0.0)
Build: pin jni_flutter 1.0.4 (1.0.4+1, published today, requires jni ^1.1.0 but Flet pins jni 1.0.0; all flet build bundles failed)
2026-10-06 19:00:43 +02:00 · 2026-10-06 12:14:37 -04:00 · 2026-10-06 12:04:20 -04:00 · 2026-10-06 11:54:47 -04:00 · 2026-10-06 11:44:01 -04:00 · 2026-10-06 11:42:04 -04:00
140 changed files with 13017 additions and 340 deletions
@@ -5,6 +5,15 @@ on:
    tags: ["v*"]
  pull_request:
  workflow_dispatch:
+    inputs:
+      dev:
+        description: "Publish the bundles as the dev build (testers: Settings → Updates → Install the latest dev build)"
+        type: boolean
+        default: true
+      notes:
+        description: "What testers should try (shown before they install it)"
+        type: string
+        default: ""

 jobs:
  test:
@@ -50,6 +59,9 @@ jobs:
        if: runner.os == 'Linux'
        run: sudo apt-get update && sudo apt-get install -y ninja-build libgtk-3-dev
      - run: uv sync --extra dev
+      - name: Dev build version (next patch + .dev<run number>; not committed)
+        if: github.event_name == 'workflow_dispatch' && inputs.dev
+        run: uv run --no-project python scripts/dev_version.py ${{ github.run_number }}
      - id: flet
        run: uv run python scripts/package.py
        continue-on-error: ${{ runner.os == 'macOS' || runner.arch == 'ARM64' }}
@@ -148,3 +160,43 @@ jobs:
            echo; cat packaging/release-footer.md; } > "$notes"  # short: the update dialog shows these notes
          gh release delete "$tag" --yes 2>/dev/null || true
          gh release create "$tag" out/* packaging/FramePort-selfsigned.cer --title "FramePort ${tag}" --notes-file "$notes"
+
+  dev-release:
+    # "Run workflow" with dev ticked: replaces the rolling `dev` pre-release (never shown by the automatic update check;
+    # testers install it from Settings → Updates). Same assets + SHA256SUMS as a release.
+    if: github.event_name == 'workflow_dispatch' && inputs.dev
+    needs: bundle
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v10.2.0
+      - id: version
+        run: echo "version=$(uv run --no-project python scripts/dev_version.py ${{ github.run_number }})" >> "$GITHUB_OUTPUT"
+      - uses: actions/download-artifact@v8
+        with:
+          path: out
+          merge-multiple: true
+      - name: Wheel
+        run: uv build --wheel -o out && ls out
+      - name: Checksums
+        run: cd out && sha256sum * > SHA256SUMS.txt && cat SHA256SUMS.txt
+      - name: Publish the dev build
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.version.outputs.version }}
+          NOTES: ${{ inputs.notes }}
+        run: |
+          notes=$(mktemp)
+          last=$(git describe --tags --abbrev=0 --match 'v*' 2>/dev/null || true)
+          { echo "Dev build **${VERSION}** from commit ${GITHUB_SHA::7} ($(date -u +%Y-%m-%d)). For testing fixes before"
+            echo "the next release; you get that release as a normal update."; echo
+            if [ -n "$NOTES" ]; then echo "## Please test"; echo; echo "$NOTES"; echo; fi
+            if [ -n "$last" ]; then echo "## Changes since ${last}"; echo
+              git log --no-merges --format='- %s' "${last}..HEAD" | cut -c1-160 | head -40; fi; } > "$notes"
+          gh release delete dev --yes --cleanup-tag 2>/dev/null || true
+          gh release create dev out/* packaging/FramePort-selfsigned.cer --prerelease --target "$GITHUB_SHA" \
+            --title "FramePort dev build ${VERSION}" --notes-file "$notes"
@@ -19,3 +19,4 @@ CLAUDE.local.md
 # outputs of `frameport report` / `parity` / ruff
 REPORT.md
 .ruff_cache/
+.claude/worktrees/
@@ -21,7 +21,27 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    the "Send files" dialog, game menu → "Add videos & files…" = `go("files", pkg)`; multi-select bar (download/
    delete); drag-and-drop from the OS via the `flet-dropzone` extension (Apache-2.0, Flutter `desktop_drop`), which
    only a `flet build` bundle contains: `files.dropzone_available()` keeps it out of source runs and the PyInstaller
-    fallback, which would show an unknown control); settings; welcome; activity panel).
+    fallback, which would show an unknown control); screenshots (Steam screenshots on the Frame, `install/screenshots.py`
+    + agent v46 `list_screenshots`/`delete_screenshots`: the Frame files every headset shot under SteamVR 250820, so
+    launch.sh logs `start/end <unix>` to `<anchor>/plays.log` (upgrade_launchers adds it; Proton launchers exec → start
+    only) and shots are matched by time; thumbnails cached in `<data>/screenshots-cache/<frame>/`, shown by asset URL;
+    delete leaves screenshots.vdf alone (Steam rewrites it at exit); game menu → "Screenshots" = `go("screenshots",
+    pkg)`); live view (`views/live.py` + `install/livestream.py`: the Frame's built-in SteamVR "headset view" webcam
+    (`steamvr-v4l2cam.service` → v4l2loopback "SteamVR" /dev/video99, see docs/FRAME_RUNTIME.md) + the default
+    output's pulse monitor (sound) → ffmpeg/x264 + AAC (qualities scale down only; "full" = SteamVR's size) →
+    fragmented MP4 on an SSH exec channel's stdout (the script stops ffmpeg on stdin EOF) → relay on 127.0.0.1 (keeps
+    init + fragments since the last keyframe of the *video* track for late viewers) → player page
+    `install/live_player.py` (MSE; starts muted as browsers require, "Sound on" button; 0.3 s cushion, catches up at
+    1.1x, seeks only when >2 s behind: seeking to the very edge starved it) opened
+    in the user's default browser: Flet can't show video outside `flet build` bundles; the stream outlives the tab and
+    stops on disconnect/window close); settings; welcome; activity panel). Files, Screenshots and the Library share right-click menus
+    (one `ft.ContextMenu` per view, filled on right-click; on one of several selected items they act on the whole
+    selection, `C.menu_targets`) and click-and-drag multi-select (`C.DragSelect`: pan start/end on the area + item
+    hover events, which Flutter also sends with the button held; Flet can't report item positions, so no rubber band).
+    Selection bars sit below the list: above it, their appearing shifted the items mid-drag. Async handlers (they
+    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.
    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
@@ -76,6 +96,11 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
    auto-start SteamVR on Play (`winhost.start_steamvr`); the Frame launcher always uses `/openxr`. UI (`game.py`
    where()) states per-game where it runs; installing an Oculus game on the Frame shows a warning. Migration
    `rift_frame_native` re-analyzes + re-derives existing entries.
+  - Own artwork (0.8.0): game menu → "Use your own artwork…" (also from the Find artwork dialog) =
+    `views/art_dialog.show_custom_art_dialog`: one slot per kind (portrait/landscape/hero/logo/icon), FilePicker →
+    `sources.apply_custom` (Pillow check, ≥64 px, ≤40 MB, scaled to ≤3840 px, PNG if alpha/logo/icon else JPEG,
+    replaces only that kind + its thumbnails, drops the generated cover/banner, writes `.picked` = "custom") /
+    `remove_custom`; Steam shapes are still composed from what exists (`steam.py` PREFER).
  - Art for Rift games: `artwork/sources.py` — Quest version package (OculusDB packageName, exact name or +
    "Unplugged"-type suffix, never sequels) → Meta art; OculusDB square cover; Steam (exact names only); exe icon.
  - Store details (`artwork/details.py`, entry `details`): OculusDB (description, genres, publisher, website; by Quest
@@ -86,6 +111,11 @@ 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)…" /
+    "…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.
  - 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
@@ -147,7 +177,7 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
 - `agent/frameport_agent.py` — runs **on the Frame** (python3 stdlib only), JSON over SSH. Owns the install layout,
  launch.sh template, Steam shortcuts (binary VDF), launch tests. Bump `AGENT_VERSION` when changing it.
 - `bootstrap/bootstrap.sh` — one-time Frame setup served by the pairing server (sshd, app key, avahi service, Lepton).
- `catalog/games/<package>.yaml` — 38 recipes (34 verified 2026-09-28; Deadpool VR, 4XVR, NEX Player and AC Nexus's
+- `catalog/games/<package>.yaml` (installed apps also fetch these from GitHub `main`, see "Catalog updates") — 38 recipes (34 verified 2026-09-28; Deadpool VR, 4XVR, NEX Player and AC Nexus's
  90 Hz default confirmed later by the owner); `catalog/triage.yaml` — log signatures → fixes.
 - `native/` — sources of the prebuilt binaries in `artifacts/` (adapter, VrApi bridge patches, GL shim, stubs).
  `native/build.py` rebuilds them with NDK r27c (downloaded on demand into `native/.cache`, git-ignored; uses
@@ -383,7 +413,7 @@ GPU. Learned in the headset: quads can't be a background (the Frame draws quad l
 whatever the order: hid 4XVR's balcony/controllers), and the Frame doesn't reproject a projection layer from its own
 pose (images drawn only after head turns, or ahead from xrWaitFrame and sometimes late, wobbled);
 `equirect_flip/face/res/fps/stereo`), `stable_local`, `focus_hold` (only after 3 s FOCUSED, dips <600 ms),
-`aim_pitch/aim_yaw/aim_forward`, `refresh_rate`, `layer_debug` (diagnostics). 4XVR re-creates LOCAL spaces every 2–4 s
+`aim_pitch/aim_yaw/aim_forward`, `refresh_rate`, `layer_debug` (diagnostics); focus_hold is default-on since 2026-10-05. 4XVR re-creates LOCAL spaces every 2–4 s
 (menu recentring suspect); its theatres are baked 7680×3840 equirect2 images (`assets/100.png` …). Test 360° videos
 (NASA, public domain) are in the Frame's ~/Videos; copies in `~/Downloads/frameport-360`. 4XVR's "Internal Storage"
 lists its own `/sdcard/4XPlayer`, not Movies: agent v25 `link_media` hard-links sent files into an app's own top-level
@@ -477,9 +507,93 @@ game runs (agent v37). New default fixes in FramePort's code reach games already
 `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
 (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
+swapchain is returned, the game gets a Surface from a SurfaceTexture on a worker thread (own EGL context, JavaVM from
+XrInstanceCreateInfoAndroidKHR), frames are read back (glReadPixels) and uploaded in xrEndFrame (Vulkan: own command
+buffer + fence per panel, never waits; GLES: glTexSubImage2D). I Am Monkey's intro works (owner-confirmed). SUPERHOT
+(Quest) quit at start: its cloud save folder was mode 1700 and Lepton's app writes through the folder's group →
+launch.sh `fix_perms` adds u+rwx,g+rwx (agent v41). Lucky's Tale: Unity's Loading.PreloadManager thread grows the
+native heap ~1 GB/s until the OOM killer (Frame freezes); no fix. `perf` works as steamos (paranoid 2; ptrace_scope 1
+blocks gdb/eu-stack/debuggerd) — see PLAYBOOK "Debugging techniques". QuestCraft downloads its JRE at first run into
+`files/runtimes/JRE` (Pojlib Installer); on the Frame it was missing (unpacked by hand, unverified). WiiCompiled: its launcher shows
+(lepton-show-flatscreen) but imports .wcgame files through Android's document picker (OPEN_DOCUMENT), which Lepton
+lacks (ActivityNotFoundException) → imported by hand: libmain.so + game.json → internal files/game/<profile>,
+DATA/ → external files/WiiCompiledOpenXRVR/DATA, MOD/ → .../RetroRewind6 (decompiled with jadx). Lepton has no
+picker at all: a FramePort fix would be an injected picker activity. Generated cover/banner art used to suppress the
+Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
+**Steam library failures (GitHub #21/#30):** on some Frames Steam never loads FramePort's shortcuts.vdf entries (same SteamOS build and arm64 beta client as the dev Frame; IDs correct; file written before Steam starts): Play → console_log `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` (= "Game configuration unavailable", Steam treats the id as a store app). Cause unknown; agent v42/43 diagnostics: `launch` returns `steam` (started / error + code / silent from console_log), `collect_diag` adds `steam_library` (real Steam dir, beta, Steam start vs vdf write time, entries per account, devkit games) + `steam-console.txt` (incl. Steam's `logs/shortcuts.previous.txt` if present; steamclient.so has "LoadShortcuts: rejecting attempt to load shortcuts: invalid account ID"). **Fallback (agent v43):** when Play gets AppError_9 the agent registers the game through Steam's devkit interface (what Valve's Devkit Management Tool does, MIT: `devkit-1 steam://devkit-1/<~/.steam/steam.token>/create-shortcut?response=<file>&gameid=<id>&directory=~/devkit-game` written to ~/.steam/steam.pipe; answer file / `.error`; `~/devkit-game/<id>/launch.sh` = link to the game's launch.sh, `<id>-argv.json` ["launch.sh"] (relative to the folder), `<id>-settings.json` {steam_play 0, compat_tool ""}). Steam adds it live (no restart), picks its own appid (read back from shortcuts.vdf by DevkitGameID), shows it as a normal non-Steam game named "Devkit Game: <id>" (OpenVR 0, but VR works: owner-verified 2026-10-04), art copied to grid/<appid>*. Ids: letter first, then letters/digits/_ only (spaces, '-', leading digit → "missing/invalid arguments"). Later Plays use the devkit entry; uninstall (`devkit_unregister`, `delete-shortcut` live) and purge remove it. Verified on the dev Frame: register/launch/unregister; the AppError_9 trigger itself only in unit tests. GitHub #42 (two Steam accounts, neither MostRecent): Steam rewrote the active account's shortcuts.vdf without FramePort's entries right after starting, and added the devkit entry live without saving it, so `devkit_appid` (vdf only) failed ("Steam added the devkit entry but didn't save it"); agent v55 `devkit_appid_from_log` reads Steam's `sanitize shortcut app id "~/devkit-game/<id>/launch.sh": replacing 0 with N` console line. GitHub #41 (one account): same Steam behaviour, and every install restarts Steam, which forgets the never-saved devkit entry. Agent v56: the log fallback reads only the current session's console_log.txt; Play re-registers a devkit entry that gets AppError_9; art updates also write the devkit entry's grid art (`copy_grid_art`). Open: why some Frames' Steam never loads or saves shortcuts.vdf (single account too).
+**Exit game (GitHub #36, 2026-10-04):** `Apps.TerminateApp` (what Exit game calls; reachable for tests through Steam's CEF devtools on 127.0.0.1:8080, SharedJSContext, `Runtime.evaluate` — a stdlib websocket client is enough) closed both a normal shortcut and a devkit entry on the dev Frame within 1-3 s. SIGTERM to Steam's `reaper` alone left launch.sh + Lepton (setsid) + the container running (an earlier headset launch ran on for 87 min); SIGTERM to launch.sh cleans up in ~4 s. Agent v44: launch.sh's 2 s loop ends the game when its parent (the reaper) is gone; `upgrade_launchers` (from ensure_host_fixes) adds that to existing launchers in place. Which in-headset exit path fails is still unknown. Screenshots on the Frame: all under SteamVR's appid 250820 (`760/remote/250820/screenshots`, screenshots.vdf has creation time, no game).
+**SteamVR dashboard at game start (2026-10-04):** the dashboard (Resume game / controller / VR options) was open whenever a FramePort game started (also over Lepton's 2D launcher). Steam's UI exposes `SteamClient.OpenVR.VROverlay.{IsDashboardVisible,HideDashboard,ShowDashboard}` (CEF devtools, `steam_js` in the agent). Agent v44: launch.sh starts `_dashboard_worker` (waits for FrameBridge's first `pacing:` line in launch.log, then hides a visible dashboard for 25 s, at most 3 times; log `<base>/dashboard.log`; opt out with env FRAMEPORT_KEEP_DASHBOARD=1). Verified on the dev Frame (dashboard shown → 4XVR launched via Steam → hidden ~5 s after the first frames); not yet seen in the headset. **Headset (ITR2, 2026-10-05): too late** — Steam shows its frame menu (`valve.steam.gamepadui.frame.menu`, vrwebhelper_systemui.txt `[PooledPopups] Showing`) ~0.3 s after the game's first submitted frame (FrameBridge `new layer:`), but the first `pacing:` summary comes ~8 s later; the owner had pressed Resume (`[HideDashboard] return_to_game`) before the worker looked. Agent v52: watches from the first `new layer:` line (incremental log reads, 0.5 s polls, 30 s window). Agent v53: stops for good once the player opens the dashboard with the controller (`toggle_dashboard_action` in vrwebhelper_systemui.txt since the worker started): v52 closed it 60 ms after each press, and the game, paused for it, stayed paused.
+**Space warp / ITR2 (2026-10-04):** Into The Radius 2 (UE5, `libUnreal.so` + OVRPlugin, Vulkan) uses Application SpaceWarp (extra swapchains `376x376 format=97` motion vectors + `format=129` depth); #35 reports flickering textures. OVRPort's `patch_disable_space_warp` has no effect on UE5, and hiding XR_FB_space_warp in FrameBridge's enumerate doesn't reach the game either: **OVRPort's dispatcher offers/enables XR_FB_space_warp itself**. FrameBridge `hide_space_warp` (per game, off) hides it and strips `XrCompositionLayerSpaceWarpInfoFB` (1000171000) from the projection views (log `hide_space_warp: removed space warp info`); the game still renders its MV swapchains. Test build installed on the dev Frame; flicker not yet checked in a headset. Heuristic: UE5 + OVRPlugin shows it as an option (off). `equirect_emul` is suggested for Unreal games whose graphics API isn't detected ("GLES or unknown"); on Vulkan it switches itself off (Myst/Riven/ITR2): harmless, but Unreal Vulkan detection is a known gap.
+**PR #34 (merged 2026-10-04, Lucas-Mathieu):** `native/adapter/audio_metadata.h` patches Meta XR Audio Wwise (only build ID e1619e7f…, Batman: Arkham Shadow 1.4.1) so queued audio metadata isn't freed while the current audio frame references it (smoke-bomb crash). Verified headless: installs ("metadata reclamation follows …"), 72 fps; we added a once-per-second scan limit. Outside PRs: review source, rebuild `artifacts/` ourselves, merge locally (contributor's commit kept), push main.
+**Heuristics eval (2026-10-04):** `scripts/eval_heuristics.py "<VR CyberDeck Portable>"` → 19/44 recipes exact, 322/352 fields (most diffs: `frame.unity_text_input` suggested where older catalog recipes lack it; the rest are runtime-only findings: use_alt, vk_shader_fix, focus_hold, sync_guard, multipass). `PATCHED/` copies aren't scored (already converted).
+**Power (0.9, agent v47):** sidebar bar below the Frame card: Sleep / Restart / Shut down, each confirmed (`app.frame_power`, a running game asks again). logind answers CanSuspend/CanReboot/CanPowerOff = "challenge" for an SSH session but "yes" inside a user unit, so agent `power` runs `systemctl suspend|reboot|poweroff` from a transient `systemd-run --user --on-active=3` timer (the command answers first). Restart verified on the device (back in ~84 s, new boot id).
+**Proton default (agent v51, owner's choice 2026-10-05):** the newest **stable** ARM64 Proton is the default for PC VR games (`pick_proton`: asked-for name/alias, else newest installed stable, else any stable). Agent v49-50 defaulted to Experimental; the owner's headset A/B with Rick and Morty (Experimental 69 % reprojected frames, stable felt much smoother) reverted it. The game page's Customize shows `pcvr.proton_tool` as a dropdown (Stable (default) / Experimental = alias `proton-experimental`); `ensure_proton` installs a chosen one (it asks once more for the runtime Steam only names after Proton is installed; Experimental installed unattended on the device in 53 s). A PC VR launch test that fails on stable suggests Experimental (`pipeline.PROTON_TOOL`, `proton_alternative_worth_trying`, button "Try Proton Experimental and reinstall"). Remaining Rick and Morty stutter on head turns = the game rendering below the refresh rate (reprojection), not Proton.
+**USB cable link (verified 2026-10-05, cabled to the dev PC):** `usb0` is a USB **NCM** gadget (configfs g1: `ncm.usb0` + `ffs.adb`, Valve 28de:2460) set up by `usb-ncm-gadget@usb0.service`, which only runs with `ConditionPathExists=|/etc/systemd/system/adbd.service.d/steamos-devkit-enabled` = **Developer Mode only**. `usb-ncm-dnsmasq@usb0` serves DHCP with fixed `dhcp-host` entries: Frame 10.86.200.233, PC **10.86.200.234** (`frame/usb.py` FRAME_USB_IP/PC_USB_IP). Windows 11 binds its built-in "UsbNcm Host Device" (no driver); WSL mirrored sees eth 10.86.200.234. USB is high-speed (USB 2.0): upload 36.9 MB/s vs 11.3 MB/s home Wi-Fi. Frame→PC over the cable worked without a firewall change. `scripts/usb_autotest.py` (Windows via powershell.exe from WSL), `frameport frame usb-check`. Wizard "Set up with a USB cable" (`PairingServer(host=PC_USB_IP)`; the real bootstrap ran end to end over USB). Discovery dedupes by SSH host key and prefers USB > Frame hotspot > network (`discovery.dedupe`); a lost address is re-found by key (`Frame.relocate`, tested with a dead saved address).
+**Catalog updates without a release (2026-10-05):** apps fetch `catalog/games/*.yaml` from GitHub `main` (`recommend/catalog.refresh_remote`: one API call `git/trees/main?recursive=1` + raw.githubusercontent downloads of changed blobs, cached as `catalog-gh-<sha>.yaml`, every 6 h; GUI at start + Settings → Data "Check now"; CLI background thread + `frameport catalog-update`). `catalog.load()` only reads the cache. A remote entry is skipped (`unusable_reason`) when it names a patch/adapter key this app doesn't register, has a field `CatalogEntry` doesn't know, or `min_app` > this version: add `min_app` (or rely on new patch ids) when a config needs an unreleased FramePort. Remote beats bundled unless the bundled entry has a later updated/verified date; the user's own entries still win as before. Off: setting `catalog.auto_update`, env FRAMEPORT_NO_CATALOG_UPDATE; FRAMEPORT_CATALOG_URL still overrides the source. So: **pushing a catalog change to main reaches users within 6 h** (their recipes follow via catalog_rev → Update on Frame).
+**Start activity / QuestCraft / ITR2 pop-in (2026-10-05):** WiiCompiled's VR part (`QuestActivity`, SDL, process `:game`) stays behind Lepton's flat window when the launcher is shown (`device.text_input_window`). `frame.start_activity` (opt-in; analysis `extra.vr_activity` = the original APK's activity with Meta's VR category when it isn't the launcher) gives that activity's filter LAUNCHER and every other LAUNCHER becomes INFO, per element (`axml.set_start_activity`); Lepton's own `apk-info-extractor --print-activity-name` (on the Frame under Lepton/liblepton/apk_extractor) then answers QuestActivity. **OVRPort gives every MAIN activity LAUNCHER + VR categories**, so the VR activity must come from the original APK's analysis, not the converted manifest. Lepton has no activity override (`APP_ACTIVITY` is reset when app_metadata.sh is sourced). QuestCraft reaches Minecraft 1.21.5 (Fabric, Vivecraft, Sodium; LTW "Large Thin Wrapper" GL 3.0 on the Frame's Zink) and stops at `OpenGL error 1282` in `WindowFramebuffer` createTexture (Minecraft's crash report in `files/instances/1.21.5/crash-reports/`, Pojlib's `files/latestlog.txt`); the vrclient SIGSEGV / "pthread_mutex_lock called on a destroyed mutex" afterwards is only the shutdown (Unity's render thread still in vrclient while the instance is destroyed). ITR2 "models popping in and out" in game: Unreal reads user config from **internal** storage (`lepton-data/internal/<pkg>/files/UnrealGame/<Project>/<Project>/Saved/Config/Android/Engine.ini`, not external); `r.AllowOcclusionQueries=0` there broke its menus (removed again). Vulkan shim `vk_query_slots` (two slots per occlusion query) never saw ITR2 create an occlusion query pool, and the run with it crashed (Unreal RenderThread SIGSEGV, caught by sentry-native: no tombstone; the backtrace is in `cache/sentry/*/.sentry-native/*.run/*.envelope` with module offsets) - left off. Next suspect: Unreal 5 mobile HZB occlusion reading depth stored with Valve's FDM injection layer; test = launcher `VK_INSTANCE_LAYERS=''` (Lepton then loads neither VALVE_rpo nor VALVE_fdm_injection, Fossilize still). QuestCraft: LTW overrides glGetError and returns 0 with `LIBGL_NOERROR` set; Lepton passes `LEPTON_ENV_<NAME>` to the app as `<NAME>`, so catalog `lepton_env: {LEPTON_ENV_LIBGL_NOERROR: '1'}` gets Minecraft past the GL error 1282; then black picture (see the catalog entry). FrameBridge logs `new layer` once per layer type per process and projection views only for the first frames, so a second session in the same process (Vivecraft after Unity) needs `layer_debug=1`.
+**Vulkan validation / ITR2 solved (2026-10-05):** Khronos' validation layer can't come from Lepton (its layer dir is in the read-only guest image; the Linux copies on the Frame are glibc) and a global `debug.vulkan.layers` property (via the LEPTON_GFXRECON_FP_PROPS trick) kills the container at boot. Working recipe: bundle `libVkLayer_khronos_validation.so` (Khronos android-binaries release, arm64-v8a, stored uncompressed) into a test APK re-signed with the game's key (`apk.sign.sign`), install with `frameport install <pkg> --apk`, and set the Vulkan shim's `vk_validation=1` (it adds the layer at vkCreateInstance; findings under the logcat tag VALIDATION in launch.log, each message ID capped at 10). ITR2's flicker + windows behind models = Unreal's Qualcomm shader-resolve subpasses with a depth resolve of a single-sampled depth attachment (VUID-04908/-03179); `vk_spec_fixes=1` drops that resolve (its TRANSFER_DST half never applies to ITR2: the main depth is transient). Valve's VALVE_rpo layer removed ITR2's fog (catalog `lepton_env: VK_INSTANCE_LAYERS: VK_LAYER_VALVE_fdm_injection`). `r.ViewDistanceScale=2` in the internal Saved/Config/Android/Engine.ini only exists on the owner's Frame (the catalog can't write internal storage yet). Launch tests: Lepton prints a transient "is not a running context" on the first start after an APK change (agent v54 `not_started` waits 30 s for "Boot complete!").
+**GitHub #38/#39 (2026-10-05):** PowerWash Simulator stuck at "Waiting.." on a reporter's Frame = Unity sized the right-eye image rect past its swapchain (rect 268+1656 on a 1920-wide swapchain; the runtime's recommended size differs per Frame) and SteamVR rejected every frame (`xrEndFrame failed -25`, XR_ERROR_SWAPCHAIN_RECT_INVALID), after which the game stopped calling xrEndFrame. FrameBridge `rect_clamp` (default on; sizes noted in xrCreateSwapchain; clamped layers count as swapped) keeps projection/quad rects inside their swapchain; triage `swapchain-rect-invalid`. Not reproducible on the dev Frame with `scale` (Unity's eye sizing isn't just the recommended width); no regression there (72 fps). The adapter's revision was NOT bumped (that would mark every installed game outdated): affected users rebuild. The Room VR (#38) = Unity's render thread SIGSEGV in libgallium_dri.so ~30 ms after the game recreates its eye swapchain with samples=4 (FrameBridge retries samples=1); the game's own code turns MSAA on (not OVRManager); candidate fix: hide GL_EXT_multisampled_render_to_texture (GL shim) - needs the APK to test. The launch test passed both (render thread dead / no frames): triage gap.
+**Headset round 2026-10-05 (evening):** I Am Cat's judder = repeated xrLocateViews of one display time returning
+slightly different poses → FrameBridge `pose_consistency` (owner-verified, works). Lucky's Tale freeze on touching a
+save slot = OVRPort's OpenXR dispatcher converting XR_FB_haptic_amplitude_envelope with ns read as s (GitHub #9) →
+xrshim `haptic_fix` (owner-verified); its remaining short pauses were the wear sensor ("HMD off/on" 0.5-1 s in
+`logs/eyetracking.txt`, not vrserver.txt) → **`focus_hold` is on by default with 5 s** (owner's choice; C defaults
+too). The Room VR works (`unity_no_overlay_copy`). BattleSisters (Unity 2019.4 built-in VR, no libOculusXRPlugin.so)
+flooded "outside of frame bounds" ~2400/s and hung the GPU (kernel hangcheck, zink DEVICE LOST) → the ovrpshim frame
+wait now also applies to Unity 2019 without the Oculus XR Plugin (`UnityOculusCheck.legacy_loop`). Vader Immortal
+(UE4, stuck on the loading image after the intro, GitHub #49): VRP repacks carry a Frida gadget (`libfrda.so`,
+config `hijack_responses`), but OVRPort's `patch_clean_up_frida` removes its loadLibrary call, so it never runs on
+the Frame; `frame.ovr_trace` (opt-in, `native/ovrtrace`: 1138 exported ovr_* stubs → real loader functions, logcat
+tag `fp_ovrtrace`: calls, PopMessage answers, unanswered requests every 10 s) is the next diagnostic.
+**Unity built-in VR input (2026-10-05):** probe builds (`FRAMEPORT_INPUT_PROBE=1 frameport build …`; it logs
+trigger/grip crossings too) showed OVRPlugin returns the full Touch state for every controller mask (also Go masks);
+presses reach the games' OVRInput. Accounting+ (Il2CppDumper v6.7.46 reads its Unity 2017 metadata v24, run on Windows)
+passes stance selection (NewtonVR grip/trigger) but its motion warning waits for `Input.GetMouseButtonDown(0/1)`,
+which Lepton never delivers (no focused Android window) → ovrpshim registers its own
+`UnityEngine.Input::GetMouseButtonDown(System.Int32)` icall (il2cpp_add_internal_call, after Unity's: resolve first)
+that adds a click in the frame a Touch trigger or A/B/X/Y is newly pressed (`unity_oculus_check` revision 3).
+BattleSisters (Unity 2019 InputSystem/XR InputDevices via `VrHandInput`): libunity's Oculus module (OVRPlugin
+function table: a global pointer at 0x16b57c0 in this build, slots filled by name, e.g. +0x160 GetControllerState,
+0x168 State2, +0xe8 GetNodePresent) only reports controllers when `strncmp(deviceModel, "Oculus", 6) == 0` (next to
+the Go check `deviceModel == "Oculus Pacific"`); Lepton's model is "Valve Lepton" → Go/unknown → only Go masks polled,
+buttons dead. `unity_oculus_check` revision 4 (`oculus_model_checks`, Unity 2019 only) turns the 17 compares' length
+into 0 (`orr w2, wzr, #6` → `mov w2, #0` after the adrp/add of the "Oculus" literal; the string stays: it is also
+Unity's VR device name). Device result: libunity now polls `ovrp_GetControllerState(0x3)` (Touch); owner-confirmed
+2026-10-06: buttons work. Its first controller vibration then hit OVRPort's haptic-envelope bug (11 GB, OOM kill) →
+`haptic_fix` is now suggested for every game with libOVRPlugin.so (settings detect), BattleSisters works. Ruled out before: ProductName, GetNodePresent, the device-model string itself, exports.
+Accounting+ works (owner, 2026-10-06).
+**Vader Immortal (UE4, GitHub #49, 2026-10-06, headless):** stuck after the intro on an in-game image (the splash
+quad ends ~6 s in; then the game's own projection frames, 72 fps, balanced xrBeginFrame/xrEndFrame). Not the Platform
+SDK (`frame.ovr_trace`: only user + entitlement, both answered) and not the repack's Frida gadget (OVRPort's
+`patch_clean_up_frida` removes its loadLibrary). It **leaks ~430 GPU mappings (/dev/dri/renderD128) and ~20 MB a
+second** (6.5 GB + swap after 5 min, then 26 fps): page-fault stacks (perf -e page-faults, offsets resolved with the
+process maps + vrclient.so's own symbols; its text segment is at file offset + 0x4000) end in SteamVR's runtime:
+`xrBeginFrame → CSxrCompositorOpenVR::BeginFrame → SubmitExplicitTimingData → CVRCompositorSharedTextures::
+BeginGPUTimingCommandBuffer` and `xrEndFrame → CVRCompositorClient::SubmitWithArrayIndexAndTime`. Ruled out: the
+layer color scale/bias + image layout structs (FrameBridge `strip_color_bias` 1/2, diagnostic), Valve's Vulkan
+layers (VK_INSTANCE_LAYERS=""), array swapchains in general (Lucky's Tale/I Am Cat flat). Kernel tracepoints aren't
+allowed for steamos. FrameBridge: `layer_debug` logs xrDestroySwapchain and per-5 s xrBeginFrame/xrEndFrame counts;
+`frame_balance` (ends an open frame before the next begin) exists but Vader never leaves one open. Next (built,
+not yet run: the Frame slept): `layer_debug` also counts xrAcquire/Wait/ReleaseSwapchainImage per 5 s (hooked only
+with layer_debug, after the other conditional hooks) to see whether Vader skips a wait or release: it doesn't (361/361/361 per 5 s).
+FrameBridge `snapshot=N` (`snapshot_gl.c`, GLES): every N s the left-eye image the game submits is read back on its
+own context and saved as `files/fb_snap_0-7.ppm` (quarter size) — headless launches show a black headset view, this
+shows what the game draws. Vader: Lucasfilm logo (an OBB mp4: video works), then its loading card (portrait + segmented
+bar) that never advances; the async loader thread sleeps and OBB reads stop (~168 MB of a 2.7 GB pak).
+**Double launch (agent v57, 2026-10-06):** a second Play while Lepton still boots (~10 s with nothing to see) made
+the second Lepton stop the first one's container ("Waiting for steamlaunch-<appid> (PID …) to exit", exit 137
+"(starting)", "Clearing baked app data due to early exit") and both died (Vader, BattleSisters). launch.sh now takes
+`flock` on `<base>/.launch.lock` (fd 9, inherited by Lepton; the watchdog and dashboard helpers close it with
+`9>&-`); a second launch exits 0 and logs to `<base>/launch-dup.log`. `upgrade_launchers` adds it to existing
+launchers. Verified on the device (second launch during boot: ignored, the first kept running). Vader on its loading
+card ignores input too (owner pressed/held every button: presses reach the runtime, the card never changes).
 **Lepton storage (2026-09-30):** each app's /sdcard (= /storage/emulated/0 → `<base>/lepton-data/external`) has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (liblepton/mounting.sh, only if they exist at start); agent v24 `storage_targets` reads that mapping. Android's MediaProvider canonicalises paths to /home/steamos/... and rejects every file ("doesn't appear under [/system/media...]"), `sm list-volumes` is empty: the media index never works, apps must browse folders. Lepton installs with `adb install -g` (runtime permissions granted, MANAGE_EXTERNAL_STORAGE too). Files: `install/files.py`, `frameport frame send|storage`, GUI Files tab (formerly Frame → Send files).
 **SteamVR per-app settings (2026-09-30):** editing steamvr.vrsettings while SteamVR runs is lost; the web API (127.0.0.1:27062 /app/setsettings) needs `x-steamvr-secret`. `native/vrsettings` = `fp_vrsettings.exe` (freestanding, OpenVR `FnTable:IVRSettings_003` as a Utility app, loads SteamVR's bin/win64/openvr_api.dll) sets them live and SteamVR persists them: section `steam.app.<shortcut appid>`, keys `preferredRefreshRate` (float) and `motionSmoothingOverride` (0 global, 1 on, 2 off, 3 always). Steam Link (vrlink) lists the Frame's rates 72/80/90/96/108/120/144 in vrserver.txt and follows the per-app preference ("host preferred N Hz"; whether the key is honoured is unverified in-headset yet). Judder metric: vrcompositor.txt session summary dropped + "Timed out. N total" (Stormland: 0 dropped but 313 timeouts in 2 min); fpsVR (`%LOCALAPPDATA%\fpsVR\*.json`, 0.1 ms histograms) gives p99 CPU/GPU ms. `pcvr.steamvr_tuning` (default on, PC only) applies on Play: highest rate whose budget ≥ p99×1.05, at least one step down, smoothing on.

+**Language packs (merged from PR #20, 2026-10-04):** overport's `libovrplatformloader.so` is a dispatcher that `dlopen`s Meta's own loader (`libovrplatformloader_meta.so` / `_meta_q1.so`, also `libpxrplatformloader.so`) and keeps its own message queue; `ovr_LanguagePack_GetCurrent/SetCurrent` are 8-byte `return 0` stubs in it, `ovr_AssetFile_GetList` forwards to Meta's loader. `frame.langpacks` (opt-in, `native/langpack`) serves `<tag>.lang` files from the game's data; `elf.hide_exports` marks the loader's exports STB_LOCAL (bionic and glibc only match GLOBAL/WEAK; verified for glibc, bionic's `is_symbol_global_and_defined` is from memory). `libfp_langpack.so` is built here (`python native/build.py --only langpack`) and committed. Owner-verified 2026-10-04: Deadpool VR with only `en.lang` and the patch on plays English dialogue and runs normally (headless launch tests show 2-6 fps while it loads: not a regression sign). A dispatcher answer that arrives after we answered the timed-out GetList is dropped (one answer per request); games already in a library get `lang_packs` filled after an app update (`library._refresh_data_fields`). The library logs to logcat under the tag `fp_langpack` (dirs looked in, packs found, every language-pack call), so it shows up in the game's `launch.log`; an `ovr_AssetFile_GetList` the dispatcher leaves unanswered for 1.5 s is answered with our packs alone. Deadpool VR (Unreal) accepts a pack only when its `Metadata` equals the game's own version string (`ULanguagePacksSubsystem` compares it with `%s.%s.%s.%s.%s` built from the build info, e.g. `1.0.40.356975.Quest` = versionName; found by disassembling `libUE4.so`): the patch writes the APK's versionName into the library (`@FPMETA@` slot, `with_metadata`), `FRAMEPORT_LANGPACK_META` overrides it. Deadpool VR (2026-10-04, headset): German became selectable with that Metadata, but dialogue stayed silent (even English once reported as a pack) while the path was spelled `/sdcard/Android/obb/<pkg>/x.lang`; with the `/storage/emulated/0/Android/obb/<pkg>/x.lang` spelling (Unreal's own, now listed first in `scan_dirs`) German dialogue plays. `FRAMEPORT_LANGPACK_SKIP=<tags>` or a file `fp_langpack_skip` in the obb folder leaves packs out of the list (experiments).
+
 **Unresolved (as of 2026-09-28):** Arcsmith (right-eye distortion) and Time Stall (both eyes) — swap, tracking, Valve
 layers, depth, pacing ruled out. Sniper Elite VR (DEVICE LOST), Espire 1 (Mesa GL upload crash), HITMAN 3 (freedreno
 crash): use PC versions.
@@ -492,6 +606,11 @@ tests, builds Windows x64 / macOS arm64 / Linux x64 bundles, signs, attests and
 `FramePort-selfsigned.cer`; notes = "What's new" from the annotated tag message + the short `packaging/release-footer.md`; owner: keep release
 notes short — a few "What's new" bullets, nothing long after them).
 Installed apps find the release themselves (self-update), so the notes are what users see in the update dialog.
+- **Dev builds (for testers, no release):** Actions → build → Run workflow (main), "dev" ticked, optional "notes"
+  (what to test). The bundles get version `<next patch>.dev<run number>` (`scripts/dev_version.py`, not committed) and
+  replace the rolling `dev` pre-release (`dev-release` job; same assets + SHA256SUMS). Automatic update checks ignore
+  pre-releases; testers use Settings → Updates → "Install the latest dev build…" (`updates.check_dev`,
+  `Updater.install_dev`). `parse_version` sorts 0.9.0 < 0.9.1.devN < 0.9.1, so testers get the next release normally.
 - **Release checklist:** bump `src/frameport/_version.py` (the only version; `scripts/package.py` fails a tag build
  whose tag ≠ `v<_version>`), commit, `git tag -a vX.Y.Z -m "FramePort X.Y.Z" -m "<What's new, Markdown bullets>"`,
  push the commit and the tag. Never publish a release without its `SHA256SUMS.txt` (the updater refuses it) and keep
@@ -507,6 +626,11 @@ Installed apps find the release themselves (self-update), so the notes are what
  Windows console) plus PYTHONUTF8; macOS builds need `--python-version 3.12 --arch arm64` (cryptography has no wheels
  for flet's default Python / x86_64 cross-build), with a PyInstaller fallback step; `astral-sh/setup-uv` has no
  floating major tags after v7 → pin the exact version; force-moving a tag starts duplicate runs (cancel one).
+- `jni` (2026-10-06): jni_flutter 1.0.4/1.0.4+1 generate bindings that require jni ^1.1.0 while Flet's build template
+  pins jni 1.0.0 → every `flet build` bundle failed (`JniVersionCheck`, "generated bindings expect package:jni
+  ^1.1.0"). pyproject `[tool.flet.flutter.pubspec.dependency_overrides] jni = "1.1.0"` fixes it (pinning
+  jni_flutter 1.0.4 does not); drop it once Flet's template moves to jni 1.1. A failed tag build publishes nothing:
+  delete and re-push the tag on the fixed commit.
 - macOS runner (2026-10-02): `macos-latest` jobs went unassigned (cancelled after 15 min, no steps); `macos-15`'s Xcode
  16.4 fails a Flutter plugin (`NWPath has no member`); `macos-26` (Xcode 26) builds with `flet build`. The PyInstaller
  fallback (`package.py --pyinstaller`) passes `--yes` so a failed `flet build`'s folder doesn't stop it at a prompt.
@@ -22,12 +22,17 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V
  [What it changes](docs/FRAME_SETUP.md).
 - **Type on Frame:** use your computer's keyboard on the Frame: in VR apps, Android apps, Steam and the desktop.
  [More](#type-on-frame).
- **One click per game:** convert, patch, sign, upload, add to Steam with artwork, launch test.
+- **One click per game:** convert, patch, sign, upload, add to Steam with artwork, launch test. Artwork that can't be found automatically can be picked from the stores or replaced with your own images.
 - **Per-game recipes:** a tested catalog plus detection rules; every patch explained in plain words.
 - **FrameBridge:** FramePort's OpenXR adapter emulates what the Frame natively lacks (passthrough, room, controller models,
  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.
+- **Screenshots tab:** the screenshots you took in the headset, sorted by game (matched by play time) and day;
+  view them and download them to your computer.
+- **Live view tab:** watch what the headset shows, with sound, in a browser window on your computer.
 - **Self-updating** releases, redacted diagnostics, one-click problem reports and working-config sharing.

 ## Quick start
@@ -48,7 +53,8 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V
 3. **Add games → Scan a folder** with your game backups (APK + OBB, or PC VR game folders).
 4. Open a game → **Install on Frame**, then play it from the Frame's Steam library.

-Full guide, firewalls and troubleshooting: [docs/INSTALL.md](docs/INSTALL.md).
+Full guide, firewalls and troubleshooting: [docs/INSTALL.md](docs/INSTALL.md). Questions (e.g. how to lay out games
+with OBB files): [docs/FAQ.md](docs/FAQ.md).

 ## Type on Frame

@@ -63,6 +69,24 @@ Unity apps whose text fields close the moment you select them on the Frame (no s
 fix, so Steam's on-screen keyboard and Type on Frame work in them too.
 [Details](docs/INSTALL.md#typing-on-the-frame).

+## Screenshots
+
+Screenshots you take in the headset show up in FramePort's **Screenshots** tab, grouped by day and matched to the game
+you were playing. Open one full size, step through them, and download single shots, a selection or all of them to
+your computer.
+
+![Screenshots](docs/images/screenshots.png)
+
+![Screenshot viewer](docs/images/screenshot-viewer.png)
+
+## Live view
+
+The **Live view** tab streams what the headset shows, with its sound, to your computer: click **Start live view** and
+it opens in your default web browser (full screen with a double-click; click **Sound on** to hear it, as browsers start
+videos muted). Pick 360p to 1080p, or the headset view's full size. The picture comes from SteamVR's built-in headset
+view on the Frame and is encoded there while you watch (about one CPU core), so stop it when you're done. It's black
+while the headset sleeps.
+
 ## Compatibility

 If a game has already been tested with FramePort, it will automatically use the optimal game config. Otherwise, FramePort
@@ -1,11 +1,14 @@
-a5b03bb7ae5d953d7ded2bf117b0a19c57fae604f16f54310847f8e89593dde6  ./arm64-v8a/libfp_ovrp.so
-6d2b9f8cea2f2cf33b8ff30d29a2f3d9c4d55549260a867168a24e44abada021  ./arm64-v8a/libfp_vk.so
-8e00552d1ab90f82749db3caad4f773351fa8a28edcc5ea5cbd1b31c434ff32a  ./arm64-v8a/libframe_xrshim.so
-3dfcb0f2bec47857bcecc7261c58e076d872d4649718c40850f29e10c75477dd  ./arm64-v8a/libglshim.so
-f326df1a5bd600033661f53509f076b9b4ecbb6226e9050460b1d0cfdd70fb9d  ./arm64-v8a/libopenxr_loader_generic.so
+48a3ecad77ec0f3215b29070e994590eb9579e04d3c88a47f37f306f9aeb01d9  ./arm64-v8a/libfp_langpack.so
+4724254982fa854de2134b15b936cfbd6bd244d51e5d72d5b51b85c60ef67321  ./arm64-v8a/libfp_ovrp.so
+40defdaddcda53bd2649eb48076fae1622bfc2bfc88e9e03c94fc8b45af2a4f2  ./arm64-v8a/libfp_ovrtrace.so
+b5949e9e90e4c51e2733b9f6cd3c857a447552ac7291aec340407c27b034b600  ./arm64-v8a/libfp_vk.so
+383054f8b3b41dde76d062c71856cd3163655e50009c08454bc1793f393ead65  ./arm64-v8a/libfpg.so
+424d8e5cb15608ad627f9415df4c4665efd9358fed3447a5d3765279dc652f6b  ./arm64-v8a/libframe_xrshim.so
+3bfd1261688ed766c0adb9172f44dd7d41cc6459f26205ce3069f536a52e4ab9  ./arm64-v8a/libglshim.so
+a93928879af7b930f19c8c0a037a52711e194d2aacafea0d6d1de9809de76228  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
 32525cd0a9ee3d9993d8871cd6905bdcf22cde4f4ba28f5db6434ce7d6554758  ./arm64-v8a/libvrapi.so
-ddfd8b6c319bfd0ea8aada3b5e941981288ac10aa6443a79843a7b8c288f82fe  ./armeabi-v7a/libopenxr_loader_generic.so
+49513211094cdaaa02f81f0101fa497da38979499cc8533e3f4bd0b71f6a3f85  ./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
@@ -0,0 +1,21 @@
+package: com.Aldin.WotW
+title: 'Waltz of the Wizard: Extended Edition'
+status: works
+notes: From what I tested, it just works. My only complaint is that the haptics go pretty crazy. But I don't remember
+  what it was like when I played it in my Quest. So it could be fine. 100% playable.
+tested_version: 5.0.8.1578
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 522cfebf954e1cab6054798479b0b32c5ba9e38cca83dd98db2ac0f7e3c0802a
+  app: 0.9.1
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 48
+  issue: 44
+source_hint: WotW
@@ -0,0 +1,36 @@
+package: com.CMGames.IntoTheRadius2
+title: Into The Radius 2
+status: works
+notes: Plays well (owner-verified 2026-10-05). Space warp is off, the headset's brief focus losses are hidden
+  (focus_hold, up to 2.5 s), only Valve's foveation layer is loaded (its render-pass optimizer removed the fog) and
+  an invalid depth resolve in Unreal's render passes is dropped (vk_spec_fixes; it made models flicker and windows
+  show behind them). Needs FramePort 0.10.0 or newer. Loading a save can take over a minute.
+details: Unreal Engine 5 game that uses Meta's Application SpaceWarp (extra motion-vector and depth swapchains). OVRPort's
+  patch_disable_space_warp doesn't reach Unreal Engine 5, so FrameBridge's hide_space_warp hides XR_FB_space_warp and
+  removes the space warp info from the eye images. Working config shared in GitHub issue 35. In the headset
+  (2026-10-05) the Frame dropped focus for 0.4 s and 1.0 s within ten seconds and Unreal paused each time; loading a save
+  shows no frames for 40-80 s while the game's Sentry SDK (debug mode) logs its breadcrumbs. Valve's VALVE_rpo
+  (render-pass optimizer) Vulkan layer removes the game's fog (owner-verified 2026-10-05; with only VALVE_fdm_injection
+  loaded the fog renders), which also hid the distance culling; ruled out for the remaining pop-in - Vulkan occlusion
+  query slots, Valve's FDM layer. The cause, found with Khronos' validation layer (vk_validation) - Unreal's render
+  passes use Qualcomm's shader resolve (VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM) together with a depth resolve
+  of a single-sampled depth attachment (VUID-VkSubpassDescription2-flags-04908, -03179), harmless on Quest's driver,
+  wrong depth on the Frame's Mesa; the Vulkan shim's vk_spec_fixes drops that resolve.
+tested_version: 1.2.4
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+adapter:
+  equirect_emul: 1
+  hide_space_warp: 1
+  focus_hold: 1
+  focus_hold_ms: 2500
+  vk_spec_fixes: 1
+lepton_env:
+  VK_INSTANCE_LAYERS: VK_LAYER_VALVE_fdm_injection
+verified:
+  date: '2026-10-05'
+  issue: 35
+min_app: 0.10.0
+source_hint: Into The Radius 2
@@ -0,0 +1,25 @@
+package: com.FireproofStudios.TheRoomVR
+title: The Room VR
+status: works
+notes: Plays normally (it used to stay on a grey screen).
+details: Unity 2018.4 with built-in Oculus support. It started VR only with frame.unity_oculus_check, then Unity's
+  render thread crashed in the GL driver (Zink) when OVROverlay copied a 4x4 fade texture into its overlay layer;
+  frame.unity_no_overlay_copy skips that copy (the fade still works). frame.unity_runtime_msaa_off keeps the eye buffer
+  at one sample (also GitHub issue 38).
+tested_version: '1.02'
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_no_msaa
+- frame.unity_oculus_check
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_no_overlay_copy
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-05'
+  issue: 38
+updated: '2026-10-05'
+min_app: 0.11.0
+source_hint: The Room VR
@@ -0,0 +1,20 @@
+package: com.ILMxLAB.VaderImmortal.ep1
+title: 'Vader Immortal: Episode I'
+status: issues
+notes: Starts in VR and plays the intro, then stays on the loading card (Vader's portrait with a progress bar).
+details: Unreal Engine 4 (GLES). After the Lucasfilm intro the game shows its loading card and never loads the next
+  scene; it keeps rendering at 72 fps and ignores input. Ruled out so far - Meta platform requests (all answered),
+  video playback (the intro is a video and plays), the no-ForceQuit build, frame and swapchain handling. The Frame's
+  SteamVR runtime also leaks about 20 MB of memory a second while the game runs, which slows it down after a few
+  minutes. Next steps - find what the loading code waits for in the game's engine library (no symbols) and report
+  the runtime leak to Valve. GitHub issue 49.
+tested_version: 1.1.1+667256.cl.387770
+engine: Unreal
+xr: VrApi
+alt_overport:
+- patch_remove_unreal_force_quit
+verified:
+  date: '2026-10-06'
+  issue: 49
+updated: '2026-10-06'
+source_hint: Vader Immortal- Episode I
@@ -1,13 +1,14 @@
 package: com.NewFolderGames.IAmCat
 title: I Am Cat
-status: issues
-notes: The view vibrates slightly, even when holding still.
+status: works
+notes: Steady view with pose_consistency (the judder is gone).
 details: Unity 2022.3 with the Oculus XR Plugin falls back to GLES (Zink) on the Frame, where its single-pass
  (multiview) rendering drew the right eye wrong (GitHub issue 8); frame.unity_multipass renders each eye in its own
  pass (OculusSettings.GetStereoRenderingMode + its inlined read in OculusLoader.Initialize). Poses and frame times
  are consistent, but every frame reaches the runtime one display period late (two passes on Zink) and the game
-  clamps its physics step to 10 ms, so the view judders; scale 0.8 didn't change it. Possible next steps are fixing the
-  multiview path instead or the game's fixed timestep.
+  clamps its physics step to 10 ms. The judder came from the game locating its views about three times per frame and
+  getting slightly different poses each time; FrameBridge pose_consistency returns the same views for repeated
+  queries of one display time (proposed in GitHub issue 8). The grey right eye on the loading screen is still open.
 tested_version: 1.4.0.0
 engine: Unity
 xr: OpenXR
@@ -16,8 +17,11 @@ frame:
 - frame.unity_multipass
 device:
 - device.text_input_window
+adapter:
+  pose_consistency: 1
 verified:
-  date: '2026-10-03'
+  date: '2026-10-05'
  issue: 8
-updated: '2026-10-04'
+updated: '2026-10-05'
+min_app: 0.11.0
 source_hint: I Am Cat
@@ -0,0 +1,21 @@
+package: com.NewFolderGames.IAmMonkey
+title: I Am Monkey
+status: works
+notes: Its intro video plays through FrameBridge's video panels.
+details: The game plays its intro on a panel that an Android media player (ExoPlayer) draws into
+  (XR_KHR_android_surface_swapchain). The Frame's runtime lists that extension but refuses the call, so the panel had
+  no image and the game stayed black waiting for the video (GitHub issue 25). The adapter's surface_emul (on by
+  default) hands the player a real Android Surface and copies each video frame into an ordinary swapchain the panel
+  shows.
+tested_version: 1.0.5
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+  issue: 25
+updated: '2026-10-04'
+source_hint: I Am Monkey
@@ -0,0 +1,26 @@
+package: com.PixelToys.BattleSisters
+title: BattleSisters
+status: works
+notes: Starts in VR; controller buttons and vibration work.
+details: Unity 2019.4 with Unity's built-in Oculus support. frame.unity_oculus_check starts VR (Meta's system-app check),
+  adds the frame wait its legacy loop never makes (without it the GPU hung, black screen) and lets Unity's Oculus
+  input accept Lepton's device model (it only reported controllers on a device named "Oculus ...", so buttons were
+  dead). haptic_fix stops the first controller vibration from freezing the Frame (OVRPort's loader read its duration
+  in nanoseconds as seconds and the game ran out of memory).
+tested_version: 1.2.4
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_no_msaa
+- frame.unity_oculus_check
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-06'
+  issue: 48
+updated: '2026-10-06'
+min_app: 0.11.1
+source_hint: Battle Sister
@@ -0,0 +1,17 @@
+package: com.camouflaj.salmon
+title: Marvel's Iron Man VR
+status: works
+tested_version: 0.1.0-250068
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 41e0ab90f622afd50accb0b6e2553520d30a6cc82e5ab4cbb2341b48f7316a71
+  app: 0.9.1
+  overport_cli: 1.2.5
+  issue: 47
+source_hint: Marvel's Iron Man VR
@@ -1,17 +1,18 @@
 package: com.crowscrowscrows.AccountingPlus
 title: Accounting+
-status: issues
-notes: Starts in VR, but doesn't get past its "press any button" screen.
+status: works
+notes: Plays normally, including the "press any button" screen after choosing to sit or stand.
 details: Unity 2017.4 built-in Oculus support. frame.unity_oculus_check gets VR started (Meta's system-app check and
-  the frame wait its legacy loop never makes, libfp_ovrp.so), ~72 fps. Controller input reaches the game's OVRInput
-  cleanly (both Touch controllers connected, individual button bits, input focus 1 while focused) but the screen
-  doesn't continue; Cpp2IL can't read this Unity version to see what it waits for.
+  the frame wait its legacy loop never makes, libfp_ovrp.so), ~72 fps. The motion warning after the stance selection
+  waits for a mouse click (Input.GetMouseButtonDown), which a Quest delivers for the controller press and Lepton never
+  does; the same library now counts a newly pressed trigger or A/B/X/Y as that click.
 tested_version: 1.24.35
 engine: Unity
 xr: VrApi
 frame:
 - frame.unity_oculus_check
 verified:
-  date: '2026-10-04'
-updated: '2026-10-04'
+  date: '2026-10-06'
+updated: '2026-10-06'
+min_app: 0.11.0
 source_hint: Accounting+
@@ -0,0 +1,18 @@
+package: com.enhanceexperience.tetriseffect
+title: TetrisEffect
+status: works
+notes: Opened the game, messed around with the menu, and played the first level. Works great.
+tested_version: 2.0.2
+engine: Unreal
+xr: VrApi
+alt_overport:
+- patch_remove_unreal_force_quit
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 9ea10027ad8b7aefba8c14f23575c9cbbcaf3b38d12b971ea9c06635721b23c1
+  app: 0.9.1
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 48
+  issue: 45
+source_hint: tetriseffect
@@ -1,10 +1,12 @@
 package: com.playful.LuckysTale
 title: Lucky's Tale
-status: issues
-notes: Keeps MSAA off; the game turned it on by itself and the whole Frame restarted in a menu.
-details: Meta's OVRManager raises MSAA to 4x at runtime ("Switching to the recommended level"); multisampled
-  render-to-texture on GLES (Zink) hung the Frame's GPU (GitHub issue 9). frame.unity_runtime_msaa_off keeps it at 0;
-  not yet confirmed in a headset.
+status: works
+notes: Plays normally; touching a save slot no longer freezes the Frame (haptic_fix).
+details: Touching a save slot vibrates the controller through XR_FB_haptic_amplitude_envelope; OVRPort's OpenXR
+  loader converts that envelope with the duration in nanoseconds read as seconds and allocates an enormous buffer, so
+  the Frame ran out of memory and froze (found by the GitHub issue 9 reporter). FrameBridge's extension shim turns the
+  envelope into a plain vibration before OVRPort's loader sees it (haptic_fix). Brief pauses came from the headset's
+  wear sensor flickering, now hidden by focus_hold (on by default).
 tested_version: 1.0.55
 engine: Unity
 xr: VrApi
@@ -13,8 +15,11 @@ frame:
 - frame.unity_runtime_msaa_off
 device:
 - device.text_input_window
+adapter:
+  haptic_fix: 1
 verified:
-  date: '2026-10-03'
+  date: '2026-10-05'
  issue: 9
-updated: '2026-10-04'
+updated: '2026-10-05'
+min_app: 0.11.0
 source_hint: Luckys Tale
@@ -0,0 +1,28 @@
+package: com.qcxr.qcxr
+title: QuestCraft
+status: works
+notes: Minecraft runs in VR (Vivecraft, about 72 fps; drops while worlds load). Needs FramePort 0.10.0 or newer for
+  the picture (older versions show black). On first start QuestCraft downloads its Java runtime, which didn't unpack on
+  the Frame once (see details).
+details: QuestCraft downloads its Java runtime (JRE.zip from QuestCraft's GitHub releases) into files/runtimes/JRE
+  on first start; on the Frame that step once left nothing behind ("libjvm.so not found"; unpacked by hand). Two
+  Frame fixes, both owner-verified 2026-10-05. (1) Minecraft 1.21.5 checks GL errors strictly and aborted with
+  "OpenGL error 1282", an error the Frame's Mesa (Zink) reports where Quest's driver doesn't; QuestCraft's GL-to-GLES
+  layer (LTW) ignores GL errors when LIBGL_NOERROR is set, which Lepton passes from LEPTON_ENV_LIBGL_NOERROR. (2) LTW
+  passes desktop GL_DEPTH_COMPONENT32 through, which Mesa rejects, so every framebuffer was incomplete and the picture
+  black; frame.ltw_depth (automatic for APKs with libltw.so) loads GLES through a shim that asks for
+  GL_DEPTH_COMPONENT32F. Left over, harmless so far - Mesa still reports about 4 GL_INVALID_OPERATION per frame
+  ("in glthread", so the call is unknown; mesa_glthread=false would name it).
+tested_version: 6.0.0-RC4
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+lepton_env:
+  LEPTON_ENV_LIBGL_NOERROR: '1'
+verified:
+  date: '2026-10-05'
+updated: '2026-10-05'
+source_hint: QuestCraft
@@ -0,0 +1,20 @@
+package: com.resolutiongames.abvriop.santacruz
+title: palazzo_santacruz
+status: works
+notes: Played a few levels. Passthrough also works.
+tested_version: 3.7.6.10866-release
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 394214a68297c1e5b019dc4f65b145e7bd0e98604205616364e0c151c1afd894
+  app: 0.9.1
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 48
+  issue: 46
+source_hint: abvriop
@@ -0,0 +1,29 @@
+package: org.wiicompiled.quest
+title: WiiCompiled VR
+status: issues
+notes: 'To add a game: in FramePort''s Files tab, upload your .wcgame file to this game''s storage, folder
+  Android/data/org.wiicompiled.quest/files/WiiCompiledOpenXRVR/Import, then open WiiCompiled (it imports the newest
+  file there; one at a time). Once your game is imported, turn on "Start straight in VR" (and off "Show the app''s
+  Android window") and update it on the Frame: it then opens in VR without the flat launcher window, which otherwise
+  stays in view (turn it off again to import another game). The right eye jitters during races.'
+details: A native Mario Kart Wii recompilation (needs your own disc as .wcgame files built by the WiiCompiled
+  launcher on a computer). Lepton's Android has no document picker, so the launcher's "Import from computer" and
+  "select disc image" buttons fail (ActivityNotFoundException for OPEN_DOCUMENT); its Import folder is read when the
+  launcher opens instead. The game's libmain.so has its own OpenXR loader and talks to the Frame's runtime directly
+  (FrameBridge isn't in its path); the right-eye jitter in races comes from its stereo replay of the race view, so it
+  needs a fix in WiiCompiled itself. The launcher is a flat Android window (shown with lepton-show-flatscreen) that
+  stays in view after it starts the VR part (QuestActivity, process :game); frame.start_activity makes QuestActivity
+  the start activity (owner-verified 2026-10-05, opens straight in VR), but it skips the launcher's import step, so it
+  stays off by default.
+tested_version: 0.4.0-quest
+engine: Other
+xr: OpenXR
+frame:
+- frame.sdl_clipboard
+- frame.vk_sanitize
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+updated: '2026-10-05'
+source_hint: WiiCompiled
@@ -0,0 +1,22 @@
+package: unity.SUPERHOT_Team.SUPERHOT_VR_QA
+title: SUPERHOT VR
+status: works
+notes: Quest version. Needs FramePort's launcher from agent 41 (reinstall once) so the game can write its saves.
+details: Unity 2018.4 with built-in Oculus support (GLES). Its eye swapchains (GL_RGBA8, then a 16-bit format) are
+  created as sRGB by the adapter's swapchain_fix. The game creates its cloud save folder with mode 1700 and quits at
+  start when it can't write there ("Something failed to initialize. Quitting!"); the launcher now gives every folder
+  in the game's storage owner and group write permission.
+tested_version: '1.161'
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_no_msaa
+- frame.unity_oculus_check
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+updated: '2026-10-04'
+source_hint: SUPERHOT VR
@@ -13,6 +13,16 @@ signatures:
    severity: fatal
    diagnosis: 32-bit-only APK. The Steam Frame has no AArch32; this cannot run. Use the PC (Rift) version via Revive.
    suggest: []
+  - id: 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: swapchain-rect-invalid
+    pattern: 'xrEndFrame failed -25\b'
+    severity: fatal
+    diagnosis: The runtime rejects the game's frames because an image rect reaches past its swapchain (by a few pixels on some Frames); the game stops drawing (e.g. stuck at a "Waiting" box). FrameBridge from FramePort 0.11.0 clamps the rects - rebuild and reinstall the game.
+    suggest: [frame.adapter]
  - id: missing-ovr-symbol
    pattern: '(UnsatisfiedLinkError|cannot locate symbol) .*"?(ovr_[A-Za-z0-9_]+|ovrMessageType_ToString)'
    severity: fatal
@@ -263,6 +273,25 @@ signatures:
    diagnosis: The game crashed under Wine/Proton (set the Proton debug log and check steam-<appid>.log).
    suggest: [pcvr.proton_log]

+  - id: save-folder-permission
+    pattern: "(We don't have write permission to|UnauthorizedAccessException: Access to the path \"/(sdcard|storage/emulated/0)/Android/data/)"
+    severity: error
+    diagnosis: The game can't write to a folder it created in its storage (e.g. SUPERHOT's cloud/data, mode 1700, which
+      makes it quit at start). FramePort's launcher (agent 41 or newer) gives such folders owner and group write
+      permission before and during every launch; update the game on the Frame (reinstall) to get the new launcher.
+    suggest: []
+  - id: surface-swapchain-emulated
+    pattern: 'surface_emul: emulated Android surface swapchain'
+    severity: info
+    diagnosis: The game plays a video on a panel through an Android Surface (XR_KHR_android_surface_swapchain), which the
+      Frame's runtime refuses; FrameBridge emulates it (surface_emul) and copies each video frame into the panel.
+    suggest: []
+  - id: surface-swapchain-failed
+    pattern: 'surface_emul: (setup failed|upload failed|EGL context failed|Vulkan upload path unavailable)'
+    severity: warning
+    diagnosis: FrameBridge couldn't emulate an Android video panel (XR_KHR_android_surface_swapchain); the panel stays
+      empty, and a game waiting for its intro video may stay black (e.g. I Am Monkey's intro).
+    suggest: []
 milestones:  # progress markers, in order; the furthest one reached is reported
  - {id: pcvr-launch, kind: pcvr, pattern: 'FramePort: launching|Launched injector with', label: Launcher started}
  - {id: pcvr-oculus-hmd, kind: pcvr, pattern: 'FramePort oculushmd: OculusHMDConnected event ready', label: Oculus headset event provided}
@@ -0,0 +1,31 @@
+# Meta XR Audio metadata lifetime
+
+FrameBridge automatically handles metadata retirement in the verified AArch64
+Meta XR Audio Wwise build (`e1619e7fb839badf0ea5ecc22d9f028d0b17c34d`). It requires
+the build ID and exact function prologues; other builds and 32-bit adapters are
+left unchanged. No additional patch switch or recipe entry is required.
+
+The SDK queues terminated metadata for deletion, then drains those queues before
+reading the current `AkAudioObjects` snapshot. In Batman: Arkham Shadow, that
+snapshot can still reference queued metadata during smoke-bomb playback. The
+audio thread subsequently clears its dirty flags at offset 8 through the stale
+pointer. A hardware watch captured this store in
+`OculusEndpointSink::ConsumeObjectExperimentalMetadata`, at library offset
+`0x2ced90`. Reallocated input tree nodes occupy the same 48-byte size class;
+the stale store corrupts their right pointer and the game crashes later.
+
+`native/adapter/audio_metadata.h` wraps the audio consumption boundary to make
+the current snapshot available to metadata cleanup. `audio_metadata_queue.h`
+retains queued objects still referenced by that snapshot, then reclaims them
+normally when the references disappear. It preserves the SDK's queue mutex,
+virtual deleting destructor, audio parameters and processing. There is no timed
+quarantine, replacement allocator, audio suppression or diagnostic memory arena.
+
+Synthetic regression tests exercise mixed referenced and unreferenced queue
+entries, both metadata types, subsequent retirement, and cleanup without a live
+snapshot. On-headset smoke-bomb tests first showed the observed overwrite stopped,
+then passed with ordinary allocations and all memory diagnostics removed.
+
+The existing `frame.adapter` install step includes the repair in its packaged
+adapter and updates already wrapped APKs. Rebuild the adapters and checksums with
+`python native/build.py --only adapter`.
@@ -0,0 +1,31 @@
+# FAQ
+
+## How should I lay out a game that has OBB files (an APK plus a data folder)?
+
+Give every game its own folder, put the APK in it, and put the game's data next to the APK in a folder named
+after the game's **package name** (the name the `.obb` files contain, e.g. `com.Armature.VR4`):
+
+```
+Games/                                  ← scan this folder (Add games → Scan a folder)
+├── Resident Evil 4/                    ← one folder per game (any name)
+│   ├── VR4.apk                         ← the APK (any file name)
+│   └── com.Armature.VR4/               ← the data folder: exactly the package name
+│       ├── main.203.com.Armature.VR4.obb
+│       └── patch.203.com.Armature.VR4.obb
+└── Beat Saber/
+    └── com.beatgames.beatsaber.apk     ← games without OBBs: just the APK
+```
+
+- **Data folder name:** the package name (`com.Armature.VR4` above), or `obb`. FramePort uses the first of the two
+  that exists and isn't empty.
+- **Everything in that folder is copied** to the game's `Android/obb/<package>/` on the Frame, subfolders included.
+  So games that ship raw data files instead of `.obb` files work the same way.
+- **One game per folder.** Several APKs in one folder count as one game; FramePort uses the first and keeps the others
+  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
+  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
+first: the game's page shows the package name under **Details**.
@@ -106,6 +106,29 @@
 - SSH: `sshd` must be enabled (`sudo systemctl enable --now sshd`), which needs a user password (`passwd`).
 - mDNS: avahi-daemon runs by default; hostname `frame` → `frame.local`.

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

 - Lepton's Android has no on-screen keyboard (IME) and VR apps run headless, so no Android window has keyboard focus
@@ -7,12 +7,14 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Game | Platform | Status | Notes |
 |---|---|---|---|
 | 4XVR Video Player | Quest | ✅ Works |  |
+| Accounting+ | Quest | ✅ Works |  |
 | AllInOneSports | Quest | ✅ Works |  |
 | Asgard's Wrath 2 | Quest | ✅ Works |  |
 | BAM | Quest | ✅ Works |  |
 | BARTENDER VR SIMULATOR | Quest | ✅ Works |  |
 | Batman: Arkham Shadow | Quest | ✅ Works |  |
 | BattleGlide | Quest | ✅ Works |  |
+| BattleSisters | Quest | ✅ Works |  |
 | Beat Saber | Quest | ✅ Works |  |
 | Beat Saber (co-existence build) | Quest | ✅ Works |  |
 | Blade & Sorcery: Nomad | Quest | ✅ Works |  |
@@ -23,18 +25,25 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Espire 2 | Quest | ✅ Works |  |
 | Genotype | Quest | ✅ Works |  |
 | H.U.N.T | Quest | ✅ Works |  |
+| I Am Cat | Quest | ✅ Works |  |
+| I Am Monkey | Quest | ✅ Works |  |
 | In Death: Unchained | Quest | ✅ Works |  |
+| Into The Radius 2 | Quest | ✅ Works |  |
 | Job Simulator | Quest | ✅ Works |  |
 | Keep Talking and Nobody Explodes | Quest | ✅ Works |  |
 | LEGO® Bricktales | Quest | ✅ Works |  |
+| Lucky's Tale | Quest | ✅ Works |  |
 | Marvel's Deadpool VR | Quest | ✅ Works |  |
+| Marvel's Iron Man VR | Quest | ✅ Works |  |
 | Medieval Dynasty New Settlement | Quest | ✅ Works |  |
 | Mobile Suit Gundam: Silver Phantom | Quest | ✅ Works |  |
 | Nano | Quest | ✅ Works |  |
 | NEX Player | Quest | ✅ Works |  |
 | NOPE CHALLENGE | Quest | ✅ Works |  |
+| palazzo_santacruz | Quest | ✅ Works |  |
 | Path of the Warrior | Quest | ✅ Works |  |
 | PowerWash Simulator VR | Quest | ✅ Works |  |
+| QuestCraft | Quest | ✅ Works |  |
 | Rick and Morty: Virtual Rick-ality | PC VR | ✅ Works |  |
 | Riven | Quest | ✅ Works |  |
 | Robo Recall | Quest | ✅ Works |  |
@@ -42,21 +51,24 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Space Pirate Trainer Quest | Quest | ✅ Works |  |
 | Stremio | Quest | ✅ Works |  |
 | SUPERHOT VR | PC VR | ✅ Works |  |
+| SUPERHOT VR | Quest | ✅ Works |  |
+| TetrisEffect | Quest | ✅ Works |  |
 | The Climb 2 | Quest | ✅ Works |  |
+| The Room VR | Quest | ✅ Works |  |
 | Toy Master | Quest | ✅ Works |  |
 | Under Cover | Quest | ✅ Works |  |
 | VR4 | Quest | ✅ Works |  |
 | Wallace & Gromit in The Grand Getaway | Quest | ✅ Works |  |
+| Waltz of the Wizard: Extended Edition | Quest | ✅ Works |  |
 | Wander | Quest | ✅ Works |  |
-| Accounting+ | Quest | ⚠️ Works with issues | Starts in VR, but doesn't get past its "press any button" screen. |
 | Arcsmith | Quest | ⚠️ Works with issues | Right eye distorts during movement (unresolved; swap, tracking, Valve layers, depth and pacing ruled out). |
 | 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. |
-| I Am Cat | Quest | ⚠️ Works with issues | The view vibrates slightly, even when holding still. |
-| Lucky's Tale | Quest | ⚠️ Works with issues | Keeps MSAA off; the game turned it on by itself and the whole Frame restarted in a menu. |
 | 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). |
 | Silhouette | Quest | ⚠️ Works with issues | Hand-tracking game; the Frame synthesizes hands from controllers, so it is janky. |
 | Time Stall | Quest | ⚠️ Works with issues | Both eyes distort during movement (unresolved). |
+| Vader Immortal: Episode I | Quest | ⚠️ Works with issues | Starts in VR and plays the intro, then stays on the loading card (Vader's portrait with a progress bar). |
+| WiiCompiled VR | Quest | ⚠️ Works with issues | To add a game: in FramePort's Files tab, upload your .wcgame file to this game's storage, folder Android/data/org.wiicompiled.quest/files/WiiCompiledOpenXRVR… |
 | BONELAB | Quest | ❌ Doesn't run | Crashes while starting its graphics (Vulkan); no fix yet. |
 | Espire 1: VR Operative (Quest Edition) | Quest | ❌ Doesn't run | Mesa GL driver crash during texture upload. |
 | HITMAN 3 VR: Reloaded | Quest | ❌ Doesn't run | Vulkan driver crash (freedreno), even without Valve layers. |
@@ -49,6 +49,20 @@ The Frame and the computer must be on the same network.
 and approve it on the Frame (Valve's own devkit pairing; it only sends this computer's key to the Frame). Install
 Lepton from the Steam Frame page afterwards if it's missing.

+### With a USB cable
+
+For networks that block the setup (guest Wi-Fi, firewalls, discovery not working), and for faster uploads:
+
+1. On the Frame, turn on **Developer Mode** (Settings → System → Developer Mode). The Frame's USB network only exists
+   in Developer Mode.
+2. Connect the Frame's USB-C port to the computer.
+3. In FramePort: **Steam Frame → Set up with a USB cable**. FramePort detects the cable and shows the setup command,
+   which reaches the computer over the cable. Already set up? It connects over the cable right away.
+
+The cable needs no driver on Windows 10/11, macOS or Linux, and the computer gets an address from the Frame
+automatically. Uploads use the cable whenever it's plugged in (about 37 MB/s, ~3× typical Wi-Fi), even when FramePort
+connected over Wi-Fi. Unplug it any time: FramePort finds the Frame on Wi-Fi again by itself.
+
 ### Firewalls

 If the setup command only says "timed out", a firewall on your computer blocks the Frame; the setup page
@@ -101,6 +115,12 @@ reality), showing only what matters for that game. Changes are kept with the gam

 ## Updating

+**Game configs** (the tested recipes in the catalog) update by themselves: FramePort checks GitHub every 6 hours for
+newly confirmed or fixed configs and uses them without a FramePort update; a game whose recipe changed then shows
+**Update on Frame**. Configs that need a newer FramePort are skipped until you update. Settings → Data shows the last
+check (**Check now**) and turns this off.
+
+
 FramePort checks for a new release at start and every 6 hours (it only downloads the release information). When one
 exists, the Library shows **Update now**: FramePort downloads the new version, verifies it against the release's
 `SHA256SUMS.txt` (on Windows also the signature), restarts and opens as the new version. Games, settings, signing keys
@@ -110,6 +130,10 @@ Settings → **Updates**: turn the check off, or turn on **Install updates autom
 installs at the next start). If FramePort's folder isn't writable, **Update now** opens the release page instead. The
 update log is `logs/update.log` in the data folder.

+**Dev builds:** when you're asked to test a fix before it's released, use Settings → Updates → **Install the latest
+dev build…**. It shows what to test, then installs like an update (same checks). Dev builds are less tested; the next
+release is offered to you as a normal update.
+
 Command line: `frameport update` (`--check` only checks, exit code 10 = update available; `--yes` doesn't ask).
 `FRAMEPORT_NO_UPDATE_CHECK=1` turns all checks off.

@@ -132,12 +156,28 @@ starts it if asked). FramePort installs it on the Frame and Proton runs it as a
 it shows up in the Frame's Steam library tagged "Windows game on Frame". Whether a game runs depends on Proton on ARM
 (x86 games run through emulation).

+## Linux apps (arm64)
+
+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`/
+`.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
+  page lists them: look for a build that includes them.
+- From the command line: `frameport add-linux <AppImage, folder or archive> [--exe <program>]`.
+
 ## Files on the Frame (videos, documents, mods, saves)

 The **Files** tab manages files on the Frame over the same connection as installs; no other transfer app is needed.
 Pick a location, browse folders, and use **Upload files** / **Upload folder**, **New folder**, or the download, rename
-and delete buttons on each entry. Tick several entries (or the box above the list for all) to download or delete them
-together. In the downloaded app you can also drag files and folders from Explorer / Finder / your file manager onto
+and delete buttons on each entry. Right-click an entry (or the empty space) for the same actions in a menu. Tick
+several entries (or the box above the list for all), or click and drag across them, to download or delete them
+together; a right-click on one of them then acts on all. The **Screenshots** tab and the **Library** work the same
+way: right-click for a menu, drag across cards to select several. In the downloaded app you can also drag files and folders from Explorer / Finder / your file manager onto
 the list to upload them into the open folder. Uploads and downloads run in the Activity panel, resume after an interruption and
 skip files that are already there.

@@ -167,6 +207,7 @@ 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) |
 | `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 |
@@ -15,6 +15,11 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 |---|---|---|
 | 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 |
+| Steam's Exit game leaves the game running (container `lepton-steamlaunch-<appid>` still up) | Steam stopped only its `reaper`; launch.sh and Lepton (setsid) never got a signal (GitHub #36) | agent v44: launch.sh's 2 s loop ends the game when its parent is gone (`upgrade_launchers` adds it to existing launchers); by hand: `podman kill lepton-steamlaunch-<appid>` |
+| 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) |
 | `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 |
@@ -30,6 +35,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | `INSTALL_FAILED_NO_MATCHING_ABIS` | 32-bit-only APK; Frame has no AArch32 | None. PC/Rift version via Revive |
 | `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`) |
@@ -49,8 +55,12 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | PC VR game judders/stutters although the GPU keeps up; vrcompositor.txt "Timed out. N total" high or frames dropped | the game misses the headset's refresh (e.g. 96 Hz = 10.4 ms; Stormland's slow frames take 10.7 ms) | `pcvr.steamvr_tuning` (default on): next Play sets SteamVR per-app `preferredRefreshRate` + `motionSmoothingOverride` via `fp_vrsettings.exe` |
 | Quest app keeps recentering / snapping the view when you turn your head; log shows session state 5→4→3→4→5 within a second | the Frame briefly takes focus; the app recenters on focus changes | unfixed: hiding the dips (debounce) made AC Nexus stay black, so it was removed |
 | Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | upload in the Files tab (Videos = /sdcard/Movies) and browse folders in the app |
+| Batman: Arkham Shadow closes during smoke-bomb effects; later input-tree corruption | Meta XR Audio Wwise deletes queued metadata still referenced by the current audio frame, then writes through the stale pointer | FrameBridge automatically retires metadata after current-frame references disappear, for the verified AArch64 SDK build only; see [AUDIO_METADATA.md](AUDIO_METADATA.md) |
+| Game stays on a loading or "Waiting" box although it reached FOCUSED; log `FrameBridge: xrEndFrame failed -25` then no more `pacing:` lines (e.g. PowerWash Simulator on some Frames, GitHub #39) | The eye image rect ends a few pixels past its swapchain (Unity rounds the swapchain width, the runtime's recommended size differs per Frame); SteamVR rejects every frame with XR_ERROR_SWAPCHAIN_RECT_INVALID | FrameBridge clamps every projection/quad image rect to its swapchain (`rect_clamp`, default on since 0.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 |
 | 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) |
+| 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` |
@@ -79,7 +89,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Eye distortion while moving (Arcsmith, Time Stall) | unknown (not eye swap, tracking, Valve layers, depth or pacing) | unresolved |
 | One eye grey / only effects (I Am Cat, Unity Oculus XR Plugin on GLES) | the game's multiview pass draws array slice 1 wrong on Zink | `frame.unity_multipass` (also rewrites the getter's inlined read in `OculusLoader.Initialize`; check for two `array=1` eye swapchains) |
 | 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 1-2 s now and then, no flicker; only some games (Blade & Sorcery) | the headset's wear sensor flickers off while worn (SteamVR vrserver.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=1` + `focus_hold_ms=2500` per game; native games don't react, so it's per game |
+| 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 `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 |
 | 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 |
@@ -98,6 +108,11 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 - Which library a stale pointer belonged to: turn on the Android linker's log for one run by adding
  `debug.ld.app.<pkg>=dlopen` as an extra line of `LEPTON_GFXRECON_FP_PROPS` (first line `0`) in the game's
  launch.sh on the Frame (back it up, restore it after) and look for `dlclose: unloading "…"`.
+- Memory runaways / busy loops: `perf` works as steamos (`perf_event_paranoid` 2, user space only; `ptrace_scope` 1
+  blocks eu-stack/gdb/debuggerd). `perf record -p <pid> -e page-faults -c 64 --call-graph fp` names the thread
+  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).
 - 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:`
@@ -1,5 +1,9 @@
 # Native components

+FrameBridge includes automatic metadata retirement for the verified Meta XR Audio
+Wwise build; see [AUDIO_METADATA.md](../docs/AUDIO_METADATA.md) for its lifetime
+invariant and regression coverage. It uses the existing adapter installation.
+
 Sources of the prebuilt binaries in `../artifacts/` (committed, with `SHA256SUMS`). End users never compile anything;
 developers rebuild with `python native/build.py` (downloads NDK r27c, OpenXR headers at pinned commits, d8 into
 `native/.cache/`, git-ignored). The adapter, GL shim and platform compat rebuild byte-identically; the VrApi bridge
@@ -10,6 +14,7 @@ embeds debug paths (`-g`) and the dex depends on the d8 version, so those differ
 | `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. |
 | `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, diagnostics behind `-DOVP_GL_DIAG`. |
 | `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`. Host-tested against a stand-in loader (`tests/test_langpack.py`, plain `cc`, no NDK); the bionic/headset side is unverified. |
 | `glshim/` | `arm64-v8a/libglshim.so` | Mesa GLSL compatibility for GLAD engines (hooks eglGetProcAddress): comments out `#pragma` before `#extension`, enables `GL_EXT_shader_implicit_conversions`, hides GL_OVR_multiview (`gl_hide_multiview`, default 1) and logs failed shaders. `-DGLSHIM_TRACE` adds per-FBO draw/error tracing. |
 | `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). |
@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Meta XR Audio Wwise metadata retirement. Enabled automatically for the
+// exact verified AArch64 SDK build; unrelated libraries remain untouched.
+#pragma once
+#if defined(__aarch64__)
+#include <pthread.h>
+#include <sched.h>
+#include <sys/mman.h>
+#include <unistd.h>
+#include <stdint.h>
+#include <time.h>
+#include <link.h>
+#include <string.h>
+static size_t mx_audio_page;
+static void *mx_audio_detour(unsigned char *address,void *replacement,const uint32_t expected[4]) {
+    if(memcmp(address,expected,16)) return NULL;
+    unsigned char *trampoline=mmap(NULL,mx_audio_page,PROT_READ|PROT_WRITE,MAP_PRIVATE|MAP_ANONYMOUS,-1,0);
+    if(trampoline==MAP_FAILED) return NULL;
+    uint32_t branch[2]={0x58000050u,0xd61f0200u}; // ldr x16, +8; br x16
+    memcpy(trampoline,address,16);
+    memcpy(trampoline+16,branch,8);
+    uintptr_t continuation=(uintptr_t)address+16;
+    memcpy(trampoline+24,&continuation,8);
+    __builtin___clear_cache((char*)trampoline,(char*)trampoline+32);
+    if(mprotect(trampoline,mx_audio_page,PROT_READ|PROT_EXEC)) return NULL;
+    unsigned char *page=(unsigned char*)((uintptr_t)address&~(mx_audio_page-1));
+    if(mprotect(page,mx_audio_page,PROT_READ|PROT_WRITE|PROT_EXEC)) return NULL;
+    memcpy(address,branch,8);
+    memcpy(address+8,&replacement,8);
+    __builtin___clear_cache((char*)address,(char*)address+16);
+    mprotect(page,mx_audio_page,PROT_READ|PROT_EXEC);
+    return trampoline;
+}
+#include "audio_metadata_queue.h"
+typedef struct {float previous,current;} MxAudioRamp;
+static uintptr_t mx_audio_base;
+// set once the library was found but isn't the verified build: stop looking (xrPollEvent runs several times a frame)
+static int mx_audio_checked;
+static uint64_t (*mx_audio_consume_original)(void*,void*,void*,const void*,MxAudioRamp);
+static void mx_audio_kill(unsigned experimental) {
+    void *mutex=(void*)(mx_audio_base+(experimental?0x5fe2e0:0x5fe380));
+    int (*trylock)(void*)=(void*)(mx_audio_base+0x5b369c);
+    void (*unlock)(void*)=(void*)(mx_audio_base+0x5b36bc);
+    if(!trylock(mutex))return;
+    mx_audio_drain((void**)(mx_audio_base+(experimental?0x5fe2d8:0x5fe378)),experimental?40:24);
+    unlock(mutex);
+}
+static void mx_audio_kill_experimental(void) {mx_audio_kill(1);}
+static void mx_audio_kill_regular(void) {mx_audio_kill(0);}
+static uint64_t mx_audio_consume(void *sink,void *main_mix,void *passthrough,const void *objects,MxAudioRamp ramp) {
+    const unsigned char *previous=mx_audio_objects;mx_audio_objects=objects;
+    // An audio thread can enter just after its prologue was patched, before
+    // the installing thread publishes the completed trampoline.
+    uint64_t (*original)(void*,void*,void*,const void*,MxAudioRamp);
+    while(!(original=__atomic_load_n(&mx_audio_consume_original,__ATOMIC_ACQUIRE)))sched_yield();
+    uint64_t result=original(sink,main_mix,passthrough,objects,ramp);
+    mx_audio_objects=previous;return result;
+}
+static int mx_audio_find(struct dl_phdr_info *info,size_t size,void *unused) {
+    (void)size;(void)unused;
+    if(!strstr(info->dlpi_name,"/libMetaXRAudioWwise.so"))return 0;
+    if(mx_audio_base)return 1;
+    const unsigned char id[20]={0xe1,0x61,0x9e,0x7f,0xb8,0x39,0xba,0xdf,0x0e,0xa5,0xec,0xc2,0x2d,0x9f,0x02,0x8d,0x0b,0x17,0xc3,0x4d};
+    int match=0;
+    for(unsigned i=0;i<info->dlpi_phnum;i++)if(info->dlpi_phdr[i].p_type==PT_NOTE) {
+        const unsigned char *p=(void*)(info->dlpi_addr+info->dlpi_phdr[i].p_vaddr);
+        const unsigned char *end=p+info->dlpi_phdr[i].p_memsz;
+        while(p+sizeof(Elf64_Nhdr)<=end) {
+            const Elf64_Nhdr *note=(void*)p;
+            const unsigned char *name=p+sizeof(*note),*desc=name+((note->n_namesz+3)&~3u);
+            const unsigned char *next=desc+((note->n_descsz+3)&~3u);
+            if(next>end || next<=p)break;
+            if(note->n_type==NT_GNU_BUILD_ID && note->n_namesz==4 && !memcmp(name,"GNU",4) && note->n_descsz==20 && !memcmp(desc,id,20))match=1;
+            p=next;
+        }
+    }
+    if(!match){__atomic_store_n(&mx_audio_checked,1,__ATOMIC_RELEASE);return 1;}
+    const uint32_t consume[4]={0xd10743ff,0x6d1623e9,0xa9177bfd,0xa9186ffc};
+    const uint32_t kill[4]={0xa9bd7bfd,0xf9000bf5,0xa9024ff4,0x910003fd};
+    unsigned char *base=(void*)info->dlpi_addr;
+    if(memcmp(base+0x2c8fac,consume,16) || memcmp(base+0x2be2c0,kill,16) || memcmp(base+0x2be7b0,kill,16)) {
+        __atomic_store_n(&mx_audio_checked,1,__ATOMIC_RELEASE);return 1;
+    }
+    __atomic_store_n(&mx_audio_base,info->dlpi_addr,__ATOMIC_RELEASE);
+    void *original=mx_audio_detour(base+0x2c8fac,(void*)mx_audio_consume,consume);
+    __atomic_store_n(&mx_audio_consume_original,original,__ATOMIC_RELEASE);
+    if(!__atomic_load_n(&mx_audio_consume_original,__ATOMIC_ACQUIRE)) {
+        __atomic_store_n(&mx_audio_base,0,__ATOMIC_RELEASE);return 1;
+    }
+    if(!mx_audio_detour(base+0x2be2c0,(void*)mx_audio_kill_experimental,kill) || !mx_audio_detour(base+0x2be7b0,(void*)mx_audio_kill_regular,kill)) {
+        LOG("FrameBridge audio metadata: incomplete installation");return 1;
+    }
+    LOG("FrameBridge audio metadata: metadata reclamation follows current audio-frame references; Meta audio base=%p",base);
+    return 1;
+}
+static pthread_mutex_t mx_audio_install_mutex=PTHREAD_MUTEX_INITIALIZER;
+static void mx_audio_initialize(void) {
+    if(__atomic_load_n(&mx_audio_base,__ATOMIC_ACQUIRE) || __atomic_load_n(&mx_audio_checked,__ATOMIC_ACQUIRE))return;
+    // until the game loads the library: look at most once a second (dl_iterate_phdr takes the linker's lock)
+    static _Atomic long mx_audio_last_scan;
+    struct timespec now;clock_gettime(CLOCK_MONOTONIC,&now);
+    if(now.tv_sec==mx_audio_last_scan)return;
+    mx_audio_last_scan=now.tv_sec;
+    if(pthread_mutex_trylock(&mx_audio_install_mutex))return;
+    if(!mx_audio_page)mx_audio_page=(size_t)sysconf(_SC_PAGESIZE);
+    if(!mx_audio_base)dl_iterate_phdr(mx_audio_find,NULL);
+    pthread_mutex_unlock(&mx_audio_install_mutex);
+}
+#else
+static void mx_audio_initialize(void) {}
+#endif
@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: GPL-3.0-only
+#pragma once
+#include <stdint.h>
+#include <stddef.h>
+#include <string.h>
+// Experimental lifetime repair for the pinned Meta XR Audio Wwise build.
+// A queued metadata object must not be reclaimed while the current immutable
+// AkAudioObjects snapshot still references it. Preserve the SDK's queue mutex,
+// virtual destructor, list linkage, audio processing, and dirty-flag writes.
+static _Thread_local const unsigned char *mx_audio_objects;
+static unsigned mx_audio_held,mx_audio_reclaimed;
+static int mx_audio_referenced(const void *pointer) {
+    if(!mx_audio_objects)return 0;
+    uint32_t count;memcpy(&count,mx_audio_objects,4);
+    const unsigned char *const *objects;memcpy(&objects,mx_audio_objects+16,8);
+    // Refuse to reclaim on an unrecognised snapshot rather than dereferencing
+    // unbounded arrays. These bounds exceed the game's ordinary voice counts.
+    if(count>4096 || (count && !objects))return 1;
+    for(unsigned i=0;i<count;i++) {
+        const unsigned char *object=objects[i];if(!object)continue;
+        uint32_t metadata_count;const unsigned char *metadata;
+        memcpy(&metadata,object+104,8);memcpy(&metadata_count,object+112,4);
+        if(metadata_count>4096 || (metadata_count && !metadata))return 1;
+        for(unsigned j=0;j<metadata_count;j++) {
+            const void *parameter;memcpy(&parameter,metadata+(size_t)j*24+8,8);
+            if(parameter==pointer)return 1;
+        }
+    }
+    return 0;
+}
+// Caller holds the original queue's mutex, just as ExecuteKillList did.
+static void mx_audio_drain(void **head,size_t next_offset) {
+    void **link=head;
+    while(*link) {
+        void *pointer=*link;void **next=(void**)((unsigned char*)pointer+next_offset);
+        if(mx_audio_referenced(pointer)) {
+            link=next;
+            unsigned held=__atomic_fetch_add(&mx_audio_held,1,__ATOMIC_RELAXED);
+            if(held<8)LOG("FrameBridge audio metadata: queued metadata=%p still referenced by audio frame; retained",pointer);
+        } else {
+            *link=*next;
+            void (**table)(void*)=*(void (***)(void*))pointer;
+            table[1](pointer);
+            __atomic_fetch_add(&mx_audio_reclaimed,1,__ATOMIC_RELAXED);
+        }
+    }
+}
@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Included by frame_adapter.c (after flip_vk.c). Per-game diagnostics for "one eye looks wrong" reports
+// (eye_debug=1; everything also goes to framebridge.log in the app's external files folder):
+//  * every frame's projection layer: each eye's submitted pose vs. a fresh xrLocateViews at the frame's display time
+//    (game-side pose errors), the left/right eye relation (eye distance, relative rotation: must stay constant),
+//    and how long before xrEndFrame each eye's image was released (images handed over too early/late);
+//    summarised every 5 s, the first frames in full.
+//  * release_wait: before an image is released, wait for the app's GPU work on the session's queue (Vulkan) or
+//    glFinish (GLES), for games that release images whose rendering hasn't finished. 2 = only after the first 60 s
+//    of frames, so one headset session compares both (log "release_wait now ON").
+
+#define EYE_TRACKED 16
+
+static struct { XrSwapchain handle; int64_t released_ns; } eye_released[EYE_TRACKED];
+static pthread_mutex_t eye_lock = PTHREAD_MUTEX_INITIALIZER;
+static int64_t eye_first_frame_ns;
+
+static int release_wait_active(void) {
+    if (release_wait == 1) return 1;
+    if (release_wait != 2 || !eye_first_frame_ns) return 0;
+    static int announced;
+    int on = monotonic_ns() - eye_first_frame_ns > 60000000000ll;
+    if (on && !announced++) LOG("eye_debug: release_wait now ON (A/B: the first 60 s ran without it)");
+    return on;
+}
+
+static void eye_wait_for_gpu(void) {
+    if (vk.device) {
+        static PFN_vkQueueWaitIdle wait_idle;
+        if (!wait_idle && vk_ready()) wait_idle = (PFN_vkQueueWaitIdle)vk.GetDeviceProcAddr(vk.device, "vkQueueWaitIdle");
+        if (wait_idle && vk.queue) wait_idle(vk.queue);
+    } else {
+        static void (*finish)(void);
+        if (!finish) finish = (void (*)(void))dlsym(RTLD_DEFAULT, "glFinish");
+        if (finish) finish();
+    }
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL eye_hook_xrReleaseSwapchainImage(XrSwapchain swapchain,
+                                                                       const XrSwapchainImageReleaseInfo *info) {
+    PFN_xrReleaseSwapchainImage fn = (PFN_xrReleaseSwapchainImage)lookup(active_instance, "xrReleaseSwapchainImage");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (release_wait_active()) eye_wait_for_gpu();
+    XrResult result = fn(swapchain, info);
+    if (eye_debug) {
+        int64_t now = monotonic_ns();
+        pthread_mutex_lock(&eye_lock);
+        int slot = -1;
+        for (int i = 0; i < EYE_TRACKED && slot < 0; ++i)
+            if (eye_released[i].handle == swapchain) slot = i;
+        for (int i = 0; i < EYE_TRACKED && slot < 0; ++i)
+            if (!eye_released[i].handle) slot = i;
+        if (slot < 0) slot = (int)(now % EYE_TRACKED);
+        eye_released[slot].handle = swapchain;
+        eye_released[slot].released_ns = now;
+        pthread_mutex_unlock(&eye_lock);
+    }
+    return result;
+}
+
+static int64_t eye_release_age_ns(XrSwapchain swapchain, int64_t now) {
+    int64_t age = -1;
+    pthread_mutex_lock(&eye_lock);
+    for (int i = 0; i < EYE_TRACKED; ++i)
+        if (eye_released[i].handle == swapchain) age = now - eye_released[i].released_ns;
+    pthread_mutex_unlock(&eye_lock);
+    return age;
+}
+
+static float eye_angle_deg(XrQuaternionf a, XrQuaternionf b) {
+    float d = fabsf(a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w);
+    return d >= 1.0f ? 0.0f : 2.0f * acosf(d) * 57.29578f;
+}
+
+static float eye_dist_mm(XrVector3f a, XrVector3f b) {
+    float x = a.x - b.x, y = a.y - b.y, z = a.z - b.z;
+    return sqrtf(x * x + y * y + z * z) * 1000.0f;
+}
+
+static void eye_debug_end_frame(XrSession session, const XrFrameEndInfo *info) {
+    if (!info) return;
+    const XrCompositionLayerProjection *proj = NULL;
+    for (uint32_t i = 0; i < info->layerCount && !proj; ++i)
+        if (info->layers[i] && info->layers[i]->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
+            ((const XrCompositionLayerProjection *)info->layers[i])->viewCount == 2)
+            proj = (const XrCompositionLayerProjection *)info->layers[i];
+    if (!proj) return;
+    int64_t now = monotonic_ns();
+    if (!eye_first_frame_ns) eye_first_frame_ns = now;
+    static struct {
+        int frames, located;
+        float pos_err[2], rot_err[2], pos_err_max[2], rot_err_max[2];  // submitted vs. fresh, per eye
+        float ipd_min, ipd_max, rel_rot_max, step_max[2];               // eye relation; frame-to-frame jump per eye
+        float age_min[2], age_max[2];                                   // ms from release to xrEndFrame
+        int64_t window;
+    } st;
+    static XrPosef last[2];
+    static int have_last;
+    static int detailed;
+    if (!st.window) { st.window = now; st.ipd_min = 1e9f; st.age_min[0] = st.age_min[1] = 1e9f; }
+    // a fresh location of the same views at the frame's display time, in the layer's space
+    XrView fresh[2] = {{XR_TYPE_VIEW, NULL}, {XR_TYPE_VIEW, NULL}};
+    XrViewState vs = {XR_TYPE_VIEW_STATE, NULL};
+    uint32_t n = 0;
+    PFN_xrLocateViews locate = (PFN_xrLocateViews)lookup(active_instance, "xrLocateViews");
+    XrViewLocateInfo li = {XR_TYPE_VIEW_LOCATE_INFO, NULL, XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO, info->displayTime,
+                           proj->space};
+    int located = locate && XR_SUCCEEDED(locate(session, &li, &vs, 2, &n, fresh)) && n == 2 &&
+                  (vs.viewStateFlags & XR_VIEW_STATE_POSITION_VALID_BIT);
+    const XrCompositionLayerProjectionView *v = proj->views;
+    float ipd = eye_dist_mm(v[0].pose.position, v[1].pose.position);
+    float rel = eye_angle_deg(v[0].pose.orientation, v[1].pose.orientation);
+    ++st.frames;
+    if (ipd < st.ipd_min) st.ipd_min = ipd;
+    if (ipd > st.ipd_max) st.ipd_max = ipd;
+    if (rel > st.rel_rot_max) st.rel_rot_max = rel;
+    for (int e = 0; e < 2; ++e) {
+        int64_t age = eye_release_age_ns(v[e].subImage.swapchain, now);
+        float ms = age < 0 ? -1.0f : age / 1e6f;
+        if (ms < st.age_min[e]) st.age_min[e] = ms;
+        if (ms > st.age_max[e]) st.age_max[e] = ms;
+        if (located) {
+            float pe = eye_dist_mm(v[e].pose.position, fresh[e].pose.position);
+            float re = eye_angle_deg(v[e].pose.orientation, fresh[e].pose.orientation);
+            st.pos_err[e] += pe;
+            st.rot_err[e] += re;
+            if (pe > st.pos_err_max[e]) st.pos_err_max[e] = pe;
+            if (re > st.rot_err_max[e]) st.rot_err_max[e] = re;
+        }
+        if (have_last) {
+            float step = eye_angle_deg(last[e].orientation, v[e].pose.orientation);
+            if (step > st.step_max[e]) st.step_max[e] = step;
+        }
+        last[e] = v[e].pose;
+    }
+    have_last = 1;
+    if (located) ++st.located;
+    if (detailed < 4) {
+        ++detailed;
+        for (int e = 0; e < 2; ++e)
+            LOG("eye_debug: eye %d swapchain=%p rect=%d,%d %dx%d array=%u pos=%.4f,%.4f,%.4f rot=%.4f,%.4f,%.4f,%.4f "
+                "fov=%.3f/%.3f/%.3f/%.3f fresh pos=%.4f,%.4f,%.4f", e, (void *)(uintptr_t)v[e].subImage.swapchain,
+                v[e].subImage.imageRect.offset.x, v[e].subImage.imageRect.offset.y, v[e].subImage.imageRect.extent.width,
+                v[e].subImage.imageRect.extent.height, v[e].subImage.imageArrayIndex, v[e].pose.position.x,
+                v[e].pose.position.y, v[e].pose.position.z, v[e].pose.orientation.x, v[e].pose.orientation.y,
+                v[e].pose.orientation.z, v[e].pose.orientation.w, v[e].fov.angleLeft, v[e].fov.angleRight,
+                v[e].fov.angleUp, v[e].fov.angleDown, fresh[e].pose.position.x, fresh[e].pose.position.y,
+                fresh[e].pose.position.z);
+    }
+    if (now - st.window > 5000000000ll) {
+        int l = st.located ? st.located : 1;
+        LOG("eye_debug: %d frames | eye distance %.1f-%.1f mm, eye-to-eye rotation max %.2f deg | vs fresh pose: "
+            "L avg %.1f mm/%.2f deg max %.1f mm/%.2f deg, R avg %.1f mm/%.2f deg max %.1f mm/%.2f deg (%d located) | "
+            "largest frame step L %.2f R %.2f deg | release->end L %.1f-%.1f ms R %.1f-%.1f ms | release_wait %s",
+            st.frames, st.ipd_min, st.ipd_max, st.rel_rot_max, st.pos_err[0] / l, st.rot_err[0] / l, st.pos_err_max[0],
+            st.rot_err_max[0], st.pos_err[1] / l, st.rot_err[1] / l, st.pos_err_max[1], st.rot_err_max[1], st.located,
+            st.step_max[0], st.step_max[1], st.age_min[0], st.age_max[0], st.age_min[1], st.age_max[1],
+            release_wait_active() ? "on" : "off");
+        memset(&st, 0, sizeof(st));
+    }
+}
@@ -28,21 +28,6 @@ xrAttachSessionActionSets:
    .globl fwd_xrAttachSessionActionSets
    .hidden fwd_xrAttachSessionActionSets
 fwd_xrAttachSessionActionSets:
-    .quad frame_unsupported
-    .text
-    .p2align 2
-    .globl xrBeginFrame
-    .type xrBeginFrame, %function
-xrBeginFrame:
-    adrp x16, fwd_xrBeginFrame
-    ldr x16, [x16, :lo12:fwd_xrBeginFrame]
-    br x16
-    .size xrBeginFrame, .-xrBeginFrame
-    .data
-    .p2align 3
-    .globl fwd_xrBeginFrame
-    .hidden fwd_xrBeginFrame
-fwd_xrBeginFrame:
    .quad frame_unsupported
    .text
    .p2align 2
@@ -403,21 +388,6 @@ xrPathToString:
    .globl fwd_xrPathToString
    .hidden fwd_xrPathToString
 fwd_xrPathToString:
-    .quad frame_unsupported
-    .text
-    .p2align 2
-    .globl xrReleaseSwapchainImage
-    .type xrReleaseSwapchainImage, %function
-xrReleaseSwapchainImage:
-    adrp x16, fwd_xrReleaseSwapchainImage
-    ldr x16, [x16, :lo12:fwd_xrReleaseSwapchainImage]
-    br x16
-    .size xrReleaseSwapchainImage, .-xrReleaseSwapchainImage
-    .data
-    .p2align 3
-    .globl fwd_xrReleaseSwapchainImage
-    .hidden fwd_xrReleaseSwapchainImage
-fwd_xrReleaseSwapchainImage:
    .quad frame_unsupported
    .text
    .p2align 2
@@ -523,20 +493,5 @@ xrSyncActions:
    .globl fwd_xrSyncActions
    .hidden fwd_xrSyncActions
 fwd_xrSyncActions:
-    .quad frame_unsupported
-    .text
-    .p2align 2
-    .globl xrWaitSwapchainImage
-    .type xrWaitSwapchainImage, %function
-xrWaitSwapchainImage:
-    adrp x16, fwd_xrWaitSwapchainImage
-    ldr x16, [x16, :lo12:fwd_xrWaitSwapchainImage]
-    br x16
-    .size xrWaitSwapchainImage, .-xrWaitSwapchainImage
-    .data
-    .p2align 3
-    .globl fwd_xrWaitSwapchainImage
-    .hidden fwd_xrWaitSwapchainImage
-fwd_xrWaitSwapchainImage:
    .quad frame_unsupported
    .section .note.GNU-stack,"",%progbits
@@ -1,7 +1,6 @@
 // Generated from overport 3.4.3 libopenxr_loader_generic.so exports minus hooked functions.
 FORWARD(xrApplyHapticFeedback)
 FORWARD(xrAttachSessionActionSets)
-FORWARD(xrBeginFrame)
 FORWARD(xrBeginSession)
 FORWARD(xrCreateAction)
 FORWARD(xrCreateActionSet)
@@ -26,7 +25,6 @@ FORWARD(xrGetReferenceSpaceBoundsRect)
 FORWARD(xrGetSystem)
 FORWARD(xrGetViewConfigurationProperties)
 FORWARD(xrPathToString)
-FORWARD(xrReleaseSwapchainImage)
 FORWARD(xrRequestExitSession)
 FORWARD(xrResultToString)
 FORWARD(xrStopHapticFeedback)
@@ -34,4 +32,3 @@ FORWARD(xrStringToPath)
 FORWARD(xrStructureTypeToString)
 FORWARD(xrSuggestInteractionProfileBindings)
 FORWARD(xrSyncActions)
-FORWARD(xrWaitSwapchainImage)
@@ -34,23 +34,6 @@ xrAttachSessionActionSets:
    .globl fwd_xrAttachSessionActionSets
    .hidden fwd_xrAttachSessionActionSets
 fwd_xrAttachSessionActionSets:
-    .word frame_unsupported
-    .text
-    .p2align 2
-    .globl xrBeginFrame
-    .type xrBeginFrame, %function
-xrBeginFrame:
-    ldr ip, 1f
-2:  add ip, pc, ip
-    ldr ip, [ip]
-    bx ip
-1:  .word fwd_xrBeginFrame - (2b + 8)
-    .size xrBeginFrame, .-xrBeginFrame
-    .data
-    .p2align 2
-    .globl fwd_xrBeginFrame
-    .hidden fwd_xrBeginFrame
-fwd_xrBeginFrame:
    .word frame_unsupported
    .text
    .p2align 2
@@ -459,23 +442,6 @@ xrPathToString:
    .globl fwd_xrPathToString
    .hidden fwd_xrPathToString
 fwd_xrPathToString:
-    .word frame_unsupported
-    .text
-    .p2align 2
-    .globl xrReleaseSwapchainImage
-    .type xrReleaseSwapchainImage, %function
-xrReleaseSwapchainImage:
-    ldr ip, 1f
-2:  add ip, pc, ip
-    ldr ip, [ip]
-    bx ip
-1:  .word fwd_xrReleaseSwapchainImage - (2b + 8)
-    .size xrReleaseSwapchainImage, .-xrReleaseSwapchainImage
-    .data
-    .p2align 2
-    .globl fwd_xrReleaseSwapchainImage
-    .hidden fwd_xrReleaseSwapchainImage
-fwd_xrReleaseSwapchainImage:
    .word frame_unsupported
    .text
    .p2align 2
@@ -595,22 +561,5 @@ xrSyncActions:
    .globl fwd_xrSyncActions
    .hidden fwd_xrSyncActions
 fwd_xrSyncActions:
-    .word frame_unsupported
-    .text
-    .p2align 2
-    .globl xrWaitSwapchainImage
-    .type xrWaitSwapchainImage, %function
-xrWaitSwapchainImage:
-    ldr ip, 1f
-2:  add ip, pc, ip
-    ldr ip, [ip]
-    bx ip
-1:  .word fwd_xrWaitSwapchainImage - (2b + 8)
-    .size xrWaitSwapchainImage, .-xrWaitSwapchainImage
-    .data
-    .p2align 2
-    .globl fwd_xrWaitSwapchainImage
-    .hidden fwd_xrWaitSwapchainImage
-fwd_xrWaitSwapchainImage:
    .word frame_unsupported
    .section .note.GNU-stack,"",%progbits
@@ -45,17 +45,63 @@
 #include <string.h>

 #define TAG "FrameBridge"
-#define LOG(...) __android_log_print(ANDROID_LOG_INFO, TAG, __VA_ARGS__)
+#include <stdarg.h>
+#include <time.h>
+// Everything also goes to <app external files>/framebridge.log when eye_debug is on: some games end Lepton's logcat
+// mirror early (WiiCompiled), so a headset session's diagnostics would otherwise be lost.
+static FILE *log_file;
+static void fb_log(const char *fmt, ...) __attribute__((format(printf, 1, 2)));
+static void fb_log(const char *fmt, ...) {
+    va_list args;
+    va_start(args, fmt);
+    __android_log_vprint(ANDROID_LOG_INFO, TAG, fmt, args);
+    va_end(args);
+    if (!log_file) return;
+    struct timespec now;
+    clock_gettime(CLOCK_REALTIME, &now);
+    flockfile(log_file);
+    fprintf(log_file, "%lld.%03ld ", (long long)now.tv_sec, now.tv_nsec / 1000000);
+    va_start(args, fmt);
+    vfprintf(log_file, fmt, args);
+    va_end(args);
+    fputc('\n', log_file);
+    fflush(log_file);
+    funlockfile(log_file);
+}
+#define LOG(...) fb_log(__VA_ARGS__)
+#include "audio_metadata.h"

 static void *loader;
 static PFN_xrGetInstanceProcAddr next_gipa;
 static pthread_once_t init_once = PTHREAD_ONCE_INIT;
 static XrInstance active_instance = XR_NULL_HANDLE;
+static void *android_vm;     // JavaVM from XrInstanceCreateInfoAndroidKHR (surface_swapchain.c)
+static int surface_emul = 1;  // setting: emulate Android surface swapchains
+static int eye_debug;          // setting: per-eye diagnostics + file log (eye_debug.c)
+static int release_wait;       // setting: wait for the app's GPU work before releasing images (2 = after 60 s: A/B)
+static void surf_on_destroy(XrSwapchain handle);

 static float scale = 1.0f;
 static int foveation_fix = 1;
+// hide XR_FB_space_warp: games then render every frame themselves (UE5 Application SpaceWarp flickered on the Frame,
+// e.g. Into The Radius 2; OVRPort's patch_disable_space_warp doesn't reach UE5's OpenXR plugin)
+static int hide_space_warp = 0;
+static int strip_color_bias = 0;
+static int snapshot = 0;  // seconds between eye-image snapshots (snapshot_gl.c; 0 = off)
+static char snap_dir[256];
+static void snap_on_create(XrSwapchain handle, const XrSwapchainCreateInfo *info);
+static void snap_on_destroy(XrSwapchain handle);
+static void snap_on_enumerate(XrSwapchain handle, uint32_t count, const XrSwapchainImageBaseHeader *images);
+static void snap_on_acquire(XrSwapchain handle, uint32_t index);
+static void snap_end_frame(const XrFrameEndInfo *info);
+static int frame_balance = 0;  // end a still-open frame before the next xrBeginFrame
+static int frame_begins, frame_discarded, frame_ends, frame_balanced;  // per pacing period (layer_debug)
+static int frame_open;
+static int sc_acquires, sc_waits, sc_releases, sc_wait_fails;  // per pacing period (layer_debug)  // drop XrCompositionLayerColorScaleBiasKHR (the runtime's color pass)
 static int controller_fix = 1;
 static int swapchain_fix = 1;
+static int rect_clamp = 1;
+static int pose_consistency = 0;  // repeat xrLocateViews queries for one display time get the same poses (GitHub #8)  // clamp submitted image rects to their swapchain (SteamVR rejects a 1 px overrun)
 static int layer_fix = 1;
 static int mutable_fix = 0;
 static int swap_eyes = 0;
@@ -80,8 +126,8 @@ static int sync_guard;       // xrSyncActions one at a time with xrPollEvent, pa
 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 stable_local;     // keep every LOCAL space the app creates on the session-start origin
-static int focus_hold;       // hide brief focus dips once the session has been focused for a while
-static float focus_hold_ms = 1000;  // longest focus dip focus_hold hides
+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
 static float aim_pitch, aim_yaw, aim_forward;  // aim pose correction (degrees, degrees, metres)
 static float refresh_rate;   // requested display refresh rate (Hz), 0 = the app's choice
 static int equirect_emul;    // show 360 layers as cube faces (GLES)
@@ -101,8 +147,14 @@ static void read_settings(const char *path) {
    while (fgets(line, sizeof(line), f)) {
        if (sscanf(line, "scale=%f", &value) == 1 && value >= 0.5f && value <= 2.0f) scale = value;
        if (sscanf(line, "foveation_fix=%f", &value) == 1) foveation_fix = value != 0;
+        if (sscanf(line, "hide_space_warp=%f", &value) == 1) hide_space_warp = value != 0;
+        if (sscanf(line, "strip_color_bias=%f", &value) == 1) strip_color_bias = (int)value;
+        if (sscanf(line, "frame_balance=%f", &value) == 1) frame_balance = value != 0;
+        if (sscanf(line, "snapshot=%f", &value) == 1) snapshot = value > 0 ? (int)value : 0;
        if (sscanf(line, "controller_fix=%f", &value) == 1) controller_fix = value != 0;
        if (sscanf(line, "swapchain_fix=%f", &value) == 1) swapchain_fix = value != 0;
+        if (sscanf(line, "rect_clamp=%f", &value) == 1) rect_clamp = value != 0;
+        if (sscanf(line, "pose_consistency=%f", &value) == 1) pose_consistency = value != 0;
        if (sscanf(line, "layer_fix=%f", &value) == 1) layer_fix = value != 0;
        if (sscanf(line, "mutable_fix=%f", &value) == 1) mutable_fix = value != 0;
        if (sscanf(line, "swap_eyes=%f", &value) == 1) swap_eyes = value != 0;
@@ -118,6 +170,9 @@ 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, "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;
        if (sscanf(line, "profile_remap=%f", &value) == 1) profile_remap = value != 0;
        if (sscanf(line, "sync_guard=%f", &value) == 1) sync_guard = value != 0;
        if (sscanf(line, "stable_local=%f", &value) == 1) stable_local = value != 0;
@@ -169,6 +224,19 @@ static void initialize(void) {
    }
    const char *env = getenv("FRAMEBRIDGE_CONFIG");
    if (env && *env) read_settings(env);
+    if (snapshot && *process && !strchr(process, '/')) {
+        snprintf(snap_dir, sizeof(snap_dir), "/sdcard/Android/data/%s/files", process);
+        LOG("per-game: snapshot every %d s to %s/fb_snap_N.ppm", snapshot, snap_dir);
+    }
+    if (eye_debug && *process && !strchr(process, '/')) {
+        snprintf(path, sizeof(path), "/sdcard/Android/data/%s/files/framebridge.log", process);
+        log_file = fopen(path, "a");
+    }
+    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)");
+    if (eye_debug || release_wait) LOG("per-game: eye_debug=%d release_wait=%d log_file=%s", eye_debug, release_wait,
+                                       log_file ? path : "none");
    if (controller_models && *process && !strchr(process, '/')) render_model_init(process);

    LOG("scale=%.2f foveation_fix=%d controller_fix=%d swapchain_fix=%d layer_fix=%d mutable_fix=%d swap_eyes=%d passthrough_emul=%d respace_kick=%d flip_quads=%d controller_models=%d loader=%s",
@@ -199,7 +267,10 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info

    int chained = 0, enabled = 0;
    for (const XrBaseInStructure *p = (const XrBaseInStructure *)info->next; p; p = p->next)
-        if (p->type == XR_TYPE_INSTANCE_CREATE_INFO_ANDROID_KHR) chained = 1;
+        if (p->type == XR_TYPE_INSTANCE_CREATE_INFO_ANDROID_KHR) {
+            chained = 1;
+            android_vm = ((const struct { XrStructureType type; const void *next; void *vm; void *activity; } *)p)->vm;
+        }
    for (uint32_t i = 0; i < info->enabledExtensionCount; ++i)
        if (!strcmp(info->enabledExtensionNames[i], "XR_KHR_android_create_instance")) enabled = 1;

@@ -229,6 +300,10 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
        int supported = !available;  // if we could not enumerate, pass everything through
        for (uint32_t j = 0; available && j < available_count && !supported; ++j)
            supported = !strcmp(available[j].extensionName, ext);
+        if (hide_space_warp && !strcmp(ext, "XR_FB_space_warp")) {
+            LOG("hide_space_warp: XR_FB_space_warp not enabled");
+            continue;
+        }
        if (supported) names[kept++] = ext;
        else if (scene_emul && is_scene_extension(ext)) {
            if (!emulate_scene) LOG("emulating Meta scene/spatial-entity extensions from the guardian bounds");
@@ -265,10 +340,11 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
    }
    no_equirect = !has_equirect; no_equirect2 = !has_equirect2; no_cylinder = !has_cylinder; no_cube = !has_cube;
    free(available);
+    mx_audio_initialize();
    XrResult result = fn(&fixed, instance);
    free(names);
    LOG("xrCreateInstance result=%d", result);
-    if (XR_SUCCEEDED(result)) active_instance = *instance;
+    if (XR_SUCCEEDED(result)) { active_instance = *instance; mx_audio_initialize(); }
    return result;
 }

@@ -339,6 +415,45 @@ static void remember_swapchain(XrSwapchain handle) {
    pthread_mutex_unlock(&swapchains_lock);
 }

+// Swapchain sizes, to keep submitted image rects inside them (rect_clamp).
+#define MAX_SIZES 256
+static struct { XrSwapchain handle; uint32_t w, h; } sizes[MAX_SIZES];
+static pthread_mutex_t sizes_lock = PTHREAD_MUTEX_INITIALIZER;
+
+static void note_swapchain_size(XrSwapchain handle, uint32_t w, uint32_t h) {
+    pthread_mutex_lock(&sizes_lock);
+    int slot = -1;
+    for (int i = 0; i < MAX_SIZES; ++i) {
+        if (sizes[i].handle == handle) { slot = i; break; }
+        if (slot < 0 && sizes[i].handle == XR_NULL_HANDLE) slot = i;
+    }
+    if (slot >= 0) { sizes[slot].handle = handle; sizes[slot].w = w; sizes[slot].h = h; }
+    pthread_mutex_unlock(&sizes_lock);
+}
+
+static int swapchain_size(XrSwapchain handle, uint32_t *w, uint32_t *h) {
+    int found = 0;
+    pthread_mutex_lock(&sizes_lock);
+    for (int i = 0; i < MAX_SIZES && !found; ++i)
+        if (sizes[i].handle == handle && handle != XR_NULL_HANDLE) { *w = sizes[i].w; *h = sizes[i].h; found = 1; }
+    pthread_mutex_unlock(&sizes_lock);
+    return found;
+}
+
+// Clamp `r` to a w x h image; returns whether it changed.
+static int clamp_rect(XrRect2Di *r, uint32_t w, uint32_t h) {
+    XrRect2Di c = *r;
+    if (c.offset.x < 0) { c.extent.width += c.offset.x; c.offset.x = 0; }
+    if (c.offset.y < 0) { c.extent.height += c.offset.y; c.offset.y = 0; }
+    if ((uint32_t)c.offset.x >= w || (uint32_t)c.offset.y >= h) return 0;  // nothing sensible to keep: leave it
+    if ((int64_t)c.offset.x + c.extent.width > (int64_t)w) c.extent.width = (int32_t)(w - (uint32_t)c.offset.x);
+    if ((int64_t)c.offset.y + c.extent.height > (int64_t)h) c.extent.height = (int32_t)(h - (uint32_t)c.offset.y);
+    if (c.extent.width <= 0 || c.extent.height <= 0) return 0;
+    int changed = memcmp(&c, r, sizeof c) != 0;
+    *r = c;
+    return changed;
+}
+
 static void forget_swapchain(XrSwapchain handle) {
    pthread_mutex_lock(&swapchains_lock);
    for (size_t i = 0; i < swapchain_count; ++i)
@@ -380,6 +495,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
    if (equirect_emul && swapchain && emul_virtual_create(session, &fixed, swapchain)) {
        remember_swapchain(*swapchain);
        emul_on_create_swapchain(*swapchain, &fixed);
+        snap_on_create(*swapchain, &fixed);
        return XR_SUCCESS;
    }
    XrResult result = fn(session, &fixed, swapchain);
@@ -388,8 +504,10 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
        (unsigned long long)fixed.usageFlags, (unsigned long long)fixed.createFlags, result);
    if (XR_SUCCEEDED(result)) {
        remember_swapchain(*swapchain);
+        note_swapchain_size(*swapchain, fixed.width, fixed.height);
        flip_on_create_swapchain(*swapchain, &fixed);
        emul_on_create_swapchain(*swapchain, &fixed);
+        snap_on_create(*swapchain, &fixed);
        return result;
    }
    if (!swapchain_fix) return result;
@@ -410,8 +528,10 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
    }
    if (XR_SUCCEEDED(result)) {
        remember_swapchain(*swapchain);
+        note_swapchain_size(*swapchain, fixed.width, fixed.height);
        flip_on_create_swapchain(*swapchain, &fixed);
        emul_on_create_swapchain(*swapchain, &fixed);
+        snap_on_create(*swapchain, &fixed);
    }
    return result;
 }
@@ -419,9 +539,15 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
 XRAPI_ATTR XrResult XRAPI_CALL xrDestroySwapchain(XrSwapchain swapchain) {
    PFN_xrDestroySwapchain fn = (PFN_xrDestroySwapchain)lookup(active_instance, "xrDestroySwapchain");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (layer_debug) {
+        static int logged;
+        if (logged++ < 200) LOG("layer_debug: xrDestroySwapchain %p", (void *)swapchain);
+    }
    forget_swapchain(swapchain);
+    surf_on_destroy(swapchain);
    flip_on_destroy(swapchain);
    emul_on_destroy_swapchain(swapchain);
+    snap_on_destroy(swapchain);
    if (equirect_emul && emul_is_virtual(swapchain)) { emul_virtual_destroy(swapchain); return XR_SUCCESS; }
    return fn(swapchain);
 }
@@ -673,6 +799,9 @@ XRAPI_ATTR XrResult XRAPI_CALL xrDestroySpace(XrSpace space) {

 #include "session_fixes.c"
 #include "layer_emul_gl.c"
+#include "snapshot_gl.c"
+#include "surface_swapchain.c"
+#include "eye_debug.c"

 XRAPI_ATTR XrResult XRAPI_CALL xrCreateSession(XrInstance instance, const XrSessionCreateInfo *info, XrSession *session) {
    PFN_xrCreateSession fn = (PFN_xrCreateSession)lookup(instance, "xrCreateSession");
@@ -697,10 +826,28 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateSwapchainImages(XrSwapchain swapchain,
    if (XR_SUCCEEDED(result) && images && capacity && count) {
        flip_on_enumerate_images(swapchain, *count, images);
        emul_on_enumerate(swapchain, *count < capacity ? *count : capacity, images);
+        snap_on_enumerate(swapchain, *count < capacity ? *count : capacity, images);
    }
    return result;
 }

+// counted for layer_debug (an app that skips the wait or release keeps runtime resources alive)
+XRAPI_ATTR XrResult XRAPI_CALL xrWaitSwapchainImage(XrSwapchain swapchain, const XrSwapchainImageWaitInfo *info) {
+    PFN_xrWaitSwapchainImage fn = (PFN_xrWaitSwapchainImage)lookup(active_instance, "xrWaitSwapchainImage");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    XrResult result = fn(swapchain, info);
+    __atomic_add_fetch(&sc_waits, 1, __ATOMIC_RELAXED);
+    if (result != XR_SUCCESS) __atomic_add_fetch(&sc_wait_fails, 1, __ATOMIC_RELAXED);
+    return result;
+}
+
+XRAPI_ATTR XrResult XRAPI_CALL xrReleaseSwapchainImage(XrSwapchain swapchain, const XrSwapchainImageReleaseInfo *info) {
+    PFN_xrReleaseSwapchainImage fn = (PFN_xrReleaseSwapchainImage)lookup(active_instance, "xrReleaseSwapchainImage");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    __atomic_add_fetch(&sc_releases, 1, __ATOMIC_RELAXED);
+    return fn(swapchain, info);
+}
+
 XRAPI_ATTR XrResult XRAPI_CALL xrAcquireSwapchainImage(XrSwapchain swapchain, const XrSwapchainImageAcquireInfo *info,
        uint32_t *index) {
    PFN_xrAcquireSwapchainImage fn = (PFN_xrAcquireSwapchainImage)lookup(active_instance, "xrAcquireSwapchainImage");
@@ -712,7 +859,12 @@ XRAPI_ATTR XrResult XRAPI_CALL xrAcquireSwapchainImage(XrSwapchain swapchain, co
        return XR_SUCCESS;
    }
    XrResult result = fn(swapchain, info, index);
-    if (XR_SUCCEEDED(result) && index) { flip_on_acquire(swapchain, *index); emul_on_acquire(swapchain, *index); }
+    __atomic_add_fetch(&sc_acquires, 1, __ATOMIC_RELAXED);
+    if (XR_SUCCEEDED(result) && index) {
+        flip_on_acquire(swapchain, *index);
+        emul_on_acquire(swapchain, *index);
+        snap_on_acquire(swapchain, *index);
+    }
    return result;
 }

@@ -726,6 +878,7 @@ static XrSession focused_session = XR_NULL_HANDLE;
 static int kicks_pending = -1;  // -1: not yet armed

 XRAPI_ATTR XrResult XRAPI_CALL xrPollEvent(XrInstance instance, XrEventDataBuffer *event) {
+    mx_audio_initialize();
    PFN_xrPollEvent fn = (PFN_xrPollEvent)lookup(instance, "xrPollEvent");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
    if (emulate_scene && event) {
@@ -814,11 +967,69 @@ XRAPI_ATTR XrResult XRAPI_CALL xrWaitFrame(XrSession session, const XrFrameWaitI
    return result;
 }

+// pose_consistency (GitHub #8, proposed by Klownicle for I Am Cat): the game asks xrLocateViews ~3 times per frame
+// for the same display time and got slightly different poses each time (tenths of a degree), so parts of its pipeline
+// rendered with different heads: judder. The first fully tracked answer for (session, space, view configuration,
+// display time) is kept and repeated; a new display time, another space or a failed/untracked answer is never cached.
+#define POSE_CACHE 8
+static struct {
+    XrSession session; XrSpace space; XrViewConfigurationType config; XrTime time;
+    XrViewStateFlags flags; uint32_t count; XrPosef pose[2]; XrFovf fov[2];
+} pose_cache[POSE_CACHE];
+static int pose_cache_next, pose_cache_hits;
+static pthread_mutex_t pose_cache_lock = PTHREAD_MUTEX_INITIALIZER;
+#define POSE_TRACKED (XR_VIEW_STATE_ORIENTATION_VALID_BIT | XR_VIEW_STATE_POSITION_VALID_BIT | \
+                      XR_VIEW_STATE_ORIENTATION_TRACKED_BIT | XR_VIEW_STATE_POSITION_TRACKED_BIT)
+
+static int pose_cache_lookup(XrSession session, const XrViewLocateInfo *info, XrViewState *state, uint32_t capacity,
+                             uint32_t *count, XrView *views) {
+    int hit = 0;
+    pthread_mutex_lock(&pose_cache_lock);
+    for (int i = 0; i < POSE_CACHE && !hit; ++i) {
+        if (pose_cache[i].session != session || pose_cache[i].space != info->space ||
+            pose_cache[i].config != info->viewConfigurationType || pose_cache[i].time != info->displayTime ||
+            !pose_cache[i].count || capacity < pose_cache[i].count)
+            continue;
+        state->viewStateFlags = pose_cache[i].flags;
+        *count = pose_cache[i].count;
+        for (uint32_t v = 0; v < pose_cache[i].count; ++v) {  // only the values: the caller's type/next stay
+            views[v].pose = pose_cache[i].pose[v];
+            views[v].fov = pose_cache[i].fov[v];
+        }
+        hit = 1;
+    }
+    if (hit && pose_cache_hits++ == 0) LOG("pose_consistency: repeated query answered with the frame's first poses");
+    pthread_mutex_unlock(&pose_cache_lock);
+    return hit;
+}
+
+static void pose_cache_store(XrSession session, const XrViewLocateInfo *info, const XrViewState *state,
+                             uint32_t count, const XrView *views) {
+    if (count == 0 || count > 2 || (state->viewStateFlags & POSE_TRACKED) != POSE_TRACKED) return;
+    pthread_mutex_lock(&pose_cache_lock);
+    int slot = pose_cache_next;
+    pose_cache_next = (pose_cache_next + 1) % POSE_CACHE;
+    pose_cache[slot].session = session;
+    pose_cache[slot].space = info->space;
+    pose_cache[slot].config = info->viewConfigurationType;
+    pose_cache[slot].time = info->displayTime;
+    pose_cache[slot].flags = state->viewStateFlags;
+    pose_cache[slot].count = count;
+    for (uint32_t v = 0; v < count; ++v) {
+        pose_cache[slot].pose[v] = views[v].pose;
+        pose_cache[slot].fov[v] = views[v].fov;
+    }
+    pthread_mutex_unlock(&pose_cache_lock);
+}
+
 XRAPI_ATTR XrResult XRAPI_CALL xrLocateViews(XrSession session, const XrViewLocateInfo *info, XrViewState *state,
        uint32_t capacity, uint32_t *count, XrView *views) {
    PFN_xrLocateViews fn = (PFN_xrLocateViews)lookup(active_instance, "xrLocateViews");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    int cacheable = pose_consistency && info && state && count && views && capacity > 0;
+    if (cacheable && pose_cache_lookup(session, info, state, capacity, count, views)) return XR_SUCCESS;
    XrResult result = fn(session, info, state, capacity, count, views);
+    if (cacheable && result == XR_SUCCESS) pose_cache_store(session, info, state, *count, views);
    if (equirect_emul && XR_SUCCEEDED(result) && info && count && views && state &&
        (state->viewStateFlags & XR_VIEW_STATE_ORIENTATION_VALID_BIT))
        emul_on_locate_views(info->space, info->displayTime, *count < capacity ? *count : capacity, views);
@@ -861,9 +1072,41 @@ XRAPI_ATTR XrResult XRAPI_CALL xrLocateViews(XrSession session, const XrViewLoca
    return result;
 }

+// xrBeginFrame: counted for layer_debug. A game that begins a new frame while the previous one is still open
+// (never ended) makes the runtime discard it; the Frame's runtime then never recycles that frame's GPU timing
+// command buffer (Vader Immortal: ~430 GPU mappings / 20 MB a second). frame_balance ends the open frame first,
+// with no layers, as the runtime expects.
+static XrTime last_begin_display_time;
+XRAPI_ATTR XrResult XRAPI_CALL xrBeginFrame(XrSession session, const XrFrameBeginInfo *info) {
+    PFN_xrBeginFrame fn = (PFN_xrBeginFrame)lookup(active_instance, "xrBeginFrame");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (frame_open && frame_balance) {
+        PFN_xrEndFrame end = (PFN_xrEndFrame)lookup(active_instance, "xrEndFrame");
+        XrFrameEndInfo empty = {XR_TYPE_FRAME_END_INFO, NULL, last_begin_display_time ? last_begin_display_time
+                                                                                        : last_predicted_time,
+                                XR_ENVIRONMENT_BLEND_MODE_OPAQUE, 0, NULL};
+        XrResult r = end ? end(session, &empty) : XR_ERROR_FUNCTION_UNSUPPORTED;
+        static int logged;
+        if (logged++ < 3) LOG("frame_balance: ended an open frame before xrBeginFrame (result %d)", r);
+        __atomic_add_fetch(&frame_balanced, 1, __ATOMIC_RELAXED);
+    }
+    XrResult result = fn(session, info);
+    __atomic_add_fetch(&frame_begins, 1, __ATOMIC_RELAXED);
+    if (result == XR_FRAME_DISCARDED) __atomic_add_fetch(&frame_discarded, 1, __ATOMIC_RELAXED);
+    if (XR_SUCCEEDED(result)) {
+        frame_open = 1;
+        last_begin_display_time = last_predicted_time;
+    }
+    return result;
+}
+
 XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInfo *info) {
    PFN_xrEndFrame fn = (PFN_xrEndFrame)lookup(active_instance, "xrEndFrame");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    frame_open = 0;
+    __atomic_add_fetch(&frame_ends, 1, __ATOMIC_RELAXED);
+    snap_end_frame(info);
+    if (eye_debug) eye_debug_end_frame(session, info);
    {   // frame pacing statistics every ~5 s: fps and submitted-vs-predicted display time
        static struct timespec start;
        static int frames;
@@ -879,6 +1122,18 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
        if (elapsed >= 5.0) {
            LOG("pacing: %.1f fps, displayTime vs predicted: avg %.2f ms, max %.2f ms", frames / elapsed,
                drift_sum / (double)frames / 1e6, drift_max / 1e6);
+            if (layer_debug)
+                LOG("layer_debug: swapchain images: %d acquired, %d waited (%d not ok), %d released",
+                    __atomic_exchange_n(&sc_acquires, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&sc_waits, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&sc_wait_fails, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&sc_releases, 0, __ATOMIC_RELAXED));
+            if (layer_debug)
+                LOG("layer_debug: frames: %d xrBeginFrame (%d discarded), %d xrEndFrame, %d balanced",
+                    __atomic_exchange_n(&frame_begins, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&frame_discarded, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&frame_ends, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&frame_balanced, 0, __ATOMIC_RELAXED));
            if (layer_debug)
                LOG("layer_debug: input: %d xrSyncActions (%d ok, last %d), %d bool reads, %d pressed",
                    __atomic_exchange_n(&input_syncs, 0, __ATOMIC_RELAXED),
@@ -969,6 +1224,13 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
                continue;
            }
        }
+        if (layer && (layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD || layer->type == XR_TYPE_COMPOSITION_LAYER_CYLINDER_KHR) &&
+            !surf_prepare_layer(layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD
+                                    ? ((const XrCompositionLayerQuad *)layer)->subImage.swapchain
+                                    : ((const XrCompositionLayerCylinderKHR *)layer)->subImage.swapchain)) {
+            ++dropped;  // an emulated video surface without a frame yet
+            continue;
+        }
        if (!layer || (layer_fix && !layer_usable(layer))) { ++dropped; continue; }
        if (layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD) {
            const XrCompositionLayerQuad *flipped = flip_quad(session, (const XrCompositionLayerQuad *)layer, &quads[count]);
@@ -1005,6 +1267,73 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
            if (!logged++) LOG("strip_depth: removed depth info from projection layer");
            ++swapped;
        }
+        {
+            // XR_KHR_composition_layer_color_scale_bias (1000034000) on the layer itself: logged when its values
+            // change (layer_debug); with strip_color_bias the runtime never gets it (Vader Immortal: the Frame's
+            // runtime allocates GPU memory for it every frame and never frees it)
+            const XrBaseInStructure *head = (const XrBaseInStructure *)layer->next;
+            const XrCompositionLayerColorScaleBiasKHR *cb = NULL;
+            for (const XrBaseInStructure *n = head; n; n = n->next)
+                if (n->type == XR_TYPE_COMPOSITION_LAYER_COLOR_SCALE_BIAS_KHR) cb = (const XrCompositionLayerColorScaleBiasKHR *)n;
+            if (cb && layer_debug) {
+                static float last[8] = {-1};
+                float now[8] = {cb->colorScale.r, cb->colorScale.g, cb->colorScale.b, cb->colorScale.a,
+                                cb->colorBias.r, cb->colorBias.g, cb->colorBias.b, cb->colorBias.a};
+                static int logged;
+                if (memcmp(now, last, sizeof(now)) && logged++ < 100) {
+                    LOG("layer_debug: layer type=%d color scale %.2f %.2f %.2f %.2f bias %.2f %.2f %.2f %.2f", layer->type,
+                        now[0], now[1], now[2], now[3], now[4], now[5], now[6], now[7]);
+                    memcpy(last, now, sizeof(now));
+                }
+            }
+            if (cb && strip_color_bias && (layer->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION ||
+                                           layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD)) {
+                const XrBaseInStructure *rest = head;  // skip leading color structs; one further down drops the chain
+                while (rest && rest->type == XR_TYPE_COMPOSITION_LAYER_COLOR_SCALE_BIAS_KHR) rest = rest->next;
+                for (const XrBaseInStructure *n = rest; n; n = n->next)
+                    if (n->type == XR_TYPE_COMPOSITION_LAYER_COLOR_SCALE_BIAS_KHR) rest = NULL;
+                if (strip_color_bias > 1) rest = NULL;  // 2: the layer's whole extension chain (diagnostics)
+                if (layer->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION) {
+                    if (layer != (const XrCompositionLayerBaseHeader *)&projections[count])
+                        projections[count] = *(const XrCompositionLayerProjection *)layer;
+                    projections[count].next = rest;
+                    layer = (const XrCompositionLayerBaseHeader *)&projections[count];
+                } else {
+                    if (layer != (const XrCompositionLayerBaseHeader *)&quads[count])
+                        quads[count] = *(const XrCompositionLayerQuad *)layer;
+                    quads[count].next = rest;
+                    layer = (const XrCompositionLayerBaseHeader *)&quads[count];
+                }
+                static int logged;
+                if (!logged++) LOG("strip_color_bias: removed the color scale/bias from a layer");
+                ++swapped;
+            }
+        }
+        if (hide_space_warp && layer->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
+            ((const XrCompositionLayerProjection *)layer)->viewCount == 2) {
+            // The game may still attach XrCompositionLayerSpaceWarpInfoFB (1000171000) to its views: OVRPort's
+            // dispatcher offers XR_FB_space_warp itself even when hidden here. Unlink it (keeping what follows when
+            // it heads the chain, else the whole chain) so the runtime never uses the motion vectors.
+            const XrCompositionLayerProjection *src = (const XrCompositionLayerProjection *)layer;
+            int found = 0;
+            for (uint32_t v = 0; v < 2; ++v)
+                for (const XrBaseInStructure *n = (const XrBaseInStructure *)src->views[v].next; n; n = n->next)
+                    found |= n->type == 1000171000;
+            if (found) {
+                if (layer != (const XrCompositionLayerBaseHeader *)&projections[count]) projections[count] = *src;
+                for (uint32_t v = 0; v < 2; ++v) {
+                    views[count][v] = src->views[v];
+                    const XrBaseInStructure *head = (const XrBaseInStructure *)src->views[v].next;
+                    if (head && head->type == 1000171000) views[count][v].next = head->next;
+                    else if (head) views[count][v].next = NULL;
+                }
+                projections[count].views = views[count];
+                layer = (const XrCompositionLayerBaseHeader *)&projections[count];
+                static int logged;
+                if (!logged++) LOG("hide_space_warp: removed space warp info from the eye images");
+                ++swapped;
+            }
+        }
        if (swap_eyes && layer->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
            ((const XrCompositionLayerProjection *)layer)->viewCount == 2) {
            // Show each eye the image the game rendered for it: keep poses/FOVs, swap sub-images.
@@ -1022,6 +1351,51 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
            layer = (const XrCompositionLayerBaseHeader *)&projections[count];
            ++swapped;
        }
+        if (rect_clamp) {
+            // Keep every image rect inside its swapchain: Unity/OVRPlugin can size the eye area a few pixels past
+            // the image on some Frames (PowerWash Simulator: rect 268+1656 on a 1920 wide swapchain) and SteamVR
+            // then rejects every frame with XR_ERROR_SWAPCHAIN_RECT_INVALID (-25) (GitHub #39).
+            uint32_t w, h;
+            if (layer->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
+                ((const XrCompositionLayerProjection *)layer)->viewCount <= 2) {
+                const XrCompositionLayerProjection *cur = (const XrCompositionLayerProjection *)layer;
+                int over = 0;
+                for (uint32_t v = 0; v < cur->viewCount; ++v) {
+                    XrRect2Di r = cur->views[v].subImage.imageRect;
+                    if (swapchain_size(cur->views[v].subImage.swapchain, &w, &h) && clamp_rect(&r, w, h)) over = 1;
+                }
+                if (over) {
+                    if (layer != (const XrCompositionLayerBaseHeader *)&projections[count]) projections[count] = *cur;
+                    if (projections[count].views != views[count])
+                        for (uint32_t v = 0; v < cur->viewCount; ++v) views[count][v] = cur->views[v];
+                    for (uint32_t v = 0; v < cur->viewCount; ++v)
+                        if (swapchain_size(views[count][v].subImage.swapchain, &w, &h) &&
+                            clamp_rect(&views[count][v].subImage.imageRect, w, h)) {
+                            static int logged;
+                            if (logged++ < 3)
+                                LOG("rect_clamp: view %u image rect clamped to %dx%d at %d,%d (swapchain %ux%u)", v,
+                                    views[count][v].subImage.imageRect.extent.width,
+                                    views[count][v].subImage.imageRect.extent.height,
+                                    views[count][v].subImage.imageRect.offset.x,
+                                    views[count][v].subImage.imageRect.offset.y, w, h);
+                        }
+                    projections[count].views = views[count];
+                    layer = (const XrCompositionLayerBaseHeader *)&projections[count];
+                    ++swapped;
+                }
+            } else if (layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD) {
+                const XrCompositionLayerQuad *q = (const XrCompositionLayerQuad *)layer;
+                XrRect2Di r = q->subImage.imageRect;
+                if (swapchain_size(q->subImage.swapchain, &w, &h) && clamp_rect(&r, w, h)) {
+                    if (layer != (const XrCompositionLayerBaseHeader *)&quads[count]) quads[count] = *q;
+                    quads[count].subImage.imageRect = r;
+                    layer = (const XrCompositionLayerBaseHeader *)&quads[count];
+                    ++swapped;
+                    static int logged;
+                    if (!logged++) LOG("rect_clamp: quad image rect clamped (swapchain %ux%u)", w, h);
+                }
+            }
+        }
        kept[count++] = layer;
    }
    XrFrameEndInfo fixed = *info;
@@ -1128,7 +1502,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateInstanceExtensionProperties(const char
        XR_NULL_HANDLE, "xrEnumerateInstanceExtensionProperties");
    if (!fn) return XR_ERROR_INITIALIZATION_FAILED;
    if (!count) return XR_ERROR_VALIDATION_FAILURE;
-    if ((!foveation_fix && !passthrough_emul && !scene_emul && !controller_models) || layer)
+    if ((!foveation_fix && !hide_space_warp && !passthrough_emul && !scene_emul && !controller_models) || layer)
        return fn(layer, capacity, count, properties);

    uint32_t total = 0;
@@ -1145,6 +1519,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateInstanceExtensionProperties(const char
        if (!strcmp(all[i].extensionName, "XR_FB_passthrough")) runtime_has_fb_passthrough = 1;
        if (!strcmp(all[i].extensionName, XR_FB_RENDER_MODEL_EXTENSION_NAME)) runtime_has_render_model = 1;
        if (foveation_fix && strstr(all[i].extensionName, "foveation")) continue;
+        if (hide_space_warp && !strcmp(all[i].extensionName, "XR_FB_space_warp")) continue;
        if (properties && kept < capacity) properties[kept] = all[i];
        ++kept;
    }
@@ -1227,6 +1602,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
    HOOK(xrCreateSwapchain)
    HOOK(xrDestroySwapchain)
    HOOK(xrEndFrame)
+    HOOK(xrBeginFrame)
    HOOK(xrLocateHandJointsEXT)
    HOOK(xrGetCurrentInteractionProfile)
    HOOK(xrEnumerateInstanceExtensionProperties)
@@ -1241,6 +1617,12 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
    if (layer_debug || refresh_rate > 0) {
        HOOK_AS(xrRequestDisplayRefreshRateFB, hook_request_refresh_rate)
    }
+    if (surface_emul) HOOK_AS(xrCreateSwapchainAndroidSurfaceKHR, hook_xrCreateSwapchainAndroidSurfaceKHR)
+    if (eye_debug || release_wait) HOOK_AS(xrReleaseSwapchainImage, eye_hook_xrReleaseSwapchainImage)
+    if (layer_debug) {  // counters only; every other wait/release hook above takes precedence
+        HOOK(xrWaitSwapchainImage)
+        HOOK(xrReleaseSwapchainImage)
+    }
    if (sync_guard || layer_debug) HOOK_AS(xrSyncActions, hook_xrSyncActions)
    if (layer_debug) HOOK_AS(xrGetActionStateBoolean, hook_xrGetActionStateBoolean)
    if (layer_debug || aim_correction_on() || profile_remap)
@@ -140,7 +140,7 @@ static XRAPI_ATTR XrResult XRAPI_CALL hook_xrGetActionStateBoolean(XrSession ses
 // ---------------------------------------------------------------- focus_hold
 #define FOCUS_HOLD_MIN_FOCUSED_NS 1000000000ll  // only after this long in FOCUSED (start-up transitions untouched;
                                                // 3 s let a 27 ms dip through in Blade & Sorcery)
-// dips longer than focus_hold_ms (setting, default 1000) are delivered (late, in order): taking the headset off or the
+// dips longer than focus_hold_ms (setting, default 5000) are delivered (late, in order): taking the headset off or the
 // system menu must still pause the game. A longer limit is for headsets whose wear sensor flickers ("HMD off" for
 // 0.5-2 s while worn; Blade & Sorcery pauses on each)
 #define FOCUS_HOLD_MAX_DIP_NS ((int64_t)(focus_hold_ms * 1000000.0f))
@@ -0,0 +1,173 @@
+// FramePort FrameBridge: eye-image snapshots for headless diagnostics (setting snapshot=<seconds>, GLES games only).
+// Every <seconds>, at xrEndFrame, the left-eye image the game just submitted (projection layer, view 0: its swapchain
+// image and array layer) is read back on the game's own GL context and written at a quarter of its size as
+// /sdcard/Android/data/<package>/files/fb_snap_<n>.ppm (n = 0-7, the oldest is overwritten). Nobody wears the headset
+// in a launch test, so the headset view stays black: this shows what the game itself draws (e.g. which screen it is
+// stuck on). The game's framebuffer, pack-buffer and pack-alignment bindings are restored afterwards.
+#define SNAP_MAX_SWAPCHAINS 16
+#define SNAP_MAX_IMAGES 8
+#define SNAP_SCALE 4
+
+
+#define SNAP_GL_FUNCS(X) X(glGenFramebuffers) X(glDeleteFramebuffers) X(glBindFramebuffer) X(glFramebufferTexture2D) \
+    X(glFramebufferTextureLayer) X(glCheckFramebufferStatus) X(glReadPixels) X(glGetIntegerv) X(glPixelStorei) \
+    X(glBindBuffer) X(glGetError)
+#define SNAP_DECLARE(fn) static __typeof__(&fn) s_##fn;
+SNAP_GL_FUNCS(SNAP_DECLARE)
+#undef SNAP_DECLARE
+static EGLContext (*s_eglGetCurrentContext)(void);
+
+static struct {
+    XrSwapchain handle;
+    uint32_t width, height, array_size, count, last_acquired;
+    GLuint images[SNAP_MAX_IMAGES];
+} snap_chains[SNAP_MAX_SWAPCHAINS];
+static pthread_mutex_t snap_lock = PTHREAD_MUTEX_INITIALIZER;
+
+static int snap_load_gl(void) {
+    static int state;  // 0 untried, 1 ok, -1 failed
+    if (state) return state > 0;
+    void *egl = dlopen("libEGL.so", RTLD_NOW | RTLD_LOCAL), *gles = dlopen("libGLESv3.so", RTLD_NOW | RTLD_LOCAL);
+    int ok = egl && gles;
+    if (ok) s_eglGetCurrentContext = (EGLContext (*)(void))dlsym(egl, "eglGetCurrentContext");
+#define SNAP_RESOLVE(fn) ok &= gles && (s_##fn = (__typeof__(s_##fn))dlsym(gles, #fn)) != NULL;
+    SNAP_GL_FUNCS(SNAP_RESOLVE)
+#undef SNAP_RESOLVE
+    state = ok && s_eglGetCurrentContext ? 1 : -1;
+    if (state < 0) LOG("snapshot: OpenGL ES not available, no snapshots");
+    return state > 0;
+}
+
+static int snap_find(XrSwapchain handle, int create) {
+    for (int i = 0; i < SNAP_MAX_SWAPCHAINS; ++i)
+        if (snap_chains[i].handle == handle) return i;
+    if (!create) return -1;
+    for (int i = 0; i < SNAP_MAX_SWAPCHAINS; ++i)
+        if (!snap_chains[i].handle) { snap_chains[i].handle = handle; snap_chains[i].count = 0; return i; }
+    return -1;
+}
+
+static void snap_on_create(XrSwapchain handle, const XrSwapchainCreateInfo *info) {
+    if (!snapshot || !info) return;
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(handle, 1);
+    if (i >= 0) {
+        snap_chains[i].width = info->width;
+        snap_chains[i].height = info->height;
+        snap_chains[i].array_size = info->arraySize ? info->arraySize : 1;
+    }
+    pthread_mutex_unlock(&snap_lock);
+}
+
+static void snap_on_destroy(XrSwapchain handle) {
+    if (!snapshot) return;
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(handle, 0);
+    if (i >= 0) snap_chains[i].handle = XR_NULL_HANDLE;
+    pthread_mutex_unlock(&snap_lock);
+}
+
+static void snap_on_enumerate(XrSwapchain handle, uint32_t count, const XrSwapchainImageBaseHeader *images) {
+    if (!snapshot || !images || !count || images->type != (XrStructureType)1000024002) return;  // OPENGL_ES_KHR
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(handle, 1);
+    if (i >= 0) {
+        uint32_t n = count < SNAP_MAX_IMAGES ? count : SNAP_MAX_IMAGES;
+        const emul_gles_image *gl = (const emul_gles_image *)images;
+        for (uint32_t k = 0; k < n; ++k) snap_chains[i].images[k] = gl[k].image;
+        snap_chains[i].count = n;
+    }
+    pthread_mutex_unlock(&snap_lock);
+}
+
+static void snap_on_acquire(XrSwapchain handle, uint32_t index) {
+    if (!snapshot) return;
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(handle, 0);
+    if (i >= 0) snap_chains[i].last_acquired = index;
+    pthread_mutex_unlock(&snap_lock);
+}
+
+static void snap_write(const unsigned char *rgba, uint32_t w, uint32_t h, int n) {
+    char path[320];
+    snprintf(path, sizeof(path), "%s/fb_snap_%d.ppm", snap_dir, n);
+    FILE *f = fopen(path, "wb");
+    if (!f) { LOG("snapshot: can't write %s", path); return; }
+    uint32_t ow = w / SNAP_SCALE, oh = h / SNAP_SCALE;
+    fprintf(f, "P6\n%u %u\n255\n", ow, oh);
+    unsigned char *row = malloc((size_t)ow * 3);
+    for (uint32_t y = 0; row && y < oh; ++y) {
+        const unsigned char *src = rgba + (size_t)(h - 1 - y * SNAP_SCALE) * w * 4;  // GL rows are bottom-up
+        for (uint32_t x = 0; x < ow; ++x) {
+            const unsigned char *p = src + (size_t)x * SNAP_SCALE * 4;
+            row[x * 3] = p[0], row[x * 3 + 1] = p[1], row[x * 3 + 2] = p[2];
+        }
+        fwrite(row, 1, (size_t)ow * 3, f);
+    }
+    free(row);
+    fclose(f);
+    LOG("snapshot: %s (%ux%u)", path, ow, oh);
+}
+
+static void snap_end_frame(const XrFrameEndInfo *info) {
+    if (!snapshot || !*snap_dir || !info) return;
+    static int64_t next_ns;
+    static int taken;
+    struct timespec now;
+    clock_gettime(CLOCK_MONOTONIC, &now);
+    int64_t t = (int64_t)now.tv_sec * 1000000000ll + now.tv_nsec;
+    if (t < next_ns) return;
+    next_ns = t + (int64_t)snapshot * 1000000000ll;
+    const XrCompositionLayerProjection *proj = NULL;
+    for (uint32_t i = 0; i < info->layerCount && !proj; ++i)
+        if (info->layers[i] && info->layers[i]->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
+            ((const XrCompositionLayerProjection *)info->layers[i])->viewCount)
+            proj = (const XrCompositionLayerProjection *)info->layers[i];
+    if (!proj || !snap_load_gl()) return;
+    if (!s_eglGetCurrentContext()) {
+        static int logged;
+        if (!logged++) LOG("snapshot: no GL context current in xrEndFrame, no snapshot");
+        return;
+    }
+    const XrSwapchainSubImage *sub = &proj->views[0].subImage;
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(sub->swapchain, 0);
+    GLuint tex = 0;
+    uint32_t w = 0, h = 0, array_size = 1;
+    if (i >= 0 && snap_chains[i].count && snap_chains[i].last_acquired < snap_chains[i].count) {
+        tex = snap_chains[i].images[snap_chains[i].last_acquired];
+        w = snap_chains[i].width, h = snap_chains[i].height, array_size = snap_chains[i].array_size;
+    }
+    pthread_mutex_unlock(&snap_lock);
+    if (!tex || !w || !h) return;
+    GLint read_fb = 0, pack_buffer = 0, pack_alignment = 4;
+    s_glGetIntegerv(GL_READ_FRAMEBUFFER_BINDING, &read_fb);
+    s_glGetIntegerv(GL_PIXEL_PACK_BUFFER_BINDING, &pack_buffer);
+    s_glGetIntegerv(GL_PACK_ALIGNMENT, &pack_alignment);
+    GLuint fb = 0;
+    s_glGenFramebuffers(1, &fb);
+    s_glBindFramebuffer(GL_READ_FRAMEBUFFER, fb);
+    if (array_size > 1)
+        s_glFramebufferTextureLayer(GL_READ_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, tex, 0, (GLint)sub->imageArrayIndex);
+    else
+        s_glFramebufferTexture2D(GL_READ_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, tex, 0);
+    unsigned char *rgba = NULL;
+    if (s_glCheckFramebufferStatus(GL_READ_FRAMEBUFFER) == GL_FRAMEBUFFER_COMPLETE &&
+        (rgba = malloc((size_t)w * h * 4))) {
+        s_glBindBuffer(GL_PIXEL_PACK_BUFFER, 0);
+        s_glPixelStorei(GL_PACK_ALIGNMENT, 1);
+        s_glReadPixels(0, 0, (GLsizei)w, (GLsizei)h, GL_RGBA, GL_UNSIGNED_BYTE, rgba);
+    } else {
+        static int logged;
+        if (logged++ < 3) LOG("snapshot: eye image %u not readable (framebuffer incomplete)", tex);
+    }
+    s_glPixelStorei(GL_PACK_ALIGNMENT, pack_alignment);
+    s_glBindBuffer(GL_PIXEL_PACK_BUFFER, (GLuint)pack_buffer);
+    s_glBindFramebuffer(GL_READ_FRAMEBUFFER, (GLuint)read_fb);
+    s_glDeleteFramebuffers(1, &fb);
+    while (s_glGetError() != GL_NO_ERROR) {}  // our calls must not leave errors for the game to find
+    if (rgba) {
+        snap_write(rgba, w, h, taken++ % 8);
+        free(rgba);
+    }
+}
@@ -0,0 +1,510 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Included by frame_adapter.c (after flip_vk.c and layer_emul_gl.c). Emulates XR_KHR_android_surface_swapchain,
+// which the Frame's runtime lists but answers with XR_ERROR_FUNCTION_UNSUPPORTED. Games use it to play a video on a
+// panel (OVROverlay "external surface", Android MediaPlayer/ExoPlayer drawing into a Surface): without it the panel has
+// no image and is dropped, and a game that waits for its intro video shows black forever (I Am Monkey).
+//
+//  * xrCreateSwapchainAndroidSurfaceKHR: the runtime first; if it can't, an ordinary runtime swapchain of the same size
+//    (sRGB RGBA8) is created and returned as the game's swapchain, and the game gets a real android.view.Surface from a
+//    SurfaceTexture owned by a worker thread (own EGL context; JNI through the JavaVM of xrCreateInstance).
+//  * The worker latches each new video frame (any size, YUV: SurfaceTexture samples it), draws it into an RGBA8
+//    texture of the swapchain's size and reads it back (glReadPixels) into a shared buffer.
+//  * xrEndFrame: a layer showing an emulated swapchain gets the newest frame uploaded first (Vulkan: staging buffer +
+//    copy on the session's queue; GLES: glTexSubImage2D in the app's context), then is submitted as usual.
+//  * Any failure: the call returns the runtime's own result (as before), so nothing gets worse.
+#include <jni.h>
+
+#define SURF_MAX 8
+
+typedef void *(*PFN_ASurfaceTexture_fromSurfaceTexture)(JNIEnv *, jobject);
+typedef int (*PFN_ASurfaceTexture_updateTexImage)(void *);
+typedef void (*PFN_ASurfaceTexture_getTransformMatrix)(void *, float[16]);
+typedef int64_t (*PFN_ASurfaceTexture_getTimestamp)(void *);
+typedef void (*PFN_ASurfaceTexture_release)(void *);
+
+#define surf_vm ((JavaVM *)android_vm)  // from XrInstanceCreateInfoAndroidKHR (frame_adapter.c)
+
+typedef struct {
+    int used;
+    XrSwapchain handle;
+    uint32_t width, height;
+    // worker
+    pthread_t thread;
+    int stop, ready, failed;  // ready: surface handed out; failed: worker gave up
+    jobject surface;          // global ref, returned to the game
+    // newest frame (RGBA8, top row first), written by the worker
+    uint8_t *pixels;
+    uint64_t seq;             // bumps with every new frame
+    int64_t frames;
+    // upload side (app render thread)
+    uint64_t uploaded_seq;
+    int uploads, upload_failures, has_content;
+    VkImage vk_images[MAX_IMAGES];
+    uint32_t gl_images[MAX_IMAGES];
+    uint32_t image_count;
+    VkBuffer staging;
+    VkDeviceMemory staging_memory;
+    void *staging_map;
+    VkCommandPool pool;  // own command buffer + fence: uploads never wait for the GPU in xrEndFrame
+    VkCommandBuffer cmd;
+    VkFence fence;
+    int in_flight;      // a copy was submitted and its fence not yet seen signalled
+} surf_swapchain;
+
+static pthread_mutex_t surf_lock = PTHREAD_MUTEX_INITIALIZER;
+static pthread_cond_t surf_cond = PTHREAD_COND_INITIALIZER;
+static surf_swapchain surfs[SURF_MAX];
+static int surf_vulkan;  // the session is Vulkan (else GLES)
+
+static surf_swapchain *surf_find(XrSwapchain handle) {
+    for (int i = 0; i < SURF_MAX; ++i)
+        if (surfs[i].used && surfs[i].handle == handle) return &surfs[i];
+    return NULL;
+}
+
+// ---------------------------------------------------------------- worker: SurfaceTexture -> RGBA pixels
+static const char *surf_vs = "#version 300 es\nout vec2 uv;\nvoid main() {\n"
+    "  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));\n"
+    "  uv = p; gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);\n}\n";
+// window row 0 (glReadPixels' first row) must hold the image's top: sample t = 1 - y (SurfaceTexture t=0 is the bottom)
+static const char *surf_fs = "#version 300 es\n#extension GL_OES_EGL_image_external_essl3 : require\n"
+    "precision mediump float;\nuniform samplerExternalOES tex;\nuniform mat4 st;\nin vec2 uv;\nout vec4 color;\n"
+    "void main() { color = texture(tex, (st * vec4(uv.x, 1.0 - uv.y, 0.0, 1.0)).xy); }\n";
+
+typedef void (*PFN_glReadPixels_)(GLint, GLint, GLsizei, GLsizei, GLenum, GLenum, void *);
+typedef void (*PFN_glTexParameteri_)(GLenum, GLenum, GLint);
+typedef void (*PFN_glUniformMatrix4fv_)(GLint, GLsizei, GLboolean, const GLfloat *);
+typedef void (*PFN_glPixelStorei_)(GLenum, GLint);
+typedef void (*PFN_glTexSubImage2D_)(GLenum, GLint, GLint, GLint, GLsizei, GLsizei, GLenum, GLenum, const void *);
+typedef EGLDisplay (*PFN_eglGetDisplay_)(EGLNativeDisplayType);
+typedef EGLBoolean (*PFN_eglInitialize_)(EGLDisplay, EGLint *, EGLint *);
+static PFN_glReadPixels_ s_glReadPixels;
+static PFN_glTexParameteri_ s_glTexParameteri;
+static PFN_glUniformMatrix4fv_ s_glUniformMatrix4fv;
+static PFN_glPixelStorei_ s_glPixelStorei;
+static PFN_glTexSubImage2D_ s_glTexSubImage2D;
+static PFN_eglGetDisplay_ s_eglGetDisplay;
+static PFN_eglInitialize_ s_eglInitialize;
+static PFN_ASurfaceTexture_fromSurfaceTexture s_ast_from;
+static PFN_ASurfaceTexture_updateTexImage s_ast_update;
+static PFN_ASurfaceTexture_getTransformMatrix s_ast_matrix;
+static PFN_ASurfaceTexture_getTimestamp s_ast_timestamp;
+static PFN_ASurfaceTexture_release s_ast_release;
+
+static int surf_load(void) {
+    static int state;  // 0 untried, 1 ok, -1 failed
+    if (state) return state > 0;
+    state = -1;
+    if (!emul_load_gl()) { LOG("surface_emul: EGL/GLES not available"); return 0; }
+    void *egl = dlopen("libEGL.so", RTLD_NOW | RTLD_LOCAL), *gles = dlopen("libGLESv3.so", RTLD_NOW | RTLD_LOCAL);
+    void *android = dlopen("libandroid.so", RTLD_NOW | RTLD_LOCAL);
+    if (!egl || !gles || !android) { LOG("surface_emul: libEGL/libGLESv3/libandroid missing"); return 0; }
+    s_glReadPixels = (PFN_glReadPixels_)dlsym(gles, "glReadPixels");
+    s_glTexParameteri = (PFN_glTexParameteri_)dlsym(gles, "glTexParameteri");
+    s_glUniformMatrix4fv = (PFN_glUniformMatrix4fv_)dlsym(gles, "glUniformMatrix4fv");
+    s_glPixelStorei = (PFN_glPixelStorei_)dlsym(gles, "glPixelStorei");
+    s_glTexSubImage2D = (PFN_glTexSubImage2D_)dlsym(gles, "glTexSubImage2D");
+    s_eglGetDisplay = (PFN_eglGetDisplay_)dlsym(egl, "eglGetDisplay");
+    s_eglInitialize = (PFN_eglInitialize_)dlsym(egl, "eglInitialize");
+    s_ast_from = (PFN_ASurfaceTexture_fromSurfaceTexture)dlsym(android, "ASurfaceTexture_fromSurfaceTexture");
+    s_ast_update = (PFN_ASurfaceTexture_updateTexImage)dlsym(android, "ASurfaceTexture_updateTexImage");
+    s_ast_matrix = (PFN_ASurfaceTexture_getTransformMatrix)dlsym(android, "ASurfaceTexture_getTransformMatrix");
+    s_ast_timestamp = (PFN_ASurfaceTexture_getTimestamp)dlsym(android, "ASurfaceTexture_getTimestamp");
+    s_ast_release = (PFN_ASurfaceTexture_release)dlsym(android, "ASurfaceTexture_release");
+    if (!s_glReadPixels || !s_glTexParameteri || !s_glUniformMatrix4fv || !s_glPixelStorei || !s_glTexSubImage2D ||
+        !s_eglGetDisplay || !s_eglInitialize || !s_ast_from || !s_ast_update || !s_ast_matrix || !s_ast_timestamp ||
+        !s_ast_release) {
+        LOG("surface_emul: a GL/EGL/ASurfaceTexture function is missing");
+        return 0;
+    }
+    state = 1;
+    return 1;
+}
+
+static void surf_fail(surf_swapchain *s, const char *why) {
+    LOG("surface_emul: %s", why);
+    pthread_mutex_lock(&surf_lock);
+    s->failed = 1;
+    pthread_cond_broadcast(&surf_cond);
+    pthread_mutex_unlock(&surf_lock);
+}
+
+static void *surf_worker(void *arg) {
+    surf_swapchain *s = arg;
+    JNIEnv *env = NULL;
+    if ((*surf_vm)->AttachCurrentThread(surf_vm, &env, NULL) != JNI_OK || !env) { surf_fail(s, "no JNI env"); return NULL; }
+    EGLDisplay dpy = s_eglGetDisplay(EGL_DEFAULT_DISPLAY);
+    EGLint cfg_attribs[] = {EGL_RENDERABLE_TYPE, 0x40 /* EGL_OPENGL_ES3_BIT */, EGL_SURFACE_TYPE, EGL_PBUFFER_BIT,
+                            EGL_RED_SIZE, 8, EGL_GREEN_SIZE, 8, EGL_BLUE_SIZE, 8, EGL_ALPHA_SIZE, 8, EGL_NONE};
+    EGLConfig config = NULL;
+    EGLint n = 0, ctx_attribs[] = {EGL_CONTEXT_CLIENT_VERSION, 3, EGL_NONE}, pb[] = {EGL_WIDTH, 16, EGL_HEIGHT, 16, EGL_NONE};
+    EGLContext ctx = EGL_NO_CONTEXT;
+    EGLSurface pbuf = EGL_NO_SURFACE;
+    void *ast = NULL;
+    jobject st_local = NULL, st_global = NULL;
+    GLuint ext_tex = 0, rgba_tex = 0, fbo = 0, vao = 0, program = 0;
+    if (dpy == EGL_NO_DISPLAY || !s_eglInitialize(dpy, NULL, NULL) || !p_eglChooseConfig(dpy, cfg_attribs, &config, 1, &n) ||
+        n < 1 || (ctx = p_eglCreateContext(dpy, config, EGL_NO_CONTEXT, ctx_attribs)) == EGL_NO_CONTEXT ||
+        (pbuf = p_eglCreatePbufferSurface(dpy, config, pb)) == EGL_NO_SURFACE || !p_eglMakeCurrent(dpy, pbuf, pbuf, ctx)) {
+        surf_fail(s, "EGL context failed");
+        goto out;
+    }
+    // the SurfaceTexture's external texture, and the RGBA target the frames are drawn into
+    p_glGenTextures(1, &ext_tex);
+    p_glBindTexture(0x8D65 /* GL_TEXTURE_EXTERNAL_OES */, ext_tex);
+    s_glTexParameteri(0x8D65, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
+    s_glTexParameteri(0x8D65, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
+    p_glGenTextures(1, &rgba_tex);
+    p_glBindTexture(GL_TEXTURE_2D, rgba_tex);
+    p_glTexStorage2D(GL_TEXTURE_2D, 1, GL_RGBA8, (GLsizei)s->width, (GLsizei)s->height);
+    p_glGenFramebuffers(1, &fbo);
+    p_glBindFramebuffer(GL_FRAMEBUFFER, fbo);
+    p_glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, rgba_tex, 0);
+    if (p_glCheckFramebufferStatus(GL_FRAMEBUFFER) != GL_FRAMEBUFFER_COMPLETE) { surf_fail(s, "framebuffer incomplete"); goto out; }
+    {
+        GLuint v = emul_compile(GL_VERTEX_SHADER, "", surf_vs), f = emul_compile(GL_FRAGMENT_SHADER, "", surf_fs);
+        if (!v || !f) { surf_fail(s, "shader compile failed"); goto out; }
+        program = p_glCreateProgram();
+        p_glAttachShader(program, v);
+        p_glAttachShader(program, f);
+        p_glLinkProgram(program);
+        GLint ok = 0;
+        p_glGetProgramiv(program, GL_LINK_STATUS, &ok);
+        if (!ok) { surf_fail(s, "program link failed"); goto out; }
+    }
+    p_glGenVertexArrays(1, &vao);
+    // android.graphics.SurfaceTexture(texName) + android.view.Surface(SurfaceTexture)
+    {
+        jclass st_class = (*env)->FindClass(env, "android/graphics/SurfaceTexture");
+        jclass surface_class = (*env)->FindClass(env, "android/view/Surface");
+        if (!st_class || !surface_class) { (*env)->ExceptionClear(env); surf_fail(s, "SurfaceTexture/Surface class missing"); goto out; }
+        jmethodID st_init = (*env)->GetMethodID(env, st_class, "<init>", "(I)V");
+        jmethodID st_size = (*env)->GetMethodID(env, st_class, "setDefaultBufferSize", "(II)V");
+        jmethodID surface_init = (*env)->GetMethodID(env, surface_class, "<init>", "(Landroid/graphics/SurfaceTexture;)V");
+        st_local = (*env)->NewObject(env, st_class, st_init, (jint)ext_tex);
+        if (!st_local || (*env)->ExceptionCheck(env)) { (*env)->ExceptionClear(env); surf_fail(s, "new SurfaceTexture failed"); goto out; }
+        (*env)->CallVoidMethod(env, st_local, st_size, (jint)s->width, (jint)s->height);
+        jobject surface_local = (*env)->NewObject(env, surface_class, surface_init, st_local);
+        if (!surface_local || (*env)->ExceptionCheck(env)) { (*env)->ExceptionClear(env); surf_fail(s, "new Surface failed"); goto out; }
+        st_global = (*env)->NewGlobalRef(env, st_local);
+        ast = s_ast_from(env, st_local);
+        if (!ast) { surf_fail(s, "ASurfaceTexture_fromSurfaceTexture failed"); goto out; }
+        pthread_mutex_lock(&surf_lock);
+        s->surface = (*env)->NewGlobalRef(env, surface_local);
+        s->ready = 1;
+        pthread_cond_broadcast(&surf_cond);
+        pthread_mutex_unlock(&surf_lock);
+        (*env)->DeleteLocalRef(env, surface_local);
+    }
+    LOG("surface_emul: Surface ready for %ux%u swapchain %p", s->width, s->height, (void *)(uintptr_t)s->handle);
+    {
+        GLint u_tex = p_glGetUniformLocation(program, "tex"), u_st = p_glGetUniformLocation(program, "st");
+        size_t bytes = (size_t)s->width * s->height * 4;
+        uint8_t *buf = malloc(bytes);
+        int64_t last_ts = -1, window_frames = 0, window_start = 0;
+        while (!s->stop && buf) {
+            struct timespec pause = {0, 8000000};  // ~120 checks a second: well above video frame rates
+            nanosleep(&pause, NULL);
+            if (s_ast_update(ast) != 0) continue;
+            int64_t ts = s_ast_timestamp(ast);
+            if (ts == last_ts) continue;  // no new frame latched
+            last_ts = ts;
+            float m[16];
+            s_ast_matrix(ast, m);
+            p_glBindFramebuffer(GL_FRAMEBUFFER, fbo);
+            p_glViewport(0, 0, (GLsizei)s->width, (GLsizei)s->height);
+            p_glUseProgram(program);
+            p_glActiveTexture(GL_TEXTURE0);
+            p_glBindTexture(0x8D65, ext_tex);
+            p_glUniform1i(u_tex, 0);
+            s_glUniformMatrix4fv(u_st, 1, GL_FALSE, m);
+            p_glBindVertexArray(vao);
+            p_glDrawArrays(GL_TRIANGLES, 0, 3);
+            s_glPixelStorei(GL_PACK_ALIGNMENT, 1);
+            s_glReadPixels(0, 0, (GLsizei)s->width, (GLsizei)s->height, GL_RGBA, GL_UNSIGNED_BYTE, buf);
+            GLenum err = p_glGetError();
+            pthread_mutex_lock(&surf_lock);
+            if (!err && s->pixels) { memcpy(s->pixels, buf, bytes); s->seq++; s->frames++; }
+            pthread_mutex_unlock(&surf_lock);
+            if (err) { static int warned; if (warned++ < 5) LOG("surface_emul: GL error 0x%x drawing a frame", err); }
+            int64_t now = monotonic_ns();
+            if (!window_start) {
+                window_start = now;
+                LOG("surface_emul: first video frame (timestamp %lld)", (long long)ts);
+            }
+            if (++window_frames && now - window_start > 5000000000ll) {
+                LOG("surface_emul: %.1f video frames/s, %d uploaded, %d upload failures", window_frames * 1e9 / (now - window_start),
+                    s->uploads, s->upload_failures);
+                window_frames = 0;
+                window_start = now;
+            }
+        }
+        free(buf);
+    }
+out:
+    if (ast) s_ast_release(ast);
+    if (st_global) (*env)->DeleteGlobalRef(env, st_global);
+    if (ctx != EGL_NO_CONTEXT) { p_eglMakeCurrent(dpy, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT); p_eglDestroyContext(dpy, ctx); }
+    if (pbuf != EGL_NO_SURFACE) p_eglDestroySurface(dpy, pbuf);
+    (*surf_vm)->DetachCurrentThread(surf_vm);
+    return NULL;
+}
+
+// ---------------------------------------------------------------- uploads (app render thread)
+static struct {
+    PFN_vkCreateBuffer CreateBuffer;
+    PFN_vkGetBufferMemoryRequirements GetBufferMemoryRequirements;
+    PFN_vkAllocateMemory AllocateMemory;
+    PFN_vkBindBufferMemory BindBufferMemory;
+    PFN_vkMapMemory MapMemory;
+    PFN_vkCmdCopyBufferToImage CmdCopyBufferToImage;
+    PFN_vkCmdClearColorImage CmdClearColorImage;
+    PFN_vkGetPhysicalDeviceMemoryProperties GetPhysicalDeviceMemoryProperties;
+    PFN_vkGetFenceStatus GetFenceStatus;
+    int state;
+} svk;
+
+static int surf_vk_ready(void) {
+    if (svk.state) return svk.state > 0;
+    svk.state = -1;
+    if (!vk_ready()) return 0;
+#define SDEV(name) svk.name = (PFN_vk##name)vk.GetDeviceProcAddr(vk.device, "vk" #name); if (!svk.name) return 0;
+    SDEV(CreateBuffer) SDEV(GetBufferMemoryRequirements) SDEV(AllocateMemory) SDEV(BindBufferMemory) SDEV(MapMemory)
+    SDEV(CmdCopyBufferToImage) SDEV(CmdClearColorImage) SDEV(GetFenceStatus)
+#undef SDEV
+    void *lib = dlopen("libvulkan.so", RTLD_NOW | RTLD_LOCAL);
+    PFN_vkGetInstanceProcAddr gipa = lib ? (PFN_vkGetInstanceProcAddr)dlsym(lib, "vkGetInstanceProcAddr") : NULL;
+    svk.GetPhysicalDeviceMemoryProperties = gipa ? (PFN_vkGetPhysicalDeviceMemoryProperties)gipa(vk.instance,
+        "vkGetPhysicalDeviceMemoryProperties") : NULL;
+    if (!svk.GetPhysicalDeviceMemoryProperties) return 0;
+    svk.state = 1;
+    return 1;
+}
+
+static void surf_barrier(VkCommandBuffer cmd, VkImage image, VkImageLayout from, VkImageLayout to,
+                         VkAccessFlags src_access, VkAccessFlags dst_access) {
+    VkImageMemoryBarrier b = {VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER, NULL, src_access, dst_access, from, to,
+                              VK_QUEUE_FAMILY_IGNORED, VK_QUEUE_FAMILY_IGNORED, image,
+                              {VK_IMAGE_ASPECT_COLOR_BIT, 0, 1, 0, 1}};
+    vk.CmdPipelineBarrier(cmd, VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, 0, 0, NULL, 0,
+                          NULL, 1, &b);
+}
+
+static int surf_staging(surf_swapchain *s) {
+    if (s->staging_map) return 1;
+    VkCommandPoolCreateInfo pool = {VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO, NULL,
+                                    VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT, vk.family};
+    if (vk.CreateCommandPool(vk.device, &pool, NULL, &s->pool) != VK_SUCCESS) return 0;
+    VkCommandBufferAllocateInfo alloc = {VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO, NULL, s->pool,
+                                         VK_COMMAND_BUFFER_LEVEL_PRIMARY, 1};
+    if (vk.AllocateCommandBuffers(vk.device, &alloc, &s->cmd) != VK_SUCCESS) return 0;
+    VkFenceCreateInfo fence = {VK_STRUCTURE_TYPE_FENCE_CREATE_INFO, NULL, 0};
+    if (vk.CreateFence(vk.device, &fence, NULL, &s->fence) != VK_SUCCESS) return 0;
+    VkBufferCreateInfo bi = {VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO, NULL, 0, (VkDeviceSize)s->width * s->height * 4,
+                             VK_BUFFER_USAGE_TRANSFER_SRC_BIT, VK_SHARING_MODE_EXCLUSIVE, 0, NULL};
+    if (svk.CreateBuffer(vk.device, &bi, NULL, &s->staging) != VK_SUCCESS) return 0;
+    VkMemoryRequirements req;
+    svk.GetBufferMemoryRequirements(vk.device, s->staging, &req);
+    VkPhysicalDeviceMemoryProperties props;
+    svk.GetPhysicalDeviceMemoryProperties(vk.physical, &props);
+    uint32_t want = VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, type = UINT32_MAX;
+    for (uint32_t i = 0; i < props.memoryTypeCount && type == UINT32_MAX; ++i)
+        if ((req.memoryTypeBits & (1u << i)) && (props.memoryTypes[i].propertyFlags & want) == want) type = i;
+    if (type == UINT32_MAX) return 0;
+    VkMemoryAllocateInfo ai = {VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO, NULL, req.size, type};
+    if (svk.AllocateMemory(vk.device, &ai, NULL, &s->staging_memory) != VK_SUCCESS) return 0;
+    if (svk.BindBufferMemory(vk.device, s->staging, s->staging_memory, 0) != VK_SUCCESS) return 0;
+    return svk.MapMemory(vk.device, s->staging_memory, 0, VK_WHOLE_SIZE, 0, &s->staging_map) == VK_SUCCESS;
+}
+
+// Copy the newest frame (or black, the first time) into the next image of the runtime swapchain. Returns 1 if the
+// swapchain now has an image to show, -1 if the previous copy is still running (try next frame), 0 on failure.
+static int surf_upload(surf_swapchain *s, int black) {
+    PFN_xrAcquireSwapchainImage acquire = (PFN_xrAcquireSwapchainImage)lookup(active_instance, "xrAcquireSwapchainImage");
+    PFN_xrWaitSwapchainImage wait = (PFN_xrWaitSwapchainImage)lookup(active_instance, "xrWaitSwapchainImage");
+    PFN_xrReleaseSwapchainImage release = (PFN_xrReleaseSwapchainImage)lookup(active_instance, "xrReleaseSwapchainImage");
+    if (!acquire || !wait || !release || !s->image_count) return 0;
+    uint32_t index = 0;
+    XrSwapchainImageAcquireInfo ai = {XR_TYPE_SWAPCHAIN_IMAGE_ACQUIRE_INFO, NULL};
+    XrSwapchainImageWaitInfo wi = {XR_TYPE_SWAPCHAIN_IMAGE_WAIT_INFO, NULL, 100000000};
+    XrSwapchainImageReleaseInfo ri = {XR_TYPE_SWAPCHAIN_IMAGE_RELEASE_INFO, NULL};
+    if (surf_vulkan && s->in_flight) {  // the previous copy still reads the staging buffer: try again next frame
+        if (svk.GetFenceStatus(vk.device, s->fence) != VK_SUCCESS) return -1;
+        vk.ResetFences(vk.device, 1, &s->fence);
+        s->in_flight = 0;
+    }
+    if (XR_FAILED(acquire(s->handle, &ai, &index)) || index >= s->image_count) return 0;
+    if (XR_FAILED(wait(s->handle, &wi))) { release(s->handle, &ri); return 0; }
+    int ok = 0;
+    size_t bytes = (size_t)s->width * s->height * 4;
+    if (surf_vulkan) {
+        if (!black) {
+            pthread_mutex_lock(&surf_lock);
+            memcpy(s->staging_map, s->pixels, bytes);
+            pthread_mutex_unlock(&surf_lock);
+        }
+        VkImage img = s->vk_images[index];
+        VkCommandBufferBeginInfo begin = {VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO, NULL,
+                                          VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT, NULL};
+        VkCommandBuffer cmd = s->cmd;
+        vk.ResetCommandBuffer(cmd, 0);
+        vk.BeginCommandBuffer(cmd, &begin);
+        surf_barrier(cmd, img, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 0, VK_ACCESS_TRANSFER_WRITE_BIT);
+        if (black) {
+            VkClearColorValue c = {{0, 0, 0, 1}};
+            VkImageSubresourceRange r = {VK_IMAGE_ASPECT_COLOR_BIT, 0, 1, 0, 1};
+            svk.CmdClearColorImage(cmd, img, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, &c, 1, &r);
+        } else {
+            VkBufferImageCopy copy = {0, 0, 0, {VK_IMAGE_ASPECT_COLOR_BIT, 0, 0, 1}, {0, 0, 0}, {s->width, s->height, 1}};
+            svk.CmdCopyBufferToImage(cmd, s->staging, img, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1, &copy);
+        }
+        surf_barrier(cmd, img, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
+                VK_ACCESS_TRANSFER_WRITE_BIT, VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT);
+        vk.EndCommandBuffer(cmd);
+        VkSubmitInfo submit = {VK_STRUCTURE_TYPE_SUBMIT_INFO, NULL, 0, NULL, NULL, 1, &cmd, 0, NULL};
+        // released right after the submit: the runtime's own work on this queue runs after the copy
+        ok = vk.QueueSubmit(vk.queue, 1, &submit, s->fence) == VK_SUCCESS;
+        s->in_flight = ok;
+    } else if (!black) {  // GLES: the app's context is current on its render thread (xrEndFrame)
+        GLint prev_tex = 0, prev_align = 4, prev_unpack = 0;
+        p_glGetIntegerv(GL_TEXTURE_BINDING_2D, &prev_tex);
+        p_glGetIntegerv(GL_UNPACK_ALIGNMENT, &prev_align);
+        p_glGetIntegerv(0x88EF /* GL_PIXEL_UNPACK_BUFFER_BINDING */, &prev_unpack);
+        if (prev_unpack) { typedef void (*bb)(GLenum, GLuint); static bb bind; if (!bind) bind = (bb)dlsym(RTLD_DEFAULT, "glBindBuffer"); if (bind) bind(0x88EC, 0); }
+        p_glBindTexture(GL_TEXTURE_2D, s->gl_images[index]);
+        s_glPixelStorei(GL_UNPACK_ALIGNMENT, 1);
+        pthread_mutex_lock(&surf_lock);
+        s_glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, (GLsizei)s->width, (GLsizei)s->height, GL_RGBA, GL_UNSIGNED_BYTE, s->pixels);
+        pthread_mutex_unlock(&surf_lock);
+        ok = p_glGetError() == GL_NO_ERROR;
+        s_glPixelStorei(GL_UNPACK_ALIGNMENT, prev_align);
+        p_glBindTexture(GL_TEXTURE_2D, (GLuint)prev_tex);
+        if (prev_unpack) { typedef void (*bb)(GLenum, GLuint); static bb bind; if (!bind) bind = (bb)dlsym(RTLD_DEFAULT, "glBindBuffer"); if (bind) bind(0x88EC, (GLuint)prev_unpack); }
+    }
+    release(s->handle, &ri);
+    return ok;
+}
+
+// xrEndFrame: before a layer showing an emulated swapchain is submitted. Returns 0 if it has nothing to show yet.
+static int surf_prepare_layer(XrSwapchain handle) {
+    pthread_mutex_lock(&surf_lock);
+    surf_swapchain *s = surf_find(handle);
+    uint64_t seq = s ? s->seq : 0;
+    pthread_mutex_unlock(&surf_lock);
+    if (!s) return 1;  // not ours
+    if (seq != s->uploaded_seq) {
+        int r = surf_upload(s, 0);
+        if (r > 0) { s->uploaded_seq = seq; s->uploads++; s->has_content = 1; }
+        else if (r == 0 && s->upload_failures++ < 5) LOG("surface_emul: upload failed (swapchain %p)", (void *)(uintptr_t)handle);
+    }
+    return s->has_content;
+}
+
+// ---------------------------------------------------------------- the emulated entry points
+typedef XrResult (XRAPI_PTR *PFN_xrCreateSwapchainAndroidSurfaceKHR_)(XrSession, const XrSwapchainCreateInfo *,
+                                                                      XrSwapchain *, jobject *);
+
+static XRAPI_ATTR XrResult XRAPI_CALL hook_xrCreateSwapchainAndroidSurfaceKHR(XrSession session,
+        const XrSwapchainCreateInfo *info, XrSwapchain *swapchain, jobject *surface) {
+    PFN_xrCreateSwapchainAndroidSurfaceKHR_ fn =
+        (PFN_xrCreateSwapchainAndroidSurfaceKHR_)lookup(active_instance, "xrCreateSwapchainAndroidSurfaceKHR");
+    XrResult result = fn ? fn(session, info, swapchain, surface) : XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (result != XR_ERROR_FUNCTION_UNSUPPORTED || !info || !swapchain || !surface) return result;
+    LOG("surface_emul: runtime has no Android surface swapchains: emulating %ux%u (vm %s, %s session)", info->width,
+        info->height, surf_vm ? "ok" : "MISSING", vk.device ? "Vulkan" : "GLES");
+    if (!surf_vm || !info->width || !info->height || !surf_load()) return result;
+    surf_vulkan = vk.device != VK_NULL_HANDLE;
+    if (surf_vulkan && !surf_vk_ready()) { LOG("surface_emul: Vulkan upload path unavailable"); return result; }
+    pthread_mutex_lock(&surf_lock);
+    surf_swapchain *s = NULL;
+    for (int i = 0; i < SURF_MAX && !s; ++i)
+        if (!surfs[i].used) s = &surfs[i];
+    if (s) { memset(s, 0, sizeof(*s)); s->used = 1; }
+    pthread_mutex_unlock(&surf_lock);
+    if (!s) { LOG("surface_emul: too many surface swapchains"); return result; }
+    // the runtime swapchain the game gets instead (what its layer will show)
+    PFN_xrCreateSwapchain create = (PFN_xrCreateSwapchain)lookup(active_instance, "xrCreateSwapchain");
+    PFN_xrEnumerateSwapchainImages enumerate =
+        (PFN_xrEnumerateSwapchainImages)lookup(active_instance, "xrEnumerateSwapchainImages");
+    PFN_xrDestroySwapchain destroy = (PFN_xrDestroySwapchain)lookup(active_instance, "xrDestroySwapchain");
+    XrSwapchainCreateInfo ci = {XR_TYPE_SWAPCHAIN_CREATE_INFO, NULL, 0,
+                                XR_SWAPCHAIN_USAGE_COLOR_ATTACHMENT_BIT | XR_SWAPCHAIN_USAGE_TRANSFER_DST_BIT |
+                                XR_SWAPCHAIN_USAGE_SAMPLED_BIT,
+                                surf_vulkan ? 43 /* VK_FORMAT_R8G8B8A8_SRGB */ : 0x8C43 /* GL_SRGB8_ALPHA8 */,
+                                1, info->width, info->height, 1, 1, 1};
+    XrSwapchain handle = XR_NULL_HANDLE;
+    XrResult cr = create && enumerate ? create(session, &ci, &handle) : XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (XR_FAILED(cr)) {
+        LOG("surface_emul: xrCreateSwapchain failed %d", cr);
+        pthread_mutex_lock(&surf_lock); s->used = 0; pthread_mutex_unlock(&surf_lock);
+        return result;
+    }
+    s->handle = handle;
+    s->width = info->width;
+    s->height = info->height;
+    s->pixels = calloc((size_t)s->width * s->height, 4);
+    uint32_t n = 0;
+    if (surf_vulkan) {
+        XrSwapchainImageVulkanKHR images[MAX_IMAGES];
+        for (int i = 0; i < MAX_IMAGES; ++i) images[i] = (XrSwapchainImageVulkanKHR){XR_TYPE_SWAPCHAIN_IMAGE_VULKAN_KHR, NULL, VK_NULL_HANDLE};
+        if (XR_SUCCEEDED(enumerate(handle, MAX_IMAGES, &n, (XrSwapchainImageBaseHeader *)images)))
+            for (uint32_t i = 0; i < n && i < MAX_IMAGES; ++i) s->vk_images[i] = images[i].image;
+    } else {
+        emul_gles_image images[MAX_IMAGES];
+        for (int i = 0; i < MAX_IMAGES; ++i) images[i] = (emul_gles_image){XR_TYPE_SWAPCHAIN_IMAGE_OPENGL_ES_KHR, NULL, 0};
+        if (XR_SUCCEEDED(enumerate(handle, MAX_IMAGES, &n, (XrSwapchainImageBaseHeader *)images)))
+            for (uint32_t i = 0; i < n && i < MAX_IMAGES; ++i) s->gl_images[i] = images[i].image;
+    }
+    s->image_count = n < MAX_IMAGES ? n : MAX_IMAGES;
+    int setup_ok = s->pixels && s->image_count && (!surf_vulkan || surf_staging(s));
+    if (setup_ok) {
+        pthread_mutex_lock(&surf_lock);
+        setup_ok = pthread_create(&s->thread, NULL, surf_worker, s) == 0;
+        struct timespec until;
+        clock_gettime(CLOCK_REALTIME, &until);
+        until.tv_sec += 3;
+        while (setup_ok && !s->ready && !s->failed && pthread_cond_timedwait(&surf_cond, &surf_lock, &until) == 0) {}
+        setup_ok = setup_ok && s->ready;
+        pthread_mutex_unlock(&surf_lock);
+    }
+    if (!setup_ok) {
+        LOG("surface_emul: setup failed (images %u, pixels %d): the panel stays empty", s->image_count, s->pixels != NULL);
+        if (s->thread) { s->stop = 1; pthread_join(s->thread, NULL); }
+        if (destroy) destroy(handle);
+        free(s->pixels);
+        pthread_mutex_lock(&surf_lock); s->used = 0; pthread_mutex_unlock(&surf_lock);
+        return result;
+    }
+    // something valid to show from the first frame on (Vulkan: a black image; GLES: the layer waits for a frame)
+    if (surf_vulkan && surf_upload(s, 1) > 0) s->has_content = 1;
+    remember_swapchain(handle);
+    *swapchain = handle;
+    *surface = s->surface;
+    LOG("surface_emul: emulated Android surface swapchain %p (%u images)", (void *)(uintptr_t)handle, s->image_count);
+    return XR_SUCCESS;
+}
+
+// xrDestroySwapchain: an emulated swapchain's worker and surface go with it
+static void surf_on_destroy(XrSwapchain handle) {
+    pthread_mutex_lock(&surf_lock);
+    surf_swapchain *s = surf_find(handle);
+    pthread_mutex_unlock(&surf_lock);
+    if (!s) return;
+    s->stop = 1;
+    if (s->thread) pthread_join(s->thread, NULL);
+    if (surf_vm && s->surface) {
+        JNIEnv *env = NULL;
+        int attached = 0;
+        if ((*surf_vm)->GetEnv(surf_vm, (void **)&env, JNI_VERSION_1_6) != JNI_OK) {
+            attached = (*surf_vm)->AttachCurrentThread(surf_vm, &env, NULL) == JNI_OK;
+        }
+        if (env) (*env)->DeleteGlobalRef(env, s->surface);
+        if (attached) (*surf_vm)->DetachCurrentThread(surf_vm);
+    }
+    pthread_mutex_lock(&surf_lock);
+    free(s->pixels);
+    s->pixels = NULL;
+    s->used = 0;
+    pthread_mutex_unlock(&surf_lock);
+    LOG("surface_emul: destroyed %p", (void *)(uintptr_t)handle);
+}
@@ -5,12 +5,12 @@ Everything is fetched on demand into native/.cache (git-ignored):
  - Android NDK r27c (27.2.12479018) from Google's repository (checksummed via repository2-3.xml)
  - OpenXR headers at the commits each component was written against (KhronosGroup/OpenXR-SDK)
  - Temurin JDK 21 (javac) and Android build-tools (d8) for the Java stub classes
-Then builds: FrameBridge adapter (arm64 + arm32), VrApi bridge, platform compat, GL shim, oculusos stub dex, the
+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.

-    python native/build.py [--only adapter,bridge,compat,glshim,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] [--ndk PATH]
 """
 from __future__ import annotations

@@ -223,6 +223,15 @@ def build_compat(tc: Path):
         "-Wl,--version-script=exports.map", "-o", ART / "arm64-v8a/libovrplatformcompat.so"], cwd=src)


+def build_langpack(tc: Path):
+    """Language packs from the game's files (see langpack/langpack.c): DT_NEEDED-injected into overport's platform loader."""
+    src = HERE / "langpack"
+    run([exe(tc, "aarch64-linux-android29-clang"), "-shared", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror",
+         "-fvisibility=hidden", f"-ffile-prefix-map={src}=native/langpack", "-Wl,--no-undefined",
+         "-Wl,-z,max-page-size=16384", "-Wl,-soname,libfp_langpack.so", "langpack.c", "-ldl", "-llog",
+         "-o", ART / "arm64-v8a/libfp_langpack.so"], cwd=src)
+
+
 def build_glshim(tc: Path):
    src = HERE / "glshim"
    run([exe(tc, "aarch64-linux-android29-clang"), "-shared", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror",
@@ -230,6 +239,24 @@ def build_glshim(tc: Path):
         "-Wl,-z,max-page-size=16384", "glshim.c", "-ldl", "-llog", "-o", ART / "arm64-v8a/libglshim.so"], cwd=src)


+def build_eglfmt(tc: Path):
+    """Depth-format shim (see glshim/eglfmt.c) that GL-to-GLES wrappers (QuestCraft's LTW) load in place of libEGL.so.
+    Named libfpg.so: no longer than "libEGL.so", whose dlopen string in the wrapper is rewritten in place. Linked to
+    libEGL so a dlsym on its handle still finds every EGL function."""
+    src = HERE / "glshim"
+    run([exe(tc, "aarch64-linux-android29-clang"), "-shared", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror",
+         "-fvisibility=hidden", "-Wl,-soname,libfpg.so", "-Wl,-z,max-page-size=16384", "eglfmt.c",
+         "-Wl,--no-as-needed", "-lEGL", "-Wl,--as-needed", "-ldl", "-llog", "-o", ART / "arm64-v8a/libfpg.so"], cwd=src)
+
+
+def build_ovrtrace(tc: Path):
+    """Meta Platform SDK tracer (see ovrtrace/ovrtrace.c): diagnostics, the game's engine library loads it first."""
+    src = HERE / "ovrtrace"
+    run([exe(tc, "aarch64-linux-android29-clang"), "-shared", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror",
+         "-Wl,-soname,libfp_ovrtrace.so", "-Wl,-z,max-page-size=16384", "ovrtrace.c", "-ldl", "-llog",
+         "-o", ART / "arm64-v8a/libfp_ovrtrace.so"], cwd=src)
+
+
 def build_xrshim(tc: Path):
    """FrameBridge extension shim (see xrshim/xrshim.c): DT_NEEDED-injected in front of overport's libopenxr_loader.so."""
    src = HERE / "xrshim"
@@ -299,7 +326,7 @@ def write_sums():

 def main():
    ap = argparse.ArgumentParser()
-    ap.add_argument("--only", default="adapter,bridge,compat,glshim,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")
    ap.add_argument("--ndk")
    args = ap.parse_args()
    parts = set(args.only.split(","))
@@ -307,11 +334,12 @@ def main():
        (ART / d).mkdir(parents=True, exist_ok=True)
    tc = clang_dir(ndk(args.ndk)) if parts - {"dex"} else None
    steps = {"adapter": lambda: build_adapter(tc), "bridge": lambda: build_bridge(tc), "compat": lambda: build_compat(tc),
-             "glshim": lambda: build_glshim(tc), "xrshim": lambda: build_xrshim(tc), "dex": build_dex, "xrlayer": lambda: build_xrlayer(tc),
+             "langpack": lambda: build_langpack(tc),
+             "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", "glshim", "xrshim", "vkshim", "ovrpshim", "dex", "xrlayer", "oculushmd", "vrsettings"):
+    for name in ("adapter", "bridge", "compat", "langpack", "glshim", "eglfmt", "ovrtrace", "xrshim", "vkshim", "ovrpshim", "dex", "xrlayer", "oculushmd", "vrsettings"):
        if name in parts:
            log(f"build {name}")
            steps[name]()
@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// FramePort depth-format shim for GL-to-GLES wrappers (QuestCraft's LTW): desktop OpenGL's sized depth format
+// GL_DEPTH_COMPONENT32 doesn't exist in OpenGL ES. Qualcomm's Quest driver accepts it anyway; the Frame's Mesa (Zink)
+// rejects it (GL_INVALID_OPERATION in glTexImage2D), so Minecraft's depth textures never exist, every framebuffer that
+// uses them is incomplete and the picture stays black. LTW resolves every GLES function through eglGetProcAddress from
+// a libEGL it dlopens itself; FramePort points that dlopen string at this library (patches/frame/ltw_depth.py), which
+// hands back wrappers for the texture/renderbuffer allocation functions and the real functions for everything else:
+//   GL_DEPTH_COMPONENT32 -> GL_DEPTH_COMPONENT32F (GL_DEPTH_COMPONENT24 when pixel data comes as GL_UNSIGNED_INT),
+//   unsized GL_DEPTH_COMPONENT with GL_FLOAT data -> GL_DEPTH_COMPONENT32F.
+#define _GNU_SOURCE
+#include <EGL/egl.h>
+#include <GLES3/gl32.h>
+#include <android/log.h>
+#include <dlfcn.h>
+#include <pthread.h>
+#include <string.h>
+
+#define LOG(...) __android_log_print(ANDROID_LOG_INFO, "FrameBridge", __VA_ARGS__)
+#define EXPORT __attribute__((visibility("default")))
+#ifndef GL_DEPTH_COMPONENT32
+#define GL_DEPTH_COMPONENT32 0x81A7
+#endif
+
+typedef __eglMustCastToProperFunctionPointerType FnPtr;
+static FnPtr (*real_gpa)(const char *);
+static pthread_once_t once = PTHREAD_ONCE_INIT;
+static int logged;
+
+static void init(void) {
+    void *egl = dlopen("libEGL.so", RTLD_NOW | RTLD_LOCAL);
+    real_gpa = egl ? (FnPtr (*)(const char *))dlsym(egl, "eglGetProcAddress") : NULL;
+    LOG("depth format shim: libEGL.so %s", real_gpa ? "OK" : "MISSING");
+}
+
+// the ES internal format for a desktop depth request (`type` = the pixel data type, 0 when there is none)
+static GLint fix(GLint internal, GLenum type, const char *fn) {
+    GLint out = internal;
+    if (internal == GL_DEPTH_COMPONENT32) out = type == GL_UNSIGNED_INT ? GL_DEPTH_COMPONENT24 : GL_DEPTH_COMPONENT32F;
+    else if (internal == GL_DEPTH_COMPONENT && type == GL_FLOAT) out = GL_DEPTH_COMPONENT32F;
+    if (out != internal && logged < 8) {
+        logged++;
+        LOG("depth format shim: %s 0x%x -> 0x%x", fn, internal, out);
+    }
+    return out;
+}
+
+static PFNGLTEXIMAGE2DPROC r_ti2;
+static PFNGLTEXIMAGE3DPROC r_ti3;
+static PFNGLTEXSTORAGE2DPROC r_ts2;
+static PFNGLTEXSTORAGE3DPROC r_ts3;
+static PFNGLTEXSTORAGE2DMULTISAMPLEPROC r_ts2ms;
+static PFNGLTEXSTORAGE3DMULTISAMPLEPROC r_ts3ms;
+static PFNGLRENDERBUFFERSTORAGEPROC r_rbs;
+static PFNGLRENDERBUFFERSTORAGEMULTISAMPLEPROC r_rbsms;
+
+static void GL_APIENTRY w_ti2(GLenum t, GLint l, GLint i, GLsizei w, GLsizei h, GLint b, GLenum f, GLenum ty, const void *d) {
+    r_ti2(t, l, fix(i, ty, "glTexImage2D"), w, h, b, f, ty, d);
+}
+static void GL_APIENTRY w_ti3(GLenum t, GLint l, GLint i, GLsizei w, GLsizei h, GLsizei dp, GLint b, GLenum f, GLenum ty,
+                              const void *d) {
+    r_ti3(t, l, fix(i, ty, "glTexImage3D"), w, h, dp, b, f, ty, d);
+}
+static void GL_APIENTRY w_ts2(GLenum t, GLsizei l, GLenum i, GLsizei w, GLsizei h) {
+    r_ts2(t, l, (GLenum)fix((GLint)i, 0, "glTexStorage2D"), w, h);
+}
+static void GL_APIENTRY w_ts3(GLenum t, GLsizei l, GLenum i, GLsizei w, GLsizei h, GLsizei d) {
+    r_ts3(t, l, (GLenum)fix((GLint)i, 0, "glTexStorage3D"), w, h, d);
+}
+static void GL_APIENTRY w_ts2ms(GLenum t, GLsizei s, GLenum i, GLsizei w, GLsizei h, GLboolean fl) {
+    r_ts2ms(t, s, (GLenum)fix((GLint)i, 0, "glTexStorage2DMultisample"), w, h, fl);
+}
+static void GL_APIENTRY w_ts3ms(GLenum t, GLsizei s, GLenum i, GLsizei w, GLsizei h, GLsizei d, GLboolean fl) {
+    r_ts3ms(t, s, (GLenum)fix((GLint)i, 0, "glTexStorage3DMultisample"), w, h, d, fl);
+}
+static void GL_APIENTRY w_rbs(GLenum t, GLenum i, GLsizei w, GLsizei h) {
+    r_rbs(t, (GLenum)fix((GLint)i, 0, "glRenderbufferStorage"), w, h);
+}
+static void GL_APIENTRY w_rbsms(GLenum t, GLsizei s, GLenum i, GLsizei w, GLsizei h) {
+    r_rbsms(t, s, (GLenum)fix((GLint)i, 0, "glRenderbufferStorageMultisample"), w, h);
+}
+
+EXPORT FnPtr eglGetProcAddress(const char *name) {
+    pthread_once(&once, init);
+    FnPtr fn = real_gpa && name ? real_gpa(name) : NULL;
+    if (!fn) return fn;
+#define WRAP(sym, real, w) if (!strcmp(name, sym)) { real = (void *)fn; return (FnPtr)w; }
+    WRAP("glTexImage2D", r_ti2, w_ti2)
+    WRAP("glTexImage3D", r_ti3, w_ti3)
+    WRAP("glTexStorage2D", r_ts2, w_ts2)
+    WRAP("glTexStorage3D", r_ts3, w_ts3)
+    WRAP("glTexStorage2DMultisample", r_ts2ms, w_ts2ms)
+    WRAP("glTexStorage3DMultisample", r_ts3ms, w_ts3ms)
+    WRAP("glRenderbufferStorage", r_rbs, w_rbs)
+    WRAP("glRenderbufferStorageMultisample", r_rbsms, w_rbsms)
+#undef WRAP
+    return fn;
+}
@@ -13,9 +13,14 @@

 #define LOG(...) __android_log_print(ANDROID_LOG_INFO, "GLShim", __VA_ARGS__)

-static const char *const hidden[] = {
+static const char *const hidden_multiview[] = {
    "GL_OVR_multiview", "GL_OVR_multiview2", "GL_OVR_multiview_multisampled_render_to_texture",
+};
+// multisampled render-to-texture: Unity renders a runtime MSAA eye buffer through it, which crashes Zink (SIGSEGV in
+// libgallium_dri.so, e.g. The Room VR); hidden, Unity uses an ordinary MSAA renderbuffer + resolve
+static const char *const hidden_msrtt[] = {
    "GL_EXT_multisampled_render_to_texture", "GL_EXT_multisampled_render_to_texture2",
+    "GL_OVR_multiview_multisampled_render_to_texture",
 };

 static void *gles;
@@ -25,23 +30,47 @@ 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;
+static int hide_multiview = -1;  // -1: not set (Unity keeps multiview, everything else hides it)
+static int hide_msrtt = 1;

-static void read_conf(void) {
-    char pkg[256] = {0}, path[512];
-    FILE *f = fopen("/proc/self/cmdline", "r");
+static void read_conf_file(const char *path) {
+    FILE *f = fopen(path, "r");
    if (!f) return;
-    size_t n = fread(pkg, 1, sizeof(pkg) - 1, f);
+    char line[256];
+    while (fgets(line, sizeof(line), f)) {
+        if (!strncmp(line, "gl_hide_multiview=", 18)) hide_multiview = atoi(line + 18);
+        if (!strncmp(line, "gl_hide_msrtt=", 14)) hide_msrtt = atoi(line + 14);
+    }
    fclose(f);
-    pkg[n] = 0;
+}
+
+// The same settings sources as FrameBridge, later ones winning: the build's libframe_settings.so (next to this
+// library), the game's framebridge.conf, then FRAMEBRIDGE_CONFIG (Lepton's per-game settings.conf).
+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;
-    snprintf(path, sizeof(path), "/sdcard/Android/data/%s/files/framebridge.conf", pkg);
-    if (!(f = fopen(path, "r"))) return;
-    char line[128];
-    while (fgets(line, sizeof(line), f))
-        if (!strncmp(line, "gl_hide_multiview=", 18)) hide_multiview = atoi(line + 18);
-    fclose(f);
+    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);
 }

 // Logging wrappers for the framebuffer calls engines use for eye buffers.
@@ -306,13 +335,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;
-    LOG("GL shim active: hide_multiview=%d", hide_multiview);
+    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);
+    }
+    LOG("GL shim active: hide_multiview=%d hide_msrtt=%d", hide_multiview, hide_msrtt);
 }

 static int is_hidden(const char *name) {
-    if (!hide_multiview) return 0;
-    for (size_t i = 0; i < sizeof(hidden) / sizeof(hidden[0]); ++i)
-        if (!strcmp(name, hidden[i])) return 1;
+    if (hide_multiview)
+        for (size_t i = 0; i < sizeof(hidden_multiview) / sizeof(hidden_multiview[0]); ++i)
+            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;
    return 0;
 }

@@ -0,0 +1,913 @@
+// SPDX-License-Identifier: GPL-3.0-only
+//
+// FramePort language packs: answers the Meta Platform SDK's language-pack calls from `*.lang` files that already
+// sit in the game's data (OBB / app files), without any download.
+//
+// Why: OVRPort's libovrplatformloader.so is a dispatcher in front of Meta's own loader (…_meta.so). It answers
+// ovr_LanguagePack_GetCurrent / ovr_LanguagePack_SetCurrent with `return 0` (request id 0, no message ever comes
+// back), so a game that asks for its language pack waits for an answer that never arrives.
+//
+// How it is wired (patch frame.langpacks):
+//   * this library becomes the first DT_NEEDED of the dispatcher;
+//   * the dispatcher's own exports of the functions defined here are marked STB_LOCAL in its .dynsym, so symbol
+//     lookups (the game's imports and dlsym on the dispatcher's handle) continue to this library;
+//   * everything we do not answer ourselves is forwarded to the dispatcher's original function, found at run time by
+//     reading the dispatcher's in-memory .dynsym (the entries are still there, only no longer visible to lookups).
+//
+// What it implements (see https://developers.meta.com/vr/documentation/native/ps-language-packs/):
+//   ovr_LanguagePack_GetCurrent / SetCurrent        answered here
+//   ovr_AssetFile_GetList                           the dispatcher's list + our packs (type "language_pack")
+//   ovr_AssetFile_StatusById                        answered here for our packs (always "installed")
+//   ovr_PopMessage, ovr_FreeMessage, ovr_Message_*, ovr_AssetDetails*_*, ovr_LanguagePackInfo_*,
+//   ovr_AssetFileDownloadResult_*, ovr_Error_*      wrappers: our messages/handles are served here, any other
+//                                                   handle goes to the dispatcher unchanged
+//
+// Where the packs are looked for (first file per tag wins; depth <= 3):
+//   $FRAMEPORT_LANGPACK_DIRS (':'-separated), otherwise
+//   /sdcard/Android/obb/<pkg>, /sdcard/Android/data/<pkg>/files, the same under /storage/emulated/0, and
+//   /data/steam_app/obb (where Lepton mounts the host's obb folder)
+// A pack is a regular file named <BCP47 tag>.lang (de.lang -> tag "de").
+//
+// Which pack is "current": the one the game applied with SetCurrent; else $FRAMEPORT_LANGPACK (a tag); else the only
+// pack if there is exactly one.
+#define _GNU_SOURCE
+#include <ctype.h>
+#include <dirent.h>
+#include <dlfcn.h>
+#include <elf.h>
+#include <link.h>
+#include <pthread.h>
+#include <stdarg.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <strings.h>
+#include <sys/stat.h>
+#include <time.h>
+#include <unistd.h>
+#ifdef __ANDROID__
+#include <android/log.h>
+#endif
+
+#define EXPORT __attribute__((visibility("default")))
+
+typedef uint64_t u64;
+typedef uint32_t u32;
+
+// Log line (logcat tag "fp_langpack" on Android, so it lands in the game's launch.log; on other systems stderr, only
+// when $FRAMEPORT_LANGPACK_DEBUG is set).
+static void fplog(const char *fmt, ...) __attribute__((format(printf, 1, 2)));
+static void fplog(const char *fmt, ...) {
+    char line[512];
+    va_list ap;
+    va_start(ap, fmt);
+    vsnprintf(line, sizeof line, fmt, ap);
+    va_end(ap);
+#ifdef __ANDROID__
+    __android_log_print(ANDROID_LOG_INFO, "fp_langpack", "%s", line);
+#else
+    if (getenv("FRAMEPORT_LANGPACK_DEBUG")) fprintf(stderr, "fp_langpack: %s\n", line);
+#endif
+}
+
+// accessor calls can repeat every frame: only the first FP_TRACE_MAX are logged
+#define FP_TRACE_MAX 400
+static int g_traced;
+#define fptrace(...) \
+    do { \
+        if (__atomic_fetch_add(&g_traced, 1, __ATOMIC_RELAXED) < FP_TRACE_MAX) fplog(__VA_ARGS__); \
+    } while (0)
+
+// how long the dispatcher gets to answer AssetFile_GetList before we answer with our packs alone
+#ifndef FP_LIST_TIMEOUT_MS
+#define FP_LIST_TIMEOUT_MS 1500
+#endif
+
+#ifndef FP_LOADER_BASENAME
+#define FP_LOADER_BASENAME "libovrplatformloader.so"
+#endif
+
+// ovrMessageType values (same table as native/platformcompat/message_type.cpp)
+#define MSG_ASSETFILE_GETLIST 0x4AFC6F74u
+#define MSG_ASSETFILE_STATUSBYID 0x5D955D38u
+#define MSG_LANGUAGEPACK_GETCURRENT 0x1F90F0D5u
+#define MSG_LANGUAGEPACK_SETCURRENT 0x5B4FBBE0u
+
+#define MAXP 32
+#define PATHLEN 1024
+#define MAX_DEPTH 3
+
+/* ---------------------------------------------------------------------------------------------------------------
+ * Finding the dispatcher's original functions
+ * ------------------------------------------------------------------------------------------------------------- */
+
+typedef struct {
+    const char *name;
+    void *addr;
+} find_t;
+
+static uintptr_t fixptr(uintptr_t base, uintptr_t v) {
+    // bionic leaves d_ptr as a link-time address, glibc adds the load bias in place
+    return v < base ? base + v : v;
+}
+
+static size_t count_syms(uintptr_t base, const ElfW(Dyn) *dyn) {
+    const uint32_t *gnu = NULL, *sysv = NULL;
+    for (const ElfW(Dyn) *d = dyn; d->d_tag != DT_NULL; d++) {
+        if (d->d_tag == DT_GNU_HASH) gnu = (const uint32_t *)fixptr(base, d->d_un.d_ptr);
+        if (d->d_tag == DT_HASH) sysv = (const uint32_t *)fixptr(base, d->d_un.d_ptr);
+    }
+    if (sysv) return sysv[1];  // nchain
+    if (!gnu) return 0;
+    uint32_t nbuckets = gnu[0], symoffset = gnu[1], bloom_size = gnu[2];
+    const uint32_t *buckets = gnu + 4 + bloom_size * (sizeof(ElfW(Addr)) / 4);
+    const uint32_t *chains = buckets + nbuckets;
+    uint32_t max = 0;
+    for (uint32_t i = 0; i < nbuckets; i++)
+        if (buckets[i] > max) max = buckets[i];
+    if (max < symoffset) return symoffset;
+    while (!(chains[max - symoffset] & 1)) max++;
+    return (size_t)max + 1;
+}
+
+static int find_cb(struct dl_phdr_info *info, size_t size, void *data) {
+    (void)size;
+    find_t *f = (find_t *)data;
+    const char *n = info->dlpi_name ? info->dlpi_name : "";
+    const char *slash = strrchr(n, '/');
+    if (strcmp(slash ? slash + 1 : n, FP_LOADER_BASENAME) != 0) return 0;
+    uintptr_t base = info->dlpi_addr;
+    const ElfW(Dyn) *dyn = NULL;
+    for (int i = 0; i < info->dlpi_phnum; i++)
+        if (info->dlpi_phdr[i].p_type == PT_DYNAMIC) dyn = (const ElfW(Dyn) *)(base + info->dlpi_phdr[i].p_vaddr);
+    if (!dyn) return 1;
+    const ElfW(Sym) *symtab = NULL;
+    const char *strtab = NULL;
+    for (const ElfW(Dyn) *d = dyn; d->d_tag != DT_NULL; d++) {
+        if (d->d_tag == DT_SYMTAB) symtab = (const ElfW(Sym) *)fixptr(base, d->d_un.d_ptr);
+        if (d->d_tag == DT_STRTAB) strtab = (const char *)fixptr(base, d->d_un.d_ptr);
+    }
+    size_t n_syms = count_syms(base, dyn);
+    if (!symtab || !strtab || !n_syms) return 1;
+    for (size_t i = 1; i < n_syms; i++) {
+        const ElfW(Sym) *s = &symtab[i];
+        if (s->st_shndx == SHN_UNDEF || s->st_value == 0) continue;
+        if (ELF64_ST_TYPE(s->st_info) != STT_FUNC) continue;
+        if (strcmp(strtab + s->st_name, f->name) == 0) {
+            f->addr = (void *)(base + s->st_value);
+            break;
+        }
+    }
+    return 1;
+}
+
+static void *orig_sym(const char *name) {
+    find_t f = {name, NULL};
+    dl_iterate_phdr(find_cb, &f);
+    return f.addr;
+}
+
+// o_<Name>(...) calls the dispatcher's original ovr_<Name>; 0/NULL when it has none
+#define DEFORIG(RET, NAME, PARAMS, ARGS)                       \
+    static RET o_##NAME PARAMS {                               \
+        typedef RET(*fn_t) PARAMS;                             \
+        static fn_t f;                                         \
+        static int tried;                                      \
+        if (!tried) {                                          \
+            f = (fn_t)orig_sym("ovr_" #NAME);                  \
+            tried = 1;                                         \
+        }                                                      \
+        return f ? f ARGS : (RET)0;                            \
+    }
+
+DEFORIG(void *, PopMessage, (void), ())
+DEFORIG(void, FreeMessage, (void *m), (m))
+DEFORIG(u32, Message_GetType, (const void *m), (m))
+DEFORIG(u64, Message_GetRequestID, (const void *m), (m))
+DEFORIG(_Bool, Message_IsError, (const void *m), (m))
+DEFORIG(void *, Message_GetError, (const void *m), (m))
+DEFORIG(void *, Message_GetAssetDetails, (const void *m), (m))
+DEFORIG(void *, Message_GetAssetDetailsArray, (const void *m), (m))
+DEFORIG(void *, Message_GetAssetFileDownloadResult, (const void *m), (m))
+DEFORIG(size_t, AssetDetailsArray_GetSize, (const void *a), (a))
+DEFORIG(void *, AssetDetailsArray_GetElement, (const void *a, size_t i), (a, i))
+DEFORIG(u64, AssetDetails_GetAssetId, (const void *d), (d))
+DEFORIG(const char *, AssetDetails_GetAssetType, (const void *d), (d))
+DEFORIG(const char *, AssetDetails_GetDownloadStatus, (const void *d), (d))
+DEFORIG(const char *, AssetDetails_GetFilepath, (const void *d), (d))
+DEFORIG(const char *, AssetDetails_GetIapStatus, (const void *d), (d))
+DEFORIG(void *, AssetDetails_GetLanguage, (const void *d), (d))
+DEFORIG(const char *, AssetDetails_GetMetadata, (const void *d), (d))
+DEFORIG(const char *, LanguagePackInfo_GetTag, (const void *l), (l))
+DEFORIG(const char *, LanguagePackInfo_GetEnglishName, (const void *l), (l))
+DEFORIG(const char *, LanguagePackInfo_GetNativeName, (const void *l), (l))
+DEFORIG(u64, AssetFileDownloadResult_GetAssetId, (const void *r), (r))
+DEFORIG(const char *, AssetFileDownloadResult_GetFilepath, (const void *r), (r))
+DEFORIG(u64, AssetFile_GetList, (void), ())
+DEFORIG(u64, AssetFile_StatusById, (u64 id), (id))
+DEFORIG(int, Error_GetCode, (const void *e), (e))
+DEFORIG(int, Error_GetHttpCode, (const void *e), (e))
+DEFORIG(const char *, Error_GetMessage, (const void *e), (e))
+DEFORIG(const char *, Error_GetDisplayableMessage, (const void *e), (e))
+
+/* ---------------------------------------------------------------------------------------------------------------
+ * Finding the packs
+ * ------------------------------------------------------------------------------------------------------------- */
+
+typedef struct {
+    char tag[48];
+    char path[PATHLEN];
+    u64 id;
+} pack_t;
+
+static const struct {
+    const char *tag, *en, *native;
+} NAMES[] = {
+    {"en", "English", "English"},      {"de", "German", "Deutsch"},        {"fr", "French", "Français"},
+    {"es", "Spanish", "Español"},      {"it", "Italian", "Italiano"},      {"pt", "Portuguese", "Português"},
+    {"nl", "Dutch", "Nederlands"},     {"pl", "Polish", "Polski"},         {"ru", "Russian", "Русский"},
+    {"tr", "Turkish", "Türkçe"},       {"ja", "Japanese", "日本語"},        {"ko", "Korean", "한국어"},
+    {"zh", "Chinese", "中文"},          {"ar", "Arabic", "العربية"},        {"cs", "Czech", "Čeština"},
+    {"sv", "Swedish", "Svenska"},      {"da", "Danish", "Dansk"},          {"fi", "Finnish", "Suomi"},
+    {"nb", "Norwegian", "Norsk"},      {"hu", "Hungarian", "Magyar"},      {"uk", "Ukrainian", "Українська"},
+    {"el", "Greek", "Ελληνικά"},       {"he", "Hebrew", "עברית"},          {"th", "Thai", "ไทย"},
+    {"id", "Indonesian", "Indonesia"}, {"vi", "Vietnamese", "Tiếng Việt"}, {"ro", "Romanian", "Română"},
+};
+
+static u64 hash_tag(const char *tag) {
+    u64 h = 1469598103934665603ULL;  // FNV-1a over the lower-case tag
+    for (const char *p = tag; *p; p++) {
+        h ^= (unsigned char)((*p >= 'A' && *p <= 'Z') ? *p + 32 : *p);
+        h *= 1099511628211ULL;
+    }
+    return 0x4650000000000000ULL | (h & 0x0000FFFFFFFFFFFFULL);  // 'FP' prefix: never a store asset id
+}
+
+static int tag_eq(const char *a, const char *b) { return strcasecmp(a, b) == 0; }
+
+static int base_len(const char *tag) {
+    int n = 0;
+    while (tag[n] && tag[n] != '-' && tag[n] != '_') n++;
+    return n;
+}
+
+static int valid_tag(const char *t) {
+    if (!*t) return 0;
+    for (; *t; t++)
+        if (!((*t >= 'a' && *t <= 'z') || (*t >= 'A' && *t <= 'Z') || (*t >= '0' && *t <= '9') || *t == '-' ||
+              *t == '_'))
+            return 0;
+    return 1;
+}
+
+static void add_pack(pack_t *out, int *n, const char *tag, const char *path) {
+    for (int i = 0; i < *n; i++)
+        if (tag_eq(out[i].tag, tag)) return;  // first one wins
+    pack_t *p = &out[(*n)++];
+    snprintf(p->tag, sizeof p->tag, "%s", tag);
+    snprintf(p->path, sizeof p->path, "%s", path);
+    p->id = hash_tag(tag);
+}
+
+static int g_logged_dirs;
+
+// Tags to leave out of the list (comma separated, case-insensitive): env FRAMEPORT_LANGPACK_SKIP, plus the lines
+// of a file "fp_langpack_skip" in any scanned folder. For finding out which pack a game needs reported: e.g. a game
+// whose built-in language works without being a "pack".
+static __thread char g_skip[160];  // per thread: scans may run on several game threads at once
+
+static void read_skip_file(const char *dir) {
+    char path[PATHLEN], line[160];
+    if (snprintf(path, sizeof path, "%s/fp_langpack_skip", dir) >= (int)sizeof path) return;
+    FILE *f = fopen(path, "r");
+    if (!f) return;
+    size_t n = fread(line, 1, sizeof line - 1, f);
+    fclose(f);
+    line[n] = 0;
+    for (char *c = line; *c; c++)
+        if (*c == '\n' || *c == '\r' || *c == ' ') *c = ',';
+    size_t have = strlen(g_skip), room = sizeof g_skip - have;
+    if (room > 3) snprintf(g_skip + have, room, ",%.*s,", (int)room - 3, line);
+}
+
+static int skipped(const char *tag) {
+    char want[64], have[sizeof g_skip + 2];
+    snprintf(want, sizeof want, ",%s,", tag);
+    snprintf(have, sizeof have, ",%s,%s", getenv("FRAMEPORT_LANGPACK_SKIP") ? getenv("FRAMEPORT_LANGPACK_SKIP") : "",
+             g_skip);
+    for (char *c = want; *c; c++) *c = (char)tolower((unsigned char)*c);
+    for (char *c = have; *c; c++) *c = (char)tolower((unsigned char)*c);
+    return strstr(have, want) != NULL;
+}
+
+static void scan_dir(const char *dir, int depth, pack_t *out, int *n) {
+    DIR *d = opendir(dir);
+    if (d && depth == 0) read_skip_file(dir);
+    if (!g_logged_dirs && depth == 0) fplog("looking in %s: %s", dir, d ? "found" : "not readable");
+    if (!d) return;
+    struct dirent *e;
+    while (*n < MAXP && (e = readdir(d)) != NULL) {
+        if (e->d_name[0] == '.') continue;
+        char path[PATHLEN];
+        if (snprintf(path, sizeof path, "%s/%s", dir, e->d_name) >= (int)sizeof path) continue;
+        struct stat st;
+        if (stat(path, &st) != 0) continue;
+        if (S_ISDIR(st.st_mode)) {
+            if (depth < MAX_DEPTH) scan_dir(path, depth + 1, out, n);
+        } else if (S_ISREG(st.st_mode)) {
+            size_t len = strlen(e->d_name);
+            if (len > 5 && strcasecmp(e->d_name + len - 5, ".lang") == 0) {
+                char tag[48];
+                if (len - 5 >= sizeof tag) continue;
+                memcpy(tag, e->d_name, len - 5);
+                tag[len - 5] = 0;
+                if (valid_tag(tag) && !skipped(tag)) add_pack(out, n, tag, path);
+            }
+        }
+    }
+    closedir(d);
+}
+
+static void package_name(char *out, size_t cap) {
+    out[0] = 0;
+    FILE *f = fopen("/proc/self/cmdline", "r");
+    if (!f) return;
+    size_t n = fread(out, 1, cap - 1, f);
+    fclose(f);
+    out[n] = 0;  // argv[0] ends at the first NUL: the package (or package:process)
+    char *colon = strchr(out, ':');
+    if (colon) *colon = 0;
+}
+
+static int scan_dirs(pack_t *out);
+
+static int scan(pack_t *out) {
+    int n = scan_dirs(out);
+    static int last = -1;
+    if (n != last) {
+        last = n;
+        fplog("%d language pack(s) found", n);
+        for (int i = 0; i < n; i++) fplog("  pack %s -> %s", out[i].tag, out[i].path);
+    }
+    g_logged_dirs = 1;
+    return n;
+}
+
+static int scan_dirs(pack_t *out) {
+    int n = 0;
+    g_skip[0] = 0;  // read again from the folders below
+    const char *dirs = getenv("FRAMEPORT_LANGPACK_DIRS");
+    if (dirs && *dirs) {
+        char buf[PATHLEN * 2];
+        snprintf(buf, sizeof buf, "%s", dirs);
+        for (char *save = NULL, *p = strtok_r(buf, ":", &save); p; p = strtok_r(NULL, ":", &save)) scan_dir(p, 0, out, &n);
+        return n;
+    }
+    char pkg[256];
+    package_name(pkg, sizeof pkg);
+    if (!g_logged_dirs) fplog("package \"%s\"", pkg);
+    if (!pkg[0] || strchr(pkg, '/')) return 0;
+    // Unreal names the files of an Android game by their /storage/emulated/0 path (its own OBB mount does), so that
+    // spelling comes first: a pack found in both gets the path the engine would use itself.
+    static const char *const FORMATS[] = {"/storage/emulated/0/Android/obb/%s",
+                                          "/storage/emulated/0/Android/data/%s/files", "/sdcard/Android/obb/%s",
+                                          "/sdcard/Android/data/%s/files"};
+    for (size_t i = 0; i < sizeof FORMATS / sizeof *FORMATS; i++) {
+        char dir[PATHLEN];
+        snprintf(dir, sizeof dir, FORMATS[i], pkg);
+        scan_dir(dir, 0, out, &n);
+    }
+    // Lepton mounts the host's <app>/lepton-app/obb here (read-only) and only links /sdcard/Android/obb/<pkg> to it
+    // at boot (liblepton/mounting.sh: podman_mount_entry "$LEPTON_MOUNT_OBB_DIR" "/$APP_MOUNT_TARGET/obb", default
+    // APP_MOUNT_TARGET=data/steam_app), so look there too.
+    scan_dir("/data/steam_app/obb", 0, out, &n);
+    return n;
+}
+
+static pthread_mutex_t g_lock = PTHREAD_MUTEX_INITIALIZER;
+static char g_current[48];  // tag the game applied with SetCurrent
+
+static int find_tag(const pack_t *p, int n, const char *tag) {
+    for (int i = 0; i < n; i++)
+        if (tag_eq(p[i].tag, tag)) return i;
+    int bl = base_len(tag);  // "de-DE" -> "de" (and the reverse: "de" asked, "de-de" present)
+    for (int i = 0; i < n; i++)
+        if (base_len(p[i].tag) == bl && strncasecmp(p[i].tag, tag, (size_t)bl) == 0) return i;
+    return -1;
+}
+
+static int pick_current(const pack_t *p, int n) {
+    char want[48] = "";
+    pthread_mutex_lock(&g_lock);
+    snprintf(want, sizeof want, "%s", g_current);
+    pthread_mutex_unlock(&g_lock);
+    if (want[0]) {
+        int i = find_tag(p, n, want);
+        if (i >= 0) return i;
+    }
+    const char *env = getenv("FRAMEPORT_LANGPACK");
+    if (env && *env) {
+        int i = find_tag(p, n, env);
+        if (i >= 0) return i;
+    }
+    return n == 1 ? 0 : -1;
+}
+
+/* ---------------------------------------------------------------------------------------------------------------
+ * Messages and handles. Every object we hand out lives inside one msg_t, so "is this handle ours" is an address
+ * range check against the live messages.
+ * ------------------------------------------------------------------------------------------------------------- */
+
+// The asset's Metadata. Deadpool VR (Unreal) only accepts a language pack whose Metadata equals its own version string
+// ("1.0.40.356975.Quest", built from five parts with "%s.%s.%s.%s.%s"), which Meta's store sets at upload. The
+// patch writes the game's versionName behind the marker below (frame.langpacks, frameport.patches.frame.langpack);
+// FRAMEPORT_LANGPACK_META overrides it. Without either the Metadata stays empty, as before.
+#define META_LEN 96
+#define META_MARK "@FPMETA@"
+__attribute__((used)) static char g_meta_slot[sizeof META_MARK + META_LEN] = META_MARK;
+
+static void pack_meta(char *out) {
+    const char *env = getenv("FRAMEPORT_LANGPACK_META");
+    const volatile char *slot = g_meta_slot + sizeof META_MARK;
+    out[0] = 0;
+    if (env && *env) snprintf(out, META_LEN, "%s", env);
+    else {
+        int i = 0;
+        for (; i < META_LEN - 1 && slot[i]; i++) out[i] = slot[i];
+        out[i] = 0;
+    }
+}
+
+typedef struct {
+    char tag[48], en[64], nat[64];
+} lang_t;
+
+typedef struct {
+    u64 id;
+    char type[16], status[16], iap[8], meta[META_LEN];
+    char path[PATHLEN];
+    lang_t *lang;
+} details_t;
+
+typedef struct {
+    u64 id;
+    char path[PATHLEN];
+} result_t;
+
+typedef struct {
+    int code, http;
+    char msg[128];
+} err_t;
+
+typedef struct msg {
+    struct msg *all_next, *q_next;
+    u32 type;
+    u64 req;
+    int is_error, has_det, has_res;
+    err_t err;
+    details_t det;
+    lang_t lng;
+    result_t res;
+    u32 arr;  // its address is the handle of the details array
+    int n;
+    details_t dets[MAXP];
+    lang_t langs[MAXP];
+    void *orig_msg, *orig_arr;
+    size_t orig_n;
+} msg_t;
+
+static msg_t *g_all, *g_qhead, *g_qtail;
+static u64 g_next_req = 0x4650000000000001ULL;
+#define MAX_PENDING 16
+static u64 g_pending[MAX_PENDING];
+static u64 g_pending_ms[MAX_PENDING];
+static u64 g_expired[MAX_PENDING];  // requests we answered ourselves after the timeout: their late answer is dropped
+static int g_expired_next;  // when each one was asked  // dispatcher requests whose AssetFile_GetList answer we extend
+
+static msg_t *owner(const void *p) {
+    msg_t *found = NULL;
+    pthread_mutex_lock(&g_lock);
+    for (msg_t *m = g_all; m; m = m->all_next)
+        if ((const char *)p >= (const char *)m && (const char *)p < (const char *)m + sizeof *m) {
+            found = m;
+            break;
+        }
+    pthread_mutex_unlock(&g_lock);
+    return found;
+}
+
+static msg_t *new_msg(u32 type, u64 req) {
+    msg_t *m = (msg_t *)calloc(1, sizeof *m);
+    if (!m) return NULL;
+    m->type = type;
+    m->req = req ? req : __atomic_fetch_add(&g_next_req, 1, __ATOMIC_RELAXED);
+    pthread_mutex_lock(&g_lock);
+    m->all_next = g_all;
+    g_all = m;
+    pthread_mutex_unlock(&g_lock);
+    return m;
+}
+
+static void post(msg_t *m) {
+    pthread_mutex_lock(&g_lock);
+    m->q_next = NULL;
+    if (g_qtail) g_qtail->q_next = m;
+    else g_qhead = m;
+    g_qtail = m;
+    pthread_mutex_unlock(&g_lock);
+}
+
+static void fail(msg_t *m, int code, const char *text) {
+    m->is_error = 1;
+    m->err.code = code;
+    snprintf(m->err.msg, sizeof m->err.msg, "%s", text);
+}
+
+static void fill_details(details_t *d, lang_t *l, const pack_t *p) {
+    d->id = p->id;
+    snprintf(d->type, sizeof d->type, "language_pack");
+    snprintf(d->status, sizeof d->status, "installed");
+    snprintf(d->iap, sizeof d->iap, "free");
+    snprintf(d->path, sizeof d->path, "%s", p->path);
+    pack_meta(d->meta);
+    snprintf(l->tag, sizeof l->tag, "%s", p->tag);
+    snprintf(l->en, sizeof l->en, "%s", p->tag);
+    snprintf(l->nat, sizeof l->nat, "%s", p->tag);
+    int bl = base_len(p->tag);
+    for (size_t i = 0; i < sizeof NAMES / sizeof *NAMES; i++)
+        if ((int)strlen(NAMES[i].tag) == bl && strncasecmp(NAMES[i].tag, p->tag, (size_t)bl) == 0) {
+            snprintf(l->en, sizeof l->en, "%s", NAMES[i].en);
+            snprintf(l->nat, sizeof l->nat, "%s", NAMES[i].native);
+            break;
+        }
+    d->lang = l;
+}
+
+static u64 now_ms(void) {
+    struct timespec t;
+    clock_gettime(CLOCK_MONOTONIC, &t);
+    return (u64)t.tv_sec * 1000u + (u64)t.tv_nsec / 1000000u;
+}
+
+static int take_pending(u64 req) {
+    int hit = 0;
+    pthread_mutex_lock(&g_lock);
+    for (int i = 0; i < MAX_PENDING; i++)
+        if (g_pending[i] == req) {
+            g_pending[i] = 0;
+            hit = 1;
+            break;
+        }
+    pthread_mutex_unlock(&g_lock);
+    return hit;
+}
+
+static int take_expired(u64 req) {
+    int hit = 0;
+    pthread_mutex_lock(&g_lock);
+    for (int i = 0; i < MAX_PENDING; i++)
+        if (req && g_expired[i] == req) {
+            g_expired[i] = 0;
+            hit = 1;
+            break;
+        }
+    pthread_mutex_unlock(&g_lock);
+    return hit;
+}
+
+static void add_pending(u64 req) {
+    pthread_mutex_lock(&g_lock);
+    for (int i = 0; i < MAX_PENDING; i++)
+        if (!g_pending[i]) {
+            g_pending[i] = req;
+            g_pending_ms[i] = now_ms();
+            break;
+        }
+    pthread_mutex_unlock(&g_lock);
+}
+
+static void fill_list(msg_t *m, const pack_t *p, int n) {
+    for (int i = 0; i < n && i < MAXP; i++) fill_details(&m->dets[i], &m->langs[i], &p[i]);
+    m->n = n < MAXP ? n : MAXP;
+}
+
+// The dispatcher's AssetFile_GetList answer arrived: ours + theirs in one array.
+static void *wrap_list(void *orig) {
+    pack_t packs[MAXP];
+    int n = scan(packs);
+    if (n == 0) return orig;
+    msg_t *m = new_msg(MSG_ASSETFILE_GETLIST, o_Message_GetRequestID(orig));
+    if (!m) return orig;
+    fill_list(m, packs, n);
+    m->orig_msg = orig;
+    if (!o_Message_IsError(orig)) {
+        m->orig_arr = o_Message_GetAssetDetailsArray(orig);
+        if (m->orig_arr) m->orig_n = o_AssetDetailsArray_GetSize(m->orig_arr);
+    }
+    return m;
+}
+
+// A GetList the dispatcher has not answered within FP_LIST_TIMEOUT_MS: answer with our packs alone (request id kept).
+// Returns NULL if nothing is overdue or no pack exists (then a late answer from the dispatcher still reaches the
+// game); once we answered, the dispatcher's late answer is dropped (ovr_PopMessage), so the game gets one answer.
+static msg_t *expire_pending(void) {
+    u64 req = 0, now = now_ms();
+    pthread_mutex_lock(&g_lock);
+    for (int i = 0; i < MAX_PENDING; i++)
+        if (g_pending[i] && now - g_pending_ms[i] >= FP_LIST_TIMEOUT_MS) {
+            req = g_pending[i];
+            g_pending[i] = 0;
+            break;
+        }
+    pthread_mutex_unlock(&g_lock);
+    if (!req) return NULL;
+    pack_t packs[MAXP];
+    int n = scan(packs);
+    fplog("AssetFile_GetList %llu: no answer after %d ms, answering with %d pack(s)", (unsigned long long)req,
+          FP_LIST_TIMEOUT_MS, n);
+    if (n == 0) return NULL;
+    msg_t *m = new_msg(MSG_ASSETFILE_GETLIST, req);
+    if (!m) return NULL;
+    fill_list(m, packs, n);
+    pthread_mutex_lock(&g_lock);
+    g_expired[g_expired_next] = req;
+    g_expired_next = (g_expired_next + 1) % MAX_PENDING;
+    pthread_mutex_unlock(&g_lock);
+    return m;
+}
+
+/* ---------------------------------------------------------------------------------------------------------------
+ * Requests
+ * ------------------------------------------------------------------------------------------------------------- */
+
+EXPORT u64 ovr_LanguagePack_GetCurrent(void) {
+    pack_t packs[MAXP];
+    int n = scan(packs), i = pick_current(packs, n);
+    fplog("LanguagePack_GetCurrent -> %s", i >= 0 ? packs[i].tag : "none applied");
+    msg_t *m = new_msg(MSG_LANGUAGEPACK_GETCURRENT, 0);
+    if (!m) return 0;
+    u64 req = m->req;
+    if (i < 0) {
+        fail(m, 404, "no language pack is applied");
+    } else {
+        fill_details(&m->det, &m->lng, &packs[i]);
+        m->has_det = 1;
+    }
+    post(m);
+    return req;
+}
+
+EXPORT u64 ovr_LanguagePack_SetCurrent(const char *tag) {
+    pack_t packs[MAXP];
+    int n = scan(packs), i = (tag && *tag) ? find_tag(packs, n, tag) : -1;
+    fplog("LanguagePack_SetCurrent(\"%s\") -> %s", tag ? tag : "(null)", i >= 0 ? packs[i].path : "not available");
+    msg_t *m = new_msg(MSG_LANGUAGEPACK_SETCURRENT, 0);
+    if (!m) return 0;
+    u64 req = m->req;
+    if (i < 0) {
+        fail(m, 404, "language pack not available on this device");
+    } else {
+        pthread_mutex_lock(&g_lock);
+        snprintf(g_current, sizeof g_current, "%s", packs[i].tag);
+        pthread_mutex_unlock(&g_lock);
+        m->res.id = packs[i].id;
+        snprintf(m->res.path, sizeof m->res.path, "%s", packs[i].path);
+        m->has_res = 1;
+    }
+    post(m);
+    return req;
+}
+
+EXPORT u64 ovr_AssetFile_GetList(void) {
+    u64 req = o_AssetFile_GetList();
+    fplog("AssetFile_GetList (dispatcher request %llu)", (unsigned long long)req);
+    if (req) {
+        add_pending(req);
+        return req;
+    }
+    // no dispatcher function behind us: answer with our packs alone
+    pack_t packs[MAXP];
+    int n = scan(packs);
+    msg_t *m = new_msg(MSG_ASSETFILE_GETLIST, 0);
+    if (!m) return 0;
+    req = m->req;
+    fill_list(m, packs, n);
+    post(m);
+    return req;
+}
+
+EXPORT u64 ovr_AssetFile_StatusById(u64 id) {
+    fplog("AssetFile_StatusById(%llu)%s", (unsigned long long)id, (id >> 48) == 0x4650 ? " (ours)" : "");
+    if ((id >> 48) == 0x4650) {
+        pack_t packs[MAXP];
+        int n = scan(packs);
+        for (int i = 0; i < n; i++)
+            if (packs[i].id == id) {
+                msg_t *m = new_msg(MSG_ASSETFILE_STATUSBYID, 0);
+                if (!m) return 0;
+                u64 req = m->req;
+                fill_details(&m->det, &m->lng, &packs[i]);
+                m->has_det = 1;
+                post(m);
+                return req;
+            }
+        msg_t *m = new_msg(MSG_ASSETFILE_STATUSBYID, 0);
+        if (!m) return 0;
+        u64 req = m->req;
+        fail(m, 404, "asset file not found");
+        post(m);
+        return req;
+    }
+    return o_AssetFile_StatusById(id);
+}
+
+/* ---------------------------------------------------------------------------------------------------------------
+ * Message loop
+ * ------------------------------------------------------------------------------------------------------------- */
+
+EXPORT void *ovr_PopMessage(void) {
+    pthread_mutex_lock(&g_lock);
+    msg_t *m = g_qhead;
+    if (m) {
+        g_qhead = m->q_next;
+        if (!g_qhead) g_qtail = NULL;
+        m->q_next = NULL;
+    }
+    pthread_mutex_unlock(&g_lock);
+    if (m) return m;
+    void *o = o_PopMessage();
+    while (o && o_Message_GetType(o) == MSG_ASSETFILE_GETLIST && take_expired(o_Message_GetRequestID(o))) {
+        // we already answered this request (timeout): a second answer for the same request would reach the game twice
+        fplog("AssetFile_GetList %llu: late answer from the dispatcher dropped", (unsigned long long)o_Message_GetRequestID(o));
+        o_FreeMessage(o);
+        o = o_PopMessage();
+    }
+    if (o && o_Message_GetType(o) == MSG_ASSETFILE_GETLIST) {
+        u64 r = o_Message_GetRequestID(o);
+        if (take_pending(r)) {
+            fplog("AssetFile_GetList %llu answered by the dispatcher", (unsigned long long)r);
+            return wrap_list(o);
+        }
+    }
+    if (o) return o;
+    return expire_pending();
+}
+
+EXPORT void ovr_FreeMessage(void *h) {
+    msg_t *m = h ? owner(h) : NULL;
+    if (!m || (void *)m != h) {
+        o_FreeMessage(h);
+        return;
+    }
+    pthread_mutex_lock(&g_lock);
+    for (msg_t **pp = &g_all; *pp; pp = &(*pp)->all_next)
+        if (*pp == m) {
+            *pp = m->all_next;
+            break;
+        }
+    for (msg_t **pp = &g_qhead; *pp; pp = &(*pp)->q_next)  // freed unpopped: leave the queue too
+        if (*pp == m) {
+            *pp = m->q_next;
+            break;
+        }
+    g_qtail = NULL;
+    for (msg_t *q = g_qhead; q; q = q->q_next) g_qtail = q;
+    pthread_mutex_unlock(&g_lock);
+    if (m->orig_msg) o_FreeMessage(m->orig_msg);
+    free(m);
+}
+
+EXPORT u32 ovr_Message_GetType(const void *h) {
+    msg_t *m = owner(h);
+    u32 t = m ? m->type : o_Message_GetType(h);
+    if (m) fptrace("Message_GetType(ours) = 0x%08X", t);
+    return t;
+}
+
+EXPORT u64 ovr_Message_GetRequestID(const void *h) {
+    msg_t *m = owner(h);
+    return m ? m->req : o_Message_GetRequestID(h);
+}
+
+EXPORT _Bool ovr_Message_IsError(const void *h) {
+    msg_t *m = owner(h);
+    return m ? (_Bool)m->is_error : o_Message_IsError(h);
+}
+
+EXPORT void *ovr_Message_GetError(const void *h) {
+    msg_t *m = owner(h);
+    if (!m) return o_Message_GetError(h);
+    return m->is_error ? (void *)&m->err : NULL;
+}
+
+EXPORT void *ovr_Message_GetAssetDetails(const void *h) {
+    msg_t *m = owner(h);
+    if (!m) return o_Message_GetAssetDetails(h);
+    return m->has_det ? (void *)&m->det : NULL;
+}
+
+EXPORT void *ovr_Message_GetAssetFileDownloadResult(const void *h) {
+    msg_t *m = owner(h);
+    if (!m) return o_Message_GetAssetFileDownloadResult(h);
+    return m->has_res ? (void *)&m->res : NULL;
+}
+
+EXPORT void *ovr_Message_GetAssetDetailsArray(const void *h) {
+    msg_t *m = owner(h);
+    if (!m) return o_Message_GetAssetDetailsArray(h);
+    fptrace("Message_GetAssetDetailsArray(ours)");
+    return m->type == MSG_ASSETFILE_GETLIST && !m->is_error ? (void *)&m->arr : NULL;
+}
+
+EXPORT size_t ovr_AssetDetailsArray_GetSize(const void *h) {
+    msg_t *m = owner(h);
+    size_t n = m ? (size_t)m->n + m->orig_n : o_AssetDetailsArray_GetSize(h);
+    if (m) fptrace("AssetDetailsArray_GetSize = %zu (%d ours + %zu dispatcher)", n, m->n, (size_t)m->orig_n);
+    return n;
+}
+
+EXPORT void *ovr_AssetDetailsArray_GetElement(const void *h, size_t i) {
+    msg_t *m = owner(h);
+    if (!m) return o_AssetDetailsArray_GetElement(h, i);
+    if (i < (size_t)m->n) {
+        fptrace("AssetDetailsArray_GetElement(%zu) = our pack %s", i, m->dets[i].lang ? m->dets[i].lang->tag : "?");
+        return &m->dets[i];
+    }
+    fptrace("AssetDetailsArray_GetElement(%zu) = dispatcher entry", i);
+    return m->orig_arr ? o_AssetDetailsArray_GetElement(m->orig_arr, i - (size_t)m->n) : NULL;
+}
+
+/* ---------------------------------------------------------------------------------------------------------------
+ * Accessors on our own objects (anything else goes to the dispatcher)
+ * ------------------------------------------------------------------------------------------------------------- */
+
+#define IS_OURS(h) (owner(h) != NULL)
+
+EXPORT u64 ovr_AssetDetails_GetAssetId(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetAssetId(h);
+    fptrace("AssetDetails_GetAssetId(ours) = %llu", (unsigned long long)((const details_t *)h)->id);
+    return ((const details_t *)h)->id;
+}
+EXPORT const char *ovr_AssetDetails_GetAssetType(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetAssetType(h);
+    fptrace("AssetDetails_GetAssetType(ours) = \"%s\"", ((const details_t *)h)->type);
+    return ((const details_t *)h)->type;
+}
+EXPORT const char *ovr_AssetDetails_GetDownloadStatus(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetDownloadStatus(h);
+    fptrace("AssetDetails_GetDownloadStatus(ours) = \"%s\"", ((const details_t *)h)->status);
+    return ((const details_t *)h)->status;
+}
+EXPORT const char *ovr_AssetDetails_GetFilepath(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetFilepath(h);
+    fptrace("AssetDetails_GetFilepath(ours) = \"%s\"", ((const details_t *)h)->path);
+    return ((const details_t *)h)->path;
+}
+EXPORT const char *ovr_AssetDetails_GetIapStatus(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetIapStatus(h);
+    fptrace("AssetDetails_GetIapStatus(ours) = \"%s\"", ((const details_t *)h)->iap);
+    return ((const details_t *)h)->iap;
+}
+EXPORT void *ovr_AssetDetails_GetLanguage(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetLanguage(h);
+    fptrace("AssetDetails_GetLanguage(ours)");
+    return (void *)((const details_t *)h)->lang;
+}
+EXPORT const char *ovr_AssetDetails_GetMetadata(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetMetadata(h);
+    fptrace("AssetDetails_GetMetadata(ours) = \"%s\"", ((const details_t *)h)->meta);
+    return ((const details_t *)h)->meta;
+}
+
+EXPORT const char *ovr_LanguagePackInfo_GetTag(const void *h) {
+    if (!IS_OURS(h)) return o_LanguagePackInfo_GetTag(h);
+    fptrace("LanguagePackInfo_GetTag(ours) = \"%s\"", ((const lang_t *)h)->tag);
+    return ((const lang_t *)h)->tag;
+}
+EXPORT const char *ovr_LanguagePackInfo_GetEnglishName(const void *h) {
+    if (!IS_OURS(h)) return o_LanguagePackInfo_GetEnglishName(h);
+    fptrace("LanguagePackInfo_GetEnglishName(ours) = \"%s\"", ((const lang_t *)h)->en);
+    return ((const lang_t *)h)->en;
+}
+EXPORT const char *ovr_LanguagePackInfo_GetNativeName(const void *h) {
+    if (!IS_OURS(h)) return o_LanguagePackInfo_GetNativeName(h);
+    fptrace("LanguagePackInfo_GetNativeName(ours) = \"%s\"", ((const lang_t *)h)->nat);
+    return ((const lang_t *)h)->nat;
+}
+
+EXPORT u64 ovr_AssetFileDownloadResult_GetAssetId(const void *h) {
+    return IS_OURS(h) ? ((const result_t *)h)->id : o_AssetFileDownloadResult_GetAssetId(h);
+}
+EXPORT const char *ovr_AssetFileDownloadResult_GetFilepath(const void *h) {
+    return IS_OURS(h) ? ((const result_t *)h)->path : o_AssetFileDownloadResult_GetFilepath(h);
+}
+
+EXPORT int ovr_Error_GetCode(const void *h) { return IS_OURS(h) ? ((const err_t *)h)->code : o_Error_GetCode(h); }
+EXPORT int ovr_Error_GetHttpCode(const void *h) { return IS_OURS(h) ? ((const err_t *)h)->http : o_Error_GetHttpCode(h); }
+EXPORT const char *ovr_Error_GetMessage(const void *h) {
+    return IS_OURS(h) ? ((const err_t *)h)->msg : o_Error_GetMessage(h);
+}
+EXPORT const char *ovr_Error_GetDisplayableMessage(const void *h) {
+    return IS_OURS(h) ? ((const err_t *)h)->msg : o_Error_GetDisplayableMessage(h);
+}
@@ -38,6 +38,8 @@ static void init(void) {

 #define STEP_RENDER (-1)  // ovrpStep_Render

+static void mouse_click_frame(void);  // below: controller presses as Unity mouse clicks
+
 EXPORT int fpov_Update2(int step, int frame_index, double prediction_seconds) {
    pthread_once(&once, init);
    static int last_waited = -1, logged;
@@ -45,6 +47,7 @@ EXPORT int fpov_Update2(int step, int frame_index, double prediction_seconds) {
        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);
+        mouse_click_frame();
    }
    return real_update2 ? real_update2(step, frame_index, prediction_seconds) : -1000;  // ovrpFailure
 }
@@ -116,7 +119,7 @@ static void note_state(const char *which, unsigned int mask, const State *s) {
    while (i < 8 && masks[i].seen && masks[i].mask != mask) i++;
    if (i == 8) return;
    if (!masks[i].seen || masks[i].buttons != s->words[1] || masks[i].connected != s->words[0]) {
-        if (changes++ < 120)
+        if (changes++ < 400)
            LOG("ovrp input: %s(mask 0x%x): connected 0x%x buttons 0x%x touches 0x%x%s", which, mask, s->words[0],
                s->words[1], s->words[2], masks[i].seen ? "" : " (first call with this mask)");
        masks[i].seen = 1;
@@ -140,6 +143,22 @@ EXPORT int fpov_GetControllerState4(unsigned int mask, State *state) {
    pthread_once(&input_once, input_init);
    int r = real_state4 ? real_state4(mask, state) : -1000;
    if (state) {
+        // ovrpControllerState4 continues with 4 floats after the 4 masks: L/R IndexTrigger, L/R HandTrigger. OVRInput
+        // turns them into the trigger/grip buttons at 0.5; log each time one crosses it (per requested mask)
+        const float *axis = (const float *)((const char *)state + 16);
+        static struct { unsigned int mask, bits; } seen[8];
+        static int axis_logs;
+        unsigned int bits = 0;
+        for (int k = 0; k < 4; ++k) bits |= (axis[k] >= 0.5f) << k;
+        int i = 0;
+        while (i < 8 && seen[i].mask && seen[i].mask != mask) i++;
+        if (i < 8 && (!seen[i].mask || seen[i].bits != bits)) {
+            if (seen[i].mask && axis_logs++ < 200)
+                LOG("ovrp input: State4(mask 0x%x) triggers L %.2f R %.2f grips L %.2f R %.2f", mask, axis[0], axis[1],
+                    axis[2], axis[3]);
+            seen[i].mask = mask;
+            seen[i].bits = bits;
+        }
        note_state("State4", mask, state);
        state->words[1] = unstick(state->words[1]);
    }
@@ -193,3 +212,84 @@ EXPORT int fpov_GetAppHasInputFocus(int *has_focus) {
    if (has_focus) *has_focus = 1;
    return 0;  // ovrpSuccess
 }
+
+// ---------------------------------------------------------------- controller presses as mouse clicks
+// Unity 2017-2019 games made for Go/Gear VR-era input wait for Input.GetMouseButtonDown(0/1), which a Quest delivers
+// for the controller's primary press (Accounting+'s "press any button" motion warning checks only that). Lepton runs
+// VR apps without a focused Android window, so no touch/mouse event ever arrives. IL2CPP looks engine functions up by
+// name (il2cpp_resolve_icall) on first use: this registers a replacement for UnityEngine.Input::GetMouseButtonDown
+// that returns Unity's answer, or true in the frame a Touch trigger (>= 0.5) or A/B/X/Y is newly pressed.
+#define MOUSE_ICALL "UnityEngine.Input::GetMouseButtonDown(System.Int32)"
+typedef void (*PFN_AddICall)(const char *name, const void *fn);
+typedef const void *(*PFN_ResolveICall)(const char *name);
+typedef int (*PFN_MouseDown)(int button);
+static PFN_MouseDown real_mouse_down;
+static volatile int click_now;  // set for the frame in which a press began
+
+static int fp_mouse_down(int button) {
+    int real = real_mouse_down ? real_mouse_down(button) : 0;
+    return real || ((button == 0 || button == 1) && click_now);
+}
+
+static void mouse_install(void) {
+    static int tries;
+    if (real_mouse_down || tries > 600) return;  // ~10 s of frames
+    tries++;
+    PFN_AddICall add = (PFN_AddICall)dlsym(RTLD_DEFAULT, "il2cpp_add_internal_call");
+    PFN_ResolveICall resolve = (PFN_ResolveICall)dlsym(RTLD_DEFAULT, "il2cpp_resolve_icall");
+    if (!add || !resolve) {
+        void *il2cpp = dlopen("libil2cpp.so", RTLD_NOW | RTLD_NOLOAD);
+        if (il2cpp) {
+            add = (PFN_AddICall)dlsym(il2cpp, "il2cpp_add_internal_call");
+            resolve = (PFN_ResolveICall)dlsym(il2cpp, "il2cpp_resolve_icall");
+        }
+    }
+    if (!add || !resolve) return;
+    const void *current = resolve(MOUSE_ICALL);
+    if (!current) return;  // Unity hasn't registered its own yet: try again next frame
+    real_mouse_down = (PFN_MouseDown)current;
+    add(MOUSE_ICALL, (const void *)fp_mouse_down);
+    LOG("controller presses count as mouse clicks (%s %s)", MOUSE_ICALL,
+        resolve(MOUSE_ICALL) == (const void *)fp_mouse_down ? "replaced" : "NOT replaced");
+}
+
+static void mouse_click_frame(void) {
+    mouse_install();
+    pthread_once(&input_once, input_init);
+    static int was_pressed;
+    unsigned char raw[512] __attribute__((aligned(16))) = {0};  // ovrpControllerState4 (+ room for newer layouts)
+    int pressed = 0;
+    if (real_state4 && real_state4(0x3, (State *)raw) >= 0) {
+        const unsigned int *w = (const unsigned int *)raw;
+        const float *axis = (const float *)(raw + 16);  // L/R IndexTrigger, L/R HandTrigger
+        pressed = (w[1] & 0x303u) != 0 || axis[0] >= 0.5f || axis[1] >= 0.5f;  // A, B, X, Y or a trigger
+    }
+    click_now = pressed && !was_pressed;
+    was_pressed = pressed;
+}
+
+// ---------------------------------------------------------------- hand nodes
+// Unity's built-in Oculus XR input creates its left/right controller devices (InputDevices.GetDeviceAtXRNode, the
+// Touch buttons and triggers games read through CommonUsages) for the hand nodes OVRPlugin reports as present
+// (ovrp_GetNodePresent). Logged per node; a hand node whose Touch controller is connected counts as present.
+typedef int (*PFN_NodePresent)(int node);
+#define NODE_HAND_LEFT 3
+#define NODE_HAND_RIGHT 4
+
+EXPORT int fpov_GetNodePresent(int node) {
+    static PFN_NodePresent real;
+    static int logged[16];
+    pthread_once(&input_once, input_init);
+    if (!real) {
+        void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
+        if (ovrp) real = (PFN_NodePresent)dlsym(ovrp, "ovrp_GetNodePresent");
+    }
+    int present = real ? real(node) : 0, answer = present;
+    if (!present && (node == NODE_HAND_LEFT || node == NODE_HAND_RIGHT) && real_connected)
+        answer = (real_connected() & (node == NODE_HAND_LEFT ? 0x1u : 0x2u)) != 0;  // LTouch / RTouch
+    if (node >= 0 && node < 16 && logged[node] != (answer ? 2 : 1)) {
+        logged[node] = answer ? 2 : 1;
+        LOG("ovrp node %d present: OVRPlugin %d -> Unity %d", node, present, answer);
+    }
+    return answer;
+}
@@ -0,0 +1,203 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// FramePort Meta Platform SDK tracer (diagnostics, patch frame.ovr_trace): logs the game's ovr_* calls and the
+// messages that answer them, to find a request that never gets an answer (a game waiting forever, e.g. Vader
+// Immortal after its intro). Nothing is answered or changed here: every call goes to the real function.
+//
+// Wiring: this library is the first DT_NEEDED of the game's engine library, so the engine's ovr_* imports resolve to
+// the exports below. Each export is a tiny assembly stub that saves the argument registers (x0-x8, d0-d7), asks
+// trace_before() for the real function (dlsym on the platform loader's handle, which also finds the language-pack
+// library's functions when frame.langpacks is on), calls it with the original registers, then reports the result to
+// trace_after(). Signatures don't matter (functions with more than 8 integer arguments would; the Platform SDK has
+// none). Logcat tag fp_ovrtrace.
+//
+// What is logged: the first calls of every function (argument 0 and the result), every message ovr_PopMessage
+// returns (type, request id, error flag), and every 10 s the request ids no message has answered yet with the
+// function that made them ("request" = a function whose name says it starts one: the result is kept when it looks
+// like a request id and the function isn't an accessor).
+#define _GNU_SOURCE
+#include <android/log.h>
+#include <dlfcn.h>
+#include <pthread.h>
+#include <stdint.h>
+#include <string.h>
+#include <time.h>
+
+#define TAG "fp_ovrtrace"
+#define LOG(...) __android_log_print(ANDROID_LOG_INFO, TAG, __VA_ARGS__)
+
+static const char *const NAMES[] = {
+#define N(name) #name,
+#include "names.inc"
+#undef N
+};
+#define COUNT (sizeof(NAMES) / sizeof(NAMES[0]))
+
+static void *real_fn[COUNT];
+static int calls[COUNT];
+static int is_pop[COUNT], is_request[COUNT];
+static void *loader;
+static pthread_once_t once = PTHREAD_ONCE_INIT;
+static pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;
+
+typedef uint32_t (*get_type_t)(const void *);
+typedef uint64_t (*get_id_t)(const void *);
+typedef _Bool (*is_error_t)(const void *);
+static get_type_t msg_type;
+static get_id_t msg_id;
+static is_error_t msg_error;
+
+#define PENDING 256
+static struct { uint64_t id; int fn; double t; } pending[PENDING];
+static double last_report;
+
+static double now(void) {
+    struct timespec ts;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    return ts.tv_sec + ts.tv_nsec * 1e-9;
+}
+
+// accessors read data out of handles; everything else that returns a 64-bit id starts a request
+static int looks_like_request(const char *n) {
+    static const char *const accessors[] = {"ovr_Message_", "Array_", "_Get", "_Is", "_Has", "_Create", "_Destroy",
+                                            "_Set", "_Free", "ovr_PopMessage", "ovr_Platform", "ovr_GetLoggedInUser",
+                                            "ovr_Error_", "Options_", "ovr_Voip_", "ovr_Net_", "ovr_Microphone_"};
+    for (size_t i = 0; i < sizeof(accessors) / sizeof(accessors[0]); ++i)
+        if (strstr(n, accessors[i])) return 0;
+    return 1;
+}
+
+static void init(void) {
+    loader = dlopen("libovrplatformloader.so", RTLD_NOW | RTLD_NOLOAD);
+    if (!loader) loader = dlopen("libovrplatformloader.so", RTLD_NOW);
+    for (size_t i = 0; i < COUNT; ++i) {
+        is_pop[i] = !strcmp(NAMES[i], "ovr_PopMessage");
+        is_request[i] = looks_like_request(NAMES[i]);
+        // "requests" whose names start with Get (e.g. ovr_User_GetLoggedInUser): Area_GetX with an upper-case X
+        const char *u = strchr(NAMES[i] + 4, '_');
+        if (u && !strncmp(u, "_Get", 4) && strncmp(NAMES[i], "ovr_Message_", 12) && !strstr(NAMES[i], "Array_"))
+            is_request[i] = 2;  // maybe: kept only when the result looks like a request id
+    }
+    if (loader) {
+        msg_type = (get_type_t)dlsym(loader, "ovr_Message_GetType");
+        msg_id = (get_id_t)dlsym(loader, "ovr_Message_GetRequestID");
+        msg_error = (is_error_t)dlsym(loader, "ovr_Message_IsError");
+    }
+    LOG("tracer active: %zu functions, platform loader %s", COUNT, loader ? "OK" : "MISSING");
+    last_report = now();
+}
+
+void *fp_trace_before(uint64_t idx, uint64_t arg0) __attribute__((visibility("hidden")));
+void *fp_trace_before(uint64_t idx, uint64_t arg0) {
+    pthread_once(&once, init);
+    if (idx >= COUNT) return NULL;
+    if (!real_fn[idx] && loader) real_fn[idx] = dlsym(loader, NAMES[idx]);
+    int n = __atomic_add_fetch(&calls[idx], 1, __ATOMIC_RELAXED);
+    if (n <= 3 && !is_pop[idx]) LOG("call %s(0x%llx)%s", NAMES[idx], (unsigned long long)arg0,
+                                    real_fn[idx] ? "" : " - not in the loader: returns 0");
+    return real_fn[idx];
+}
+
+static void report_pending(double t) {
+    int shown = 0;
+    for (int i = 0; i < PENDING; ++i) {
+        if (!pending[i].id) continue;
+        if (shown++ < 12)
+            LOG("unanswered after %.0f s: request %llu from %s", t - pending[i].t, (unsigned long long)pending[i].id,
+                NAMES[pending[i].fn]);
+    }
+    if (shown) LOG("%d request(s) without an answer", shown);
+}
+
+uint64_t fp_trace_after(uint64_t idx, uint64_t ret) __attribute__((visibility("hidden")));
+uint64_t fp_trace_after(uint64_t idx, uint64_t ret) {
+    if (idx >= COUNT) return ret;
+    double t = now();
+    pthread_mutex_lock(&lock);
+    if (is_pop[idx]) {
+        if (ret && msg_type && msg_id) {
+            const void *m = (const void *)(uintptr_t)ret;
+            uint64_t id = msg_id(m);
+            int answered = -1;
+            for (int i = 0; i < PENDING; ++i)
+                if (pending[i].id && pending[i].id == id) { answered = pending[i].fn; pending[i].id = 0; break; }
+            LOG("message type=0x%08x request=%llu error=%d%s%s", msg_type(m), (unsigned long long)id,
+                msg_error ? msg_error(m) : -1, answered >= 0 ? " answers " : "", answered >= 0 ? NAMES[answered] : "");
+        }
+    } else {
+        int n = calls[idx];
+        if (n <= 3) LOG("  %s -> 0x%llx", NAMES[idx], (unsigned long long)ret);
+        // request ids are small positive counters; pointers (handles) are large
+        if (is_request[idx] && ret && ret < (1ull << 40)) {
+            for (int i = 0; i < PENDING; ++i)
+                if (!pending[i].id) { pending[i].id = ret; pending[i].fn = (int)idx; pending[i].t = t; break; }
+            if (n <= 20) LOG("request %llu <- %s", (unsigned long long)ret, NAMES[idx]);
+        }
+    }
+    if (t - last_report >= 10.0) {
+        last_report = t;
+        report_pending(t);
+    }
+    pthread_mutex_unlock(&lock);
+    return ret;
+}
+
+// The shared stub: x16 = function index. Saves the argument registers, gets the real function, calls it with them,
+// reports the result. x8 (indirect result) and d0-d7 (float/HFA arguments) are preserved, x0/x1/d0-d3 returned.
+__asm__(
+    ".text\n"
+    ".p2align 2\n"
+    "fp_trace_common:\n"
+    "  stp x29, x30, [sp, #-224]!\n"
+    "  mov x29, sp\n"
+    "  stp x0, x1, [sp, #16]\n"
+    "  stp x2, x3, [sp, #32]\n"
+    "  stp x4, x5, [sp, #48]\n"
+    "  stp x6, x7, [sp, #64]\n"
+    "  stp d0, d1, [sp, #80]\n"
+    "  stp d2, d3, [sp, #96]\n"
+    "  stp d4, d5, [sp, #112]\n"
+    "  stp d6, d7, [sp, #128]\n"
+    "  stp x8, x16, [sp, #144]\n"
+    "  mov x0, x16\n"
+    "  ldr x1, [sp, #16]\n"
+    "  bl fp_trace_before\n"
+    "  str x0, [sp, #160]\n"
+    "  ldp x0, x1, [sp, #16]\n"
+    "  ldp x2, x3, [sp, #32]\n"
+    "  ldp x4, x5, [sp, #48]\n"
+    "  ldp x6, x7, [sp, #64]\n"
+    "  ldp d0, d1, [sp, #80]\n"
+    "  ldp d2, d3, [sp, #96]\n"
+    "  ldp d4, d5, [sp, #112]\n"
+    "  ldp d6, d7, [sp, #128]\n"
+    "  ldr x8, [sp, #144]\n"
+    "  ldr x17, [sp, #160]\n"
+    "  cbz x17, 1f\n"
+    "  blr x17\n"
+    "  b 2f\n"
+    "1:\n"
+    "  mov x0, #0\n"
+    "  mov x1, #0\n"
+    "  movi d0, #0\n"
+    "2:\n"
+    "  stp x0, x1, [sp, #16]\n"
+    "  stp d0, d1, [sp, #80]\n"
+    "  stp d2, d3, [sp, #96]\n"
+    "  ldr x0, [sp, #152]\n"
+    "  ldr x1, [sp, #16]\n"
+    "  bl fp_trace_after\n"
+    "  ldp x0, x1, [sp, #16]\n"
+    "  ldp d0, d1, [sp, #80]\n"
+    "  ldp d2, d3, [sp, #96]\n"
+    "  ldp x29, x30, [sp], #224\n"
+    "  ret\n");
+
+// one exported stub per name: x16 = its index
+#define STR2(x) #x
+#define STR(x) STR2(x)
+static const int dummy_index_base __attribute__((unused)) = 0;
+#define N(name)                                                    \
+    __asm__(".text\n.p2align 2\n.globl " #name "\n.type " #name ", %function\n" #name ":\n" \
+            "  mov x16, #" STR(__COUNTER__) "\n  b fp_trace_common\n");
+#include "names.inc"
+#undef N
@@ -13,6 +13,21 @@
 // copied with extra words inserted at a byte offset, e.g. stores that initialize locals a shader reads before writing
 // (an undefined loop counter hung the GPU in VR4's campaign). Every other module passes through unchanged.
 // Format: vk_shader_fix=<size>:<sha256 hex>:<byte offset>:<word>,<word>,...[;<next fix>]
+//
+// Query slots (adapter setting vk_query_slots=2, per game): with multiview, Vulkan counts a query that runs in a
+// multiview render pass as one query per view (N consecutive indices). Mesa's drivers (the Frame's Turnip) write a
+// zero result into the extra views' slots; Meta's Quest driver doesn't. Engines that allocate one slot per query
+// (Into The Radius 2, Unreal 5) then have the next object's occlusion query overwritten with "0 samples" and cull it:
+// models pop in and out. With the setting, occlusion pools get N slots per query; query i uses slot N*i, so the extra
+// views land in N*i+1.., and results are read from slot N*i only (view 0's count; Turnip counts every view there).
+//
+// Spec fixes (vk_spec_fixes=1, per game; found with the validation layer in Into The Radius 2, Unreal 5):
+//  * depth/stencil images created without VK_IMAGE_USAGE_TRANSFER_DST_BIT are cleared with vkCmdClearDepthStencilImage
+//    (VUID-vkCmdClearDepthStencilImage-pRanges-02659); Mesa's Turnip picks the image's compression from its usage, so
+//    the flag is added at vkCreateImage.
+//  * subpasses with Qualcomm's shader resolve (VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM) also name a depth
+//    resolve attachment for a single-sampled depth attachment (VUID-VkSubpassDescription2-flags-04908, -03179): the
+//    resolve is dropped (there is nothing to resolve from one sample).
 #define _GNU_SOURCE
 #include <vulkan/vulkan.h>
 #include <android/log.h>
@@ -74,12 +89,23 @@ static void parse_fixes(char *v) {
    }
 }

+static int query_slots = 1;  // vk_query_slots: slots per occlusion query (1 = untouched)
+static int spec_fixes;       // vk_spec_fixes: make two Unreal habits valid Vulkan (depth clears, depth resolves)
+#define VALIDATION_LAYER "VK_LAYER_KHRONOS_validation"
+static int validation;       // vk_validation: add Khronos' validation layer (bundled in the APK) to the instance
+
 static void read_settings(const char *path) {
    FILE *f = fopen(path, "r");
    if (!f) return;
    char line[4096];
    while (fgets(line, sizeof line, f)) {
        line[strcspn(line, "\r\n")] = 0;
+        if (!strncmp(line, "vk_validation=", 14)) validation = atoi(line + 14) != 0;
+        if (!strncmp(line, "vk_spec_fixes=", 14)) spec_fixes = atoi(line + 14) != 0;
+        if (!strncmp(line, "vk_query_slots=", 15)) {
+            int v = atoi(line + 15);
+            query_slots = v == 1 ? 2 : v >= 2 && v <= 4 ? v : 1;  // 1 = on (the settings dialog's switch) = 2 slots
+        }
        if (!strncmp(line, "vk_shader_fix=", 14)) {
            nfixes = 0;  // later sources override earlier ones (as for the adapter's settings)
            parse_fixes(line + 14);
@@ -182,6 +208,10 @@ static uint32_t *fixed_shader(const uint32_t *code, size_t size, size_t *out_siz
 static void init(void) {
    read_all_settings();
    if (nfixes) LOG("vk shim: %d shader fix(es) configured", nfixes);
+    if (query_slots > 1) LOG("vk shim: %d slots per occlusion query", query_slots);
+    if (validation) LOG("vk shim: adding %s to the instance", VALIDATION_LAYER);
+    if (spec_fixes) LOG("vk shim: Vulkan spec fixes on (depth images can be cleared, no depth resolve in shader-resolve "
+                        "subpasses)");
    real_vk = dlopen("libvulkan.so", RTLD_NOW | RTLD_LOCAL);
    if (real_vk) {
        real_gipa = (PFN_vkGetInstanceProcAddr)dlsym(real_vk, "vkGetInstanceProcAddr");
@@ -318,6 +348,8 @@ static const void *clean_chain(Arena *a, const void *head, int *fixes) {
    return first;
 }

+static int resolves_logged;
+
 static VkRenderPassCreateInfo2 clean_create_info(Arena *a, const VkRenderPassCreateInfo2 *ci, int *fixes) {
    VkRenderPassCreateInfo2 out = *ci;
    out.pNext = clean_chain(a, ci->pNext, fixes);
@@ -342,6 +374,27 @@ static VkRenderPassCreateInfo2 clean_create_info(Arena *a, const VkRenderPassCre
            out.pSubpasses = sp;
        }
    }
+    if (spec_fixes && out.pSubpasses) {
+        VkSubpassDescription2 *sp = (VkSubpassDescription2 *)out.pSubpasses;
+        for (uint32_t i = 0; i < ci->subpassCount; i++) {
+            if (!(sp[i].flags & 0x8 /* VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM */) || !sp[i].pDepthStencilAttachment)
+                continue;
+            uint32_t att = sp[i].pDepthStencilAttachment->attachment;
+            if (att == VK_ATTACHMENT_UNUSED || att >= ci->attachmentCount || !ci->pAttachments ||
+                ci->pAttachments[att].samples != VK_SAMPLE_COUNT_1_BIT)
+                continue;
+            for (VkBaseOutStructure *n = (VkBaseOutStructure *)sp[i].pNext; n; n = n->pNext) {
+                if (n->sType != VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE) continue;
+                VkSubpassDescriptionDepthStencilResolve *r = (void *)n;
+                if (r->pDepthStencilResolveAttachment &&
+                    r->pDepthStencilResolveAttachment->attachment != VK_ATTACHMENT_UNUSED) {
+                    r->pDepthStencilResolveAttachment = NULL;
+                    (*fixes)++;
+                    if (resolves_logged++ < 5) LOG("vk shim: dropped the depth resolve of shader-resolve subpass %u", i);
+                }
+            }
+        }
+    }
    if (ci->pDependencies && ci->dependencyCount) {
        VkSubpassDependency2 *dep = arena_dup(a, ci->pDependencies, sizeof *dep * ci->dependencyCount);
        if (dep) {
@@ -356,8 +409,11 @@ static VkRenderPassCreateInfo2 clean_create_info(Arena *a, const VkRenderPassCre
 // ---------------------------------------------------------------- entry points

 #define MAX_DEVICES 8
-enum { FN_RP2, FN_RP2KHR, FN_CSM, FN_COUNT };
-static const char *const FN_NAMES[FN_COUNT] = {"vkCreateRenderPass2", "vkCreateRenderPass2KHR", "vkCreateShaderModule"};
+enum { FN_RP2, FN_RP2KHR, FN_CSM, FN_CIMG, FN_CQP, FN_DQP, FN_BQ, FN_EQ, FN_CRQP, FN_RQP, FN_RQPEXT, FN_GQPR, FN_CCQPR, FN_COUNT };
+static const char *const FN_NAMES[FN_COUNT] = {
+    "vkCreateRenderPass2", "vkCreateRenderPass2KHR", "vkCreateShaderModule", "vkCreateImage", "vkCreateQueryPool", "vkDestroyQueryPool",
+    "vkCmdBeginQuery", "vkCmdEndQuery", "vkCmdResetQueryPool", "vkResetQueryPool", "vkResetQueryPoolEXT",
+    "vkGetQueryPoolResults", "vkCmdCopyQueryPoolResults"};
 static struct { VkDevice device; PFN_vkVoidFunction fn[FN_COUNT]; } devices[MAX_DEVICES];
 static PFN_vkCreateRenderPass2 fallback_rp2khr;  // from vkGetInstanceProcAddr
 static pthread_mutex_t dev_lock = PTHREAD_MUTEX_INITIALIZER;
@@ -428,6 +484,223 @@ EXPORT VKAPI_ATTR VkResult VKAPI_CALL vkCreateShaderModule(VkDevice device, cons
    return r;
 }

+// ---------------------------------------------------------------- query slots
+
+// Command buffer functions carry no VkDevice: their next implementation is the one the (single) game device got.
+static PFN_vkVoidFunction cmd_fn[FN_COUNT];
+static PFN_vkVoidFunction any_fn(VkDevice device, int which) {
+    PFN_vkVoidFunction fn = device ? device_fn(device, which) : NULL;
+    if (!fn) fn = cmd_fn[which];
+    if (!fn && real_vk) fn = (PFN_vkVoidFunction)dlsym(real_vk, FN_NAMES[which]);
+    return fn;
+}
+
+#define MAX_POOLS 4096
+static uint64_t occlusion_pools[MAX_POOLS];  // open addressing; 0 = empty, 1 = deleted
+static pthread_mutex_t pool_lock = PTHREAD_MUTEX_INITIALIZER;
+static int pools_logged;
+
+static unsigned pool_hash(uint64_t h) { return (unsigned)((h * 0x9E3779B97F4A7C15ull) >> 52) % MAX_POOLS; }
+
+static void pool_add(VkQueryPool pool) {
+    uint64_t h = (uint64_t)pool;
+    pthread_mutex_lock(&pool_lock);
+    for (unsigned i = pool_hash(h), n = 0; n < MAX_POOLS; i = (i + 1) % MAX_POOLS, n++)
+        if (occlusion_pools[i] <= 1) { occlusion_pools[i] = h; break; }
+    pthread_mutex_unlock(&pool_lock);
+}
+
+static int pool_slot(VkQueryPool pool, int remove) {
+    uint64_t h = (uint64_t)pool;
+    if (h <= 1) return 0;
+    int found = 0;
+    pthread_mutex_lock(&pool_lock);
+    for (unsigned i = pool_hash(h), n = 0; n < MAX_POOLS && occlusion_pools[i]; i = (i + 1) % MAX_POOLS, n++)
+        if (occlusion_pools[i] == h) {
+            found = 1;
+            if (remove) occlusion_pools[i] = 1;
+            break;
+        }
+    pthread_mutex_unlock(&pool_lock);
+    return found;
+}
+
+// the remapped first query of `pool` (unchanged for pools that aren't remapped)
+static uint32_t q(VkQueryPool pool, uint32_t query) { return pool_slot(pool, 0) ? query * (uint32_t)query_slots : query; }
+
+static VKAPI_ATTR VkResult VKAPI_CALL create_query_pool(VkDevice device, const VkQueryPoolCreateInfo *ci,
+                                                       const VkAllocationCallbacks *alloc, VkQueryPool *pool) {
+    PFN_vkCreateQueryPool real = (PFN_vkCreateQueryPool)any_fn(device, FN_CQP);
+    if (!real) return VK_ERROR_INITIALIZATION_FAILED;
+    if (!ci || ci->queryType != VK_QUERY_TYPE_OCCLUSION || query_slots < 2) return real(device, ci, alloc, pool);
+    VkQueryPoolCreateInfo copy = *ci;
+    copy.queryCount = ci->queryCount * (uint32_t)query_slots;
+    VkResult r = real(device, &copy, alloc, pool);
+    if (r == VK_SUCCESS) {
+        pool_add(*pool);
+        if (pools_logged++ < 5)
+            LOG("vk shim: occlusion query pool %u -> %u slots", ci->queryCount, copy.queryCount);
+    }
+    return r;
+}
+
+static VKAPI_ATTR void VKAPI_CALL destroy_query_pool(VkDevice device, VkQueryPool pool, const VkAllocationCallbacks *alloc) {
+    PFN_vkDestroyQueryPool real = (PFN_vkDestroyQueryPool)any_fn(device, FN_DQP);
+    pool_slot(pool, 1);
+    if (real) real(device, pool, alloc);
+}
+
+static VKAPI_ATTR void VKAPI_CALL cmd_begin_query(VkCommandBuffer cb, VkQueryPool pool, uint32_t query,
+                                                 VkQueryControlFlags flags) {
+    PFN_vkCmdBeginQuery real = (PFN_vkCmdBeginQuery)any_fn(NULL, FN_BQ);
+    if (real) real(cb, pool, q(pool, query), flags);
+}
+
+static VKAPI_ATTR void VKAPI_CALL cmd_end_query(VkCommandBuffer cb, VkQueryPool pool, uint32_t query) {
+    PFN_vkCmdEndQuery real = (PFN_vkCmdEndQuery)any_fn(NULL, FN_EQ);
+    if (real) real(cb, pool, q(pool, query));
+}
+
+static uint32_t span(VkQueryPool pool, uint32_t count) { return pool_slot(pool, 0) ? count * (uint32_t)query_slots : count; }
+
+static VKAPI_ATTR void VKAPI_CALL cmd_reset_query_pool(VkCommandBuffer cb, VkQueryPool pool, uint32_t first, uint32_t count) {
+    PFN_vkCmdResetQueryPool real = (PFN_vkCmdResetQueryPool)any_fn(NULL, FN_CRQP);
+    if (real) real(cb, pool, q(pool, first), span(pool, count));
+}
+
+static void reset_query_pool(VkDevice device, VkQueryPool pool, uint32_t first, uint32_t count, int ext) {
+    PFN_vkResetQueryPool real = (PFN_vkResetQueryPool)any_fn(device, ext ? FN_RQPEXT : FN_RQP);
+    if (real) real(device, pool, q(pool, first), span(pool, count));
+}
+static VKAPI_ATTR void VKAPI_CALL host_reset_query_pool(VkDevice d, VkQueryPool p, uint32_t f, uint32_t c) { reset_query_pool(d, p, f, c, 0); }
+static VKAPI_ATTR void VKAPI_CALL host_reset_query_pool_ext(VkDevice d, VkQueryPool p, uint32_t f, uint32_t c) { reset_query_pool(d, p, f, c, 1); }
+
+// Results come from slot N*i of each query, one query at a time: the extra slots are only written in multiview passes,
+// so reading them (with VK_QUERY_RESULT_WAIT_BIT) could wait forever.
+static VKAPI_ATTR VkResult VKAPI_CALL get_query_pool_results(VkDevice device, VkQueryPool pool, uint32_t first, uint32_t count,
+                                                            size_t size, void *data, VkDeviceSize stride,
+                                                            VkQueryResultFlags flags) {
+    PFN_vkGetQueryPoolResults real = (PFN_vkGetQueryPoolResults)any_fn(device, FN_GQPR);
+    if (!real) return VK_ERROR_INITIALIZATION_FAILED;
+    if (!pool_slot(pool, 0) || !count) return real(device, pool, first, count, size, data, stride, flags);
+    VkResult result = VK_SUCCESS;
+    for (uint32_t i = 0; i < count; i++) {
+        size_t offset = (size_t)(i * stride);
+        if (offset >= size) break;
+        VkResult r = real(device, pool, (first + i) * (uint32_t)query_slots, 1, size - offset, (uint8_t *)data + offset,
+                          stride, flags);
+        if (r < 0) return r;
+        if (r == VK_NOT_READY) result = VK_NOT_READY;
+    }
+    return result;
+}
+
+static VKAPI_ATTR void VKAPI_CALL cmd_copy_query_pool_results(VkCommandBuffer cb, VkQueryPool pool, uint32_t first,
+                                                             uint32_t count, VkBuffer buffer, VkDeviceSize offset,
+                                                             VkDeviceSize stride, VkQueryResultFlags flags) {
+    PFN_vkCmdCopyQueryPoolResults real = (PFN_vkCmdCopyQueryPoolResults)any_fn(NULL, FN_CCQPR);
+    if (!real) return;
+    if (!pool_slot(pool, 0)) { real(cb, pool, first, count, buffer, offset, stride, flags); return; }
+    for (uint32_t i = 0; i < count; i++)
+        real(cb, pool, (first + i) * (uint32_t)query_slots, 1, buffer, offset + i * stride, stride, flags);
+}
+
+// ---------------------------------------------------------------- spec fixes: depth images
+
+static int is_depth_format(VkFormat f) {
+    return f == VK_FORMAT_D16_UNORM || f == VK_FORMAT_X8_D24_UNORM_PACK32 || f == VK_FORMAT_D32_SFLOAT ||
+           f == VK_FORMAT_S8_UINT || f == VK_FORMAT_D16_UNORM_S8_UINT || f == VK_FORMAT_D24_UNORM_S8_UINT ||
+           f == VK_FORMAT_D32_SFLOAT_S8_UINT;
+}
+static int images_logged;
+
+static VKAPI_ATTR VkResult VKAPI_CALL create_image(VkDevice device, const VkImageCreateInfo *ci,
+                                                  const VkAllocationCallbacks *alloc, VkImage *image) {
+    PFN_vkCreateImage real = (PFN_vkCreateImage)any_fn(device, FN_CIMG);
+    if (!real) return VK_ERROR_INITIALIZATION_FAILED;
+    if (!spec_fixes || !ci || !is_depth_format(ci->format) || !(ci->usage & VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT) ||
+        (ci->usage & (VK_IMAGE_USAGE_TRANSFER_DST_BIT | VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT)))  // transient: no
+        return real(device, ci, alloc, image);
+    VkImageCreateInfo copy = *ci;
+    copy.usage |= VK_IMAGE_USAGE_TRANSFER_DST_BIT;
+    VkResult r = real(device, &copy, alloc, image);
+    if (images_logged++ < 5) LOG("vk shim: depth image %ux%u format %d can be cleared now: %d", ci->extent.width,
+                                 ci->extent.height, ci->format, r);
+    if (r != VK_SUCCESS) r = real(device, ci, alloc, image);  // the flag isn't allowed here: as the game asked
+    return r;
+}
+
+EXPORT VKAPI_ATTR VkResult VKAPI_CALL vkCreateImage(VkDevice d, const VkImageCreateInfo *ci, const VkAllocationCallbacks *a,
+                                                    VkImage *img) {
+    pthread_once(&once, init);
+    return create_image(d, ci, a, img);
+}
+
+// ---------------------------------------------------------------- validation (diagnostics)
+
+static PFN_vkCreateInstance real_ci;
+
+static VKAPI_ATTR VkResult VKAPI_CALL create_instance(const VkInstanceCreateInfo *ci, const VkAllocationCallbacks *a,
+                                                    VkInstance *inst) {
+    if (!real_ci && real_vk) real_ci = (PFN_vkCreateInstance)dlsym(real_vk, "vkCreateInstance");
+    if (!real_ci) return VK_ERROR_INITIALIZATION_FAILED;
+    if (!validation || !ci) return real_ci(ci, a, inst);
+    for (uint32_t i = 0; i < ci->enabledLayerCount; i++)
+        if (!strcmp(ci->ppEnabledLayerNames[i], VALIDATION_LAYER)) return real_ci(ci, a, inst);
+    const char **names = malloc(sizeof(char *) * (ci->enabledLayerCount + 1));
+    if (!names) return real_ci(ci, a, inst);
+    for (uint32_t i = 0; i < ci->enabledLayerCount; i++) names[i] = ci->ppEnabledLayerNames[i];
+    names[ci->enabledLayerCount] = VALIDATION_LAYER;
+    VkInstanceCreateInfo copy = *ci;
+    copy.enabledLayerCount = ci->enabledLayerCount + 1;
+    copy.ppEnabledLayerNames = names;
+    VkResult r = real_ci(&copy, a, inst);
+    LOG("vk shim: vkCreateInstance with %s: %d", VALIDATION_LAYER, r);
+    if (r == VK_ERROR_LAYER_NOT_PRESENT) r = real_ci(ci, a, inst);  // not bundled: start without it
+    free(names);
+    return r;
+}
+
+EXPORT VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance(const VkInstanceCreateInfo *ci, const VkAllocationCallbacks *a,
+                                                       VkInstance *inst) {
+    pthread_once(&once, init);
+    return create_instance(ci, a, inst);
+}
+
+// The same entry points for engines that dlsym them from the shim instead of asking vkGet*ProcAddr
+EXPORT VKAPI_ATTR VkResult VKAPI_CALL vkCreateQueryPool(VkDevice d, const VkQueryPoolCreateInfo *ci,
+                                                        const VkAllocationCallbacks *a, VkQueryPool *p) {
+    pthread_once(&once, init);
+    return create_query_pool(d, ci, a, p);
+}
+EXPORT VKAPI_ATTR void VKAPI_CALL vkDestroyQueryPool(VkDevice d, VkQueryPool p, const VkAllocationCallbacks *a) {
+    pthread_once(&once, init);
+    destroy_query_pool(d, p, a);
+}
+EXPORT VKAPI_ATTR void VKAPI_CALL vkCmdBeginQuery(VkCommandBuffer cb, VkQueryPool p, uint32_t i, VkQueryControlFlags f) {
+    pthread_once(&once, init);
+    cmd_begin_query(cb, p, i, f);
+}
+EXPORT VKAPI_ATTR void VKAPI_CALL vkCmdEndQuery(VkCommandBuffer cb, VkQueryPool p, uint32_t i) {
+    pthread_once(&once, init);
+    cmd_end_query(cb, p, i);
+}
+EXPORT VKAPI_ATTR void VKAPI_CALL vkCmdResetQueryPool(VkCommandBuffer cb, VkQueryPool p, uint32_t f, uint32_t c) {
+    pthread_once(&once, init);
+    cmd_reset_query_pool(cb, p, f, c);
+}
+EXPORT VKAPI_ATTR VkResult VKAPI_CALL vkGetQueryPoolResults(VkDevice d, VkQueryPool p, uint32_t f, uint32_t c, size_t s,
+                                                            void *data, VkDeviceSize st, VkQueryResultFlags fl) {
+    pthread_once(&once, init);
+    return get_query_pool_results(d, p, f, c, s, data, st, fl);
+}
+EXPORT VKAPI_ATTR void VKAPI_CALL vkCmdCopyQueryPoolResults(VkCommandBuffer cb, VkQueryPool p, uint32_t f, uint32_t c,
+                                                           VkBuffer b, VkDeviceSize o, VkDeviceSize st,
+                                                           VkQueryResultFlags fl) {
+    pthread_once(&once, init);
+    cmd_copy_query_pool_results(cb, p, f, c, b, o, st, fl);
+}
+
 static int wrapped_index(const char *name) {
    for (int i = 0; i < FN_COUNT; i++)
        if (!strcmp(name, FN_NAMES[i])) return i;
@@ -439,6 +712,20 @@ static PFN_vkVoidFunction wrap(const char *name) {
    case FN_RP2: return (PFN_vkVoidFunction)vkCreateRenderPass2;
    case FN_RP2KHR: return (PFN_vkVoidFunction)create_render_pass2_khr;
    case FN_CSM: return nfixes ? (PFN_vkVoidFunction)vkCreateShaderModule : NULL;  // nothing to fix: no detour
+    case FN_CIMG: return spec_fixes ? (PFN_vkVoidFunction)create_image : NULL;
+    default: break;
+    }
+    if (query_slots < 2) return NULL;  // no query remapping: no detours
+    switch (wrapped_index(name)) {
+    case FN_CQP: return (PFN_vkVoidFunction)create_query_pool;
+    case FN_DQP: return (PFN_vkVoidFunction)destroy_query_pool;
+    case FN_BQ: return (PFN_vkVoidFunction)cmd_begin_query;
+    case FN_EQ: return (PFN_vkVoidFunction)cmd_end_query;
+    case FN_CRQP: return (PFN_vkVoidFunction)cmd_reset_query_pool;
+    case FN_RQP: return (PFN_vkVoidFunction)host_reset_query_pool;
+    case FN_RQPEXT: return (PFN_vkVoidFunction)host_reset_query_pool_ext;
+    case FN_GQPR: return (PFN_vkVoidFunction)get_query_pool_results;
+    case FN_CCQPR: return (PFN_vkVoidFunction)cmd_copy_query_pool_results;
    default: return NULL;
    }
 }
@@ -460,6 +747,7 @@ EXPORT VKAPI_ATTR PFN_vkVoidFunction VKAPI_CALL vkGetDeviceProcAddr(VkDevice dev
        devices[slot].device = device;
        devices[slot].fn[which] = fn;
    }
+    cmd_fn[which] = fn;
    pthread_mutex_unlock(&dev_lock);
    return w;
 }
@@ -469,9 +757,12 @@ EXPORT VKAPI_ATTR PFN_vkVoidFunction VKAPI_CALL vkGetInstanceProcAddr(VkInstance
    if (!real_gipa || !name) return NULL;
    if (!strcmp(name, "vkGetDeviceProcAddr")) return (PFN_vkVoidFunction)vkGetDeviceProcAddr;
    if (!strcmp(name, "vkGetInstanceProcAddr")) return (PFN_vkVoidFunction)vkGetInstanceProcAddr;
+    if (!strcmp(name, "vkCreateInstance") && validation) return (PFN_vkVoidFunction)vkCreateInstance;
    PFN_vkVoidFunction fn = real_gipa(instance, name);
    PFN_vkVoidFunction w = fn ? wrap(name) : NULL;
    if (!w) return fn;
    if (!strcmp(name, "vkCreateRenderPass2KHR")) fallback_rp2khr = (PFN_vkCreateRenderPass2)fn;
+    int which = wrapped_index(name);
+    if (which >= FN_CQP && !cmd_fn[which]) cmd_fn[which] = fn;
    return w;
 }
@@ -7,11 +7,18 @@
 // Meta's OVRPlugin finds xrGetInstanceProcAddr with dlopen("libopenxr_loader.so") + dlsym, so FramePort points that
 // string in libOVRPlugin.so at this library instead (patches/frame/adapter.py). Names the adapter emulates are served
 // by the adapter (framebridge_extension_proc); everything else goes to overport's xrGetInstanceProcAddr unchanged.
+//
+// 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.
 #include <openxr/openxr.h>
 #include <android/log.h>
 #include <dlfcn.h>
 #include <pthread.h>
 #include <stddef.h>
+#include <string.h>

 #define TAG "FrameBridge"
 #define EXPORT __attribute__((visibility("default")))
@@ -40,9 +47,38 @@ static PFN_xrVoidFunction adapter_proc(const char *name) {
    return fn(name);
 }

+static PFN_xrApplyHapticFeedback overport_haptics;
+static int haptics_logged;
+
+static XRAPI_ATTR XrResult XRAPI_CALL apply_haptic_feedback(XrSession session, const XrHapticActionInfo *info,
+                                                           const XrHapticBaseHeader *feedback) {
+    if (feedback && feedback->type == XR_TYPE_HAPTIC_AMPLITUDE_ENVELOPE_VIBRATION_FB) {
+        const XrHapticAmplitudeEnvelopeVibrationFB *env = (const XrHapticAmplitudeEnvelopeVibrationFB *)feedback;
+        float peak = 0.0f;
+        for (uint32_t i = 0; env->amplitudes && i < env->amplitudeCount; ++i)
+            if (env->amplitudes[i] > peak) peak = env->amplitudes[i];
+        XrHapticVibration plain = {XR_TYPE_HAPTIC_VIBRATION, NULL, env->duration, XR_FREQUENCY_UNSPECIFIED,
+                                   peak > 1.0f ? 1.0f : peak};
+        if (haptics_logged++ < 3)
+            __android_log_print(ANDROID_LOG_INFO, TAG, "extension shim: haptic envelope (%u samples, %lld ns) -> "
+                                "vibration %.2f", env->amplitudeCount, (long long)env->duration, plain.amplitude);
+        return overport_haptics(session, info, (const XrHapticBaseHeader *)&plain);
+    }
+    return overport_haptics(session, info, feedback);
+}
+
 EXPORT XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const char *name,
                                                            PFN_xrVoidFunction *function) {
    pthread_once(&once, resolve_overport);
+    if (name && function && instance != XR_NULL_HANDLE && overport_gipa && !strcmp(name, "xrApplyHapticFeedback")) {
+        PFN_xrVoidFunction real = NULL;
+        XrResult r = overport_gipa(instance, name, &real);
+        if (XR_SUCCEEDED(r) && real) {
+            overport_haptics = (PFN_xrApplyHapticFeedback)real;
+            *function = (PFN_xrVoidFunction)apply_haptic_feedback;
+        }
+        return r;
+    }
    if (name && function && instance != XR_NULL_HANDLE) {
        PFN_xrVoidFunction emulated = adapter_proc(name);
        if (emulated) {
@@ -79,10 +79,19 @@ company = "FramePort"
 path = "src"
 module = "main"

+# jni_flutter (1.0.4 and 1.0.4+1, 2026-10) generates bindings that require jni ^1.1.0, while Flet's build template pins
+# jni 1.0.0: every bundle failed ("generated bindings expect package:jni ^1.1.0"). jni 1.1 also satisfies bindings
+# made for 1.0 (the check is "same major, at least this minor"). Remove once Flet's template moves to jni 1.1.
+[tool.flet.flutter.pubspec.dependency_overrides]
+jni = "1.1.0"
+
+[tool.flet.macos]
+entitlement."com.apple.security.files.user-selected.read-write" = true
+
 [tool.ruff]
 line-length = 120
 target-version = "py311"
-extend-exclude = ["native", "src/frameport/_data"]
+extend-exclude = ["native", "src/frameport/_data", ".claude"]

 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "B", "UP"]
@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Stamp a dev build's version into src/frameport/_version.py (CI only; never committed): the next patch release plus
+.dev<build number>, e.g. 0.9.0 -> 0.9.1.dev57. It sorts above the current release and below the next one, so
+testers on a dev build get the next release offered as a normal update.
+
+    python scripts/dev_version.py <build number>     # prints the stamped version
+"""
+import re
+import sys
+from pathlib import Path
+
+VERSION_FILE = Path(__file__).resolve().parents[1] / "src/frameport/_version.py"
+
+
+def dev_version(current: str, build: int) -> str:
+    base = re.match(r"(\d+)\.(\d+)\.(\d+)", current)
+    if not base:
+        raise ValueError(f"unexpected version {current!r}")
+    major, minor, patch = (int(x) for x in base.groups())
+    return f"{major}.{minor}.{patch + 1}.dev{int(build)}"
+
+
+def main() -> None:
+    text = VERSION_FILE.read_text(encoding="utf-8")
+    current = re.search(r'__version__\s*=\s*"([^"]+)"', text).group(1)
+    version = dev_version(current, int(sys.argv[1]))
+    VERSION_FILE.write_text(text.replace(f'"{current}"', f'"{version}"', 1), encoding="utf-8")
+    print(version)
+
+
+if __name__ == "__main__":
+    main()
@@ -3,6 +3,9 @@
 Chromium (Playwright). Any exception in a view shows up on stdout; screenshots land in --out.

    FRAMEPORT_HOME=<a test data dir> python scripts/ui_smoke.py --out /tmp/shots [--game <package>]
+
+--linux adds two pretend arm64 Linux apps (an AppImage and a VR folder app, tiny fake ELF files in FRAMEPORT_HOME)
+and renders their pages; with --fake-frame the AppImage is "installed" with a missing library.
 """
 from __future__ import annotations

@@ -21,7 +24,7 @@ import flet as ft  # noqa: E402
 from frameport.core import library  # noqa: E402
 from frameport.ui.app import FramePortApp  # noqa: E402

-PORT = 8557
+PORT = int(os.environ.get("FRAMEPORT_SMOKE_PORT", "8557"))  # two smoke runs at once need different ports
 ERRORS: list[str] = []


@@ -44,12 +47,65 @@ class FakeFS:
                else:
                    with open(os.path.join(base, n), "wb") as f:
                        f.truncate(sizes.get(os.path.splitext(n)[1], 48_000))  # sparse: no real disk use
+        self.shots = self._screenshots()
+
+    def _screenshots(self) -> list[dict]:
+        """Sample Steam screenshots for the Screenshots tab, two days, a few games + SteamVR: crops of the games' own
+        store art (hero/landscape) when the library has some (docs screenshots), else colour gradients."""
+        from PIL import Image, ImageOps
+
+        from frameport.artwork import fetch
+
+        folder = os.path.join(self.home, "shots")
+        os.makedirs(folder, exist_ok=True)
+        games = []
+        for g in library.games():
+            if g.get("kind") == "rift":
+                continue
+            # the store's own screenshots look like real captures; else hero/wide art
+            shots_art = sorted(fetch.artwork_dir(g["package"]).glob("shot_*.jpg"))
+            games.append((g, shots_art or [p for p in fetch.files(g["package"]) if p.stem in ("hero", "landscape")],
+                          bool(shots_art)))
+        games.sort(key=lambda ga: (not ga[2], -len(ga[1])))
+        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))
+        now, shots = time.time(), []
+        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"
+            path = os.path.join(folder, name)
+            pkg, title, arts = owners[i % len(owners)]
+            if arts:  # a different crop of the game's art per shot, so they don't all look alike
+                with Image.open(arts[i % len(arts)]) as src:
+                    src = src.convert("RGB")
+                    zoom = 1.0 + 0.15 * (i % 3) * (src.width < 2 * src.height)
+                    w, h = int(src.width / zoom), int(src.height / zoom)
+                    x, y = (src.width - w) * (i % 2), (src.height - h) // 2
+                    im = ImageOps.fit(src.crop((x, y, x + w, y + h)), (1280, 720))
+            else:
+                im = Image.linear_gradient("L").resize((640, 360)).convert("RGB")
+                im = Image.merge("RGB", (im.getchannel(0).point(lambda v, i=i: (v + 40 * i) % 256),
+                                         im.getchannel(1).point(lambda v: 255 - v), im.getchannel(2)))
+            im.save(path, "JPEG", quality=85)
+            shots.append({"path": path, "thumb": None, "time": int(t), "width": 1920, "height": 1080,
+                          "size": os.path.getsize(path), "account": "1", "appid": "250820", "package": pkg,
+                          "title": title})
+        return shots

    def agent(self, command, **args):
        if command == "storage_targets":
            return {"targets": [{"id": n.lower(), "path": os.path.join(self.home, n), "android": a, "shared": True}
                                for n, a in (("Videos", "/sdcard/Movies"), ("Downloads", "/sdcard/Download"),
                                             ("Documents", "/sdcard/Documents"))]}
+        if command == "list_screenshots":
+            want = args.get("package")
+            shots = [s for s in self.shots if want is None or (s["package"] or "") == want]
+            games = {}
+            for s in self.shots:
+                games.setdefault(s["package"] or "", {"package": s["package"], "title": s["title"], "count": 0})
+                games[s["package"] or ""]["count"] += 1
+            return {"shots": shots, "total": len(shots), "games": list(games.values())}
        raise RuntimeError(f"fake Frame: {command} not available")

    @property
@@ -67,6 +123,11 @@ class FakeFS:

            def stat(self, path):
                return paramiko.SFTPAttributes.from_stat(os.stat(path))
+
+            def get(self, remote, local, callback=None):
+                import shutil
+
+                shutil.copyfile(remote, local)
        return SFTP()


@@ -86,6 +147,11 @@ class FakeTarget:
        self.games = [{"package": g["package"], "kind": "quest", "title": g.get("title"),
                       "apk_size": (g.get("data_bytes") or 0) + 2**28, "sha256": g["build"]["sha256"],
                       "recipe": {"patches": (g.get("recipe") or {}).get("patches", [])}} for g in works[:count]]
+        # --linux: the AppImage is on the Frame, but SteamOS lacks one of its libraries
+        self.games += [{"package": g["package"], "kind": "linux", "title": g.get("title"), "apk_size": 2**26,
+                        "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]

    def describe(self) -> dict:
        return {"hostname": "steamframe", "os": "SteamOS", "os_version": "3.8", "build_id": "20260922",
@@ -129,6 +195,36 @@ def open_type_dialog(app: FramePortApp) -> None:
    listener.on_key_down(SimpleNamespace(key="Enter"))


+LINUX_APPIMAGE = "linux.venera"  # --linux's packages
+LINUX_FOLDER = "linux.matineevr"
+
+
+def _elf(machine: int = 183, appimage: bool = False, extra: bytes = b"") -> bytes:
+    """A minimal ELF header (183 = aarch64): enough for FramePort's Linux app detection."""
+    head = bytearray(64)
+    head[:4], head[4], head[5] = b"\x7fELF", 2, 1
+    if appimage:
+        head[8:11] = b"AI\x02"
+    head[18:20] = machine.to_bytes(2, "little")
+    return bytes(head) + extra
+
+
+def add_fake_linux_apps() -> None:
+    """--linux: an AppImage and a VR app folder (with a helper program, so "Change program…" shows) in the library."""
+    from frameport import pipeline
+    from frameport.core.paths import user_data_dir
+
+    base = user_data_dir() / "smoke-linux"
+    app = base / "MatineeVR"
+    (app / "lib").mkdir(parents=True, exist_ok=True)
+    (base / "Venera-2.4.2-aarch64.AppImage").write_bytes(_elf(appimage=True, extra=b"\0" * 4096))
+    (app / "MatineeVR").write_bytes(_elf(extra=b"\0" * 8192))
+    (app / "crashpad_handler").write_bytes(_elf())
+    (app / "lib" / "libopenxr_loader.so.1").write_bytes(_elf(extra=b"xrCreateInstance"))
+    pipeline.add_linux_app(base / "Venera-2.4.2-aarch64.AppImage")
+    pipeline.add_linux_app(app)
+
+
 STEP_SECONDS = 4  # per screen (the screenshot is taken ~3 s in)


@@ -143,6 +239,35 @@ def driver(app: FramePortApp, steps: list[tuple[str, callable]], ready: threadin
        time.sleep(STEP_SECONDS)


+def find_button(root, text: str):
+    """The first button under `root` whose label is `text` (walks Flet's control tree)."""
+    seen, stack = set(), [root]
+    while stack:
+        c = stack.pop()
+        if c is None or id(c) in seen:
+            continue
+        seen.add(id(c))
+        label = getattr(c, "content", None)
+        if (label == text or getattr(c, "text", None) == text) and getattr(c, "on_click", None):
+            return c
+        for attr in ("controls", "content", "actions"):
+            v = getattr(c, attr, None)
+            if isinstance(v, list):
+                stack.extend(v)
+            elif v is not None and not isinstance(v, str):
+                stack.append(v)
+    return None
+
+
+def click_usb_setup(app) -> None:
+    app.navigate(1)
+    time.sleep(2)
+    button = find_button(app.body, "Set up with a USB cable")
+    print(f"usb button found: {button is not None}", flush=True)
+    if button:
+        button.on_click(None)
+
+
 def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("--out", type=Path, required=True)
@@ -157,8 +282,15 @@ def main() -> int:
    ap.add_argument("--install-questions", nargs="+", metavar="PKG", default=None,
                    help="open the install questions for these games, then click each dialog's main button twice "
                         "(a double click must not duplicate dialogs); nothing is installed")
+    ap.add_argument("--usb-setup", action="store_true", help="click 'Set up with a USB cable' on the connect page "
+                    "(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")
+    ap.add_argument("--linux", action="store_true", help="add two pretend arm64 Linux apps and render their pages")
    args = ap.parse_args()
+    if args.linux:
+        add_fake_linux_apps()
    global STEP_SECONDS
    if args.hover:
        STEP_SECONDS = 7
@@ -169,12 +301,14 @@ def main() -> int:
    args.out.mkdir(parents=True, exist_ok=True)
    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")), ("tools", lambda a: a.go("settings"))]
+             ("files", lambda a: a.go("files")), ("screenshots", lambda a: a.go("screenshots")),
+             ("live", lambda a: a.go("live")), ("tools", lambda a: a.go("settings"))]
    if game:
        steps.insert(1, ("game", lambda a: a.open_game(game)))
        steps.insert(2, ("game-customize", lambda a: a.open_game(game, advanced=True)))
        steps += [("share-dialog", lambda a: a.share_config_dialog(game)),
-                  ("report-dialog", lambda a: (a.page.pop_dialog(), a.report_problem_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)))]
        # last: the right-click menu stays open over whatever comes next
        steps.append(("library-menu", lambda a: (a.page.pop_dialog(), a.navigate(0), time.sleep(3),
                                                 a.library_view.open_menu(game))))
@@ -187,7 +321,75 @@ def main() -> int:
        steps.append(("files", lambda a: a.go("files")))
        steps.append(("files-select", lambda a: [a.files_view._toggle(e.path, True)
                                                 for e in a.files_view.entries[1:3]]))
-        steps.append(("type-on-frame", open_type_dialog))
+        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(("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
+
+        def drag(*points):
+            def run(page):
+                page.mouse.move(*points[0])
+                time.sleep(0.5)
+                page.mouse.down()
+                for pt in points[1:]:
+                    page.mouse.move(*pt, steps=25)
+                    time.sleep(0.4)
+                page.mouse.up()
+            return run
+
+        def right_click(x, y):
+            return lambda page: (page.mouse.move(x, y), time.sleep(0.5), page.mouse.click(x, y, button="right"))
+
+        def report(label, view, extra=""):
+            def run(a):
+                v = getattr(a, view)
+                print(f"GESTURE {label}: selected={sorted(v.selected)} {extra and eval(extra)}", flush=True)
+            return run
+
+        def escape(page):
+            page.keyboard.press("Escape")
+        steps = [("files", lambda a: a.go("files")),
+                 ("files-dragged", report("files drag", "files_view")),
+                 ("files-menu", lambda a: None),
+                 ("files-space-menu", lambda a: None),
+                 ("screenshots", lambda a: a.go("screenshots")),
+                 ("screenshots-dragged", report("screenshots drag", "screenshots_view")),
+                 ("screenshots-menu", lambda a: None),
+                 ("library", lambda a: a.navigate(0)),
+                 ("library-dragged", report("library drag", "library_view", "a.library_view.select_mode")),
+                 ("library-undrag", report("library drag back", "library_view"))]
+        mouse = {"files": drag((900, 268), (900, 320), (900, 372)),          # the folder + 2 files
+                 "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-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
+    if args.linux:
+        def linux_filter(a, value):
+            a.navigate(0)
+            time.sleep(2)
+            a.library_view._set("platform", value)
+        steps = [("library", lambda a: a.navigate(0)), ("library-linux", lambda a: linux_filter(a, "linux")),
+                 ("linux-appimage", lambda a: (a.library_view._set("platform", "all"), a.open_game(LINUX_APPIMAGE))),
+                 ("linux-folder", lambda a: a.open_game(LINUX_FOLDER)),
+                 ("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)))]
+    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]
+            button = find_button(dialog, "Done: look for the cable") or dialog.actions[-1]  # (label inside a Row)
+            print(f"dialog button found: {button is not None}", flush=True)
+            button.on_click(None)
+        steps = [("usb-explain", click_usb_setup), ("usb-continue", continue_usb),
+                 ("usb-wait", lambda a: time.sleep(8)), ("usb-after", lambda a: time.sleep(10))]
    if args.install_questions:
        queued: list[str] = []

@@ -279,6 +481,11 @@ def main() -> int:
                            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)
+                            page.screenshot(path=str(args.out / f"{shot:02d}-{name}-mouse.png"))
+                            shot += 1
                browser.close()
        except Exception:  # noqa: BLE001
            ERRORS.append("browser: " + traceback.format_exc())
@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+# ruff: noqa: E501  (the shell snippet for the Frame keeps its lines whole)
+"""Autonomous USB-cable test (Frame cabled to this PC): everything needed to decide on a "Connect with a USB cable"
+setup option, in one run, without touching the headset. Writes a Markdown report.
+
+    uv run python scripts/usb_autotest.py --out <report.md> [--no-speed]
+
+Checks: Windows (via powershell.exe from WSL, or directly): new network adapters, Valve USB devices (VID 28DE), the
+driver Windows bound and the USB class codes (NCM 02/0D, ECM 02/06, RNDIS E0 or EF/04); the adapter's IPv4 and
+network category; Frame side (over the normal connection): agent `usb_link`, the systemd units / NetworkManager
+connection behind usb0 (does it depend on Developer Mode?); Frame -> PC over the cable (the setup direction: a
+temporary listener on a pairing port); PC -> Frame SSH over the cable (same host key); upload speed USB vs normal.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+PS_PATHS = ("/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe", "powershell.exe", "powershell")
+LISTEN_PORT = 8766  # in FramePort's pairing range (8765-8767)
+
+
+def powershell() -> str | None:
+    for p in PS_PATHS:
+        if os.path.exists(p) or shutil.which(p):
+            return p
+    return None
+
+
+def ps(script: str, timeout: int = 60) -> str:
+    exe = powershell()
+    if not exe:
+        return "(no PowerShell)"
+    env = {k: v for k, v in os.environ.items() if k != "PSModulePath"}
+    try:
+        p = subprocess.run([exe, "-NoProfile", "-NonInteractive", "-Command", script], capture_output=True,
+                           text=True, timeout=timeout, env=env)
+        return (p.stdout + p.stderr).replace("\r", "").strip()
+    except (OSError, subprocess.SubprocessError) as exc:
+        return f"(powershell failed: {exc})"
+
+
+WINDOWS = r"""
+$ErrorActionPreference = 'SilentlyContinue'
+'== adapters'
+Get-NetAdapter -IncludeHidden | Select-Object Name,InterfaceDescription,Status,LinkSpeed,MacAddress |
+  Format-Table -AutoSize | Out-String -Width 250
+'== Valve USB devices (VID 28DE)'
+Get-PnpDevice -PresentOnly | Where-Object { $_.InstanceId -match 'VID_28DE' } | ForEach-Object {
+  $d = $_
+  $compat = (Get-PnpDeviceProperty -InstanceId $d.InstanceId -KeyName 'DEVPKEY_Device_CompatibleIds').Data -join ' '
+  $svc = (Get-PnpDeviceProperty -InstanceId $d.InstanceId -KeyName 'DEVPKEY_Device_Service').Data
+  $drv = (Get-PnpDeviceProperty -InstanceId $d.InstanceId -KeyName 'DEVPKEY_Device_DriverDesc').Data
+  "{0} | {1} | status={2} | class={3} | service={4} | driver={5} | compat={6}" -f $d.FriendlyName, $d.InstanceId,
+    $d.Status, $d.Class, $svc, $drv, $compat
+}
+'== problem devices'
+Get-PnpDevice -PresentOnly | Where-Object { $_.Status -ne 'OK' -and $_.InstanceId -match 'USB' } |
+  Select-Object FriendlyName,Status,InstanceId | Format-Table -AutoSize | Out-String -Width 250
+'== IPv4 on 10.86.200.*'
+Get-NetIPAddress -AddressFamily IPv4 | Where-Object { $_.IPAddress -like '10.86.200.*' } |
+  Select-Object InterfaceAlias,IPAddress,PrefixLength,PrefixOrigin | Format-Table | Out-String
+'== network profiles'
+Get-NetConnectionProfile | Select-Object InterfaceAlias,NetworkCategory | Format-Table | Out-String
+'== SSH to the Frame over the cable (from Windows)'
+(Test-NetConnection 10.86.200.233 -Port 22 -WarningAction SilentlyContinue).TcpTestSucceeded
+'== FramePort firewall rules'
+Get-NetFirewallRule -DisplayName '*FramePort*' | Select-Object DisplayName,Enabled,Profile,Direction |
+  Format-Table | Out-String
+"""
+
+FRAME_UNITS = r"""
+echo "== units mentioning usb/gadget"; systemctl list-units --all --no-pager 2>/dev/null | grep -i -E 'gadget|usb' | head -20
+for u in $(systemctl list-unit-files --no-pager 2>/dev/null | grep -i -E 'gadget|usb' | awk '{print $1}' | head -8); do
+  echo "== $u"; systemctl cat "$u" --no-pager 2>/dev/null | grep -v '^#' | grep -v '^$' | head -30; done
+echo "== NetworkManager usb0"; nmcli -f GENERAL.CONNECTION,IP4.ADDRESS device show usb0 2>/dev/null
+c=$(nmcli -g GENERAL.CONNECTION device show usb0 2>/dev/null); [ -n "$c" ] && nmcli -f ipv4.method,ipv4.addresses,connection.autoconnect connection show "$c" 2>/dev/null
+echo "== configfs"; ls -la /sys/kernel/config/usb_gadget/ 2>&1 | head; ls /sys/kernel/config/usb_gadget/*/functions/ 2>&1 | head
+echo "== udc"; for u in /sys/class/udc/*; do echo "$u $(cat $u/current_speed 2>/dev/null) $(cat $u/state 2>/dev/null)"; done
+echo "== devkit"; ls -la /etc/steamos-devkit-enabled 2>&1
+"""
+
+
+def frame_to_pc(frame, pc_ips: list[str]) -> list[str]:
+    """Can the Frame open a TCP connection to this PC over the cable (what the setup step needs)?"""
+    lines, got = [], []
+    srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    try:
+        srv.bind(("0.0.0.0", LISTEN_PORT))
+    except OSError as exc:
+        return [f"couldn't listen on {LISTEN_PORT}: {exc}"]
+    srv.listen(4)
+    srv.settimeout(1)
+
+    def accept():
+        end = time.time() + 20
+        while time.time() < end:
+            try:
+                conn, addr = srv.accept()
+                got.append(addr[0])
+                conn.sendall(b"HTTP/1.0 200 OK\r\n\r\nframeport-usb-ok\n")
+                conn.close()
+            except OSError:
+                continue
+    t = threading.Thread(target=accept, daemon=True)
+    t.start()
+    for ip in pc_ips:
+        code, out, err = frame.run(f"curl -s --max-time 6 http://{ip}:{LISTEN_PORT}/ping || echo FAILED", timeout=20)
+        lines.append(f"Frame -> {ip}:{LISTEN_PORT}: {(out or err).strip()[:80]}")
+    t.join(timeout=22)
+    srv.close()
+    lines.append(f"connections seen from: {got or 'none'}")
+    return lines
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out", type=Path, default=Path("usb-autotest.md"))
+    ap.add_argument("--no-speed", action="store_true")
+    args = ap.parse_args()
+    from frameport.frame import usb
+    from frameport.frame.connection import saved_targets
+    from frameport.targets.frame_lepton import FrameLeptonTarget
+
+    report = [f"# USB cable autotest {time.strftime('%Y-%m-%d %H:%M')}", ""]
+
+    def section(title, text):
+        report.extend([f"## {title}", "```", text.strip() or "(nothing)", "```", ""])
+        print(f"--- {title}\n{text.strip()[:3000]}\n", flush=True)
+
+    section("Windows", ps(WINDOWS, timeout=120))
+    wsl = subprocess.run(["ip", "-4", "-o", "addr", "show"], capture_output=True, text=True).stdout
+    section("This side (WSL/Linux) IPv4", wsl)
+    frame = FrameLeptonTarget(saved_targets()[0], None).connect().frame
+    section("Frame units / NetworkManager / configfs", frame.run(FRAME_UNITS, timeout=60)[1])
+    result = usb.check(frame, measure=not args.no_speed)
+    section("frameport frame usb-check", json.dumps(result, indent=1, default=str))
+    ips = result.get("pc_addresses") or []
+    section("Frame -> PC over the cable (setup direction)", "\n".join(frame_to_pc(frame, ips)) if ips else
+            "skipped: this side has no address on the Frame's USB network")
+    args.out.write_text("\n".join(report), encoding="utf-8")
+    print(f"report: {args.out}")
+
+
+if __name__ == "__main__":
+    main()
@@ -1,2 +1,2 @@
 # The FramePort version: the single source (pyproject reads it via hatch; CI checks a release tag matches it).
-__version__ = "0.7.0"
+__version__ = "0.11.1"
@@ -202,6 +202,8 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
            "oculus_xr_plugin": bool(il2cpp_meta) and b"\0m_StereoRenderingModeAndroid\0" in il2cpp_meta,
            # Unity's built-in Oculus support checks for Meta's system apps before VR (frame.unity_oculus_check)
            "unity_oculus_check": b"\0com.oculus.systemactivities\0" in lib_bytes.get("libunity.so", b""),
+            # 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,
        },
    )
@@ -247,7 +249,7 @@ def missing_ovr_symbols(lib_bytes: dict[str, bytes]) -> set[str]:
        return set()
    exported = set(elf.dyn_symbols(loader, True))
    linked = set(elf.needed(loader))
-    for extra in ("libovrplatformcompat.so", "libovrstubs.so"):
+    for extra in ("libovrplatformcompat.so", "libovrstubs.so", "libfp_langpack.so"):
        if extra in lib_bytes and extra in linked:  # only counts when the loader loads it (a lone file doesn't help)
            exported |= elf.dyn_symbols(lib_bytes[extra], True)
    wanted = set()
@@ -106,6 +106,29 @@ def replace_rodata_string(data: bytes, old: str, new: str) -> tuple[bytes, int]:
    return bytes(buf), count


+def hide_exports(data: bytes, names) -> tuple[bytes, list[str]]:
+    """Make the exported functions `names` invisible to symbol lookup without removing them: their .dynsym entries
+    become STB_LOCAL (name, value and section stay, nothing moves, the hash tables are untouched). Both bionic's and
+    glibc's lookups only match GLOBAL/WEAK entries, so a lookup for such a name (a game's import, or dlsym on this
+    library's handle) goes on to the next library in the dependency list; code that reads the library's own .dynsym
+    (native/langpack) still finds the original address. Returns (data, names actually hidden); ELF64 only."""
+    if not is_elf(data) or not is_64bit(data) or data[5] != 1:
+        return data, []
+    sec = _elf(data).get_section_by_name(".dynsym")
+    if not isinstance(sec, SymbolTableSection):
+        return data, []
+    wanted = set(names)
+    entsize, start = sec["sh_entsize"] or 24, sec["sh_offset"]
+    buf, hidden = bytearray(data), []
+    for i, sym in enumerate(sec.iter_symbols()):
+        if (sym.name in wanted and sym["st_shndx"] != "SHN_UNDEF"
+                and sym["st_info"]["bind"] in ("STB_GLOBAL", "STB_WEAK")):
+            at = start + i * entsize + 4  # Elf64_Sym.st_info: binding in the high nibble, type in the low one
+            buf[at] &= 0x0F
+            hidden.append(sym.name)
+    return bytes(buf), sorted(hidden)
+
+
 def add_needed(data: bytes, library: str) -> bytes:
    """Add a DT_NEEDED entry in front of the existing ones (same effect as `patchelf --add-needed`; being first matters
    for symbol interposition, e.g. the GL shim must precede libEGL).
@@ -0,0 +1,28 @@
+"""Language packs (`<BCP47 tag>.lang`) in a game's data folder (OBB / app files); see native/langpack."""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+MAX_DEPTH = 3  # same depth as the runtime scan in native/langpack/langpack.c
+TAG = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def find_tags(data_dir: Path | str | None) -> list[str]:
+    """Tags of the language packs below `data_dir` (de.lang -> "de"), sorted, first file per tag."""
+    if not data_dir:
+        return []
+    root = Path(data_dir)
+    if not root.is_dir():
+        return []
+    seen: dict[str, str] = {}
+    base_depth = len(root.parts)
+    for folder, dirs, files in os.walk(root):
+        if len(Path(folder).parts) - base_depth >= MAX_DEPTH:
+            dirs[:] = []
+        for name in files:
+            stem, dot, ext = name.rpartition(".")
+            if dot and ext.lower() == "lang" and TAG.match(stem):
+                seen.setdefault(stem.lower(), stem)
+    return sorted(seen.values(), key=str.lower)
@@ -0,0 +1,184 @@
+"""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
+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
+
+import hashlib
+import re
+import shutil
+import tarfile
+import zipfile
+from pathlib import Path
+
+from ..core.paths import user_data_dir
+
+EM_AARCH64, EM_X86_64 = 183, 62
+ARCHIVES = (".zip", ".tar.gz", ".tgz", ".tar.xz", ".txz", ".tar.bz2", ".tar")
+OPENXR_MARKERS = (b"libopenxr_loader.so", b"xrCreateInstance")
+MAX_SCAN = 256 << 20  # don't read huge files looking for OpenXR markers
+
+
+def elf_machine(path: Path) -> int | None:
+    """e_machine of an ELF file (183 = aarch64, 62 = x86_64), None if it isn't ELF."""
+    try:
+        with open(path, "rb") as f:
+            head = f.read(20)
+    except OSError:
+        return None
+    if head[:4] != b"\x7fELF" or len(head) < 20:
+        return None
+    return int.from_bytes(head[18:20], "little" if head[5] == 1 else "big")
+
+
+def is_appimage(path: Path) -> bool:
+    try:
+        with open(path, "rb") as f:
+            head = f.read(11)
+    except OSError:
+        return False
+    return head[:4] == b"\x7fELF" and head[8:11] == b"AI\x02"
+
+
+def is_archive(path: Path) -> bool:
+    return path.is_file() and path.name.lower().endswith(ARCHIVES)
+
+
+def looks_like_linux_app(path: Path) -> bool:
+    """For the file picker / drag-and-drop: something this module can add."""
+    path = Path(path)
+    return path.is_dir() or is_archive(path) or is_appimage(path) or elf_machine(path) is not None
+
+
+def slug(name: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", name.lower()).strip("_")[:48] or "app"
+
+
+def clean_title(name: str) -> str:
+    """'Venera-Prime-2.4.2-aarch64.AppImage' -> 'Venera Prime'."""
+    stem = re.sub(r"(\.AppImage|\.tar\.\w+|\.tgz|\.txz|\.zip)$", "", name, flags=re.I)
+    stem = re.split(r"[-_ .]v?\d+(\.\d+)+", stem, maxsplit=1)[0]
+    stem = re.sub(r"[-_ .](linux|aarch64|arm64|x86_64|amd64)\b.*$", "", stem, flags=re.I)
+    return re.sub(r"[-_.]+", " ", stem).strip() or name
+
+
+def unpack(archive: Path) -> Path:
+    """Unpack an archive into <data>/linux-apps/<slug>-<hash>/ (once per archive version)."""
+    st = archive.stat()
+    key = hashlib.sha1(f"{archive.resolve()}:{st.st_size}:{st.st_mtime_ns}".encode()).hexdigest()[:8]
+    dest = user_data_dir() / "linux-apps" / f"{slug(clean_title(archive.name))}-{key}"
+    done = dest / ".unpacked"
+    if done.exists():
+        return dest
+    shutil.rmtree(dest, ignore_errors=True)
+    dest.mkdir(parents=True)
+    if archive.name.lower().endswith(".zip"):
+        with zipfile.ZipFile(archive) as z:
+            for info in z.infolist():
+                target = (dest / info.filename).resolve()
+                if not str(target).startswith(str(dest.resolve())):
+                    raise ValueError(f"unsafe path in archive: {info.filename}")
+            z.extractall(dest)
+    else:
+        with tarfile.open(archive) as t:
+            t.extractall(dest, filter="data")
+    done.write_text(archive.name, encoding="utf-8")
+    return dest
+
+
+def _desktop_exec(root: Path) -> str | None:
+    for desktop in sorted(root.rglob("*.desktop"))[:5]:
+        m = re.search(r"^Exec=(\S+)", desktop.read_text(encoding="utf-8", errors="replace"), re.M)
+        if m:
+            return Path(m.group(1).strip('"')).name
+    return None
+
+
+def _desktop_name(root: Path) -> str | None:
+    for desktop in sorted(root.rglob("*.desktop"))[:5]:
+        m = re.search(r"^Name=(.+)$", desktop.read_text(encoding="utf-8", errors="replace"), re.M)
+        if m:
+            return m.group(1).strip()
+    return None
+
+
+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."""
+    wanted = _desktop_exec(root)
+    folder = slug(root.name.split("-")[0])
+    found = []
+    for p in root.rglob("*"):
+        if not p.is_file() or ".so" in p.name or p.suffix in (".py", ".pyc", ".txt", ".json"):
+            continue
+        machine = elf_machine(p)
+        if machine is None:
+            continue
+        rel_depth = len(p.relative_to(root).parts)
+        score = (100 if wanted and p.name == wanted else 0) + (30 if slug(p.stem) and slug(p.stem) in folder else 0) \
+            + (20 if folder and folder in slug(p.stem) else 0) - 5 * rel_depth
+        found.append((score, p.stat().st_size, p, machine))
+    found.sort(key=lambda t: (-t[0], -t[1]))
+    return [(p, m) for _s, _size, p, m in found]
+
+
+def app_libraries(root: Path, exe: Path) -> list[Path]:
+    """Libraries the program loads: next to it, in a lib*/ folder beside it, or the app's usr/lib*. Libraries deep
+    in data folders don't count (FramePort's own build ships FrameBridge's OpenXR loader as data and isn't VR)."""
+    dirs = {exe.parent}
+    for base in (exe.parent, root, root / "usr"):
+        dirs.update(d for d in base.glob("lib*") if d.is_dir())
+    out = []
+    for d in dirs:
+        out += [p for p in d.glob("*.so*") if p.is_file()]
+    return sorted(out)[:200]
+
+
+def uses_openxr(paths: list[Path]) -> bool:
+    for p in paths:
+        try:
+            if p.stat().st_size > MAX_SCAN:
+                continue
+            data = p.read_bytes()
+        except OSError:
+            continue
+        if any(m in data for m in OPENXR_MARKERS):
+            return True
+    return False
+
+
+def inspect(path: Path) -> dict:
+    """{root, exe (relative to root), appimage, machine, arch_ok, 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):
+        root = unpack(path)
+        subdirs = [d for d in root.iterdir() if not d.name.startswith(".")]
+        if len(subdirs) == 1 and subdirs[0].is_dir():  # the usual single top folder
+            pass
+        title = clean_title(path.name)
+    elif path.is_file():
+        root = path.parent
+        title = clean_title(path.name)
+    else:
+        root = path
+        title = clean_title(path.name)
+    if path.is_file() and not is_archive(path):
+        machine = elf_machine(path)
+        if machine is None:
+            raise ValueError(f"{path.name} isn't a Linux program (AppImage or ELF)")
+        appimage = is_appimage(path)
+        return {"root": str(path.parent), "exe": path.name, "files": [path.name], "appimage": appimage,
+                "machine": machine, "arch_ok": machine == EM_AARCH64, "openxr": uses_openxr([path]),
+                "title": title, "candidates": [path.name]}
+    programs = rank_programs(root)
+    if not programs:
+        raise ValueError(f"no Linux program found in {path.name}")
+    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)
+    title = _desktop_name(root) or title
+    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]}
@@ -18,6 +18,10 @@ TYPE_INT_BOOLEAN = 0x12
 ANDROID_NS = "http://schemas.android.com/apk/res/android"
 LAUNCHER = "android.intent.category.LAUNCHER"
 INFO = "android.intent.category.INFO"
+MAIN = "android.intent.action.MAIN"
+DEFAULT = "android.intent.category.DEFAULT"
+VR_CATEGORY = "com.oculus.intent.category.VR"
+COMPONENTS = ("activity", "activity-alias", "service", "receiver", "provider")


@dataclass
@@ -226,6 +230,81 @@ def fix_launcher(manifest: bytes) -> bytes | None:
    return x.bytes() if x.retarget("category", info, launcher) else None


+def component_filters(manifest: bytes) -> list[tuple[str, str, list[tuple[str, int, int]]]]:
+    """[(element, component name, [(element, attr offset, string index)])] for each component's intent-filter
+    children (action/category), in file order. Children follow their component's start element, so the last
+    component seen owns them."""
+    x = Axml(manifest)
+    names = x.strings()
+    out: list = []
+    for el in x.elements():
+        if el.name in COMPONENTS:
+            out.append((el.name, x.attr_str(el, "name") or "", []))
+        elif el.name in ("action", "category") and out:
+            for a in el.attrs:
+                if a.name < len(names) and names[a.name] == "name":
+                    idx = a.raw if a.raw < len(names) else a.value
+                    out[-1][2].append((el.name, a.offset, idx))
+    return out
+
+
+def vr_activity(manifest: bytes) -> str | None:
+    """The activity with Meta's VR category when it isn't the launcher activity (a 2D launcher that starts the VR
+    part, e.g. WiiCompiled's LauncherActivity -> QuestActivity)."""
+    x = Axml(manifest)
+    names = x.strings()
+    vr = launcher = None
+    for el, name, items in component_filters(manifest):
+        cats = {names[i] for kind, _, i in items if kind == "category" and i < len(names)}
+        if el == "activity" and VR_CATEGORY in cats:
+            vr = vr or name
+        if LAUNCHER in cats:
+            launcher = launcher or name
+    return vr if vr and vr != launcher else None
+
+
+def set_start_activity(manifest: bytes, activity: str) -> bytes | None:
+    """Make `activity` the one Lepton starts: its MAIN intent-filter gets category LAUNCHER (in place of its VR or
+    DEFAULT category), every other component's LAUNCHER category becomes INFO. Only those attribute values change
+    (per element, not every use of the string). None when `activity` has no MAIN filter or already is the only
+    launcher."""
+    filters = component_filters(manifest)
+    x = Axml(manifest)
+    names = x.strings()
+    short = activity.rsplit(".", 1)[-1]
+    target = next((f for f in filters if f[0] in ("activity", "activity-alias")
+                   and (f[1] == activity or f[1].rsplit(".", 1)[-1] == short)), None)
+    if target is None or not any(k == "action" and names[i] == MAIN for k, _, i in target[2] if i < len(names)):
+        return None
+    cats = [(off, names[i]) for k, off, i in target[2] if k == "category" and i < len(names)]
+    others = [off for f in filters if f is not target for k, off, i in f[2]
+              if k == "category" and i < len(names) and names[i] == LAUNCHER]
+    if any(c == LAUNCHER for _, c in cats) and not others:
+        return None
+    pick = next((off for off, c in cats if c == VR_CATEGORY), None) or next(
+        (off for off, c in cats if c == DEFAULT), None) or next((off for off, c in cats if c != LAUNCHER), None)
+    if pick is None and not any(c == LAUNCHER for _, c in cats):
+        return None
+
+    def index(s: str) -> int:
+        i = x.index(s)
+        return i if i is not None else x.append_string(s)
+    launcher, info = index(LAUNCHER), index(INFO)
+    # append_string rebuilds the pool: offsets of attribute records move by the same amount for all of them
+    shift = len(x.data) - len(manifest)
+    for off in others:
+        _set_string_attr(x, off + shift, info)
+    if pick is not None and not any(c == LAUNCHER for _, c in cats):
+        _set_string_attr(x, pick + shift, launcher)
+    return x.bytes()
+
+
+def _set_string_attr(x: Axml, offset: int, index: int) -> None:
+    struct.pack_into("<I", x.data, offset + 8, index)
+    if x.data[offset + 15] == TYPE_STRING:
+        struct.pack_into("<I", x.data, offset + 16, index)
+
+
 def set_bool_attr(manifest: bytes, element: str, attr: str, value: bool) -> bytes | None:
    x = Axml(manifest)
    return x.bytes() if x.set_bool(element, attr, value) else None
@@ -251,3 +251,68 @@ def apply_choice(package: str, choice: dict) -> bool:
        return True
    finally:
        shutil.rmtree(stage, ignore_errors=True)
+
+
+# The user's own images (Artwork dialog → "Your own images"), for games whose art can't be found automatically.
+CUSTOM_KINDS = ("portrait", "landscape", "hero", "logo", "icon")
+CUSTOM_MAX_BYTES = 40 << 20
+CUSTOM_MIN_PX = 64
+CUSTOM_MAX_PX = 3840  # larger images are scaled down (Steam's biggest shape is 1920 px wide)
+
+
+class ArtError(ValueError):
+    """The chosen file can't be used as artwork (the message says why, for the GUI)."""
+
+
+def apply_custom(package: str, kind: str, path: str | Path) -> Path:
+    """Store an image file the user chose as one kind of artwork, replacing that kind only. It is checked and
+    re-encoded (PNG when it has transparency, else JPEG; logos and icons always PNG), marked as the user's pick so
+    automatic fetches never replace it, and the old thumbnails go. FramePort's generated cover/banner (games without
+    store art) are dropped once a real cover shape exists. Returns the stored file."""
+    from PIL import Image, UnidentifiedImageError
+
+    if kind not in CUSTOM_KINDS:
+        raise ArtError(f"unknown artwork kind {kind!r}")
+    path = Path(path)
+    try:
+        if path.stat().st_size > CUSTOM_MAX_BYTES:
+            raise ArtError(f"{path.name} is larger than {CUSTOM_MAX_BYTES >> 20} MB")
+        with Image.open(path) as im:
+            im.load()
+            im = im.copy()
+    except (OSError, UnidentifiedImageError, Image.DecompressionBombError):
+        raise ArtError(f"{path.name} isn't an image FramePort can read (use PNG, JPEG or WebP)") from None
+    if min(im.size) < CUSTOM_MIN_PX:
+        raise ArtError(f"{path.name} is too small ({im.width}×{im.height}); use at least {CUSTOM_MIN_PX} px")
+    if max(im.size) > CUSTOM_MAX_PX:
+        im.thumbnail((CUSTOM_MAX_PX, CUSTOM_MAX_PX), Image.LANCZOS)
+    alpha = im.mode in ("RGBA", "LA", "PA") or (im.mode == "P" and "transparency" in im.info)
+    png = alpha or kind in ("logo", "icon")
+    d = fetch.artwork_dir(package)
+    tmp = d / f".custom-{kind}.tmp"
+    if png:
+        im.convert("RGBA" if alpha else "RGB").save(tmp, "PNG", optimize=True)
+    else:
+        im.convert("RGB").save(tmp, "JPEG", quality=92, optimize=True)
+    _drop_kind(d, kind)
+    out = d / f"{kind}{'.png' if png else '.jpg'}"
+    tmp.replace(out)
+    if kind in ("portrait", "landscape", "hero"):
+        for stem in ("cover", "banner"):
+            _drop_kind(d, stem)
+    (d / fetch.PICKED).write_text("custom", encoding="utf-8")  # automatic fetches leave the art alone
+    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:
+        raise ArtError(f"unknown artwork kind {kind!r}")
+    d = fetch.artwork_dir(package)
+    _drop_kind(d, kind)
+    (d / fetch.PICKED).write_text("custom", encoding="utf-8")  # "Find automatically" brings store art back
+
+
+def _drop_kind(d: Path, kind: str) -> None:
+    for f in list(d.glob(f"{kind}.*")) + list(d.glob(f"t_{kind}_*")):
+        f.unlink(missing_ok=True)
@@ -76,7 +76,8 @@ def steam_set(package: str, title: str = "", apk: str | Path | None = None) -> d
    title = title or package
    out_dir = fetch.artwork_dir(package) / "steam"
    out_dir.mkdir(parents=True, exist_ok=True)
-    placeholder = not (set(src) - {"icon"})  # no store art (at most the APK's icon): the name on a coloured tile
+    # no store art (at most the APK's icon; the GUI's generated cover/banner don't count): the name on a coloured tile
+    placeholder = not (set(src) & (STORE_KINDS | {"shot"}))
    parts = [f"{k}:{p.stat().st_size}:{p.stat().st_mtime_ns}" for k, p in sorted(src.items())]
    if placeholder:
        parts.append(f"placeholder:{PLACEHOLDER_VERSION}:{title}:{apk or ''}")
@@ -298,6 +299,8 @@ def _placeholder(out_dir: Path, title: str, icon_file: Path | None, apk) -> dict
 def original_platform(entry: dict) -> str:
    """What the game was made for (a Steam tag)."""
    extra = (entry.get("analysis") or {}).get("extra") or {}
+    if entry.get("kind") == "linux":
+        return "Linux"
    if entry.get("kind") == "rift":
        if extra.get("flat"):
            return "Windows"
@@ -314,7 +317,7 @@ def steam_tags(entry: dict, where: str = "frame") -> list[str]:
    kind = ((entry.get("analysis") or {}).get("extra") or {}).get("vr_kind") or "quest"
    flat = bool(((entry.get("analysis") or {}).get("extra") or {}).get("flat"))
    runs = TAG if where != "frame" else ("Windows game on Frame" if flat else "PC VR on Frame") \
-        if entry.get("kind") == "rift" else \
+        if entry.get("kind") == "rift" else "Linux app on Frame" if entry.get("kind") == "linux" else \
        "Quest on Frame" if kind == "quest" else "Android on Frame"
    base = [runs, original_platform(entry)]
    genres = ((entry.get("details") or {}).get("genres") or [])[:4]
@@ -84,6 +84,9 @@ def _update_hint() -> None:
    age = updates.cache_age()
    if age is None or age > updates.CHECK_EVERY:
        threading.Thread(target=updates.refresh_cache, daemon=True).start()
+        from .recommend import catalog as _catalog
+
+        threading.Thread(target=_catalog.refresh_remote, daemon=True).start()  # confirmed configs from GitHub main
    up = updates.cached_update()
    today = time.strftime("%Y-%m-%d")
    if up and library.setting("update.cli_hint") != today:
@@ -227,6 +230,31 @@ def scan(path: Path = typer.Argument(..., help="a folder with game backups (APKs
        typer.echo(f"{g['package']:40} {g.get('title', '')[:34]:34} {r['status']:11} {r['source']}")


+@app.command("catalog-update")
+def catalog_update():
+    """Fetch confirmed game configs from the repo's main branch now (normally automatic, every 6 h)."""
+    from .recommend import catalog
+
+    n = catalog.refresh_remote(force=True)
+    st = catalog.remote_status()
+    typer.echo(f"{n} config(s) downloaded; {st['entries']} on GitHub main")
+    for pkg, why in sorted(st["skipped"].items()):
+        typer.echo(f"  skipped {pkg}: {why}")
+
+
+@app.command("add-linux")
+def add_linux(path: Path = typer.Argument(..., help="an arm64 AppImage, a folder, or a .zip/.tar.gz with the app"),
+              exe: Optional[str] = typer.Option(None, help="the program to start (relative to the app's folder)")):
+    """Add a native arm64 Linux app to the library (installed on the Frame as it is, with a Steam shortcut)."""
+    try:
+        g = pipeline.add_linux_app(path, printing_reporter(verbose=False), exe=exe)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from None
+    extra = g["analysis"]["extra"]
+    typer.echo(f"{g['package']:40} {g.get('title', '')[:34]:34} program {extra['exe']}"
+               f"{' (AppImage)' if extra['appimage'] else ''}{' VR' if extra['openxr'] else ''}")
+
+
@app.command("list")
 def list_games():
    """The games in the library."""
@@ -480,6 +508,16 @@ def frame_info(frame: Optional[str] = typer.Option(None, help=FRAME_HELP)):
    typer.echo(json.dumps(_target(frame).describe(), indent=1, default=str))


+@frame_app.command("usb-check")
+def frame_usb_check(frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
+                    no_speed: bool = typer.Option(False, help="skip the upload speed test (2 × 128 MB)")):
+    """Check the USB cable link to the Frame: what the Frame presents, this PC's address on it, SSH over it and its
+    upload speed vs the normal connection (JSON)."""
+    from .frame import usb
+
+    typer.echo(json.dumps(usb.check(_target(frame).connect().frame, measure=not no_speed), indent=1, default=str))
+
+
@frame_app.command("controller-models")
 def frame_controller_models(frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
                            convert: bool = typer.Option(False, help="also convert them (cached on the Frame)")):
@@ -22,17 +22,40 @@ def _path() -> Path:
    return user_data_dir() / "library.json"


+_updating = threading.local()  # set while load() runs the migrations/catalog step (see load)
+
+
 def load() -> dict:
    with _lock:
        try:
            data = json.loads(_path().read_text(encoding="utf-8"))
        except (OSError, ValueError):
            return {"games": {}, "settings": {}}
-        if _migrate(data) | _follow_catalog(data):
+        # The catalog step loads the catalog, whose first load reads a setting: that nested load() must not run the
+        # step again (GitHub #58: ~140 nested loads and a 30 s blank window, or a crash at start-up)
+        if getattr(_updating, "active", False):
+            return data
+        _updating.active = True
+        try:
+            changed = _migrate(data) | _follow_catalog(data)
+        finally:
+            _updating.active = False
+        if changed:
            save(data)
        return data


+def peek_setting(key: str, default=None):
+    """A setting as stored, without migrations or the catalog step (for code that load() itself runs)."""
+    with _lock:
+        try:
+            data = json.loads(_path().read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return default
+    settings = data.get("settings") if isinstance(data, dict) else None
+    return settings.get(key, default) if isinstance(settings, dict) else default
+
+
@contextmanager
 def edit() -> Iterator[dict]:
    """A read-modify-write of the whole library as one step: `with edit() as data: ...` (saved on exit)."""
@@ -58,8 +81,26 @@ def _follow_catalog(data: dict) -> bool:
    settings["recipes.app_version"] = __version__
    for pkg, g in (data.get("games") or {}).items():
        r, a = g.get("recipe"), g.get("analysis")
-        if not isinstance(r, dict) or not isinstance(a, dict) or r.get("source") == "user":
+        if g.get("kind") == "linux":  # installed as it is: no recipe to derive
            continue
+        if app_updated and isinstance(a, dict):
+            changed |= _refresh_data_fields(g, a)
+        if not isinstance(r, dict) or not isinstance(a, dict):
+            continue
+        if r.get("source") == "user":
+            # the user's own recipe isn't replaced, but a changed catalog entry is offered on the game page (GitHub
+            # #10: a VR4 fix never reached a recipe whose Game settings had been saved once)
+            entry = catalog.lookup(pkg)
+            offer = entry.rev() if entry is not None and r.get("catalog_rev") not in (None, entry.rev()) else None
+            if g.get("catalog_update") != offer:
+                if offer:
+                    g["catalog_update"] = offer
+                else:
+                    g.pop("catalog_update", None)
+                changed = True
+            continue
+        if g.pop("catalog_update", None) is not None:  # no longer the user's recipe (reset): nothing to offer
+            changed = True
        entry = catalog.lookup(pkg)
        if not app_updated and (entry is None or r.get("catalog_rev") == entry.rev()):
            continue
@@ -71,6 +112,21 @@ def _follow_catalog(data: dict) -> bool:
    return changed


+def _refresh_data_fields(g: dict, a: dict) -> bool:
+    """Analysis fields read from the game's data folder (cheap, no APK analysis) that newer FramePort versions added:
+    filled in for games already in the library, so their patches are offered without a re-analysis."""
+    extra = a.setdefault("extra", {})
+    if "lang_packs" in extra or a.get("package", "").startswith("rift."):
+        return False
+    from ..analysis import langpacks
+
+    try:
+        extra["lang_packs"] = langpacks.find_tags(g.get("data_dir"))
+    except OSError:
+        return False
+    return True
+
+
 def _migrate(data: dict) -> bool:
    """One-time updates of stored recipes when a new default is introduced (each runs once per library)."""
    done = data.setdefault("settings", {}).setdefault("migrations", [])
@@ -206,7 +262,7 @@ def _migrate(data: dict) -> bool:
        # Android apps without VR gain the default-on "Hide Android's navigation bar" patch
        for g in (data.get("games") or {}).values():
            a, r = g.get("analysis") or {}, g.get("recipe")
-            if isinstance(r, dict) and (a.get("extra") or {}).get("vr_kind") == "none":
+            if isinstance(r, dict) and (a.get("extra") or {}).get("vr_kind") == "none" and g.get("kind") != "linux":
                r.setdefault("patches", {}).setdefault("device.hide_navbar", {})
                r.setdefault("reasons", {}).setdefault(
                    "device.hide_navbar", "2D app: Android's navigation buttons would cover the app's own controls.")
@@ -16,7 +16,7 @@ def twins(games: list[dict]) -> set[str]:
    by_pkg = {g["package"]: g for g in games}
    quest_by_title = {}
    for g in games:
-        if g.get("kind") != "rift":
+        if g.get("kind") not in ("rift", "linux"):  # (Linux apps have no Quest/Rift twin)
            quest_by_title.setdefault(_norm(g.get("title") or ""), []).append(g["package"])
    out = set()
    for g in games:
@@ -41,11 +41,13 @@ def display_title(game: dict, twin_set: set[str] | None = None) -> str:

 def counterparts(game: dict, games: list[dict]) -> list[dict]:
    """The other-platform versions of this game in the library."""
+    if game.get("kind") == "linux":
+        return []
    rift = game.get("kind") == "rift"
    t = _norm(game.get("title") or "")
    out = []
    for g in games:
-        if g["package"] == game["package"] or (g.get("kind") == "rift") == rift:
+        if g["package"] == game["package"] or (g.get("kind") == "rift") == rift or g.get("kind") == "linux":
            continue
        linked = (rift and game.get("quest_package") == g["package"]) or \
            (not rift and g.get("quest_package") == game["package"])
@@ -170,6 +170,18 @@ def package_listing(g: dict) -> dict[str, object]:
                    pe[rel] = {"error": str(exc)}
            out["pe.json"] = pe
        return out
+    if g.get("kind") == "linux":  # the app's file list (a lone AppImage: only it, not the folder it's in)
+        root, extra = Path(g.get("game_dir") or ""), (g.get("analysis") or {}).get("extra") or {}
+        paths = [root / f for f in extra["files"]] if extra.get("files") else \
+            sorted(root.rglob("*")) if root.is_dir() else []
+        files = []
+        for p in paths:
+            if p.is_file():
+                files.append([p.relative_to(root).as_posix(), p.stat().st_size])
+                if len(files) >= 20000:
+                    break
+        out["files.json"] = files
+        return out
    apk = Path(g.get("apk") or "")
    if not apk.is_file():
        return out
@@ -55,7 +55,7 @@ def working_config_url(g: dict, recipe_yaml: str, status: str, notes: str, env:
                       red: redact.Redactor | None = None) -> str:
    red = red or redact.Redactor()
    title = g.get("title") or g["package"]
-    kind = "Oculus Rift (PC VR)" if g.get("kind") == "rift" else "Meta Quest"
+    kind = {"rift": "Oculus Rift (PC VR)", "linux": "Linux app (arm64)"}.get(g.get("kind"), "Meta Quest")
    a = g.get("analysis") or {}
    game = f"{title} — {g['package']} ({kind}, version {a.get('version') or '?'}, {a.get('engine') or '?'} / " \
           f"{a.get('xr') or '?'})"
@@ -28,6 +28,12 @@ log = logging.getLogger(__name__)
 REMOTE_AGENT_DIR = ".local/share/frameport/agent"


+def agent_version_of(text: str) -> int:
+    """AGENT_VERSION from an agent's source (0 if missing)."""
+    m = re.search(r"^AGENT_VERSION\s*=\s*(\d+)", text, re.M)
+    return int(m.group(1)) if m else 0
+
+
 class FrameNotPaired(ConnectionError):
    """SSH works but none of FramePort's ways in was accepted: the Frame hasn't run the first-time setup (or the
    password was wrong). The message keeps "authentication failed" for older callers."""
@@ -512,8 +518,17 @@ class Frame:
        remote = posixpath.join(remote_dir, "frameport_agent.py")
        if self._agent_digest == digest:
            return remote
-        code, out, _ = self.run(f"sha256sum {sh_quote(remote)} 2>/dev/null | cut -c1-16")
-        if out.strip() != digest:
+        code, out, _ = self.run(f"sha256sum {sh_quote(remote)} 2>/dev/null | cut -c1-16; "
+                                f"grep -m1 '^AGENT_VERSION' {sh_quote(remote)} 2>/dev/null")
+        lines = out.split("\n")
+        remote_version = agent_version_of(lines[1] if len(lines) > 1 else "")
+        if lines[0].strip() != digest and remote_version > agent_version_of(text.decode("utf-8", "replace")):
+            # a newer FramePort (another PC, or FramePort on the Frame) installed a newer agent: keep it. Agents
+            # stay compatible with older apps; replacing it broke the newer one's launchers (2026-10-04: an older
+            # app put agent 43 back over 45 every few seconds)
+            self._agent_digest = digest
+            return remote
+        if lines[0].strip() != digest:
            self.run(f"mkdir -p {sh_quote(remote_dir)}")
            tmp = f"{remote}.{os.getpid()}.{threading.get_ident()}.tmp"  # two threads never share a temp file
            with self.sftp.open(tmp, "wb") as f:
@@ -152,8 +152,41 @@ def browse(seconds: float = 4.0, scan: bool = True) -> list[Found]:
        known = {f.host for f in out}
        for ip in _scan(local_subnets(), known):
            out.append(Found(ip, ip, 22, "steamos", "scan", [ip]))
-    rank = {"frameport": 0, "devkit": 1, "saved": 2, "scan": 3}
-    return sorted(out, key=lambda f: (rank.get(f.source, 9), f.name, link_label(f.host) != "network", f.host))
+    out = dedupe(out)
+    return sorted(out, key=lambda f: (SOURCE_RANK.get(f.source, 9), f.name, LINK_RANK.get(f.via, 9), f.host))
+
+
+SOURCE_RANK = {"frameport": 0, "devkit": 1, "saved": 2, "scan": 3}
+LINK_RANK = {"USB": 0, "Frame hotspot": 1, "network": 2}  # fastest first (USB ~37 MB/s, hotspot ~85, but the hotspot
+# needs the PC on the Frame's Wi-Fi: when both answer, the cable is the deliberate choice)
+
+
+def dedupe(found: list[Found], key_of=None) -> list[Found]:
+    """One entry per Frame: entries whose SSH host key matches (the same device reached over home Wi-Fi, its hotspot
+    and USB, or found by mDNS, the saved list and the network scan) merge into one that uses the fastest link, keeps
+    the best-known source/name and lists the other addresses. Entries whose key can't be read stay as they are."""
+    if key_of is None:
+        from .connection import server_key
+
+        def key_of(f: Found):
+            k = server_key(f.host, f.port, timeout=3)
+            return k.get_base64() if k else None
+    with ThreadPoolExecutor(16) as pool:
+        keys = list(pool.map(key_of, found))
+    groups: dict[str, list[Found]] = {}
+    out = []
+    for f, k in zip(found, keys, strict=True):
+        if k is None:
+            out.append(f)
+        else:
+            groups.setdefault(k, []).append(f)
+    for members in groups.values():
+        best = min(members, key=lambda f: (LINK_RANK.get(f.via, 9), f.host))
+        named = min(members, key=lambda f: (SOURCE_RANK.get(f.source, 9), f.source == "scan"))
+        addresses = list(dict.fromkeys([best.host] + [a for f in members for a in [f.host, *f.addresses]]))
+        out.append(Found(named.name if named.source != "scan" else best.name, best.host, best.port, named.user,
+                         named.source, addresses, {**best.properties, **named.properties}))
+    return out


 def local_ip_towards(host: str = "8.8.8.8") -> str:
@@ -102,11 +102,13 @@ class PairingServer:
    requests: int = 0  # requests from the network (right or wrong code): the Frame can reach us
    flag: Path | None = None  # WSL: the temporary firewall rule stays while this file exists
    hint: str = ""  # set by the UI when nothing reached us after HINT_AFTER seconds: what may block the Frame
+    host: str = ""  # the address the Frame uses to reach this PC; "" = the PC's address towards the internet. The USB
+    # setup uses the cable's fixed PC address (10.86.200.234), so no Wi-Fi, router or discovery is involved
    _httpd: http.server.ThreadingHTTPServer | None = None

    @property
    def url(self) -> str:
-        return f"http://{local_ip_towards()}:{self.port}"
+        return f"http://{self.host or local_ip_towards()}:{self.port}"

    @property
    def one_liner(self) -> str:
@@ -0,0 +1,81 @@
+"""USB cable link to the Frame (usb0, a USB network gadget): one check that answers whether "connect with a USB
+cable" can work on this PC: what the Frame presents, whether this PC got an address on it, whether SSH answers
+over it (same host key), and how fast an upload is compared with the normal connection."""
+from __future__ import annotations
+
+import io
+import os
+import re
+import socket
+import subprocess
+import sys
+import time
+
+USB_IFACE = "usb0"
+FRAME_USB_IP, PC_USB_IP = "10.86.200.233", "10.86.200.234"  # fixed by the Frame's dnsmasq (dhcp-host by MAC)
+TEST_BYTES = 128 << 20
+
+
+def pc_usb_addresses(frame_ip: str) -> list[str]:
+    """This PC's IPv4 addresses in the same /24 as the Frame's USB address (Windows via ipconfig, else `ip`)."""
+    prefix = frame_ip.rsplit(".", 1)[0] + "."
+    texts = []
+    for cmd in (["ip", "-4", "-o", "addr", "show"], ["ipconfig"], ["ifconfig"], ["ipconfig.exe"]):
+        try:
+            texts.append(subprocess.run(cmd, capture_output=True, text=True, timeout=10).stdout)
+        except (OSError, subprocess.SubprocessError):
+            continue
+    text = "\n".join(texts)
+    # interface addresses only (`ip`/ifconfig "inet X", ipconfig "IPv4 Address ... : X"): not broadcast/netmask values
+    found = re.findall(r"\binet\s+(\d+\.\d+\.\d+\.\d+)", text) + \
+        re.findall(r"IPv4[^:\n]*:\s*(\d+\.\d+\.\d+\.\d+)", text)
+    return sorted({ip for ip in found if ip.startswith(prefix) and ip != frame_ip})
+
+
+def upload_speed(frame, size: int = TEST_BYTES) -> float:
+    """MB/s of one SFTP upload of `size` bytes to /tmp on the Frame (removed afterwards)."""
+    path = f"/tmp/frameport-speed-{os.getpid()}"
+    data = io.BytesIO(os.urandom(1 << 20) * (size >> 20))
+    start = time.time()
+    frame.sftp.putfo(data, path)
+    elapsed = time.time() - start
+    frame.run(f"rm -f {path}")
+    return size / elapsed / 1e6
+
+
+def check(frame, measure: bool = True) -> dict:
+    """{frame: <agent usb_link>, frame_ip, pc_addresses, reachable, same_frame, speed_usb, speed_default, notes}."""
+    info = frame.agent("usb_link", timeout=60)
+    out = {"frame": info, "platform": sys.platform, "notes": []}
+    ip = next((a.split("/")[0] for a in info.get("addresses") or []), None)
+    out["frame_ip"] = ip
+    if not info.get("present"):
+        out["notes"].append("The Frame has no usb0 link: is the cable in the Frame's USB-C port and the PC?")
+        return out
+    if not ip:
+        out["notes"].append("usb0 exists but has no address on the Frame (cable not connected to a PC?)")
+        return out
+    out["pc_addresses"] = pc_usb_addresses(ip)
+    if not out["pc_addresses"]:
+        out["notes"].append("This PC has no address on the Frame's USB network: no driver for the gadget "
+                            f"({', '.join(info.get('functions') or []) or 'unknown type'}) or no DHCP from the Frame")
+    try:
+        socket.create_connection((ip, frame.target.port), timeout=3).close()
+        out["reachable"] = True
+    except OSError:
+        out["reachable"] = False
+        out["notes"].append(f"SSH ({ip}:{frame.target.port}) doesn't answer over the cable from this PC")
+        return out
+    from .connection import Frame, FrameTarget
+
+    other = Frame(FrameTarget(ip, frame.target.user, frame.target.port), frame.password)
+    try:
+        other.connect(timeout=10)
+        out["same_frame"] = (other.client.get_transport().get_remote_server_key()
+                             == frame.client.get_transport().get_remote_server_key())
+        if measure:
+            out["speed_usb"] = round(upload_speed(other), 1)
+            out["speed_default"] = round(upload_speed(frame), 1)
+    finally:
+        other.close()
+    return out
@@ -217,6 +217,57 @@ def install_pcvr(frame: Frame, plan: PcvrPlan, reporter: Reporter) -> dict:
    return result


+@dataclass
+class LinuxPlan:
+    package: str  # "linux.<slug>"
+    title: str
+    root: Path  # the app's folder (for a lone AppImage: the folder it's in, with files = [its name])
+    exe: str  # relative to root
+    files: list[str] | None = None  # only these files of root (a lone AppImage), else the whole folder
+    appimage: bool = False
+    openxr: bool = False
+
+
+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)."""
+    reporter.stage("Prepare Frame")
+    prep = frame.agent("prepare_linux", package=plan.package, title=plan.title)
+    if plan.files:
+        manifest = {name: (plan.root / name).stat().st_size for name in plan.files}
+    else:
+        manifest = local_data_manifest(plan.root)
+        manifest = {k: v for k, v in manifest.items() if not k.startswith(".unpacked")}
+    to_send = [rel for rel, size in manifest.items() if prep["existing"].get("app", {}).get(rel) != size]
+    need = sum(manifest[rel] for rel in to_send)
+    if need > prep["free_bytes"] - (1 << 30):
+        raise RuntimeError(f"not enough space on the Frame: need {need / 2**30:.1f} GiB + 1 GiB headroom, "
+                           f"have {prep['free_bytes'] / 2**30:.1f} GiB")
+    if to_send:
+        reporter.stage(f"Upload app ({len(to_send)} files, {need / 2**20:.0f} MiB)")
+        with transfer_link(frame, reporter, need) as xfer:
+            upload_files(xfer, [(plan.root / rel, f"app/{rel}", manifest[rel]) for rel in to_send],
+                         prep["incoming"], reporter, max(need, 1), 0)
+    else:
+        reporter.log("all app files already on the Frame; not re-sending")
+    upload_steam_art(frame, plan.package, prep["base"], reporter)
+    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)
+    reporter.log(f"installed at {result['base']} (Steam shortcut id {result['appid']})")
+    return result
+
+
+def _is_elf(path: Path) -> bool:
+    try:
+        with open(path, "rb") as f:
+            return f.read(4) == b"\x7fELF"
+    except OSError:
+        return False
+
+
 def ensure_proton(frame: Frame, reporter: Reporter, tool: str | None = None, timeout: float = 45 * 60) -> 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)."""
@@ -230,6 +281,7 @@ def ensure_proton(frame: Frame, reporter: Reporter, tool: str | None = None, tim
    reporter.log(r.get("hint") or f"installing {r.get('tool')}")
    end = time.time() + timeout
    last = None
+    asked_runtime = False
    while time.time() < end:
        reporter.check_cancel()
        time.sleep(10)
@@ -241,6 +293,14 @@ def ensure_proton(frame: Frame, reporter: Reporter, tool: str | None = None, tim
            reporter.check("Proton installed", True, st["ready"]["display_name"])
            return st["ready"]
        dl = st.get("download") or {}
+        sug = st.get("suggested") or {}
+        if sug.get("installed") and not sug.get("require_installed") and not dl.get("total") and not asked_runtime:
+            # Steam names the runtime a Proton needs (e.g. Experimental) only once Proton itself is installed: ask
+            # for it now
+            asked_runtime = True
+            reporter.log("installing the Steam Linux Runtime this Proton needs")
+            frame.agent("install_proton", mode="unattended", tool=tool)
+            continue
        if dl.get("total"):
            reporter.progress(dl["done"] / dl["total"], f"downloading Proton {dl['done'] / 2**20:.0f}/"
                                                         f"{dl['total'] / 2**20:.0f} MiB")
@@ -0,0 +1,138 @@
+# ruff: noqa: E501  (the embedded page's JavaScript)
+"""The Live view player page (served by livestream.py). A Python string rather than an .html file: the
+PyInstaller fallback bundle only carries data files it is told about."""
+
+PLAYER_HTML = r"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>FramePort Live view</title>
+<style>
+  :root { --bg: #0e1013; --text: #e8eaed; --muted: #9aa0a6; --accent: #66b3ff; --panel: rgba(20, 22, 26, .82); }
+  html, body { margin: 0; height: 100%; background: var(--bg); color: var(--text);
+               font: 14px/1.4 system-ui, -apple-system, "Segoe UI", sans-serif; overflow: hidden; }
+  video { position: fixed; inset: 0; width: 100%; height: 100%; object-fit: contain; background: #000; }
+  #bar { position: fixed; left: 12px; right: 12px; bottom: 12px; display: flex; gap: 12px; align-items: center;
+         padding: 8px 12px; border-radius: 10px; background: var(--panel); transition: opacity .3s; }
+  body.idle #bar { opacity: 0; }
+  #dot { width: 9px; height: 9px; border-radius: 50%; background: var(--muted); flex: none; }
+  #dot.live { background: #3ddc84; } #dot.err { background: #ff6b6b; }
+  #msg { flex: 1; min-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  #info { color: var(--muted); font-variant-numeric: tabular-nums; }
+  button { background: transparent; color: var(--text); border: 1px solid #3c4043; border-radius: 6px;
+           padding: 4px 10px; font: inherit; cursor: pointer; }
+  button:hover { border-color: var(--accent); }
+</style>
+</head>
+<body>
+<video id="v" muted autoplay playsinline disablepictureinpicture></video>
+<div id="bar">
+  <span id="dot"></span><span id="msg">Connecting to the Frame…</span><span id="info"></span>
+  <button id="snd" hidden title="Browsers start videos muted: click to hear the Frame">Sound on</button>
+  <button id="fs" title="Full screen (or double-click the picture)">Full screen</button>
+</div>
+<script>
+"use strict";
+const video = document.getElementById("v"), dot = document.getElementById("dot");
+const msg = document.getElementById("msg"), info = document.getElementById("info");
+const CUSHION = 0.3, CATCH_UP = 0.7, FAR_BEHIND = 2.0, KEEP = 10;  // seconds behind the newest data
+let session = 0, frames = 0, lastFrames = 0, size = "";
+
+function say(text, state) { msg.textContent = text; dot.className = state || ""; }
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+async function status() {
+  try { const r = await fetch("status", {cache: "no-store"}); return await r.json(); }
+  catch (e) { return null; }
+}
+
+async function run() {
+  const id = ++session;
+  let st = await status();
+  while (id === session && (!st || !st.ready)) {
+    if (st && st.ended) { say("Stopped: " + st.ended + " — start it again in FramePort.", "err"); return; }
+    if (!st) { say("FramePort isn't streaming any more. Start Live view in FramePort.", "err"); return; }
+    say("Waiting for the first picture from the Frame…");
+    await sleep(500); st = await status();
+  }
+  const type = 'video/mp4; codecs="' + (st.codec || "avc1.640028") + '"';
+  const MS = window.ManagedMediaSource || window.MediaSource;
+  if (!MS || !MS.isTypeSupported(type)) { say("This browser can't play H.264 video (" + type + "). Copy this page's address into another browser.", "err"); return; }
+  size = st.width ? st.width + "×" + st.height : "";
+  snd.hidden = !st.audio;
+  const ms = new MS();
+  video.disableRemotePlayback = true;
+  video.src = URL.createObjectURL(ms);
+  await new Promise(r => ms.addEventListener("sourceopen", r, {once: true}));
+  const sb = ms.addSourceBuffer(type);
+  sb.mode = "segments";
+  const pending = [];
+  const pump = () => {
+    if (sb.updating || !pending.length || ms.readyState !== "open") return;
+    try { sb.appendBuffer(pending.shift()); } catch (e) { trim(true); }
+  };
+  const trim = (force) => {
+    if (sb.updating || !sb.buffered.length) return;
+    const start = sb.buffered.start(0), cut = video.currentTime - (force ? 1 : KEEP);
+    if (cut > start) { try { sb.remove(start, cut); } catch (e) {} }
+  };
+  sb.addEventListener("updateend", () => {
+    if (sb.buffered.length) {
+      const end = sb.buffered.end(sb.buffered.length - 1);
+      const lag = end - video.currentTime;
+      if (lag > FAR_BEHIND || video.currentTime < sb.buffered.start(0)) video.currentTime = Math.max(end - CUSHION, 0);
+      else video.playbackRate = lag > CATCH_UP ? 1.1 : lag < CUSHION ? 1.0 : video.playbackRate;
+      if (video.paused) video.play().catch(() => {});
+    }
+    pump();
+  });
+  try {
+    const resp = await fetch("stream.mp4", {cache: "no-store"});
+    if (!resp.ok) throw new Error(await resp.text());
+    say("Live from the Frame", "live");
+    const reader = resp.body.getReader();
+    let n = 0;
+    while (id === session) {
+      const {value, done} = await reader.read();
+      if (done) break;
+      pending.push(value); frames++;
+      if (++n % 60 === 0) trim(false);
+      pump();
+    }
+  } catch (e) {
+    say("Connection lost (" + e.message + "), reconnecting…", "err");
+  }
+  if (id !== session) return;
+  await sleep(1000);
+  const again = await status();
+  if (again && again.ended) { say("Stopped: " + again.ended + " — start it again in FramePort.", "err"); return; }
+  run();
+}
+
+setInterval(() => {
+  const chunks = frames - lastFrames; lastFrames = frames;
+  info.textContent = [size, chunks ? "receiving" : ""].filter(Boolean).join(" · ");
+}, 1000);
+document.addEventListener("visibilitychange", () => { if (!document.hidden) run(); });
+const toggleFs = () => document.fullscreenElement ? document.exitFullscreen() : document.documentElement.requestFullscreen();
+document.getElementById("fs").onclick = toggleFs;
+const snd = document.getElementById("snd");
+let wantSound = false;  // the choice survives reconnects (each one makes a new MediaSource)
+snd.onclick = () => {
+  wantSound = !wantSound; video.muted = !wantSound;
+  snd.textContent = wantSound ? "Mute" : "Sound on";
+  if (wantSound) video.play().catch(() => {});
+};
+video.addEventListener("loadedmetadata", () => { video.muted = !wantSound; });
+video.ondblclick = toggleFs;
+let idle;
+document.addEventListener("mousemove", () => {
+  document.body.classList.remove("idle"); clearTimeout(idle);
+  idle = setTimeout(() => document.body.classList.add("idle"), 2500);
+});
+run();
+</script>
+</body>
+</html>
+"""
@@ -0,0 +1,508 @@
+"""Live view: what the Frame shows, played in a browser window on this PC (the GUI's Live view tab).
+
+The Frame sends fragmented MP4 (H.264) on the stdout of one SSH command (`source_command`); a small HTTP server on
+127.0.0.1 relays it to a player page (`live_player.py`: Media Source Extensions, no plugin). Flet has no video control
+outside packaged builds, so the picture is shown in the browser, which also decodes it in hardware.
+
+The relay keeps the init segment (ftyp + moov) and the fragments since the last keyframe, so a viewer that opens later
+starts at a keyframe. No image bytes ever go through Flet.
+"""
+from __future__ import annotations
+
+import json
+import queue
+import struct
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+SAMPLE_NON_SYNC = 0x10000  # ISO/IEC 14496-12 sample_is_non_sync_sample
+CLIENT_QUEUE = 240  # fragments a slow viewer may lag behind before it's dropped (it reconnects at a keyframe)
+
+
+# ------------------------------------------------------------------------------------------------ MP4 parsing
+def iter_boxes(data: bytes, start: int = 0, end: int | None = None):
+    """(type, payload start, box end) of each complete box in data[start:end]."""
+    end = len(data) if end is None else end
+    pos = start
+    while pos + 8 <= end:
+        size, kind = struct.unpack_from(">I4s", data, pos)
+        header = 8
+        if size == 1:
+            if pos + 16 > end:
+                return
+            size = struct.unpack_from(">Q", data, pos + 8)[0]
+            header = 16
+        elif size == 0:
+            size = end - pos
+        if size < header or pos + size > end:
+            return
+        yield kind.decode("latin-1"), pos + header, pos + size
+        pos += size
+
+
+def _child(data: bytes, start: int, end: int, kind: str):
+    for k, s, e in iter_boxes(data, start, end):
+        if k == kind:
+            return s, e
+    return None
+
+
+def fragment_is_keyframe(moof: bytes, track_id: int | None = None) -> bool:
+    """Whether a movie fragment starts with a sync sample in the given track (default: its first track): trun's
+    first-sample flags, else its per-sample flags, else tfhd's default flags. Unknown or no such track → False: a
+    viewer then waits for the next fragment that is one."""
+    top = _child(moof, 0, len(moof), "moof")
+    if not top:
+        return False
+    for kind, s, e in iter_boxes(moof, *top):
+        if kind != "traf":
+            continue
+        default_flags = None
+        tfhd = _child(moof, s, e, "tfhd")
+        if tfhd:
+            p = tfhd[0]
+            flags = int.from_bytes(moof[p + 1:p + 4], "big")
+            if track_id is not None and struct.unpack_from(">I", moof, p + 4)[0] != track_id:
+                continue
+            p += 8  # version/flags + track_ID
+            for bit, size in ((0x1, 8), (0x2, 4), (0x8, 4), (0x10, 4)):
+                if flags & bit:
+                    p += size
+            if flags & 0x20 and p + 4 <= tfhd[1]:
+                default_flags = struct.unpack_from(">I", moof, p)[0]
+        trun = _child(moof, s, e, "trun")
+        if not trun:
+            continue
+        p = trun[0]
+        flags = int.from_bytes(moof[p + 1:p + 4], "big")
+        count = struct.unpack_from(">I", moof, p + 4)[0]
+        p += 8
+        if flags & 0x1:
+            p += 4  # data_offset
+        if flags & 0x4:
+            return not struct.unpack_from(">I", moof, p)[0] & SAMPLE_NON_SYNC
+        if count and flags & 0x400:
+            if flags & 0x100:
+                p += 4
+            if flags & 0x200:
+                p += 4
+            return not struct.unpack_from(">I", moof, p)[0] & SAMPLE_NON_SYNC
+        if default_flags is not None:
+            return not default_flags & SAMPLE_NON_SYNC
+        return False
+    return False
+
+
+def codec_string(init: bytes) -> str | None:
+    """The MSE codecs parameter from the init segment: `avc1.PPCCLL` (from avcC), plus `mp4a.40.2` when it has an AAC
+    track (ffmpeg's aac encoder writes AAC-LC)."""
+    i = init.find(b"avcC")
+    if i < 0 or i + 8 > len(init):
+        return None
+    profile, compat, level = init[i + 5], init[i + 6], init[i + 7]
+    out = f"avc1.{profile:02x}{compat:02x}{level:02x}"
+    if b"mp4a" in init:
+        out += ", mp4a.40.2"
+    return out
+
+
+def video_track_id(init: bytes) -> int | None:
+    """track_ID of the init segment's video track (its trak's hdlr is 'vide')."""
+    moov = _child(init, 0, len(init), "moov")
+    if not moov:
+        return None
+    for kind, s, e in iter_boxes(init, *moov):
+        if kind != "trak":
+            continue
+        tkhd, mdia = _child(init, s, e, "tkhd"), _child(init, s, e, "mdia")
+        hdlr = mdia and _child(init, *mdia, "hdlr")
+        if tkhd and hdlr and init[hdlr[0] + 8:hdlr[0] + 12] == b"vide":
+            version = init[tkhd[0]]
+            return struct.unpack_from(">I", init, tkhd[0] + (20 if version == 1 else 12))[0]
+    return None
+
+
+def video_size(init: bytes) -> tuple[int, int] | None:
+    """Width and height from the init segment's avc1 sample entry."""
+    i = init.find(b"avc1")
+    if i < 0 or i + 4 + 28 > len(init):
+        return None
+    p = i + 4 + 24  # sample entry: 6 reserved + 2 data ref index + 16 pre_defined/reserved
+    return struct.unpack_from(">HH", init, p)
+
+
+class Mp4Splitter:
+    """Cuts a byte stream into the init segment and movie fragments (moof + mdat), whatever the read sizes."""
+
+    def __init__(self):
+        self.buf = bytearray()
+        self.init = bytearray()
+        self.have_init = False
+        self._moof: bytes | None = None
+
+    def feed(self, data: bytes) -> list[tuple[str, bytes]]:
+        """[("init", bytes) | ("fragment", bytes)] completed by this data."""
+        self.buf += data
+        out = []
+        while True:
+            if len(self.buf) < 8:
+                break
+            size, kind = struct.unpack_from(">I4s", self.buf, 0)
+            header = 8
+            if size == 1:
+                if len(self.buf) < 16:
+                    break
+                size = struct.unpack_from(">Q", self.buf, 8)[0]
+                header = 16
+            if size < header:
+                raise ValueError(f"bad MP4 box size {size}")
+            if len(self.buf) < size:
+                break
+            box = bytes(self.buf[:size])
+            del self.buf[:size]
+            kind = kind.decode("latin-1")
+            if not self.have_init:
+                self.init += box
+                if kind == "moov":
+                    self.have_init = True
+                    out.append(("init", bytes(self.init)))
+            elif kind == "moof":
+                self._moof = box
+            elif kind == "mdat" and self._moof is not None:
+                out.append(("fragment", self._moof + box))
+                self._moof = None
+            # other top-level boxes (styp, sidx, free) carry nothing a viewer needs
+        return out
+
+
+# ------------------------------------------------------------------------------------------------ relay
+def _end(q: queue.Queue) -> None:
+    """Tell a viewer's sender the stream is over: drop what it hasn't sent yet, then the end marker (None)."""
+    try:
+        while True:
+            q.get_nowait()
+    except queue.Empty:
+        pass
+    try:
+        q.put_nowait(None)
+    except queue.Full:
+        pass
+
+
+class Relay:
+    """Fan-out of one MP4 stream to any number of HTTP viewers."""
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self.init: bytes | None = None
+        self.video_track: int | None = None
+        self.gop: list[bytes] = []  # fragments since the last keyframe fragment (incl.)
+        self.clients: list[queue.Queue] = []
+        self.frames = 0
+        self.bytes = 0
+        self.started = time.time()
+        self.ended: str | None = None  # why the source stopped
+        self._splitter = Mp4Splitter()
+
+    def feed(self, data: bytes) -> None:
+        for kind, chunk in self._splitter.feed(data):
+            with self._lock:
+                self.bytes += len(chunk)
+                if kind == "init":
+                    self.init = chunk
+                    self.video_track = video_track_id(chunk)
+                    continue
+                self.frames += 1
+                if fragment_is_keyframe(chunk, self.video_track):
+                    self.gop = [chunk]
+                elif self.gop:
+                    self.gop.append(chunk)
+                for q in list(self.clients):
+                    try:
+                        q.put_nowait(chunk)
+                    except queue.Full:  # too slow: drop it, its page reconnects (never block: we hold the lock)
+                        self.clients.remove(q)
+                        _end(q)
+
+    def finish(self, reason: str) -> None:
+        with self._lock:
+            self.ended = reason
+            for q in self.clients:
+                _end(q)
+            self.clients.clear()
+
+    def subscribe(self) -> tuple[bytes | None, list[bytes], queue.Queue]:
+        q: queue.Queue = queue.Queue(CLIENT_QUEUE)
+        with self._lock:
+            self.clients.append(q)
+            return self.init, list(self.gop), q
+
+    def unsubscribe(self, q: queue.Queue) -> None:
+        with self._lock:
+            if q in self.clients:
+                self.clients.remove(q)
+
+    def status(self) -> dict:
+        with self._lock:
+            init = self.init
+            out = {"ready": init is not None, "ended": self.ended, "viewers": len(self.clients),
+                   "fragments": self.frames, "bytes": self.bytes, "seconds": round(time.time() - self.started, 1)}
+        if init:
+            out["codec"] = codec_string(init)
+            out["audio"] = b"mp4a" in init
+            size = video_size(init)
+            if size:
+                out["width"], out["height"] = size
+        return out
+
+
+def player_html() -> bytes:
+    from .live_player import PLAYER_HTML
+
+    return PLAYER_HTML.encode("utf-8")
+
+
+class _Handler(BaseHTTPRequestHandler):
+    server: _Server
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, fmt, *args):  # quiet
+        pass
+
+    def _send(self, code: int, body: bytes, ctype: str) -> None:
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):  # noqa: N802
+        path = self.path.split("?", 1)[0]
+        live = self.server.live
+        if path in ("/", "/index.html"):
+            self._send(200, player_html(), "text/html; charset=utf-8")
+        elif path == "/status":
+            self._send(200, json.dumps(live.relay.status()).encode(), "application/json")
+        elif path == "/stream.mp4":
+            self._stream(live.relay)
+        else:
+            self._send(404, b"not found", "text/plain")
+
+    def _stream(self, relay: Relay) -> None:
+        if relay.ended:
+            self._send(503, relay.ended.encode(), "text/plain")
+            return
+        init, gop, q = relay.subscribe()
+        try:
+            deadline = time.time() + 30
+            while init is None:  # the source hasn't sent its init segment yet
+                if relay.ended or time.time() > deadline:
+                    self._send(503, (relay.ended or "no picture yet").encode(), "text/plain")
+                    return
+                time.sleep(0.1)
+                relay.unsubscribe(q)
+                init, gop, q = relay.subscribe()
+            self.send_response(200)
+            self.send_header("Content-Type", "video/mp4")
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("Transfer-Encoding", "chunked")
+            self.end_headers()
+            self._chunk(init)
+            for f in gop:
+                self._chunk(f)
+            while True:
+                try:
+                    f = q.get(timeout=5)
+                except queue.Empty:
+                    if relay.ended:
+                        break
+                    continue
+                if f is None:
+                    break
+                self._chunk(f)
+            self.wfile.write(b"0\r\n\r\n")
+        except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError, OSError):
+            pass
+        finally:
+            relay.unsubscribe(q)
+
+    def _chunk(self, data: bytes) -> None:
+        self.wfile.write(f"{len(data):x}\r\n".encode() + data + b"\r\n")
+        self.wfile.flush()
+
+
+class _Server(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+    live: LiveStream
+
+
+# ------------------------------------------------------------------------------------------------ the Frame's side
+# SteamVR on the Frame runs `steamvr-v4l2cam.service` (Valve's v4l2cam): it copies the compositor's "headset view"
+# (what the wearer sees: games, SteamVR home, Steam's panels) into a v4l2loopback webcam named "SteamVR"
+# (/dev/video99, 1920x1080 RGB24, frames at the display rate). It costs nothing until someone reads it. Steam's own
+# recording/Remote Play capture gamescope instead (only the flat Steam UI in VR) and encode with x264 as well; the
+# Frame's Qualcomm encoder (qcom-iris) doesn't work with the stock ffmpeg/GStreamer. So: read the headset view, drop
+# to 30 fps before scaling, x264 at low priority, fragmented MP4 on stdout. Black while the headset sleeps.
+DEVICE_NAME = "SteamVR"
+# The headset view's size comes from SteamVR (1920x1080 on SteamOS 0.3.0; v4l2cam follows it, it has no size option),
+# so qualities are heights the picture is scaled *down* to (never up: a 2K/4K setting would only add bytes); "full"
+# sends it at its own size, whatever SteamVR makes it.
+QUALITY = {  # max height (None = the headset view's own), bitrate
+    "360p": (360, "1M"),
+    "480p": (480, "1500k"),
+    "720p": (720, "3M"),
+    "1080p": (1080, "6M"),
+    "full": (None, "10M"),
+}
+DEFAULT_QUALITY = "720p"
+FPS = 30
+# Clocks: pulse stamps audio with the wall clock, v4l2 with CLOCK_MONOTONIC → `-ts mono2abs` puts the picture on the
+# wall clock too. (Forcing -use_wallclock_as_timestamps on the pulse input gave bursts of AAC packets one shared time,
+# a broken audio timeline.) aresample=async=1 keeps the sound continuous across hiccups.
+AUDIO_BITRATE = "128k"  # AAC of the Frame's default output's monitor = what the headset plays (Lepton/Proton games)
+ENCODER_THREADS = 3  # leaves the game most of the CPU
+
+
+def source_command(quality: str = DEFAULT_QUALITY, fps: int = FPS) -> str:
+    """Shell script for the Frame: finds the headset-view device, streams fMP4 (H.264, + AAC sound of the
+    default output when there is one) to stdout and stops when the SSH channel closes (stdin reaches EOF).
+    Exit 3 = no headset view device (SteamVR not running)."""
+    h, rate = QUALITY.get(quality, QUALITY[DEFAULT_QUALITY])
+    # width -2 keeps the aspect ratio (even, as yuv420p needs); full size only drops an odd last row/column
+    scale = (",crop=trunc(iw/2)*2:trunc(ih/2)*2" if h is None
+             else f",scale=-2:'min({h},ih)':flags=fast_bilinear")
+    return f"""dev=
+for d in /sys/class/video4linux/video*; do
+  [ "$(cat "$d/name" 2>/dev/null)" = "{DEVICE_NAME}" ] && dev=/dev/${{d##*/}} && break
+done
+if [ -z "$dev" ]; then echo "no SteamVR headset view device: is SteamVR running?" >&2; exit 3; fi
+exec 3<&0
+export XDG_RUNTIME_DIR=${{XDG_RUNTIME_DIR:-/run/user/$(id -u)}}  # (an SSH session may lack it: PipeWire's socket)
+audio=(-an)
+sink=$(pactl get-default-sink 2>/dev/null)
+if [ -n "$sink" ]; then
+  audio=(-thread_queue_size 1024 -f pulse -fragment_size 3840 -i "$sink.monitor"
+         -map 0:v -map 1:a -af aresample=async=1 -c:a aac -b:a {AUDIO_BITRATE} -ac 2 -ar 48000)
+fi
+nice -n 10 ffmpeg -nostdin -hide_banner -loglevel error \\
+  -thread_queue_size 64 -ts mono2abs -f v4l2 -input_format rgb24 -i "$dev" "${{audio[@]}}" \\
+  -vf "fps={fps}{scale},format=yuv420p" -c:v libx264 -preset ultrafast -tune zerolatency -threads {ENCODER_THREADS} \\
+  -g {fps} -b:v {rate} -maxrate {rate} -bufsize {rate} \\
+  -f mp4 -movflags empty_moov+default_base_moof -frag_duration 100000 - &
+pid=$!
+( cat <&3 >/dev/null; kill $pid 2>/dev/null ) >/dev/null 2>&1 &  # (a background job's own stdin is /dev/null)
+wait $pid
+"""
+
+
+class FrameSource:
+    """The stdout of `source_command` on the Frame, on its own SSH channel of the existing connection."""
+
+    def __init__(self, frame, quality: str):
+        self.frame = frame
+        self.quality = quality
+        self.chan = None
+
+    def open(self):
+        transport = self.frame.client.get_transport()
+        if transport is None or not transport.is_active():
+            raise ConnectionError("not connected to the Frame")
+        self.chan = transport.open_session()
+        from ..frame.connection import sh_quote
+
+        self.chan.exec_command("bash -c " + sh_quote(source_command(self.quality)))
+        return self
+
+    def read(self, n: int) -> bytes:
+        data = self.chan.recv(n)
+        if not data:
+            err = b""
+            while self.chan.recv_stderr_ready():
+                err += self.chan.recv_stderr(4096)
+            if err.strip():
+                raise RuntimeError(err.decode("utf-8", "replace").strip().splitlines()[-1])
+        return data
+
+    def close(self) -> None:
+        if self.chan is not None:
+            try:
+                self.chan.shutdown_write()  # EOF on the script's stdin: it stops ffmpeg
+            finally:
+                self.chan.close()
+
+
+def start(frame, quality: str = DEFAULT_QUALITY) -> LiveStream:
+    """Start streaming the Frame's headset view; open `.url` in a browser to watch."""
+    src = FrameSource(frame, quality)
+    return LiveStream(src.open, src.close).start()
+
+
+class LiveStream:
+    """One live view: the source command on the Frame + the local relay server.
+
+    `open_source()` returns a file-like object with `read(n)`; it's the stdout of a command on the Frame (or, in tests,
+    a local process). `stop()` ends both.
+    """
+
+    def __init__(self, open_source, close_source=None, host: str = "127.0.0.1", port: int = 0):
+        self._open_source = open_source
+        self._close_source = close_source
+        self.relay = Relay()
+        self.server = _Server((host, port), _Handler)
+        self.server.live = self
+        self._threads: list[threading.Thread] = []
+        self._stop = threading.Event()
+        self.on_end = None  # callback(reason) when the source stops by itself
+
+    @property
+    def url(self) -> str:
+        host, port = self.server.server_address[:2]
+        return f"http://{host}:{port}/"
+
+    def start(self) -> LiveStream:
+        t1 = threading.Thread(target=self.server.serve_forever, name="live-http", daemon=True)
+        t2 = threading.Thread(target=self._pump, name="live-source", daemon=True)
+        self._threads = [t1, t2]
+        t1.start()
+        t2.start()
+        return self
+
+    def _pump(self) -> None:
+        reason = "stopped"
+        try:
+            src = self._open_source()
+            while not self._stop.is_set():
+                data = src.read(65536)
+                if not data:
+                    reason = "the Frame stopped sending a picture"
+                    break
+                self.relay.feed(data)
+        except Exception as exc:  # noqa: BLE001
+            from ..errors import explain
+
+            reason = explain(exc)
+        if self._stop.is_set():
+            reason = "stopped"
+        self.relay.finish(reason)
+        if not self._stop.is_set() and self.on_end:
+            self.on_end(reason)
+
+    @property
+    def running(self) -> bool:
+        return not self._stop.is_set() and self.relay.ended is None
+
+    def stop(self) -> None:
+        if self._stop.is_set():
+            return
+        self._stop.set()
+        if self._close_source:
+            try:
+                self._close_source()
+            except Exception:  # noqa: BLE001
+                pass
+        self.relay.finish("stopped")
+        self.server.shutdown()
+        self.server.server_close()
@@ -0,0 +1,151 @@
+"""Steam screenshots taken on the Frame (the GUI's Screenshots tab).
+
+Steam keeps them per account in userdata/<id>/760/remote/<appid>/screenshots/ (+ thumbnails/). The Frame files every
+headset screenshot under SteamVR (250820), so the agent (`list_screenshots`) matches them to FramePort games by time:
+launch.sh logs each play session to <anchor>/plays.log. Thumbnails and opened images are cached on this PC in
+<user data>/screenshots-cache/<frame>/ and shown by asset URL (never image bytes in controls).
+"""
+from __future__ import annotations
+
+import hashlib
+import posixpath
+import re
+import threading
+from pathlib import Path
+
+from ..core.events import Reporter
+from ..core.paths import user_data_dir
+from . import installer
+
+THUMB_WIDTH = 480
+_locks: dict[str, threading.Lock] = {}
+_guard = threading.Lock()
+
+
+def list_shots(frame, package: str | None = None, offset: int = 0, limit: int = 0) -> dict:
+    """{shots, total, games} from the agent, newest first. package: a game ("" = shots of no FramePort game)."""
+    args = {"offset": offset, "limit": limit}
+    if package is not None:
+        args["package"] = package
+    return frame.agent("list_screenshots", **args)
+
+
+def frame_id(frame) -> str:
+    target = getattr(frame, "target", None)
+    raw = (getattr(target, "name", "") or getattr(target, "host", "") or "frame") if target else "frame"
+    return re.sub(r"[^A-Za-z0-9._-]+", "_", raw).strip("._") or "frame"
+
+
+def cache_dir(frame) -> Path:
+    d = user_data_dir() / "screenshots-cache" / frame_id(frame)
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _key(shot: dict) -> str:
+    return hashlib.sha1(f"{shot['path']}:{shot.get('size')}".encode()).hexdigest()[:16]
+
+
+def _lock(key: str) -> threading.Lock:
+    with _guard:
+        return _locks.setdefault(key, threading.Lock())
+
+
+def _fetch(frame, remote: str, dest: Path) -> Path:
+    with _lock(str(dest)):
+        if not dest.exists():
+            tmp = dest.with_suffix(dest.suffix + ".part")
+            frame.sftp.get(remote, str(tmp))
+            tmp.replace(dest)
+    return dest
+
+
+def cached(frame, shot: dict, kind: str = "thumb") -> Path | None:
+    """The cached thumbnail/full image if it was already downloaded (no network: for render paths)."""
+    p = cache_dir(frame) / _cache_name(shot, kind)
+    return p if p.exists() else None
+
+
+def _cache_name(shot: dict, kind: str) -> str:
+    ext = posixpath.splitext(shot["path"])[1].lower() if kind == "full" else ".jpg"
+    return f"{kind}_{_key(shot)}{ext or '.jpg'}"
+
+
+def image_path(frame, shot: dict) -> Path:
+    """The full image, downloaded once into the cache (the viewer shows it from there)."""
+    return _fetch(frame, shot["path"], cache_dir(frame) / _cache_name(shot, "full"))
+
+
+def thumb_path(frame, shot: dict) -> Path:
+    """A small image for the grid: Steam's own thumbnail, downloaded once; without one, made from the full image."""
+    dest = cache_dir(frame) / _cache_name(shot, "thumb")
+    if dest.exists():
+        return dest
+    if shot.get("thumb"):
+        try:
+            return _fetch(frame, shot["thumb"], dest)
+        except OSError:
+            pass  # thumbnail gone: make one
+    full = image_path(frame, shot)
+    with _lock(str(dest)):
+        if not dest.exists():
+            try:
+                from PIL import Image
+
+                with Image.open(full) as im:
+                    im.thumbnail((THUMB_WIDTH, THUMB_WIDTH))
+                    tmp = dest.with_suffix(".jpg.part")
+                    im.convert("RGB").save(tmp, "JPEG", quality=85)
+                    tmp.replace(dest)
+            except Exception:  # noqa: BLE001  (unreadable image: show the original)
+                return full
+    return dest
+
+
+def safe_name(text: str) -> str:
+    return re.sub(r'[<>:"/\\|?*\x00-\x1f]+', "_", text or "").strip(" .") or "Screenshots"
+
+
+def download(frame, shots: list[dict], dest_dir: Path, reporter: Reporter | None = None) -> dict:
+    """Copy the full images into dest_dir/<game title>/ (files already there with the same size are skipped).
+    Interruptible (Cancel)."""
+    reporter = reporter or Reporter()
+    dest_dir = Path(dest_dir)
+    items = []
+    for s in shots:
+        dest = dest_dir / safe_name(s.get("title") or "") / posixpath.basename(s["path"])
+        if dest.exists() and dest.stat().st_size == s.get("size"):
+            continue
+        items.append((s, dest))
+    total = sum(s.get("size") or 0 for s, _ in items)
+    skipped = len(shots) - len(items)
+    reporter.log(f"{len(items)} screenshot(s), {total / 2**20:.1f} MiB → {dest_dir}"
+                 + (f" ({skipped} already there)" if skipped else ""))
+    done = 0
+    if items:
+        with installer.transfer_link(frame, reporter, total) as xfer:
+            reporter.stage(f"Download {len(items)} screenshot(s)")
+            for s, dest in items:
+                reporter.check_cancel()
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                tmp = dest.with_name(dest.name + ".part")
+
+                def progress(got, _total, base=done, name=dest.name):
+                    reporter.check_cancel()
+                    reporter.progress((base + got) / max(total, 1), name)
+                xfer.sftp.get(s["path"], str(tmp), callback=progress)
+                tmp.replace(dest)
+                done += s.get("size") or 0
+    return {"files": len(items), "skipped": skipped, "bytes": total, "folder": str(dest_dir)}
+
+
+def delete(frame, shots: list[dict]) -> int:
+    """Delete screenshots on the Frame (the agent only deletes images in Steam's screenshot folders) and their cached
+    copies here. Steam's own screenshot list may still show them until Steam restarts."""
+    if not shots:
+        return 0
+    r = frame.agent("delete_screenshots", paths=[s["path"] for s in shots])
+    for s in shots:
+        for kind in ("thumb", "full"):
+            (cache_dir(frame) / _cache_name(s, kind)).unlink(missing_ok=True)
+    return len(r.get("deleted") or [])
@@ -38,6 +38,7 @@
 "108 Hz": "",
 "120 Hz": "",
 "144 Hz": "",
+ "360p (lightest)": "",
 "360° (equirect) layers, e.g. a video player's virtual theatre or 360° videos (e.g. 4XVR), which the Frame's runtime lacks, are drawn by a background thread into a layer behind the game's own picture: the 360° image is converted only when it changes (a theatre once, a 360° video once per video frame) and the view is drawn for each frame's head pose. GLES games only; without it these layers are missing (black).": "",
 "360° 3D": "",
 "360° detail": "",
@@ -46,14 +47,20 @@
 "360° sharpness": "",
 "360° video frame rate limit": "",
 "72 Hz": "",
+ "720p (recommended)": "",
 "80 Hz": "",
 "90 Hz": "",
+ "920 × 430": "",
 "96 Hz": "",
 "A folder with Android games (APK + OBB, e.g. Quest games) or PC VR games.": "",
+ "A game is running on the Frame": "",
 "A game is running on the Frame. Close it in the headset first, then try again.": "",
 "a known blocker": "",
+ "A Linux app for arm64 (AppImage, .zip or .tar.gz)": "",
 "A Meta Quest game (APK). It's rebuilt for the Frame and runs in Lepton, Valve's Android container.": "",
+ "A native Linux program built for arm64 (aarch64), like the Frame's own CPU. It's installed unchanged and runs directly on SteamOS (no Android container, no Proton), started from the Frame's Steam library. VR apps use the Frame's OpenXR runtime.": "",
 "A new FramePort version is ready to install": "",
+ "A newer known-good config for this game is available (you changed this game's settings, so it wasn't applied by itself).": "",
 "A recipe is the list of patches FramePort applies to a game before installing it. Known-good recipes were tested on a Frame; the others are suggested from the game's engine and VR API. Hover a patch for why it's there.": "",
 "A VR app made for another Android headset. OpenXR apps are translated like Quest games; apps built on a headset maker's own SDK (Pico, HTC Wave) can't run on the Frame.": "",
 "A Windows game without VR, added with \"Add one game folder…\". On the Frame, Proton runs it as a window (like Steam's own Windows games); it's in the Frame's Steam library.": "",
@@ -65,6 +72,8 @@
 "AC Nexus: no AppSW at 72 Hz": "",
 "AC Nexus: no AppSW at 90 Hz": "",
 "Activity": "",
+ "Add a Linux app (arm64)…": "",
+ "Add a Linux app folder…": "",
 "Add a tag": "",
 "Add an APK file": "",
 "Add an APK file…": "",
@@ -75,12 +84,15 @@
 "Add videos": "",
 "Add videos and files…": "",
 "Add your games": "",
+ "Add {name}": "",
 "Added automatically (engine, VR API or store genre)": "",
 "Added automatically when needed": "",
 "Added {n} game": [
  "",
  ""
 ],
+ "Added {title}": "",
+ "Added {title}: it starts with {exe}. Not the right program? Change it on its page.": "",
 "Adds a launcher entry point (Lepton additionally needs category LAUNCHER, see the Frame 'launcher' fix).": "",
 "Adds a real ovrMessageType_ToString (OVRPort's platform compat library) for games whose platform loader lacks it (e.g. The Climb 2). OVRPort 1.2.5+ adds the same library itself; then this is skipped.": "",
 "Adds a small piece of Meta's platform library that some games need to start.": "",
@@ -91,6 +103,7 @@
 "Advanced": "",
 "All": "",
 "All at their defaults": "",
+ "All games": "",
 "All of FramePort's data on this PC is gone": "",
 "Allow swapchains larger than 4096 px": "",
 "Allows data backup.": "",
@@ -103,6 +116,8 @@
 "Also delete this game's files on this PC ({size})": "",
 "Also in your library: {value} version": "",
 "Also remove FramePort's games and files from the Frame": "",
+ "An AppImage is a Linux app packed into one file. FramePort unpacks it on the Frame once, so it starts without FUSE.": "",
+ "An AppImage, a folder or a .zip/.tar archive with a Linux program built for arm64 (aarch64). x86_64 builds can't run on the Frame. The app must bring the libraries SteamOS doesn't have.": "",
 "An ordinary Android app or game (no VR). It's installed unchanged and runs in Lepton, Valve's Android container.": "",
 "Analyze again": "",
 "Analyze {title} again": "",
@@ -114,6 +129,7 @@
 "Any": "",
 "APK": "",
 "Appearance": "",
+ "AppImage": "",
 "Apply the suggested patches and reinstall": "",
 "Apps that suggest controller bindings only for Meta's newer profiles (Touch Plus, Touch Pro), which the Frame's runtime rejects (XR_ERROR_PATH_UNSUPPORTED), get the same bindings as oculus/touch_controller instead (components Touch lacks are dropped). Without it such apps get no controller input.": "",
 "Artwork for {get}": "",
@@ -123,6 +139,7 @@
 "Artwork: {value}": "",
 "As the game sends it": "",
 "Asked Steam to install Lepton": "",
+ "Asked to test a fix? Dev builds come before the next release.": "",
 "Assassin's Creed Nexus (build 207706 only): turns off application space warp and runs at 72 Hz.": "",
 "Assassin's Creed Nexus (build 207706 only): turns off application space warp and runs at 90 Hz.": "",
 "Assassin's Creed Nexus: smoother picture at 72 Hz (turns off Meta's frame-rate trick).": "",
@@ -132,10 +149,14 @@
 "Automatic SteamVR performance settings (this PC)": "",
 "Back to library": "",
 "Back up the signing keys ({len}) to {shown_dir} first": "",
+ "Banner": "",
+ "Before a swapchain image is handed to the Frame, wait until the game's GPU work on it has finished, for games that hand over images early (an eye flickers or jitters). Costs some frame time. 2 = only after the first 60 s (compare both in one session).": "",
 "Before each Play on this PC, FramePort reads SteamVR's record of the game's last session (frames dropped; frame times from fpsVR if installed). If it dropped frames, it lowers the game's refresh rate to one whose frame budget fits (e.g. 96 → 90 Hz) and turns motion smoothing on, through SteamVR's per-application settings; each later session can step down again. Set a refresh rate or smoothing mode here to choose yourself. Ignored on the Frame.": "",
 "Best guess": "",
 "Blit quads flagged XrCompositionLayerImageLayoutFB VERTICAL_FLIP upside down (Vulkan). Fixes UI panels and text that show upside down (e.g. Assassin's Creed Nexus).": "",
 "Browse and manage files on the Frame (Files tab): upload from this PC, download, rename, delete. Videos, Downloads and Documents are shared by every Quest game (/sdcard/Movies, /sdcard/Download, /sdcard/Documents); each installed game also has its own storage (its /sdcard). Apps find files by browsing folders. Video players that list only their own folder (e.g. 4XVR's Internal Storage = 4XPlayer): upload into that folder in the game's storage.": "",
+ "Build page": "",
+ "Cable connected.": "",
 "Can't reach your Frame. Make sure it's on, awake and on the same network, then try again.": "",
 "Can't run": "",
 "Cancel": "",
@@ -146,28 +167,35 @@
 "Ceiling height for scene_emul.": "",
 "Ceiling height of the pretend room.": "",
 "Change executable…": "",
+ "Change program…": "",
 "Change settings…": "",
 "Changes apply the next time FramePort starts.": "",
 "Changes apply to the next install. Hover a chip above for why it was suggested.": "",
 "Changes are used the next time the game starts. Not sure? Leave a setting as it is.": "",
+ "Change…": "",
 "Check": "",
 "Check exe": "",
 "Check for new versions automatically": "",
 "Check for updates": "",
 "Check game files": "",
+ "Check now": "",
 "Check that the Frame and this computer are on the same network.": "",
 "Checking this PC…": "",
 "Checking tools…": "",
- "Chooses which Proton version runs the game on the Frame.": "",
+ "Choose PNG, JPEG or WebP images. Steam fills any missing shape from the ones you choose; FramePort never replaces your images automatically.": "",
+ "Choose…": "",
+ "Chosen by you.": "",
+ "Clamp image rects": "",
 "Clean up Frida leftovers in smali": "",
 "Cleans up graphics data that crashes some Unreal games on the Frame.": "",
 "Clear": "",
 "Clear android:debuggable": "",
 "Clear finished": "",
 "Clear search": "",
+ "Clear selection": "",
 "Clear tags": "",
 "Click here, then type. Everything you type goes to the Frame (Esc and shortcuts too).": "",
- "Click to open · right-click for quick actions": "",
+ "Click to open · right-click for quick actions · drag across cards to select several": "",
 "Close": "",
 "Close FramePort": "",
 "Collect and open GitHub": "",
@@ -176,6 +204,7 @@
 "Collect logs: {title}": "",
 "Command-line arguments for the game program. Games that support several VR runtimes pick one with an argument, e.g. Unreal's -hmd=OpenXR or -hmd=SteamVR, Unity's -vrmode OpenVR, or a game's own switch (-Runtime=OpenXRHMD). FramePort fills them in from the game files (the repack's VD.bat with the Oculus module swapped for OpenXR, else the engine's usual switch).": "",
 "Connect": "",
+ "Connect the Frame's USB-C port to this computer with a USB cable (a data cable, not a charge-only one).": "",
 "Connect your Frame": "",
 "Connect your Frame first": "",
 "Connect your Steam Frame": "",
@@ -193,18 +222,23 @@
 "Copy": "",
 "Copy all": "",
 "Copy failed; select the text instead": "",
+ "Copy folder path": "",
 "Copy log": "",
 "Copy OVRPlugin if VrApi is present": "",
 "Copy OVRPort libraries": "",
 "Copy path": "",
 "Couldn't check this PC": "",
 "Couldn't connect: {exc}": "",
+ "Couldn't list the screenshots: {exc}": "",
 "Couldn't list {path}: {exc}": "",
+ "couldn't load the full image: {exc}": "",
 "Couldn't open the game's storage: {exc}": "",
 "Couldn't read the file list: {exc}": "",
 "Couldn't read the Frame's folders: {exc}": "",
 "Couldn't read {path}: {exc}": "",
+ "Couldn't start the live view: {exc}": "",
 "Couldn't use {choice}: {exc}": "",
+ "Cover": "",
 "Create": "",
 "Customize": "",
 "Cylinder layers (curved menus and movie screens, e.g. 4XVR), which the Frame's runtime lacks, are shown as a few flat strips along the curve. 0 = drop them. 360° (equirect) layers can't be shown on the Frame.": "",
@@ -216,9 +250,23 @@
 "Declares Meta's permissions some mixed-reality games ask for, so they don't stop.": "",
 "Delete": "",
 "Delete {names}?": "",
+ "Delete {n} items…": "",
+ "Delete {n} screenshot?": [
+  "",
+  ""
+ ],
+ "Delete {n} screenshots…": "",
+ "Deleted {n} screenshot": [
+  "",
+  ""
+ ],
 "Deletes the rollback copies kept from each game's previous install and leftover uploads. The games and saves stay.": "",
+ "Delete…": "",
+ "Deselect": "",
 "Details": "",
+ "Dev builds let you test fixes before they're released. They're less tested than releases and may have bugs. You get the next release as a normal update (you have {version}).": "",
 "Developer Mode (on the Frame: Settings → System → Developer) lets FramePort find the Frame on your network and connect to it over SSH. The first-time setup command turns it on for you.": "",
+ "Diagnostics: the Vulkan shim (frame.vk_sanitize) adds Khronos' validation layer to the game's instance; its findings go to launch.log. The layer library (libVkLayer_khronos_validation.so) must be in the APK.": "",
 "Didn't finish ({value}): {error}": "",
 "Disable application space warp if used": "",
 "Disable controller tracking offset": "",
@@ -229,19 +277,36 @@
 "Don't pause on short interruptions": "",
 "done": "",
 "Done": "",
+ "Done: look for the cable": "",
 "Download": "",
+ "Download all": "",
+ "Download all ({n})…": "",
+ "Download selected": "",
 "Download to this PC": "",
+ "Download to this PC…": "",
 "Download to which folder on this PC?": "",
 "Download {name}": "",
+ "Download {n} items to this PC…": "",
+ "Download {n} screenshot": [
+  "",
+  ""
+ ],
+ "Download {n} screenshots…": "",
 "Downloaded when first needed": "",
 "Downloaded {n} file to {folder}": [
  "",
  ""
 ],
+ "Downloaded {n} screenshot to {folder}": [
+  "",
+  ""
+ ],
 "Downloading…": "",
 "Downloads": "",
+ "Download…": "",
 "Draws each eye separately; try it when one eye shows a grey or broken picture.": "",
 "Drop invalid layers": "",
+ "Drop layer color fades": "",
 "Drop layers whose swapchain failed or whose extension isn't enabled.": "",
 "Drop to upload": "",
 "Drops Quest-only shared library requirements.": "",
@@ -253,6 +318,7 @@
 "Environment variables for the Proton launcher on the Frame (e.g. DXVK_HUD=fps), one KEY=value per line.": "",
 "Every 'local' play space the game creates lines up with the one at the start. For games whose menus or screens jump to where you look on the Frame.": "",
 "Every game start on the Frame used to leak one kernel key, and after about 200 launches every game fails to start. FramePort switches that leak off, but keys already used only come back after a restart of the Frame.": "",
+ "Every N seconds, saves the left-eye image the game submits (a quarter of its size) as fb_snap_0-7.ppm in the game's files folder on the Frame. Launch tests run without anyone wearing the headset, so the headset view stays black; this shows what the game itself draws. OpenGL ES games only.": "",
 "Every uploaded file is present with the right size.": "",
 "everything in ~ (not seen by games)": "",
 "Everything is up to date": "",
@@ -264,6 +330,7 @@
 "Extra Lepton environment": "",
 "Extra settings for Proton (for testing).": "",
 "Extra settings for the Android container (for testing).": "",
+ "Eye-image snapshots (diagnostics)": "",
 "failed": "",
 "Failed": "",
 "Failed: {error}": "",
@@ -280,26 +347,36 @@
 "Find automatically": "",
 "firewalld is active. Allow the setup port until the next restart with: sudo firewall-cmd --add-port={port}/tcp": "",
 "First-time setup": "",
+ "Fix depth flicker (Unreal Vulkan)": "",
+ "Fix freezes when controllers vibrate": "",
 "Fix launcher icon entry": "",
 "Fix minimal Android SDK": "",
 "Fix UE4 crash with Unity stub": "",
 "Fix upside-down menus": "",
 "Fixes graphics code that the Frame's drivers reject (black screen with sound).": "",
+ "Fixes the black picture in Minecraft launchers (e.g. QuestCraft): uses depth formats the Frame's graphics driver accepts.": "",
 "Flat": "",
 "focus_hold hides focus dips up to this long (100-5000). Longer for a headset whose wear sensor flickers (\"HMD off\" for 0.5-2 s while worn, e.g. Blade & Sorcery pausing); taking the headset off or the system menu pauses the game only after this long.": "",
 "Folder": "",
 "folder and everything in it": "",
 "Folder name": "",
 "Folder to upload to the Frame": "",
+ "Folder with a Linux app for arm64": "",
 "Folder with VR games (Android APKs or PC VR games)": "",
 "For apps that only know Quest 3/Pro controllers: without it they get no buttons.": "",
 "For games that crash right after you return to them (e.g. after the Steam menu).": "",
+ "For games that freeze the Frame when a controller vibrates (e.g. Lucky's Tale). Needs a rebuild.": "",
+ "For games that judder or shimmer while you hold your head still (e.g. I Am Cat).": "",
 "For games that pause or recenter when the headset briefly loses focus.": "",
 "For games that show the headset's own controllers. Takes effect after a reinstall.": "",
 "For games whose menus or screens jump to wherever you look.": "",
 "For heavy games that use application space warp: it causes artifacts or hangs on non-Quest runtimes (e.g. Asgard's Wrath 2, Batman: Arkham Shadow).": "",
 "For mixed-reality-only games. On the Frame, passthrough is emulated by the FrameBridge adapter (greyscale cameras).": "",
+ "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.": "",
+ "For troubleshooting: records the game's requests to Meta's platform services and which ones never get an answer.": "",
 "For Unreal games that close themselves right after starting (e.g. Phantom: Covert Ops). Also disables the in-game Quit.": "",
+ "For Unreal games whose models flicker or show through walls and windows on the Frame (e.g. Into The Radius 2). Needs a rebuild.": "",
+ "For Vulkan games whose models flicker or vanish while you look at them (e.g. Into The Radius 2). Needs a rebuild.": "",
 "Force enable passthrough": "",
 "Found": "",
 "Frame agent": "",
@@ -310,6 +387,7 @@
 "FramePort": "",
 "FramePort can't replace itself in {value} (no permission): opening the release page to download it": "",
 "FramePort checks GitHub for a new release every few hours and shows it in the sidebar and the Library. \"Update now\" downloads it, checks its checksum (and on Windows its signature), closes FramePort and opens the new version; your games, settings and Frame connection are kept. With automatic install, the download happens in the background and the new version starts next time.": "",
+ "FramePort found more than one arm64 program in this app. Pick the one that starts it (helpers such as crash reporters or updaters are the wrong choice).": "",
 "FramePort found more than one program that could start this game. Pick the one you'd double-click to play it. Oculus builds usually work better with Revive than Steam builds.": "",
 "FramePort has Steam on the Frame download Proton and the runtime it needs (about 1 GiB). Steam restarts once, which closes a running game.": "",
 "FramePort installs games on the Frame over your network": "",
@@ -318,6 +396,7 @@
 "FramePort picked {value} to start this game, but there are other candidates. Check it before installing.": "",
 "FramePort runs in WSL with its default NAT network, which other devices can't reach. Set networkingMode=mirrored under [wsl2] in %UserProfile%\\.wslconfig, run wsl --shutdown and start FramePort again.": "",
 "FramePort saves a diagnostics zip (logs, recipe, device info; no game files, personal data removed) and opens a prefilled GitHub issue. Drag the zip into it, check the text, submit.": "",
+ "FramePort then finds the Frame on the cable by itself.": "",
 "FramePort updates and restarts after the current job": "",
 "FramePort was removed": "",
 "FramePort {version} is available": "",
@@ -337,9 +416,13 @@
 "Freed {value:.1f} GiB on the Frame": "",
 "From the tested recipe for this game": "",
 "From the {src}": "",
+ "Full (headset view size)": "",
 "Full launch log": "",
+ "Game": "",
 "Game arguments (select SteamVR / OpenXR)": "",
 "Game config files": "",
+ "Game configs are up to date": "",
+ "Game configs from GitHub: last checked {when}": "",
 "Game launch capacity": "",
 "Game not found": "",
 "Game settings": "",
@@ -358,9 +441,14 @@
 "GiB": "",
 "Gives older Quest games a newer version of Meta's VR plugin that can be converted.": "",
 "GL shim (Mesa GLSL compatibility)": "",
+ "GL shim for Unity (no multisampled render-to-texture)": "",
+ "GL shim only: hide GL_EXT_multisampled_render_to_texture(2) (Zink crashes rendering Unity's runtime MSAA eye buffer through it, e.g. The Room VR).": "",
 "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).": "",
+ "GL shim: hide multisampled render-to-texture": "",
 "GL shim: hide multiview": "",
+ "GL wrapper: OpenGL ES depth formats (Minecraft)": "",
 "Go to my library": "",
+ "Go to System and turn on \"Enable Developer Mode\". A Developer page appears in Settings; nothing else changes, your games and data stay as they are.": "",
 "Graphics": "",
 "Hide Android's navigation bar": "",
 "Hide log": "",
@@ -368,7 +456,8 @@
 "Hide Quest foveation": "",
 "Hides Android's back/home/recents buttons, which cover the app's own buttons.": "",
 "Hides Quest foveation extensions the Frame runtime lacks.": "",
- "Hides the Frame's brief focus dips (up to a second) once the game has been focused for a second. For games that recentre or pause every time focus returns.": "",
+ "Hides the Frame's brief focus dips (up to focus_hold_ms) once the game has been focused for a second. On by default: the Frame's wear sensor flickers \"HMD off\" for 0.5-2 s while worn, and many games pause or recentre every time (e.g. Blade & Sorcery, Lucky's Tale).": "",
+ "Hides XR_FB_space_warp, so the game renders every frame itself instead of half of them plus motion vectors (Application SpaceWarp). For games whose picture flickers or smears on the Frame (e.g. Unreal Engine 5 games such as Into The Radius 2).": "",
 "High": "",
 "Higher is sharper but needs more power.": "",
 "Higher keeps more detail but uses more memory.": "",
@@ -378,14 +467,18 @@
 "How often the picture updates. Higher is smoother if the game can keep up.": "",
 "How well the game runs on the Steam Frame. \"Works\" and \"Works with issues\" come from recipes tested on a real Frame. \"Untested\" means FramePort suggested a recipe from the game's engine and VR API that nobody has confirmed yet. \"Can't run\" means there's a known blocker (for example a 32-bit-only game).": "",
 "I played it in the headset with this recipe": "",
+ "Icon": "",
 "If the pointer doesn't hit what you aim at, tilt it up or down.": "",
 "If Windows asked whether FramePort may use the network, allow it (Private networks).": "",
 "If you know the Frame's address.": "",
 "Ignore focus dips up to": "",
+ "Image for the {label}": "",
 "In your Steam library": "",
 "In your Steam library · launch settings changed — update it": "",
 "Install": "",
 "Install anyway": "",
+ "Install dev build": "",
+ "Install dev build {version}?": "",
 "Install it anyway to try it, e.g. with different patches.": "",
 "Install Lepton on the Frame": "",
 "Install missing": "",
@@ -395,6 +488,7 @@
 "Install Proton on the Frame?": "",
 "Install SteamVR from Steam to play PC VR games": "",
 "Install the alternate build (": "",
+ "Install the latest dev build…": "",
 "Install updates automatically (downloads in the background, installs when FramePort next starts)": "",
 "Install {len} on this PC": "",
 "Install {n} on Frame": "",
@@ -406,6 +500,8 @@
 "Installed · launch test failed": "",
 "Installed, but it didn't start properly: ": "",
 "Installing": "",
+ "Installs the app as it is, unpacked on the Frame, with an entry in its Steam library": "",
+ "Installs the app as it is, with an entry in the Frame's Steam library": "",
 "Installs the game exactly as it is: no patches (your copy is already patched)": "",
 "into {value}": "",
 "It can't be reached (asleep, turned off or out of Wi-Fi). Wake it or turn it on: FramePort continues by itself, and uploads pick up where they stopped.": "",
@@ -415,6 +511,8 @@
 "it stopped at '{value}'": "",
 "It trusts this app, turns on Developer Mode and installs Lepton if needed. Turning on Developer Mode closes the desktop; the setup finishes on its own and FramePort connects by itself. You only do this once.": "",
 "It was removed from the library.": "",
+ "It will be closed without saving. Continue?": "",
+ "It won't start on the Frame: SteamOS doesn't have these libraries and the app doesn't bring them. Look for a build of the app that includes them, then install that one.": "",
 "It works: share…": "",
 "Java runtime": "",
 "Java, OVRPort and apksigner are ready.": "",
@@ -423,12 +521,14 @@
 "Keep game saves on the Frame": "",
 "Keep menus in place": "",
 "Keeps a smoothing setting off that the game turns on itself and that can freeze the Frame.": "",
+ "Keeps every submitted image rect inside its swapchain. Unity can size the eye area a few pixels past the image on some Frames; SteamVR then rejects every frame (xrEndFrame -25, XR_ERROR_SWAPCHAIN_RECT_INVALID) and the game stops drawing (e.g. PowerWash Simulator stuck at \"Waiting\").": "",
 "Keeps one label so the title is stable.": "",
 "Keeps one name for the game, so it shows the same everywhere.": "",
 "Keyboard connected to {label}.": "",
 "Keyboard disconnected: {error}": "",
 "KiB": "",
 "Language": "",
+ "Language packs from the game's files": "",
 "Last build": "",
 "Last launch test: {get} · furthest: {value}": "",
 "Later": "",
@@ -453,6 +553,7 @@
 "Lets mixed-reality games start even though they insist on a camera view of your room.": "",
 "Lets older Unity games start VR without Meta's system apps (they'd stay on a 2D screen).": "",
 "Lets SDL and LÖVE games start on the Frame (they'd crash looking for a clipboard).": "",
+ "Lets the game find language files (like de.lang) that are already in its data, instead of waiting for a download that never comes.": "",
 "Lets typing reach this app: Steam's on-screen keyboard or your computer's keyboard (VR is unaffected).": "",
 "Lets Unity games accept a headset that isn't a Quest.": "",
 "Lets Unreal games accept a headset that isn't a Quest.": "",
@@ -460,13 +561,22 @@
 "Lets you read logs/attach. Some Unreal games abort under CheckJNI when debuggable; the Frame 'nodebug' fix undoes it.": "",
 "Lets you type into this app's text fields on the Frame (they'd close at once).": "",
 "Library": "",
+ "Linux": "",
+ "Linux app (arm64)": "",
+ "Linux VR app · OpenXR": "",
+ "Live": "",
+ "Live view": "",
 "Loading…": "",
 "Loads FramePort's OpenXR layer under Proton on the Frame. The Frame's SteamVR runtime only accepts OpenXR 1.0 apps, but Proton's VR helper asks for 1.1, so without the layer VR never starts (the game shows as a flat window, or Revive fails with 'Unable to load LibOVRRT DLL'); the layer retries as 1.0. It also emulates xrConvertTimespecTimeToTimeKHR if a runtime refuses it. Ignored on this PC.": "",
 "Loads libglshim.so ahead of libEGL in every engine library that fetches GL through eglGetProcAddress. Fixes Quest-only leniency that Mesa/Zink rejects: #pragma before #extension, implicit int/float conversions (enables GL_EXT_shader_implicit_conversions), and multiview shaders used on single-view framebuffers (hides GL_OVR_multiview; gl_hide_multiview=0 turns that off). Logs every failed shader with its source lines (logcat tag GLShim). Symptom: black screen with working audio in a GLES game.": "",
+ "Loads the GL shim into a Unity GLES game and hides GL_EXT_multisampled_render_to_texture (and the multiview variant). Some Unity games switch their eye buffer to 4x MSAA at runtime; the Frame only gives single-sampled swapchains, Unity then renders through multisampled render-to-texture and Mesa/Zink crashes (SIGSEGV in libgallium_dri.so on the render thread: grey or frozen screen, e.g. The Room VR). Hidden, Unity uses an ordinary MSAA buffer and resolves it. Unity's multiview stays on (gl_hide_multiview defaults to 0 here).": "",
 "Locations": "",
+ "Logo": "",
 "Logs details for debugging: composition layers and swapchains, focus changes, play-space creation, pointer vs grip poses, refresh rates. No effect on the game.": "",
+ "Logs every Meta Platform SDK request the game makes (user, entitlement, cloud saves, ...) and the messages that answer them, and every 10 s the requests that never got an answer (logcat tag fp_ovrtrace, in launch.log). For games that wait forever on a loading screen (e.g. Vader Immortal after its intro). Changes nothing: every call goes to the real function.": "",
 "Longer for headsets that briefly think they're off your head.": "",
 "Looking for Frames on your network…": "",
+ "Looking for the Frame on a USB cable (Developer Mode on, USB-C port connected to this computer).": "",
 "Looking for your Frame…": "",
 "Looking up the store description and screenshots…": "",
 "Low": "",
@@ -486,8 +596,10 @@
 "Menus and screens": "",
 "Meta Quest": "",
 "Meta XR Audio: skip Quest telemetry class": "",
- "Meta's OVRManager switches Unity to the headset's recommended MSAA level (4x) while the game runs, whatever its quality settings say (log: \"Switching to the recommended level\"). Multisampled render-to-texture on GLES can hang the Frame's GPU, up to a restart of the whole headset (e.g. Lucky's Tale in a menu). Rewrites OVRDisplay.recommendedMSAALevel -> 0 in libil2cpp.so (found with Cpp2IL), so MSAA stays off.": "",
+ "Meta's OVRManager switches Unity to the headset's recommended MSAA level (4x) while the game runs, whatever its quality settings say (log: \"Switching to the recommended level\"). Multisampled render-to-texture on GLES can hang the Frame's GPU, up to a restart of the whole headset (e.g. Lucky's Tale in a menu) or a crash of its GL driver (e.g. The Room VR, whose own code sets 4x). Rewrites OVRDisplay.recommendedMSAALevel -> 0 and makes QualitySettings.antiAliasing's setter do nothing in libil2cpp.so (found with Cpp2IL), so MSAA stays off.": "",
+ "Meta's OVROverlay copies a texture into its own compositor layer every frame. For some games (e.g. The Room VR's screen fade, a 4x4 overlay) that copy crashes the Frame's GL driver: SIGSEGV in libgallium_dri.so on Unity's render thread right after a tiny xrCreateSwapchain, grey or frozen screen. Rewrites OVROverlay.PopulateLayer -> false in libil2cpp.so (found with Cpp2IL): overlays are skipped (fades become instant cuts, overlay splash screens don't show). Only for games with this crash: menus drawn as overlays would disappear too.": "",
 "MiB": "",
+ "Minecraft asks for desktop OpenGL's GL_DEPTH_COMPONENT32 depth textures. Some builds of LTW, the OpenGL-to-OpenGL ES wrapper in Minecraft launchers such as QuestCraft, pass that on unchanged; Quest's driver accepts it, the Frame's Mesa rejects it (GL_INVALID_OPERATION in glTexImage2D), so the depth buffer never exists and the picture stays black. LTW then loads OpenGL ES through a small shim that asks for GL_DEPTH_COMPONENT32F (or 24-bit) instead.": "",
 "Mirrored": "",
 "Mixed reality": "",
 "Mixed-reality games that build their level from your room get a simple room with walls.": "",
@@ -502,30 +614,43 @@
 "Needs the Oculus Platform (Meta Horizon app) for its license check, which the Frame doesn't have — it crashes at startup there. Play it on this PC.": "",
 "Needs Windows (or WSL on Windows)": "",
 "Neutralises Meta XR Audio's Quest-only calls (Unity/Wwise).": "",
+ "never": "",
+ "New config applied: use Update on Frame to install it": "",
 "New folder": "",
+ "New folder…": "",
 "New Frame? Run one command on it and FramePort does the rest. Did this once already? Your Frame appears under step 2.": "",
 "New name": "",
 "Next": "",
+ "No": "",
 "No activity": "",
 "no answer from the Frame": "",
 "No artwork could be downloaded from that {source} result; the current artwork stays. Try another one.": "",
+ "No dev build is published right now": "",
 "No folders to rescan yet: add games with Scan a folder": "",
 "No Frames found. New Frame? Use first-time setup (step 1). Otherwise make sure Developer Mode is on (Settings → System → Developer) and the Frame is on the same network.": "",
 "No games found in that folder": "",
 "No limit": "",
 "No matching files": "",
 "No new games in {name}": "",
+ "No notes.": "",
 "No release notes.": "",
+ "No screenshots yet": "",
 "No Unreal crash reporter": "",
+ "no viewer open": "",
+ "No Wi-Fi needed: for networks that block the setup, and faster game uploads": "",
+ "No: a 2D app": "",
+ "None": "",
 "None found": "",
 "Normal": "",
 "Not enough space on the Frame": "",
 "Not enough space on the Frame ({detail}). Remove games you don't play or use Free up space on the Steam Frame page.": "",
+ "Not from a FramePort game": "",
 "Not installed": "",
 "Not now": "",
 "Not offered by Steam on this Frame yet": "",
 "Not recommended: breaks games that load VrApi through OVRPlugin.": "",
 "Not set up": "",
+ "Not streaming": "",
 "Not verified on many games yet: try it if the game doesn't work without it.": "",
 "Notes (what you checked, known issues)": "",
 "Nothing found. Try a shorter or different name.": "",
@@ -545,7 +670,9 @@
 "Offline": "",
 "Older workaround for upside-down quads: rotates them 180° (quads are single-sided; prefer flip_emul).": "",
 "On Frame": "",
+ "On the Frame, open Steam's Settings (Steam button → Settings).": "",
 "On the Frame, place Revive's runtime (FramePort's Revive, or the repack's bundled LibRevive) where the game's Oculus SDK looks for LibOVRRT so it can load a VR runtime (pure runtime substitution — what Revive's LoadLibrary hook does on Windows; that hook doesn't work under Proton on the Frame). It does NOT bypass the Oculus runtime signature check: a game that verifies the runtime's signature will still refuse it. Ignored on this PC (Revive's hook handles it there).": "",
+ "On the Frame: SteamVR dashboard → Launch a program → Desktop, then app menu → System → Konsole, and run (it reaches this computer over the USB cable):": "",
 "On the Frame: SteamVR dashboard → Launch a program → Desktop, then app menu → System → Konsole, and run:": "",
 "On this PC": "",
 "On this PC, launch the game through Revive's OpenVR backend, which talks straight to SteamVR — the original, most reliable Revive path. On by default for PC installs. Turn it off to use Revive's newer OpenXR backend instead. Ignored on the Frame (which always uses OpenXR).": "",
@@ -557,10 +684,13 @@
 "Open": "",
 "Open game": "",
 "Open GitHub issue": "",
+ "Open viewer": "",
 "OpenGL ES games run on the Frame through Zink (OpenGL on top of Vulkan), which is stricter than Quest drivers. Vulkan games run natively.": "",
 "Opens a prefilled GitHub issue with this game's recipe, so it can join the built-in catalog (no account token needed; you review and submit it on GitHub). No game files or personal data are sent.": "",
+ "Opens the app straight in VR, skipping its flat launcher screen (turn off to use the launcher, e.g. to import new content).": "",
 "Opens this player's storage on the Frame (Files tab): upload videos into the folder it lists": "",
 "OpenXR runtime": "",
+ "OR": "",
 "Or paste text to type it in one go": "",
 "Or turn on Developer Mode on the Frame (Settings → System → Developer): it then shows up under step 2. Open Settings → Developer → Pair new host on the Frame, click Connect there and approve FramePort. That way needs no connection into this computer.": "",
 "Override the guardian depth (0 = use guardian, min 1.5 m).": "",
@@ -571,6 +701,7 @@
 "OVRPort's OpenXR dispatcher aborts the app ('Wrong createInfo size', SIGABRT in libopenxr_loader.so xrCreateSwapchain) when a swapchain is wider or taller than 4096 px, which video players do for 8K video or big theatre textures (e.g. 4XVR). Raises the guard to 16384 px so the Frame's runtime (8192 px max) decides instead.": "",
 "OVRPort's own converter for games that use Meta's oldest VR interface (experimental).": "",
 "OVRPort's own VrApi→OpenXR adapter for engines that call libvrapi.so directly: the same upstream code as FramePort's 'VrApi → OpenXR bridge' without its Frame-specific changes. Only in OVRPort's experimental CLI builds (the stable CLI lists it but can't apply it).": "",
+ "OVRPort's platform loader answers the Meta Platform SDK's language-pack calls (ovr_LanguagePack_GetCurrent/SetCurrent) with 'no request', so a game that asks for its language pack never gets an answer. Adds a small library that serves language packs (<tag>.lang, e.g. de.lang) found in the game's own data folders (OBB and app files) through the same calls, the asset-file list and the status call, without any download. The game then finds the file path itself. The pack it applies with SetCurrent wins; otherwise the environment variable FRAMEPORT_LANGPACK (a tag), otherwise the only pack there is. Everything else goes to the loader unchanged. Off by default: turn it on for a game whose data has such files (the game page lists the patch only then).": "",
 "Package": "",
 "Pairing: on the Frame open Settings → Developer → Pair new host, then approve FramePort.": "",
 "Password (first time only)": "",
@@ -594,11 +725,13 @@
 "PC VR · Proton": "",
 "PC VR —": "",
 "PC VR ✓": "",
+ "Per-eye diagnostics (log)": "",
 "Pick several games and install them in one go. FramePort asks every question first, then works through the queue in the background.": "",
 "Picks a refresh rate and motion smoothing that suit the game on this PC.": "",
 "Pico/YVR/Quest metadata": "",
 "Picture": "",
 "pictures for the Steam library": "",
+ "Pictures you took in the headset (Steam screenshots on the Frame)": "",
 "Platform compat (ovrMessageType_ToString)": "",
 "Play on Frame": "",
 "Play on this PC": "",
@@ -614,6 +747,7 @@
 "Prevents a start-up crash in some Unreal games.": "",
 "Previous": "",
 "Problems and feedback": "",
+ "Program": "",
 "Proton couldn't run a test program (see the log)": "",
 "Proton debug log (Frame)": "",
 "Proton is Valve's Windows compatibility layer. On the Frame it runs PC VR games. Its ARM64 build isn't installed by default; FramePort can install it (Steam restarts once).": "",
@@ -622,7 +756,10 @@
 "Provide the Oculus runtime from Revive (Frame)": "",
 "Provides stand-ins for Meta store functions the game expects, so it doesn't crash at start.": "",
 "Provides stand-ins for Quest system reporting some games call at start.": "",
+ "Put the Frame to sleep": "",
+ "Put the Frame to sleep?": "",
 "Puts settings files next to the game on the Frame (e.g. to turn off an unsupported effect).": "",
+ "Quality": "",
 "Quest": "",
 "Quest games (Lepton)": "",
 "Quest ✓": "",
@@ -674,12 +811,15 @@
 "Removes Meta's old VR library when the game doesn't need it.": "",
 "Removes OVRPort's controller pose offset if controllers look misplaced.": "",
 "Removes requirements for Quest-only system parts.": "",
+ "Removes the color scale/bias (XR_KHR_composition_layer_color_scale_bias) from the game's layers, so the runtime doesn't apply it. The Frame's runtime allocates GPU memory for it every frame without freeing it, e.g. Vader Immortal leaked ~20 MB/s on its loading screen. Fades done this way no longer show.": "",
 "Removes the game from the Frame. Saves are kept, so a reinstall picks up where you left off.": "",
 "Removes the previous version kept after each reinstall and any leftover uploads. Games and saves aren't touched.": "",
 "Removes {title} from this PC's Steam library (Steam restarts once). The game folder isn't touched.": "",
 "Removes {title}'s game files from the Frame. Saves are kept; the Steam entry disappears after the next Steam restart.": "",
 "Rename": "",
 "Rename {name}": "",
+ "Rename…": "",
+ "Repeat xrLocateViews queries for the same display time get the first, fully tracked answer again. Games that ask several times per frame got slightly different poses and rendered parts of the frame with different heads: judder (e.g. I Am Cat; proposed by Klownicle, GitHub #8).": "",
 "Replace application label and icon": "",
 "Replaces libvrapi.so with a VrApi→OpenXR bridge (Android-XR-Bridge/OVRPort fork, GPL-3.0, patched for the Frame: GLES sessions, cylinder→quad layers, sRGB format fallback, 30 s VR-mode deadline, emulated time conversion). Needed when the engine calls VrApi itself instead of through OVRPlugin (e.g. The Climb 2, Path of the Warrior); OVRPort cannot translate those.": "",
 "Report a problem": "",
@@ -693,7 +833,10 @@
 ],
 "Reset to recommended": "",
 "Reset to suggested recipe": "",
+ "Restart": "",
 "Restart now": "",
+ "Restart the Frame": "",
+ "Restart the Frame?": "",
 "Resume": "",
 "Resuming — files already copied are skipped": "",
 "Retry rejected GLES formats/MSAA with sRGB, samples=1.": "",
@@ -706,13 +849,16 @@
 "Room height": "",
 "Room width": "",
 "Rotate quads 180°": "",
+ "Routes OVRPlugin through FramePort's extension shim, which turns Meta's amplitude-envelope vibrations into plain ones: OVRPort's loader reads their nanosecond duration as seconds and allocates gigabytes, freezing the Frame when the game vibrates a controller (e.g. Lucky's Tale's save slots, GitHub #9). Needs a rebuild.": "",
 "Runs directly — no Revive needed": "",
+ "Runs natively on SteamOS, started from the Frame's Steam library": "",
 "Runs Oculus PC games on OpenXR": "",
 "Runs OVRPort and apksigner": "",
 "Runs the game directly": "",
 "Runs xrSyncActions one at a time with xrPollEvent and skips it for 250 ms after focus returns. For games that crash in the runtime's input code right after focus comes back (SIGSEGV in vrclient.so UpdateActionStateInternal / xrSyncActions, e.g. Myst).": "",
 "Save": "",
 "Save as known-good recipe": "",
+ "Save the screenshots to which folder on this PC?": "",
 "Saved as a known-good recipe": "",
 "Saved as known-good. Check the issue on GitHub and submit it": "",
 "Saved {name} (in {parent})": "",
@@ -724,10 +870,13 @@
 "Scan a folder…": "",
 "Scan {name}": "",
 "Scans the folders you added games from again and adds games that appeared since. Games already in the library keep their recipe, tags and art; unchanged ones aren't analyzed again.": "",
+ "Screenshots": "",
+ "Screenshots on the Frame can be shown once FramePort is connected to it.": "",
 "SDL apps: start without a clipboard service": "",
 "Search": "",
 "Search again": "",
 "Search games and tags": "",
+ "Search the stores instead": "",
 "Searched a moment ago.": "",
 "Searching…": "",
 "See every patch and turn them on or off": "",
@@ -740,6 +889,7 @@
 "Set by you.": "",
 "Set up the connection to your Steam Frame first": "",
 "Set up the Frame": "",
+ "Set up with a USB cable": "",
 "Sets Unity QualitySettings antiAliasing to 0. Unity's multisampled render-to-texture path can hang the Frame's GL driver ('zink: DEVICE LOST', e.g. Sniper Elite VR). Try it for GLES Unity games that freeze or crash the GPU.": "",
 "Settings": "",
 "shader cache: makes later starts load faster; rebuilt if deleted": "",
@@ -755,14 +905,20 @@
 "Show less": "",
 "Show log": "",
 "Show more": "",
+ "Show only screenshots not from a FramePort game": "",
+ "Show only this game's screenshots": "",
 "Show progress": "",
 "Show setup command": "",
 "Show Steam Frame controllers": "",
 "Show technical details (patch ids, exact effects, parameters)": "",
 "Show the app's Android window (for typing)": "",
+ "Show video panels": "",
 "Showing {len} of {n}": "",
 "Shows 3D 360° pictures flat if they look doubled.": "",
 "Shows the Frame's cameras where the game expects passthrough.": "",
+ "Shows videos that games play on a flat panel (e.g. an intro video).": "",
+ "Shut down": "",
+ "Shut down the Frame?": "",
 "Signing keys matter: game updates must be signed with the same key or their saves are lost on reinstall.": "",
 "Signs rebuilt games": "",
 "Size": "",
@@ -772,6 +928,8 @@
 "Skip this version": "",
 "Skips a Quest-only reporting step in Meta's audio library that crashes some games.": "",
 "Skips Meta XR Audio's telemetry under x86_64 ARM translation (emulators). Not needed on the Frame, which runs games natively.": "",
+ "Sleep": "",
+ "Some apps open a flat Android launcher that then starts a separate VR activity (e.g. WiiCompiled). Shown with Lepton's flat window, that window stays in view after the VR part starts. This makes the VR activity the one Lepton starts (its LAUNCHER category), so the app opens in VR with no flat window. Everything only the launcher does (choosing or importing content) is skipped: turn it off for a run when you need the launcher, and turn off \"Show the app's Android window\".": "",
 "Some engines leave the pNext of unused Vulkan attachment references uninitialized. The Frame's driver never reads it, but Lepton always loads Steam's Fossilize shader-cache layer, which follows it and crashes on the first frame (SIGSEGV in libVkLayer_fossilize.so from FVulkanRenderPass, e.g. Deadpool VR). Loads Vulkan through a small shim that keeps valid pointers and drops only unreadable ones or ones pointing at the wrong structure type.": "",
 "Some game folders are already set up for SteamVR: a Revive copy (LibRevive64.dll) next to the game, started by a small loader DLL (e.g. xinput1_3.dll) that Windows loads from the game's folder. Then FramePort starts the game program directly — like double-clicking it — instead of through its own Revive (two Revives conflict; e.g. the Oculus Platform check then fails). On the Frame, Wine is told to use those loader DLLs from the game folder instead of its own.": "",
 "Some games need a second build with different OVRPort patches (for some Unreal games: one with Unreal's ForceQuit removed). Turn this on to install that build instead.": "",
@@ -779,17 +937,23 @@
 "Something went wrong": "",
 "Sort": "",
 "Source": "",
+ "square, 256 × 256": "",
 "Standard for every game": "",
+ "Start live view": "",
+ "Start straight in VR (skip the 2D launcher)": "",
 "Starting SteamVR and {title} — put your headset on": "",
+ "Starting the stream on the Frame…": "",
 "Starting {title} on the Frame — put the headset on": "",
 "Starting {title}, but SteamVR isn't running — it may open as a flat window. Start SteamVR and relaunch.": "",
 "Starting…": "",
+ "Starts a video stream on the Frame and opens it in your browser.": "",
 "Starts the game on the Frame while nobody is wearing it and reads the log: did it start, create a VR session and render frames. It can't check what you'd see: tracking only runs with the headset on.": "",
 "Starts the game through Steam on this PC (SteamVR + Revive)": "",
 "Starts the game through the Frame's Steam — put the headset on": "",
 "Starts the game with options, e.g. to choose SteamVR or OpenXR.": "",
 "Starts the game with the launcher that came with your copy.": "",
 "Status": "",
+ "Steadier head tracking": "",
 "Steady controller input after focus": "",
 "Steam": "",
 "Steam for Windows not found": "",
@@ -800,6 +964,11 @@
 "steamos@frame.local or an IP address": "",
 "SteamVR": "",
 "Stereo (3D) 360° layers: 0 = as the game sends them, 2 = flat (the left image to both eyes).": "",
+ "Stop": "",
+ "Stop objects popping in and out": "",
+ "Stopped: {why}": "",
+ "Stops a grey or frozen screen in Unity games that turn on anti-aliasing while running (e.g. The Room VR).": "",
+ "Stops a grey screen crash in some Unity games by skipping their overlay layers (e.g. The Room VR's screen fades).": "",
 "Stops Meta's audio library from reporting to Meta (only matters on PC emulators).": "",
 "Stops some Unreal games from closing themselves right after starting.": "",
 "Stops strict debugging checks that make some games quit.": "",
@@ -821,6 +990,8 @@
 "Switch Frame…": "",
 "Tags": "",
 "Tags:": "",
+ "Take one in the headset with Steam's screenshot shortcut; it shows up here. Screenshots are matched to the FramePort game that was running.": "",
+ "tall, 600 × 900": "",
 "Test": "",
 "Test Proton on the Frame": "",
 "Text and layout size": "",
@@ -830,21 +1001,33 @@
 "The copy on your Frame differs from what FramePort would install now (the recipe or your game files changed). Update to install the new build; saves are kept.": "",
 "The CPU types the game ships code for. The Frame runs only 64-bit ARM (arm64-v8a); 32-bit-only games can't run on it.": "",
 "The download didn't finish. Check your internet connection.": "",
+ "The first picture takes a few seconds.": "",
 "The Frame can't show curved panels; this shows them as gently bent strips.": "",
+ "The Frame goes to sleep in a few seconds. Wake it with its power button.": "",
+ "The Frame goes to sleep now.": "",
 "The Frame is charging: continuing the installs.": "",
+ "The Frame is restarting.": "",
+ "The Frame is shutting down.": "",
 "the Frame isn't connected": "",
 "The Frame isn't connected": "",
+ "The Frame only offers its USB connection in Developer Mode:": "",
 "The Frame refused that password. Check it, or run the first-time setup instead: Steam Frame → Show setup command.": "",
+ "The Frame restarts in a few seconds; FramePort reconnects when it's back.": "",
+ "The Frame turns off in a few seconds. Turn it on again with its power button.": "",
 "The Frame went offline: {exc}": "",
 "The Frame's battery is at {pct} % and not charging. Plug it in (a strong charger, not a PC port): long installs can drain it, and FramePort pauses them at {pause} %.": "",
 "The Frame's battery is at {pct} %: installs paused so it doesn't switch off mid-upload. Plug it in; the queue continues by itself.": "",
 "The Frame's desktop password, only needed the first time so FramePort can add its own key. After that it connects with the key.": "",
+ "The Frame's Steam couldn't start {title} (Steam error {code}). Please send a problem report so we can see why.": "",
+ "The Frame's Steam didn't accept {title}'s library entry, so FramePort added it as \"Devkit Game: …\" instead. Starting it now — put the headset on.": "",
 "The Frame's Steam library still shows the old artwork.": "",
 "the game didn't pass its checks (see the list above)": "",
 "the installed game (APK and its data)": "",
 "The launch settings changed since it was installed: update the Steam shortcut": "",
+ "The live view can start once FramePort is connected to the Frame.": "",
 "the log of the last start": "",
 "The PC VR counterpart of OVRPort's 'Patch Oculus detection for Unreal'. Unreal's Oculus plugin only starts when the Oculus service announces a headset (the Windows event 'OculusHMDConnected'); without it the game runs as a flat window. On the Frame the launcher runs the game through FramePort's small helper (fp_oculushmd.exe) that provides that event while the game runs, instead of relying only on Revive's hook of the check. Ignored on this PC (the Oculus app or Revive handle it there).": "",
+ "The picture opens in your default web browser, where it plays smoothly and can go full screen. It shows the headset's view with its sound (click Sound on in the player) whatever is running: Steam's menus, SteamVR or a game; while the headset sleeps the picture is black and updates about once a second. Streaming costs the Frame a little performance; stop it when you're done.": "",
 "the previous version, kept for one rollback": "",
 "The repack's own Revive · runs the game directly": "",
 "The small helper program FramePort runs on the Frame (installs, launch tests, Steam entries). It comes with this app and is replaced on the Frame automatically whenever it differs.": "",
@@ -853,6 +1036,7 @@
 "These games can't run on the Steam Frame": "",
 "These games check their Oculus license": "",
 "These installs need about {need} on the Frame, and it has {free} free. Remove games you don't play (or use Free up space on the Steam Frame page), or install fewer at once.": "",
+ "They are deleted on the Frame and can't be restored. Steam's own screenshot list may still show them until Steam restarts.": "",
 "They use the Oculus Platform SDK, which comes with the Meta Horizon (Oculus) app — it isn't installed on this PC, so they may quit right after starting. FramePort doesn't change how a game checks its license. Untick the ones you'd rather skip.": "",
 "They use the Oculus Platform SDK, which comes with the Meta Horizon (Oculus) app. It doesn't exist on the Steam Frame, so there they crash right at startup (seen with Robo Recall, Lies Beneath and Lone Echo) — play them on this PC. Tick any you still want to try on the Frame.": "",
 "They're Oculus games that need Revive to reach VR, and Revive can't run on the Frame. Play them on this PC instead (Install on this PC — SteamVR + Revive). Tick any you still want to put on the Frame to experiment (they'll likely run flat or crash).": "",
@@ -871,15 +1055,22 @@
 "This source checkout has uncommitted changes: commit or stash them, then update": "",
 "Tilts the controllers' pointing ray up (+) or down (−), for games whose pointer doesn't hit what you aim at.": "",
 "To finish, close FramePort and delete its program folder.": "",
+ "Today": "",
 "Tools": "",
 "Tools are up to date": "",
+ "Trace Meta platform requests (diagnostics)": "",
 "Translator for games built on Meta's oldest VR interface.": "",
+ "transparent PNG": "",
 "Treat newer Quest controllers as Touch": "",
 "Tried it in the headset? Tell us how it runs: with your recipe it can join FramePort's built-in list, so it works out of the box for everyone.": "",
 "Troubleshooting": "",
 "Try again": "",
 "Try now": "",
+ "Try Proton Experimental and reinstall": "",
 "Turn off only for games you play with your hands instead of controllers.": "",
+ "Turn off space warp": "",
+ "Turn on Developer Mode first": "",
+ "Turn the Frame off": "",
 "Turn this on if your copy is already patched: an APK is installed unchanged instead of being patched again. PC VR games are never modified on this PC; the Frame's copy only gets launch fixes.": "",
 "Turned around": "",
 "Turned on by you": "",
@@ -906,12 +1097,14 @@
 "Uninstall. ": "",
 "Uninstalled {title}": "",
 "Uninstalled {title} and deleted its files on this PC ({size})": "",
- "Unity 2017: start VR without Meta's system apps": "",
- "Unity's older built-in Oculus support (Unity 2017–2018) only starts VR when Android has Meta's com.oculus.systemactivities package; without it the game runs as a hidden 2D app (you see the Android home screen, e.g. Accounting+). Points that package name in libunity.so at \"android\", which always exists, and adds the frame wait its legacy frame loop never makes (libfp_ovrp.so calls ovrp_WaitToBeginFrame before ovrp_Update2; without it no frame starts and the dashboard freezes).": "",
+ "Unity's built-in Oculus support (Unity 2017–2019) only starts VR when Android has Meta's com.oculus.systemactivities package; without it the game runs as a 2D app (the Android home screen or a black window, e.g. Accounting+, BattleSisters). Points that package name in 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 warning) and which Lepton never delivers.": "",
 "Unity's TMP_InputField / InputField wait for Android's on-screen keyboard and close themselves a frame later when there is none (Lepton has no on-screen keyboard; Meta's system keyboard does this on a Quest), so a selected text field only flashes a caret. Rewrites TouchScreenKeyboardShouldBeUsed -> false and isKeyboardUsingEvents (TMP) / InPlaceEditing (uGUI) -> true in libil2cpp.so, found per game with Cpp2IL (downloaded on first use), so fields stay selected and take key presses: Steam's keyboard (with \"Show the app window\") or Type on Frame from the PC.": "",
 "Unity: disable MSAA": "",
 "Unity: keep MSAA off at runtime (OVRManager)": "",
 "Unity: render each eye separately (no multiview)": "",
+ "Unity: skip OVROverlay layers (fades, splash screens)": "",
+ "Unity: start VR without Meta's system apps": "",
+ "Unknown date": "",
 "Unreal builds of Meta XR Audio abort ('ClassNotFoundException com.oculus.os.AnalyticsEvent') on non-Quest devices. Patches that one JNI FindClass call so the library continues (e.g. NOPE Challenge).": "",
 "Unreal games start CrashReportClient when they crash, which leaves a crash dialog instead of simply closing. This passes -nocrashreports to the game and, on the Frame, renames the game's copy of CrashReportClient.exe so it can't start (your game files on this PC aren't changed).": "",
 "Untested": "",
@@ -921,6 +1114,7 @@
 "Update available": "",
 "Update failed: {exc}": "",
 "Update FramePort to {version}": "",
+ "Update game configs from GitHub automatically (confirmed configs arrive without a FramePort update)": "",
 "Update now": "",
 "Update on Frame": "",
 "Update on this PC": "",
@@ -933,7 +1127,9 @@
 "Updates, tools, this PC and where FramePort keeps its data": "",
 "Updating works in the desktop app": "",
 "Upload files": "",
+ "Upload files…": "",
 "Upload folder": "",
+ "Upload folder…": "",
 "Upload to {label}": "",
 "Uploaded {n} file": [
  "",
@@ -943,9 +1139,12 @@
 "Upside down and mirrored": "",
 "Use controllers": "",
 "Use tags to group and filter your library": "",
+ "Use the new config": "",
 "Use the repack's launcher (bundled Revive)": "",
 "Use this computer's keyboard on the Frame": "",
 "Use this program": "",
+ "Use your own artwork…": "",
+ "Use your own images…": "",
 "Uses OVRPort, Revive (LibreVR), Valve's Lepton and Proton. Not affiliated with Valve or Meta.": "",
 "Uses the Oculus Platform SDK: it checks your Oculus license. Normally that needs the Oculus app on this PC with a license you own, so it may quit right after starting on the headset. You can still try it.": "",
 "Uses the repack's bundled Revive — experimental on the Frame": "",
@@ -954,21 +1153,31 @@
 "Valve's Android runtime isn't installed (needs Developer Mode)": "",
 "Version": "",
 "Very high": "",
+ "Video panels that an Android media player draws into (XR_KHR_android_surface_swapchain, e.g. I Am Monkey's intro video), which the Frame's runtime refuses, get an Android Surface from FrameBridge: each video frame is copied into an ordinary swapchain the panel shows. Without it these panels are missing and a game waiting for its video stays black. 0 = leave them to the runtime.": "",
 "Video players' virtual theatres and 360° videos would otherwise stay black.": "",
 "Videos": "",
 "Videos, documents, mods and saves on your Steam Frame": "",
+ "View": "",
 "View screenshot": "",
+ "Viewer address on this PC: {url}": "",
+ "VR (OpenXR)": "",
 "VrApi → OpenXR adapter (OVRPort)": "",
 "VrApi → OpenXR bridge": "",
 "Vulkan shader fixes": "",
+ "Vulkan shim (frame.vk_sanitize): makes two Unreal habits valid Vulkan - depth images get VK_IMAGE_USAGE_TRANSFER_DST_BIT (they are cleared with vkCmdClearDepthStencilImage) and Qualcomm shader-resolve subpasses lose an invalid depth resolve. Found with the validation layer in Into The Radius 2 (flickering models, windows behind models).": "",
+ "Vulkan shim (frame.vk_sanitize): on gives every occlusion query room for both eyes. In multiview passes the Frame's driver writes a zero result for the second eye into the next query, so engines that count on one slot cull visible objects (models popping in and out, e.g. Into The Radius 2). 0 = off, 1 = on (2 slots).": "",
 "Vulkan shim (frame.vk_sanitize): SPIR-V modules matching size + SHA-256 get words inserted at a byte offset, e.g. stores that initialize locals a shader reads before writing (an undefined loop counter hung the GPU in VR4's campaign). Format: <size>:<sha256>:<byte offset>:<word>,<word>,...; several separated by ';'. Comes from a game's recipe.": "",
+ "Vulkan shim: validation layer": "",
 "Vulkan: drop invalid render-pass pointers": "",
 "v{remote} (updates on the next action)": "",
+ "Wait for the game's GPU before showing an image": "",
 "Waiting": "",
 "Waiting ({n})": "",
+ "Waiting for the cable…": "",
 "Waiting for the Frame": "",
 "Waiting for your Frame": "",
 "Waiting for your Frame… (code {code})": "",
+ "Watch what the headset shows, in a window on this PC": "",
 "Welcome to FramePort": "",
 "What FramePort will do": "",
 "What happens? (optional: you can also write it on GitHub)": "",
@@ -976,7 +1185,10 @@
 "Where it's installed": "",
 "Where this game's recipe came from: catalog (tested on a Frame), heuristics (suggested by FramePort) or user (changed by you).": "",
 "Which program starts {get}?": "",
- "Which Proton build runs the game on the Frame (a Steam compat tool name from the Frame's ARM64 compat list, e.g. proton_11-arm64 or proton-experimental-arm64). Empty = newest installed.": "",
+ "Which Proton build runs the game on the Frame: the stable Proton (the default: smoother in our tests) or Proton Experimental (gets Valve's ARM64 fixes first; try it when a game doesn't start or runs badly). Also takes any compat tool name from the Frame's ARM64 list.": "",
+ "Which Proton runs the game on the Frame: Stable is smoother; choose Experimental if the game doesn't start or runs badly.": "",
+ "Wide cover": "",
+ "wide, 1920 × 620": "",
 "Windows": "",
 "Windows game (Proton)": "",
 "Windows not detected": "",
@@ -996,6 +1208,10 @@
 "Writes liboverport.config.so with runtime options.": "",
 "Writes the conversion's settings into the game.": "",
 "XR_FB_passthrough via ALPHA_BLEND (Frame greyscale cameras).": "",
+ "Yes": "",
+ "Yes: uses the Frame's OpenXR runtime": "",
+ "Yesterday": "",
+ "You already have the latest dev build ({version})": "",
 "You have the latest version as of the last check ({when}).": "",
 "You have {version}. {how}": "",
 "Your copy is used as it is (only the Frame's copy gets launch patches)": "",
@@ -1005,6 +1221,7 @@
 "Your Frame isn't set up for FramePort yet. Run the first-time setup once (step 1).": "",
 "Your Frame restarted unexpectedly while {title} was running (or soon after). If that game crashed it, please report it.": "",
 "Your headset, what it's ready for and what's installed": "",
+ "Your own artwork for {title}": "",
 "Your own game files aren't touched.": "",
 "Your own tags (filled) can be anything you like. Outlined tags are added automatically from the engine, VR API and store genres. Filter the library by either.": "",
 "{count} files · {human}": "",
@@ -1022,10 +1239,14 @@
 "{int} h ago": "",
 "{int} min ago": "",
 "{label} ({host}) isn't reachable. Make sure it's switched on and on the same network.": "",
+ "{label} removed for {title}.": "",
+ "{label} updated for {title}.": "",
 "{len} known-good recipes (bundled, remote and yours)": "",
 "{len} results": "",
 "{len} selected": "",
+ "{message} The Frame's Steam library still shows the old art.": "",
 "{n_pc} on this PC": "",
+ "{name} isn't a Linux app (an AppImage, a Linux program or a .zip/.tar archive)": "",
 "{n} file": [
  "",
  ""
@@ -1042,6 +1263,10 @@
  "",
  ""
 ],
+ "{n} game config was updated": [
+  "",
+  ""
+ ],
 "{n} game didn't work out": [
  "",
  ""
@@ -1055,16 +1280,29 @@
  ""
 ],
 "{n} lines, the last 4000 shown": "",
+ "{n} needs a newer FramePort": [
+  "",
+  ""
+ ],
 "{n} new game in {name}": [
  "",
  ""
 ],
+ "{n} screenshot": [
+  "",
+  ""
+ ],
 "{n} selected": "",
 "{n} setting changed from the default": [
  "",
  ""
 ],
+ "{n} viewer": [
+  "",
+  ""
+ ],
 "{on} on your Frame": "",
+ "{rate}/s": "",
 "{remaining} more after this": "",
 "{title} couldn't be added to the Frame's Steam library: {why}": "",
 "{title} failed: {error}": "",
@@ -1077,6 +1315,7 @@
 "{title}: launch test {verdict} (furthest: {value})": "",
 "{title}: Steam artwork updated on the Frame": "",
 "{user}@{host} · {get} {get2} (build {get3})": "",
+ "{value:.0f} MiB": "",
 "{value:.1f} GiB": "",
 "{value} didn't work out": "",
 "{value} failed ({returncode})": "",
@@ -68,7 +68,8 @@ def needs_xrshim(recipe_patches: dict) -> bool:
    """Adapter features whose functions OVRPort's dispatcher doesn't forward (it only knows a fixed table)."""
    from ..settings import adapter_settings

-    return bool(adapter_settings(recipe_patches).get("controller_models"))
+    s = adapter_settings(recipe_patches)
+    return bool(s.get("controller_models") or s.get("haptic_fix"))


 def add_xrshim(ctx: ApkContext) -> bool:
@@ -0,0 +1,90 @@
+"""Language packs (`<tag>.lang` files in the game's data) for the Meta Platform SDK (native/langpack)."""
+from __future__ import annotations
+
+from ...analysis import elf
+from ..base import ApkContext, Patch, register
+from . import artifact
+
+LOADER = "libovrplatformloader.so"
+LIB = "libfp_langpack.so"
+META_MARK = b"@FPMETA@\0"  # native/langpack: g_meta_slot = marker + META_LEN bytes the Metadata is written into
+META_LEN = 96
+
+
+def with_metadata(lib: bytes, text: str) -> bytes:
+    """The library with `text` (the game's versionName) as the Metadata of the packs it serves.
+
+    Unreal games such as Deadpool VR only treat a pack as installed when its Metadata equals their own version string,
+    which Meta's store sets when the pack is uploaded."""
+    raw = text.encode("utf-8")
+    at = lib.find(META_MARK)
+    if not raw or len(raw) >= META_LEN or at < 0:
+        return lib
+    at += len(META_MARK)
+    return lib[:at] + raw + b"\0" * (META_LEN - len(raw)) + lib[at + META_LEN:]
+
+# Every function native/langpack/langpack.c defines. The loader's own exports of these are hidden (see
+# elf.hide_exports) so lookups reach LIB first; tests/test_langpack.py keeps this list equal to the C source.
+EXPORTS = (
+    "ovr_AssetDetailsArray_GetElement", "ovr_AssetDetailsArray_GetSize", "ovr_AssetDetails_GetAssetId",
+    "ovr_AssetDetails_GetAssetType", "ovr_AssetDetails_GetDownloadStatus", "ovr_AssetDetails_GetFilepath",
+    "ovr_AssetDetails_GetIapStatus", "ovr_AssetDetails_GetLanguage", "ovr_AssetDetails_GetMetadata",
+    "ovr_AssetFileDownloadResult_GetAssetId", "ovr_AssetFileDownloadResult_GetFilepath", "ovr_AssetFile_GetList",
+    "ovr_AssetFile_StatusById", "ovr_Error_GetCode", "ovr_Error_GetDisplayableMessage", "ovr_Error_GetHttpCode",
+    "ovr_Error_GetMessage", "ovr_FreeMessage", "ovr_LanguagePackInfo_GetEnglishName",
+    "ovr_LanguagePackInfo_GetNativeName", "ovr_LanguagePackInfo_GetTag", "ovr_LanguagePack_GetCurrent",
+    "ovr_LanguagePack_SetCurrent", "ovr_Message_GetAssetDetails", "ovr_Message_GetAssetDetailsArray",
+    "ovr_Message_GetAssetFileDownloadResult", "ovr_Message_GetError", "ovr_Message_GetRequestID",
+    "ovr_Message_GetType", "ovr_Message_IsError", "ovr_PopMessage",
+)
+
+
+class LanguagePacks(Patch):
+    id = "frame.langpacks"
+    title = "Language packs from the game's files"
+    description = ("OVRPort's platform loader answers the Meta Platform SDK's language-pack calls "
+                   "(ovr_LanguagePack_GetCurrent/SetCurrent) with 'no request', so a game that asks for its language "
+                   "pack never gets an answer. Adds a small library that serves language packs (<tag>.lang, e.g. "
+                   "de.lang) found in the game's own data folders (OBB and app files) through the same calls, the "
+                   "asset-file list and the status call, without any download. The game then finds the file path "
+                   "itself. The pack it applies with SetCurrent wins; otherwise the environment variable "
+                   "FRAMEPORT_LANGPACK (a tag), otherwise the only pack there is. Everything else goes to the "
+                   "loader unchanged. Off by default: turn it on for a game whose data has such files (the game "
+                   "page lists the patch only then).")
+    order = 32
+    experimental = True  # opt-in: checked in a headset with Deadpool VR, AC Nexus and Asgard's Wrath 2 only
+
+    # never part of a default recipe (few games tested): shown under Customize for games whose data has
+    # language packs, off until the user turns it on
+
+    def applies(self, a):
+        return LOADER in a.libs and "arm64-v8a" in a.abis and bool((a.extra or {}).get("lang_packs"))
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a" or not ws.has(ws.lib(LOADER)):
+            return False
+        loader = ws.read_lib(LOADER)
+        patched, hidden = elf.hide_exports(loader, EXPORTS)
+        if not hidden and LIB in elf.needed(loader):
+            return False  # applied by an earlier build
+        if not hidden:
+            ctx.notes.append("the platform loader has none of the language-pack functions: nothing to replace")
+            return False
+        patched = elf.add_needed(patched, LIB)
+        ws.put(ws.lib(LOADER), patched)
+        version = (ctx.analysis.version or "").strip()
+        ws.put(ws.lib(LIB), with_metadata(artifact(ws.abi, LIB), version))
+        ctx.notes.append(f"language packs served by {LIB} ({len(hidden)} loader functions replaced, "
+                         f"Metadata \"{version}\")")
+        return True
+
+    def validate(self, ctx: ApkContext):
+        ws = ctx.ws
+        if not ws.has(ws.lib(LOADER)):
+            return []
+        linked = LIB in elf.needed(ws.read_lib(LOADER))
+        return [("Language-pack library linked to the platform loader", linked and ws.has(ws.lib(LIB)), LIB)]
+
+
+register(LanguagePacks)
@@ -0,0 +1,54 @@
+"""Depth formats for LTW, the GL-to-GLES wrapper of Minecraft launchers (QuestCraft): native/glshim/eglfmt.c."""
+from __future__ import annotations
+
+from ...analysis import elf
+from ..base import ApkContext, Patch, Suggestion, register
+from . import artifact
+
+LTW = "libltw.so"
+EGL = "libEGL.so"
+SHIM = "libfpg.so"  # not longer than "libEGL.so": LTW's dlopen string is rewritten in place (.rodata only)
+
+
+class LtwDepthFormats(Patch):
+    id = "frame.ltw_depth"
+    needs_vr = False
+    title = "GL wrapper: OpenGL ES depth formats (Minecraft)"
+    description = ("Minecraft asks for desktop OpenGL's GL_DEPTH_COMPONENT32 depth textures. Some builds of LTW, the "
+                   "OpenGL-to-OpenGL ES wrapper in Minecraft launchers such as QuestCraft, pass that on unchanged; "
+                   "Quest's driver accepts it, the Frame's Mesa rejects it (GL_INVALID_OPERATION in glTexImage2D), so "
+                   "the depth buffer never exists and the picture stays black. LTW then loads OpenGL ES through a "
+                   "small shim that asks for GL_DEPTH_COMPONENT32F (or 24-bit) instead.")
+    order = 74
+    default_on = True
+
+    def applies(self, a):
+        return LTW in a.libs
+
+    def detect(self, a):
+        if self.applies(a):
+            return Suggestion(True, "Ships LTW (Minecraft's OpenGL-to-OpenGL ES wrapper): Minecraft's 32-bit depth "
+                                    "textures need the OpenGL ES format on the Frame (e.g. QuestCraft).")
+        return None
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a" or not ws.has(ws.lib(LTW)):
+            return False
+        data, count = elf.replace_rodata_string(ws.read_lib(LTW), EGL, SHIM)
+        if not count:
+            return False
+        ws.put(ws.lib(LTW), data)
+        ws.put(ws.lib(SHIM), artifact(ws.abi, SHIM))
+        ctx.notes.append(f"{LTW} loads OpenGL ES through {SHIM}")
+        return True
+
+    def validate(self, ctx: ApkContext):
+        ws = ctx.ws
+        if not ws.has(ws.lib(LTW)):
+            return []
+        uses = b"\0" + SHIM.encode() + b"\0" in ws.read_lib(LTW)
+        return [("LTW loads the depth-format shim", uses and ws.has(ws.lib(SHIM)), SHIM)]
+
+
+register(LtwDepthFormats)
@@ -2,7 +2,7 @@
 from __future__ import annotations

 from ...apk import axml
-from ..base import ApkContext, Patch, Suggestion, register
+from ..base import ApkContext, Param, Patch, Suggestion, register

 MANIFEST = "AndroidManifest.xml"

@@ -96,6 +96,54 @@ class MetaPermissions(Patch):
        return bool(fixed)


+class StartActivity(Patch):
+    id = "frame.start_activity"
+    needs_vr = False
+    title = "Start straight in VR (skip the 2D launcher)"
+    description = ("Some apps open a flat Android launcher that then starts a separate VR activity (e.g. WiiCompiled). "
+                   "Shown with Lepton's flat window, that window stays in view after the VR part starts. This makes "
+                   "the VR activity the one Lepton starts (its LAUNCHER category), so the app opens in VR with no "
+                   "flat window. Everything only the launcher does (choosing or importing content) is skipped: turn "
+                   "it off for a run when you need the launcher, and turn off \"Show the app's Android window\".")
+    order = 22
+    params = [Param("activity", "str", "", "Activity to start (empty: the app's VR activity)")]
+
+    def applies(self, a):
+        return bool((a.extra or {}).get("vr_activity"))
+
+    def detect(self, a):
+        vr = (a.extra or {}).get("vr_activity")
+        if not vr:
+            return None
+        return Suggestion(False, f"The app opens a 2D launcher; its VR part is {vr.rsplit('.', 1)[-1]}. Turn on to "
+                                 "start that directly once the app is set up.")
+
+    def apply(self, ctx: ApkContext) -> bool:
+        manifest = ctx.ws.read(MANIFEST)
+        # the original APK's VR activity (analysis): after OVRPort's conversion every MAIN activity has the VR
+        # category, so the converted manifest no longer tells them apart
+        activity = ((ctx.params or {}).get("activity") or (ctx.analysis.extra or {}).get("vr_activity")
+                    or axml.vr_activity(manifest))
+        if not activity:
+            ctx.notes.append("no VR activity found")
+            return False
+        fixed = axml.set_start_activity(manifest, activity)
+        if fixed:
+            ctx.ws.put(MANIFEST, fixed)
+            ctx.notes.append(f"starts {activity}")
+        return bool(fixed)
+
+    def validate(self, ctx):
+        manifest = ctx.ws.read(MANIFEST)
+        names = axml.Axml(manifest).strings()
+        starts = [n for el, n, items in axml.component_filters(manifest) if el in ("activity", "activity-alias")
+                  and any(k == "category" and names[i] == axml.LAUNCHER for k, _, i in items)]
+        wanted = (ctx.params or {}).get("activity") or (ctx.analysis.extra or {}).get("vr_activity") or ""
+        ok = len(starts) == 1 and wanted.rsplit(".", 1)[-1] == starts[0].rsplit(".", 1)[-1]
+        return [("Only the VR activity is a launcher", ok, ", ".join(starts))]
+
+
 register(Launcher)
 register(NoDebuggable)
 register(MetaPermissions)
+register(StartActivity)
@@ -0,0 +1,65 @@
+"""Meta Platform SDK tracer (diagnostics): logs the game's ovr_* calls and their answers (native/ovrtrace)."""
+from __future__ import annotations
+
+from ...analysis import elf
+from ..base import ApkContext, Patch, register
+from . import artifact
+
+LIB = "libfp_ovrtrace.so"
+SKIP = ("libovrplatformloader", "libfp_", "libframe", "libopenxr", "libOVRPlugin", "libvrapi", "libc++")
+
+
+def ovr_importers(ws) -> list[str]:
+    """The game's libraries that call Meta Platform SDK functions (ovr_* imports)."""
+    out = []
+    for lib in ws.libs():
+        if lib.startswith(SKIP):
+            continue
+        data = ws.read_lib(lib)
+        if elf.is_elf(data) and any(s.startswith("ovr_") for s in elf.dyn_symbols(data, False)):
+            out.append(lib)
+    return out
+
+
+class OvrTrace(Patch):
+    id = "frame.ovr_trace"
+    title = "Trace Meta platform requests (diagnostics)"
+    description = ("Logs every Meta Platform SDK request the game makes (user, entitlement, cloud saves, ...) and the "
+                   "messages that answer them, and every 10 s the requests that never got an answer (logcat tag "
+                   "fp_ovrtrace, in launch.log). For games that wait forever on a loading screen (e.g. Vader "
+                   "Immortal after its intro). Changes nothing: every call goes to the real function.")
+    order = 95
+    needs_vr = False
+    experimental = True
+
+    def applies(self, a):
+        return "arm64-v8a" in a.abis and "libovrplatformloader.so" in a.libs
+
+    def detect(self, a):
+        return None  # diagnostics only, on request
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a":
+            return False
+        libs = ovr_importers(ws)
+        for lib in libs:
+            data = ws.read_lib(lib)
+            if LIB not in elf.needed(data):
+                ws.put(ws.lib(lib), elf.add_needed(data, LIB))
+        if libs:
+            ws.put(ws.lib(LIB), artifact(ws.abi, LIB))
+            ctx.notes.append(f"Meta platform calls traced in {', '.join(libs)}")
+        return bool(libs)
+
+    def validate(self, ctx: ApkContext):
+        ws = ctx.ws
+        traced = []
+        for lib in ws.libs():
+            data = b"" if lib.startswith(SKIP) else ws.read_lib(lib)
+            if elf.is_elf(data) and LIB in elf.needed(data):
+                traced.append(lib)
+        return [("Platform tracer loaded", bool(traced) and ws.has(ws.lib(LIB)), ", ".join(traced))] if traced else []
+
+
+register(OvrTrace)
@@ -5,6 +5,8 @@ Android home screen, e.g. Accounting+, Unity 2017.4). The package name in libuni
 installed): a same-length, in-place string edit; everything else about the check stays as it is."""
 from __future__ import annotations

+import os
+
 from ...analysis import elf
 from ..base import ApkContext, Patch, Suggestion, register
 from . import artifact
@@ -14,38 +16,95 @@ 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"
+# 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
 # return, report input focus as true and release buttons held > 2 s. Accounting+ still didn't pass "press any button"
 # with them (input reached the game cleanly), so they stay off; switch on to investigate another game.
-INPUT_PROBE = False
+INPUT_PROBE = os.environ.get("FRAMEPORT_INPUT_PROBE") == "1"  # diagnostic builds only
 INPUT_CALLS = ("ovrp_GetConnectedControllers", "ovrp_GetControllerState4", "ovrp_GetControllerState2",
               "ovrp_GetAppHasInputFocus")
 UNITY_INPUT_CALLS = ("ovrp_GetControllerState", "ovrp_GetControllerState2")


+ORR_W2_6 = 0x321F07E2  # orr w2, wzr, #6   (strncmp length 6)
+MOV_W2_0 = 0x52800002  # mov w2, #0        (strncmp length 0: always equal)
+
+
+def oculus_model_checks(data: bytes) -> tuple[bytes, int]:
+    """Unity's built-in Oculus input only reports controllers on a device whose model starts with "Oculus"
+    (strncmp(SystemInfo.deviceModel, "Oculus", 6), next to its Oculus Go check "Oculus Pacific"). Lepton's Android is
+    "Valve Lepton", so BattleSisters got no controller buttons. Every such compare (the literal loaded with adrp/add
+    right before `orr w2, wzr, #6`) gets length 0, so any device but the Go counts as an Oculus one. The "Oculus"
+    string itself stays: Unity also uses it as its VR device name."""
+    import struct
+
+    literal = data.find(b"\0Oculus\0") + 1
+    if literal <= 0:
+        return data, 0
+    buf, count = bytearray(data), 0
+    end = len(data) - len(data) % 4
+    for at in range(0, end, 4):
+        if struct.unpack_from("<I", data, at)[0] != ORR_W2_6:
+            continue
+        # look back for `adrp xA, page` + `add x1, xA, #off` that computes the literal's address
+        for back in range(4, 16, 4):
+            add = struct.unpack_from("<I", data, at - back)[0] if at >= back else 0
+            if add & 0xFFC00000 != 0x91000000 or add & 0x1F != 1:  # add x1, xN, #imm (no shift)
+                continue
+            rn, imm12 = (add >> 5) & 0x1F, (add >> 10) & 0xFFF
+            adrp_at = at - back - 4
+            adrp = struct.unpack_from("<I", data, adrp_at)[0] if adrp_at >= 0 else 0
+            if adrp & 0x9F000000 != 0x90000000 or adrp & 0x1F != rn:
+                continue
+            imm = ((adrp >> 5) & 0x7FFFF) << 2 | (adrp >> 29) & 3
+            if imm & (1 << 20):
+                imm -= 1 << 21
+            if (adrp_at & ~0xFFF) + (imm << 12) + imm12 == literal:
+                struct.pack_into("<I", buf, at, MOV_W2_0)
+                count += 1
+            break
+    return bytes(buf), count
+
+
 class UnityOculusCheck(Patch):
    id = "frame.unity_oculus_check"
-    title = "Unity 2017: start VR without Meta's system apps"
-    description = ("Unity's older built-in Oculus support (Unity 2017–2018) only starts VR when Android has Meta's "
-                   "com.oculus.systemactivities package; without it the game runs as a hidden 2D app (you see the "
-                   "Android home screen, e.g. Accounting+). Points that package name in libunity.so at \"android\", "
-                   "which always exists, and adds the frame wait its legacy frame loop never makes (libfp_ovrp.so "
-                   "calls ovrp_WaitToBeginFrame before ovrp_Update2; without it no frame starts and the dashboard "
-                   "freezes).")
+    title = "Unity: start VR without Meta's system apps"
+    description = ("Unity's built-in Oculus support (Unity 2017–2019) only starts VR when Android has Meta's "
+                   "com.oculus.systemactivities package; without it the game runs as a 2D app (the Android home "
+                   "screen or a black window, e.g. Accounting+, BattleSisters). Points that package name in "
+                   "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 "
+                   "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
+
+    @staticmethod
+    def _major(a) -> int:
+        return int(str((a.extra or {}).get("unity_version") or "0").split(".")[0] or 0)
+
+    @classmethod
+    def legacy_loop(cls, a) -> bool:
+        """Unity's built-in Oculus VR drives OVRPlugin without waiting for frames: Unity 2017-2018, and 2019 games
+        without the Oculus XR Plugin (BattleSisters flooded "outside of frame bounds" and hung the GPU). With
+        libOculusXRPlugin.so (XR Plugin Management, e.g. Lucky's Tale) the plugin waits itself."""
+        major = cls._major(a)
+        return 0 < major < 2019 or (major == 2019 and "libOculusXRPlugin.so" not in a.libs)

    def applies(self, a):
-        x = a.extra or {}
-        major = int(str(x.get("unity_version") or "0").split(".")[0] or 0)
-        # Unity 2019+ games run without it (e.g. Lucky's Tale 2019.4): their builds stay as they are
-        return a.engine == "Unity" and "libOVRPlugin.so" in a.libs and bool(x.get("unity_oculus_check")) \
-            and 0 < major < 2019
+        # any Unity with built-in Oculus support whose libunity.so has the check (BattleSisters, Unity 2019.4, stayed
+        # a 2D app without it); Lucky's Tale (2019.4) runs either way
+        return a.engine == "Unity" and "libOVRPlugin.so" in a.libs and bool((a.extra or {}).get("unity_oculus_check"))

    def detect(self, a):
        if self.applies(a):
-            return Suggestion(True, "Older Unity with built-in Oculus support: it checks for Meta's system apps "
-                                    "before starting VR, and its frame loop never waits for the next frame "
-                                    "(e.g. Accounting+).")
+            return Suggestion(True, "Unity with built-in Oculus support: it checks for Meta's system apps before "
+                                    "starting VR, else it runs as a 2D app (e.g. Accounting+, BattleSisters).")
        return None

    def apply(self, ctx: ApkContext) -> bool:
@@ -56,7 +115,15 @@ class UnityOculusCheck(Patch):
        data, count = elf.replace_rodata_string(ws.read(name), PACKAGE, ALWAYS_THERE)
        if not count:
            return False
-        data, loops = elf.replace_rodata_string(data, UPDATE, SHIM_UPDATE)
+        data, loops = elf.replace_rodata_string(data, UPDATE, SHIM_UPDATE) if self.legacy_loop(ctx.analysis) \
+            else (data, 0)
+        if loops and self._major(ctx.analysis) >= 2019:  # Accounting+ (2017) reads OVRInput: works without
+            data, models = oculus_model_checks(data)
+            if models:
+                ctx.notes.append(f"libunity.so: {models} Oculus device-model checks accept Lepton's model")
+            data, nodes = elf.replace_rodata_string(data, NODE, SHIM_NODE)
+            if nodes:
+                ctx.notes.append(f"libunity.so: {NODE} -> {SHIM_NODE}")
        plugin = ws.lib("libOVRPlugin.so")
        if loops and ws.abi == "arm64-v8a" and ws.has(plugin):
            ovrp = ws.read(plugin)
@@ -23,11 +23,16 @@ class UnityRuntimeMsaa(Il2cppReturnPatch):
    description = ("Meta's OVRManager switches Unity to the headset's recommended MSAA level (4x) while the game runs, "
                   "whatever its quality settings say (log: \"Switching to the recommended level\"). Multisampled "
                   "render-to-texture on GLES can hang the Frame's GPU, up to a restart of the whole headset (e.g. "
-                   "Lucky's Tale in a menu). Rewrites OVRDisplay.recommendedMSAALevel -> 0 in libil2cpp.so (found with "
-                   "Cpp2IL), so MSAA stays off.")
+                   "Lucky's Tale in a menu) or a crash of its GL driver (e.g. The Room VR, whose own code sets 4x). "
+                   "Rewrites OVRDisplay.recommendedMSAALevel -> 0 and makes QualitySettings.antiAliasing's setter do "
+                   "nothing in libil2cpp.so (found with Cpp2IL), so MSAA stays off.")
    order = 47
    targets = {"Oculus.VR/OVRDisplay.cs": {"get_recommendedMSAALevel": RET_ZERO},
-               "Assembly-CSharp/OVRDisplay.cs": {"get_recommendedMSAALevel": RET_ZERO}}  # older Oculus Integration
+               "Assembly-CSharp/OVRDisplay.cs": {"get_recommendedMSAALevel": RET_ZERO},  # older Oculus Integration
+               # the game's own code can raise MSAA too (The Room VR: QualitySettingsManager.SetMSAA with its
+               # platform's default 4): Unity's setter does nothing, the quality settings' 0 stays
+               "UnityEngine.CoreModule/UnityEngine/QualitySettings.cs": {"set_antiAliasing": RET_ZERO}}
+    revision = 2  # 0.11.0: also QualitySettings.set_antiAliasing (the game's own runtime MSAA crashed Zink)
    check_name = "Unity MSAA"

    def applies(self, a):
@@ -65,5 +70,27 @@ class UnityMultiPass(Il2cppReturnPatch):
        return None  # only for a game that shows the symptom (catalog recipe or the user's choice)


+class UnityNoOverlayCopy(Il2cppReturnPatch):
+    id = "frame.unity_no_overlay_copy"
+    title = "Unity: skip OVROverlay layers (fades, splash screens)"
+    description = ("Meta's OVROverlay copies a texture into its own compositor layer every frame. For some games "
+                   "(e.g. The Room VR's screen fade, a 4x4 overlay) that copy crashes the Frame's GL driver: SIGSEGV "
+                   "in libgallium_dri.so on Unity's render thread right after a tiny xrCreateSwapchain, grey or frozen "
+                   "screen. Rewrites OVROverlay.PopulateLayer -> false in libil2cpp.so (found with Cpp2IL): overlays "
+                   "are skipped (fades become instant cuts, overlay splash screens don't show). Only for games with "
+                   "this crash: menus drawn as overlays would disappear too.")
+    order = 49
+    targets = {"Oculus.VR/OVROverlay.cs": {"PopulateLayer": RET_ZERO},
+               "Assembly-CSharp/OVROverlay.cs": {"PopulateLayer": RET_ZERO}}  # older Oculus Integration
+    check_name = "Unity overlays"
+
+    def applies(self, a):
+        return a.engine == "Unity" and "libil2cpp.so" in a.libs and not a.only_32bit and "GLES" in a.graphics
+
+    def detect(self, a):
+        return None  # only for a game that shows the crash (catalog recipe or the user's choice)
+
+
 register(UnityRuntimeMsaa)
 register(UnityMultiPass)
+register(UnityNoOverlayCopy)
@@ -84,5 +84,29 @@ class GlShim(Patch):
        return True


+class UnityGlShim(GlShim):
+    id = "frame.unity_gl_shim"
+    title = "GL shim for Unity (no multisampled render-to-texture)"
+    description = (
+        "Loads the GL shim into a Unity GLES game and hides GL_EXT_multisampled_render_to_texture (and the multiview "
+        "variant). Some Unity games switch their eye buffer to 4x MSAA at runtime; the Frame only gives single-sampled "
+        "swapchains, Unity then renders through multisampled render-to-texture and Mesa/Zink crashes (SIGSEGV in "
+        "libgallium_dri.so on the render thread: grey or frozen screen, e.g. The Room VR). Hidden, Unity uses an "
+        "ordinary MSAA buffer and resolves it. Unity's multiview stays on (gl_hide_multiview defaults to 0 here).")
+    order = 62
+    requires = ()
+    experimental = False
+
+    def detect(self, a):
+        if self.applies(a) and ((a.extra or {}).get("ovr_runtime_msaa") or a.unity_msaa_levels):
+            return Suggestion(True, "Unity GLES game that may switch to MSAA at runtime: hide multisampled "
+                                    "render-to-texture, which crashes the Frame's GL driver (e.g. The Room VR).")
+        return None
+
+    def applies(self, a):
+        return a.engine == "Unity" and "GLES" in a.graphics and "arm64-v8a" in a.abis
+
+
 register(VrApiBridge)
 register(GlShim)
+register(UnityGlShim)
@@ -97,6 +97,10 @@ class OverportPatch(Patch):
                return Suggestion(True, f"Very heavy game ({total / 2**30:.0f} GiB) using OVRPlugin: application space "
                                        "warp causes artifacts/hangs off-Quest.")
            return Suggestion(False, "Enable if the game shows warping artifacts or hangs (uses OVRPlugin space warp).")
+        if self.id == "patch_ac_nexus_no_appsw_90" and self.applies(a):
+            # verified in the headset (owner preferred 90 Hz over 72): the catalog default, now also without it
+            return Suggestion(True, "This Assassin's Creed Nexus build runs smoothly on the Frame without application "
+                                    "space warp, at 90 Hz.")
        if self.id == "patch_remove_unreal_force_quit" and ap.is_unreal(a):
            return Suggestion(False, "Built as the alternate APK for Unreal games (use it if the game quits itself).")
        return None
@@ -202,10 +202,12 @@ class ProtonLog(_PcvrPatch):
 class ProtonTool(_PcvrPatch):
    id = "pcvr.proton_tool"
    title = "Proton version (Frame)"
-    description = ("Which Proton build runs the game on the Frame (a Steam compat tool name from the Frame's ARM64 "
-                   "compat list, e.g. proton_11-arm64 or proton-experimental-arm64). Empty = newest installed.")
+    description = ("Which Proton build runs the game on the Frame: the stable Proton (the default: smoother in our "
+                   "tests) or Proton Experimental (gets Valve's ARM64 fixes first; try it when a game doesn't start "
+                   "or runs badly). Also takes any compat tool name from the Frame's ARM64 list.")
    order = 40
-    params = [Param("tool", "str", "", "compat tool name")]
+    params = [Param("tool", "str", "", "proton-stable (default), proton-experimental, or a compat tool name")]
+    CHOICES = (("", "Stable (default)"), ("proton-experimental", "Experimental"))


 class ProtonEnv(_PcvrPatch):
@@ -16,6 +16,18 @@ SETTINGS = [
    ("scale", "float", 1.0, "Resolution scale",
     "Multiplies the recommended eye-buffer width and height (0.5–2.0). 1.5 ≈ 2.25× pixels."),
    ("foveation_fix", "int", 1, "Hide Quest foveation", "Hides Quest foveation extensions the Frame runtime lacks."),
+    ("snapshot", "int", 0, "Eye-image snapshots (diagnostics)",
+     "Every N seconds, saves the left-eye image the game submits (a quarter of its size) as fb_snap_0-7.ppm in the "
+     "game's files folder on the Frame. Launch tests run without anyone wearing the headset, so the headset view stays "
+     "black; this shows what the game itself draws. OpenGL ES games only."),
+    ("strip_color_bias", "int", 0, "Drop layer color fades",
+     "Removes the color scale/bias (XR_KHR_composition_layer_color_scale_bias) from the game's layers, so the runtime "
+     "doesn't apply it. The Frame's runtime allocates GPU memory for it every frame without freeing it, e.g. Vader "
+     "Immortal leaked ~20 MB/s on its loading screen. Fades done this way no longer show."),
+    ("hide_space_warp", "int", 0, "Turn off space warp",
+     "Hides XR_FB_space_warp, so the game renders every frame itself instead of half of them plus motion vectors "
+     "(Application SpaceWarp). For games whose picture flickers or smears on the Frame (e.g. Unreal Engine 5 games "
+     "such as Into The Radius 2)."),
    ("controller_fix", "int", 1, "Report Touch controllers",
     "Reports Frame controllers as Oculus Touch and hides synthetic hand tracking. Set 0 for games that require hand "
     "tracking (e.g. Silhouette)."),
@@ -31,6 +43,11 @@ SETTINGS = [
    ("cylinder_strips", "int", 1, "Show curved panels",
     "Cylinder layers (curved menus and movie screens, e.g. 4XVR), which the Frame's runtime lacks, are shown as a "
     "few flat strips along the curve. 0 = drop them. 360° (equirect) layers can't be shown on the Frame."),
+    ("surface_emul", "int", 1, "Show video panels",
+     "Video panels that an Android media player draws into (XR_KHR_android_surface_swapchain, e.g. I Am Monkey's "
+     "intro video), which the Frame's runtime refuses, get an Android Surface from FrameBridge: each video frame is "
+     "copied into an ordinary swapchain the panel shows. Without it these panels are missing and a game waiting for "
+     "its video stays black. 0 = leave them to the runtime."),
    ("equirect_emul", "int", 0, "Show 360° layers",
     "360° (equirect) layers, e.g. a video player's virtual theatre or 360° videos (e.g. 4XVR), which the Frame's "
     "runtime lacks, are drawn by a background thread into a layer behind the game's own picture: the 360° image is "
@@ -52,10 +69,11 @@ SETTINGS = [
    ("stable_local", "int", 0, "Keep the play space still",
     "Every 'local' play space the game creates lines up with the one at the start. For games whose menus or screens "
     "jump to where you look on the Frame."),
-    ("focus_hold", "int", 0, "Ignore brief focus dips",
-     "Hides the Frame's brief focus dips (up to a second) once the game has been focused for a second. For "
-     "games that recentre or pause every time focus returns."),
-    ("focus_hold_ms", "float", 1000.0, "Longest focus dip to ignore (ms)",
+    ("focus_hold", "int", 1, "Ignore brief focus dips",
+     "Hides the Frame's brief focus dips (up to focus_hold_ms) once the game has been focused for a second. On by "
+     "default: the Frame's wear sensor flickers \"HMD off\" for 0.5-2 s while worn, and many games pause or recentre "
+     "every time (e.g. Blade & Sorcery, Lucky's Tale)."),
+    ("focus_hold_ms", "float", 5000.0, "Longest focus dip to ignore (ms)",
     "focus_hold hides focus dips up to this long (100-5000). Longer for a headset whose wear sensor flickers "
     "(\"HMD off\" for 0.5-2 s while worn, e.g. Blade & Sorcery pausing); taking the headset off or the system menu "
     "pauses the game only after this long."),
@@ -78,6 +96,14 @@ SETTINGS = [
    ("layer_debug", "int", 0, "Extra diagnostics (log)",
     "Logs details for debugging: composition layers and swapchains, focus changes, play-space creation, pointer vs "
     "grip poses, refresh rates. No effect on the game."),
+    ("eye_debug", "int", 0, "Per-eye diagnostics (log)",
+     "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."),
+    ("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 "
+     "(compare both in one session)."),
    ("scene_emul", "int", 0, "Emulate Meta scene (room)",
     "Fake XR_FB_scene/spatial entities: a guardian-sized room with floor, ceiling and four walls, for mixed-reality "
     "games that build their level from the room (e.g. Demeter)."),
@@ -91,6 +117,18 @@ SETTINGS = [
     "Override the guardian width (0 = use guardian, min 1.5 m)."),
    ("scene_depth", "float", 0.0, "Emulated room depth (m)",
     "Override the guardian depth (0 = use guardian, min 1.5 m)."),
+    ("pose_consistency", "int", 0, "Consistent head poses per frame",
+     "Repeat xrLocateViews queries for the same display time get the first, fully tracked answer again. Games that "
+     "ask several times per frame got slightly different poses and rendered parts of the frame with different heads: "
+     "judder (e.g. I Am Cat; proposed by Klownicle, GitHub #8)."),
+    ("haptic_fix", "int", 0, "Fix controller vibration freezes",
+     "Routes OVRPlugin through FramePort's extension shim, which turns Meta's amplitude-envelope vibrations into "
+     "plain ones: OVRPort's loader reads their nanosecond duration as seconds and allocates gigabytes, freezing the "
+     "Frame when the game vibrates a controller (e.g. Lucky's Tale's save slots, GitHub #9). Needs a rebuild."),
+    ("rect_clamp", "int", 1, "Clamp image rects",
+     "Keeps every submitted image rect inside its swapchain. Unity can size the eye area a few pixels past the image "
+     "on some Frames; SteamVR then rejects every frame (xrEndFrame -25, XR_ERROR_SWAPCHAIN_RECT_INVALID) and the game "
+     "stops drawing (e.g. PowerWash Simulator stuck at \"Waiting\")."),
    ("swap_eyes", "int", 0, "Swap eyes", "Swap left/right views (diagnostic)."),
    ("strip_depth", "int", 0, "Strip depth layers", "Remove XR_KHR_composition_layer_depth chains (diagnostic)."),
    ("mutable_fix", "int", 0, "Mutable swapchain fix", "Experimental Vulkan mutable-format workaround."),
@@ -102,14 +140,30 @@ SETTINGS = [
     "e.g. stores that initialize locals a shader reads before writing (an undefined loop counter hung the GPU in "
     "VR4's campaign). Format: <size>:<sha256>:<byte offset>:<word>,<word>,...; several separated by ';'. Comes from "
     "a game's recipe."),
+    ("vk_query_slots", "int", 0, "Vulkan shim: slots per occlusion query",
+     "Vulkan shim (frame.vk_sanitize): on gives every occlusion query room for both eyes. In multiview passes the "
+     "Frame's driver writes a zero result for the second eye into the next query, so engines that count on one slot "
+     "cull visible objects (models popping in and out, e.g. Into The Radius 2). 0 = off, 1 = on (2 slots)."),
+    ("vk_spec_fixes", "int", 0, "Vulkan shim: depth spec fixes",
+     "Vulkan shim (frame.vk_sanitize): makes two Unreal habits valid Vulkan - depth images get "
+     "VK_IMAGE_USAGE_TRANSFER_DST_BIT (they are cleared with vkCmdClearDepthStencilImage) and Qualcomm shader-resolve "
+     "subpasses lose an invalid depth resolve. Found with the validation layer in Into The Radius 2 (flickering "
+     "models, windows behind models)."),
+    ("vk_validation", "int", 0, "Vulkan shim: validation layer",
+     "Diagnostics: the Vulkan shim (frame.vk_sanitize) adds Khronos' validation layer to the game's instance; its "
+     "findings go to launch.log. The layer library (libVkLayer_khronos_validation.so) must be in the APK."),
+    ("gl_hide_msrtt", "int", 1, "GL shim: hide multisampled render-to-texture",
+     "GL shim only: hide GL_EXT_multisampled_render_to_texture(2) (Zink crashes rendering Unity's runtime MSAA eye "
+     "buffer through it, e.g. The Room VR)."),
    ("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)."),
 ]


-# settings that need a new build, not only new settings files: the Vulkan shim learned vk_shader_fix in 0.6.4
-REVISIONS = {"vk_shader_fix": 2}
+# 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
+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
 # shown; advanced ones only under "Show advanced settings"), a plain label and one-line help, the control, and the
@@ -130,6 +184,21 @@ UI: dict[str, dict] = {
    "focus_hold_ms": dict(group="screens", level="advanced", label="Ignore focus dips up to", depends="focus_hold",
                          help="Longer for headsets that briefly think they're off your head.",
                          control=("slider", 500.0, 3000.0, 100.0, "{:.0f} ms")),
+    "pose_consistency": dict(group="picture", level="advanced", label="Steadier head tracking",
+                             help="For games that judder or shimmer while you hold your head still (e.g. I Am Cat).",
+                             control=("switch",)),
+    "haptic_fix": dict(group="controllers", level="advanced", label="Fix freezes when controllers vibrate",
+                       help="For games that freeze the Frame when a controller vibrates (e.g. Lucky's Tale). Needs a "
+                            "rebuild.",
+                       control=("switch",)),
+    "vk_spec_fixes": dict(group="troubleshooting", level="advanced", label="Fix depth flicker (Unreal Vulkan)",
+                          help="For Unreal games whose models flicker or show through walls and windows on the Frame "
+                               "(e.g. Into The Radius 2). Needs a rebuild.",
+                          control=("switch",)),
+    "vk_query_slots": dict(group="troubleshooting", level="advanced", label="Stop objects popping in and out",
+                           help="For Vulkan games whose models flicker or vanish while you look at them (e.g. Into "
+                                "The Radius 2). Needs a rebuild.",
+                           control=("switch",)),
    "sync_guard": dict(group="troubleshooting", level="advanced", label="Steady controller input after focus",
                       help="For games that crash right after you return to them (e.g. after the Steam menu).",
                       control=("switch",)),
@@ -150,6 +219,9 @@ UI: dict[str, dict] = {
    "cylinder_strips": dict(group="screens", level="common", label="Show curved menus and screens",
                            help="The Frame can't show curved panels; this shows them as gently bent strips.",
                            control=("switch",)),
+    "surface_emul": dict(group="screens", level="common", label="Show video panels",
+                         help="Shows videos that games play on a flat panel (e.g. an intro video).",
+                         control=("switch",)),
    "flip_emul": dict(group="screens", level="common", label="Fix upside-down menus",
                      help="Turns menus and text the right way up.", control=("switch",)),
    "stable_local": dict(group="screens", level="common", label="Keep menus in place",
@@ -190,8 +262,9 @@ UI: dict[str, dict] = {
                            help="Shows 3D 360° pictures flat if they look doubled.",
                            control=("choice", [(0, "As the game sends it"), (2, "Flat")])),
    **{key: dict(group="troubleshooting", level="advanced", control=("switch",)) for key in (
-        "foveation_fix", "swapchain_fix", "layer_fix", "gl_hide_multiview", "mutable_fix", "flip_quads", "swap_eyes",
-        "strip_depth", "respace_kick", "layer_debug")},
+        "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")},
 }


@@ -217,9 +290,18 @@ class AdapterSetting(Patch):
        if self.key == "controller_models" and uses_render_models(a):
            return Suggestion(True, "The game asks the headset for its controller models: show Steam Frame controllers "
                                    "instead of Quest Touch controllers.", {"value": 1})
+        if self.key == "haptic_fix" and "libOVRPlugin.so" in a.libs:
+            return Suggestion(True, "Meta's OVRPlugin vibrates controllers through OVRPort's loader, which turns some "
+                                    "vibrations into gigabyte allocations that freeze the Frame (e.g. Lucky's Tale, "
+                                    "BattleSisters): vibrations are converted before they reach it.", {"value": 1})
        if self.key == "equirect_emul" and uses_equirect_layers(a):
            return Suggestion(True, "The game draws 360° layers (e.g. a video player's theatre or 360° videos), which "
                                    "the Frame's runtime can't show: show them as panels around you.", {"value": 1})
+        if self.key == "hide_space_warp" and "libUnreal.so" in a.libs and "libOVRPlugin.so" in a.libs:
+            # Unreal Engine 5 + Meta's plugin: Application SpaceWarp is on by default (Into The Radius 2 flickered;
+            # OVRPort's patch_disable_space_warp doesn't reach UE5). Off until confirmed in more games.
+            return Suggestion(False, "Unreal Engine 5 game with Meta's space warp: turn on if the picture flickers or "
+                                     "smears (e.g. Into The Radius 2).", {"value": 1})
        if self.key == "scene_emul" and needs_scene(a):
            return Suggestion(True, "Mixed-reality game that builds its level from the room model: emulate a "
                                    "guardian-sized room (e.g. Demeter).", {"value": 1})
@@ -240,7 +322,12 @@ class AdapterSetting(Patch):
            "mutable_fix": ap.is_vulkan,
            "swapchain_fix": ap.is_gles,
            "gl_hide_multiview": lambda a: a.direct_vrapi and ap.is_gles(a),
+            "gl_hide_msrtt": ap.is_gles,
            "vk_shader_fix": lambda a: a.engine == "Unreal",  # read by the Vulkan shim, which only Unreal games get
+            "vk_query_slots": lambda a: a.engine == "Unreal" and ap.is_vulkan(a),
+            "vk_validation": lambda a: a.engine == "Unreal",
+            "haptic_fix": lambda a: "libOVRPlugin.so" in a.libs,
+            "vk_spec_fixes": lambda a: a.engine == "Unreal" and ap.is_vulkan(a),
            "controller_models": ap.may_use_render_models,
            **{k: ap.is_gles for k in ("equirect_emul", "equirect_face", "equirect_res", "equirect_flip",
                                       "equirect_fps", "equirect_stereo")},
@@ -38,10 +38,22 @@ SUMMARIES = {
    "frame.adapter": "FramePort's translator between the game and the Steam Frame: fills in what the Frame lacks "
                     "(controllers, room, passthrough). Needed for every converted game.",
    "frame.launcher": "Makes the game start from the Frame's Steam library.",
+    "frame.start_activity": "Opens the app straight in VR, skipping its flat launcher screen (turn off to use the "
+                            "launcher, e.g. to import new content).",
+    "frame.ltw_depth": "Fixes the black picture in Minecraft launchers (e.g. QuestCraft): uses depth formats the "
+                       "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.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.",
    "frame.meta_permissions": "Declares Meta's permissions some mixed-reality games ask for, so they don't stop.",
    "frame.ovrplatformcompat": "Adds a small piece of Meta's platform library that some games need to start.",
    "frame.ovrstubs": "Provides stand-ins for Meta store functions the game expects, so it doesn't crash at start.",
+    "frame.langpacks": "Lets the game find language files (like de.lang) that are already in its data, instead of "
+                       "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.unity_no_msaa": "Turns off a smoothing setting that crashes some older Unity games on the Frame.",
    "frame.unity_runtime_msaa_off": "Keeps a smoothing setting off that the game turns on itself and that can freeze "
                                    "the Frame.",
@@ -72,7 +84,8 @@ SUMMARIES = {
    "pcvr.revive_openvr": "On this PC, runs Revive through SteamVR (works with more headsets).",
    "pcvr.xr_timefix": "Lets games written for newer OpenXR versions run on the Frame.",
    "pcvr.proton_log": "Writes a detailed Proton log for troubleshooting.",
-    "pcvr.proton_tool": "Chooses which Proton version runs the game on the Frame.",
+    "pcvr.proton_tool": "Which Proton runs the game on the Frame: Stable is smoother; choose Experimental if the "
+                        "game doesn't start or runs badly.",
    "pcvr.steamvr_tuning": "Picks a refresh rate and motion smoothing that suit the game on this PC.",
    "pcvr.proton_env": "Extra settings for Proton (for testing).",
 }
@@ -9,10 +9,12 @@ PC (Revive + local Steam) or on the Frame (Proton + Revive).
 """
 from __future__ import annotations

+import threading
 import time
 from pathlib import Path

 from . import build as builder
+from .analysis import langpacks
 from .analysis.detect import analyze
 from .artwork import fetch as artwork
 from .core import library
@@ -252,6 +254,12 @@ def fetch_details(package: str, reporter: Reporter | None = None) -> dict:
 def set_exe(package: str, exe: str) -> dict:
    """The user picked the program that starts a Rift game: re-analyze with it (keeps recipe choices and tags)."""
    entry = library.game(package)
+    if entry and is_linux(entry):  # a Linux app: the same source again, with this program
+        folder = Path(entry["game_dir"])
+        if not (folder / exe).is_file():
+            raise FileNotFoundError(folder / exe)
+        source = ((entry.get("analysis") or {}).get("extra") or {}).get("source") or entry["game_dir"]
+        return add_linux_app(source, exe=exe)
    if not entry or entry.get("kind") != "rift":
        raise ValueError(f"{package} is not a Rift game")
    folder = Path(entry["game_dir"])
@@ -271,10 +279,80 @@ def is_rift(entry: dict) -> bool:
    return entry.get("kind") == "rift"


+def is_linux(entry: dict) -> bool:
+    """A native arm64 Linux app (AppImage / folder / archive), installed as it is (GitHub #31)."""
+    return entry.get("kind") == "linux"
+
+
+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)."""
+    from .analysis import linux
+    from .core.models import Recipe
+
+    path = Path(path)
+    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.")
+    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)}}
+    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)
+        size = sum((root / f).stat().st_size for f in info["files"]) if info["files"] else \
+            sum(f.stat().st_size for f in root.rglob("*") if f.is_file())
+    except OSError:
+        size = 0
+    fields = dict(kind="linux", name=path.name, apk=None, game_dir=info["root"], exe=info["exe"], data_dir=None,
+                  origin=str(path.parent), analysis=analysis, suggested=library.recipe_to_dict(recipe),
+                  data_bytes=size)
+    if not old:
+        fields.update(title=info["title"], recipe=library.recipe_to_dict(recipe), status="unknown")
+    library.upsert_game(package, **fields)
+    try:
+        from .artwork import fetch
+
+        fetch.artwork_dir(package)
+        from .artwork import steam
+
+        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)
+
+
+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.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:
+        reporter.check("Libraries on the Frame", True, "everything the app needs is there")
+    if add_to_library:
+        target.add_to_library([package], reporter)
+    _record_install(package, target.label, {"exe": entry["exe"], "result": result, "time": time.time()})
+    return result
+
+
 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)
    recipe = engine.suggest(a)
    return library.upsert_game(
        a.package, title=recipe.title or a.label, name=src.name, apk=str(src.apk),
@@ -294,6 +372,7 @@ def reanalyze(package: str, 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)
    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),
@@ -324,6 +403,23 @@ def reset_recipe(package: str) -> Recipe:
    return recipe


+def apply_catalog_update(package: str) -> Recipe:
+    """Take the newer catalog recipe for a game whose recipe the user edited (the game page's "newer known-good
+    config" offer): derived again from the catalog, keeping the user's FrameBridge settings the catalog doesn't set."""
+    entry = library.game(package)
+    old = library.recipe_from_dict(entry["recipe"])
+    recipe = engine.suggest(library.analysis_from_dict(entry["analysis"]))
+    for pid, params in old.patches.items():
+        if pid.startswith("adapter.") and pid not in recipe.patches:
+            recipe.patches[pid] = params
+            if pid in old.reasons:
+                recipe.reasons[pid] = old.reasons[pid]
+    set_recipe(package, recipe)
+    with library.edit() as data:
+        data["games"].get(package, {}).pop("catalog_update", None)
+    return recipe
+
+
 def prepare_rift(package: str, reporter: Reporter) -> dict:
    """Rift games aren't rebuilt: check the folder still matches the analysis and make sure Revive is available."""
    from .build import sha256
@@ -399,8 +495,19 @@ def recipe_fingerprint(recipe: dict) -> str:
    return fp(recipe)


+_build_locks: dict[str, threading.Lock] = {}
+_build_locks_guard = threading.Lock()
+
+
+def _build_lock(package: str) -> threading.Lock:
+    with _build_locks_guard:
+        return _build_locks.setdefault(package, threading.Lock())
+
+
 def build_game(package: str, reporter: Reporter, outdir: Path | None = None) -> dict:
    entry = library.game(package)
+    if is_linux(entry):  # nothing to convert: installed as it is
+        return {"ok": True, "linux": True}
    if is_rift(entry):
        return prepare_rift(package, reporter)
    if library.recipe_from_dict(entry["recipe"]).as_is:
@@ -409,7 +516,8 @@ def build_game(package: str, reporter: Reporter, outdir: Path | None = None) ->
    a = library.analysis_from_dict(entry["analysis"])
    recipe = library.recipe_from_dict(entry["recipe"])
    out = outdir or (output_dir() / quest_dump.display_name(entry.get("name") or package))
-    res = builder.build(src, a, recipe, out, reporter)
+    with _build_lock(package):  # one build per game at a time: builds share the game's work folder
+        res = builder.build(src, a, recipe, out, reporter)
    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,
@@ -422,6 +530,8 @@ def install_game(package: str, target: Target, reporter: Reporter, apk_only: boo
                 add_to_library: bool = True, apk: Path | None = None) -> dict:
    """Install the game's last build (or `apk`, e.g. a test build of the same package signed with the same key)."""
    entry = library.game(package)
+    if is_linux(entry):
+        return install_linux(package, target, reporter, add_to_library)
    if is_rift(entry):
        return install_rift(package, target, reporter, add_to_library)
    test_build = apk is not None
@@ -464,13 +574,17 @@ def local_game_files(package: str) -> list[Path]:
    paths: list[Path] = []
    if g.get("kind") == "rift":
        paths += [Path(g["game_dir"])] if g.get("game_dir") else []
+    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]
    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 for p in (o.get("apk"), o.get("data_dir"), o.get("game_dir")) if p]
+    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]
+    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
        rp = p.resolve()
@@ -478,6 +592,21 @@ def local_game_files(package: str) -> list[Path]:
    return [p for p in dict.fromkeys(paths) if p.exists() and not shared(p)]


+def linux_local_files(g: dict) -> list[Path]:
+    """A Linux app's own files: a lone AppImage/program (never the folder it sits in, e.g. Downloads), the app's
+    folder, or the archive it came from + FramePort's unpacked copy of it."""
+    extra = (g.get("analysis") or {}).get("extra") or {}
+    root = Path(g["game_dir"]) if g.get("game_dir") else None
+    if root is None:
+        return []
+    if extra.get("files"):
+        return [root / f for f in extra["files"]]
+    source = Path(extra["source"]) if extra.get("source") else None
+    if source is not None and source.is_file():  # an archive: it and its unpacked copy in FramePort's data folder
+        return [source, root]
+    return [root]
+
+
 def delete_local_files(package: str) -> tuple[list[str], int]:
    """Delete local_game_files(package), then the game's folder if that left it empty, and drop the library entry (the
    game can't be rebuilt without its files). Returns (deleted paths, bytes freed)."""
@@ -485,7 +614,8 @@ def delete_local_files(package: str) -> tuple[list[str], int]:

    files = local_game_files(package)
    freed, done = 0, []
-    parents = {p.parent for p in files}
+    # (not for Linux apps: a lone AppImage's folder is the user's, e.g. Downloads)
+    parents = set() if is_linux(library.game(package) or {}) else {p.parent for p in files}
    for p in files:
        size = sum(f.stat().st_size for f in p.rglob("*") if f.is_file()) if p.is_dir() else p.stat().st_size
        shutil.rmtree(p) if p.is_dir() else p.unlink()
@@ -555,14 +685,30 @@ def test_game(package: str, target: Target, reporter: Reporter, seconds: int = 4
    for old in sorted(logs.glob(f"{package}-*.log"))[:-5]:  # keep the last 5 per game
        old.unlink(missing_ok=True)
    reporter.log(f"full launch log ({len((log or '').splitlines())} lines): {log_path}")
+    suggestions = useful_suggestions(package, result.suggestions())
+    if proton_alternative_worth_trying(package, result.verdict):
+        suggestions.append(PROTON_TOOL)
+        reporter.log("it failed on the stable Proton: the suggestion is to try Proton Experimental")
    summary = {"state": result.state, "verdict": result.verdict, "milestone": result.milestone, "fps": result.fps,
               "findings": [f.__dict__ for f in result.findings],
-               "suggestions": useful_suggestions(package, result.suggestions()),
+               "suggestions": suggestions,
               "time": time.time(), "target": target.label, "log_path": str(log_path)}
    library.upsert_game(package, last_test=summary)
    return summary


+PROTON_TOOL = "pcvr.proton_tool"  # as a suggestion: run the game with Proton Experimental instead of the stable one
+
+
+def proton_alternative_worth_trying(package: str, verdict: str | None) -> bool:
+    """A PC VR game failed its launch test on the stable Proton (the default): Proton Experimental is worth a try."""
+    entry = library.game(package) or {}
+    if not is_rift(entry) or verdict == "pass":
+        return False
+    chosen = ((entry.get("recipe") or {}).get("patches") or {}).get(PROTON_TOOL) or {}
+    return "experimental" not in (chosen.get("tool") or "")
+
+
 def useful_suggestions(package: str, suggestions: list[str]) -> list[str]:
    """Triage suggestions that would change something: not already on, and not conflicting with the recipe (e.g. no
    Revive for a repack that runs its own)."""
@@ -584,6 +730,10 @@ def apply_suggestions(package: str, suggestions: list[str]) -> Recipe:
    entry = library.game(package)
    recipe = library.recipe_from_dict(entry["recipe"])
    for pid in suggestions:
+        if pid == PROTON_TOOL:
+            recipe.patches[pid] = {"tool": "proton-experimental"}
+            recipe.reasons[pid] = "It failed on the stable Proton: trying Proton Experimental."
+            continue
        if pid.startswith("adapter."):
            from .patches.base import get

@@ -2,8 +2,11 @@

 Sources, highest priority first:
  1. user entries   <user data>/catalog/games/*.yaml  (written by "Save as known-good" after a successful test)
-  2. remote catalog FRAMEPORT_CATALOG_URL (a folder URL serving index.json + <package>.yaml), cached; lets the
-                    catalog be updated without a new app release
+  2. remote catalog the repo's catalog/games on GitHub `main` (default; or FRAMEPORT_CATALOG_URL, a folder URL serving
+                    index.json + <package>.yaml): confirmed configs reach installed apps without a release. Fetched
+                    in the background (refresh_remote, at most every 6 h); loading only reads the cache. An entry that
+                    needs a newer FramePort (a patch, adapter setting or recipe field this version doesn't know, or
+                    min_app above this version) is skipped: the bundled entry stays.
  3. bundled        catalog/games/*.yaml in this repo
 """
 from __future__ import annotations
@@ -50,6 +53,7 @@ class CatalogEntry:
    as_is: bool = False  # Rift: the dump runs unchanged (e.g. a SteamVR build: no Revive)
    verified: dict = field(default_factory=dict)
    updated: str = ""  # date of the last maintainer change without a new headset test (e.g. a fix from a report)
+    min_app: str = ""  # oldest FramePort version this entry is for (remote entries for a newer app are skipped)
    source_hint: str = ""
    origin: str = "bundled"

@@ -96,10 +100,144 @@ def _load_dir(path: Path, origin: str) -> dict[str, CatalogEntry]:
 PACKAGE_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)+$")


+REMOTE_EVERY = 6 * 3600
+GITHUB_TREE = "https://api.github.com/repos/{repo}/git/trees/{ref}?recursive=1"
+GITHUB_RAW = "https://raw.githubusercontent.com/{repo}/{ref}/{path}"
+GITHUB_DIR = "catalog/games/"
+
+
+def _repo() -> str:
+    from .. import REPO_URL
+
+    return REPO_URL.removeprefix("https://github.com/").strip("/")
+
+
+def remote_enabled() -> bool:
+    """Automatic catalog updates from GitHub (Settings; FRAMEPORT_NO_CATALOG_UPDATE=1 turns them off)."""
+    from ..core import library
+
+    if os.environ.get("FRAMEPORT_NO_CATALOG_UPDATE"):
+        return False
+    try:
+        # never library.setting(): load() refreshes recipes from the catalog, which would load the catalog again
+        return bool(library.peek_setting("catalog.auto_update", True))
+    except Exception:  # noqa: BLE001 - no library yet
+        return True
+
+
+def unusable_reason(entry_dict: dict) -> str | None:
+    """Why this FramePort can't use a (remote) entry, or None: a recipe field, patch or adapter setting it doesn't
+    know (the entry was written for a newer FramePort), or min_app above this version."""
+    from .. import __version__
+    from ..patches import base
+    from ..updates import parse_version
+
+    unknown = [k for k in entry_dict if k not in CatalogEntry.__dataclass_fields__]
+    if unknown:
+        return f"unknown field(s) {', '.join(sorted(unknown))}"
+    if entry_dict.get("min_app") and parse_version(str(entry_dict["min_app"])) > parse_version(__version__):
+        return f"needs FramePort {entry_dict['min_app']}"
+    base.load_all()  # every patch registered (overport ids come from this app's OVRPort list)
+    known = set(base.REGISTRY)
+    ids = [i for key in ("overport_extra", "overport_remove", "alt_overport", "frame", "frame_remove", "device",
+                         "pcvr", "pcvr_remove") for i in (entry_dict.get(key) or [])]
+    ids += [f"adapter.{k}" for k in (entry_dict.get("adapter") or {})]
+    missing = [i for i in ids if isinstance(i, str) and i not in known]
+    return f"unknown patch(es) {', '.join(missing)}" if missing else None
+
+
+def _remote_index_path() -> Path:
+    return cache.cache_dir() / "catalog-github.json"
+
+
+def refresh_remote(force: bool = False) -> int:
+    """Fetch new/changed entries from GitHub main into the cache (one API call for the file list + one raw download
+    per changed file). Returns the number of files downloaded. Never raises (offline: the cache stays)."""
+    import json
+    import time
+
+    if not remote_enabled() or os.environ.get("FRAMEPORT_CATALOG_URL"):
+        return 0
+    idx_path = _remote_index_path()
+    try:
+        old = json.loads(idx_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        old = {}
+    if not force and time.time() - old.get("checked", 0) < REMOTE_EVERY:
+        return 0
+    repo, fetched = _repo(), 0
+    try:
+        tree = cache.http_get(GITHUB_TREE.format(repo=repo, ref="main"), timeout=20).json()
+        files = {t["path"][len(GITHUB_DIR):]: t["sha"] for t in tree.get("tree") or []
+                 if t.get("type") == "blob" and t.get("path", "").startswith(GITHUB_DIR)
+                 and t["path"].endswith(".yaml") and "/" not in t["path"][len(GITHUB_DIR):]}
+        for name, sha in files.items():
+            dest = cache.cache_dir() / f"catalog-gh-{sha}.yaml"
+            if dest.exists() or not PACKAGE_RE.match(name.removesuffix(".yaml")):
+                continue
+            text = cache.http_get(GITHUB_RAW.format(repo=repo, ref="main", path=GITHUB_DIR + name), timeout=20).text
+            cache.write_atomic(dest, text)
+            fetched += 1
+        for f in cache.cache_dir().glob("catalog-gh-*.yaml"):  # files gone from main (or old versions)
+            if f.name.removeprefix("catalog-gh-").removesuffix(".yaml") not in files.values():
+                f.unlink(missing_ok=True)
+        cache.write_atomic(idx_path, json.dumps({"checked": time.time(), "files": files}))
+    except Exception:  # noqa: BLE001 - offline / rate limited: keep what we have, try again next time
+        return 0
+    if fetched or files != old.get("files"):
+        load(refresh=True)
+    if not old.get("files"):  # the first download (a new install): nothing was "updated"
+        return 0
+    return fetched
+
+
+def remote_status() -> dict:
+    """{checked: time or None, entries: n, skipped: {package: reason}} for Settings."""
+    import json
+
+    try:
+        idx = json.loads(_remote_index_path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        idx = {}
+    load()
+    return {"checked": idx.get("checked"), "entries": len(idx.get("files") or {}), "skipped": dict(_skipped)}
+
+
+_skipped: dict[str, str] = {}
+
+
+def _load_github() -> dict[str, CatalogEntry]:
+    """Cached entries from GitHub main (no network here)."""
+    import json
+
+    try:
+        files = json.loads(_remote_index_path().read_text(encoding="utf-8")).get("files") or {}
+    except (OSError, ValueError):
+        return {}
+    out = {}
+    for sha in files.values():
+        path = cache.cache_dir() / f"catalog-gh-{sha}.yaml"
+        try:
+            d = yaml.safe_load(path.read_text(encoding="utf-8"))
+        except (OSError, yaml.YAMLError):
+            continue
+        if not isinstance(d, dict) or not d.get("package"):
+            continue
+        reason = unusable_reason(d)
+        if reason:
+            _skipped[d["package"]] = reason
+            continue
+        try:
+            out[d["package"]] = CatalogEntry.from_dict(d, "remote")
+        except Exception:  # noqa: BLE001
+            continue
+    return out
+
+
 def _load_remote() -> dict[str, CatalogEntry]:
    base = os.environ.get("FRAMEPORT_CATALOG_URL")
    if not base:
-        return {}
+        return _load_github() if remote_enabled() else {}
    base = base.rstrip("/") + "/"
    index = cache.cached_json("catalog-index.json", base + "index.json", max_age=6 * 3600, fallback=[])
    out = {}
@@ -109,7 +247,12 @@ def _load_remote() -> dict[str, CatalogEntry]:
        text = cache.cached_text(f"catalog-{pkg}.yaml", f"{base}{pkg}.yaml", max_age=6 * 3600)
        if text:
            try:
-                out[pkg] = CatalogEntry.from_dict(yaml.safe_load(text), "remote")
+                d = yaml.safe_load(text)
+                reason = unusable_reason(d)
+                if reason:
+                    _skipped[pkg] = reason
+                    continue
+                out[pkg] = CatalogEntry.from_dict(d, "remote")
            except Exception:
                pass
    return out
@@ -122,7 +265,11 @@ def load(refresh: bool = False) -> dict[str, CatalogEntry]:
    global _cache
    if _cache is None or refresh:
        entries = _load_dir(catalog_dir() / "games", "bundled")
-        entries.update(_load_remote())
+        _skipped.clear()
+        for pkg, e in _load_remote().items():
+            # main is normally ahead of the bundled copy; a source checkout or dev build may be ahead of main
+            if pkg not in entries or _when(e) >= _when(entries[pkg]):
+                entries[pkg] = e
        for pkg, e in _load_dir(user_catalog_dir(), "user").items():
            if not _newer(entries.get(pkg), e):  # the user's own recipe, unless a maintained one was verified later
                entries[pkg] = e
@@ -130,6 +277,10 @@ def load(refresh: bool = False) -> dict[str, CatalogEntry]:
    return _cache


+def _when(e: CatalogEntry) -> str:
+    return max(str(e.updated or ""), str(e.verified.get("date") or ""))
+
+
 def _newer(maintained: CatalogEntry | None, user: CatalogEntry) -> bool:
    """True when the bundled/remote entry was verified after the user's (e.g. a fix for a config the user shared)."""
    if maintained is None:
@@ -33,6 +33,10 @@ 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)."""
+        raise NotImplementedError(f"{self.label} can't install Linux apps")
+
    def collect_diag(self, package: str | None = None) -> dict:
        """Debug data from the target for a diagnostics bundle: {"host": {...}, "files": {name: text}, ...}."""
        return {}