Install links: FramePort-only manifest fields (frameport.description / frameport.icon) shown in the install question and used as the game's icon and description; readable titles for bare file links; handler scripts wait for the open window to take a link (a just-closed window's heartbeat swallowed clicks on Windows), the heartbeat is removed on close, and the Windows handler runs under conhost --headless (no console flash)

Lint: line lengths, import order, unused loop variable (ruff)
Install links (FrameDrop's "Install with FrameDrop" button protocol), drop files on the Library, add a lone Windows .exe, VR / flat window choice, x86_64 Linux apps through FEX
2026-10-08 03:01:01 +02:00 · 2026-10-07 16:35:21 -04:00 · 2026-10-07 16:09:03 -04:00 · 2026-10-07 16:06:40 -04:00 · 2026-10-07 09:24:17 -04:00 · 2026-10-06 23:13:52 -04:00
174 changed files with 14694 additions and 612 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' }}
@@ -84,8 +96,27 @@ jobs:
        if: runner.os == 'macOS'
        run: |
          app=$(find dist -maxdepth 3 -name "*.app" -type d | head -1)
-          codesign --force --deep --sign - "$app"
+          # Re-signing replaces the signature, entitlements included: pass them again, or the file picker refuses to
+          # open ("ENTITLEMENT_NOT_FOUND", GitHub #63). flet build writes them to Release.entitlements; the
+          # PyInstaller fallback has none, so it gets the same set.
+          ent=build/flutter/macos/Runner/Release.entitlements
+          if [ ! -f "$ent" ]; then
+            ent="$RUNNER_TEMP/FramePort.entitlements"
+            cat > "$ent" <<'EOF'
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0"><dict>
+            <key>com.apple.security.cs.allow-jit</key><true/>
+            <key>com.apple.security.cs.allow-unsigned-executable-memory</key><true/>
+            <key>com.apple.security.network.client</key><true/>
+            <key>com.apple.security.network.server</key><true/>
+            <key>com.apple.security.files.user-selected.read-write</key><true/>
+          </dict></plist>
+          EOF
+          fi
+          codesign --force --deep --sign - --entitlements "$ent" "$app"
          codesign --verify --deep --strict --verbose=2 "$app"
+          codesign -d --entitlements - "$app" 2>/dev/null | tee /dev/stderr | grep -q "files.user-selected.read-write"

      # ---- package (archives keep permissions/symlinks) + provenance ----
      - name: Package (Windows)
@@ -148,3 +179,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
@@ -91,6 +111,15 @@ 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>`; x86_64 builds run through FEX (app 3127680, no SLR:
+    RootFS /usr/share/guestos/fex-mesa from the OS image; needs `STEAM_COMPAT_DATA_PATH`, see docs/FRAME_RUNTIME.md):
+    agent v61 `linux_x86_tools`/`pick_tool`, `install_proton`/`proton_status` `kind: linux_x86`, `finalize_linux
+    x86_64`, `installer.ensure_proton(kind=)`; an arm64 program wins over an x86_64 one): GUI = Add
+    games → "Add a Linux app…" /
+    "…folder…" (`app.add_linux` job → `pipeline.add_linux_app`); game page `linux_summary` (program + Change…, AppImage,
+    OpenXR, source) instead of recipe/patches, `C.missing_libraries` callout (Frame deployment, else last install);
+    no Analyze/Rebuild/recipe/share/Game settings actions, Frame only; platform "Linux" badge + library filter; Steam
+    tags "Linux app on Frame"/"Linux"; `_follow_catalog` skips them; local files of a lone AppImage = the file only.
  - 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
@@ -152,7 +181,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
@@ -388,7 +417,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
@@ -497,7 +526,88 @@ lacks (ActivityNotFoundException) → imported by hand: libmain.so + game.json
 DATA/ → external files/WiiCompiledOpenXRVR/DATA, MOD/ → .../RetroRewind6 (decompiled with jadx). Lepton has no
 picker at all: a FramePort fix would be an injected picker activity. Generated cover/banner art used to suppress the
 Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
-**Steam library failures (GitHub #21/#30):** on some Frames Steam never loads FramePort's shortcuts.vdf entries (same SteamOS build and arm64 beta client as the dev Frame; IDs correct; file written before Steam starts): Play → console_log `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` (= "Game configuration unavailable", Steam treats the id as a store app). Cause unknown; agent v42/43 diagnostics: `launch` returns `steam` (started / error + code / silent from console_log), `collect_diag` adds `steam_library` (real Steam dir, beta, Steam start vs vdf write time, entries per account, devkit games) + `steam-console.txt` (incl. Steam's `logs/shortcuts.previous.txt` if present; steamclient.so has "LoadShortcuts: rejecting attempt to load shortcuts: invalid account ID"). **Fallback (agent v43):** when Play gets AppError_9 the agent registers the game through Steam's devkit interface (what Valve's Devkit Management Tool does, MIT: `devkit-1 steam://devkit-1/<~/.steam/steam.token>/create-shortcut?response=<file>&gameid=<id>&directory=~/devkit-game` written to ~/.steam/steam.pipe; answer file / `.error`; `~/devkit-game/<id>/launch.sh` = link to the game's launch.sh, `<id>-argv.json` ["launch.sh"] (relative to the folder), `<id>-settings.json` {steam_play 0, compat_tool ""}). Steam adds it live (no restart), picks its own appid (read back from shortcuts.vdf by DevkitGameID), shows it as a normal non-Steam game named "Devkit Game: <id>" (OpenVR 0, but VR works: owner-verified 2026-10-04), art copied to grid/<appid>*. Ids: letter first, then letters/digits/_ only (spaces, '-', leading digit → "missing/invalid arguments"). Later Plays use the devkit entry; uninstall (`devkit_unregister`, `delete-shortcut` live) and purge remove it. Verified on the dev Frame: register/launch/unregister; the AppError_9 trigger itself only in unit tests.
+**Steam library failures (GitHub #21/#30):** on some Frames Steam never loads FramePort's shortcuts.vdf entries (same SteamOS build and arm64 beta client as the dev Frame; IDs correct; file written before Steam starts): Play → console_log `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` (= "Game configuration unavailable", Steam treats the id as a store app). Cause unknown; agent v42/43 diagnostics: `launch` returns `steam` (started / error + code / silent from console_log), `collect_diag` adds `steam_library` (real Steam dir, beta, Steam start vs vdf write time, entries per account, devkit games) + `steam-console.txt` (incl. Steam's `logs/shortcuts.previous.txt` if present; steamclient.so has "LoadShortcuts: rejecting attempt to load shortcuts: invalid account ID"). **Fallback (agent v43):** when Play gets AppError_9 the agent registers the game through Steam's devkit interface (what Valve's Devkit Management Tool does, MIT: `devkit-1 steam://devkit-1/<~/.steam/steam.token>/create-shortcut?response=<file>&gameid=<id>&directory=~/devkit-game` written to ~/.steam/steam.pipe; answer file / `.error`; `~/devkit-game/<id>/launch.sh` = link to the game's launch.sh, `<id>-argv.json` ["launch.sh"] (relative to the folder), `<id>-settings.json` {steam_play 0, compat_tool ""}). Steam adds it live (no restart), picks its own appid (read back from shortcuts.vdf by DevkitGameID), shows it as a normal non-Steam game named "Devkit Game: <id>" (OpenVR 0, but VR works: owner-verified 2026-10-04), art copied to grid/<appid>*. Ids: letter first, then letters/digits/_ only (spaces, '-', leading digit → "missing/invalid arguments"). Later Plays use the devkit entry; uninstall (`devkit_unregister`, `delete-shortcut` live) and purge remove it. Verified on the dev Frame: register/launch/unregister; the AppError_9 trigger itself only in unit tests. GitHub #42 (two Steam accounts, neither MostRecent): Steam rewrote the active account's shortcuts.vdf without FramePort's entries right after starting, and added the devkit entry live without saving it, so `devkit_appid` (vdf only) failed ("Steam added the devkit entry but didn't save it"); agent v55 `devkit_appid_from_log` reads Steam's `sanitize shortcut app id "~/devkit-game/<id>/launch.sh": replacing 0 with N` console line. GitHub #41 (one account): same Steam behaviour, and every install restarts Steam, which forgets the never-saved devkit entry. Agent v56: the log fallback reads only the current session's console_log.txt; Play re-registers a devkit entry that gets AppError_9; art updates also write the devkit entry's grid art (`copy_grid_art`). Open: why some Frames' Steam never loads or saves shortcuts.vdf (single account too).
+**Exit game (GitHub #36, 2026-10-04):** `Apps.TerminateApp` (what Exit game calls; reachable for tests through Steam's CEF devtools on 127.0.0.1:8080, SharedJSContext, `Runtime.evaluate` — a stdlib websocket client is enough) closed both a normal shortcut and a devkit entry on the dev Frame within 1-3 s. SIGTERM to Steam's `reaper` alone left launch.sh + Lepton (setsid) + the container running (an earlier headset launch ran on for 87 min); SIGTERM to launch.sh cleans up in ~4 s. Agent v44: launch.sh's 2 s loop ends the game when its parent (the reaper) is gone; `upgrade_launchers` (from ensure_host_fixes) adds that to existing launchers in place. Which in-headset exit path fails is still unknown. Screenshots on the Frame: all under SteamVR's appid 250820 (`760/remote/250820/screenshots`, screenshots.vdf has creation time, no game).
+**SteamVR dashboard at game start (2026-10-04):** the dashboard (Resume game / controller / VR options) was open whenever a FramePort game started (also over Lepton's 2D launcher). Steam's UI exposes `SteamClient.OpenVR.VROverlay.{IsDashboardVisible,HideDashboard,ShowDashboard}` (CEF devtools, `steam_js` in the agent). Agent v44: launch.sh starts `_dashboard_worker` (waits for FrameBridge's first `pacing:` line in launch.log, then hides a visible dashboard for 25 s, at most 3 times; log `<base>/dashboard.log`; opt out with env FRAMEPORT_KEEP_DASHBOARD=1). Verified on the dev Frame (dashboard shown → 4XVR launched via Steam → hidden ~5 s after the first frames); not yet seen in the headset. **Headset (ITR2, 2026-10-05): too late** — Steam shows its frame menu (`valve.steam.gamepadui.frame.menu`, vrwebhelper_systemui.txt `[PooledPopups] Showing`) ~0.3 s after the game's first submitted frame (FrameBridge `new layer:`), but the first `pacing:` summary comes ~8 s later; the owner had pressed Resume (`[HideDashboard] return_to_game`) before the worker looked. Agent v52: watches from the first `new layer:` line (incremental log reads, 0.5 s polls, 30 s window). Agent v59: watches 120 s and hides up to 10 times (the menu came back after 30 s in the owner's sessions). 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).
+**Issue triage round (2026-10-06, owner's headset):** vibration in OVRPlugin games = 2 s vibrations updated per frame and
+stopped with amplitude 0; FrameBridge turns amplitude 0 into xrStopHapticFeedback (else each buzz ran 2 s), haptic_fix
+uses the envelope RMS (was its peak), per-game `haptic_scale` → Creed/The Boys/Jurassic World fine. Lambda1VR (TBXR):
+loader named by Build.MANUFACTURER (`frame.tbxr_vendor`), no graphics extension enabled (FrameBridge adds
+XR_KHR_opengl_es_enable + asks for the requirements on -50), always multisampled render-to-texture (GL shim gives
+single-sampled stand-ins when GL_EXT_multisampled_render_to_texture is hidden) + its xash/ data → works. Jurassic World:
+`frame.vrapi_stub`. Metro Awakening: contributor's vkshim fixes + hide_space_warp + no VALVE_rpo (jumping polygons like
+ITR2). Pinball FX VR: hide_space_warp (stutters). Eleven: a Meta online request fails after platform init → needs Meta
+services. Star Wars Tales: top half black + freeze after loading; ruled out: asset-file paks (never requested), Valve
+foveation (off: no change), GL errors (MESA_DEBUG=1: none), EGL_BAD_ACCESS once in OVRPlugin init (harmless); the game's
+eye image reads back black. BlazeRush: VrApi bridge exports + ovr*_ToString stubs + avatar stub get it to the menu room
+at 72 fps, full input reaches it (diagnostics `input 5s`: Touch type only, sticks 1.0, buttons, poses 0x8f), but the room
+draws no controllers and ignores input; avatar loader forced to its "Failed" path (no logged-in user) changed nothing.
+`frame.ovr_trace` can't trace Unity games (P/Invoke dlsym; nothing imports ovr_*). Headless: the VrApi bridge's 30 s
+head-pose deadline ends VR mode without a worn headset (not a game bug).
 **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.

@@ -507,6 +617,40 @@ Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
 layers, depth, pacing ruled out. Sniper Elite VR (DEVICE LOST), Espire 1 (Mesa GL upload crash), HITMAN 3 (freedreno
 crash): use PC versions.

+**Install links / FrameDrop button protocol (2026-10-07, not yet clicked end to end from a browser):** FrameDrop
+(framedropvr.com, a closed-source Windows sideloader) defines "Install with FrameDrop" buttons:
+`https://framedropvr.com/install?manifest=<url>|url=<file>` → that page opens `framedrop://install?…` (1.6 s, else its
+home page); manifest `{"schema":"framedrop.install/v1","name","files":[{"url","sha256"}]}` (name = Steam title; .apk
+or Linux .zip). `deeplink.py` (no Flet) parses framedrop://, frameport:// and the pasted https link, enforces its
+rules (https; http only on loopback; no credentials; no LAN/loopback/link-local IPs, also after DNS and redirects; URL
+ends in a file name), caps manifests at 256 KiB, ignores non-hex sha256 (FrameDrop's own example has a placeholder),
+downloads into `<data>/downloads/<slug>-<hash>/` (OBBs → `obb/` next to the APK, `.part` removed on cancel/mismatch);
+`pipeline.add_from_link` routes APK / Linux / exe and sets `title` + `title_locked` + `link` (a bare file link keeps
+FramePort's title). GUI: `views/link_dialog.py` (always asks first), Add games → "Install from a link…", CLI
+`frameport open-link [--yes --no-install --gui]`. **A `flet build` bundle can't take a URL argument** (the Flutter
+host treats any argv as a developer page URL), so `urlhandler.py` registers a script, not FramePort.exe: Windows
+HKCU `Software\Classes\{framedrop,frameport}` → hidden PowerShell `frameport-link-handler.ps1`; WSL (source runs)
+the same keys → `wsl.exe -d <distro> -e sh frameport-link-handler.sh`; Linux `frameport-links.desktop` +
+`xdg-mime`; macOS unsupported (Apple Events, paste instead). The script drops the link into `<data>/links/*.link`
+and starts FramePort unless `<data>/gui.alive` is < 10 s old (`gui.starting` stops double starts); the GUI's
+`_watch_links` thread touches the heartbeat and opens links (newest window session). Settings → Install links: one
+switch per scheme (`links.framedrop`, `links.frameport`, default on); a scheme another program owns (FrameDrop) is
+only taken with "Use FramePort for these links" (`register([s], force=True)`); off removes only FramePort's own
+registration (`MARK` in the command). Never registered with FRAMEPORT_HOME/FRAMEPORT_NO_LINK_HANDLER (tests,
+screenshots). Same round: files dropped on the Library (`ui/dropped.py`, bundles only like the Files tab), "Add a
+Windows program (.exe)…" (`pipeline.add_windows_exe`: exe in Downloads/home/drive root copied alone into
+`<data>/windows-apps/<slug>/`), patch `device.display_mode` (Automatic / VR / Flat window → `InstallContext.display`,
+`installer.show_window`). FramePort-only manifest extension `"frameport": {"description", "icon"}` (bad values ignored; icon: same URL rules,
+≤2 MiB, Pillow-checked, ≥32 px, saved as PNG in `<data>/downloads/icons/`, shown in the question by asset URL, then
+`sources.apply_custom(pkg, "icon")` unless `.picked` exists; description fills `details.description` only when
+empty). Bare file links get a title guessed from the file name (`title_from_filename`: version/arch dropped, package
+names → last part). Windows test of 0.12.1.dev191 (2026-10-07): a button click opened the dialog; but a click right
+after closing FramePort did nothing (the closed window's heartbeat was < 10 s old) → the handler scripts now wait
+up to 4 s for the link file to be taken before trusting the heartbeat, the window's CLOSE event / atexit delete
+`gui.alive`, and the Windows command runs under `conhost.exe --headless` (plain `-WindowStyle Hidden` flashed a
+console). Screens: `scripts/ui_smoke.py --links --fake-frame --game <pkg>` (tall pages: `--viewport
+1280x7000`; Flutter's popup menu ignores Escape).
+
 ## Releases, CI, GitHub
 Maintainer-only notes (accounts, credentials, key locations) live in the git-ignored `CLAUDE.local.md`.
 Public repo `github.com/spoopyghosty0/frameport` (branch `main`). Push a `v*` tag → CI (`.github/workflows/build.yml`)
@@ -515,6 +659,12 @@ 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.
+- **Upstream trackers:** issues labelled `upstream` (#73 microphone, #74 haptics, #75 VrApi bridge) list our workarounds for OVRPort bugs and how to drop them; check them against OVRPort's latest release before each release.
 - **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
@@ -530,6 +680,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.
@@ -28,6 +28,13 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V
  curved and 360° layers); game settings as simple switches.
 - **Beyond Quest:** Android apps as windows, PC VR via Proton or Revive, Windows (non-VR) games via Proton, a Files
  tab with drag and drop.
+- **Linux apps:** install Linux apps (AppImage, a folder, or a zip/tar archive) on the Frame with a Steam
+  shortcut; arm64 builds run natively on SteamOS, x86_64 builds through Valve's FEX translator.
+- **Install links:** "Install with FrameDrop" buttons on web pages (the one-click protocol of the FrameDrop
+  sideloader) and pasted links open in FramePort, which asks, downloads, adds and installs the build.
+- **Screenshots tab:** the screenshots you took in the headset, sorted by game (matched by play time) and day;
+  view them and download them to your computer.
+- **Live view tab:** watch what the headset shows, with sound, in a browser window on your computer.
 - **Self-updating** releases, redacted diagnostics, one-click problem reports and working-config sharing.

 ## Quick start
@@ -48,14 +55,15 @@ 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

 Typing in VR is painful, so FramePort turns your computer's keyboard into a keyboard for the Frame. Open **Type on
-Frame** (keyboard icon on the sidebar's Frame card, the Steam Frame page, or a game's menu), select a text field in
-the headset and type: searches, logins, chat, in any app, in Steam or on the desktop. Paste longer text to type it in
-one go. Nothing to install: FramePort adds a virtual keyboard on the Frame while the window is open, without root.
+Frame** (its own tab in the sidebar), select a text field in the headset and type: searches, logins, chat, in any
+app, in Steam or on the desktop. Paste longer text to type it in one go. Nothing to install: FramePort adds a virtual
+keyboard on the Frame while the tab is open, without root.

 ![Type on Frame](docs/images/type-on-frame.png)

@@ -63,6 +71,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,12 +1,14 @@
-48a3ecad77ec0f3215b29070e994590eb9579e04d3c88a47f37f306f9aeb01d9  ./arm64-v8a/libfp_langpack.so
-a5b03bb7ae5d953d7ded2bf117b0a19c57fae604f16f54310847f8e89593dde6  ./arm64-v8a/libfp_ovrp.so
-6d2b9f8cea2f2cf33b8ff30d29a2f3d9c4d55549260a867168a24e44abada021  ./arm64-v8a/libfp_vk.so
-8e00552d1ab90f82749db3caad4f773351fa8a28edcc5ea5cbd1b31c434ff32a  ./arm64-v8a/libframe_xrshim.so
-3dfcb0f2bec47857bcecc7261c58e076d872d4649718c40850f29e10c75477dd  ./arm64-v8a/libglshim.so
-507bb1c62168da9335a5883ec264aabed2ce09d04b6524e67be504a273473f8d  ./arm64-v8a/libopenxr_loader_generic.so
+e7554c6343ee2989b0a273ee6230e65c25bfe6499eefd00de19f5f0fee58754f  ./arm64-v8a/libfp_langpack.so
+98a99cefe93079268d9158b23fa8ad5c7ade8e54c0d31526892635625eb3ef04  ./arm64-v8a/libfp_ovrp.so
+40defdaddcda53bd2649eb48076fae1622bfc2bfc88e9e03c94fc8b45af2a4f2  ./arm64-v8a/libfp_ovrtrace.so
+7522a7cfb236e48d3442d418c4820cd37760a9627c6bdef80fb0df82df5fd826  ./arm64-v8a/libfp_vk.so
+383054f8b3b41dde76d062c71856cd3163655e50009c08454bc1793f393ead65  ./arm64-v8a/libfpg.so
+06c8a17b37cb1513fdfeba87ece457a02097bb22dd0a3a3a8719fb8fea16b52a  ./arm64-v8a/libframe_xrshim.so
+9f5ba793d1804728394a8fe9e83028e13f1bc939b558892e7beb5c3662317259  ./arm64-v8a/libglshim.so
+cc5b493cadefe76ad13fd096d3f8494a140ba593e0e1692db12d284bc548c1cf  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
-32525cd0a9ee3d9993d8871cd6905bdcf22cde4f4ba28f5db6434ce7d6554758  ./arm64-v8a/libvrapi.so
-11b7019c6a8d3b2f0f89cf23011f84bbbcb8e907f0935978e1df675339abbb6e  ./armeabi-v7a/libopenxr_loader_generic.so
+aa4dc0020c77e12d41ef6ce80b23ad90c9cb7e882338eddf2261efe8645cf38d  ./arm64-v8a/libvrapi.so
+c10412dd76a65a1d587b7ed226367d1a6f2bec238c733c97ee67eb8870c868e8  ./armeabi-v7a/libopenxr_loader_generic.so
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 1aa733117cf57ccff7cf23f0425dbfd73b0332a3ef1c905ceeca0ccd0449c4e0  ./linux-arm64/XR_APILAYER_FRAMEPORT_timefix.json
 28c2430a02bbd8902c5bfb9562c6fd0e318654f9e05c095bfeb94b0450ab1b07  ./linux-arm64/libxr_frameport_timefix.so
@@ -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,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
@@ -1,15 +1,20 @@
 package: com.StressLevelZero.BONELAB
 title: BONELAB
-status: unsupported
-notes: Crashes while starting its graphics (Vulkan); no fix yet.
-details: SIGSEGV in vkCreateInstance, called from the game's own Vulkan hooks (libSLZQuestNative.so) into code that no
-  longer exists, right after OVRPlugin's pre-initialization creates and destroys an OpenXR instance. Keeping the
-  runtime (vrclient.so) and Steam's Fossilize layer loaded didn't help, so the stale pointer is to memory freed with
-  that first instance.
-tested_version: 1.2974.57485
+status: issues
+notes: Build 1.2068 plays (head tracking and controls work with frame.unity_user_presence); the newer build
+  1.2974 crashes at start (Vulkan), no fix yet.
+details: The game runs (72 fps), but its player body stayed frozen - no head tracking, the controllers stuck to the
+  model, no buttons - although OpenXR input and OVRPlugin's poses were fine. A few seconds after start (when Unity
+  switches XR loaders) OVRPlugin reports the worn headset as not worn (ovrp_GetUserPresent2 -> 0), and BONELAB's
+  Marrow rig only follows the player while Unity's HMD device reports UserPresence (OpenControllerRig checks
+  XRHMD.IsUserPresent every frame). frame.unity_user_presence reports the headset as worn. Build 1.2974 crashed
+  earlier in vkCreateInstance from the game's own Vulkan hooks (libSLZQuestNative.so); not retested.
+tested_version: 1.2068.34555
 engine: Unity
 xr: OpenXR
+frame:
+- frame.unity_user_presence
 verified:
-  date: '2026-10-04'
-updated: '2026-10-04'
+  date: '2026-10-06'
+updated: '2026-10-06'
 source_hint: BONELAB
@@ -0,0 +1,21 @@
+package: com.beatgames.beatsaber.lj369vr
+title: Beat Saber
+status: works
+tested_version: 1.40.8_7379
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 6366a5411328b21de9e2da034af78290882b3c27b7a8f0c61688196e91320055
+  app: 0.11.0
+  overport_cli: 1.2.5
+  frame_build: '20261005.6135832'
+  agent: 56
+  issue: 68
+source_hint: Beat Saber
@@ -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
@@ -0,0 +1,25 @@
+package: com.coatsink.alone
+title: Jurassic World Aftermath Collection
+status: works
+notes: Plays (owner's headset test, 2026-10-06).
+tested_version: v3.16
+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
+- frame.vrapi_stub
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 0566b39d96258fa15eb1b03f27a7ad4219eb5442b0355cd803ed1cf13313f1b3
+  app: 0.12.0
+updated: '2026-10-06'
+min_app: 0.12.0
+source_hint: Jurassic World Aftermath Collection
@@ -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,14 @@
+package: com.drbeef.doom3quest
+title: Doom3Quest
+status: issues
+notes: PDA shows black screen.
+tested_version: 1.4.8
+engine: Other
+xr: OpenXR
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 3c733f5cd08b6fa5d9e2775b1c1aee36b5943518b5d8451ba87e3c59a702afdf
+  app: 0.12.0
+  overport_cli: 1.2.3
+  issue: 77
+source_hint: doom3quest148
@@ -0,0 +1,17 @@
+package: com.drbeef.lambda1vr
+title: Lambda1VR
+status: works
+notes: 'Needs the game data: upload the release''s xash folder to the game''s storage (Files tab) and set --msaa
+  1 in xash/commandline.txt. Owner''s headset test, 2026-10-06.'
+tested_version: 1.7.3
+engine: Other
+xr: OpenXR
+frame:
+- frame.tbxr_vendor
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 10bbccceb8d9a84ff3bcc9a21fd59db52784ff7742998bbe5b30d938dd7b97d2
+  app: 0.12.0
+updated: '2026-10-06'
+min_app: 0.12.0
+source_hint: Lambda1VR
@@ -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
@@ -0,0 +1,19 @@
+package: com.odders.shapeit
+title: BodyCombat
+status: works
+tested_version: 3.0.0
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 1aa5b2a46b25c86db65e3355a575af14b5d4d89b967c812274f181aab2e62b33
+  app: 0.9.1
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 48
+  issue: 56
+source_hint: LES MILLS BODYCOMBAT
@@ -1,11 +1,12 @@
 package: com.playful.LuckysTale
 title: Lucky's Tale
-status: issues
-notes: Runs out of memory within a few minutes and freezes the Frame until the game is killed.
-details: Unity's asset loading thread (Loading.PreloadManager) grows the game's native heap by about 1 GB/s
-  shortly after start (10+ GB plus all swap, then the kernel kills it; perf page-fault profile, 2026-10-04). The text
-  window and the MSAA patch aren't the cause (same with the window off); the OBB is byte-identical to the original.
-  The earlier "headset restarted in a menu" reports (GitHub issue 9) were most likely this. No fix yet.
+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
@@ -14,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
@@ -1,13 +1,18 @@
 package: com.qcxr.qcxr
 title: QuestCraft
-status: issues
-notes: The launcher runs, but Minecraft crashes while starting its graphics (OpenGL error 1282).
+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 left nothing behind ("libjvm.so not found"). With the runtime unpacked there
-  by hand, Java, Fabric and the mods load and Minecraft 1.21.5 starts initializing, then its first texture fails with
-  OpenGL error 1282 in QuestCraft's GL-to-GLES layer on Zink. Leads (2026-10-04) - Android's libEGL ran out of
-  eglGetProcAddress slots for desktop GL functions; LWJGL and JNA natives in the APK don't match the newer files
-  QuestCraft downloads.
+  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
@@ -15,7 +20,9 @@ frame:
 - frame.unity_text_input
 device:
 - device.text_input_window
+lepton_env:
+  LEPTON_ENV_LIBGL_NOERROR: '1'
 verified:
-  date: '2026-10-04'
-updated: '2026-10-04'
+  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,17 @@
+package: com.survios.Creed
+title: Creed
+status: works
+tested_version: CRU-386950
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+verified:
+  date: '2026-10-05'
+  known_good_sha256: c319dd95198a0a96a883aa70f6be9c843da0a265967fa4a7343ce7e6f4bfdc87
+  app: 0.10.0
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 54
+  issue: 60
+source_hint: Creed Rise to Glory
@@ -0,0 +1,26 @@
+package: com.vertigogames.ImpactDevelopment
+title: Metro Awakening
+status: works
+notes: Plays (owner's headset test) with the Vulkan shim's fixes, fragment density maps hidden, space warp off and without
+  Valve's VALVE_rpo layer (random jumping polygons in 3D without the last two, as in Into The Radius 2).
+details: Unreal 5.2 (Vulkan) quit itself (ForceQuit, use_alt), then crashed three times in the Frame's Vulkan driver
+  (Turnip) on things Quest's driver ignores - a depth resolve in a subpass without a depth attachment, image barriers
+  and image views for a missing image. Unreal turns on fragment-density-map foveation because the driver offers the
+  extension and then expects the density map from the headset, which the Frame never provides; vk_hide_fdm hides the
+  extension from the game (Valve's own foveation layer is unaffected).
+tested_version: 1.0-916944
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+use_alt: true
+adapter:
+  vk_spec_fixes: 1
+  vk_hide_fdm: 1
+  hide_space_warp: 1
+lepton_env:
+  VK_INSTANCE_LAYERS: VK_LAYER_VALVE_fdm_injection
+verified:
+  date: '2026-10-06'
+updated: '2026-10-06'
+source_hint: Metro Awakening
@@ -0,0 +1,22 @@
+package: com.zenstudios.PFXVRQuest
+title: Pinball FX VR
+status: issues
+notes: Plays; mixed reality mode not working yet. Space warp off (fewer stutters).
+tested_version: '1.9'
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+adapter:
+  equirect_emul: 1
+  hide_space_warp: 1
+verified:
+  date: '2026-10-05'
+  known_good_sha256: ec5491f6a809c0ee9624e4a43aa0f2c307eb048763492d32a00ff4e0511efe54
+  app: 0.9.1
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 48
+  issue: 50
+updated: '2026-10-06'
+source_hint: Pinball FX VR
@@ -0,0 +1,21 @@
+package: io.ARVORE.TheBoysVR
+title: The Boys VR
+status: works
+notes: Plays with space warp off (owner's headset test, 2026-10-06; black screen reported before).
+tested_version: 1.1.0.345
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+  hide_space_warp: 1
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 5df46b1771611c607229ee59298d983a4d78a57591d4864a02da2df5d2b6f97b
+  app: 0.12.0
+updated: '2026-10-06'
+min_app: 0.12.0
+source_hint: The Boys
@@ -3,13 +3,18 @@ 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). The right eye jitters during races.'
+  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).
+  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
@@ -20,5 +25,5 @@ device:
 - device.text_input_window
 verified:
  date: '2026-10-04'
-updated: '2026-10-04'
+updated: '2026-10-05'
 source_hint: WiiCompiled
@@ -0,0 +1,18 @@
+package: ru.targem.blazerush
+title: BlazeRush
+status: unsupported
+notes: Starts and reaches the menu room, but the room shows no controllers and ignores all input (it all reaches
+  the game); no fix yet.
+tested_version: 1.0.349
+engine: Other
+xr: VrApi
+frame:
+- frame.vrapi_bridge
+- frame.avatar_stub
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 7cbd5d4252788ccd3c95b5c1841dcc798ea029d687938c024e33bd698ba17671
+  app: 0.12.0
+updated: '2026-10-06'
+min_app: 0.12.0
+source_hint: BlazeRush
@@ -8,13 +8,28 @@ signatures:
    severity: fatal
    diagnosis: Lepton found no activity with category LAUNCHER.
    suggest: [frame.launcher]
+  - id: linux-x86-no-fex
+    pattern: '(cannot execute binary file: Exec format error|exec format error)'
+    severity: fatal
+    diagnosis: An x86_64 Linux program was started directly; the Frame's arm64 CPU needs FEX (x86 translation) for it. Reinstall the app with FramePort 0.12 or newer, which installs FEX and starts the program through it.
+    suggest: []
  - id: no-arm64
    pattern: 'INSTALL_FAILED_NO_MATCHING_ABIS'
    severity: fatal
    diagnosis: 32-bit-only APK. The Steam Frame has no AArch32; this cannot run. Use the PC (Rift) version via Revive.
    suggest: []
+  - id: 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)'
+    pattern: '(UnsatisfiedLinkError|cannot locate symbol) .*"?(ovr_[A-Za-z0-9_]+|ovr[A-Z][A-Za-z0-9]*_ToString)'
    severity: fatal
    diagnosis: The game imports Meta platform functions overport's loader lacks.
    suggest: [frame.ovrstubs, frame.ovrplatformcompat]
@@ -81,6 +96,12 @@ signatures:
      harmless (Meta's OVRPlugin suggests plain Touch too); a game that suggests only these gets them again as Touch
      (profile_remap, on by default; log "controller profile ... -> oculus/touch_controller").
    suggest: []
+  - id: input-call-failed
+    pattern: 'input_diag: unsupported: (xrStringToPath|xrCreateAction|xrAttachSessionActionSets|xrSyncActions) ->'
+    severity: warning
+    diagnosis: The runtime refused one of the game's controller-input calls (logged by input_diag; the line names the
+      call, the result and the argument), so controls set up through it don't work.
+    suggest: []
  - id: gl-shader-failed
    pattern: 'GLShim\s*: SHADER COMPILE FAILED|#extension directive is not allowed in the middle|could not implicitly convert operands'
    severity: error
@@ -91,8 +112,37 @@ signatures:
    severity: error
    diagnosis: The game submits a VrApi layer type the bridge can't show; whole frames are dropped (black screen).
    suggest: []
+  - id: graphics-requirements-missing
+    pattern: '(XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING|Failed to create XR session: -50\b|xrCreateSession[^\n]*-50\b)'
+    severity: fatal
+    diagnosis: The game creates its OpenXR session without asking for the graphics requirements first; Meta's runtime
+      allows that, the Frame's doesn't (e.g. Lambda1VR). Current FrameBridge builds ask on the game's behalf and retry -
+      rebuild the game.
+    suggest: [frame.adapter]
+    supersedes: [native-crash]
+  - id: avatar-driver-missing
+    pattern: 'OVRAvatar-Loader: DisplayErrorAndExit'
+    severity: fatal
+    diagnosis: Meta's avatar library can't find its driver (it needs Meta's Horizon app) and stops the game (e.g.
+      BlazeRush). Replace it with a do-nothing library; the game runs without Meta avatars.
+    suggest: [frame.avatar_stub]
+    supersedes: [native-crash, java-crash]
+  - id: vrapi-symbol-missing
+    pattern: 'cannot locate symbol "vrapi_\w+"'
+    severity: fatal
+    diagnosis: The game needs a VrApi function its libvrapi.so doesn't have (e.g. BlazeRush before the bridge gained
+      vrapi_PollEvent). Rebuild with the current FramePort; if it persists, report the function name.
+    suggest: []
+    supersedes: [native-crash, java-crash, dlopen-failed]
+  - id: vrapi-before-init
+    pattern: 'VrApiLoader: vrapi_\w+ was called before vrapi_Initialize'
+    severity: fatal
+    diagnosis: Meta's VrApi loader stopped the game. Its OVRPlugin runs on OpenXR but still calls a VrApi function
+      without starting VrApi (e.g. Jurassic World Aftermath); the VrApi bridge can't stand in for this loader.
+    suggest: [frame.vrapi_stub]
+    supersedes: [direct-vrapi, native-crash]
  - id: direct-vrapi
-    pattern: 'vrapi_Initialize|VrApi.*not supported|libvrapi\.so.*(not found|failed)'
+    pattern: '(?<!called before )vrapi_Initialize|VrApi.*not supported|libvrapi\.so.*(not found|failed)'
    severity: warning
    diagnosis: The engine talks to VrApi directly; it needs the VrApi bridge.
    suggest: [frame.vrapi_bridge]
@@ -125,6 +175,18 @@ signatures:
    severity: warning
    diagnosis: Runtime lacks timespec time conversion (emulated by the current adapter build).
    suggest: [frame.adapter]
+  - id: unreal-vulkan-driver-crash
+    pattern: '#00 pc [^\n]*/vulkan\.freedreno\.so[\s\S]{0,3000}?lib(Unreal|UE4)\.so'
+    severity: fatal
+    diagnosis: The Frame's Vulkan driver crashed on a call from Unreal. Unreal 5 passes things Quest's driver ignores - a depth resolve in a subpass without a depth attachment (fixed by the Vulkan shim), image barriers and image views for a missing image when it expects fragment density maps (foveation) from the headset (e.g. Metro Awakening).
+    suggest: [frame.vk_sanitize, adapter.vk_spec_fixes, adapter.vk_hide_fdm]
+    supersedes: [native-crash]
+  - id: unreal-fdm-missing
+    pattern: 'vk shim: left out \d+ image barrier\(s\) without an image \(first: layout \d+ -> 1000218000'
+    unless: 'vk shim: fragment density map extensions hidden'
+    severity: warning
+    diagnosis: Unreal expects fragment density maps (foveation) from the headset, which the Frame doesn't provide; its image views for them crash the Frame's driver a few seconds later (e.g. Metro Awakening).
+    suggest: [adapter.vk_hide_fdm]
  - id: fossilize-renderpass
    pattern: '#0\d pc [^\n]*libVkLayer_fossilize\.so[\s\S]{0,4000}?FVulkanRenderPass::FVulkanRenderPass'
    severity: fatal
@@ -149,6 +211,14 @@ signatures:
    diagnosis: overport's OpenXR dispatcher aborted on a swapchain larger than 4096 px (video players, big textures).
    suggest: [frame.swapchain_limit]
    supersedes: [native-crash]
+  - id: ovr-microphone-crash
+    pattern: 'ovr_Microphone_GetOutputBufferMaxSize\+'
+    severity: fatal
+    diagnosis: The game asked OVRPort's Meta platform library for the microphone buffer size before starting the
+      microphone, and the library read the not-yet-opened audio stream (SIGSEGV in libaaudio.so, e.g. Unreal's Oculus
+      voice chat a few seconds after the logo).
+    suggest: [frame.ovr_microphone]
+    supersedes: [native-crash]
  - id: native-crash
    pattern: 'Fatal signal (\d+) \(SIG[A-Z]+\)'
    severity: fatal
@@ -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**.
@@ -55,6 +55,10 @@
 ## Graphics stack
 - Vulkan: freedreno (Mesa Turnip); Valve injects `VK_LAYER_VALVE_rpo` and `VALVE_fdm_injection` via
  VK_INSTANCE_LAYERS (set `VK_INSTANCE_LAYERS=""` through `device.lepton_env` to test without them).
+  The FDM layer follows each eye's gaze; one-eye jitter in some games (GitHub #69) is fixed per game with
+  `device.foveation`: `fixed` = `FDM_DEBUG=disable_offsets`, `off` = `VK_INSTANCE_LAYERS=""`. Lepton passes `FDM`,
+  `FDM_DEBUG`, `FOVE_LEVEL` and `FDM_SWAPCHAIN_SIZE` through to the container (liblepton/mounting.sh PASSTHROUGH_VARS);
+  the layers are chosen on the host, so setting them inside the game does nothing.
 - GL ES: Zink (Mesa GL on Vulkan). Strict GLSL (see PLAYBOOK) and occasional `DEVICE LOST` with MSAA render-to-texture.

 ## Proton / Windows games (surveyed 2026-09-29; running a Rift game under it not yet verified)
@@ -65,6 +69,17 @@
  SteamLinuxRuntime_4). None are installed by default.
 - `steam -ifrunning steam://install/<appid>` only opens a confirmation dialog in the headset. The agent's unattended
  mode writes an appmanifest stub (StateFlags 1026, installdir from appinfo) and restarts Steam, which then downloads it.
+- **x86_64 Linux apps (agent v61; verified on the device 2026-10-07: an x86_64 glibc test program installed + launch test RUNNING, "machine=x86_64 glibc=2.41"):**
+  FEX is Steam app 3127680 (`fex`, installs as `common/FEX-Emu`, ~6 MB, 21 s via the appmanifest-stub path:
+  `install_proton` / `proton_status` with `kind: linux_x86`). Its toolmanifest commandline is
+  `/fex-compat-tool %verb% --`, **no** require_tool_appid: it does not use the Steam Linux Runtime. fex-compat-tool
+  (Python) runs `<FEX-Emu>/usr/bin/FEX` with RootFS `/usr/share/guestos/fex-mesa` (part of the SteamOS image: an
+  x86 Arch-style root with glibc 2.41, Mesa, graphics_provider.json for x86_64 + i386), emulates x86_64 and i386
+  (emulator.json), honours `STEAM_FEX_TSOENABLED`, `STEAM_FEX_MULTIBLOCK`, `STEAM_COMPAT_FEX_CONFIG`, sets
+  `tu_override_uncached_as_cache_coherent=true` and logs to `/tmp/fex-compat-tool-<pid>.log`. It **exits 1 ("No compat
+  data path?") without `STEAM_COMPAT_DATA_PATH`** (keeps Config.json/AppConfig/Server/Telemetry in `<it>/fex-emu/`):
+  the Linux launcher exports `<base>/compatdata`. Version seen: FEX-2607-76-g37265b1. ldd can't read x86 programs,
+  so the missing-library check is skipped for them; an x86_64 AppImage is extracted through the same chain.
 - The command Steam runs is built from each tool's `toolmanifest.vdf` (`commandline`, `require_tool_appid`):
  `<SLR4-arm64>/_v2-entry-point --verb=waitforexitandrun -- <Proton>/proton waitforexitandrun <exe>`.
 - Proton sets up VR (vrclient/wineopenxr registry) only when `SteamGameId` is set (steam_helper `setup_vr_registry`).
@@ -106,6 +121,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,35 +7,49 @@ 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 | Quest | ✅ Works |  |
 | Beat Saber (co-existence build) | Quest | ✅ Works |  |
 | Blade & Sorcery: Nomad | Quest | ✅ Works |  |
+| BodyCombat | Quest | ✅ Works |  |
 | Carve Snowboarding | Quest | ✅ Works |  |
 | Cook-Out | Quest | ✅ Works |  |
+| Creed | Quest | ✅ Works |  |
 | Demeter | Quest | ✅ Works |  |
 | Dinosaur Island | Quest | ✅ Works |  |
 | 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 |  |
+| Jurassic World Aftermath Collection | Quest | ✅ Works |  |
 | Keep Talking and Nobody Explodes | Quest | ✅ Works |  |
+| Lambda1VR | 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 |  |
+| Metro Awakening | 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 |  |
@@ -44,24 +58,27 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Stremio | Quest | ✅ Works |  |
 | SUPERHOT VR | PC VR | ✅ Works |  |
 | SUPERHOT VR | Quest | ✅ Works |  |
+| TetrisEffect | Quest | ✅ Works |  |
+| The Boys VR | 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 | Runs out of memory within a few minutes and freezes the Frame until the game is killed. |
+| BONELAB | Quest | ⚠️ Works with issues | Build 1.2068 plays (head tracking and controls work with frame.unity_user_presence); the newer build 1.2974 crashes at start (Vulkan), no fix yet. |
 | 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). |
-| QuestCraft | Quest | ⚠️ Works with issues | The launcher runs, but Minecraft crashes while starting its graphics (OpenGL error 1282). |
+| Pinball FX VR | Quest | ⚠️ Works with issues | Plays; mixed reality mode not working yet. |
 | 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. |
+| BlazeRush | Quest | ❌ Doesn't run | Starts and reaches the menu room, but the room shows no controllers and ignores all input (it all reaches the game); 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. |
 | Journey of the Gods | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |
@@ -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
@@ -77,7 +91,39 @@ which would end Desktop Mode). This is new: please report anything odd with **Re
  mixed-reality options in plain words, only those that matter for the game. Changes are kept with the game and,
  when it's installed, used the next time it starts.
 - Ordinary Android apps (no VR) are installed unchanged and shown as a flat window in the headset. Android's
-  back/home/recents buttons are hidden by default (patch **Hide Android's navigation bar**).
+  back/home/recents buttons are hidden by default (patch **Hide Android's navigation bar**). If FramePort guesses
+  wrong (a phone app shows nothing in the headset, or a VR app opens as a flat window), choose **VR** or **Flat
+  window** under **Show as VR or as a flat window** in the game's **Customize** section, then **Update on Frame**.
+- **Add games → Add a Windows program (.exe)…** adds a single Windows program; the Frame runs it through Proton (as a
+  window unless it is a VR game). A program sitting in Downloads, the home folder or a drive root is copied on its
+  own first, so the install doesn't upload everything next to it.
+- In the packaged app you can also **drag files onto the Library**: APKs, Linux apps (AppImage, `.zip`/`.tar.gz`),
+  Windows programs (`.exe`), folders, or a FrameDrop manifest (`.json`).
+
+### Install links ("Install with FrameDrop" buttons)
+
+Some developers put an **Install with FrameDrop** button on their site (the one-click protocol of the FrameDrop
+sideloader, documented at framedropvr.com/docs). FramePort understands the same links:
+
+- **Clicking a button** opens FramePort (or the window that's already open) on Windows and Linux. FramePort shows
+  the title, the files, their size and whether a checksum is given, and asks before it downloads anything. Then it
+  downloads the build, adds it to your library and starts the usual install on the Frame. If no Frame is connected,
+  the game is added now and installs once the Frame is back.
+- **Add games → Install from a link…** takes the button's address (right-click → Copy link), a `framedrop://` or
+  `frameport://` link, a manifest (`.json`) or a direct link to an APK, a Linux build or a Windows program. Use it on
+  macOS, where web pages can't hand links to FramePort yet.
+- **Settings → Install links** has one switch for `framedrop://` links (the buttons) and one for FramePort's own
+  `frameport://` links. Both are on by default. If FrameDrop is installed too and already opens `framedrop://`
+  links, FramePort leaves them to it; **Use FramePort for these links** takes them over (turn the switch off to give
+  them back).
+- **For developers:** a FrameDrop manifest works as it is
+  (`{"schema": "framedrop.install/v1", "name": "…", "files": [{"url": "https://…", "sha256": "…"}]}`). FramePort
+  also reads an optional `"frameport": {"description": "…", "icon": "https://….png"}` object (FrameDrop ignores
+  it): the install question then shows the icon and description, and they become the game's icon and "About this
+  game" text when no store has them. Without a manifest (a bare file link) FramePort guesses the title from the
+  file name and replaces it with the app's own name once it's downloaded.
+- Only `https://` links to public servers are used (plain `http://` only on this PC, for testing); links with a
+  user name or password, or pointing into your local network, are refused. Only install from sites you trust.

 ![Game page](images/game.png)

@@ -88,10 +134,10 @@ reality), showing only what matters for that game. Changes are kept with the gam

 ## Typing on the Frame

- **Type on Frame** (Steam Frame page, a game's menu, or the keyboard icon on the sidebar's Frame card): while the
-  window is open, this computer's keyboard works as a keyboard plugged into the Frame. Select a text field in the
-  headset (in an app, Steam or the desktop) and type; Esc and shortcuts go to the Frame too. Paste longer text into
-  the box to type it in one go (US keyboard layout). Click **Done** to disconnect.
+- **Type on Frame** (its own tab in the sidebar; also on the Steam Frame page and in a game's menu): while the tab is
+  open, this computer's keyboard works as a keyboard plugged into the Frame. Select a text field in the headset (in
+  an app, Steam or the desktop) and type; Esc and shortcuts go to the Frame too. Paste longer text into the box to
+  type it in one go (US keyboard layout). Opening another tab disconnects the keyboard.
 - **Steam's on-screen keyboard** opens for text fields of apps shown as a window (2D apps, and VR apps with
  **Show the app's Android window**). Steam lists that window as **Gamescope** (the Frame's display compositor);
  leave it open: it's what receives the typing, the VR view isn't affected.
@@ -101,6 +147,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 +162,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 +188,32 @@ 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
+
+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…** 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** run through **FEX**, Valve's x86 translator, with the x86 system libraries SteamOS ships for it
+  (the way Steam on the Frame runs x86 Linux games). The first install of one installs FEX on the Frame (Steam
+  restarts once and downloads it, a few MB). They run slower than arm64 builds: when an app offers both, FramePort picks the arm64 one. The game
+  page shows which CPU a build is for.
+- The app must bring the libraries SteamOS doesn't have (checked for arm64 builds; x86_64 builds use FEX's x86
+  system, which has glibc and Mesa, and aren't checked ahead). If some are missing, the install reports them and the game
+  page lists them: look for a build that includes them.
+- 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,11 +243,13 @@ 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 a Linux app, arm64 or x86_64 (AppImage, folder or archive) |
 | `recipe <game> --enable/--disable <patch>` | change a game's patches (`patches` lists them all) |
 | `build <game>` / `install <game>` / `test <game>` | build, install on the Frame (`--to pc` for PC VR on this PC), launch test |
 | `frame discover` / `frame connect` / `frame info` | find, pair with and describe the Frame |
 | `frame send` / `frame storage` / `frame cleanup` | copy files to the Frame, show where they go, free space |
 | `tools status` / `tools install` | the tools FramePort downloads |
+| `open-link "<link>"` | install from an "Install with FrameDrop" button's address or a manifest/APK/zip link (`--yes`, `--no-install`) |
 | `diag report <game>` / `share-recipe <game>` | report a problem / share a working recipe |
 | `update` | update FramePort |

@@ -13,11 +13,23 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 ## Startup failures (visible in launch.log)
 | Symptom | Cause | Fix |
 |---|---|---|
+| One eye (usually the right) shimmers or jitters in the 3D view while menus and panels look steady; pacing is clean (GitHub #69, e.g. RTCWQuest, Moss) | Valve's eye-tracked foveation layer (`VALVE_fdm_injection`) moves its low-density regions with each eye's gaze, and the right eye's gaze filter restarts often (`CEyePoseUKF R: Large dt … Bootstrapped` in `~/.local/share/Steam/logs/eyetracking.txt`) | Customize → "Eye-tracked foveation (Valve)" (`device.foveation`): **Fixed** (`FDM_DEBUG=disable_offsets`, keeps the GPU saving) or **Off** (`VK_INSTANCE_LAYERS=""`); catalog field `foveation:` |
+| A Unity OpenXR game closes right after the OpenXR instance is created: `F VrApiLoader: vrapi_SetPropertyInt was called before vrapi_Initialize()!`, SIGABRT on UnityMain (GitHub #62, Jurassic World Aftermath) | the APK still ships Meta's VrApi loader; OVRPlugin (1.89, on OpenXR) calls it without starting VrApi and Meta's loader aborts. The VrApi bridge can't replace it (39 of the loader's 114 functions: OVRPlugin wouldn't link) | `frame.vrapi_stub` (same exports, each returns 0); triage `vrapi-before-init` |
+| A VrApi game exits at once: `UnsatisfiedLinkError … dlopen failed: cannot locate symbol "vrapi_PollEvent"` (GitHub #57, BlazeRush) | the engine imports a VrApi function the VrApi bridge didn't implement | the bridge has `vrapi_PollEvent`, `RecenterPose`, `SetDisplayRefreshRate`, `GetSystemPropertyFloatArray` (rebuild the game); the static check "VrApi functions resolvable" names any other missing one; triage `vrapi-symbol-missing` |
+| A Team Beef port (Lambda1VR, RTCWQuest, …) exits at once: `UnsatisfiedLinkError: dlopen failed: library "libopenxr_loader_valve.so" not found` (GitHub #59) | TBXR loads `openxr_loader_<Build.MANUFACTURER>` (Lepton: valve) and takes the Meta path only when `strstr(OPENXR_HMD, "meta")` matches, else Pico's | `frame.tbxr_vendor` (empty `libopenxr_loader_valve.so` + the "meta" literal → "alve"). Game data (`xash/`, …) goes to /sdcard: upload it with the Files tab to the game's storage. Black eyes with `TBXR: Incomplete frame buffer object: GL_FRAMEBUFFER_INCOMPLETE_MULTISAMPLE`: TBXR always uses multisampled render-to-texture (even `--msaa 1`); `frame.tbxr_vendor` links the GL shim, which hands it single-sampled versions (log `GL shim: multisampled render-to-texture … drawn single-sampled`) |
+| Logos and a loading animation, then black (no crash, frames keep coming) in a game whose OBB folder has extra `*.pak` files (GitHub #61, Star Wars: Tales from the Galaxy's Edge: seasons + Wwise banks) | the game asks Meta's platform for these asset files (`ovr_AssetFile_GetList` / `DownloadById`); OVRPort's loader doesn't know them, so the content never "arrives" | `frame.asset_files` (native/langpack lists the data's `*.pak` as installed `default` assets, IAP `free`, and answers DownloadById at once with the path; off: env FRAMEPORT_ASSET_FILES=0) |
+| `cannot locate symbol "ovrPeerConnectionState_ToString"` (or another `ovr<Enum>_ToString`) at start (BlazeRush, GitHub #57) | OVRPort's platform loader lacks several Platform SDK enum helpers | `frame.ovrstubs` now stubs them too; `*_ToString` stubs return "" (not NULL) |
+| Exits right after the OpenXR instance is created: `Failed to create XR session: -50` (`XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING`, Lambda1VR) | the game skips `xrGet*GraphicsRequirementsKHR`; Meta's runtime tolerates it, SteamVR's doesn't. Lambda1VR's TBXR doesn't even enable `XR_KHR_opengl_es_enable` (only `XR_EXT_local_floor`) | FrameBridge adds `XR_KHR_opengl_es_enable` when an app enables no graphics API extension, asks for the requirements on the game's behalf and retries xrCreateSession once (logs `added XR_KHR_opengl_es_enable …`, `the app skipped …; asked for it`; every launch logs the final extension list `xrCreateInstance with N extension(s)`); triage `graphics-requirements-missing`. Verified headless: Lambda1VR runs at 72 fps |
+| Exits at start: `OVRAvatar-Loader: DisplayErrorAndExit: Failed to launch SystemActivities` after `ovrAvatar_Initialize: Failed to load AvatarSDK driver` (BlazeRush, GitHub #57) | Meta's avatar loader needs Horizon; it then tries Meta's error screen and aborts | `frame.avatar_stub` (same exports, do nothing); triage `avatar-driver-missing`. Games that ship the library but don't start avatars at launch (Lucky's Tale, BattleSisters, Arcsmith) don't need it |
+| Controller vibrations much stronger than on a Quest (The Boys VR, Jurassic World, BONELAB, …) | OVRPlugin games send amplitude envelopes; `haptic_fix` turned each into one vibration at the envelope's *peak* for its whole duration (a short fading pulse became a long full-strength buzz) | `haptic_fix` now uses the envelope's RMS; Game settings → "Vibration strength" (`haptic_scale`, 0-1) scales every vibration in FrameBridge; launch.log shows the first requests (`haptic: …`). OVRPlugin stops a vibration with amplitude 0 (2 s duration): FrameBridge turns that into xrStopHapticFeedback (without it the last buzz ran its full 2 s) |
 | Every game suddenly fails to start: `crun: create keyring …: Disk quota exceeded`, `is not a running context` | rootless podman leaked a kernel keyring per launch; 200-key quota exhausted | `keyring = false` in `~/.config/containers/containers.conf` (FramePort agent does it), then reboot the Frame once |
 | A Unity app's text field shows a caret for a moment and loses focus; no keyboard appears (e.g. Stremio VR login) | Unity's TMP_InputField/InputField wait for Android's on-screen keyboard and close themselves without one (Lepton has none); headless VR apps also have no focused Android window, so no key press reaches them | `frame.unity_text_input` (Cpp2IL finds `TouchScreenKeyboardShouldBeUsed`/`isKeyboardUsingEvents`, rewritten to false/true) + `device.text_input_window` (lepton-show-flatscreen: Steam's keyboard and Type on Frame work) |
+| Play gives Steam's "Game configuration unavailable"; Steam's console_log: `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` | this Frame's Steam never loaded FramePort's shortcuts.vdf entry (it treats the id as a store app); cause unknown (GitHub #21/#30) | automatic since agent v43: Play registers the game through Steam's devkit interface ("Devkit Game: …", `devkit_register`) and starts that; uninstall removes it. Agent v58: a devkit entry Steam forgot after a restart is added again live on Play (no NOT_IN_LIBRARY → no Steam restart), and installs/art updates of devkit games only copy art (no Steam restart, GitHub #41) |
+| 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) |
+| A Linux app exits at once: `cannot execute binary file: Exec format error` in launch.log | an x86_64 program started directly (installed before FramePort ran x86 builds through FEX, or by hand) | reinstall it: x86_64 Linux apps install FEX on the Frame and start through it (agent v61, `kind: linux_x86`; FEX also needs `STEAM_COMPAT_DATA_PATH`: "No compat data path?" in launch.log = an agent v60 launcher, reinstall); triage `linux-x86-no-fex`. Prefer an arm64 build when the app offers one |
 | `APP_ACTIVITY is empty`, nothing starts | Manifest has category INFO only; Lepton needs LAUNCHER | `frame.launcher` (automatic) |
 | PC VR game on the Frame shows as a flat window / Revive: `Unable to load LibOVRRT DLL` / `LoaderInstance::CreateInstance chained CreateInstance call failed` | Frame SteamVR runtime rejects OpenXR apiVersion 1.1 (`XR_ERROR_API_VERSION_UNSUPPORTED`), which Proton 11's VR helper requests | `pcvr.xr_timefix` (Frame OpenXR layer, default on): retries xrCreateInstance as 1.0 |
 | Unreal PC VR game on the Frame runs as a flat window although OpenXR works (no `LogHMD` OVRPlugin lines; Unreal logs nothing when it skips the Oculus plugin) / launch.log: `FramePort oculushmd: could not create the OculusHMDConnected event` | UE's OculusHMD (and LibOVR's `ovr_Detect`) only start when the Windows event `OculusHMDConnected` exists and is signalled; on a PC the Oculus service creates it. Revive hooks `OpenEventW` for it, but that relies on Detours patching Wine's (ARM64EC) kernelbase | `pcvr.oculus_unreal` (default for Unreal Rift games; PC VR counterpart of overport's `patch_oculus_unreal`): launch.sh runs the injector through `fp_oculushmd.exe`, which provides the real event until the game exits |
@@ -37,6 +49,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | `ClassNotFoundException com.oculus.os.AnalyticsEvent` → abort | Quest telemetry lookup in Meta XR Audio (Unreal build) or native code | `frame.metaxr_telemetry` + `frame.oculusos` (automatic) |
 | `JNI DETECTED ERROR`, `GetStringUTFChars … NULL` | CheckJNI is on because overport marks the app debuggable | `frame.nodebug` |
 | Unreal game quits a few seconds after start (`System.exit`) | ForceQuit after a failed Quest platform check | alternate build with `patch_remove_unreal_force_quit` (`use_alt`) |
+| Unreal game crashes a few seconds after the logo with no backtrace (Unreal's own signal handler hides it: logcat-crash.log empty, Zygote `exited due to signal 11`); the crashing thread is `GameThread`, pc in `libaaudio.so`, lr `libovrplatformloader.so (ovr_Microphone_GetOutputBufferMaxSize+0x10)`; the last platform call is `ovr_Microphone_Create` (e.g. The Walking Dead: Saints & Sinners Ch. 2) | OVRPort's platform loader opens the microphone's AAudio stream only in `ovr_Microphone_Start`, but `GetOutputBufferMaxSize` reads that stream unchecked; Unreal's Oculus voice asks for the size right after `Create` | `frame.ovr_microphone` (NULL check rewritten in place; size 0 until the microphone starts) |
 | `xrCreateSwapchain` -26 / format unsupported (GLES) | Frame takes only sRGB formats, no MSAA | adapter `swapchain_fix` (default on) |
 | Frames rejected, "Waiting…" forever | a layer uses a failed swapchain or an extension that isn't enabled (e.g. equirect2) | adapter `layer_fix` (default on) |
 | `xrConvert…TimeKHR` FUNCTION_UNSUPPORTED spam; VrApi bridge stalls before recenter | runtime lacks timespec conversion | current adapter emulates it |
@@ -53,13 +66,18 @@ 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` |
 | SDL / LÖVE app crashes at start: `NullPointerException … ClipboardManager.addPrimaryClipChangedListener` in `SDLClipboardHandler.<init>` (e.g. Dramatic Shape) | Lepton's Android has no clipboard service (`service check clipboard`: not found) | `frame.sdl_clipboard` (that call → nops in classes.dex, in place, `apk/dex.py`); reproduced and verified with LÖVE for Android 11.5 |
 | Controllers do nothing (e.g. stuck on a setup screen); log: `xrSuggestInteractionProfileBindings … XR_ERROR_PATH_UNSUPPORTED` | the game only suggests bindings for Meta's newer profiles (Touch Plus / Touch Pro); the Frame's Android runtime knows `oculus/touch_controller`, not those | adapter `profile_remap` (default on): the bindings are suggested again for Touch (log: `controller profile … -> oculus/touch_controller`) |
+| Some buttons do nothing or the wrong thing (e.g. a Quest game's X/Y on the Frame's left controller) | the game binds only Quest Touch and SteamVR maps Touch onto the Frame controllers with its own remap (Touch left X/Y land on the d-pad, right X and Y repeat B), or the runtime rejected a profile or an input call | turn on adapter `input_diag` (diagnostics, off by default; `frameport settings <pkg> input_diag=1`) and look for `input_diag:` lines: `bindings: <profile> accepted` or `unsupported: interaction profile <profile> -> <result>` with the rejected paths, `bindings: /user/hand/<hand> uses <profile>`, `unsupported: function <name>`, `unsupported: xrCreateAction -> <result> (<action>)` |
 | Unity game hangs or the whole Frame restarts (e.g. in a menu); log: `The current MSAA level is 0, but the recommended MSAA level is 4. Switching to the recommended level.` (e.g. Lucky's Tale) | Meta's OVRManager (`useRecommendedMSAALevel`) turns 4x MSAA on at runtime, past QualitySettings; multisampled render-to-texture on GLES/Zink hangs the GPU | `frame.unity_runtime_msaa_off` (Cpp2IL: `OVRDisplay.get_recommendedMSAALevel` → 0) |
 | Unity game: one eye shows only effects or grey, the other is fine (e.g. I Am Cat, Oculus XR Plugin on GLES) | the game's single-pass multiview rendering goes wrong for array slice 1 (the adapter submits both slices correctly) | `frame.unity_multipass` (Cpp2IL: `OculusSettings.GetStereoRenderingMode` → MultiPass); `swap_eyes=1` tells whether the game or the adapter is at fault |
 | Setup/intro loops every launch (Espire 2) | save folders created without write permission | launcher repairs permissions every 2 s (built in) |
@@ -69,6 +87,8 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Symptom | Cause | Fix |
 |---|---|---|
 | 2D Android app: Steam says it's running but nothing shows | Lepton runs apps headless unless the app folder has `lepton-show-flatscreen` | FramePort adds it for apps without VR (agent v28+); reinstall apps installed before |
+| A phone/tablet app shows nothing in the headset, or a VR app opens as a flat window | FramePort's VR/2D guess (`vr_kind`) is wrong for this app | patch `device.display_mode` → **Flat window** or **VR** (Customize → "Show as VR or as a flat window"), then Update on Frame |
+| "Install with FrameDrop" button opens FrameDrop (or nothing) instead of FramePort | another program owns `framedrop://`, or the switch is off, or macOS (Flet can't receive links there) | Settings → Install links → **Use FramePort for these links**; else Add games → Install from a link… (paste the button's address) |
 | 2D Android app: back/home/recents buttons cover the app's own buttons | Android's navigation bar | patch `device.hide_navbar` (on by default for apps without VR) sets `qemu.hw.mainkeys=1`; reinstall to apply |
 | Black screen, audio works, GLES engine with direct VrApi | Mesa rejects Quest-style GLSL | `frame.gl_shim` (logs `GLShim: SHADER COMPILE FAILED` + source lines) |
 | Black screen, audio works, log `Unsupported VrApi layer type N` | bridge drops frames containing that layer | extend the bridge (cylinder=3 is converted to a quad already) |
@@ -83,9 +103,12 @@ 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 |
+| Graphics crash in vkCreateInstance with pc == fault address, from the game's own Vulkan hooks (BONELAB 1.2974 `libSLZQuestNative`) | a pointer into memory freed with OVRPlugin's pre-init OpenXR instance; not the runtime (vrclient.so) or Fossilize being unloaded (keeping both loaded with RTLD_NODELETE didn't help) | unresolved |
+| Unity game shows a picture but the player body is frozen: no head tracking, the controllers stay on the model, no buttons, although OpenXR input works (BONELAB 1.2068, Oculus XR Plugin) | OVRPlugin reports the headset as not worn (`ovrp_GetUserPresent2` → 0) a few seconds after start, and the game's rig only follows a present user (Marrow `XRHMD.IsUserPresent` = Unity's HMD `UserPresence`) | `frame.unity_user_presence` (the Oculus XR Plugin's lookup → `libfp_ovrp.so`, reports present; log `user presence: OVRPlugin 0 …`) |
+| Unreal 5 game crashes at its first render pass, backtrace `vulkan.freedreno.so` ← `libVkLayer_fossilize.so` ← `libfp_vk.so (create_render_pass2)` (Metro Awakening) | a subpass without a depth attachment names a depth/stencil resolve attachment; the Frame's Turnip reads the missing depth attachment (NULL) | the Vulkan shim drops that resolve (always, FramePort after 0.11.0; log `dropped the depth resolve of subpass N (no depth attachment)`); triage `unreal-vulkan-driver-crash` |
+| Unreal 5 game crashes in `vulkan.freedreno.so` called straight from `libUnreal.so` right after its swapchains, or a few seconds into the first frames (Metro Awakening) | Unreal turns on fragment-density-map foveation because Turnip offers VK_EXT_fragment_density_map, then records barriers (to `FRAGMENT_DENSITY_MAP_OPTIMAL`) and image views (2D array R8G8) for a density map the Frame never provides (VK_NULL_HANDLE); Turnip dereferences it | adapter `vk_hide_fdm=1` (the game doesn't see the extension) + `vk_spec_fixes=1` (leaves out null-image barriers, refuses null-image views); triage `unreal-fdm-missing`. Found by disassembling the driver at the crash pc: the struct offsets (0x58 = VkSubpassDescription2, 0x48/0x60 = image barriers, viewType/format in registers) name the call |
 | Own-engine game crashes in `je_free` from its own library on the first frames (Roblox) | the game frees memory it doesn't own; not the Vulkan shim or the format fallback | unsupported |

 ## Debugging techniques that worked
@@ -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
@@ -7,10 +11,10 @@ embeds debug paths (`-g`) and the dex depends on the d8 version, so those differ

 | Dir | Artifact | What / why |
 |---|---|---|
-| `adapter/` | `{arm64-v8a,armeabi-v7a}/libopenxr_loader_generic.so` | **FrameBridge**: replaces overport's generic loader (which is renamed `libopenxr_loader_original.so`) and fixes Steam Frame runtime gaps. Hooks xrCreateInstance, swapchains, xrEndFrame, spaces, xrPollEvent, … everything else is forwarded by `gen_forwarders.py`-generated tail calls. `scene_emu.c` = Meta scene/spatial-entity emulation; `flip_vk.c` = Vulkan blit for VERTICAL_FLIP quads. `session_fixes.c` = per-game session fixes, all off by default and hooked only when on (`layer_debug` diagnostics, `stable_local`, `focus_hold`, aim correction `aim_pitch/aim_yaw/aim_forward`, `refresh_rate`); `layer_emul_gl.c` = `equirect_emul` (GLES sessions only): 360° equirect/equirect2 layers become one adapter projection layer, drawn by a worker thread with its own EGL context shared with the app's: each 360° image is converted to a cube map only when it changes, and the view is redrawn only after a 4° head turn (GL/EGL resolved with dlopen, so Vulkan games never load them); `layer_math.h` = their pose/face math, tested on the host by `tests/test_layer_emul.py`. `render_model.c` = XR_FB_render_model emulation (setting `controller_models`, off by default): serves `files/framebridge/controller_{left,right}.glb`, which the agent converts on the Frame from SteamVR's own Frame controller render models (never shipped by FramePort); tested on the host by `tests/test_render_model.py`. Settings: `libframe_settings.so` in the APK + `settings.conf`/`framebridge.conf` on the Frame. |
-| `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`. |
+| `adapter/` | `{arm64-v8a,armeabi-v7a}/libopenxr_loader_generic.so` | **FrameBridge**: replaces overport's generic loader (which is renamed `libopenxr_loader_original.so`) and fixes Steam Frame runtime gaps. Hooks xrCreateInstance, swapchains, xrEndFrame, spaces, xrPollEvent, … everything else is forwarded by `gen_forwarders.py`-generated tail calls. `scene_emu.c` = Meta scene/spatial-entity emulation; `flip_vk.c` = Vulkan blit for VERTICAL_FLIP quads. `session_fixes.c` = per-game session fixes, all off by default and hooked only when on (`layer_debug` diagnostics, `stable_local`, `focus_hold`, aim correction `aim_pitch/aim_yaw/aim_forward`, `refresh_rate`); `input_diag.c` = controller-input diagnostics (setting `input_diag`, off by default and hooked only when on; logs suggested interaction profiles and the runtime's answers, each hand's current profile, functions the runtime lacks and failing input/haptics/perf calls, each line once; tested on the host by `tests/test_input_diag.py`); `layer_emul_gl.c` = `equirect_emul` (GLES sessions only): 360° equirect/equirect2 layers become one adapter projection layer, drawn by a worker thread with its own EGL context shared with the app's: each 360° image is converted to a cube map only when it changes, and the view is redrawn only after a 4° head turn (GL/EGL resolved with dlopen, so Vulkan games never load them); `layer_math.h` = their pose/face math, tested on the host by `tests/test_layer_emul.py`. `render_model.c` = XR_FB_render_model emulation (setting `controller_models`, off by default): serves `files/framebridge/controller_{left,right}.glb`, which the agent converts on the Frame from SteamVR's own Frame controller render models (never shipped by FramePort); tested on the host by `tests/test_render_model.py`. Settings: `libframe_settings.so` in the APK + `settings.conf`/`framebridge.conf` on the Frame. |
+| `vrapi-bridge/` | `arm64-v8a/libvrapi.so` | VrApi → OpenXR bridge from [Android-XR-Bridge/OVRPort](https://github.com/Android-XR-Bridge/OVRPort) `native/vrapi` at 5e7df52 (GPL-3.0, `LICENSE.upstream`; unchanged upstream as of OVRPort v1.2.5, which ships the unpatched code as its opt-in `patch_vrapi_openxr` in experimental CLI builds), with our changes in `upstream-patches/`: GLES sessions + GL texture swapchains, cylinder→quad layers, GL vertical flip, UNORM↔sRGB format twins, 30 s VR-mode deadline, VALID-only recenter, loading-icon layers skipped, `vrapi_PollEvent`/`RecenterPose`/`SetDisplayRefreshRate`/`GetSystemPropertyFloatArray` (BlazeRush imports them, GitHub #57), diagnostics behind `-DOVP_GL_DIAG`. `upstream-patches/` reproduces these sources from the fork's `native/vrapi` (checked 2026-10-06 against its latest commit); upstream PRs Android-XR-Bridge/OVRPort#3-#8, tracked in GitHub #75. |
 | `platformcompat/` | `arm64-v8a/libovrplatformcompat.so` | Real `ovrMessageType_ToString` (same fork, `native/platform`). |
-| `langpack/` | `arm64-v8a/libfp_langpack.so` | Language packs for the Meta Platform SDK (patch `frame.langpacks`, opt-in). overport's platform loader is a dispatcher in front of Meta's own loader and answers `ovr_LanguagePack_GetCurrent/SetCurrent` with `return 0` (no reply ever). This library becomes the loader's first DT_NEEDED; the loader's own exports of the 31 functions it defines are made STB_LOCAL in `.dynsym` (`elf.hide_exports`, nothing moves), so symbol lookups reach the library first. It serves `<tag>.lang` files found in the game's OBB / app files (`$FRAMEPORT_LANGPACK_DIRS` overrides the search path) through `ovr_LanguagePack_*`, `ovr_AssetFile_GetList` (the loader's list + the packs) and `ovr_AssetFile_StatusById`; its own message queue is merged into `ovr_PopMessage`, and every handle that is not ours (an address-range check) goes to the loader's original function, whose address is read at run time from the loader's in-memory `.dynsym`. Host-tested against a stand-in loader (`tests/test_langpack.py`, plain `cc`, no NDK); the bionic/headset side is unverified. |
+| `langpack/` | `arm64-v8a/libfp_langpack.so` | Language packs for the Meta Platform SDK (patch `frame.langpacks`, opt-in). overport's platform loader is a dispatcher in front of Meta's own loader and answers `ovr_LanguagePack_GetCurrent/SetCurrent` with `return 0` (no reply ever). This library becomes the loader's first DT_NEEDED; the loader's own exports of the 31 functions it defines are made STB_LOCAL in `.dynsym` (`elf.hide_exports`, nothing moves), so symbol lookups reach the library first. It serves `<tag>.lang` files found in the game's OBB / app files (`$FRAMEPORT_LANGPACK_DIRS` overrides the search path) through `ovr_LanguagePack_*`, `ovr_AssetFile_GetList` (the loader's list + the packs) and `ovr_AssetFile_StatusById`; its own message queue is merged into `ovr_PopMessage`, and every handle that is not ours (an address-range check) goes to the loader's original function, whose address is read at run time from the loader's in-memory `.dynsym`. With patch `frame.asset_files` (marker byte `@FPASSETS@`, or env `FRAMEPORT_ASSET_FILES=1`) it also lists the data's `*.pak` content files as installed `default` asset files and answers `ovr_AssetFile_DownloadById` for them at once (a completed `DownloadUpdate`, then the result with the path). Host-tested against a stand-in loader (`tests/test_langpack.py`, plain `cc`, no NDK); the bionic/headset side is unverified. |
 | `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);
+        }
+    }
+}
@@ -1,19 +1,4 @@
 // Generated: register-preserving tail-call forwarders (see frame_adapter.c).
-    .text
-    .p2align 2
-    .globl xrApplyHapticFeedback
-    .type xrApplyHapticFeedback, %function
-xrApplyHapticFeedback:
-    adrp x16, fwd_xrApplyHapticFeedback
-    ldr x16, [x16, :lo12:fwd_xrApplyHapticFeedback]
-    br x16
-    .size xrApplyHapticFeedback, .-xrApplyHapticFeedback
-    .data
-    .p2align 3
-    .globl fwd_xrApplyHapticFeedback
-    .hidden fwd_xrApplyHapticFeedback
-fwd_xrApplyHapticFeedback:
-    .quad frame_unsupported
    .text
    .p2align 2
    .globl xrAttachSessionActionSets
@@ -28,21 +13,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 +373,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 +478,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,5 @@
 // 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 +24,6 @@ FORWARD(xrGetReferenceSpaceBoundsRect)
 FORWARD(xrGetSystem)
 FORWARD(xrGetViewConfigurationProperties)
 FORWARD(xrPathToString)
-FORWARD(xrReleaseSwapchainImage)
 FORWARD(xrRequestExitSession)
 FORWARD(xrResultToString)
 FORWARD(xrStopHapticFeedback)
@@ -34,4 +31,3 @@ FORWARD(xrStringToPath)
 FORWARD(xrStructureTypeToString)
 FORWARD(xrSuggestInteractionProfileBindings)
 FORWARD(xrSyncActions)
-FORWARD(xrWaitSwapchainImage)
@@ -3,23 +3,6 @@
    .arm
    .text
    .p2align 2
-    .globl xrApplyHapticFeedback
-    .type xrApplyHapticFeedback, %function
-xrApplyHapticFeedback:
-    ldr ip, 1f
-2:  add ip, pc, ip
-    ldr ip, [ip]
-    bx ip
-1:  .word fwd_xrApplyHapticFeedback - (2b + 8)
-    .size xrApplyHapticFeedback, .-xrApplyHapticFeedback
-    .data
-    .p2align 2
-    .globl fwd_xrApplyHapticFeedback
-    .hidden fwd_xrApplyHapticFeedback
-fwd_xrApplyHapticFeedback:
-    .word frame_unsupported
-    .text
-    .p2align 2
    .globl xrAttachSessionActionSets
    .type xrAttachSessionActionSets, %function
 xrAttachSessionActionSets:
@@ -34,23 +17,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 +425,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 +544,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
@@ -26,6 +26,9 @@
 //    render_model.c);
 //  * per-game session fixes (session_fixes.c, all off by default): layer_debug diagnostics, stable_local,
 //    focus_hold, aim pose correction (aim_pitch/aim_yaw/aim_forward), refresh_rate;
+//  * optionally logs controller-input diagnostics: suggested interaction profiles and the runtime's answers, each
+//    hand's current profile, functions the runtime lacks, failing input/haptics/perf calls (input_diag,
+//    input_diag.c, off by default);
 //  * optionally shows 360° (equirect/equirect2) layers as cube-face quads drawn by a worker thread with a shared
 //    GLES context (equirect_emul, layer_emul_gl.c; GLES sessions only, off by default).
 //
@@ -69,6 +72,7 @@ static void fb_log(const char *fmt, ...) {
    funlockfile(log_file);
 }
 #define LOG(...) fb_log(__VA_ARGS__)
+#include "audio_metadata.h"

 static void *loader;
 static PFN_xrGetInstanceProcAddr next_gipa;
@@ -82,8 +86,25 @@ 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;
@@ -107,9 +128,11 @@ static int controller_models;  // serve Frame controller models via XR_FB_render
 static int sync_guard;       // xrSyncActions one at a time with xrPollEvent, paused briefly after focus returns
 static int profile_remap = 1; // Meta's newer controller profiles (rejected by the Frame) -> oculus/touch_controller
 static int layer_debug;      // diagnostics: layers, swapchains, session states, spaces, aim/grip, refresh rates
+static int input_diag;       // diagnostics: controller profiles, bindings, missing functions, failing input calls
 static int stable_local;     // keep every LOCAL space the app creates on the session-start origin
-static int focus_hold;       // 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 haptic_scale = 1.0f;   // vibration strength (0-1), all vibration types (xrApplyHapticFeedback)
 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)
@@ -129,8 +152,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;
@@ -146,6 +175,7 @@ static void read_settings(const char *path) {
        if (sscanf(line, "scene_depth=%f", &value) == 1 && value > 0.5f && value < 20.0f) scene_depth = value;
        if (sscanf(line, "controller_models=%f", &value) == 1) controller_models = value != 0;
        if (sscanf(line, "layer_debug=%f", &value) == 1) layer_debug = value != 0;
+        if (sscanf(line, "input_diag=%f", &value) == 1) input_diag = value != 0;
        if (sscanf(line, "surface_emul=%f", &value) == 1) surface_emul = value != 0;
        if (sscanf(line, "eye_debug=%f", &value) == 1) eye_debug = value != 0;
        if (sscanf(line, "release_wait=%f", &value) == 1) release_wait = (int)value;
@@ -154,6 +184,7 @@ static void read_settings(const char *path) {
        if (sscanf(line, "stable_local=%f", &value) == 1) stable_local = value != 0;
        if (sscanf(line, "focus_hold=%f", &value) == 1) focus_hold = value != 0;
        if (sscanf(line, "focus_hold_ms=%f", &value) == 1 && value >= 100 && value <= 5000) focus_hold_ms = value;
+        if (sscanf(line, "haptic_scale=%f", &value) == 1 && value >= 0 && value <= 1) haptic_scale = value;
        if (sscanf(line, "aim_pitch=%f", &value) == 1 && fabsf(value) <= 90) aim_pitch = value;
        if (sscanf(line, "aim_yaw=%f", &value) == 1 && fabsf(value) <= 90) aim_yaw = value;
        if (sscanf(line, "aim_forward=%f", &value) == 1 && fabsf(value) <= 0.5f) aim_forward = value;
@@ -200,10 +231,18 @@ 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 (input_diag) LOG("per-game: input_diag=1 (controller-input diagnostics)");
+    if (hide_space_warp) LOG("per-game: hide_space_warp=1 (XR_FB_space_warp hidden, space warp info removed)");
+    if (strip_color_bias) LOG("per-game: strip_color_bias=%d (layer color scale/bias removed)", strip_color_bias);
+    if (frame_balance) LOG("per-game: frame_balance=1 (an open frame is ended before the next one begins)");
    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);
@@ -261,7 +300,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
    }

    XrInstanceCreateInfo fixed = *info;
-    const char **names = calloc(info->enabledExtensionCount + 2, sizeof(*names));
+    const char **names = calloc(info->enabledExtensionCount + 3, sizeof(*names));
    if (!names) { free(available); return XR_ERROR_OUT_OF_MEMORY; }
    uint32_t kept = 0;
    for (uint32_t i = 0; i < info->enabledExtensionCount; ++i) {
@@ -269,6 +308,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");
@@ -285,6 +328,19 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
        names[kept++] = "XR_KHR_android_create_instance";
        LOG("added %s", "XR_KHR_android_create_instance");
    }
+    {   // no graphics API extension at all: Meta's runtime still accepts a GLES session, the Frame's doesn't
+        // (Lambda1VR's TBXR enables only XR_EXT_local_floor). Add GLES, which every such app uses, if offered.
+        int graphics = 0, gles_offered = 0;
+        for (uint32_t i = 0; i < kept; ++i)
+            graphics |= !strcmp(names[i], "XR_KHR_opengl_es_enable") || !strcmp(names[i], "XR_KHR_vulkan_enable") ||
+                        !strcmp(names[i], "XR_KHR_vulkan_enable2");
+        for (uint32_t j = 0; available && j < available_count; ++j)
+            gles_offered |= !strcmp(available[j].extensionName, "XR_KHR_opengl_es_enable");
+        if (!graphics && gles_offered) {
+            names[kept++] = "XR_KHR_opengl_es_enable";
+            LOG("added XR_KHR_opengl_es_enable (the app enabled no graphics API extension)");
+        }
+    }
    if (refresh_rate > 0) {  // the refresh_rate setting needs XR_FB_display_refresh_rate even if the app doesn't use it
        int requested = 0, offered = 0;
        for (uint32_t i = 0; i < kept; ++i) requested |= !strcmp(names[i], "XR_FB_display_refresh_rate");
@@ -293,6 +349,14 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
    }
    fixed.enabledExtensionNames = names;
    fixed.enabledExtensionCount = kept;
+    {   // what the runtime gets (diagnostics: e.g. a graphics extension the app forgot)
+        char list[1024] = "";
+        for (uint32_t i = 0; i < kept; ++i) {
+            size_t len = strlen(list);
+            snprintf(list + len, sizeof list - len, "%s%s", i ? " " : "", names[i] + (strncmp(names[i], "XR_", 3) ? 0 : 3));
+        }
+        LOG("xrCreateInstance with %u extension(s): %s", kept, list);
+    }
    for (uint32_t j = 0; available && j < available_count; ++j)
        if (!strcmp(available[j].extensionName, "XR_FB_composition_layer_image_layout")) runtime_has_image_layout = 1;
    // Layer types are only valid if their extension ends up enabled; some apps submit them regardless.
@@ -305,10 +369,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;
 }

@@ -379,6 +444,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)
@@ -420,6 +524,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);
@@ -428,8 +533,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;
@@ -450,8 +557,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;
 }
@@ -459,10 +568,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);
 }
@@ -712,15 +826,47 @@ XRAPI_ATTR XrResult XRAPI_CALL xrDestroySpace(XrSpace space) {
    return fn ? fn(space) : XR_ERROR_FUNCTION_UNSUPPORTED;
 }

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

+// OpenXR requires xrGet*GraphicsRequirementsKHR before xrCreateSession; Meta's runtime doesn't enforce it, the Frame's
+// does (XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING, e.g. Lambda1VR's TBXR). Ask on the app's behalf, once, and retry.
+static int ask_graphics_requirements(XrInstance instance, const XrSessionCreateInfo *info) {
+    const XrBaseInStructure *binding = info ? (const XrBaseInStructure *)info->next : NULL;
+    for (; binding; binding = binding->next) {
+        const char *name = NULL;
+        XrStructureType type = 0;
+        if (binding->type == (XrStructureType)1000024001) {  // XR_TYPE_GRAPHICS_BINDING_OPENGL_ES_ANDROID_KHR
+            name = "xrGetOpenGLESGraphicsRequirementsKHR";
+            type = (XrStructureType)1000024003;               // XR_TYPE_GRAPHICS_REQUIREMENTS_OPENGL_ES_KHR
+        } else if (binding->type == (XrStructureType)1000025000) {  // XR_TYPE_GRAPHICS_BINDING_VULKAN_KHR
+            name = "xrGetVulkanGraphicsRequirementsKHR";
+            type = (XrStructureType)1000025002;               // XR_TYPE_GRAPHICS_REQUIREMENTS_VULKAN_KHR
+        }
+        if (!name) continue;
+        // XrGraphicsRequirementsOpenGLESKHR and ...VulkanKHR share this layout
+        struct { XrStructureType type; void *next; XrVersion min, max; } req = {type, NULL, 0, 0};
+        typedef XrResult (XRAPI_PTR *PFN_requirements)(XrInstance, XrSystemId, void *);
+        PFN_requirements get = (PFN_requirements)lookup(instance, name);
+        if (!get && type == (XrStructureType)1000025002)  // XR_KHR_vulkan_enable2 apps: same struct and call
+            get = (PFN_requirements)lookup(instance, "xrGetVulkanGraphicsRequirements2KHR");
+        XrResult r = get ? get(instance, info->systemId, &req) : XR_ERROR_FUNCTION_UNSUPPORTED;
+        LOG("xrCreateSession: the app skipped %s; asked for it (result=%d)", name, (int)r);
+        return XR_SUCCEEDED(r);
+    }
+    return 0;
+}
+
 XRAPI_ATTR XrResult XRAPI_CALL xrCreateSession(XrInstance instance, const XrSessionCreateInfo *info, XrSession *session) {
    PFN_xrCreateSession fn = (PFN_xrCreateSession)lookup(instance, "xrCreateSession");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
    XrResult result = fn(instance, info, session);
+    if (result == XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING && ask_graphics_requirements(instance, info))
+        result = fn(instance, info, session);
    if (XR_SUCCEEDED(result)) {
        flip_emul = flip_emul_setting;
        flip_on_create_session(info);
@@ -731,6 +877,63 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSession(XrInstance instance, const XrSess
    return result;
 }

+// Vibrations: logged (the first few, to see what games ask for) and scaled by haptic_scale. Plain vibrations, Meta's
+// amplitude envelopes and PCM buffers all pass here: games' own calls, OVRPort's VrApi bridge and the xrshim alike.
+static int haptics_logged;
+static XrResult apply_haptics(XrSession session, const XrHapticActionInfo *info, const XrHapticBaseHeader *feedback) {
+    PFN_xrApplyHapticFeedback fn = (PFN_xrApplyHapticFeedback)lookup(active_instance, "xrApplyHapticFeedback");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (!feedback) return fn(session, info, feedback);
+    if (feedback->type == XR_TYPE_HAPTIC_VIBRATION) {
+        XrHapticVibration v = *(const XrHapticVibration *)feedback;
+        if (haptics_logged++ < 8)
+            LOG("haptic: vibration amplitude=%.2f duration=%lld ns frequency=%.0f (scale %.2f)", v.amplitude,
+                (long long)v.duration, v.frequency, haptic_scale);
+        v.amplitude *= haptic_scale;
+        if (v.amplitude <= 0.001f) {
+            // OVRPlugin stops a vibration by sending amplitude 0 with its usual 2 s duration (Jurassic World, The Boys
+            // VR): on a Quest that stops the motor; OpenXR's stop is xrStopHapticFeedback, and without it the last
+            // buzz ran its full 2 s
+            PFN_xrStopHapticFeedback stop = (PFN_xrStopHapticFeedback)lookup(active_instance, "xrStopHapticFeedback");
+            if (stop) return stop(session, info);
+        }
+        return fn(session, info, (const XrHapticBaseHeader *)&v);
+    }
+    if (feedback->type == (XrStructureType)1000173001 || feedback->type == (XrStructureType)1000209001) {
+        // XR_TYPE_HAPTIC_AMPLITUDE_ENVELOPE_VIBRATION_FB / XR_TYPE_HAPTIC_PCM_VIBRATION_FB: a sample buffer
+        typedef struct { XrStructureType type; const void *next; XrDuration duration; uint32_t count; const float *s; } env_t;
+        typedef struct { XrStructureType type; const void *next; uint32_t count; const float *s; float rate; XrBool32 append;
+                         uint32_t *consumed; } pcm_t;
+        int envelope = feedback->type == (XrStructureType)1000173001;
+        uint32_t n = envelope ? ((const env_t *)feedback)->count : ((const pcm_t *)feedback)->count;
+        const float *in = envelope ? ((const env_t *)feedback)->s : ((const pcm_t *)feedback)->s;
+        if (haptics_logged++ < 8) {
+            float peak = 0;
+            for (uint32_t i = 0; in && i < n; ++i) peak = fmaxf(peak, in[i]);
+            LOG("haptic: %s %u samples peak=%.2f (scale %.2f)", envelope ? "envelope" : "pcm", n, peak, haptic_scale);
+        }
+        if (haptic_scale >= 0.999f || !in || !n || n > 1u << 20) return fn(session, info, feedback);
+        float *scaled = malloc(n * sizeof *scaled);
+        if (!scaled) return fn(session, info, feedback);
+        for (uint32_t i = 0; i < n; ++i) scaled[i] = in[i] * haptic_scale;
+        XrResult r;
+        if (envelope) { env_t e = *(const env_t *)feedback; e.s = scaled; r = fn(session, info, (const XrHapticBaseHeader *)&e); }
+        else { pcm_t c = *(const pcm_t *)feedback; c.s = scaled; r = fn(session, info, (const XrHapticBaseHeader *)&c); }
+        free(scaled);
+        return r;
+    }
+    return fn(session, info, feedback);
+}
+
+XRAPI_ATTR XrResult XRAPI_CALL xrApplyHapticFeedback(XrSession session, const XrHapticActionInfo *info,
+                                                    const XrHapticBaseHeader *feedback) {
+    XrResult result = apply_haptics(session, info, feedback);
+    if (input_diag && XR_FAILED(result))  // always hooked (haptic_scale), so input_diag reports failures here
+        diag_call_failed("xrApplyHapticFeedback", result,
+                         feedback && feedback->type != XR_TYPE_HAPTIC_VIBRATION ? "(not XrHapticVibration)" : NULL);
+    return result;
+}
+
 XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateSwapchainImages(XrSwapchain swapchain, uint32_t capacity, uint32_t *count,
        XrSwapchainImageBaseHeader *images) {
    PFN_xrEnumerateSwapchainImages fn = (PFN_xrEnumerateSwapchainImages)lookup(active_instance, "xrEnumerateSwapchainImages");
@@ -740,10 +943,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");
@@ -755,7 +976,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;
 }

@@ -769,6 +995,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) {
@@ -857,11 +1084,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);
@@ -904,9 +1189,40 @@ 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;
@@ -923,6 +1239,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),
@@ -1056,6 +1384,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.
@@ -1073,6 +1468,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;
@@ -1148,6 +1588,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetCurrentInteractionProfile(XrSession session,
        (PFN_xrGetCurrentInteractionProfile)lookup(active_instance, "xrGetCurrentInteractionProfile");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
    XrResult result = fn(session, user, state);
+    if (input_diag && XR_SUCCEEDED(result) && state) input_diag_current_profile(user, state->interactionProfile);
    if (layer_debug && active_instance) {  // which device each hand has, as the runtime reports it
        PFN_xrPathToString str = (PFN_xrPathToString)lookup(active_instance, "xrPathToString");
        char who[XR_MAX_PATH_LENGTH] = "?", what[XR_MAX_PATH_LENGTH] = "(none)";
@@ -1179,7 +1620,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;
@@ -1196,6 +1637,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;
    }
@@ -1263,6 +1705,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
    if (!emulated && emulate_scene && !strcmp(name, "xrLocateSpacesKHR")) emulated = (PFN_xrVoidFunction)emu_locate_spaces_khr;
    if (emulated) { *function = emulated; return XR_SUCCESS; }
    HOOK(xrGetSystemProperties)
+    HOOK(xrApplyHapticFeedback)
    HOOK(xrCreateReferenceSpace)
    HOOK(xrLocateViews)
    HOOK(xrPollEvent)
@@ -1278,6 +1721,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
    HOOK(xrCreateSwapchain)
    HOOK(xrDestroySwapchain)
    HOOK(xrEndFrame)
+    HOOK(xrBeginFrame)
    HOOK(xrLocateHandJointsEXT)
    HOOK(xrGetCurrentInteractionProfile)
    HOOK(xrEnumerateInstanceExtensionProperties)
@@ -1294,15 +1738,26 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
    }
    if (surface_emul) HOOK_AS(xrCreateSwapchainAndroidSurfaceKHR, hook_xrCreateSwapchainAndroidSurfaceKHR)
    if (eye_debug || release_wait) HOOK_AS(xrReleaseSwapchainImage, eye_hook_xrReleaseSwapchainImage)
-    if (sync_guard || layer_debug) HOOK_AS(xrSyncActions, hook_xrSyncActions)
+    if (layer_debug) {  // counters only; every other wait/release hook above takes precedence
+        HOOK(xrWaitSwapchainImage)
+        HOOK(xrReleaseSwapchainImage)
+    }
+    if (sync_guard || layer_debug || input_diag) HOOK_AS(xrSyncActions, hook_xrSyncActions)
    if (layer_debug) HOOK_AS(xrGetActionStateBoolean, hook_xrGetActionStateBoolean)
-    if (layer_debug || aim_correction_on() || profile_remap)
+    if (layer_debug || aim_correction_on() || profile_remap || input_diag)
        HOOK_AS(xrSuggestInteractionProfileBindings, hook_xrSuggestInteractionProfileBindings)
    if (layer_debug || aim_correction_on()) {
        HOOK_AS(xrCreateActionSpace, hook_xrCreateActionSpace)
    }
 #undef HOOK_AS
 #undef HOOK
+    if (input_diag) {  // logs only: wraps a few input/haptics/perf calls, notes lookups the runtime can't answer
+        PFN_xrVoidFunction diag = input_diag_hook(name);
+        XrResult result = next_gipa(instance, name, function);
+        input_diag_lookup(instance, name, result, *function);
+        if (diag && XR_SUCCEEDED(result) && *function) *function = diag;
+        return result;
+    }
    return next_gipa(instance, name, function);
 }

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

@@ -140,7 +142,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))
@@ -324,6 +326,7 @@ static XRAPI_ATTR XrResult XRAPI_CALL hook_xrSuggestInteractionProfileBindings(X
                note_pose_binding(suggested->suggestedBindings[i].action, path);
        }
    XrResult r = fn(instance, suggested);
+    input_diag_suggested(instance, suggested, r, to_string);  // the runtime's answer to the game's own suggestion
    if (!profile_remap || !suggested || !to_string) return r;
    char profile[XR_MAX_PATH_LENGTH] = {0};
    uint32_t size = 0;
@@ -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);
+    }
+}
@@ -10,7 +10,7 @@ timefix OpenXR layer for Proton games (linux-arm64, glibc; the NDK's clang build
 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,langpack,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

@@ -239,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"
@@ -308,7 +326,7 @@ def write_sums():

 def main():
    ap = argparse.ArgumentParser()
-    ap.add_argument("--only", default="adapter,bridge,compat,langpack,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(","))
@@ -317,11 +335,11 @@ def main():
    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),
             "langpack": lambda: build_langpack(tc),
-             "glshim": lambda: build_glshim(tc), "xrshim": lambda: build_xrshim(tc), "dex": build_dex, "xrlayer": lambda: build_xrlayer(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", "langpack", "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;
 }

@@ -362,6 +399,24 @@ __attribute__((visibility("default"))) const GLubyte *glGetString(GLenum name) {
    return (const GLubyte *)filtered;
 }

+// With GL_EXT_multisampled_render_to_texture hidden (gl_hide_msrtt), an app that calls its functions anyway (Team
+// Beef's TBXR, e.g. Lambda1VR: color via glFramebufferTexture2DMultisampleEXT, depth via
+// glRenderbufferStorageMultisampleEXT) gets plain single-sampled versions, so both attachments match: Zink called
+// the mix GL_FRAMEBUFFER_INCOMPLETE_MULTISAMPLE and the eyes stayed black.
+typedef void (*PFN_FT2D)(GLenum, GLenum, GLenum, GLuint, GLint);
+typedef void (*PFN_RBS)(GLenum, GLenum, GLsizei, GLsizei);
+static PFN_FT2D r_plain_ft2d;
+static PFN_RBS r_plain_rbs;
+static int msrtt_logged;
+static void plain_ft2dms(GLenum target, GLenum attachment, GLenum textarget, GLuint texture, GLint level, GLsizei samples) {
+    if (!msrtt_logged++) LOG("GL shim: multisampled render-to-texture (%d samples) drawn single-sampled", (int)samples);
+    if (r_plain_ft2d) r_plain_ft2d(target, attachment, textarget, texture, level);
+}
+static void plain_rbsms(GLenum target, GLsizei samples, GLenum format, GLsizei width, GLsizei height) {
+    (void)samples;
+    if (r_plain_rbs) r_plain_rbs(target, format, width, height);
+}
+
 __attribute__((visibility("default"))) __eglMustCastToProperFunctionPointerType eglGetProcAddress(const char *name) {
    pthread_once(&once, init);
    if (name && !strcmp(name, "glGetStringi")) return (__eglMustCastToProperFunctionPointerType)glGetStringi;
@@ -370,6 +425,13 @@ __attribute__((visibility("default"))) __eglMustCastToProperFunctionPointerType
    __eglMustCastToProperFunctionPointerType fn = real_eglGetProcAddress ? real_eglGetProcAddress(name) : NULL;
    if (!fn || !name) return fn;
 #define WRAP(sym, real, w) if (!strcmp(name, sym)) { real = (void *)fn; return (__eglMustCastToProperFunctionPointerType)w; }
+    if (hide_msrtt && (!strcmp(name, "glFramebufferTexture2DMultisampleEXT") ||
+                       !strcmp(name, "glRenderbufferStorageMultisampleEXT"))) {
+        if (!r_plain_ft2d) r_plain_ft2d = (PFN_FT2D)real_eglGetProcAddress("glFramebufferTexture2D");
+        if (!r_plain_rbs) r_plain_rbs = (PFN_RBS)real_eglGetProcAddress("glRenderbufferStorage");
+        return name[2] == 'F' ? (__eglMustCastToProperFunctionPointerType)plain_ft2dms
+                              : (__eglMustCastToProperFunctionPointerType)plain_rbsms;
+    }
 #ifdef GLSHIM_TRACE  // build with -DGLSHIM_TRACE for eye-buffer / draw / error tracing
    WRAP("glFramebufferTextureMultiviewOVR", real_ftmv, w_ftmv)
    WRAP("glFramebufferTextureMultisampleMultiviewOVR", real_ftmsmv, w_ftmsmv)
@@ -30,6 +30,12 @@
 //
 // 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.
+//
+// Content files (patch frame.asset_files, which sets the marker byte g_assets_slot; or FRAMEPORT_ASSET_FILES=1):
+// every *.pak next to the game's OBB is also listed as an installed asset file of type "default" (Meta's type for
+// content that comes with the game, IAP status "free"), named after the file. ovr_AssetFile_DownloadById on one of
+// them answers at once with a completed download update and a result carrying the file's path (nothing is copied).
+// E.g. Star Wars: Tales from the Galaxy's Edge, whose seasons and sound banks are such files (ETacoDLC::Season1...).
 #define _GNU_SOURCE
 #include <ctype.h>
 #include <dirent.h>
@@ -93,6 +99,8 @@ static int g_traced;
 #define MSG_ASSETFILE_STATUSBYID 0x5D955D38u
 #define MSG_LANGUAGEPACK_GETCURRENT 0x1F90F0D5u
 #define MSG_LANGUAGEPACK_SETCURRENT 0x5B4FBBE0u
+#define MSG_ASSETFILE_DOWNLOADBYID 0x2D008992u
+#define MSG_NOTIFICATION_DOWNLOADUPDATE 0x2FDD0CCDu

 #define MAXP 32
 #define PATHLEN 1024
@@ -206,6 +214,12 @@ 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(u64, AssetFile_DownloadById, (u64 id), (id))
+DEFORIG(void *, Message_GetAssetFileDownloadUpdate, (const void *m), (m))
+DEFORIG(u64, AssetFileDownloadUpdate_GetAssetFileId, (const void *u), (u))
+DEFORIG(u64, AssetFileDownloadUpdate_GetBytesTotal, (const void *u), (u))
+DEFORIG(long long, AssetFileDownloadUpdate_GetBytesTransferred, (const void *u), (u))
+DEFORIG(_Bool, AssetFileDownloadUpdate_GetCompleted, (const void *u), (u))
 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))
@@ -216,9 +230,12 @@ DEFORIG(const char *, Error_GetDisplayableMessage, (const void *e), (e))
 * ------------------------------------------------------------------------------------------------------------- */

 typedef struct {
-    char tag[48];
+    char tag[48];  // language packs: the BCP47 tag; content files: empty
+    char name[128];  // content files: the file name (the asset's name)
    char path[PATHLEN];
    u64 id;
+    long long size;
+    int content;
 } pack_t;

 static const struct {
@@ -263,8 +280,9 @@ static int valid_tag(const char *t) {

 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
+        if (!out[i].content && tag_eq(out[i].tag, tag)) return;  // first one wins
    pack_t *p = &out[(*n)++];
+    memset(p, 0, sizeof *p);
    snprintf(p->tag, sizeof p->tag, "%s", tag);
    snprintf(p->path, sizeof p->path, "%s", path);
    p->id = hash_tag(tag);
@@ -272,6 +290,37 @@ static void add_pack(pack_t *out, int *n, const char *tag, const char *path) {

 static int g_logged_dirs;

+// frame.asset_files sets the byte after the marker to '1' (frameport.patches.frame.langpack.with_assets)
+#define ASSETS_MARK "@FPASSETS@"
+__attribute__((used)) static char g_assets_slot[sizeof ASSETS_MARK + 1] = ASSETS_MARK "0";
+
+static int assets_enabled(void) {
+    const char *env = getenv("FRAMEPORT_ASSET_FILES");
+    if (env && *env) return *env == '1';
+    return ((const volatile char *)g_assets_slot)[sizeof ASSETS_MARK - 1] == '1';
+}
+
+static u64 hash_name(const char *name) {
+    u64 h = 1469598103934665603ULL ^ 0x66;  // FNV-1a, seeded apart from the tags
+    for (const char *p = name; *p; p++) {
+        h ^= (unsigned char)((*p >= 'A' && *p <= 'Z') ? *p + 32 : *p);
+        h *= 1099511628211ULL;
+    }
+    return 0x4650000000000000ULL | (h & 0x0000FFFFFFFFFFFFULL);
+}
+
+static void add_content(pack_t *out, int *n, const char *name, const char *path, long long size) {
+    for (int i = 0; i < *n; i++)
+        if (out[i].content && strcasecmp(out[i].name, name) == 0) return;  // first one wins
+    pack_t *p = &out[(*n)++];
+    memset(p, 0, sizeof *p);
+    p->content = 1;
+    snprintf(p->name, sizeof p->name, "%.127s", name);  // (callers pass names shorter than 128)
+    snprintf(p->path, sizeof p->path, "%s", path);
+    p->size = size;
+    p->id = hash_name(name);
+}
+
 // 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".
@@ -323,6 +372,9 @@ static void scan_dir(const char *dir, int depth, pack_t *out, int *n) {
                memcpy(tag, e->d_name, len - 5);
                tag[len - 5] = 0;
                if (valid_tag(tag) && !skipped(tag)) add_pack(out, n, tag, path);
+            } else if (len > 4 && strcasecmp(e->d_name + len - 4, ".pak") == 0 && assets_enabled() &&
+                       strlen(e->d_name) < sizeof out[0].name) {
+                add_content(out, n, e->d_name, path, (long long)st.st_size);
            }
        }
    }
@@ -347,8 +399,10 @@ static int scan(pack_t *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);
+        fplog("%d language pack(s) and content file(s) found", n);
+        for (int i = 0; i < n; i++)
+            fplog("  %s %s -> %s", out[i].content ? "content" : "pack", out[i].content ? out[i].name : out[i].tag,
+                  out[i].path);
    }
    g_logged_dirs = 1;
    return n;
@@ -390,10 +444,10 @@ 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;
+        if (!p[i].content && 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;
+        if (!p[i].content && base_len(p[i].tag) == bl && strncasecmp(p[i].tag, tag, (size_t)bl) == 0) return i;
    return -1;
 }

@@ -411,7 +465,10 @@ static int pick_current(const pack_t *p, int n) {
        int i = find_tag(p, n, env);
        if (i >= 0) return i;
    }
-    return n == 1 ? 0 : -1;
+    int only = -1, langs = 0;
+    for (int i = 0; i < n; i++)
+        if (!p[i].content) only = i, langs++;
+    return langs == 1 ? only : -1;
 }

 /* ---------------------------------------------------------------------------------------------------------------
@@ -460,12 +517,19 @@ typedef struct {
    char msg[128];
 } err_t;

+typedef struct {
+    u64 id;
+    long long total, done;
+    int completed;
+} update_t;
+
 typedef struct msg {
    struct msg *all_next, *q_next;
    u32 type;
    u64 req;
-    int is_error, has_det, has_res;
+    int is_error, has_det, has_res, has_upd;
    err_t err;
+    update_t upd;
    details_t det;
    lang_t lng;
    result_t res;
@@ -525,6 +589,16 @@ static void fail(msg_t *m, int code, const char *text) {
 }

 static void fill_details(details_t *d, lang_t *l, const pack_t *p) {
+    if (p->content) {  // content that comes with the game: Meta's "default" asset type, nothing to buy
+        d->id = p->id;
+        snprintf(d->type, sizeof d->type, "default");
+        snprintf(d->status, sizeof d->status, "installed");
+        snprintf(d->iap, sizeof d->iap, "free");
+        snprintf(d->path, sizeof d->path, "%s", p->path);
+        d->meta[0] = 0;
+        d->lang = NULL;
+        return;
+    }
    d->id = p->id;
    snprintf(d->type, sizeof d->type, "language_pack");
    snprintf(d->status, sizeof d->status, "installed");
@@ -722,6 +796,35 @@ EXPORT u64 ovr_AssetFile_StatusById(u64 id) {
    return o_AssetFile_StatusById(id);
 }

+EXPORT u64 ovr_AssetFile_DownloadById(u64 id) {
+    fplog("AssetFile_DownloadById(%llu)%s", (unsigned long long)id, (id >> 48) == 0x4650 ? " (ours)" : "");
+    if ((id >> 48) != 0x4650) return o_AssetFile_DownloadById(id);
+    pack_t packs[MAXP];
+    int n = scan(packs), i = 0;
+    while (i < n && packs[i].id != id) i++;
+    msg_t *m = new_msg(MSG_ASSETFILE_DOWNLOADBYID, 0);
+    if (!m) return 0;
+    u64 req = m->req;
+    if (i == n) {
+        fail(m, 404, "asset file not found");
+        post(m);
+        return req;
+    }
+    // already on the device: a finished download update, then the result with the file's path
+    msg_t *u = new_msg(MSG_NOTIFICATION_DOWNLOADUPDATE, 0);
+    if (u) {
+        u->req = 0;  // notifications carry no request id
+        u->upd = (update_t){packs[i].id, packs[i].size, packs[i].size, 1};
+        u->has_upd = 1;
+        post(u);
+    }
+    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;
+}
+
 /* ---------------------------------------------------------------------------------------------------------------
 * Message loop
 * ------------------------------------------------------------------------------------------------------------- */
@@ -813,6 +916,12 @@ EXPORT void *ovr_Message_GetAssetFileDownloadResult(const void *h) {
    return m->has_res ? (void *)&m->res : NULL;
 }

+EXPORT void *ovr_Message_GetAssetFileDownloadUpdate(const void *h) {
+    msg_t *m = owner(h);
+    if (!m) return o_Message_GetAssetFileDownloadUpdate(h);
+    return m->has_upd ? (void *)&m->upd : NULL;
+}
+
 EXPORT void *ovr_Message_GetAssetDetailsArray(const void *h) {
    msg_t *m = owner(h);
    if (!m) return o_Message_GetAssetDetailsArray(h);
@@ -903,6 +1012,19 @@ EXPORT const char *ovr_AssetFileDownloadResult_GetFilepath(const void *h) {
    return IS_OURS(h) ? ((const result_t *)h)->path : o_AssetFileDownloadResult_GetFilepath(h);
 }

+EXPORT u64 ovr_AssetFileDownloadUpdate_GetAssetFileId(const void *h) {
+    return IS_OURS(h) ? ((const update_t *)h)->id : o_AssetFileDownloadUpdate_GetAssetFileId(h);
+}
+EXPORT u64 ovr_AssetFileDownloadUpdate_GetBytesTotal(const void *h) {
+    return IS_OURS(h) ? (u64)((const update_t *)h)->total : o_AssetFileDownloadUpdate_GetBytesTotal(h);
+}
+EXPORT long long ovr_AssetFileDownloadUpdate_GetBytesTransferred(const void *h) {
+    return IS_OURS(h) ? ((const update_t *)h)->done : o_AssetFileDownloadUpdate_GetBytesTransferred(h);
+}
+EXPORT _Bool ovr_AssetFileDownloadUpdate_GetCompleted(const void *h) {
+    return IS_OURS(h) ? (_Bool)((const update_t *)h)->completed : o_AssetFileDownloadUpdate_GetCompleted(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) {
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-3.0-only
-// FramePort OVRPlugin frame-loop shim for Unity 2017-2018 built-in Oculus support.
+// FramePort OVRPlugin shim: the frame loop for Unity 2017-2018 built-in Oculus support, and Unity's user presence.
 //
 // That Unity drives OVRPlugin with the legacy frame loop: ovrp_Update2(render step, frame index, ...) on the main
 // thread, then ovrp_BeginFrame / ovrp_EndFrame on the render thread. It never calls ovrp_WaitToBeginFrame, which
@@ -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,105 @@ 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;
+}
+
+// ---------------------------------------------------------------- user presence (patch frame.unity_user_presence)
+// Unity's Oculus XR Plugin gives its HMD input device a UserPresence feature from ovrp_GetUserPresent2. On the Frame
+// OVRPort's OVRPlugin answers "not worn" a few seconds after start while the headset is worn, and games that drive
+// their rig only while the user is present stay frozen (BONELAB's Marrow rig: XRHMD.IsUserPresent). The plugin's
+// lookup is renamed to this function, which reports the user as present and logs OVRPlugin's own answer on change.
+typedef int (*PFN_UserPresent2)(int *present);
+
+EXPORT int fpov_GetUserPresent2(int *present) {
+    static PFN_UserPresent2 real;
+    if (!real) {
+        void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
+        if (ovrp) real = (PFN_UserPresent2)dlsym(ovrp, "ovrp_GetUserPresent2");
+    }
+    int value = 0, r = real ? real(&value) : -1000;
+    static int last = -2, logged;
+    if ((r < 0 ? -1 : value) != last && logged++ < 20) LOG("user presence: OVRPlugin %d (result %d) -> 1", value, r);
+    last = r < 0 ? -1 : value;
+    if (present) *present = 1;
+    return 0;  // ovrpSuccess
+}
@@ -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
@@ -8,11 +8,30 @@
 // at this shim (patches/frame/vk_sanitize.py). dlsym on the shim finds the functions below first and every other
 // symbol in its dependency, the real libvulkan.so. Valid pointers are kept; a pointer is dropped only when it isn't
 // readable memory or doesn't point at a structure type the parent may chain.
+// A depth/stencil resolve named in a subpass without a depth attachment is dropped as well: the Frame's driver
+// (Turnip) reads the missing depth attachment and crashes in vkCreateRenderPass2 (Unreal 5, e.g. Metro Awakening).
 //
 // Shader fixes (adapter setting vk_shader_fix, from a game's recipe): a SPIR-V module whose size and SHA-256 match is
 // 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).
+//  * image memory barriers whose image is VK_NULL_HANDLE (Unreal 5, e.g. Metro Awakening) are left out of
+//    vkCmdPipelineBarrier(2): Quest's driver skips them, the Frame's Turnip crashes on them.
 #define _GNU_SOURCE
 #include <vulkan/vulkan.h>
 #include <android/log.h>
@@ -20,6 +39,7 @@
 #include <errno.h>
 #include <fcntl.h>
 #include <pthread.h>
+#include <stddef.h>
 #include <stdlib.h>
 #include <string.h>
 #include <unistd.h>
@@ -74,12 +94,25 @@ 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 int hide_fdm;         // vk_hide_fdm: the game doesn't see VK_EXT_fragment_density_map(2)
+
 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_hide_fdm=", 12)) hide_fdm = atoi(line + 12) != 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 +215,11 @@ 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 (hide_fdm) LOG("vk shim: fragment density map extensions hidden from the game");
+    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 +356,24 @@ static const void *clean_chain(Arena *a, const void *head, int *fixes) {
    return first;
 }

+static int resolves_logged, sourceless_logged;
+
+// A subpass without a depth/stencil attachment that still names a depth/stencil resolve attachment (Unreal 5, e.g.
+// Metro Awakening; valid Vulkan only while that resolve is VK_ATTACHMENT_UNUSED): the Frame's Turnip reads the
+// subpass's depth attachment whenever a resolve attachment is named and crashes on the NULL pointer in
+// vkCreateRenderPass2. With nothing to resolve from, no resolve attachment means the same thing.
+// `sp` is our copy; its known pNext members are copies too (clean_chain), the first unknown one ends the walk.
+static void drop_sourceless_resolve(VkSubpassDescription2 *sp, uint32_t index, int *fixes) {
+    for (VkBaseOutStructure *n = (VkBaseOutStructure *)sp->pNext; n && chain_size(n->sType); n = n->pNext) {
+        if (n->sType != VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE) continue;
+        VkSubpassDescriptionDepthStencilResolve *r = (void *)n;
+        if (!r->pDepthStencilResolveAttachment) continue;
+        r->pDepthStencilResolveAttachment = NULL;
+        (*fixes)++;
+        if (sourceless_logged++ < 5) LOG("vk shim: dropped the depth resolve of subpass %u (no depth attachment)", index);
+    }
+}
+
 static VkRenderPassCreateInfo2 clean_create_info(Arena *a, const VkRenderPassCreateInfo2 *ci, int *fixes) {
    VkRenderPassCreateInfo2 out = *ci;
    out.pNext = clean_chain(a, ci->pNext, fixes);
@@ -338,10 +394,32 @@ static VkRenderPassCreateInfo2 clean_create_info(Arena *a, const VkRenderPassCre
                sp[i].pColorAttachments = clean_refs(a, sp[i].pColorAttachments, sp[i].colorAttachmentCount, fixes);
                sp[i].pResolveAttachments = clean_refs(a, sp[i].pResolveAttachments, sp[i].colorAttachmentCount, fixes);
                sp[i].pDepthStencilAttachment = clean_refs(a, sp[i].pDepthStencilAttachment, 1, fixes);
+                if (!sp[i].pDepthStencilAttachment) drop_sourceless_resolve(&sp[i], i, fixes);
            }
            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 +434,13 @@ 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_PB, FN_PB2, FN_PB2KHR, FN_EDEP, FN_CDEV, FN_CIV, FN_COUNT };
+static const char *const FN_NAMES[FN_COUNT] = {
+    "vkCreateRenderPass2", "vkCreateRenderPass2KHR", "vkCreateShaderModule", "vkCreateImage", "vkCreateQueryPool", "vkDestroyQueryPool",
+    "vkCmdBeginQuery", "vkCmdEndQuery", "vkCmdResetQueryPool", "vkResetQueryPool", "vkResetQueryPoolEXT",
+    "vkGetQueryPoolResults", "vkCmdCopyQueryPoolResults", "vkCmdPipelineBarrier", "vkCmdPipelineBarrier2",
+    "vkCmdPipelineBarrier2KHR", "vkEnumerateDeviceExtensionProperties", "vkCreateDevice", "vkCreateImageView"};
 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 +511,373 @@ 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);
+}
+
+// ---------------------------------------------------------------- fragment density map (vk_hide_fdm)
+
+// Unreal 5 turns on fragment-density-map foveation when the driver offers VK_EXT_fragment_density_map (the Frame's
+// Turnip does) and expects the density map from the headset's runtime, which the Frame doesn't provide (e.g. Metro
+// Awakening: image views and barriers for a VK_NULL_HANDLE image, then a crash). Hidden, the game renders without it;
+// Valve's own FDM layer sits below this shim and isn't affected.
+static int is_fdm_extension(const char *name) { return strstr(name, "fragment_density_map") != NULL; }
+
+EXPORT VKAPI_ATTR VkResult VKAPI_CALL vkEnumerateDeviceExtensionProperties(VkPhysicalDevice pd, const char *layer,
+                                                                          uint32_t *count, VkExtensionProperties *props) {
+    pthread_once(&once, init);
+    PFN_vkEnumerateDeviceExtensionProperties real = (PFN_vkEnumerateDeviceExtensionProperties)any_fn(NULL, FN_EDEP);
+    if (!real) return VK_ERROR_INITIALIZATION_FAILED;
+    if (!hide_fdm || layer || !count) return real(pd, layer, count, props);
+    uint32_t n = 0;
+    VkResult r = real(pd, NULL, &n, NULL);
+    if (r != VK_SUCCESS) return r;
+    VkExtensionProperties *all = calloc(n ? n : 1, sizeof *all);
+    if (!all) return VK_ERROR_OUT_OF_HOST_MEMORY;
+    r = real(pd, NULL, &n, all);
+    if (r < 0) { free(all); return r; }
+    uint32_t kept = 0;
+    for (uint32_t i = 0; i < n; i++)
+        if (!is_fdm_extension(all[i].extensionName)) all[kept++] = all[i];
+    if (!props) {
+        *count = kept;
+        free(all);
+        return VK_SUCCESS;
+    }
+    uint32_t c = *count < kept ? *count : kept;
+    memcpy(props, all, c * sizeof *props);
+    *count = c;
+    free(all);
+    return c < kept ? VK_INCOMPLETE : VK_SUCCESS;
+}
+
+EXPORT VKAPI_ATTR VkResult VKAPI_CALL vkCreateDevice(VkPhysicalDevice pd, const VkDeviceCreateInfo *ci,
+                                                    const VkAllocationCallbacks *alloc, VkDevice *device) {
+    pthread_once(&once, init);
+    PFN_vkCreateDevice real = (PFN_vkCreateDevice)any_fn(NULL, FN_CDEV);
+    if (!real) return VK_ERROR_INITIALIZATION_FAILED;
+    if (!ci || (!hide_fdm && !spec_fixes)) return real(pd, ci, alloc, device);
+    char names[1024] = "";
+    VkDeviceCreateInfo copy = *ci;
+    const char **kept = calloc(ci->enabledExtensionCount + 1, sizeof *kept);
+    if (!kept) return VK_ERROR_OUT_OF_HOST_MEMORY;
+    copy.enabledExtensionCount = 0;
+    for (uint32_t i = 0; i < ci->enabledExtensionCount; i++) {
+        const char *e = ci->ppEnabledExtensionNames[i];
+        size_t len = strlen(names);
+        snprintf(names + len, sizeof names - len, "%s%s", len ? " " : "", e + (strncmp(e, "VK_", 3) ? 0 : 3));
+        if (hide_fdm && is_fdm_extension(e)) continue;
+        kept[copy.enabledExtensionCount++] = e;
+    }
+    copy.ppEnabledExtensionNames = kept;
+    LOG("vk shim: vkCreateDevice with %u extension(s): %s", ci->enabledExtensionCount, names);
+    VkResult r = real(pd, &copy, alloc, device);
+    free(kept);
+    return r;
+}
+
+static int null_views_logged;
+
+// An image view of VK_NULL_HANDLE crashes the Frame's Turnip (it reads the image); with vk_spec_fixes it fails with
+// an error instead, which names the call in the game's own log.
+static VKAPI_ATTR VkResult VKAPI_CALL create_image_view(VkDevice device, const VkImageViewCreateInfo *ci,
+                                                       const VkAllocationCallbacks *alloc, VkImageView *view) {
+    PFN_vkCreateImageView real = (PFN_vkCreateImageView)any_fn(device, FN_CIV);
+    if (!real) return VK_ERROR_INITIALIZATION_FAILED;
+    if (!ci || ci->image) return real(device, ci, alloc, view);
+    if (null_views_logged++ < 10)
+        LOG("vk shim: refused an image view without an image (format %d, view type %d, aspect 0x%x, layers %u)",
+            ci->format, ci->viewType, ci->subresourceRange.aspectMask, ci->subresourceRange.layerCount);
+    if (view) *view = VK_NULL_HANDLE;
+    return VK_ERROR_INITIALIZATION_FAILED;
+}
+
+// ---------------------------------------------------------------- image barriers without an image (vk_spec_fixes)
+
+// Unreal 5 (e.g. Metro Awakening) records image memory barriers whose image is VK_NULL_HANDLE (invalid Vulkan,
+// VUID-VkImageMemoryBarrier-image-parameter). Quest's driver skips them; the Frame's Turnip reads the image and
+// crashes in vkCmdPipelineBarrier. They change nothing, so they are left out.
+static int null_barriers_logged;
+
+// The barriers without the ones naming no image: `src` itself when there are none, else a copy in `buf` (or a malloc'd
+// one in *heap, which the caller frees); *count is updated.
+static const void *without_null_images(const void *src, uint32_t *count, size_t size, size_t image_offset, void *buf,
+                                       size_t buf_size, void **heap) {
+    uint32_t n = *count, kept = 0;
+    for (uint32_t i = 0; i < n; i++)
+        if (*(const uint64_t *)((const char *)src + i * size + image_offset)) kept++;
+    if (kept == n) return src;
+    char *out = n * size <= buf_size ? buf : (*heap = malloc(n * size));
+    if (!out) return src;
+    for (uint32_t i = 0, j = 0; i < n; i++)
+        if (*(const uint64_t *)((const char *)src + i * size + image_offset)) memcpy(out + j++ * size, (const char *)src + i * size, size);
+    if (null_barriers_logged++ < 5) {
+        // in both barrier versions oldLayout/newLayout sit 16 bytes before the image, the subresource range 8 after it
+        const char *first = NULL;
+        for (uint32_t i = 0; i < n && !first; i++)
+            if (!*(const uint64_t *)((const char *)src + i * size + image_offset)) first = (const char *)src + i * size;
+        const uint32_t *layouts = (const uint32_t *)(first + image_offset - 16);  // oldLayout, newLayout, srcQFI, dstQFI
+        const uint32_t *range = (const uint32_t *)(first + image_offset + 8);     // aspect, mip, levels, layer, layers
+        LOG("vk shim: left out %u image barrier(s) without an image (first: layout %u -> %u, aspect 0x%x, layers %u)",
+            n - kept, layouts[0], layouts[1], range[0], range[4]);
+    }
+    *count = kept;
+    return out;
+}
+
+static VKAPI_ATTR void VKAPI_CALL cmd_pipeline_barrier(VkCommandBuffer cb, VkPipelineStageFlags src, VkPipelineStageFlags dst,
+                                                       VkDependencyFlags flags, uint32_t memory_count,
+                                                       const VkMemoryBarrier *memory, uint32_t buffer_count,
+                                                       const VkBufferMemoryBarrier *buffers, uint32_t image_count,
+                                                       const VkImageMemoryBarrier *images) {
+    PFN_vkCmdPipelineBarrier real = (PFN_vkCmdPipelineBarrier)any_fn(NULL, FN_PB);
+    if (!real) return;
+    VkImageMemoryBarrier buf[16];
+    void *heap = NULL;
+    const VkImageMemoryBarrier *kept = images && image_count
+        ? without_null_images(images, &image_count, sizeof *images, offsetof(VkImageMemoryBarrier, image), buf, sizeof buf, &heap)
+        : images;
+    real(cb, src, dst, flags, memory_count, memory, buffer_count, buffers, image_count, kept);
+    free(heap);
+}
+
+static void pipeline_barrier2(VkCommandBuffer cb, const VkDependencyInfo *info, int which) {
+    PFN_vkCmdPipelineBarrier2 real = (PFN_vkCmdPipelineBarrier2)any_fn(NULL, which);
+    if (!real) return;
+    if (!info || !info->pImageMemoryBarriers || !info->imageMemoryBarrierCount) {
+        real(cb, info);
+        return;
+    }
+    VkImageMemoryBarrier2 buf[16];
+    void *heap = NULL;
+    VkDependencyInfo copy = *info;
+    copy.pImageMemoryBarriers = without_null_images(info->pImageMemoryBarriers, &copy.imageMemoryBarrierCount,
+                                                    sizeof *buf, offsetof(VkImageMemoryBarrier2, image), buf, sizeof buf, &heap);
+    real(cb, &copy);
+    free(heap);
+}
+
+static VKAPI_ATTR void VKAPI_CALL cmd_pipeline_barrier2(VkCommandBuffer cb, const VkDependencyInfo *info) {
+    pipeline_barrier2(cb, info, FN_PB2);
+}
+
+static VKAPI_ATTR void VKAPI_CALL cmd_pipeline_barrier2_khr(VkCommandBuffer cb, const VkDependencyInfo *info) {
+    pipeline_barrier2(cb, info, FN_PB2KHR);
+}
+
 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 +889,26 @@ 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;
+    case FN_PB: return spec_fixes ? (PFN_vkVoidFunction)cmd_pipeline_barrier : NULL;
+    case FN_PB2: return spec_fixes ? (PFN_vkVoidFunction)cmd_pipeline_barrier2 : NULL;
+    case FN_PB2KHR: return spec_fixes ? (PFN_vkVoidFunction)cmd_pipeline_barrier2_khr : NULL;
+    case FN_EDEP: return hide_fdm ? (PFN_vkVoidFunction)vkEnumerateDeviceExtensionProperties : NULL;
+    case FN_CDEV: return hide_fdm || spec_fixes ? (PFN_vkVoidFunction)vkCreateDevice : NULL;
+    case FN_CIV: return spec_fixes ? (PFN_vkVoidFunction)create_image_view : 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 +930,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 +940,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;
 }
@@ -11,6 +11,7 @@
 using ovrResult = int32_t;
 constexpr ovrResult Success = 0, NotInitialized = -1004, InvalidParameter = -1005,
    DeviceUnavailable = -1010, InvalidOperation = -1015, Unsupported = -1050, NoDevice = -1051;
+struct ovrEventHeader { int32_t EventType; };  // VrApi_Types.h: followed by event-specific data
 struct ovrJava { JavaVM* Vm; JNIEnv* Env; jobject ActivityObject; };
 struct ovrVector2f { float x, y; };
 struct ovrVector3f { float x, y, z; };
@@ -1361,7 +1361,8 @@ namespace {
 constexpr int64_t kFormat8888 = 4, kFormat8888Srgb = 5, kFormatRgba16f = 6;
 }

-VRAPI ovrTextureSwapChain* vrapi_CreateTextureSwapChain2(int32_t type, int64_t format, int width, int height,
+// format: VrApi's 32-bit ovrTextureFormat enum (only vrapi_CreateTextureSwapChain3 takes a 64-bit format)
+VRAPI ovrTextureSwapChain* vrapi_CreateTextureSwapChain2(int32_t type, int32_t format, int width, int height,
                                                          int levels, int bufferCount) {
    ovp::Runtime& s = ovp::runtime();
    std::lock_guard<std::recursive_mutex> lock(s.mutex);
@@ -1413,7 +1414,7 @@ VRAPI ovrTextureSwapChain* vrapi_CreateTextureSwapChain2(int32_t type, int64_t f
    return chain;
 }

-VRAPI ovrTextureSwapChain* vrapi_CreateTextureSwapChain(int32_t type, int64_t format, int width, int height,
+VRAPI ovrTextureSwapChain* vrapi_CreateTextureSwapChain(int32_t type, int32_t format, int width, int height,
                                                         int levels, bool buffered) {
    return vrapi_CreateTextureSwapChain2(type, format, width, height, levels, buffered ? 3 : 1);
 }
@@ -426,11 +426,43 @@ void sync() {
 }
 } // namespace ovp::input

+// Input diagnostics: every 5 s, how the game uses the controller API (FramePort, e.g. BlazeRush's untracked
+// controllers): call counts, the last tracking status/position per hand, and the vibration amplitudes it asked for.
+namespace ovp::input::diag {
+struct Counters {
+    uint32_t enumerate = 0, caps = 0, state = 0, tracking = 0, trackingFail = 0, haptic = 0;
+    uint32_t stateTypes = 0, capsTypes = 0, stateRefused = 0, buttons = 0;  // ControllerType bits asked for
+    float stickMax[HandCount] = {};
+    uint32_t lastStatus[HandCount] = {};
+    float lastPos[HandCount][3] = {};
+    float hapticMin = 2.0f, hapticMax = -1.0f;
+    double lastTime = 0, lastLog = 0;
+};
+static Counters c;
+static void maybeLog() {
+    const double now = ovp::secondsNow();
+    if (c.lastLog == 0) c.lastLog = now;
+    if (now - c.lastLog < 5.0) return;
+    OVP_LOG("input 5s: enumerate=%u caps=%u state=%u tracking=%u (failed %u, time %.3f vs now %.3f) "
+            "L status=0x%x pos=%.2f,%.2f,%.2f R status=0x%x pos=%.2f,%.2f,%.2f haptic=%u amp %.2f..%.2f",
+            c.enumerate, c.caps, c.state, c.tracking, c.trackingFail, c.lastTime, now,
+            c.lastStatus[Left], c.lastPos[Left][0], c.lastPos[Left][1], c.lastPos[Left][2],
+            c.lastStatus[Right], c.lastPos[Right][0], c.lastPos[Right][1], c.lastPos[Right][2],
+            c.haptic, c.haptic ? c.hapticMin : 0.0f, c.haptic ? c.hapticMax : 0.0f);
+    OVP_LOG("input 5s: state types asked 0x%x (refused %u), caps types 0x%x, buttons seen 0x%x, stick max L %.2f R %.2f",
+            c.stateTypes, c.stateRefused, c.capsTypes, c.buttons, c.stickMax[Left], c.stickMax[Right]);
+    const double last = now;
+    c = {};
+    c.lastLog = last;
+}
+} // namespace ovp::input::diag
+
 VRAPI ovrResult vrapi_EnumerateInputDevices(ovrMobile* mobile, uint32_t index,
                                             ovrInputCapabilityHeader* capsHeader) {
    ovp::Runtime& s = ovp::runtime();
    std::lock_guard<std::recursive_mutex> lock(s.mutex);
    if (capsHeader == nullptr) return InvalidParameter;
+    ++ovp::input::diag::c.enumerate;
    if (!ovp::validMobile(mobile) || !ovp::input::ready()) return NotInitialized;
    uint32_t connectedIndex = 0;
    for (size_t hand = 0; hand < ovp::input::HandCount; ++hand) {
@@ -450,6 +482,8 @@ VRAPI ovrResult vrapi_GetInputDeviceCapabilities(ovrMobile* mobile,
    std::lock_guard<std::recursive_mutex> lock(s.mutex);
    if (capsHeader == nullptr) return InvalidParameter;
    if (!ovp::validMobile(mobile) || !ovp::input::ready()) return NotInitialized;
+    ++ovp::input::diag::c.caps;
+    ovp::input::diag::c.capsTypes |= static_cast<uint32_t>(capsHeader->Type);
    if (capsHeader->Type != ovrControllerType_TrackedRemote) return Unsupported;
    size_t hand = 0;
    ovp::input::Hand* value = ovp::input::handForId(capsHeader->DeviceID, &hand);
@@ -478,7 +512,13 @@ VRAPI ovrResult vrapi_GetCurrentInputState(ovrMobile* mobile, ovrDeviceID device
    std::lock_guard<std::recursive_mutex> lock(s.mutex);
    if (inputState == nullptr) return InvalidParameter;
    if (!ovp::validMobile(mobile) || !ovp::input::ready()) return NotInitialized;
-    if (inputState->ControllerType != ovrControllerType_TrackedRemote) return Unsupported;
+    ++ovp::input::diag::c.state;
+    ovp::input::diag::c.stateTypes |= static_cast<uint32_t>(inputState->ControllerType);
+    ovp::input::diag::maybeLog();
+    if (inputState->ControllerType != ovrControllerType_TrackedRemote) {
+        ++ovp::input::diag::c.stateRefused;
+        return Unsupported;
+    }
    ovp::input::Hand* hand = ovp::input::handForId(deviceID);
    if (hand == nullptr) return NoDevice;
    auto* state = reinterpret_cast<ovrInputStateTrackedRemote*>(inputState);
@@ -489,6 +529,12 @@ VRAPI ovrResult vrapi_GetCurrentInputState(ovrMobile* mobile, ovrDeviceID device
        return DeviceUnavailable;
    }
    *state = hand->state;
+    {
+        auto& d = ovp::input::diag::c;
+        size_t i = hand == &ovp::input::g.hands[ovp::input::Left] ? ovp::input::Left : ovp::input::Right;
+        d.buttons |= state->Buttons;
+        d.stickMax[i] = std::max(d.stickMax[i], std::max(std::fabs(state->Joystick.x), std::fabs(state->Joystick.y)));
+    }
    return Success;
 }

@@ -507,9 +553,18 @@ VRAPI ovrResult vrapi_GetInputTrackingState(ovrMobile* mobile, ovrDeviceID devic
    if (!hand->active) return DeviceUnavailable;
    const double requestedSeconds = absTimeInSeconds == 0.0 ? ovp::secondsNow() : absTimeInSeconds;
    const XrTime requestedTime = ovp::toXrTime(requestedSeconds);
+    auto& d = ovp::input::diag::c;
+    ++d.tracking;
+    d.lastTime = requestedSeconds;
+    ovp::input::diag::maybeLog();
    if (!ovp::locate(hand->gripSpace, requestedTime, tracking->HeadPose, tracking->Status)) {
+        ++d.trackingFail;
        return DeviceUnavailable;
    }
+    d.lastStatus[handIndex] = tracking->Status;
+    d.lastPos[handIndex][0] = tracking->HeadPose.Pose.Position.x;
+    d.lastPos[handIndex][1] = tracking->HeadPose.Pose.Position.y;
+    d.lastPos[handIndex][2] = tracking->HeadPose.Pose.Position.z;
    return Success;
 }

@@ -525,6 +580,12 @@ VRAPI ovrResult vrapi_SetHapticVibrationSimple(ovrMobile* mobile, ovrDeviceID de
    if (!hand->active) return DeviceUnavailable;

    const float amplitude = std::clamp(intensity, 0.0f, 1.0f);
+    auto& d = ovp::input::diag::c;
+    if (amplitude > 0.0f) {
+        ++d.haptic;
+        d.hapticMin = std::min(d.hapticMin, amplitude);
+        d.hapticMax = std::max(d.hapticMax, amplitude);
+    }
    if (amplitude == 0.0f) {
        XrHapticActionInfo info{XR_TYPE_HAPTIC_ACTION_INFO};
        info.action = ovp::input::g.actions.haptic;
@@ -527,6 +527,7 @@ VRAPI int vrapi_Initialize(const ovrInitParms* parms) {
    if (s.threadExtension) load("xrSetAndroidApplicationThreadKHR", reinterpret_cast<PFN_xrVoidFunction*>(&s.setThread));
    if (s.systemDisplayRefreshRateExtension) load("xrGetSystemDisplayRefreshRateAXRB", reinterpret_cast<PFN_xrVoidFunction*>(&s.getSystemDisplayRefreshRate));
    if (s.displayRefreshRateExtension) load("xrGetDisplayRefreshRateFB", reinterpret_cast<PFN_xrVoidFunction*>(&s.getDisplayRefreshRate));
+    if (s.displayRefreshRateExtension) load("xrRequestDisplayRefreshRateFB", reinterpret_cast<PFN_xrVoidFunction*>(&s.requestDisplayRefreshRate));
    if (s.glesExtension) load("xrGetOpenGLESGraphicsRequirementsKHR", reinterpret_cast<PFN_xrVoidFunction*>(&s.getGlesRequirements));
    OVP_LOG("Initialized Vulkan/GLES OpenXR adapter (gles=%d), stereo=%ux%u", s.glesExtension ? 1 : 0, s.viewConfig[0].recommendedImageRectWidth, s.viewConfig[0].recommendedImageRectHeight);
    return 0;
@@ -730,13 +731,40 @@ VRAPI ovrResult vrapi_SetClientColorDesc(ovrMobile* mobile, const ovrHmdColorDes
    return xrOk(s.setColorSpace(s.session, static_cast<XrColorSpaceFB>(color->ColorSpace)), "xrSetColorSpaceFB") ? Success : InvalidParameter;
 }

-VRAPI void vrapi_SetTrackingSpace(ovrMobile* mobile, int32_t space) {
-    // Tracking-space changes (eye/floor level) are handled by the app's own poses; accept and ignore.
+VRAPI ovrResult vrapi_SetTrackingSpace(ovrMobile* mobile, int32_t space) {
+    // Tracking-space changes (eye/floor level) are handled by the app's own poses; accept and ignore. VrApi returns an
+    // ovrResult here: a void function left the caller reading whatever was in w0.
    (void)mobile;
    OVP_LOG("vrapi_SetTrackingSpace(%d) ignored", space);
+    return Success;
 }
 VRAPI bool vrapi_ShowSystemUI(const ovrJava* java, int32_t type) {
    (void)java;
    OVP_LOG("vrapi_ShowSystemUI(%d) unsupported", type);
    return false;
 }
+
+// Functions some engines import even when they never rely on them (e.g. BlazeRush's libtargemapp.so): a missing one
+// stops the game from loading at all ("cannot locate symbol").
+VRAPI ovrResult vrapi_PollEvent(ovrEventHeader* event) {
+    // No VrApi events are produced: VRAPI_EVENT_NONE + ovrSuccess_EventUnavailable ends the app's polling loop.
+    if (event) event->EventType = 0;
+    return 1002;  // ovrSuccess_EventUnavailable
+}
+VRAPI void vrapi_RecenterPose(ovrMobile* mobile) {
+    // Deprecated in VrApi; OpenXR has no application recenter (the runtime's own recenter is reported via status 13).
+    (void)mobile;
+    OVP_LOG("vrapi_RecenterPose ignored");
+}
+VRAPI ovrResult vrapi_SetDisplayRefreshRate(ovrMobile* mobile, float rate) {
+    LOCK_STATE;
+    if (!validMobile(mobile)) return NotInitialized;
+    if (!s.requestDisplayRefreshRate || !s.session) return Unsupported;
+    return xrOk(s.requestDisplayRefreshRate(s.session, rate), "xrRequestDisplayRefreshRateFB") ? Success : InvalidParameter;
+}
+VRAPI int vrapi_GetSystemPropertyFloatArray(const ovrJava*, int property, float* values, int count) {
+    // The only array property is the supported refresh rates; its count property is 0 here, so report none.
+    (void)values;
+    OVP_LOG("Float array system property %d (%d values) unsupported", property, count);
+    return 0;
+}
@@ -80,6 +80,7 @@ struct Runtime {
    PFN_xrSetAndroidApplicationThreadKHR setThread = nullptr;
    PFN_axrbGetSystemDisplayRefreshRate getSystemDisplayRefreshRate = nullptr;
    PFN_xrGetDisplayRefreshRateFB getDisplayRefreshRate = nullptr;
+    PFN_xrRequestDisplayRefreshRateFB requestDisplayRefreshRate = nullptr;
    DisplayRefreshRateSource loggedDisplayRefreshRateSource = DisplayRefreshRateSource::Unqueried;
    float loggedDisplayRefreshRate = 0;
    ovrPosef trackingTransform{{0, 0, 0, 1}, {0, 0, 0}};
@@ -1,8 +1,14 @@
-diff --git a/native/vrapi/abi.h b/native/vrapi/abi.h
-index 975698a..c9a2a9d 100644
 --- a/native/vrapi/abi.h
 +++ b/native/vrapi/abi.h
-@@ -62,6 +62,17 @@ struct ovrLayerProjection2 {
+@@ -11,6 +11,7 @@
+ using ovrResult = int32_t;
+ constexpr ovrResult Success = 0, NotInitialized = -1004, InvalidParameter = -1005,
+     DeviceUnavailable = -1010, InvalidOperation = -1015, Unsupported = -1050, NoDevice = -1051;
+struct ovrEventHeader { int32_t EventType; };  // VrApi_Types.h: followed by event-specific data
+ struct ovrJava { JavaVM* Vm; JNIEnv* Env; jobject ActivityObject; };
+ struct ovrVector2f { float x, y; };
+ struct ovrVector3f { float x, y, z; };
+@@ -62,6 +63,17 @@
         ovrRectf TextureRect;
     } Textures[2];
 };
@@ -20,7 +26,7 @@ index 975698a..c9a2a9d 100644
 struct ovrSubmitFrameDescription2 {
     uint32_t Flags, SwapInterval;
     uint64_t FrameIndex;
-@@ -77,3 +88,4 @@ static_assert(sizeof(ovrRigidBodyPosef) == 96 && sizeof(ovrTracking2) == 360);
+@@ -77,3 +89,4 @@
 static_assert(sizeof(ovrTracking) == 104 && sizeof(ovrLayerHeader2) == 40);
 static_assert(sizeof(ovrLayerProjection2) == 328 && sizeof(ovrSubmitFrameDescription2) == 48);
 static_assert(offsetof(ovrLayerProjection2, Textures) == 136);
@@ -1,5 +1,5 @@
--- graphics.cpp.orig	2026-09-28 17:20:25.629612301 -0400
-+++ graphics.cpp	2026-09-28 18:50:49.704207711 -0400
+--- graphics.cpp.orig
+++ graphics.cpp
@@ -1,6 +1,9 @@
 // SPDX-License-Identifier: GPL-3.0-only
 #include "runtime.h"
@@ -102,7 +102,43 @@
 
     uint32_t formatCount = 0;
     XrResult result = s.xr.xrEnumerateSwapchainFormats(s.session, 0, &formatCount, nullptr);
-@@ -502,8 +572,104 @@
+@@ -331,12 +401,29 @@
+         ovp::xrOk(result, "xrEnumerateSwapchainFormats");
+         return false;
+     }
+-    const int64_t wanted = static_cast<int64_t>(chain->format);
+-    if (std::find(formats.begin(), formats.begin() + formatCount, wanted) ==
+-        formats.begin() + formatCount) {
+-        OVP_ERROR("OpenXR runtime does not expose requested VkFormat %lld",
+-                  static_cast<long long>(wanted));
+-        return false;
+    int64_t wanted = static_cast<int64_t>(chain->format);
+    auto exposed = [&](int64_t f) {
+        return std::find(formats.begin(), formats.begin() + formatCount, f) != formats.begin() + formatCount;
+    };
+    if (!exposed(wanted)) {
+        // Steam Frame exposes only the sRGB variants. The output is filled with vkCmdCopyImage, a raw
+        // copy that is valid between size-compatible UNORM/SRGB twins, so use the twin instead.
+        int64_t twin = 0;
+        switch (wanted) {
+            case VK_FORMAT_R8G8B8A8_UNORM: twin = VK_FORMAT_R8G8B8A8_SRGB; break;
+            case VK_FORMAT_R8G8B8A8_SRGB: twin = VK_FORMAT_R8G8B8A8_UNORM; break;
+            case VK_FORMAT_B8G8R8A8_UNORM: twin = VK_FORMAT_B8G8R8A8_SRGB; break;
+            case VK_FORMAT_B8G8R8A8_SRGB: twin = VK_FORMAT_B8G8R8A8_UNORM; break;
+            default: break;
+        }
+        if (!twin || !exposed(twin)) {
+            OVP_ERROR("OpenXR runtime does not expose requested VkFormat %lld",
+                      static_cast<long long>(wanted));
+            return false;
+        }
+        OVP_LOG("Runtime lacks VkFormat %lld; using size-compatible VkFormat %lld for the output swapchain",
+                static_cast<long long>(wanted), static_cast<long long>(twin));
+        wanted = twin;
+     }
+ 
+     XrSwapchainCreateInfo create{XR_TYPE_SWAPCHAIN_CREATE_INFO};
+@@ -485,8 +572,104 @@
     return true;
 }
 
@@ -207,7 +243,7 @@
     bool black = false;
     XrCompositionLayerProjection projection{XR_TYPE_COMPOSITION_LAYER_PROJECTION};
     std::array<XrCompositionLayerProjectionView, 2> views{{
-@@ -564,7 +730,97 @@
+@@ -547,7 +730,97 @@
     return true;
 }
 
@@ -305,7 +341,7 @@
     if (!settleCopy(kFrameWaitNs, false)) return false;
     reapRetired();
     if (count == 0) return true;
-@@ -843,6 +1099,28 @@
+@@ -826,6 +1099,28 @@
     for (uint32_t i = 0; i < description->LayerCount; ++i) {
         const ovrLayerHeader2* header = description->Layers[i];
         if (!header) return failFrame(InvalidParameter);
@@ -334,7 +370,7 @@
         if (header->Type != kProjectionLayer) {
             OVP_ERROR("Unsupported VrApi layer type %d", header->Type);
             return failFrame(Unsupported);
-@@ -927,6 +1205,56 @@
+@@ -910,6 +1205,56 @@
     for (uint32_t i = 0; i < description->LayerCount; ++i) {
         PreparedLayer& output = prepared[i];
         if (output.black) continue;
@@ -391,7 +427,7 @@
         const bool headLocked = (output.source->Header.Flags & kLayerFixedToView) != 0;
         if (headLocked && !haveHeadLockedViews) {
             XrViewLocateInfo locate{XR_TYPE_VIEW_LOCATE_INFO};
-@@ -968,6 +1296,9 @@
+@@ -951,6 +1296,9 @@
                           rect.x, rect.y, rect.width, rect.height);
                 return failFrame(InvalidParameter);
             }
@@ -401,7 +437,7 @@
             output.views[eye].subImage.swapchain = chain->output;
             output.views[eye].subImage.imageArrayIndex =
                 chain->type == kTexture2DArray ? eye : 0;
-@@ -1024,3 +1355,73 @@
+@@ -1007,3 +1355,74 @@
     destroyCopyContext();
 }
 } // namespace ovp::graphics
@@ -411,7 +447,8 @@
 +constexpr int64_t kFormat8888 = 4, kFormat8888Srgb = 5, kFormatRgba16f = 6;
 +}
 +
-+VRAPI ovrTextureSwapChain* vrapi_CreateTextureSwapChain2(int32_t type, int64_t format, int width, int height,
+// format: VrApi's 32-bit ovrTextureFormat enum (only vrapi_CreateTextureSwapChain3 takes a 64-bit format)
+VRAPI ovrTextureSwapChain* vrapi_CreateTextureSwapChain2(int32_t type, int32_t format, int width, int height,
 +                                                          int levels, int bufferCount) {
 +    ovp::Runtime& s = ovp::runtime();
 +    std::lock_guard<std::recursive_mutex> lock(s.mutex);
@@ -463,7 +500,7 @@
 +    return chain;
 +}
 +
-+VRAPI ovrTextureSwapChain* vrapi_CreateTextureSwapChain(int32_t type, int64_t format, int width, int height,
+VRAPI ovrTextureSwapChain* vrapi_CreateTextureSwapChain(int32_t type, int32_t format, int width, int height,
 +                                                         int levels, bool buffered) {
 +    return vrapi_CreateTextureSwapChain2(type, format, width, height, levels, buffered ? 3 : 1);
 +}
@@ -0,0 +1,115 @@
+--- input.cpp.orig
+++ input.cpp
+@@ -426,11 +426,43 @@
+ }
+ } // namespace ovp::input
+ 
+// Input diagnostics: every 5 s, how the game uses the controller API (FramePort, e.g. BlazeRush's untracked
+// controllers): call counts, the last tracking status/position per hand, and the vibration amplitudes it asked for.
+namespace ovp::input::diag {
+struct Counters {
+    uint32_t enumerate = 0, caps = 0, state = 0, tracking = 0, trackingFail = 0, haptic = 0;
+    uint32_t stateTypes = 0, capsTypes = 0, stateRefused = 0, buttons = 0;  // ControllerType bits asked for
+    float stickMax[HandCount] = {};
+    uint32_t lastStatus[HandCount] = {};
+    float lastPos[HandCount][3] = {};
+    float hapticMin = 2.0f, hapticMax = -1.0f;
+    double lastTime = 0, lastLog = 0;
+};
+static Counters c;
+static void maybeLog() {
+    const double now = ovp::secondsNow();
+    if (c.lastLog == 0) c.lastLog = now;
+    if (now - c.lastLog < 5.0) return;
+    OVP_LOG("input 5s: enumerate=%u caps=%u state=%u tracking=%u (failed %u, time %.3f vs now %.3f) "
+            "L status=0x%x pos=%.2f,%.2f,%.2f R status=0x%x pos=%.2f,%.2f,%.2f haptic=%u amp %.2f..%.2f",
+            c.enumerate, c.caps, c.state, c.tracking, c.trackingFail, c.lastTime, now,
+            c.lastStatus[Left], c.lastPos[Left][0], c.lastPos[Left][1], c.lastPos[Left][2],
+            c.lastStatus[Right], c.lastPos[Right][0], c.lastPos[Right][1], c.lastPos[Right][2],
+            c.haptic, c.haptic ? c.hapticMin : 0.0f, c.haptic ? c.hapticMax : 0.0f);
+    OVP_LOG("input 5s: state types asked 0x%x (refused %u), caps types 0x%x, buttons seen 0x%x, stick max L %.2f R %.2f",
+            c.stateTypes, c.stateRefused, c.capsTypes, c.buttons, c.stickMax[Left], c.stickMax[Right]);
+    const double last = now;
+    c = {};
+    c.lastLog = last;
+}
+} // namespace ovp::input::diag
+
+ VRAPI ovrResult vrapi_EnumerateInputDevices(ovrMobile* mobile, uint32_t index,
+                                              ovrInputCapabilityHeader* capsHeader) {
+     ovp::Runtime& s = ovp::runtime();
+     std::lock_guard<std::recursive_mutex> lock(s.mutex);
+     if (capsHeader == nullptr) return InvalidParameter;
+    ++ovp::input::diag::c.enumerate;
+     if (!ovp::validMobile(mobile) || !ovp::input::ready()) return NotInitialized;
+     uint32_t connectedIndex = 0;
+     for (size_t hand = 0; hand < ovp::input::HandCount; ++hand) {
+@@ -450,6 +482,8 @@
+     std::lock_guard<std::recursive_mutex> lock(s.mutex);
+     if (capsHeader == nullptr) return InvalidParameter;
+     if (!ovp::validMobile(mobile) || !ovp::input::ready()) return NotInitialized;
+    ++ovp::input::diag::c.caps;
+    ovp::input::diag::c.capsTypes |= static_cast<uint32_t>(capsHeader->Type);
+     if (capsHeader->Type != ovrControllerType_TrackedRemote) return Unsupported;
+     size_t hand = 0;
+     ovp::input::Hand* value = ovp::input::handForId(capsHeader->DeviceID, &hand);
+@@ -478,7 +512,13 @@
+     std::lock_guard<std::recursive_mutex> lock(s.mutex);
+     if (inputState == nullptr) return InvalidParameter;
+     if (!ovp::validMobile(mobile) || !ovp::input::ready()) return NotInitialized;
+-    if (inputState->ControllerType != ovrControllerType_TrackedRemote) return Unsupported;
+    ++ovp::input::diag::c.state;
+    ovp::input::diag::c.stateTypes |= static_cast<uint32_t>(inputState->ControllerType);
+    ovp::input::diag::maybeLog();
+    if (inputState->ControllerType != ovrControllerType_TrackedRemote) {
+        ++ovp::input::diag::c.stateRefused;
+        return Unsupported;
+    }
+     ovp::input::Hand* hand = ovp::input::handForId(deviceID);
+     if (hand == nullptr) return NoDevice;
+     auto* state = reinterpret_cast<ovrInputStateTrackedRemote*>(inputState);
+@@ -489,6 +529,12 @@
+         return DeviceUnavailable;
+     }
+     *state = hand->state;
+    {
+        auto& d = ovp::input::diag::c;
+        size_t i = hand == &ovp::input::g.hands[ovp::input::Left] ? ovp::input::Left : ovp::input::Right;
+        d.buttons |= state->Buttons;
+        d.stickMax[i] = std::max(d.stickMax[i], std::max(std::fabs(state->Joystick.x), std::fabs(state->Joystick.y)));
+    }
+     return Success;
+ }
+ 
+@@ -507,9 +553,18 @@
+     if (!hand->active) return DeviceUnavailable;
+     const double requestedSeconds = absTimeInSeconds == 0.0 ? ovp::secondsNow() : absTimeInSeconds;
+     const XrTime requestedTime = ovp::toXrTime(requestedSeconds);
+    auto& d = ovp::input::diag::c;
+    ++d.tracking;
+    d.lastTime = requestedSeconds;
+    ovp::input::diag::maybeLog();
+     if (!ovp::locate(hand->gripSpace, requestedTime, tracking->HeadPose, tracking->Status)) {
+        ++d.trackingFail;
+         return DeviceUnavailable;
+     }
+    d.lastStatus[handIndex] = tracking->Status;
+    d.lastPos[handIndex][0] = tracking->HeadPose.Pose.Position.x;
+    d.lastPos[handIndex][1] = tracking->HeadPose.Pose.Position.y;
+    d.lastPos[handIndex][2] = tracking->HeadPose.Pose.Position.z;
+     return Success;
+ }
+ 
+@@ -525,6 +580,12 @@
+     if (!hand->active) return DeviceUnavailable;
+ 
+     const float amplitude = std::clamp(intensity, 0.0f, 1.0f);
+    auto& d = ovp::input::diag::c;
+    if (amplitude > 0.0f) {
+        ++d.haptic;
+        d.hapticMin = std::min(d.hapticMin, amplitude);
+        d.hapticMax = std::max(d.hapticMax, amplitude);
+    }
+     if (amplitude == 0.0f) {
+         XrHapticActionInfo info{XR_TYPE_HAPTIC_ACTION_INFO};
+         info.action = ovp::input::g.actions.haptic;
@@ -1,5 +1,5 @@
--- runtime.cpp.orig	2026-09-28 17:20:25.629612301 -0400
-+++ runtime.cpp	2026-09-28 17:24:17.092150139 -0400
+--- runtime.cpp.orig
+++ runtime.cpp
@@ -176,9 +176,44 @@
     }
     return true;
@@ -45,7 +45,30 @@
     if (!s.instance || !s.vk.Device) return false;
     VkPhysicalDevice expected = VK_NULL_HANDLE;
     if (!xrOk(s.xr.xrGetVulkanGraphicsDeviceKHR(s.instance, s.system, s.vk.Instance, &expected), "xrGetVulkanGraphicsDeviceKHR") || expected != s.vk.PhysicalDevice) {
-@@ -413,11 +448,14 @@
+@@ -246,12 +281,16 @@
+         // OpenXR LOCAL need not be eye-level. Establish VrApi's initial yaw/position
+         // origin from a tracked, visible head before exposing it to the application.
+         XrSpaceLocation head{XR_TYPE_SPACE_LOCATION};
+-        constexpr XrSpaceLocationFlags tracked =
+-            XR_SPACE_LOCATION_ORIENTATION_VALID_BIT | XR_SPACE_LOCATION_POSITION_VALID_BIT |
+-            XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT | XR_SPACE_LOCATION_POSITION_TRACKED_BIT;
+-        if ((s.sessionState != XR_SESSION_STATE_VISIBLE && s.sessionState != XR_SESSION_STATE_FOCUSED) ||
+-            !xrOk(s.xr.xrLocateSpace(s.viewSpace, s.localSpace, s.frame.predictedDisplayTime, &head), "initial eye-level origin") ||
+-            (head.locationFlags & tracked) != tracked) {
+        // Steam Frame reports poses as VALID without the TRACKED bits here, so only validity is required.
+        constexpr XrSpaceLocationFlags tracked = XR_SPACE_LOCATION_ORIENTATION_VALID_BIT | XR_SPACE_LOCATION_POSITION_VALID_BIT;
+        const bool visible = s.sessionState == XR_SESSION_STATE_VISIBLE || s.sessionState == XR_SESSION_STATE_FOCUSED;
+        const bool located = visible &&
+            xrOk(s.xr.xrLocateSpace(s.viewSpace, s.localSpace, s.frame.predictedDisplayTime, &head), "initial eye-level origin");
+        static int logged;
+        if (visible && logged++ % 90 == 0)
+            OVP_LOG("initial recenter: head flags=0x%llx pos=%.3f,%.3f,%.3f", (unsigned long long)head.locationFlags,
+                    head.pose.position.x, head.pose.position.y, head.pose.position.z);
+        if (!located || (head.locationFlags & tracked) != tracked) {
+             endFrame(nullptr, 0);
+             return false;
+         }
+@@ -409,11 +448,14 @@
 VRAPI int vrapi_Initialize(const ovrInitParms* parms) {
     LOCK_STATE;
     if (s.instance) return -3;
@@ -62,7 +85,7 @@
     s.activity = parms->Java.Env->NewGlobalRef(parms->Java.ActivityObject);
     if (!s.activity) { shutdown(); return -1; }
     s.loader = dlopen("libopenxr_loader.so", RTLD_NOW | RTLD_LOCAL);
-@@ -439,10 +477,13 @@
+@@ -435,10 +477,13 @@
     if (!xrOk(s.xr.xrEnumerateInstanceExtensionProperties(nullptr, count, &count, supported.data()), "enumerate extensions")) { shutdown(); return -4; }
     auto has = [&](const char* name) { return std::any_of(supported.begin(), supported.end(), [&](const auto& e) { return std::strcmp(e.extensionName, name) == 0; }); };
     std::vector<const char*> extensions;
@@ -80,17 +103,18 @@
     s.viewConfigurationFovExtension = has(XR_EPIC_VIEW_CONFIGURATION_FOV_EXTENSION_NAME);
     if (s.viewConfigurationFovExtension) extensions.push_back(XR_EPIC_VIEW_CONFIGURATION_FOV_EXTENSION_NAME);
     s.systemDisplayRefreshRateExtension = has(SystemDisplayRefreshRateExtension);
-@@ -486,7 +527,8 @@
+@@ -482,7 +527,9 @@
     if (s.threadExtension) load("xrSetAndroidApplicationThreadKHR", reinterpret_cast<PFN_xrVoidFunction*>(&s.setThread));
     if (s.systemDisplayRefreshRateExtension) load("xrGetSystemDisplayRefreshRateAXRB", reinterpret_cast<PFN_xrVoidFunction*>(&s.getSystemDisplayRefreshRate));
     if (s.displayRefreshRateExtension) load("xrGetDisplayRefreshRateFB", reinterpret_cast<PFN_xrVoidFunction*>(&s.getDisplayRefreshRate));
 -    OVP_LOG("Initialized Vulkan/OpenXR adapter, stereo=%ux%u", s.viewConfig[0].recommendedImageRectWidth, s.viewConfig[0].recommendedImageRectHeight);
+    if (s.displayRefreshRateExtension) load("xrRequestDisplayRefreshRateFB", reinterpret_cast<PFN_xrVoidFunction*>(&s.requestDisplayRefreshRate));
 +    if (s.glesExtension) load("xrGetOpenGLESGraphicsRequirementsKHR", reinterpret_cast<PFN_xrVoidFunction*>(&s.getGlesRequirements));
 +    OVP_LOG("Initialized Vulkan/GLES OpenXR adapter (gles=%d), stereo=%ux%u", s.glesExtension ? 1 : 0, s.viewConfig[0].recommendedImageRectWidth, s.viewConfig[0].recommendedImageRectHeight);
     return 0;
 }
 VRAPI void vrapi_Shutdown() { LOCK_STATE; shutdown(); }
-@@ -522,9 +564,27 @@
+@@ -518,18 +565,36 @@
 }
 VRAPI ovrMobile* vrapi_EnterVrMode(const ovrModeParms* parms) {
     LOCK_STATE;
@@ -119,20 +143,59 @@
 +    }
 +    if (!ensureSession(queue)) return nullptr;
     // Runtime READY can arrive asynchronously. Wait only for a bounded lifecycle transition.
-     auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds(30);  // Frame: session reaches FOCUSED and first tracked pose later than Quest
+-    auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds(5);
+    auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds(30);  // Frame: session reaches FOCUSED and first tracked pose later than Quest
     while (!s.running) {
-@@ -669,3 +729,14 @@
+-        if (!pollEvents() || std::chrono::steady_clock::now() >= deadline) { destroySession(); return nullptr; }
+        if (!pollEvents() || std::chrono::steady_clock::now() >= deadline) { OVP_LOG("EnterVrMode: session never started running"); destroySession(); return nullptr; }
+         if (!s.running) std::this_thread::sleep_for(std::chrono::milliseconds(5));
+     }
+     while (s.initialRecenterPending) {
+         if (beginFrame(s.frameIndex + 1)) break;
+-        if (std::chrono::steady_clock::now() >= deadline) { destroySession(); return nullptr; }
+        if (std::chrono::steady_clock::now() >= deadline) { OVP_LOG("EnterVrMode: no tracked head pose before deadline"); destroySession(); return nullptr; }
+         std::this_thread::sleep_for(std::chrono::milliseconds(5));
+     }
+     ++s.mobile.generation;
+@@ -665,3 +730,41 @@
     if (!s.setColorSpace) return color->ColorSpace == 0 ? Success : Unsupported;
     return xrOk(s.setColorSpace(s.session, static_cast<XrColorSpaceFB>(color->ColorSpace)), "xrSetColorSpaceFB") ? Success : InvalidParameter;
 }
 +
-+VRAPI void vrapi_SetTrackingSpace(ovrMobile* mobile, int32_t space) {
-+    // Tracking-space changes (eye/floor level) are handled by the app's own poses; accept and ignore.
+VRAPI ovrResult vrapi_SetTrackingSpace(ovrMobile* mobile, int32_t space) {
+    // Tracking-space changes (eye/floor level) are handled by the app's own poses; accept and ignore. VrApi returns an
+    // ovrResult here: a void function left the caller reading whatever was in w0.
 +    (void)mobile;
 +    OVP_LOG("vrapi_SetTrackingSpace(%d) ignored", space);
+    return Success;
 +}
 +VRAPI bool vrapi_ShowSystemUI(const ovrJava* java, int32_t type) {
 +    (void)java;
 +    OVP_LOG("vrapi_ShowSystemUI(%d) unsupported", type);
 +    return false;
 +}
+
+// Functions some engines import even when they never rely on them (e.g. BlazeRush's libtargemapp.so): a missing one
+// stops the game from loading at all ("cannot locate symbol").
+VRAPI ovrResult vrapi_PollEvent(ovrEventHeader* event) {
+    // No VrApi events are produced: VRAPI_EVENT_NONE + ovrSuccess_EventUnavailable ends the app's polling loop.
+    if (event) event->EventType = 0;
+    return 1002;  // ovrSuccess_EventUnavailable
+}
+VRAPI void vrapi_RecenterPose(ovrMobile* mobile) {
+    // Deprecated in VrApi; OpenXR has no application recenter (the runtime's own recenter is reported via status 13).
+    (void)mobile;
+    OVP_LOG("vrapi_RecenterPose ignored");
+}
+VRAPI ovrResult vrapi_SetDisplayRefreshRate(ovrMobile* mobile, float rate) {
+    LOCK_STATE;
+    if (!validMobile(mobile)) return NotInitialized;
+    if (!s.requestDisplayRefreshRate || !s.session) return Unsupported;
+    return xrOk(s.requestDisplayRefreshRate(s.session, rate), "xrRequestDisplayRefreshRateFB") ? Success : InvalidParameter;
+}
+VRAPI int vrapi_GetSystemPropertyFloatArray(const ovrJava*, int property, float* values, int count) {
+    // The only array property is the supported refresh rates; its count property is 0 here, so report none.
+    (void)values;
+    OVP_LOG("Float array system property %d (%d values) unsupported", property, count);
+    return 0;
+}
@@ -1,5 +1,5 @@
--- runtime.h.orig	2026-09-28 17:20:25.629612301 -0400
-+++ runtime.h	2026-09-28 17:20:25.629612301 -0400
+--- runtime.h.orig
+++ runtime.h
@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 #pragma once
@@ -21,3 +21,11 @@
     VkQueue queue = VK_NULL_HANDLE;
     uint32_t queueFamily = 0;
     double timeOffset = 0;
+@@ -73,6 +80,7 @@
+     PFN_xrSetAndroidApplicationThreadKHR setThread = nullptr;
+     PFN_axrbGetSystemDisplayRefreshRate getSystemDisplayRefreshRate = nullptr;
+     PFN_xrGetDisplayRefreshRateFB getDisplayRefreshRate = nullptr;
+    PFN_xrRequestDisplayRefreshRateFB requestDisplayRefreshRate = nullptr;
+     DisplayRefreshRateSource loggedDisplayRefreshRateSource = DisplayRefreshRateSource::Unqueried;
+     float loggedDisplayRefreshRate = 0;
+     ovrPosef trackingTransform{{0, 0, 0, 1}, {0, 0, 0}};
@@ -7,11 +7,20 @@
 // 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.
+// Upstream: ovrport/app#73; tracked in FramePort GitHub #74.
 #include <openxr/openxr.h>
 #include <android/log.h>
 #include <dlfcn.h>
 #include <pthread.h>
+#include <math.h>
 #include <stddef.h>
+#include <string.h>

 #define TAG "FrameBridge"
 #define EXPORT __attribute__((visibility("default")))
@@ -40,9 +49,41 @@ 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;
+        // the envelope's energy (RMS), not its peak: a short fading pulse held at its peak for the whole duration
+        // felt far stronger than on a Quest (The Boys VR, Jurassic World, BONELAB)
+        double sum = 0.0;
+        for (uint32_t i = 0; env->amplitudes && i < env->amplitudeCount; ++i)
+            sum += (double)env->amplitudes[i] * env->amplitudes[i];
+        float rms = env->amplitudeCount ? (float)sqrt(sum / env->amplitudeCount) : 0.0f;
+        XrHapticVibration plain = {XR_TYPE_HAPTIC_VIBRATION, NULL, env->duration, XR_FREQUENCY_UNSPECIFIED,
+                                   rms > 1.0f ? 1.0f : rms};
+        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",
@@ -116,17 +182,41 @@ class FakeKeyboardSession:
        self.closed = True


-def open_type_dialog(app: FramePortApp) -> None:
-    """Type on Frame over the Steam Frame page, with one key 'pressed' so the screenshot shows it working."""
-    from types import SimpleNamespace
-
-    app.navigate(1)
-    time.sleep(1.5)
+def open_type_tab(app: FramePortApp) -> None:
+    """The Type on Frame tab, with one key 'pressed' so the screenshot shows it working."""
    app.type_on_frame()
    time.sleep(1.5)
-    dialog = [d for d in app.page._dialogs.controls if d.open][-1]
-    listener = dialog.content.controls[1]
-    listener.on_key_down(SimpleNamespace(key="Enter"))
+    app.keyboard_view.press("Enter")
+
+
+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 +233,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 +276,18 @@ 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")
+    ap.add_argument("--links", action="store_true", help="install links: the Add games menu, the paste dialog, the "
+                    "confirmation for a pretend FrameDrop manifest, Settings → Install links and (with --game) the "
+                    "VR / flat window choice")
    args = ap.parse_args()
+    if args.linux:
+        add_fake_linux_apps()
    global STEP_SECONDS
    if args.hover:
        STEP_SECONDS = 7
@@ -169,7 +298,9 @@ 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")), ("keyboard", lambda a: a.go("keyboard")),
+             ("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)))
@@ -188,7 +319,113 @@ 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_tab(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.links:
+        from frameport import deeplink
+        from frameport.ui.views import link_dialog
+
+        fake = deeplink.Manifest("Example Game", [
+            deeplink.ManifestFile("https://cdn.example.com/example-game-arm64.apk", "ab" * 32),
+            deeplink.ManifestFile("https://cdn.example.com/main.1.com.example.game.obb")],
+            "https://example.com/example-game.framedrop.json",
+            description="A puzzle adventure across floating islands: build bridges, bend light and find your way home. "
+                        "Room-scale or seated, with smooth or snap turning.",
+            icon="https://example.com/icon.png")
+        sizes = {fake.files[0].url: 412_000_000, fake.files[1].url: 1_900_000_000}
+        from PIL import Image, ImageDraw
+
+        from frameport.core.paths import user_data_dir
+
+        icon = user_data_dir() / "downloads" / "icons" / "smoke-example.png"  # a stand-in for the downloaded icon
+        icon.parent.mkdir(parents=True, exist_ok=True)
+        im = Image.new("RGBA", (256, 256), (0, 0, 0, 0))
+        ImageDraw.Draw(im).rounded_rectangle((8, 8, 248, 248), 48, fill=(124, 92, 255, 255))
+        ImageDraw.Draw(im).ellipse((72, 72, 184, 184), fill=(255, 214, 102, 255))
+        im.save(icon)
+
+        def add_menu(a):
+            a.navigate(0)
+            time.sleep(2)
+        steps = [("library", add_menu),
+                 ("links-paste", lambda a: a.pick_link()),
+                 ("links-confirm", lambda a: (a.page.pop_dialog(), link_dialog._confirm(a, fake, sizes, False, icon))),
+                 ("links-settings", lambda a: (a.page.pop_dialog(), a.go("settings")))]
+        if game:
+            steps.append(("links-display-mode", lambda a: a.open_game(game, advanced=True)))
+        def add_menu_open(page):
+            page.mouse.click(1194, 94)  # Add games (1280-wide viewport)
+            time.sleep(2)
+            page.screenshot(path=str(args.out / "library-add-menu.png"))
+            page.mouse.click(120, 520)  # outside the menu (Flutter's popup ignores Escape)
+        mouse["library"] = add_menu_open  # tall pages: run with e.g. --viewport 1280x3200
+    if args.usb_setup:
+        def continue_usb(a):
+            dialog = [d for d in a.page._dialogs.controls if d.open and type(d).__name__ == "AlertDialog"][-1]
+            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] = []

@@ -280,6 +517,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.8.0"
+__version__ = "0.12.0"
@@ -179,7 +179,18 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
        debuggable=bool(axml.Axml(manifest).get_bool("application", "debuggable")),
        extra={
            "frame_patched": "libframe_settings.so" in libset,  # already has FramePort's FrameBridge adapter
+            # Team Beef's TBXR ports pick their OpenXR path by headset maker (frame.tbxr_vendor): their libraries
+            # the game asks Meta's platform for asset files (content shipped as separate files, frame.asset_files)
+            "asset_file_api": any(b"\0ovr_AssetFile_GetList\0" in d for n, d in lib_bytes.items()
+                                  if n != "libovrplatformloader.so"),
+            "tbxr_libs": sorted(n for n, d in lib_bytes.items() if b"\0OPENXR_HMD\0" in d and b"\0meta\0" in d),
            "missing_ovr_symbols": sorted(missing_ovr_symbols(lib_bytes)), "size": path.stat().st_size,
+            # the game sizes Meta's microphone buffer (Unreal's Oculus voice): OVRPort crashes there
+            # (frame.ovr_microphone)
+            # (not libil2cpp.so: Unity's C# platform wrapper names every function, used or not; a Unity game that
+            # does crash there is found by triage ovr-microphone-crash)
+            "ovr_microphone": any(b"ovr_Microphone_GetOutputBufferMaxSize\0" in d for n, d in lib_bytes.items()
+                                  if not n.startswith("libovrplatformloader") and n != "libil2cpp.so"),
            "data_bytes": data_bytes or 0,
            "features": features,
            "meta_permissions_used": sorted(p for p in used_perms
@@ -202,6 +213,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,
        },
    )
@@ -240,8 +253,13 @@ def _uses_feature(manifest: bytes, feature: str) -> bool:
    return any(el.name == "uses-feature" and (x.attr_str(el, "name") or "").startswith(feature) for el in x.elements())


+# Platform SDK enum helpers, e.g. ovrPeerConnectionState_ToString (BlazeRush): OVRPort's loader lacks several
+OVR_TO_STRING = re.compile(r"^ovr[A-Z][A-Za-z0-9]*_ToString$")
+
+
 def missing_ovr_symbols(lib_bytes: dict[str, bytes]) -> set[str]:
-    """ovr_* / ovrMessageType_* functions the game imports that the platform loader (+compat/stub libs) lacks."""
+    """ovr_* / ovrMessageType_* / ovr<Enum>_ToString functions the game imports that the platform loader (+compat/stub
+    libs) lacks."""
    loader = lib_bytes.get("libovrplatformloader.so")
    if not loader or not elf.is_elf(loader):
        return set()
@@ -255,5 +273,6 @@ def missing_ovr_symbols(lib_bytes: dict[str, bytes]) -> set[str]:
        if (name.startswith(("libovrplatformloader", "libopenxr_loader", "libframe_settings", "libfrda"))
                or not elf.is_elf(data)):
            continue
-        wanted |= {s for s in elf.dyn_symbols(data, False) if s.startswith(("ovr_", "ovrMessageType_"))}
+        wanted |= {s for s in elf.dyn_symbols(data, False)
+                   if s.startswith(("ovr_", "ovrMessageType_")) or OVR_TO_STRING.match(s)}
    return wanted - exported
@@ -26,3 +26,22 @@ def find_tags(data_dir: Path | str | None) -> list[str]:
            if dot and ext.lower() == "lang" and TAG.match(stem):
                seen.setdefault(stem.lower(), stem)
    return sorted(seen.values(), key=str.lower)
+
+
+def find_content_files(data_dir: Path | str | None) -> list[str]:
+    """Names of the content files (*.pak) below `data_dir` that native/langpack lists as installed asset files (the
+    OBB itself is main.<v>.<pkg>.obb, not a .pak), sorted, first file per name."""
+    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:
+            if name.lower().endswith(".pak") and len(name) < 128:
+                seen.setdefault(name.lower(), name)
+    return sorted(seen.values(), key=str.lower)
@@ -0,0 +1,195 @@
+"""Linux apps for the Frame (GitHub #31): an AppImage, a folder, or a .zip/.tar.* archive with an aarch64 program
+(or an x86_64 one, which the Frame runs through FEX). Finds the program to start, checks the CPU architecture and
+whether it's an OpenXR (VR) app. Archives are unpacked once into FramePort's data folder, so installs upload a
+plain folder like PC VR games do."""
+from __future__ import annotations
+
+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 runs_on_frame(machine: int | None) -> bool:
+    """aarch64 natively, x86_64 through FEX (x86 translation, slower)."""
+    return machine in (EM_AARCH64, EM_X86_64)
+
+
+def inspect(path: Path) -> dict:
+    """{root, exe (relative to root), appimage, machine, arch_ok (aarch64: native), openxr, title, candidates} for an
+    AppImage, a
+    folder or an archive. Raises ValueError when there's no Linux program in it."""
+    path = Path(path)
+    if path.is_file() and is_archive(path):
+        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}")
+    # an arm64 build wins; x86_64 programs only when there is nothing else (they run through FEX on the Frame)
+    for want in (EM_AARCH64, EM_X86_64):
+        if any(m == want for _p, m in programs):
+            programs = [(p, m) for p, m in programs if m == want]
+            break
+    appimages = [p for p, _m in programs if is_appimage(p)]
+    exe, machine = (appimages[0], elf_machine(appimages[0])) if appimages else programs[0]
+    libs = app_libraries(root, exe)
+    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 == machine]}
@@ -10,6 +10,7 @@ from __future__ import annotations
 import struct

 PAGE = 16384
+EMPTY_STRING_AT = 9  # e_ident padding (bytes 9-15 are zero), mapped with the text segment at vaddr 0


 def _elf_hash(name: bytes) -> int:
@@ -129,7 +130,14 @@ def build_stub_library(symbols: list[str], soname: str = "libovrstubs.so", abi:
    out[dynsym_off:dynsym_off + len(syms)] = syms
    out[dynstr_off:dynstr_off + len(dynstr)] = dynstr
    out[hash_off:hash_off + len(hash_bytes)] = hash_bytes
-    out[text_off:text_off + text_size] = body * len(symbols)
+    text = bytearray(body * len(symbols))
+    if is64:  # *_ToString answers "" instead of NULL (a caller may build a string from it): adr x0, <a zero byte>
+        for i, name in enumerate(symbols):
+            if name.endswith("_ToString"):
+                pc = text_off + 8 * i
+                imm = (EMPTY_STRING_AT - pc) & 0x1FFFFF  # 21-bit signed offset; byte 9 of e_ident is always 0
+                text[8 * i:8 * i + 8] = struct.pack("<II", 0x10000000 | (imm & 3) << 29 | (imm >> 2) << 5, 0xD65F03C0)
+    out[text_off:text_off + text_size] = text
    out[dyn_off:dyn_off + len(dyn_bytes)] = dyn_bytes
    out[shstr_off:shstr_off + len(shstr)] = shstr
    out[sh_off:] = sh_bytes
@@ -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
@@ -299,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"
@@ -315,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]
@@ -19,6 +19,7 @@ Errors are one line on stderr; FRAMEPORT_DEBUG=1 shows the traceback.
    frameport diag inspect <zip>                 # re-triage a diagnostics zip (no game files or Frame needed)
    frameport diag report <pkg>                  # zip + prefilled GitHub problem report
    frameport share-recipe <pkg> --status works  # prefilled GitHub issue submitting a working recipe
+    frameport open-link "<install link>"         # FrameDrop button / frameport:// link: download, add, install
 """
 from __future__ import annotations

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