FramePort 0.12.0

Notes: 2026-10-06 issue triage round (headset results, what was ruled out)
Catalog: Metro Awakening plays with space warp off and without Valve's VALVE_rpo layer (random jumping polygons otherwise; owner's headset test)
2026-10-07 16:00:41 +02:00 · 2026-10-06 18:21:32 -04:00 · 2026-10-06 18:19:12 -04:00 · 2026-10-06 17:22:56 -04:00 · 2026-10-06 17:08:10 -04:00 · 2026-10-06 17:07:40 -04:00
93 changed files with 4853 additions and 325 deletions
@@ -96,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)
@@ -413,7 +413,7 @@ GPU. Learned in the headset: quads can't be a background (the Frame draws quad l
 whatever the order: hid 4XVR's balcony/controllers), and the Frame doesn't reproject a projection layer from its own
 pose (images drawn only after head turns, or ahead from xrWaitFrame and sometimes late, wobbled);
 `equirect_flip/face/res/fps/stereo`), `stable_local`, `focus_hold` (only after 3 s FOCUSED, dips <600 ms),
-`aim_pitch/aim_yaw/aim_forward`, `refresh_rate`, `layer_debug` (diagnostics). 4XVR re-creates LOCAL spaces every 2–4 s
+`aim_pitch/aim_yaw/aim_forward`, `refresh_rate`, `layer_debug` (diagnostics); focus_hold is default-on since 2026-10-05. 4XVR re-creates LOCAL spaces every 2–4 s
 (menu recentring suspect); its theatres are baked 7680×3840 equirect2 images (`assets/100.png` …). Test 360° videos
 (NASA, public domain) are in the Frame's ~/Videos; copies in `~/Downloads/frameport-360`. 4XVR's "Internal Storage"
 lists its own `/sdcard/4XPlayer`, not Movies: agent v25 `link_media` hard-links sent files into an app's own top-level
@@ -524,7 +524,7 @@ picker at all: a FramePort fix would be an injected picker activity. Generated c
 Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
 **Steam library failures (GitHub #21/#30):** on some Frames Steam never loads FramePort's shortcuts.vdf entries (same SteamOS build and arm64 beta client as the dev Frame; IDs correct; file written before Steam starts): Play → console_log `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` (= "Game configuration unavailable", Steam treats the id as a store app). Cause unknown; agent v42/43 diagnostics: `launch` returns `steam` (started / error + code / silent from console_log), `collect_diag` adds `steam_library` (real Steam dir, beta, Steam start vs vdf write time, entries per account, devkit games) + `steam-console.txt` (incl. Steam's `logs/shortcuts.previous.txt` if present; steamclient.so has "LoadShortcuts: rejecting attempt to load shortcuts: invalid account ID"). **Fallback (agent v43):** when Play gets AppError_9 the agent registers the game through Steam's devkit interface (what Valve's Devkit Management Tool does, MIT: `devkit-1 steam://devkit-1/<~/.steam/steam.token>/create-shortcut?response=<file>&gameid=<id>&directory=~/devkit-game` written to ~/.steam/steam.pipe; answer file / `.error`; `~/devkit-game/<id>/launch.sh` = link to the game's launch.sh, `<id>-argv.json` ["launch.sh"] (relative to the folder), `<id>-settings.json` {steam_play 0, compat_tool ""}). Steam adds it live (no restart), picks its own appid (read back from shortcuts.vdf by DevkitGameID), shows it as a normal non-Steam game named "Devkit Game: <id>" (OpenVR 0, but VR works: owner-verified 2026-10-04), art copied to grid/<appid>*. Ids: letter first, then letters/digits/_ only (spaces, '-', leading digit → "missing/invalid arguments"). Later Plays use the devkit entry; uninstall (`devkit_unregister`, `delete-shortcut` live) and purge remove it. Verified on the dev Frame: register/launch/unregister; the AppError_9 trigger itself only in unit tests. GitHub #42 (two Steam accounts, neither MostRecent): Steam rewrote the active account's shortcuts.vdf without FramePort's entries right after starting, and added the devkit entry live without saving it, so `devkit_appid` (vdf only) failed ("Steam added the devkit entry but didn't save it"); agent v55 `devkit_appid_from_log` reads Steam's `sanitize shortcut app id "~/devkit-game/<id>/launch.sh": replacing 0 with N` console line. GitHub #41 (one account): same Steam behaviour, and every install restarts Steam, which forgets the never-saved devkit entry. Agent v56: the log fallback reads only the current session's console_log.txt; Play re-registers a devkit entry that gets AppError_9; art updates also write the devkit entry's grid art (`copy_grid_art`). Open: why some Frames' Steam never loads or saves shortcuts.vdf (single account too).
 **Exit game (GitHub #36, 2026-10-04):** `Apps.TerminateApp` (what Exit game calls; reachable for tests through Steam's CEF devtools on 127.0.0.1:8080, SharedJSContext, `Runtime.evaluate` — a stdlib websocket client is enough) closed both a normal shortcut and a devkit entry on the dev Frame within 1-3 s. SIGTERM to Steam's `reaper` alone left launch.sh + Lepton (setsid) + the container running (an earlier headset launch ran on for 87 min); SIGTERM to launch.sh cleans up in ~4 s. Agent v44: launch.sh's 2 s loop ends the game when its parent (the reaper) is gone; `upgrade_launchers` (from ensure_host_fixes) adds that to existing launchers in place. Which in-headset exit path fails is still unknown. Screenshots on the Frame: all under SteamVR's appid 250820 (`760/remote/250820/screenshots`, screenshots.vdf has creation time, no game).
-**SteamVR dashboard at game start (2026-10-04):** the dashboard (Resume game / controller / VR options) was open whenever a FramePort game started (also over Lepton's 2D launcher). Steam's UI exposes `SteamClient.OpenVR.VROverlay.{IsDashboardVisible,HideDashboard,ShowDashboard}` (CEF devtools, `steam_js` in the agent). Agent v44: launch.sh starts `_dashboard_worker` (waits for FrameBridge's first `pacing:` line in launch.log, then hides a visible dashboard for 25 s, at most 3 times; log `<base>/dashboard.log`; opt out with env FRAMEPORT_KEEP_DASHBOARD=1). Verified on the dev Frame (dashboard shown → 4XVR launched via Steam → hidden ~5 s after the first frames); not yet seen in the headset. **Headset (ITR2, 2026-10-05): too late** — Steam shows its frame menu (`valve.steam.gamepadui.frame.menu`, vrwebhelper_systemui.txt `[PooledPopups] Showing`) ~0.3 s after the game's first submitted frame (FrameBridge `new layer:`), but the first `pacing:` summary comes ~8 s later; the owner had pressed Resume (`[HideDashboard] return_to_game`) before the worker looked. Agent v52: watches from the first `new layer:` line (incremental log reads, 0.5 s polls, 30 s window). Agent v53: stops for good once the player opens the dashboard with the controller (`toggle_dashboard_action` in vrwebhelper_systemui.txt since the worker started): v52 closed it 60 ms after each press, and the game, paused for it, stayed paused.
+**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).
@@ -535,6 +535,75 @@ Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
 **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.

@@ -572,6 +641,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.
@@ -36,7 +36,7 @@ import time
 import zlib
 from types import SimpleNamespace

-AGENT_VERSION = 56
+AGENT_VERSION = 59
 HOME = os.path.expanduser("~")
 STEAM = os.path.join(HOME, ".local/share/Steam")
 ANCHORS = os.path.join(HOME, "Applications/quest-frame")
@@ -1072,6 +1072,16 @@ def _shortcuts_worker(payload):
    os.makedirs(os.path.dirname(STATUS_FILE), exist_ok=True)
    try:
        users = library_users()
+        # games Steam only knows through their devkit entry (this Frame's Steam drops FramePort's shortcuts.vdf
+        # entries, GitHub #41/#42): rewriting the vdf changes nothing for them, and the Steam restart would drop the
+        # live devkit entry too. They get their art only; Play re-adds a lost devkit entry live.
+        devkit = [p for p in args["packages"] if devkit_gameid(p)]
+        for pkg in devkit:
+            appid = devkit_appid(devkit_gameid(pkg))
+            if appid:
+                copy_grid_art(pkg, appid)
+        args["packages"] = [p for p in args["packages"] if p not in devkit]
+        result["devkit"] = devkit
        if not args.get("remove") and not library_changes(users, args["packages"]):
            # nothing to change in shortcuts.vdf (e.g. a reinstall): only the artwork, no Steam restart
            for user in users:
@@ -1412,6 +1422,13 @@ def cmd_launch(args):
        raise AgentError("Steam isn't running on the Frame")
    devkit = devkit_gameid(pkg)
    appid = devkit_appid(devkit) if devkit else None  # this Frame needed the fallback entry before: use it
+    if devkit and not appid:
+        # Steam forgot the devkit entry (it never saves it on some Frames, and a restart drops it, GitHub #41): add it
+        # again live instead of reporting NOT_IN_LIBRARY, whose repair restarts Steam
+        try:
+            appid = devkit_register(pkg)
+        except AgentError:
+            appid = None
    via = "devkit" if appid else "shortcut"
    appid = appid or shortcut_appid_for(f'"{os.path.join(ANCHORS, pkg)}/launch.sh"')
    if appid is None:  # Steam would only say "Game configuration unavailable"
@@ -1889,6 +1906,7 @@ LAUNCH_SH = (r"""#!/usr/bin/env bash
 set -euo pipefail
 app_dir={base_q}
 [[ -d "$app_dir/lepton-app" ]] || {{ echo "Game files missing at $app_dir (storage not mounted?)" >&2; exit 1; }}
+{single}
 # Some games (Unreal cloud saves, SUPERHOT's cloud/data: mode 1700) create folders without write/search permission
 # for the app inside Lepton (it writes through the folder's group), which breaks saving or makes the game quit.
 # Repair them before and during every launch.
@@ -1939,10 +1957,19 @@ OLD_WATCHDOG = "( while sleep 2 && kill -0 $$ 2>/dev/null; do fix_perms; done )
 # by hand (also when Lepton shows its Android launcher first). Once the game's first VR frames are logged, the agent
 # closes it through Steam's UI (_dashboard_worker); opt out per game with FRAMEPORT_KEEP_DASHBOARD=1.
 DASHBOARD_LINE = ('[[ -n "${{FRAMEPORT_KEEP_DASHBOARD:-}}" ]] || python3 {agent_q} _dashboard_worker '
-                  '"$app_dir/launch.log" $$ >"$app_dir/dashboard.log" 2>&1 &')
+                  '"$app_dir/launch.log" $$ >"$app_dir/dashboard.log" 2>&1 9>&- &')
 WATCHDOG = ("parent=$PPID\n"
            "( while sleep 2 && kill -0 $$ 2>/dev/null; do fix_perms;"
-            " if [[ $parent -gt 1 ]] && ! kill -0 $parent 2>/dev/null; then kill -TERM $$; fi; done ) & permfix=$!")
+            " if [[ $parent -gt 1 ]] && ! kill -0 $parent 2>/dev/null; then kill -TERM $$; fi; done )"
+            " 9>&- & permfix=$!")
+
+
+# One launcher per game: Play pressed again while Lepton still boots (~10 s with nothing to see) made the second Lepton
+# stop the first one's container, and both died (Vader Immortal, BattleSisters). The lock is held by Lepton's process
+# (inherited fd), so it is released when the game ends.
+SINGLE_LINE = ('exec 9>"$app_dir/.launch.lock"; flock -n 9 || '
+               '{ echo "$(date +%s) already starting or running: second launch ignored" >>"$app_dir/launch-dup.log"; '
+               'exit 0; }')


 def dashboard_line():
@@ -1971,6 +1998,13 @@ def upgrade_launchers():
            new = new.replace(OLD_WATCHDOG, WATCHDOG, 1)
        if "_dashboard_worker" not in new and 'child=$!\nwait "$child"' in new:
            new = new.replace('child=$!\nwait "$child"', 'child=$!\n' + dashboard_line() + '\nwait "$child"', 1)
+        guard = '[[ -d "$app_dir/lepton-app" ]] ||'
+        if ".launch.lock" not in new and guard in new:
+            i = new.index("\n", new.index(guard)) + 1
+            new = new[:i] + SINGLE_LINE + "\n" + new[i:]
+            # the lock belongs to Lepton only: helpers that outlive the game must not keep it
+            new = new.replace("; fi; done ) & permfix=$!", "; fi; done ) 9>&- & permfix=$!", 1)
+            new = new.replace('>"$app_dir/dashboard.log" 2>&1 &', '>"$app_dir/dashboard.log" 2>&1 9>&- &', 1)
        if PLAYS_LOG not in new:
            start, end = plays_lines(os.path.dirname(path))
            if "\nsetsid " in new and "\n    trap - EXIT INT TERM\n" in new:  # Lepton launcher
@@ -1994,7 +2028,7 @@ def write_launcher(anchor, base, pkg, title, appid, lepton, env):
                    if re.fullmatch(r"[A-Z_][A-Z0-9_]*", k))
    text = LAUNCH_SH.format(title=title.replace("\n", " "), pkg=pkg, base_q=shlex.quote(base), appid=appid,
                            lepton_q=shlex.quote(lepton), extra_env=extra, watchdog=WATCHDOG,
-                            dashboard=dashboard_line(), plays_start=plays_lines(anchor)[0],
+                            dashboard=dashboard_line(), single=SINGLE_LINE, plays_start=plays_lines(anchor)[0],
                            plays_end=plays_lines(anchor)[1])
    path = os.path.join(anchor, "launch.sh")
    with open(path + ".tmp", "w") as f:
@@ -3684,10 +3718,11 @@ def user_opened_dashboard(log, pos):
        return False, pos


-def dashboard_worker(log, parent, wait_start=240, window=30, poll=0.5, ui_log=None):
+def dashboard_worker(log, parent, wait_start=240, window=120, poll=0.5, ui_log=None, max_hides=10):
    """Close SteamVR's dashboard (Steam's "Resume game" frame menu) that opens when the game submits its first VR
    frame: watch from FrameBridge's first "new layer:" line (the first submitted frame; Steam showed the menu ~0.3 s
-    later with ITR2), checking every `poll` s for `window` s after it (at most 3 hides). Waiting for the first
+    later with ITR2), checking every `poll` s for `window` s after it (at most `max_hides`; agent 59: 120 s / 10, the
+    menu came back after the first 30 s in the owner's sessions). Waiting for the first
    "pacing:" summary (agent 44-51) was ~8 s too late: the owner had pressed Resume by then. Stops for good once the
    player opens the dashboard with the controller (agent 52 closed it 60 ms after each press: the game had paused
    for it and stayed paused). Ends with the launcher."""
@@ -3719,7 +3754,7 @@ def dashboard_worker(log, parent, wait_start=240, window=30, poll=0.5, ui_log=No
        return
    print(f"{time.strftime('%H:%M:%S')} first VR frame")
    hidden, end = 0, time.time() + window
-    while time.time() < end and hidden < 3 and alive():
+    while time.time() < end and hidden < max_hides and alive():
        user, ui_pos = user_opened_dashboard(ui_log, ui_pos)
        if user:  # the player wants the dashboard (or the game's menu button opened it): never close it on them
            print(f"{time.strftime('%H:%M:%S')} dashboard opened with the controller: leaving it to the player")
@@ -1,13 +1,14 @@
-48a3ecad77ec0f3215b29070e994590eb9579e04d3c88a47f37f306f9aeb01d9  ./arm64-v8a/libfp_langpack.so
-a5b03bb7ae5d953d7ded2bf117b0a19c57fae604f16f54310847f8e89593dde6  ./arm64-v8a/libfp_ovrp.so
-b5949e9e90e4c51e2733b9f6cd3c857a447552ac7291aec340407c27b034b600  ./arm64-v8a/libfp_vk.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
-8e00552d1ab90f82749db3caad4f773351fa8a28edcc5ea5cbd1b31c434ff32a  ./arm64-v8a/libframe_xrshim.so
-3dfcb0f2bec47857bcecc7261c58e076d872d4649718c40850f29e10c75477dd  ./arm64-v8a/libglshim.so
-0780f29b4844bcf5070929d8118cfcc2e7da2f16dd0dbfe1eaf12be7f5567401  ./arm64-v8a/libopenxr_loader_generic.so
+06c8a17b37cb1513fdfeba87ece457a02097bb22dd0a3a3a8719fb8fea16b52a  ./arm64-v8a/libframe_xrshim.so
+9f5ba793d1804728394a8fe9e83028e13f1bc939b558892e7beb5c3662317259  ./arm64-v8a/libglshim.so
+d7709fe953a3170467ec0c53e6b715833014512fbd8d91803a9cb2aecf0961ad  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
-32525cd0a9ee3d9993d8871cd6905bdcf22cde4f4ba28f5db6434ce7d6554758  ./arm64-v8a/libvrapi.so
-9c82f4ff57395e220329a22d0f0f47ce88b77132bed4dfb7b57809077fd0d6c4  ./armeabi-v7a/libopenxr_loader_generic.so
+aa4dc0020c77e12d41ef6ce80b23ad90c9cb7e882338eddf2261efe8645cf38d  ./arm64-v8a/libvrapi.so
+f994e6bc9ae32ab7ad17ffc992e10dce19289bed44d577b5ac08d7e99eb0174d  ./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,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
@@ -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,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
@@ -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
@@ -13,13 +13,18 @@ signatures:
    severity: fatal
    diagnosis: 32-bit-only APK. The Steam Frame has no AArch32; this cannot run. Use the PC (Rift) version via Revive.
    suggest: []
+  - id: unity-render-crash
+    pattern: 'CRASH\s*:.*#\d+\s+pc [0-9a-f]+\s+\S*libgallium_dri\.so'
+    severity: fatal
+    diagnosis: Unity's render thread crashed inside the Frame's GL driver (Mesa/Zink); the picture freezes or stays grey. Known triggers - an OVROverlay copy (try "Unity - skip OVROverlay layers", e.g. The Room VR), MSAA switched on at runtime, a GPU hang (zink DEVICE LOST).
+    suggest: [frame.unity_no_overlay_copy, frame.unity_runtime_msaa_off]
  - id: swapchain-rect-invalid
    pattern: 'xrEndFrame failed -25\b'
    severity: fatal
-    diagnosis: The runtime rejects the game's frames because an image rect reaches past its swapchain (by a few pixels on some Frames); the game stops drawing (e.g. stuck at a "Waiting" box). FrameBridge from FramePort 0.10.1 clamps the rects - rebuild and reinstall the game.
+    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]
@@ -96,8 +101,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]
@@ -130,6 +164,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
@@ -154,6 +200,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
@@ -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)
@@ -7,31 +7,39 @@ 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 |  |
 | Keep Talking and Nobody Explodes | Quest | ✅ Works |  |
 | LEGO® Bricktales | Quest | ✅ Works |  |
+| Lucky's Tale | Quest | ✅ Works |  |
 | Marvel's Deadpool VR | Quest | ✅ Works |  |
 | Marvel's Iron Man VR | Quest | ✅ Works |  |
 | Medieval Dynasty New Settlement | Quest | ✅ Works |  |
+| Metro Awakening | Quest | ✅ Works |  |
 | Mobile Suit Gundam: Silver Phantom | Quest | ✅ Works |  |
 | Nano | Quest | ✅ Works |  |
 | NEX Player | Quest | ✅ Works |  |
@@ -50,23 +58,23 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | SUPERHOT VR | Quest | ✅ Works |  |
 | TetrisEffect | Quest | ✅ Works |  |
 | The Climb 2 | Quest | ✅ Works |  |
+| The Room VR | Quest | ✅ Works |  |
 | Toy Master | Quest | ✅ Works |  |
 | Under Cover | Quest | ✅ Works |  |
 | VR4 | Quest | ✅ Works |  |
 | Wallace & Gromit in The Grand Getaway | Quest | ✅ Works |  |
 | Waltz of the Wizard: Extended Edition | Quest | ✅ Works |  |
 | Wander | Quest | ✅ Works |  |
-| Accounting+ | Quest | ⚠️ Works with issues | Starts in VR, but doesn't get past its "press any button" screen. |
 | Arcsmith | Quest | ⚠️ Works with issues | Right eye distorts during movement (unresolved; swap, tracking, Valve layers, depth and pacing ruled out). |
 | Assassin's Creed Nexus | Quest | ⚠️ Works with issues | Some launch warning text is still upside down; the rest of the UI is fixed by flip emulation. |
-| I Am Cat | Quest | ⚠️ Works with issues | The view vibrates slightly, even when holding still. |
-| Lucky's Tale | Quest | ⚠️ Works with issues | 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). |
+| 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. |
 | 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. |
@@ -13,9 +13,18 @@ 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 |
+| 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 |
@@ -39,6 +48,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 |
@@ -56,9 +66,11 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Quest app keeps recentering / snapping the view when you turn your head; log shows session state 5→4→3→4→5 within a second | the Frame briefly takes focus; the app recenters on focus changes | unfixed: hiding the dips (debounce) made AC Nexus stay black, so it was removed |
 | Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | upload in the Files tab (Videos = /sdcard/Movies) and browse folders in the app |
 | Batman: Arkham Shadow closes during smoke-bomb effects; later input-tree corruption | Meta XR Audio Wwise deletes queued metadata still referenced by the current audio frame, then writes through the stale pointer | FrameBridge automatically retires metadata after current-frame references disappear, for the verified AArch64 SDK build only; see [AUDIO_METADATA.md](AUDIO_METADATA.md) |
-| Game stays on a loading or "Waiting" box although it reached FOCUSED; log `FrameBridge: xrEndFrame failed -25` then no more `pacing:` lines (e.g. PowerWash Simulator on some Frames, GitHub #39) | The eye image rect ends a few pixels past its swapchain (Unity rounds the swapchain width, the runtime's recommended size differs per Frame); SteamVR rejects every frame with XR_ERROR_SWAPCHAIN_RECT_INVALID | FrameBridge clamps every projection/quad image rect to its swapchain (`rect_clamp`, default on since 0.10.1; log `rect_clamp: view N image rect clamped`): rebuild + reinstall the game |
+| Game 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` |
@@ -87,9 +99,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
@@ -12,9 +12,9 @@ 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`. |
+| `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). |
 | `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). |
@@ -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
@@ -86,9 +86,22 @@ 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;  // clamp submitted image rects to their swapchain (SteamVR rejects a 1 px overrun)
+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;
@@ -113,8 +126,9 @@ static int sync_guard;       // xrSyncActions one at a time with xrPollEvent, pa
 static int profile_remap = 1; // Meta's newer controller profiles (rejected by the Frame) -> oculus/touch_controller
 static int layer_debug;      // diagnostics: layers, swapchains, session states, spaces, aim/grip, refresh rates
 static int stable_local;     // keep every LOCAL space the app creates on the session-start origin
-static int focus_hold;       // hide brief focus dips once the session has been focused for a while
-static float focus_hold_ms = 1000;  // longest focus dip focus_hold hides
+static int focus_hold = 1;   // hide brief focus dips once the session has been focused for a while
+static float focus_hold_ms = 5000;  // longest focus dip focus_hold hides
+static float 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)
@@ -135,9 +149,13 @@ static void read_settings(const char *path) {
        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;
@@ -161,6 +179,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;
@@ -207,11 +226,17 @@ static void initialize(void) {
    }
    const char *env = getenv("FRAMEBRIDGE_CONFIG");
    if (env && *env) read_settings(env);
+    if (snapshot && *process && !strchr(process, '/')) {
+        snprintf(snap_dir, sizeof(snap_dir), "/sdcard/Android/data/%s/files", process);
+        LOG("per-game: snapshot every %d s to %s/fb_snap_N.ppm", snapshot, snap_dir);
+    }
    if (eye_debug && *process && !strchr(process, '/')) {
        snprintf(path, sizeof(path), "/sdcard/Android/data/%s/files/framebridge.log", process);
        log_file = fopen(path, "a");
    }
    if (hide_space_warp) LOG("per-game: hide_space_warp=1 (XR_FB_space_warp hidden, space warp info removed)");
+    if (strip_color_bias) LOG("per-game: strip_color_bias=%d (layer color scale/bias removed)", strip_color_bias);
+    if (frame_balance) LOG("per-game: frame_balance=1 (an open frame is ended before the next one begins)");
    if (eye_debug || release_wait) LOG("per-game: eye_debug=%d release_wait=%d log_file=%s", eye_debug, release_wait,
                                       log_file ? path : "none");
    if (controller_models && *process && !strchr(process, '/')) render_model_init(process);
@@ -269,7 +294,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) {
@@ -297,6 +322,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");
@@ -305,6 +343,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.
@@ -472,6 +518,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);
@@ -483,6 +530,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
        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;
@@ -506,6 +554,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
        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;
 }
@@ -513,10 +562,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);
 }
@@ -768,13 +822,44 @@ XRAPI_ATTR XrResult XRAPI_CALL xrDestroySpace(XrSpace space) {

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

+// 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);
@@ -785,6 +870,55 @@ 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;
+XRAPI_ATTR XrResult XRAPI_CALL xrApplyHapticFeedback(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 xrEnumerateSwapchainImages(XrSwapchain swapchain, uint32_t capacity, uint32_t *count,
        XrSwapchainImageBaseHeader *images) {
    PFN_xrEnumerateSwapchainImages fn = (PFN_xrEnumerateSwapchainImages)lookup(active_instance, "xrEnumerateSwapchainImages");
@@ -794,10 +928,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");
@@ -809,7 +961,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;
 }

@@ -912,11 +1069,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);
@@ -959,9 +1174,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;
@@ -978,6 +1224,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),
@@ -1111,6 +1369,48 @@ 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
@@ -1389,6 +1689,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)
@@ -1404,6 +1705,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
    HOOK(xrCreateSwapchain)
    HOOK(xrDestroySwapchain)
    HOOK(xrEndFrame)
+    HOOK(xrBeginFrame)
    HOOK(xrLocateHandJointsEXT)
    HOOK(xrGetCurrentInteractionProfile)
    HOOK(xrEnumerateInstanceExtensionProperties)
@@ -1420,6 +1722,10 @@ 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 (layer_debug) {  // counters only; every other wait/release hook above takes precedence
+        HOOK(xrWaitSwapchainImage)
+        HOOK(xrReleaseSwapchainImage)
+    }
    if (sync_guard || layer_debug) HOOK_AS(xrSyncActions, hook_xrSyncActions)
    if (layer_debug) HOOK_AS(xrGetActionStateBoolean, hook_xrGetActionStateBoolean)
    if (layer_debug || aim_correction_on() || profile_remap)
@@ -140,7 +140,7 @@ static XRAPI_ATTR XrResult XRAPI_CALL hook_xrGetActionStateBoolean(XrSession ses
 // ---------------------------------------------------------------- focus_hold
 #define FOCUS_HOLD_MIN_FOCUSED_NS 1000000000ll  // only after this long in FOCUSED (start-up transitions untouched;
                                                // 3 s let a 27 ms dip through in Blade & Sorcery)
-// dips longer than focus_hold_ms (setting, default 1000) are delivered (late, in order): taking the headset off or the
+// dips longer than focus_hold_ms (setting, default 5000) are delivered (late, in order): taking the headset off or the
 // system menu must still pause the game. A longer limit is for headsets whose wear sensor flickers ("HMD off" for
 // 0.5-2 s while worn; Blade & Sorcery pauses on each)
 #define FOCUS_HOLD_MAX_DIP_NS ((int64_t)(focus_hold_ms * 1000000.0f))
@@ -0,0 +1,173 @@
+// FramePort FrameBridge: eye-image snapshots for headless diagnostics (setting snapshot=<seconds>, GLES games only).
+// Every <seconds>, at xrEndFrame, the left-eye image the game just submitted (projection layer, view 0: its swapchain
+// image and array layer) is read back on the game's own GL context and written at a quarter of its size as
+// /sdcard/Android/data/<package>/files/fb_snap_<n>.ppm (n = 0-7, the oldest is overwritten). Nobody wears the headset
+// in a launch test, so the headset view stays black: this shows what the game itself draws (e.g. which screen it is
+// stuck on). The game's framebuffer, pack-buffer and pack-alignment bindings are restored afterwards.
+#define SNAP_MAX_SWAPCHAINS 16
+#define SNAP_MAX_IMAGES 8
+#define SNAP_SCALE 4
+
+
+#define SNAP_GL_FUNCS(X) X(glGenFramebuffers) X(glDeleteFramebuffers) X(glBindFramebuffer) X(glFramebufferTexture2D) \
+    X(glFramebufferTextureLayer) X(glCheckFramebufferStatus) X(glReadPixels) X(glGetIntegerv) X(glPixelStorei) \
+    X(glBindBuffer) X(glGetError)
+#define SNAP_DECLARE(fn) static __typeof__(&fn) s_##fn;
+SNAP_GL_FUNCS(SNAP_DECLARE)
+#undef SNAP_DECLARE
+static EGLContext (*s_eglGetCurrentContext)(void);
+
+static struct {
+    XrSwapchain handle;
+    uint32_t width, height, array_size, count, last_acquired;
+    GLuint images[SNAP_MAX_IMAGES];
+} snap_chains[SNAP_MAX_SWAPCHAINS];
+static pthread_mutex_t snap_lock = PTHREAD_MUTEX_INITIALIZER;
+
+static int snap_load_gl(void) {
+    static int state;  // 0 untried, 1 ok, -1 failed
+    if (state) return state > 0;
+    void *egl = dlopen("libEGL.so", RTLD_NOW | RTLD_LOCAL), *gles = dlopen("libGLESv3.so", RTLD_NOW | RTLD_LOCAL);
+    int ok = egl && gles;
+    if (ok) s_eglGetCurrentContext = (EGLContext (*)(void))dlsym(egl, "eglGetCurrentContext");
+#define SNAP_RESOLVE(fn) ok &= gles && (s_##fn = (__typeof__(s_##fn))dlsym(gles, #fn)) != NULL;
+    SNAP_GL_FUNCS(SNAP_RESOLVE)
+#undef SNAP_RESOLVE
+    state = ok && s_eglGetCurrentContext ? 1 : -1;
+    if (state < 0) LOG("snapshot: OpenGL ES not available, no snapshots");
+    return state > 0;
+}
+
+static int snap_find(XrSwapchain handle, int create) {
+    for (int i = 0; i < SNAP_MAX_SWAPCHAINS; ++i)
+        if (snap_chains[i].handle == handle) return i;
+    if (!create) return -1;
+    for (int i = 0; i < SNAP_MAX_SWAPCHAINS; ++i)
+        if (!snap_chains[i].handle) { snap_chains[i].handle = handle; snap_chains[i].count = 0; return i; }
+    return -1;
+}
+
+static void snap_on_create(XrSwapchain handle, const XrSwapchainCreateInfo *info) {
+    if (!snapshot || !info) return;
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(handle, 1);
+    if (i >= 0) {
+        snap_chains[i].width = info->width;
+        snap_chains[i].height = info->height;
+        snap_chains[i].array_size = info->arraySize ? info->arraySize : 1;
+    }
+    pthread_mutex_unlock(&snap_lock);
+}
+
+static void snap_on_destroy(XrSwapchain handle) {
+    if (!snapshot) return;
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(handle, 0);
+    if (i >= 0) snap_chains[i].handle = XR_NULL_HANDLE;
+    pthread_mutex_unlock(&snap_lock);
+}
+
+static void snap_on_enumerate(XrSwapchain handle, uint32_t count, const XrSwapchainImageBaseHeader *images) {
+    if (!snapshot || !images || !count || images->type != (XrStructureType)1000024002) return;  // OPENGL_ES_KHR
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(handle, 1);
+    if (i >= 0) {
+        uint32_t n = count < SNAP_MAX_IMAGES ? count : SNAP_MAX_IMAGES;
+        const emul_gles_image *gl = (const emul_gles_image *)images;
+        for (uint32_t k = 0; k < n; ++k) snap_chains[i].images[k] = gl[k].image;
+        snap_chains[i].count = n;
+    }
+    pthread_mutex_unlock(&snap_lock);
+}
+
+static void snap_on_acquire(XrSwapchain handle, uint32_t index) {
+    if (!snapshot) return;
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(handle, 0);
+    if (i >= 0) snap_chains[i].last_acquired = index;
+    pthread_mutex_unlock(&snap_lock);
+}
+
+static void snap_write(const unsigned char *rgba, uint32_t w, uint32_t h, int n) {
+    char path[320];
+    snprintf(path, sizeof(path), "%s/fb_snap_%d.ppm", snap_dir, n);
+    FILE *f = fopen(path, "wb");
+    if (!f) { LOG("snapshot: can't write %s", path); return; }
+    uint32_t ow = w / SNAP_SCALE, oh = h / SNAP_SCALE;
+    fprintf(f, "P6\n%u %u\n255\n", ow, oh);
+    unsigned char *row = malloc((size_t)ow * 3);
+    for (uint32_t y = 0; row && y < oh; ++y) {
+        const unsigned char *src = rgba + (size_t)(h - 1 - y * SNAP_SCALE) * w * 4;  // GL rows are bottom-up
+        for (uint32_t x = 0; x < ow; ++x) {
+            const unsigned char *p = src + (size_t)x * SNAP_SCALE * 4;
+            row[x * 3] = p[0], row[x * 3 + 1] = p[1], row[x * 3 + 2] = p[2];
+        }
+        fwrite(row, 1, (size_t)ow * 3, f);
+    }
+    free(row);
+    fclose(f);
+    LOG("snapshot: %s (%ux%u)", path, ow, oh);
+}
+
+static void snap_end_frame(const XrFrameEndInfo *info) {
+    if (!snapshot || !*snap_dir || !info) return;
+    static int64_t next_ns;
+    static int taken;
+    struct timespec now;
+    clock_gettime(CLOCK_MONOTONIC, &now);
+    int64_t t = (int64_t)now.tv_sec * 1000000000ll + now.tv_nsec;
+    if (t < next_ns) return;
+    next_ns = t + (int64_t)snapshot * 1000000000ll;
+    const XrCompositionLayerProjection *proj = NULL;
+    for (uint32_t i = 0; i < info->layerCount && !proj; ++i)
+        if (info->layers[i] && info->layers[i]->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
+            ((const XrCompositionLayerProjection *)info->layers[i])->viewCount)
+            proj = (const XrCompositionLayerProjection *)info->layers[i];
+    if (!proj || !snap_load_gl()) return;
+    if (!s_eglGetCurrentContext()) {
+        static int logged;
+        if (!logged++) LOG("snapshot: no GL context current in xrEndFrame, no snapshot");
+        return;
+    }
+    const XrSwapchainSubImage *sub = &proj->views[0].subImage;
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(sub->swapchain, 0);
+    GLuint tex = 0;
+    uint32_t w = 0, h = 0, array_size = 1;
+    if (i >= 0 && snap_chains[i].count && snap_chains[i].last_acquired < snap_chains[i].count) {
+        tex = snap_chains[i].images[snap_chains[i].last_acquired];
+        w = snap_chains[i].width, h = snap_chains[i].height, array_size = snap_chains[i].array_size;
+    }
+    pthread_mutex_unlock(&snap_lock);
+    if (!tex || !w || !h) return;
+    GLint read_fb = 0, pack_buffer = 0, pack_alignment = 4;
+    s_glGetIntegerv(GL_READ_FRAMEBUFFER_BINDING, &read_fb);
+    s_glGetIntegerv(GL_PIXEL_PACK_BUFFER_BINDING, &pack_buffer);
+    s_glGetIntegerv(GL_PACK_ALIGNMENT, &pack_alignment);
+    GLuint fb = 0;
+    s_glGenFramebuffers(1, &fb);
+    s_glBindFramebuffer(GL_READ_FRAMEBUFFER, fb);
+    if (array_size > 1)
+        s_glFramebufferTextureLayer(GL_READ_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, tex, 0, (GLint)sub->imageArrayIndex);
+    else
+        s_glFramebufferTexture2D(GL_READ_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, tex, 0);
+    unsigned char *rgba = NULL;
+    if (s_glCheckFramebufferStatus(GL_READ_FRAMEBUFFER) == GL_FRAMEBUFFER_COMPLETE &&
+        (rgba = malloc((size_t)w * h * 4))) {
+        s_glBindBuffer(GL_PIXEL_PACK_BUFFER, 0);
+        s_glPixelStorei(GL_PACK_ALIGNMENT, 1);
+        s_glReadPixels(0, 0, (GLsizei)w, (GLsizei)h, GL_RGBA, GL_UNSIGNED_BYTE, rgba);
+    } else {
+        static int logged;
+        if (logged++ < 3) LOG("snapshot: eye image %u not readable (framebuffer incomplete)", tex);
+    }
+    s_glPixelStorei(GL_PACK_ALIGNMENT, pack_alignment);
+    s_glBindBuffer(GL_PIXEL_PACK_BUFFER, (GLuint)pack_buffer);
+    s_glBindFramebuffer(GL_READ_FRAMEBUFFER, (GLuint)read_fb);
+    s_glDeleteFramebuffers(1, &fb);
+    while (s_glGetError() != GL_NO_ERROR) {}  // our calls must not leave errors for the game to find
+    if (rgba) {
+        snap_write(rgba, w, h, taken++ % 8);
+        free(rgba);
+    }
+}
@@ -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,eglfmt,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

@@ -249,6 +249,14 @@ def build_eglfmt(tc: Path):
         "-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"
@@ -318,7 +326,7 @@ def write_sums():

 def main():
    ap = argparse.ArgumentParser()
-    ap.add_argument("--only", default="adapter,bridge,compat,langpack,glshim,eglfmt,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(","))
@@ -327,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), "eglfmt": lambda: build_eglfmt(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", "eglfmt", "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]()
@@ -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,6 +8,8 @@
 // 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
@@ -28,6 +30,8 @@
 //  * 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>
@@ -35,6 +39,7 @@
 #include <errno.h>
 #include <fcntl.h>
 #include <pthread.h>
+#include <stddef.h>
 #include <stdlib.h>
 #include <string.h>
 #include <unistd.h>
@@ -93,6 +98,7 @@ static int query_slots = 1;  // vk_query_slots: slots per occlusion query (1 = u
 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");
@@ -101,6 +107,7 @@ static void read_settings(const char *path) {
    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);
@@ -210,6 +217,7 @@ static void init(void) {
    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);
@@ -348,7 +356,23 @@ static const void *clean_chain(Arena *a, const void *head, int *fixes) {
    return first;
 }

-static int resolves_logged;
+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;
@@ -370,6 +394,7 @@ 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;
        }
@@ -409,11 +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_CIMG, FN_CQP, FN_DQP, FN_BQ, FN_EQ, FN_CRQP, FN_RQP, FN_RQPEXT, FN_GQPR, FN_CCQPR, FN_COUNT };
+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"};
+    "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;
@@ -701,6 +728,156 @@ EXPORT VKAPI_ATTR void VKAPI_CALL vkCmdCopyQueryPoolResults(VkCommandBuffer cb,
    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;
@@ -713,6 +890,12 @@ static PFN_vkVoidFunction wrap(const char *name) {
    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
@@ -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,19 @@
 // Meta's OVRPlugin finds xrGetInstanceProcAddr with dlopen("libopenxr_loader.so") + dlsym, so FramePort points that
 // string in libOVRPlugin.so at this library instead (patches/frame/adapter.py). Names the adapter emulates are served
 // by the adapter (framebridge_extension_proc); everything else goes to overport's xrGetInstanceProcAddr unchanged.
+//
+// Haptics (GitHub #9, found by Klownicle in Lucky's Tale): overport's dispatcher converts an
+// XrHapticAmplitudeEnvelopeVibrationFB with its nanosecond duration taken as seconds, so one vibration allocates an
+// enormous sample buffer and the Frame runs out of memory and freezes. The shim hands OVRPlugin its own
+// xrApplyHapticFeedback, which turns such an envelope into a plain XrHapticVibration (same duration, its peak
+// amplitude) before the dispatcher sees it. Everything else passes through unchanged.
 #include <openxr/openxr.h>
 #include <android/log.h>
 #include <dlfcn.h>
 #include <pthread.h>
+#include <math.h>
 #include <stddef.h>
+#include <string.h>

 #define TAG "FrameBridge"
 #define EXPORT __attribute__((visibility("default")))
@@ -40,9 +48,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,6 +79,12 @@ 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

@@ -1,2 +1,2 @@
 # The FramePort version: the single source (pyproject reads it via hatch; CI checks a release tag matches it).
-__version__ = "0.10.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
@@ -242,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()
@@ -257,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)
@@ -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
@@ -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)."""
@@ -62,8 +85,22 @@ def _follow_catalog(data: dict) -> bool:
            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
@@ -79,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
@@ -29,7 +29,8 @@ class InstallPlan:

 def install_context(recipe: Recipe) -> base.InstallContext:
    ctx = base.InstallContext(recipe.package, {}, {}, {}, adapter_settings(recipe.patches))
-    for pid, params in recipe.patches.items():
+    # device.foveation last: the player's explicit choice beats a recipe's lepton_env VK_INSTANCE_LAYERS
+    for pid, params in sorted(recipe.patches.items(), key=lambda kv: kv[0] == "device.foveation"):
        patch = base.get(pid)
        if patch.stage == "install" and patch.category == "device":
            ctx.params = params or {}
@@ -60,6 +60,7 @@
 "A Meta Quest game (APK). It's rebuilt for the Frame and runs in Lepton, Valve's Android container.": "",
 "A native Linux program built for arm64 (aarch64), like the Frame's own CPU. It's installed unchanged and runs directly on SteamOS (no Android container, no Proton), started from the Frame's Steam library. VR apps use the Frame's OpenXR runtime.": "",
 "A new FramePort version is ready to install": "",
+ "A newer known-good config for this game is available (you changed this game's settings, so it wasn't applied by itself).": "",
 "A recipe is the list of patches FramePort applies to a game before installing it. Known-good recipes were tested on a Frame; the others are suggested from the game's engine and VR API. Hover a patch for why it's there.": "",
 "A VR app made for another Android headset. OpenXR apps are translated like Quest games; apps built on a headset maker's own SDK (Pico, HTC Wave) can't run on the Frame.": "",
 "A Windows game without VR, added with \"Add one game folder…\". On the Frame, Proton runs it as a window (like Steam's own Windows games); it's in the Frame's Steam library.": "",
@@ -214,6 +215,7 @@
 "Connecting the keyboard…": "",
 "Connecting to {value}…": "",
 "Connecting…": "",
+ "Content files from the game's data": "",
 "Continue": "",
 "Controllers": "",
 "Converts Quest games to OpenXR": "",
@@ -237,6 +239,7 @@
 "Couldn't read {path}: {exc}": "",
 "Couldn't start the live view: {exc}": "",
 "Couldn't use {choice}: {exc}": "",
+ "Counts the headset as worn, so games that only move the player while it's worn get head tracking and controls (e.g. BONELAB).": "",
 "Cover": "",
 "Create": "",
 "Customize": "",
@@ -305,6 +308,7 @@
 "Download…": "",
 "Draws each eye separately; try it when one eye shows a grey or broken picture.": "",
 "Drop invalid layers": "",
+ "Drop layer color fades": "",
 "Drop layers whose swapchain failed or whose extension isn't enabled.": "",
 "Drop to upload": "",
 "Drops Quest-only shared library requirements.": "",
@@ -316,6 +320,7 @@
 "Environment variables for the Proton launcher on the Frame (e.g. DXVK_HUD=fps), one KEY=value per line.": "",
 "Every 'local' play space the game creates lines up with the one at the start. For games whose menus or screens jump to where you look on the Frame.": "",
 "Every game start on the Frame used to leak one kernel key, and after about 200 launches every game fails to start. FramePort switches that leak off, but keys already used only come back after a restart of the Frame.": "",
+ "Every N seconds, saves the left-eye image the game submits (a quarter of its size) as fb_snap_0-7.ppm in the game's files folder on the Frame. Launch tests run without anyone wearing the headset, so the headset view stays black; this shows what the game itself draws. OpenGL ES games only.": "",
 "Every uploaded file is present with the right size.": "",
 "everything in ~ (not seen by games)": "",
 "Everything is up to date": "",
@@ -327,6 +332,8 @@
 "Extra Lepton environment": "",
 "Extra settings for Proton (for testing).": "",
 "Extra settings for the Android container (for testing).": "",
+ "Eye-image snapshots (diagnostics)": "",
+ "Eye-tracked foveation (Valve)": "",
 "failed": "",
 "Failed": "",
 "Failed: {error}": "",
@@ -343,7 +350,9 @@
 "Find automatically": "",
 "firewalld is active. Allow the setup port until the next restart with: sudo firewall-cmd --add-port={port}/tcp": "",
 "First-time setup": "",
+ "Fix crash when the game prepares the microphone": "",
 "Fix depth flicker (Unreal Vulkan)": "",
+ "Fix freezes when controllers vibrate": "",
 "Fix launcher icon entry": "",
 "Fix minimal Android SDK": "",
 "Fix UE4 crash with Unity stub": "",
@@ -360,12 +369,15 @@
 "Folder with VR games (Android APKs or PC VR games)": "",
 "For apps that only know Quest 3/Pro controllers: without it they get no buttons.": "",
 "For games that crash right after you return to them (e.g. after the Steam menu).": "",
+ "For games that freeze the Frame when a controller vibrates (e.g. Lucky's Tale). Needs a rebuild.": "",
+ "For games that judder or shimmer while you hold your head still (e.g. I Am Cat).": "",
 "For games that pause or recenter when the headset briefly loses focus.": "",
 "For games that show the headset's own controllers. Takes effect after a reinstall.": "",
 "For games whose menus or screens jump to wherever you look.": "",
 "For heavy games that use application space warp: it causes artifacts or hangs on non-Quest runtimes (e.g. Asgard's Wrath 2, Batman: Arkham Shadow).": "",
 "For mixed-reality-only games. On the Frame, passthrough is emulated by the FrameBridge adapter (greyscale cameras).": "",
 "For one eye looking wrong (e.g. a jittering right eye): logs each eye's submitted pose against a fresh one, the eye-to-eye relation and when each eye's image was released, also into framebridge.log in the game's storage (some games stop Android's log early). No effect on the game.": "",
+ "For troubleshooting: records the game's requests to Meta's platform services and which ones never get an answer.": "",
 "For Unreal games that close themselves right after starting (e.g. Phantom: Covert Ops). Also disables the in-game Quit.": "",
 "For Unreal games whose models flicker or show through walls and windows on the Frame (e.g. Into The Radius 2). Needs a rebuild.": "",
 "For Vulkan games whose models flicker or vanish while you look at them (e.g. Into The Radius 2). Needs a rebuild.": "",
@@ -433,7 +445,10 @@
 "GiB": "",
 "Gives older Quest games a newer version of Meta's VR plugin that can be converted.": "",
 "GL shim (Mesa GLSL compatibility)": "",
+ "GL shim for Unity (no multisampled render-to-texture)": "",
+ "GL shim only: hide GL_EXT_multisampled_render_to_texture(2) (Zink crashes rendering Unity's runtime MSAA eye buffer through it, e.g. The Room VR).": "",
 "GL shim only: hide GL_OVR_multiview so all passes use single-view shaders. For GLES games whose multiview shaders fail on single-view render targets (e.g. Path of the Warrior).": "",
+ "GL shim: hide multisampled render-to-texture": "",
 "GL shim: hide multiview": "",
 "GL wrapper: OpenGL ES depth formats (Minecraft)": "",
 "Go to my library": "",
@@ -445,7 +460,7 @@
 "Hide Quest foveation": "",
 "Hides Android's back/home/recents buttons, which cover the app's own buttons.": "",
 "Hides Quest foveation extensions the Frame runtime lacks.": "",
- "Hides the Frame's brief focus dips (up to a second) once the game has been focused for a second. For games that recentre or pause every time focus returns.": "",
+ "Hides the Frame's brief focus dips (up to focus_hold_ms) once the game has been focused for a second. On by default: the Frame's wear sensor flickers \"HMD off\" for 0.5-2 s while worn, and many games pause or recentre every time (e.g. Blade & Sorcery, Lucky's Tale).": "",
 "Hides XR_FB_space_warp, so the game renders every frame itself instead of half of them plus motion vectors (Application SpaceWarp). For games whose picture flickers or smears on the Frame (e.g. Unreal Engine 5 games such as Into The Radius 2).": "",
 "High": "",
 "Higher is sharper but needs more power.": "",
@@ -538,10 +553,13 @@
 "Lepton runs VR apps headless: their Android window is never shown, so it never gets keyboard focus and no key press (Steam's on-screen keyboard, a USB/Bluetooth keyboard, Type on Frame) reaches the app's text fields. With Lepton's lepton-show-flatscreen marker the window is shown (behind the VR view, which keeps working) and Steam's keyboard opens for a selected text field. Steam lists the shown window as \"Gamescope\" (the Frame's compositor). Pairs with \"Make Unity text fields work without a system keyboard\".": "",
 "Lepton's Android has no clipboard service, and SDL's Java code (SDL2 and LÖVE games, e.g. Dramatic Shape) registers a clipboard listener at start without checking, so the app crashes with a NullPointerException in SDLClipboardHandler. That call is skipped (an in-place edit of classes.dex).": "",
 "Lets games made for Oculus PCs run on SteamVR.": "",
+ "Lets games start that would stop on Meta's avatar system (e.g. BlazeRush); no Meta avatars.": "",
 "Lets games written for newer OpenXR versions run on the Frame.": "",
 "Lets mixed-reality games start even though they insist on a camera view of your room.": "",
 "Lets older Unity games start VR without Meta's system apps (they'd stay on a 2D screen).": "",
 "Lets SDL and LÖVE games start on the Frame (they'd crash looking for a clipboard).": "",
+ "Lets Team Beef ports (e.g. Lambda1VR) start on the Frame and use their Meta Quest setup.": "",
+ "Lets the game find content it keeps in separate files next to its data (e.g. Star Wars Tales' seasons).": "",
 "Lets the game find language files (like de.lang) that are already in its data, instead of waiting for a download that never comes.": "",
 "Lets typing reach this app: Steam's on-screen keyboard or your computer's keyboard (VR is unaffected).": "",
 "Lets Unity games accept a headset that isn't a Quest.": "",
@@ -558,9 +576,11 @@
 "Loading…": "",
 "Loads FramePort's OpenXR layer under Proton on the Frame. The Frame's SteamVR runtime only accepts OpenXR 1.0 apps, but Proton's VR helper asks for 1.1, so without the layer VR never starts (the game shows as a flat window, or Revive fails with 'Unable to load LibOVRRT DLL'); the layer retries as 1.0. It also emulates xrConvertTimespecTimeToTimeKHR if a runtime refuses it. Ignored on this PC.": "",
 "Loads libglshim.so ahead of libEGL in every engine library that fetches GL through eglGetProcAddress. Fixes Quest-only leniency that Mesa/Zink rejects: #pragma before #extension, implicit int/float conversions (enables GL_EXT_shader_implicit_conversions), and multiview shaders used on single-view framebuffers (hides GL_OVR_multiview; gl_hide_multiview=0 turns that off). Logs every failed shader with its source lines (logcat tag GLShim). Symptom: black screen with working audio in a GLES game.": "",
+ "Loads the GL shim into a Unity GLES game and hides GL_EXT_multisampled_render_to_texture (and the multiview variant). Some Unity games switch their eye buffer to 4x MSAA at runtime; the Frame only gives single-sampled swapchains, Unity then renders through multisampled render-to-texture and Mesa/Zink crashes (SIGSEGV in libgallium_dri.so on the render thread: grey or frozen screen, e.g. The Room VR). Hidden, Unity uses an ordinary MSAA buffer and resolves it. Unity's multiview stays on (gl_hide_multiview defaults to 0 here).": "",
 "Locations": "",
 "Logo": "",
 "Logs details for debugging: composition layers and swapchains, focus changes, play-space creation, pointer vs grip poses, refresh rates. No effect on the game.": "",
+ "Logs every Meta Platform SDK request the game makes (user, entitlement, cloud saves, ...) and the messages that answer them, and every 10 s the requests that never got an answer (logcat tag fp_ovrtrace, in launch.log). For games that wait forever on a loading screen (e.g. Vader Immortal after its intro). Changes nothing: every call goes to the real function.": "",
 "Longer for headsets that briefly think they're off your head.": "",
 "Looking for Frames on your network…": "",
 "Looking for the Frame on a USB cable (Developer Mode on, USB-C port connected to this computer).": "",
@@ -583,7 +603,9 @@
 "Menus and screens": "",
 "Meta Quest": "",
 "Meta XR Audio: skip Quest telemetry class": "",
- "Meta's OVRManager switches Unity to the headset's recommended MSAA level (4x) while the game runs, whatever its quality settings say (log: \"Switching to the recommended level\"). Multisampled render-to-texture on GLES can hang the Frame's GPU, up to a restart of the whole headset (e.g. Lucky's Tale in a menu). Rewrites OVRDisplay.recommendedMSAALevel -> 0 in libil2cpp.so (found with Cpp2IL), so MSAA stays off.": "",
+ "Meta's avatar library needs Meta's Horizon app, which the Frame doesn't have; it then stops the game at start (\"Failed to launch SystemActivities\", e.g. BlazeRush). Replaces it with a library that does nothing, so the game runs without Meta avatars.": "",
+ "Meta's OVRManager switches Unity to the headset's recommended MSAA level (4x) while the game runs, whatever its quality settings say (log: \"Switching to the recommended level\"). Multisampled render-to-texture on GLES can hang the Frame's GPU, up to a restart of the whole headset (e.g. Lucky's Tale in a menu) or a crash of its GL driver (e.g. The Room VR, whose own code sets 4x). Rewrites OVRDisplay.recommendedMSAALevel -> 0 and makes QualitySettings.antiAliasing's setter do nothing in libil2cpp.so (found with Cpp2IL), so MSAA stays off.": "",
+ "Meta's OVROverlay copies a texture into its own compositor layer every frame. For some games (e.g. The Room VR's screen fade, a 4x4 overlay) that copy crashes the Frame's GL driver: SIGSEGV in libgallium_dri.so on Unity's render thread right after a tiny xrCreateSwapchain, grey or frozen screen. Rewrites OVROverlay.PopulateLayer -> false in libil2cpp.so (found with Cpp2IL): overlays are skipped (fades become instant cuts, overlay splash screens don't show). Only for games with this crash: menus drawn as overlays would disappear too.": "",
 "MiB": "",
 "Minecraft asks for desktop OpenGL's GL_DEPTH_COMPONENT32 depth textures. Some builds of LTW, the OpenGL-to-OpenGL ES wrapper in Minecraft launchers such as QuestCraft, pass that on unchanged; Quest's driver accepts it, the Frame's Mesa rejects it (GL_INVALID_OPERATION in glTexImage2D), so the depth buffer never exists and the picture stays black. LTW then loads OpenGL ES through a small shim that asks for GL_DEPTH_COMPONENT32F (or 24-bit) instead.": "",
 "Mirrored": "",
@@ -601,6 +623,7 @@
 "Needs Windows (or WSL on Windows)": "",
 "Neutralises Meta XR Audio's Quest-only calls (Unity/Wwise).": "",
 "never": "",
+ "New config applied: use Update on Frame to install it": "",
 "New folder": "",
 "New folder…": "",
 "New Frame? Run one command on it and FramePort does the rest. Did this once already? Your Frame appears under step 2.": "",
@@ -683,6 +706,7 @@
 "OVRPort converts Quest games from Meta's own VR APIs to standard OpenXR. These are its optional patches.": "",
 "OVRPort marks apps debuggable; that turns on CheckJNI, which aborts some Unreal games on sloppy JNI calls ('JNI DETECTED ERROR', e.g. 'GetStringUTFChars ... NULL' in Time Stall). Clear it for those.": "",
 "OVRPort patches": "",
+ "OVRPort's Meta platform library opens the microphone only when it's started, but answers a game's question about the microphone buffer size from that not-yet-opened stream: games that ask first (Unreal's Oculus voice chat, e.g. The Walking Dead: Saints & Sinners Ch. 2) crash a few seconds after the logo (SIGSEGV in libaaudio.so). Adds the missing check (size 0 until the microphone is started).": "",
 "OVRPort's OpenXR dispatcher aborts the app ('Wrong createInfo size', SIGABRT in libopenxr_loader.so xrCreateSwapchain) when a swapchain is wider or taller than 4096 px, which video players do for 8K video or big theatre textures (e.g. 4XVR). Raises the guard to 16384 px so the Frame's runtime (8192 px max) decides instead.": "",
 "OVRPort's own converter for games that use Meta's oldest VR interface (experimental).": "",
 "OVRPort's own VrApi→OpenXR adapter for engines that call libvrapi.so directly: the same upstream code as FramePort's 'VrApi → OpenXR bridge' without its Frame-specific changes. Only in OVRPort's experimental CLI builds (the stable CLI lists it but can't apply it).": "",
@@ -751,6 +775,7 @@
 "Quest ✓: Lepton is installed, so Quest games can run. PC VR ✓: Proton is installed, so PC VR games can run on the Frame.": "",
 "Quest ✗": "",
 "Queued {len} installs — they run one after another in the background": "",
+ "Quiet Meta's VrApi loader (OpenXR games)": "",
 "Raises minSdk where the loader needs it.": "",
 "Raises the minimum Android version the game declares, so the new parts load.": "",
 "Re-create reference space": "",
@@ -796,6 +821,7 @@
 "Removes Meta's old VR library when the game doesn't need it.": "",
 "Removes OVRPort's controller pose offset if controllers look misplaced.": "",
 "Removes requirements for Quest-only system parts.": "",
+ "Removes the color scale/bias (XR_KHR_composition_layer_color_scale_bias) from the game's layers, so the runtime doesn't apply it. The Frame's runtime allocates GPU memory for it every frame without freeing it, e.g. Vader Immortal leaked ~20 MB/s on its loading screen. Fades done this way no longer show.": "",
 "Removes the game from the Frame. Saves are kept, so a reinstall picks up where you left off.": "",
 "Removes the previous version kept after each reinstall and any leftover uploads. Games and saves aren't touched.": "",
 "Removes {title} from this PC's Steam library (Steam restarts once). The game folder isn't touched.": "",
@@ -803,6 +829,7 @@
 "Rename": "",
 "Rename {name}": "",
 "Rename…": "",
+ "Repeat xrLocateViews queries for the same display time get the first, fully tracked answer again. Games that ask several times per frame got slightly different poses and rendered parts of the frame with different heads: judder (e.g. I Am Cat; proposed by Klownicle, GitHub #8).": "",
 "Replace application label and icon": "",
 "Replaces libvrapi.so with a VrApi→OpenXR bridge (Android-XR-Bridge/OVRPort fork, GPL-3.0, patched for the Frame: GLES sessions, cylinder→quad layers, sRGB format fallback, 30 s VR-mode deadline, emulated time conversion). Needed when the engine calls VrApi itself instead of through OVRPlugin (e.g. The Climb 2, Path of the Warrior); OVRPort cannot translate those.": "",
 "Report a problem": "",
@@ -832,6 +859,7 @@
 "Room height": "",
 "Room width": "",
 "Rotate quads 180°": "",
+ "Routes OVRPlugin through FramePort's extension shim, which turns Meta's amplitude-envelope vibrations into plain ones: OVRPort's loader reads their nanosecond duration as seconds and allocates gigabytes, freezing the Frame when the game vibrates a controller (e.g. Lucky's Tale's save slots, GitHub #9). Needs a rebuild.": "",
 "Runs directly — no Revive needed": "",
 "Runs natively on SteamOS, started from the Frame's Steam library": "",
 "Runs Oculus PC games on OpenXR": "",
@@ -848,6 +876,7 @@
 "Saved. Restart the game to use the new settings.": "",
 "Saved. The settings are used when the game is installed.": "",
 "saves and settings (the app's Android storage)": "",
+ "Scales every controller vibration the game asks for (0-1): plain vibrations, Meta's amplitude envelopes and PCM buffers. For games whose vibrations feel much stronger than on a Quest.": "",
 "Scan a folder": "",
 "Scan a folder…": "",
 "Scan {name}": "",
@@ -907,14 +936,17 @@
 "Size in pixels per eye of the 360° background, redrawn every frame on a background thread (512–4096). Higher is sharper but costs more GPU time per frame.": "",
 "Size of text and layout. Automatic follows Windows' display scaling halfway (150 % in Windows → 125 %) when FramePort runs under WSL, where the window doesn't get it from Windows itself.": "",
 "Skip for now": "",
+ "Skip Meta avatars": "",
 "Skip this version": "",
 "Skips a Quest-only reporting step in Meta's audio library that crashes some games.": "",
 "Skips Meta XR Audio's telemetry under x86_64 ARM translation (emulators). Not needed on the Frame, which runs games natively.": "",
 "Sleep": "",
 "Some apps open a flat Android launcher that then starts a separate VR activity (e.g. WiiCompiled). Shown with Lepton's flat window, that window stays in view after the VR part starts. This makes the VR activity the one Lepton starts (its LAUNCHER category), so the app opens in VR with no flat window. Everything only the launcher does (choosing or importing content) is skipped: turn it off for a run when you need the launcher, and turn off \"Show the app's Android window\".": "",
- "Some engines leave the pNext of unused Vulkan attachment references uninitialized. The Frame's driver never reads it, but Lepton always loads Steam's Fossilize shader-cache layer, which follows it and crashes on the first frame (SIGSEGV in libVkLayer_fossilize.so from FVulkanRenderPass, e.g. Deadpool VR). Loads Vulkan through a small shim that keeps valid pointers and drops only unreadable ones or ones pointing at the wrong structure type.": "",
+ "Some engines leave the pNext of unused Vulkan attachment references uninitialized. The Frame's driver never reads it, but Lepton always loads Steam's Fossilize shader-cache layer, which follows it and crashes on the first frame (SIGSEGV in libVkLayer_fossilize.so from FVulkanRenderPass, e.g. Deadpool VR). Loads Vulkan through a small shim that keeps valid pointers and drops only unreadable ones or ones pointing at the wrong structure type. It also drops a depth resolve named in a subpass without a depth attachment, which crashes the Frame's driver at the first render pass (e.g. Metro Awakening).": "",
 "Some game folders are already set up for SteamVR: a Revive copy (LibRevive64.dll) next to the game, started by a small loader DLL (e.g. xinput1_3.dll) that Windows loads from the game's folder. Then FramePort starts the game program directly — like double-clicking it — instead of through its own Revive (two Revives conflict; e.g. the Oculus Platform check then fails). On the Frame, Wine is told to use those loader DLLs from the game folder instead of its own.": "",
+ "Some games keep content in separate files next to their OBB (e.g. Star Wars: Tales from the Galaxy's Edge: its seasons and sound banks) and ask Meta's platform for them as asset files. OVRPort's platform loader doesn't know them, so the game waits for content that never arrives (black screen after loading). Lists the content files shipped with the game's data (*.pak) as installed and answers their download request at once with the file's path; nothing is copied or downloaded. Shares the language-pack library.": "",
 "Some games need a second build with different OVRPort patches (for some Unreal games: one with Unreal's ForceQuit removed). Turn this on to install that build instead.": "",
+ "Some OpenXR games still ship Meta's VrApi loader and call it a few times without starting VrApi (e.g. Jurassic World Aftermath); Meta's loader then stops the game (\"vrapi_SetPropertyInt was called before vrapi_Initialize()\"). Replaces it with a library that has the same functions, each doing nothing. Only for games whose VR runs through OVRPlugin on OpenXR.": "",
 "Something not working? Collect a diagnostics zip (logs, settings, device info; personal data removed) and attach it to a GitHub issue. For one game, use its menu instead.": "",
 "Something went wrong": "",
 "Sort": "",
@@ -935,6 +967,7 @@
 "Starts the game with options, e.g. to choose SteamVR or OpenXR.": "",
 "Starts the game with the launcher that came with your copy.": "",
 "Status": "",
+ "Steadier head tracking": "",
 "Steady controller input after focus": "",
 "Steam": "",
 "Steam for Windows not found": "",
@@ -948,7 +981,11 @@
 "Stop": "",
 "Stop objects popping in and out": "",
 "Stopped: {why}": "",
+ "Stops a crash a few seconds after the logo in games with voice chat.": "",
+ "Stops a grey or frozen screen in Unity games that turn on anti-aliasing while running (e.g. The Room VR).": "",
+ "Stops a grey screen crash in some Unity games by skipping their overlay layers (e.g. The Room VR's screen fades).": "",
 "Stops Meta's audio library from reporting to Meta (only matters on PC emulators).": "",
+ "Stops Meta's leftover VrApi library from closing the game at start (e.g. Jurassic World Aftermath).": "",
 "Stops some Unreal games from closing themselves right after starting.": "",
 "Stops strict debugging checks that make some games quit.": "",
 "Stops Unreal's crash reporter, which can block the game from starting.": "",
@@ -971,6 +1008,8 @@
 "Tags:": "",
 "Take one in the headset with Steam's screenshot shortcut; it shows up here. Screenshots are matched to the FramePort game that was running.": "",
 "tall, 600 × 900": "",
+ "Team Beef ports: treat the Frame as a Meta headset": "",
+ "Team Beef's ports (e.g. Lambda1VR, RTCWQuest) load an OpenXR library named after the headset maker and pick their VR setup by maker; for \"valve\" they stop at start (libopenxr_loader_valve.so not found) or take the Pico path. Adds that library and lets them take the Meta path.": "",
 "Test": "",
 "Test Proton on the Frame": "",
 "Text and layout size": "",
@@ -1037,14 +1076,17 @@
 "Today": "",
 "Tools": "",
 "Tools are up to date": "",
+ "Trace Meta platform requests (diagnostics)": "",
 "Translator for games built on Meta's oldest VR interface.": "",
 "transparent PNG": "",
 "Treat newer Quest controllers as Touch": "",
 "Tried it in the headset? Tell us how it runs: with your recipe it can join FramePort's built-in list, so it works out of the box for everyone.": "",
 "Troubleshooting": "",
+ "Try \"Fixed\" or \"Off\" if one eye shimmers or jitters while menus look fine.": "",
 "Try again": "",
 "Try now": "",
 "Try Proton Experimental and reinstall": "",
+ "Turn it down if controller vibrations are too strong.": "",
 "Turn off only for games you play with your hands instead of controllers.": "",
 "Turn off space warp": "",
 "Turn on Developer Mode first": "",
@@ -1075,12 +1117,15 @@
 "Uninstall. ": "",
 "Uninstalled {title}": "",
 "Uninstalled {title} and deleted its files on this PC ({size})": "",
- "Unity 2017: start VR without Meta's system apps": "",
- "Unity's older built-in Oculus support (Unity 2017–2018) only starts VR when Android has Meta's com.oculus.systemactivities package; without it the game runs as a hidden 2D app (you see the Android home screen, e.g. Accounting+). Points that package name in libunity.so at \"android\", which always exists, and adds the frame wait its legacy frame loop never makes (libfp_ovrp.so calls ovrp_WaitToBeginFrame before ovrp_Update2; without it no frame starts and the dashboard freezes).": "",
+ "Unity's built-in Oculus support (Unity 2017–2019) only starts VR when Android has Meta's com.oculus.systemactivities package; without it the game runs as a 2D app (the Android home screen or a black window, e.g. Accounting+, BattleSisters). Points that package name in libunity.so at \"android\", which always exists. Games on Unity's built-in VR (2017–2018, and 2019 without the Oculus XR Plugin) also get the frame wait their legacy frame loop never makes (libfp_ovrp.so calls ovrp_WaitToBeginFrame before ovrp_Update2; without it no frame starts, the dashboard freezes or the GPU hangs). The shim also counts a newly pressed trigger or A/B/X/Y as a mouse click (Input.GetMouseButtonDown), which Go-era screens wait for (e.g. Accounting+'s motion warning) and which Lepton never delivers.": "",
+ "Unity's Oculus XR Plugin asks OVRPlugin whether the headset is worn; on the Frame the answer turns to \"not worn\" a few seconds after start. Games that only move the player while the headset is worn then show a frozen body with no head tracking and no controls (e.g. BONELAB). Reports the headset as worn; taking it off still pauses the game through the session's focus.": "",
 "Unity's TMP_InputField / InputField wait for Android's on-screen keyboard and close themselves a frame later when there is none (Lepton has no on-screen keyboard; Meta's system keyboard does this on a Quest), so a selected text field only flashes a caret. Rewrites TouchScreenKeyboardShouldBeUsed -> false and isKeyboardUsingEvents (TMP) / InPlaceEditing (uGUI) -> true in libil2cpp.so, found per game with Cpp2IL (downloaded on first use), so fields stay selected and take key presses: Steam's keyboard (with \"Show the app window\") or Type on Frame from the PC.": "",
 "Unity: disable MSAA": "",
+ "Unity: headset always counts as worn": "",
 "Unity: keep MSAA off at runtime (OVRManager)": "",
 "Unity: render each eye separately (no multiview)": "",
+ "Unity: skip OVROverlay layers (fades, splash screens)": "",
+ "Unity: start VR without Meta's system apps": "",
 "Unknown date": "",
 "Unreal builds of Meta XR Audio abort ('ClassNotFoundException com.oculus.os.AnalyticsEvent') on non-Quest devices. Patches that one JNI FindClass call so the library continues (e.g. NOPE Challenge).": "",
 "Unreal games start CrashReportClient when they crash, which leaves a crash dialog instead of simply closing. This passes -nocrashreports to the game and, on the Frame, renames the game's copy of CrashReportClient.exe so it can't start (your game files on this PC aren't changed).": "",
@@ -1116,6 +1161,7 @@
 "Upside down and mirrored": "",
 "Use controllers": "",
 "Use tags to group and filter your library": "",
+ "Use the new config": "",
 "Use the repack's launcher (bundled Revive)": "",
 "Use this computer's keyboard on the Frame": "",
 "Use this program": "",
@@ -1127,8 +1173,10 @@
 "Uses the store title/icon (OVRPort image service) for the app label.": "",
 "Uses the store's name and icon for the game.": "",
 "Valve's Android runtime isn't installed (needs Developer Mode)": "",
+ "Valve's foveation layer (VALVE_fdm_injection) lowers the image density away from where you look, following each eye's gaze. In some games one eye then shimmers or jitters while menus look fine (the right eye's gaze filter restarts often). \"Fixed\" keeps the foveation but stops it following the gaze (FDM_DEBUG=disable_offsets); \"Off\" loads none of Valve's Vulkan layers (VK_INSTANCE_LAYERS=\"\"; costs GPU time in heavy games).": "",
 "Version": "",
 "Very high": "",
+ "Vibration strength": "",
 "Video panels that an Android media player draws into (XR_KHR_android_surface_swapchain, e.g. I Am Monkey's intro video), which the Frame's runtime refuses, get an Android Surface from FrameBridge: each video frame is copied into an ordinary swapchain the panel shows. Without it these panels are missing and a game waiting for its video stays black. 0 = leave them to the runtime.": "",
 "Video players' virtual theatres and 360° videos would otherwise stay black.": "",
 "Videos": "",
@@ -1140,9 +1188,11 @@
 "VrApi → OpenXR adapter (OVRPort)": "",
 "VrApi → OpenXR bridge": "",
 "Vulkan shader fixes": "",
- "Vulkan shim (frame.vk_sanitize): makes two Unreal habits valid Vulkan - depth images get VK_IMAGE_USAGE_TRANSFER_DST_BIT (they are cleared with vkCmdClearDepthStencilImage) and Qualcomm shader-resolve subpasses lose an invalid depth resolve. Found with the validation layer in Into The Radius 2 (flickering models, windows behind models).": "",
+ "Vulkan shim (frame.vk_sanitize): makes two Unreal habits valid Vulkan - depth images get VK_IMAGE_USAGE_TRANSFER_DST_BIT (they are cleared with vkCmdClearDepthStencilImage) and Qualcomm shader-resolve subpasses lose an invalid depth resolve. Found with the validation layer in Into The Radius 2 (flickering models, windows behind models). Also leaves out image barriers without an image and refuses image views without one, which crash the Frame's driver (e.g. Metro Awakening).": "",
 "Vulkan shim (frame.vk_sanitize): on gives every occlusion query room for both eyes. In multiview passes the Frame's driver writes a zero result for the second eye into the next query, so engines that count on one slot cull visible objects (models popping in and out, e.g. Into The Radius 2). 0 = off, 1 = on (2 slots).": "",
 "Vulkan shim (frame.vk_sanitize): SPIR-V modules matching size + SHA-256 get words inserted at a byte offset, e.g. stores that initialize locals a shader reads before writing (an undefined loop counter hung the GPU in VR4's campaign). Format: <size>:<sha256>:<byte offset>:<word>,<word>,...; several separated by ';'. Comes from a game's recipe.": "",
+ "Vulkan shim (frame.vk_sanitize): the game doesn't see VK_EXT_fragment_density_map(2). Unreal Engine 5 turns on fragment-density-map foveation when the driver offers it and expects the density map from the headset, which the Frame doesn't provide: image views and barriers for a missing image, then a crash in the Frame's Vulkan driver (e.g. Metro Awakening). Valve's own foveation layer isn't affected.": "",
+ "Vulkan shim: hide fragment density maps": "",
 "Vulkan shim: validation layer": "",
 "Vulkan: drop invalid render-pass pointers": "",
 "v{remote} (updates on the next action)": "",
@@ -1282,6 +1332,8 @@
 "{remaining} more after this": "",
 "{title} couldn't be added to the Frame's Steam library: {why}": "",
 "{title} failed: {error}": "",
+ "{title} is already running on the Frame — put the headset on": "",
+ "{title} is already starting — put the headset on": "",
 "{title} isn't in the Frame's Steam library yet: adding it (Steam restarts once)": "",
 "{title} will be in the Frame's Steam library when the game that's running is closed": "",
 "{title} will be in the Frame's Steam library when you're back in Gaming Mode: start it from there": "",
@@ -68,7 +68,8 @@ def needs_xrshim(recipe_patches: dict) -> bool:
    """Adapter features whose functions OVRPort's dispatcher doesn't forward (it only knows a fixed table)."""
    from ..settings import adapter_settings

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


 def add_xrshim(ctx: ApkContext) -> bool:
@@ -0,0 +1,46 @@
+"""Meta's Avatar SDK loader (libovravatarloader.so) needs Meta's Horizon app for its driver. On the Frame it fails
+(ovrAvatar_Initialize: Failed to load AvatarSDK driver), tries to start Meta's SystemActivities error screen, which
+doesn't exist either, and aborts the game ("OVRAvatar-Loader: DisplayErrorAndExit: Failed to launch
+SystemActivities", e.g. BlazeRush). The loader is replaced by a library with the same functions, each doing nothing:
+the game gets no avatar (no message ever arrives, every handle is NULL) and goes on without one.
+"""
+from __future__ import annotations
+
+from ...analysis import elf
+from ...analysis.stubgen import build_stub_library
+from ..base import ApkContext, Patch, register
+
+AVATAR = "libovravatarloader.so"
+
+
+class AvatarStub(Patch):
+    id = "frame.avatar_stub"
+    title = "Skip Meta avatars"
+    description = ("Meta's avatar library needs Meta's Horizon app, which the Frame doesn't have; it then stops the "
+                   "game at start (\"Failed to launch SystemActivities\", e.g. BlazeRush). Replaces it with a "
+                   "library that does nothing, so the game runs without Meta avatars.")
+    order = 58
+
+    def applies(self, a):
+        return AVATAR in a.libs and "arm64-v8a" in a.abis
+
+    def detect(self, a):
+        return None  # triage avatar-driver-missing: games that ship the library without starting it at launch run fine
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a" or not ws.has(ws.lib(AVATAR)):
+            return False
+        data = ws.read_lib(AVATAR)
+        if not elf.is_elf(data):
+            return False
+        exports = sorted(s for s in elf.dyn_symbols(data, True) if s.startswith("ovr"))
+        stub = build_stub_library(exports, soname=AVATAR)
+        if not exports or data == stub:
+            return False
+        ws.put(ws.lib(AVATAR), stub)
+        ctx.notes.append(f"{AVATAR}: {len(exports)} avatar functions do nothing (Meta's avatar driver isn't available)")
+        return True
+
+
+register(AvatarStub)
@@ -2,7 +2,7 @@
 from __future__ import annotations

 from ...analysis import elf
-from ..base import ApkContext, Patch, register
+from ..base import ApkContext, Patch, Suggestion, register
 from . import artifact

 LOADER = "libovrplatformloader.so"
@@ -23,18 +23,33 @@ def with_metadata(lib: bytes, text: str) -> bytes:
    at += len(META_MARK)
    return lib[:at] + raw + b"\0" * (META_LEN - len(raw)) + lib[at + META_LEN:]

+ASSETS_MARK = b"@FPASSETS@"  # native/langpack: g_assets_slot = marker + '0'/'1' (content files listed or not)
+
+
+def with_assets(lib: bytes) -> bytes:
+    """The library with content files (*.pak next to the OBB) listed as installed asset files."""
+    at = lib.find(ASSETS_MARK + b"0")
+    if at < 0:
+        return lib
+    at += len(ASSETS_MARK)
+    return lib[:at] + b"1" + lib[at + 1:]
+
 # Every function native/langpack/langpack.c defines. The loader's own exports of these are hidden (see
 # elf.hide_exports) so lookups reach LIB first; tests/test_langpack.py keeps this list equal to the C source.
 EXPORTS = (
    "ovr_AssetDetailsArray_GetElement", "ovr_AssetDetailsArray_GetSize", "ovr_AssetDetails_GetAssetId",
    "ovr_AssetDetails_GetAssetType", "ovr_AssetDetails_GetDownloadStatus", "ovr_AssetDetails_GetFilepath",
    "ovr_AssetDetails_GetIapStatus", "ovr_AssetDetails_GetLanguage", "ovr_AssetDetails_GetMetadata",
-    "ovr_AssetFileDownloadResult_GetAssetId", "ovr_AssetFileDownloadResult_GetFilepath", "ovr_AssetFile_GetList",
-    "ovr_AssetFile_StatusById", "ovr_Error_GetCode", "ovr_Error_GetDisplayableMessage", "ovr_Error_GetHttpCode",
+    "ovr_AssetFileDownloadResult_GetAssetId", "ovr_AssetFileDownloadResult_GetFilepath",
+    "ovr_AssetFileDownloadUpdate_GetAssetFileId", "ovr_AssetFileDownloadUpdate_GetBytesTotal",
+    "ovr_AssetFileDownloadUpdate_GetBytesTransferred", "ovr_AssetFileDownloadUpdate_GetCompleted",
+    "ovr_AssetFile_DownloadById", "ovr_AssetFile_GetList", "ovr_AssetFile_StatusById", "ovr_Error_GetCode",
+    "ovr_Error_GetDisplayableMessage", "ovr_Error_GetHttpCode",
    "ovr_Error_GetMessage", "ovr_FreeMessage", "ovr_LanguagePackInfo_GetEnglishName",
    "ovr_LanguagePackInfo_GetNativeName", "ovr_LanguagePackInfo_GetTag", "ovr_LanguagePack_GetCurrent",
    "ovr_LanguagePack_SetCurrent", "ovr_Message_GetAssetDetails", "ovr_Message_GetAssetDetailsArray",
-    "ovr_Message_GetAssetFileDownloadResult", "ovr_Message_GetError", "ovr_Message_GetRequestID",
+    "ovr_Message_GetAssetFileDownloadResult", "ovr_Message_GetAssetFileDownloadUpdate", "ovr_Message_GetError",
+    "ovr_Message_GetRequestID",
    "ovr_Message_GetType", "ovr_Message_IsError", "ovr_PopMessage",
 )

@@ -87,4 +102,54 @@ class LanguagePacks(Patch):
        return [("Language-pack library linked to the platform loader", linked and ws.has(ws.lib(LIB)), LIB)]


+class AssetFiles(Patch):
+    id = "frame.asset_files"
+    title = "Content files from the game's data"
+    description = ("Some games keep content in separate files next to their OBB (e.g. Star Wars: Tales from the "
+                   "Galaxy's Edge: its seasons and sound banks) and ask Meta's platform for them as asset files. "
+                   "OVRPort's platform loader doesn't know them, so the game waits for content that never arrives "
+                   "(black screen after loading). Lists the content files shipped with the game's data (*.pak) as "
+                   "installed and answers their download request at once with the file's path; nothing is copied or "
+                   "downloaded. Shares the language-pack library.")
+    order = 33
+
+    def applies(self, a):
+        extra = a.extra or {}
+        return LOADER in a.libs and "arm64-v8a" in a.abis and bool(extra.get("asset_files"))
+
+    def detect(self, a):
+        if self.applies(a) and (a.extra or {}).get("asset_file_api"):
+            n = len(a.extra["asset_files"])
+            return Suggestion(True, f"The game asks Meta's platform for asset files and its data has {n} content "
+                                    "file(s) (*.pak) that OVRPort's loader doesn't report.")
+        return None
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a" or not ws.has(ws.lib(LOADER)):
+            return False
+        loader = ws.read_lib(LOADER)
+        if LIB not in elf.needed(loader):  # frame.langpacks didn't link the library: do it here
+            patched, hidden = elf.hide_exports(loader, EXPORTS)
+            if not hidden:
+                ctx.notes.append("the platform loader has none of the asset-file functions: nothing to replace")
+                return False
+            ws.put(ws.lib(LOADER), elf.add_needed(patched, LIB))
+            ws.put(ws.lib(LIB), with_metadata(artifact(ws.abi, LIB), (ctx.analysis.version or "").strip()))
+        lib = ws.read_lib(LIB)
+        flagged = with_assets(lib)
+        if flagged == lib:
+            return False
+        ws.put(ws.lib(LIB), flagged)
+        ctx.notes.append(f"content files listed as installed asset files by {LIB}")
+        return True
+
+    def validate(self, ctx: ApkContext):
+        ws = ctx.ws
+        if not ws.has(ws.lib(LIB)):
+            return []
+        return [("Content files listed (asset-file library)", ASSETS_MARK + b"1" in ws.read_lib(LIB), LIB)]
+
+
 register(LanguagePacks)
+register(AssetFiles)
@@ -0,0 +1,88 @@
+"""OVRPort's platform loader crashes when a game sizes its microphone buffer before starting the microphone.
+
+OVRPort's `ovr_Microphone_Create` only allocates the handle; the AAudio input stream is opened in
+`ovr_Microphone_Start`. `ovr_Microphone_GetOutputBufferMaxSize` returns `AAudioStream_getFramesPerBurst(stream)`
+without a check, so a game that asks for the buffer size right after Create (Unreal's Oculus voice capture, e.g. The
+Walking Dead: Saints & Sinners Ch. 2) dereferences a NULL stream: SIGSEGV in libaaudio.so on the GameThread a few
+seconds after the logo. Meta's own library allows that order. The function is rewritten in place (same size) to return
+0 while no stream is open and behave as before otherwise.
+"""
+from __future__ import annotations
+
+from ...analysis import elf
+from ..base import ApkContext, Patch, Suggestion, register
+
+LOADER = "libovrplatformloader.so"
+FUNC = "ovr_Microphone_GetOutputBufferMaxSize"
+
+STP = 0xA9BF7BFD       # stp x29, x30, [sp, #-16]!
+MOV_FP = 0x910003FD    # mov x29, sp
+LDR_STREAM = 0xF9400C00  # ldr x0, [x0, #0x18]   (the handle's AAudioStream*)
+BL, BL_MASK = 0x94000000, 0xFC000000
+SXTW = 0x93407C00      # sxtw x0, w0
+LDP = 0xA8C17BFD       # ldp x29, x30, [sp], #16
+RET = 0xD65F03C0
+CBZ_TO_RET = 0xB40000A0  # cbz x0, +0x14 (from the 2nd instruction to the final ret: x0 = 0 is the result)
+
+
+def _words(data: bytes | bytearray, off: int, n: int) -> list[int]:
+    return [int.from_bytes(data[off + 4 * i:off + 4 * i + 4], "little") for i in range(n)]
+
+
+def guard_microphone(data: bytes) -> bytes | None:
+    """The loader with a NULL-stream check in ovr_Microphone_GetOutputBufferMaxSize, or None if the function isn't
+    OVRPort's unchecked 7-instruction version (already fixed, Meta's library, another OVRPort build)."""
+    try:
+        dynsym = elf._elf(data).get_section_by_name(".dynsym")
+    except Exception:  # noqa: BLE001
+        return None
+    found = dynsym.get_symbol_by_name(FUNC) if dynsym is not None else None
+    if not found or not found[0]["st_value"]:
+        return None
+    vaddr = found[0]["st_value"]
+    off = elf.vaddr_to_offset(elf.load_segments(data), vaddr)
+    if off is None or off + 28 > len(data):
+        return None
+    w = _words(data, off, 7)
+    if w[:3] != [STP, MOV_FP, LDR_STREAM] or w[3] & BL_MASK != BL or w[4:] != [SXTW, LDP, RET]:
+        return None
+    # mov x29, sp goes (the frame record is still pushed), which makes room for the check; the bl stays at +12, so
+    # its PC-relative offset is unchanged
+    new = [LDR_STREAM, CBZ_TO_RET, STP, w[3], LDP, SXTW, RET]
+    out = bytearray(data)
+    for i, word in enumerate(new):
+        out[off + 4 * i:off + 4 * i + 4] = word.to_bytes(4, "little")
+    return bytes(out)
+
+
+class OvrMicrophone(Patch):
+    id = "frame.ovr_microphone"
+    title = "Fix crash when the game prepares the microphone"
+    description = ("OVRPort's Meta platform library opens the microphone only when it's started, but answers a "
+                   "game's question about the microphone buffer size from that not-yet-opened stream: games that ask "
+                   "first (Unreal's Oculus voice chat, e.g. The Walking Dead: Saints & Sinners Ch. 2) crash a few "
+                   "seconds after the logo (SIGSEGV in libaaudio.so). Adds the missing check (size 0 until the "
+                   "microphone is started).")
+    order = 46
+
+    def detect(self, a):
+        if a.extra.get("ovr_microphone"):
+            return Suggestion(True, "The game uses Meta's microphone API (ovr_Microphone_GetOutputBufferMaxSize), "
+                                    "which crashes in OVRPort's library before the microphone is started.")
+        return None
+
+    def applies(self, a):
+        return bool(a.extra.get("ovr_microphone")) or LOADER in a.libs
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if not ws.has(ws.lib(LOADER)):
+            return False
+        fixed = guard_microphone(ws.read_lib(LOADER))
+        if fixed:
+            ws.put(ws.lib(LOADER), fixed)
+            ctx.notes.append(f"{LOADER}: {FUNC} checks for an unopened microphone stream")
+        return bool(fixed)
+
+
+register(OvrMicrophone)
@@ -0,0 +1,65 @@
+"""Meta Platform SDK tracer (diagnostics): logs the game's ovr_* calls and their answers (native/ovrtrace)."""
+from __future__ import annotations
+
+from ...analysis import elf
+from ..base import ApkContext, Patch, register
+from . import artifact
+
+LIB = "libfp_ovrtrace.so"
+SKIP = ("libovrplatformloader", "libfp_", "libframe", "libopenxr", "libOVRPlugin", "libvrapi", "libc++")
+
+
+def ovr_importers(ws) -> list[str]:
+    """The game's libraries that call Meta Platform SDK functions (ovr_* imports)."""
+    out = []
+    for lib in ws.libs():
+        if lib.startswith(SKIP):
+            continue
+        data = ws.read_lib(lib)
+        if elf.is_elf(data) and any(s.startswith("ovr_") for s in elf.dyn_symbols(data, False)):
+            out.append(lib)
+    return out
+
+
+class OvrTrace(Patch):
+    id = "frame.ovr_trace"
+    title = "Trace Meta platform requests (diagnostics)"
+    description = ("Logs every Meta Platform SDK request the game makes (user, entitlement, cloud saves, ...) and the "
+                   "messages that answer them, and every 10 s the requests that never got an answer (logcat tag "
+                   "fp_ovrtrace, in launch.log). For games that wait forever on a loading screen (e.g. Vader "
+                   "Immortal after its intro). Changes nothing: every call goes to the real function.")
+    order = 95
+    needs_vr = False
+    experimental = True
+
+    def applies(self, a):
+        return "arm64-v8a" in a.abis and "libovrplatformloader.so" in a.libs
+
+    def detect(self, a):
+        return None  # diagnostics only, on request
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a":
+            return False
+        libs = ovr_importers(ws)
+        for lib in libs:
+            data = ws.read_lib(lib)
+            if LIB not in elf.needed(data):
+                ws.put(ws.lib(lib), elf.add_needed(data, LIB))
+        if libs:
+            ws.put(ws.lib(LIB), artifact(ws.abi, LIB))
+            ctx.notes.append(f"Meta platform calls traced in {', '.join(libs)}")
+        return bool(libs)
+
+    def validate(self, ctx: ApkContext):
+        ws = ctx.ws
+        traced = []
+        for lib in ws.libs():
+            data = b"" if lib.startswith(SKIP) else ws.read_lib(lib)
+            if elf.is_elf(data) and LIB in elf.needed(data):
+                traced.append(lib)
+        return [("Platform tracer loaded", bool(traced) and ws.has(ws.lib(LIB)), ", ".join(traced))] if traced else []
+
+
+register(OvrTrace)
@@ -0,0 +1,69 @@
+"""Team Beef's TBXR ports (Lambda1VR, RTCWQuest, ...) choose their OpenXR setup by headset maker.
+
+Their Java activity does System.loadLibrary("openxr_loader_" + Build.MANUFACTURER) and sets OPENXR_HMD to the same
+name; Lepton reports the maker "valve", so the app stops at once (UnsatisfiedLinkError: libopenxr_loader_valve.so not
+found). Past that, the native code takes Meta's path only where strstr(OPENXR_HMD, "meta") matches and Pico's
+otherwise (XR_PICO_configs_ext and a NULL xrSetConfigPICO call). The patch adds an empty libopenxr_loader_valve.so and
+turns the "meta" literal those checks compare with into "alve", which "valve" contains: the Meta path, which OVRPort
+translates. Checked in Lambda1VR 1.7.3's libxash.so: all six uses of the literal are these strstr checks.
+
+TBXR also draws through multisampled render-to-texture (glFramebufferTexture2DMultisampleEXT +
+glRenderbufferStorageMultisampleEXT) whatever its --msaa setting; on the Frame that framebuffer is incomplete
+(GL_FRAMEBUFFER_INCOMPLETE_MULTISAMPLE, black eyes). The GL shim (libglshim.so, linked into the TBXR library) hands
+it single-sampled versions of both.
+"""
+from __future__ import annotations
+
+from ...analysis import elf
+from ...analysis.stubgen import build_stub_library
+from ..base import ApkContext, Patch, Suggestion, register
+from . import artifact
+from .vrapi_bridge import SHIM
+
+VENDOR_LOADER = "libopenxr_loader_valve.so"
+
+
+class TbxrVendor(Patch):
+    id = "frame.tbxr_vendor"
+    title = "Team Beef ports: treat the Frame as a Meta headset"
+    description = ("Team Beef's ports (e.g. Lambda1VR, RTCWQuest) load an OpenXR library named after the headset maker "
+                   "and pick their VR setup by maker; for \"valve\" they stop at start (libopenxr_loader_valve.so not "
+                   "found) or take the Pico path. Adds that library and lets them take the Meta path.")
+    order = 47
+
+    def applies(self, a):
+        return bool((a.extra or {}).get("tbxr_libs")) and "arm64-v8a" in a.abis
+
+    def detect(self, a):
+        if self.applies(a):
+            return Suggestion(True, "Team Beef port: it picks its OpenXR setup by headset maker, which the Frame "
+                                    "reports as \"valve\".")
+        return None
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a":
+            return False
+        changed = False
+        for lib in (ctx.analysis.extra or {}).get("tbxr_libs") or []:
+            if not ws.has(ws.lib(lib)):
+                continue
+            data, count = elf.replace_rodata_string(ws.read_lib(lib), "meta", "alve")
+            if count:
+                ws.put(ws.lib(lib), data)
+                ctx.notes.append(f"{lib}: headset checks for \"meta\" match \"valve\" ({count})")
+                changed = True
+            data = ws.read_lib(lib)
+            if "eglGetProcAddress" in elf.dyn_symbols(data, False) and SHIM not in elf.needed(data):
+                ws.put(ws.lib(lib), elf.add_needed(data, SHIM))  # its GL comes through eglGetProcAddress
+                ctx.notes.append(f"GL shim loaded by {lib} (single-sampled render-to-texture)")
+                changed = True
+        if changed or ws.has(ws.lib(SHIM)):
+            ws.put(ws.lib(SHIM), artifact(ws.abi, SHIM))
+        if not ws.has(ws.lib(VENDOR_LOADER)):
+            ws.put(ws.lib(VENDOR_LOADER), build_stub_library([], soname=VENDOR_LOADER))
+            changed = True
+        return changed
+
+
+register(TbxrVendor)
@@ -5,6 +5,8 @@ Android home screen, e.g. Accounting+, Unity 2017.4). The package name in libuni
 installed): a same-length, in-place string edit; everything else about the check stays as it is."""
 from __future__ import annotations

+import os
+
 from ...analysis import elf
 from ..base import ApkContext, Patch, Suggestion, register
 from . import artifact
@@ -14,38 +16,95 @@ ALWAYS_THERE = "android"
 # Unity's legacy frame loop never calls ovrp_WaitToBeginFrame: its ovrp_Update2 lookup goes to native/ovrpshim
 SHIM = "libfp_ovrp.so"
 UPDATE, SHIM_UPDATE = "ovrp_Update2", "fpov_Update2"
+# Unity creates its XR controller devices for the hand nodes OVRPlugin reports present (logged/fixed by the shim)
+NODE, SHIM_NODE = "ovrp_GetNodePresent", "fpov_GetNodePresent"
 # input diagnostics (off): the C# P/Invoke names in libil2cpp.so pointed at the shim's wrappers, which log what they
 # return, report input focus as true and release buttons held > 2 s. Accounting+ still didn't pass "press any button"
 # with them (input reached the game cleanly), so they stay off; switch on to investigate another game.
-INPUT_PROBE = False
+INPUT_PROBE = os.environ.get("FRAMEPORT_INPUT_PROBE") == "1"  # diagnostic builds only
 INPUT_CALLS = ("ovrp_GetConnectedControllers", "ovrp_GetControllerState4", "ovrp_GetControllerState2",
               "ovrp_GetAppHasInputFocus")
 UNITY_INPUT_CALLS = ("ovrp_GetControllerState", "ovrp_GetControllerState2")


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

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

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

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

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


+class UnityNoOverlayCopy(Il2cppReturnPatch):
+    id = "frame.unity_no_overlay_copy"
+    title = "Unity: skip OVROverlay layers (fades, splash screens)"
+    description = ("Meta's OVROverlay copies a texture into its own compositor layer every frame. For some games "
+                   "(e.g. The Room VR's screen fade, a 4x4 overlay) that copy crashes the Frame's GL driver: SIGSEGV "
+                   "in libgallium_dri.so on Unity's render thread right after a tiny xrCreateSwapchain, grey or frozen "
+                   "screen. Rewrites OVROverlay.PopulateLayer -> false in libil2cpp.so (found with Cpp2IL): overlays "
+                   "are skipped (fades become instant cuts, overlay splash screens don't show). Only for games with "
+                   "this crash: menus drawn as overlays would disappear too.")
+    order = 49
+    targets = {"Oculus.VR/OVROverlay.cs": {"PopulateLayer": RET_ZERO},
+               "Assembly-CSharp/OVROverlay.cs": {"PopulateLayer": RET_ZERO}}  # older Oculus Integration
+    check_name = "Unity overlays"
+
+    def applies(self, a):
+        return a.engine == "Unity" and "libil2cpp.so" in a.libs and not a.only_32bit and "GLES" in a.graphics
+
+    def detect(self, a):
+        return None  # only for a game that shows the crash (catalog recipe or the user's choice)
+
+
 register(UnityRuntimeMsaa)
 register(UnityMultiPass)
+register(UnityNoOverlayCopy)
@@ -0,0 +1,59 @@
+"""Unity's Oculus XR Plugin gives its HMD input device a UserPresence feature from OVRPlugin (ovrp_GetUserPresent2).
+On the Frame, OVRPort's OVRPlugin reports the headset as not worn a few seconds after start, while it is worn (BONELAB,
+right after Unity switches XR loaders). Games that drive their player rig only while the user is present then show a
+frozen body: no head tracking, controllers stuck to the model, no buttons (BONELAB's Marrow rig checks
+XRHMD.IsUserPresent every frame). The plugin's lookup of that function is pointed at native/ovrpshim, which reports
+the user as present (the session's focus still pauses the game when the headset is taken off)."""
+from __future__ import annotations
+
+from ...analysis import elf
+from ..base import ApkContext, Patch, register
+from . import artifact
+from .unity_oculus_check import SHIM
+
+XR_PLUGIN = "libOculusXRPlugin.so"
+CALL, SHIM_CALL = "ovrp_GetUserPresent2", "fpov_GetUserPresent2"  # same length: an in-place string edit
+
+
+class UnityUserPresence(Patch):
+    id = "frame.unity_user_presence"
+    title = "Unity: headset always counts as worn"
+    description = ("Unity's Oculus XR Plugin asks OVRPlugin whether the headset is worn; on the Frame the answer "
+                   "turns to \"not worn\" a few seconds after start. Games that only move the player while the "
+                   "headset is worn then show a frozen body with no head tracking and no controls (e.g. BONELAB). "
+                   "Reports the headset as worn; taking it off still pauses the game through the session's focus.")
+    order = 46
+    revision = 1
+
+    def applies(self, a):
+        return a.engine == "Unity" and "arm64-v8a" in a.abis and XR_PLUGIN in a.libs and "libOVRPlugin.so" in a.libs
+
+    def detect(self, a):
+        return None  # per game (catalog): most games don't depend on user presence
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        xr, plugin = ws.lib(XR_PLUGIN), ws.lib("libOVRPlugin.so")
+        if ws.abi != "arm64-v8a" or not ws.has(xr) or not ws.has(plugin):
+            return False
+        data, count = elf.replace_rodata_string(ws.read(xr), CALL, SHIM_CALL)
+        if not count:
+            return False
+        ws.put(xr, data)
+        ovrp = ws.read(plugin)
+        if SHIM not in elf.needed(ovrp):  # the plugin's dlsym on OVRPlugin's handle also searches its dependencies
+            ws.put(plugin, elf.add_needed(ovrp, SHIM))
+        ws.put(ws.lib(SHIM), artifact(ws.abi, SHIM))
+        ctx.notes.append(f"{XR_PLUGIN}: {CALL} -> {SHIM_CALL} ({SHIM} reports the user as present)")
+        return True
+
+    def validate(self, ctx: ApkContext):
+        ws = ctx.ws
+        xr, plugin = ws.lib(XR_PLUGIN), ws.lib("libOVRPlugin.so")
+        if not ws.has(xr) or SHIM_CALL.encode() not in ws.read(xr):
+            return []
+        linked = ws.has(plugin) and SHIM in elf.needed(ws.read(plugin)) and ws.has(ws.lib(SHIM))
+        return [("User presence shim loaded", linked, SHIM)]
+
+
+register(UnityUserPresence)
@@ -35,7 +35,9 @@ class VulkanSanitize(Patch):
                   "driver never reads it, but Lepton always loads Steam's Fossilize shader-cache layer, which follows "
                   "it and crashes on the first frame (SIGSEGV in libVkLayer_fossilize.so from FVulkanRenderPass, "
                   "e.g. Deadpool VR). Loads Vulkan through a small shim that keeps valid pointers and drops only "
-                   "unreadable ones or ones pointing at the wrong structure type.")
+                   "unreadable ones or ones pointing at the wrong structure type. It also drops a depth resolve "
+                   "named in a subpass without a depth attachment, which crashes the Frame's driver at the first "
+                   "render pass (e.g. Metro Awakening).")
    order = 72
    default_on = True

@@ -19,6 +19,7 @@ class VrApiBridge(Patch):
    )
    order = 60
    experimental = True
+    conflicts = ("frame.vrapi_stub",)

    def detect(self, a):
        if a.direct_vrapi and "arm64-v8a" in a.abis:
@@ -84,5 +85,29 @@ class GlShim(Patch):
        return True


+class UnityGlShim(GlShim):
+    id = "frame.unity_gl_shim"
+    title = "GL shim for Unity (no multisampled render-to-texture)"
+    description = (
+        "Loads the GL shim into a Unity GLES game and hides GL_EXT_multisampled_render_to_texture (and the multiview "
+        "variant). Some Unity games switch their eye buffer to 4x MSAA at runtime; the Frame only gives single-sampled "
+        "swapchains, Unity then renders through multisampled render-to-texture and Mesa/Zink crashes (SIGSEGV in "
+        "libgallium_dri.so on the render thread: grey or frozen screen, e.g. The Room VR). Hidden, Unity uses an "
+        "ordinary MSAA buffer and resolves it. Unity's multiview stays on (gl_hide_multiview defaults to 0 here).")
+    order = 62
+    requires = ()
+    experimental = False
+
+    def detect(self, a):
+        if self.applies(a) and ((a.extra or {}).get("ovr_runtime_msaa") or a.unity_msaa_levels):
+            return Suggestion(True, "Unity GLES game that may switch to MSAA at runtime: hide multisampled "
+                                    "render-to-texture, which crashes the Frame's GL driver (e.g. The Room VR).")
+        return None
+
+    def applies(self, a):
+        return a.engine == "Unity" and "GLES" in a.graphics and "arm64-v8a" in a.abis
+
+
 register(VrApiBridge)
 register(GlShim)
+register(UnityGlShim)
@@ -0,0 +1,58 @@
+"""Meta's own VrApi loader left in an OpenXR game: replaced by a library that answers every VrApi call with 0.
+
+Some Unity games ship Meta's libvrapi.so next to an OpenXR OVRPlugin (e.g. Jurassic World Aftermath, OVRPlugin
+1.89.1). OVRPlugin runs on OpenXR, but still calls a few VrApi functions (vrapi_SetPropertyInt) without ever calling
+vrapi_Initialize; Meta's loader aborts on that ("vrapi_SetPropertyInt was called before vrapi_Initialize()!", SIGABRT
+on UnityMain right after the OpenXR instance is created). The VrApi bridge can't take its place: it implements a
+different, smaller set of functions (39 of the loader's 114), so OVRPlugin wouldn't link at all.
+"""
+from __future__ import annotations
+
+from ...analysis import elf
+from ...analysis.stubgen import build_stub_library
+from ..base import ApkContext, Patch, register
+
+VRAPI = "libvrapi.so"
+
+
+class VrApiStub(Patch):
+    id = "frame.vrapi_stub"
+    title = "Quiet Meta's VrApi loader (OpenXR games)"
+    description = ("Some OpenXR games still ship Meta's VrApi loader and call it a few times without starting VrApi "
+                   "(e.g. Jurassic World Aftermath); Meta's loader then stops the game (\"vrapi_SetPropertyInt was "
+                   "called before vrapi_Initialize()\"). Replaces it with a library that has the same functions, each "
+                   "doing nothing. Only for games whose VR runs through OVRPlugin on OpenXR.")
+    order = 59
+    conflicts = ("frame.vrapi_bridge",)
+
+    def applies(self, a):
+        return VRAPI in a.libs and "libOVRPlugin.so" in a.libs and not a.direct_vrapi and "arm64-v8a" in a.abis
+
+    def detect(self, a):
+        return None  # suggested by triage (signature vrapi-before-init): most such games never call it
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a" or not ws.has(ws.lib(VRAPI)):
+            return False
+        data = ws.read_lib(VRAPI)
+        if not elf.is_elf(data):
+            return False
+        exports = sorted(s for s in elf.dyn_symbols(data, True) if s.startswith(("vrapi_", "ovr")))
+        stub = build_stub_library(exports, soname=VRAPI)
+        if not exports or data == stub:
+            return False  # nothing to stand in for, or already the stub
+        ws.put(ws.lib(VRAPI), stub)
+        ctx.notes.append(f"{VRAPI}: {len(exports)} functions answer 0 (Meta's loader aborted calls made before init)")
+        return True
+
+    def validate(self, ctx: ApkContext):
+        ws = ctx.ws
+        if not ws.has(ws.lib(VRAPI)) or not ws.has(ws.lib("libOVRPlugin.so")):
+            return []
+        have = elf.dyn_symbols(ws.read_lib(VRAPI), True)
+        need = {s for s in elf.dyn_symbols(ws.read_lib("libOVRPlugin.so"), False) if s.startswith("vrapi_")}
+        return [("OVRPlugin's VrApi functions present", need <= have, ", ".join(sorted(need - have)[:5]))]
+
+
+register(VrApiStub)
@@ -16,6 +16,14 @@ SETTINGS = [
    ("scale", "float", 1.0, "Resolution scale",
     "Multiplies the recommended eye-buffer width and height (0.5–2.0). 1.5 ≈ 2.25× pixels."),
    ("foveation_fix", "int", 1, "Hide Quest foveation", "Hides Quest foveation extensions the Frame runtime lacks."),
+    ("snapshot", "int", 0, "Eye-image snapshots (diagnostics)",
+     "Every N seconds, saves the left-eye image the game submits (a quarter of its size) as fb_snap_0-7.ppm in the "
+     "game's files folder on the Frame. Launch tests run without anyone wearing the headset, so the headset view stays "
+     "black; this shows what the game itself draws. OpenGL ES games only."),
+    ("strip_color_bias", "int", 0, "Drop layer color fades",
+     "Removes the color scale/bias (XR_KHR_composition_layer_color_scale_bias) from the game's layers, so the runtime "
+     "doesn't apply it. The Frame's runtime allocates GPU memory for it every frame without freeing it, e.g. Vader "
+     "Immortal leaked ~20 MB/s on its loading screen. Fades done this way no longer show."),
    ("hide_space_warp", "int", 0, "Turn off space warp",
     "Hides XR_FB_space_warp, so the game renders every frame itself instead of half of them plus motion vectors "
     "(Application SpaceWarp). For games whose picture flickers or smears on the Frame (e.g. Unreal Engine 5 games "
@@ -61,10 +69,11 @@ SETTINGS = [
    ("stable_local", "int", 0, "Keep the play space still",
     "Every 'local' play space the game creates lines up with the one at the start. For games whose menus or screens "
     "jump to where you look on the Frame."),
-    ("focus_hold", "int", 0, "Ignore brief focus dips",
-     "Hides the Frame's brief focus dips (up to a second) once the game has been focused for a second. For "
-     "games that recentre or pause every time focus returns."),
-    ("focus_hold_ms", "float", 1000.0, "Longest focus dip to ignore (ms)",
+    ("focus_hold", "int", 1, "Ignore brief focus dips",
+     "Hides the Frame's brief focus dips (up to focus_hold_ms) once the game has been focused for a second. On by "
+     "default: the Frame's wear sensor flickers \"HMD off\" for 0.5-2 s while worn, and many games pause or recentre "
+     "every time (e.g. Blade & Sorcery, Lucky's Tale)."),
+    ("focus_hold_ms", "float", 5000.0, "Longest focus dip to ignore (ms)",
     "focus_hold hides focus dips up to this long (100-5000). Longer for a headset whose wear sensor flickers "
     "(\"HMD off\" for 0.5-2 s while worn, e.g. Blade & Sorcery pausing); taking the headset off or the system menu "
     "pauses the game only after this long."),
@@ -76,6 +85,9 @@ SETTINGS = [
     "Apps that suggest controller bindings only for Meta's newer profiles (Touch Plus, Touch Pro), which the Frame's "
     "runtime rejects (XR_ERROR_PATH_UNSUPPORTED), get the same bindings as oculus/touch_controller instead "
     "(components Touch lacks are dropped). Without it such apps get no controller input."),
+    ("haptic_scale", "float", 1.0, "Vibration strength",
+     "Scales every controller vibration the game asks for (0-1): plain vibrations, Meta's amplitude envelopes and "
+     "PCM buffers. For games whose vibrations feel much stronger than on a Quest."),
    ("aim_pitch", "float", 0.0, "Pointer tilt (degrees)",
     "Tilts the controllers' pointing ray up (+) or down (−), for games whose pointer doesn't hit what you aim at."),
    ("aim_yaw", "float", 0.0, "Pointer turn (degrees)", "Turns the controllers' pointing ray left (+) or right (−)."),
@@ -108,6 +120,14 @@ SETTINGS = [
     "Override the guardian width (0 = use guardian, min 1.5 m)."),
    ("scene_depth", "float", 0.0, "Emulated room depth (m)",
     "Override the guardian depth (0 = use guardian, min 1.5 m)."),
+    ("pose_consistency", "int", 0, "Consistent head poses per frame",
+     "Repeat xrLocateViews queries for the same display time get the first, fully tracked answer again. Games that "
+     "ask several times per frame got slightly different poses and rendered parts of the frame with different heads: "
+     "judder (e.g. I Am Cat; proposed by Klownicle, GitHub #8)."),
+    ("haptic_fix", "int", 0, "Fix controller vibration freezes",
+     "Routes OVRPlugin through FramePort's extension shim, which turns Meta's amplitude-envelope vibrations into "
+     "plain ones: OVRPort's loader reads their nanosecond duration as seconds and allocates gigabytes, freezing the "
+     "Frame when the game vibrates a controller (e.g. Lucky's Tale's save slots, GitHub #9). Needs a rebuild."),
    ("rect_clamp", "int", 1, "Clamp image rects",
     "Keeps every submitted image rect inside its swapchain. Unity can size the eye area a few pixels past the image "
     "on some Frames; SteamVR then rejects every frame (xrEndFrame -25, XR_ERROR_SWAPCHAIN_RECT_INVALID) and the game "
@@ -131,10 +151,19 @@ SETTINGS = [
     "Vulkan shim (frame.vk_sanitize): makes two Unreal habits valid Vulkan - depth images get "
     "VK_IMAGE_USAGE_TRANSFER_DST_BIT (they are cleared with vkCmdClearDepthStencilImage) and Qualcomm shader-resolve "
     "subpasses lose an invalid depth resolve. Found with the validation layer in Into The Radius 2 (flickering "
-     "models, windows behind models)."),
+     "models, windows behind models). Also leaves out image barriers without an image and refuses image views without "
+     "one, which crash the Frame's driver (e.g. Metro Awakening)."),
    ("vk_validation", "int", 0, "Vulkan shim: validation layer",
     "Diagnostics: the Vulkan shim (frame.vk_sanitize) adds Khronos' validation layer to the game's instance; its "
     "findings go to launch.log. The layer library (libVkLayer_khronos_validation.so) must be in the APK."),
+    ("gl_hide_msrtt", "int", 1, "GL shim: hide multisampled render-to-texture",
+     "GL shim only: hide GL_EXT_multisampled_render_to_texture(2) (Zink crashes rendering Unity's runtime MSAA eye "
+     "buffer through it, e.g. The Room VR)."),
+    ("vk_hide_fdm", "int", 0, "Vulkan shim: hide fragment density maps",
+     "Vulkan shim (frame.vk_sanitize): the game doesn't see VK_EXT_fragment_density_map(2). Unreal Engine 5 turns on "
+     "fragment-density-map foveation when the driver offers it and expects the density map from the headset, which the "
+     "Frame doesn't provide: image views and barriers for a missing image, then a crash in the Frame's Vulkan driver "
+     "(e.g. Metro Awakening). Valve's own foveation layer isn't affected."),
    ("gl_hide_multiview", "int", 1, "GL shim: hide multiview",
     "GL shim only: hide GL_OVR_multiview so all passes use single-view shaders. For GLES games whose multiview "
     "shaders fail on single-view render targets (e.g. Path of the Warrior)."),
@@ -143,7 +172,7 @@ SETTINGS = [

 # settings that need a new build, not only new settings files: the Vulkan shim learned vk_shader_fix in 0.6.4 and
 # vk_query_slots and vk_spec_fixes in 0.10.0
-REVISIONS = {"vk_shader_fix": 2, "vk_query_slots": 3, "vk_spec_fixes": 2}
+REVISIONS = {"vk_shader_fix": 2, "vk_query_slots": 3, "vk_spec_fixes": 2, "haptic_fix": 2, "pose_consistency": 2}

 # How the "Game settings" dialog shows each setting to non-technical users: group, level (common settings are always
 # shown; advanced ones only under "Show advanced settings"), a plain label and one-line help, the control, and the
@@ -164,6 +193,13 @@ UI: dict[str, dict] = {
    "focus_hold_ms": dict(group="screens", level="advanced", label="Ignore focus dips up to", depends="focus_hold",
                          help="Longer for headsets that briefly think they're off your head.",
                          control=("slider", 500.0, 3000.0, 100.0, "{:.0f} ms")),
+    "pose_consistency": dict(group="picture", level="advanced", label="Steadier head tracking",
+                             help="For games that judder or shimmer while you hold your head still (e.g. I Am Cat).",
+                             control=("switch",)),
+    "haptic_fix": dict(group="controllers", level="advanced", label="Fix freezes when controllers vibrate",
+                       help="For games that freeze the Frame when a controller vibrates (e.g. Lucky's Tale). Needs a "
+                            "rebuild.",
+                       control=("switch",)),
    "vk_spec_fixes": dict(group="troubleshooting", level="advanced", label="Fix depth flicker (Unreal Vulkan)",
                          help="For Unreal games whose models flicker or show through walls and windows on the Frame "
                               "(e.g. Into The Radius 2). Needs a rebuild.",
@@ -178,6 +214,9 @@ UI: dict[str, dict] = {
    "profile_remap": dict(group="controllers", level="advanced", label="Treat newer Quest controllers as Touch",
                          help="For apps that only know Quest 3/Pro controllers: without it they get no buttons.",
                          control=("switch",)),
+    "haptic_scale": dict(group="controllers", level="common", label="Vibration strength",
+                         help="Turn it down if controller vibrations are too strong.",
+                         control=("slider", 0.0, 1.0, 0.05, "{:.0%}")),
    "aim_pitch": dict(group="controllers", level="common", label="Pointer angle",
                      help="If the pointer doesn't hit what you aim at, tilt it up or down.",
                      control=("slider", -30.0, 30.0, 1.0, "{:+.0f}°")),
@@ -236,8 +275,8 @@ UI: dict[str, dict] = {
                            control=("choice", [(0, "As the game sends it"), (2, "Flat")])),
    **{key: dict(group="troubleshooting", level="advanced", control=("switch",)) for key in (
        "foveation_fix", "hide_space_warp", "swapchain_fix", "layer_fix", "gl_hide_multiview", "mutable_fix",
-        "flip_quads", "swap_eyes", "vk_validation", "rect_clamp",
-        "strip_depth", "respace_kick", "layer_debug", "eye_debug", "release_wait")},
+        "flip_quads", "swap_eyes", "vk_validation", "rect_clamp", "gl_hide_msrtt", "strip_color_bias", "snapshot",
+        "strip_depth", "respace_kick", "layer_debug", "eye_debug", "release_wait", "vk_hide_fdm")},
 }


@@ -263,6 +302,10 @@ class AdapterSetting(Patch):
        if self.key == "controller_models" and uses_render_models(a):
            return Suggestion(True, "The game asks the headset for its controller models: show Steam Frame controllers "
                                    "instead of Quest Touch controllers.", {"value": 1})
+        if self.key == "haptic_fix" and "libOVRPlugin.so" in a.libs:
+            return Suggestion(True, "Meta's OVRPlugin vibrates controllers through OVRPort's loader, which turns some "
+                                    "vibrations into gigabyte allocations that freeze the Frame (e.g. Lucky's Tale, "
+                                    "BattleSisters): vibrations are converted before they reach it.", {"value": 1})
        if self.key == "equirect_emul" and uses_equirect_layers(a):
            return Suggestion(True, "The game draws 360° layers (e.g. a video player's theatre or 360° videos), which "
                                    "the Frame's runtime can't show: show them as panels around you.", {"value": 1})
@@ -291,9 +334,12 @@ class AdapterSetting(Patch):
            "mutable_fix": ap.is_vulkan,
            "swapchain_fix": ap.is_gles,
            "gl_hide_multiview": lambda a: a.direct_vrapi and ap.is_gles(a),
+            "gl_hide_msrtt": ap.is_gles,
            "vk_shader_fix": lambda a: a.engine == "Unreal",  # read by the Vulkan shim, which only Unreal games get
+            "vk_hide_fdm": lambda a: a.engine == "Unreal",  # Unreal's Vulkan isn't always detected (Metro Awakening)
            "vk_query_slots": lambda a: a.engine == "Unreal" and ap.is_vulkan(a),
            "vk_validation": lambda a: a.engine == "Unreal",
+            "haptic_fix": lambda a: "libOVRPlugin.so" in a.libs,
            "vk_spec_fixes": lambda a: a.engine == "Unreal" and ap.is_vulkan(a),
            "controller_models": ap.may_use_render_models,
            **{k: ap.is_gles for k in ("equirect_emul", "equirect_face", "equirect_res", "equirect_flip",
@@ -386,6 +432,25 @@ class HideNavBar(Patch):
        ctx.env.update(self.ENV)


+class Foveation(Patch):
+    id = "device.foveation"
+    title = "Eye-tracked foveation (Valve)"
+    description = ("Valve's foveation layer (VALVE_fdm_injection) lowers the image density away from where you look, "
+                   "following each eye's gaze. In some games one eye then shimmers or jitters while menus look fine "
+                   "(the right eye's gaze filter restarts often). \"Fixed\" keeps the foveation but stops it "
+                   "following the gaze (FDM_DEBUG=disable_offsets); \"Off\" loads none of Valve's Vulkan layers "
+                   "(VK_INSTANCE_LAYERS=\"\"; costs GPU time in heavy games).")
+    category = "device"
+    stage = "install"
+    params = [Param("mode", "str", "", "fixed or off (empty = Valve's default)")]
+    CHOICES = (("", "Default"), ("fixed", "Fixed (doesn't follow the eyes)"), ("off", "Off"))
+    ENV = {"fixed": {"FDM_DEBUG": "disable_offsets"}, "off": {"VK_INSTANCE_LAYERS": ""}}
+
+    def install(self, ctx: InstallContext) -> None:
+        # runs after device.lepton_env (install_context), so this choice wins over a recipe's VK_INSTANCE_LAYERS
+        ctx.env.update(self.ENV.get(ctx.params.get("mode") or "", {}))
+
+
 class TextInputWindow(Patch):
    id = "device.text_input_window"
    title = "Show the app's Android window (for typing)"
@@ -416,3 +481,4 @@ register(DeviceFiles)
 register(LeptonEnv)
 register(HideNavBar)
 register(TextInputWindow)
+register(Foveation)
@@ -42,12 +42,20 @@ SUMMARIES = {
                            "launcher, e.g. to import new content).",
    "frame.ltw_depth": "Fixes the black picture in Minecraft launchers (e.g. QuestCraft): uses depth formats the "
                       "Frame's graphics driver accepts.",
+    "frame.unity_gl_shim": "Stops a grey or frozen screen in Unity games that turn on anti-aliasing while running "
+                           "(e.g. The Room VR).",
+    "frame.unity_no_overlay_copy": "Stops a grey screen crash in some Unity games by skipping their overlay "
+                                   "layers (e.g. The Room VR's screen fades).",
    "frame.nodebug": "Stops strict debugging checks that make some games quit.",
    "frame.meta_permissions": "Declares Meta's permissions some mixed-reality games ask for, so they don't stop.",
    "frame.ovrplatformcompat": "Adds a small piece of Meta's platform library that some games need to start.",
    "frame.ovrstubs": "Provides stand-ins for Meta store functions the game expects, so it doesn't crash at start.",
    "frame.langpacks": "Lets the game find language files (like de.lang) that are already in its data, instead of "
                       "waiting for a download that never comes.",
+    "frame.ovr_trace": "For troubleshooting: records the game's requests to Meta's platform services and which ones "
+                       "never get an answer.",
+    "frame.unity_user_presence": "Counts the headset as worn, so games that only move the player while it's worn "
+                                 "get head tracking and controls (e.g. BONELAB).",
    "frame.unity_no_msaa": "Turns off a smoothing setting that crashes some older Unity games on the Frame.",
    "frame.unity_runtime_msaa_off": "Keeps a smoothing setting off that the game turns on itself and that can freeze "
                                    "the Frame.",
@@ -56,6 +64,13 @@ SUMMARIES = {
                                "screen).",
    "frame.unity_multipass": "Draws each eye separately; try it when one eye shows a grey or broken picture.",
    "frame.swapchain_limit": "Allows very large pictures (8K video, theatres) instead of quitting.",
+    "frame.vrapi_stub": "Stops Meta's leftover VrApi library from closing the game at start (e.g. Jurassic World "
+                        "Aftermath).",
+    "frame.tbxr_vendor": "Lets Team Beef ports (e.g. Lambda1VR) start on the Frame and use their Meta Quest setup.",
+    "frame.asset_files": "Lets the game find content it keeps in separate files next to its data (e.g. Star Wars "
+                         "Tales' seasons).",
+    "frame.ovr_microphone": "Stops a crash a few seconds after the logo in games with voice chat.",
+    "frame.avatar_stub": "Lets games start that would stop on Meta's avatar system (e.g. BlazeRush); no Meta avatars.",
    "frame.vrapi_bridge": "Translator for games built on Meta's oldest VR interface.",
    "frame.gl_shim": "Fixes graphics code that the Frame's drivers reject (black screen with sound).",
    "frame.metaxr_telemetry": "Skips a Quest-only reporting step in Meta's audio library that crashes some games.",
@@ -68,6 +83,7 @@ SUMMARIES = {
    "device.text_input_window": "Lets typing reach this app: Steam's on-screen keyboard or your computer's keyboard "
                                "(VR is unaffected).",
    "device.lepton_env": "Extra settings for the Android container (for testing).",
+    "device.foveation": "Try \"Fixed\" or \"Off\" if one eye shimmers or jitters while menus look fine.",
    # PC VR
    "pcvr.repack_launcher": "Starts the game with the launcher that came with your copy.",
    "pcvr.launch_args": "Starts the game with options, e.g. to choose SteamVR or OpenXR.",
@@ -353,6 +353,7 @@ def add_game(src: SourceGame, reporter: Reporter | None = None) -> dict:
        reporter.log(f"analyzing {src.apk.name}")
    a = analyze(src.apk, data_bytes=src.data_bytes())
    a.extra["lang_packs"] = langpacks.find_tags(src.data_dir)
+    a.extra["asset_files"] = langpacks.find_content_files(src.data_dir)
    recipe = engine.suggest(a)
    return library.upsert_game(
        a.package, title=recipe.title or a.label, name=src.name, apk=str(src.apk),
@@ -373,6 +374,7 @@ def reanalyze(package: str, reporter: Reporter | None = None) -> dict:
        reporter.log(f"analyzing {src.apk.name}")
    a = analyze(src.apk, data_bytes=src.data_bytes())
    a.extra["lang_packs"] = langpacks.find_tags(src.data_dir)
+    a.extra["asset_files"] = langpacks.find_content_files(src.data_dir)
    suggested = engine.suggest(a)
    keep = library.recipe_from_dict(entry["recipe"]).source == "user"
    return library.upsert_game(package, analysis=a.to_dict(), suggested=library.recipe_to_dict(suggested),
@@ -403,6 +405,23 @@ def reset_recipe(package: str) -> Recipe:
    return recipe


+def apply_catalog_update(package: str) -> Recipe:
+    """Take the newer catalog recipe for a game whose recipe the user edited (the game page's "newer known-good
+    config" offer): derived again from the catalog, keeping the user's FrameBridge settings the catalog doesn't set."""
+    entry = library.game(package)
+    old = library.recipe_from_dict(entry["recipe"])
+    recipe = engine.suggest(library.analysis_from_dict(entry["analysis"]))
+    for pid, params in old.patches.items():
+        if pid.startswith("adapter.") and pid not in recipe.patches:
+            recipe.patches[pid] = params
+            if pid in old.reasons:
+                recipe.reasons[pid] = old.reasons[pid]
+    set_recipe(package, recipe)
+    with library.edit() as data:
+        data["games"].get(package, {}).pop("catalog_update", None)
+    return recipe
+
+
 def prepare_rift(package: str, reporter: Reporter) -> dict:
    """Rift games aren't rebuilt: check the folder still matches the analysis and make sure Revive is available."""
    from .build import sha256
@@ -520,6 +539,9 @@ def install_game(package: str, target: Target, reporter: Reporter, apk_only: boo
    test_build = apk is not None
    b = entry.get("build") or {}
    recipe = library.recipe_from_dict(entry["recipe"])
+    if not test_build and not b.get("apk"):  # never built yet (e.g. `frameport install` right after a scan)
+        build_game(package, reporter)
+        return install_game(package, target, reporter, apk_only, add_to_library)
    apk = Path(apk) if apk else Path(b["alt_apk"] if recipe.use_alt and b.get("alt_apk") else b["apk"])
    if not test_build and not apk.exists():  # the converted copy was removed after an earlier install: make it again
        build_game(package, reporter)
@@ -572,7 +594,33 @@ def local_game_files(package: str) -> list[Path]:
    def shared(p: Path) -> bool:  # the same path, a path inside it, or a folder around it belongs to another game
        rp = p.resolve()
        return any(u == rp or rp in u.parents or u in rp.parents for u in used)
-    return [p for p in dict.fromkeys(paths) if p.exists() and not shared(p)]
+    files = [p for p in dict.fromkeys(paths) if p.exists() and not shared(p)]
+    if g.get("kind") != "rift" and not is_linux(g):
+        files += [m for m in _download_manifests(files) if not shared(m)]
+    return files
+
+
+def _download_manifests(files: list[Path]) -> list[Path]:
+    """Download managers leave a manifest next to the game (e.g. "release.manifest": a "#filelist" section of
+    "f;./name;size" / "d;./name;0" lines). It goes with the game when it lists nothing but files that are deleted
+    anyway; otherwise the folder survives and the download manager still shows the game."""
+    gone = [p.resolve() for p in files]
+    found = []
+    for folder in dict.fromkeys(p.parent for p in files if p.is_file()):
+        for m in folder.glob("*.manifest"):
+            try:
+                lines = m.read_text(encoding="utf-8-sig", errors="replace").splitlines()
+            except OSError:
+                continue
+            start = next((i for i, line in enumerate(lines) if line.strip().lower() == "#filelist"), None)
+            if start is None:
+                continue
+            listed = [line.split(";")[1] for line in lines[start + 1:]
+                      if line.count(";") >= 2 and line.split(";")[0] in ("f", "d")]
+            targets = [(folder / name).resolve() for name in listed]
+            if targets and all(t in gone or any(d in t.parents for d in gone) for t in targets):
+                found.append(m)
+    return found


 def linux_local_files(g: dict) -> list[Path]:
@@ -42,6 +42,7 @@ class CatalogEntry:
    adapter: dict = field(default_factory=dict)
    device_files: dict = field(default_factory=dict)
    lepton_env: dict = field(default_factory=dict)
+    foveation: str = ""  # device.foveation: fixed / off (Valve's eye-tracked foveation layer)
    pcvr_alternative: str | None = None
    # Rift (PC VR) recipes: package is "rift.<slug>"; kind "rift"
    kind: str = "quest"
@@ -119,7 +120,8 @@ def remote_enabled() -> bool:
    if os.environ.get("FRAMEPORT_NO_CATALOG_UPDATE"):
        return False
    try:
-        return bool(library.setting("catalog.auto_update", True))
+        # never library.setting(): load() refreshes recipes from the catalog, which would load the catalog again
+        return bool(library.peek_setting("catalog.auto_update", True))
    except Exception:  # noqa: BLE001 - no library yet
        return True

@@ -347,7 +349,8 @@ def entry_from_library(g: dict, status: str | None = None, notes: str | None = N
        frame=[p for p in r.patches if (c := cat(p)) and c.category == "frame" and not c.default_on],
        device=[p for p in r.patches if p in TOGGLED_DEVICE],
        adapter={p.split(".", 1)[1]: v.get("value") for p, v in r.patches.items() if p.startswith("adapter.")},
-        device_files=r.params("device.files").get("files", {}))
+        device_files=r.params("device.files").get("files", {}),
+        foveation=r.params("device.foveation").get("mode") or "")


 def generic_source_hint(name: str) -> str:
@@ -63,6 +63,9 @@ def suggest(analysis: Analysis, use_catalog: bool = True) -> Recipe:
            recipe.reasons["device.files"] = why
        if entry.lepton_env:
            recipe.patches["device.lepton_env"] = {"env": dict(entry.lepton_env)}
+        if entry.foveation:
+            recipe.patches["device.foveation"] = {"mode": entry.foveation}
+            recipe.reasons["device.foveation"] = why
        recipe.alt_patches = list(entry.alt_overport)
        recipe.use_alt = entry.use_alt
    else:
@@ -592,14 +592,23 @@ class FramePortApp:
                        tr("Starts the game through Steam on this PC (SteamVR + Revive)")))
        return out

+    PLAY_COOLDOWN = 20  # s: a second Play while Steam/Lepton still start the game only gets Steam's AppError_16
+
    def play(self, pkg: str, to: str = "frame") -> None:
        title = self._title(pkg)
+        started = getattr(self, "_play_started", {})
+        self._play_started = started
+        if time.time() - started.get((pkg, to), 0) < self.PLAY_COOLDOWN:
+            self.toast(tr("{title} is already starting — put the headset on").format(title=title))
+            return
+        started[(pkg, to)] = time.time()

        def work():
            try:
                res = self._target_for(to).launch(pkg) or {}
-            except AgentFailed as exc:
-                if to != "frame" or NOT_IN_LIBRARY not in str(exc):
+            except Exception as exc:
+                started.pop((pkg, to), None)  # a failed start can be retried right away
+                if not isinstance(exc, AgentFailed) or to != "frame" or NOT_IN_LIBRARY not in str(exc):
                    raise
                self._add_then_play(pkg, title)  # e.g. the shortcut step failed during the install
                return
@@ -617,7 +626,11 @@ class FramePortApp:
                # Steam ignored FramePort's library entry: the game was added the way Valve's devkit tool does it
                self.toast(tr("The Frame's Steam didn't accept {title}'s library entry, so FramePort added it as "
                              "\"Devkit Game: …\" instead. Starting it now — put the headset on.").format(title=title))
+            elif to == "frame" and steam.get("result") == "error" and steam.get("code") == 16:
+                # AppError_16: "WaitingPrevProcess" - the game is still starting or running (GitHub #41)
+                self.toast(tr("{title} is already running on the Frame — put the headset on").format(title=title))
            elif to == "frame" and steam.get("result") == "error":  # 9 = "Game configuration unavailable"
+                started.pop((pkg, to), None)
                self.toast(tr("The Frame's Steam couldn't start {title} (Steam error {code}). Please send a problem "
                              "report so we can see why.").format(title=title, code=steam.get("code")), error=True,
                           action=tr("Report a problem"), on_action=lambda e: self.report_problem_dialog(pkg))
@@ -53,6 +53,7 @@ def save_to_recipe(package: str, values: dict) -> None:
    """Adapter patches = the settings that differ from their defaults (BASE_SETTINGS are written anyway)."""
    g = library.game(package)
    r = library.recipe_from_dict(g["recipe"])
+    before = {pid: dict(v or {}) for pid, v in r.patches.items() if pid.startswith("adapter.")}
    for key in SPECS:
        pid = f"adapter.{key}"
        v = _num(key, values.get(key, default(key)))
@@ -63,6 +64,9 @@ def save_to_recipe(package: str, values: dict) -> None:
            if (r.patches.get(pid) or {}).get("value") != v:
                r.reasons[pid] = tr("Set by you.")
            r.patches[pid] = {"value": v}
+    after = {pid: dict(v or {}) for pid, v in r.patches.items() if pid.startswith("adapter.")}
+    if after == before:  # saved without a change: the recipe keeps following FramePort's catalog (GitHub #10)
+        return
    r.source = "user"
    pipeline.set_recipe(package, r)

@@ -252,6 +252,18 @@ class GameView:
                    C.ghost(tr("Not now"), on_click=dismiss),
                ], spacing=T.S2, run_spacing=T.S2, wrap=True),
            ], spacing=T.S2), "info", ft.Icons.VOLUNTEER_ACTIVISM_OUTLINED))
+        if g.get("catalog_update") and recipe.source == "user":
+            def take_update(e):
+                from ... import pipeline
+
+                pipeline.apply_catalog_update(pkg)
+                self.app.toast(tr("New config applied: use Update on Frame to install it"))
+                self.app.render()
+            out.append(C.callout(ft.Row([
+                C.body(tr("A newer known-good config for this game is available (you changed this game's settings, "
+                          "so it wasn't applied by itself)."), T.TEXT, expand=True),
+                C.secondary(tr("Use the new config"), ft.Icons.AUTO_FIX_HIGH_OUTLINED, take_update)],
+                vertical_alignment=ft.CrossAxisAlignment.CENTER), "info", ft.Icons.NEW_RELEASES_OUTLINED))
        if g.get("steam_art_stale") and installed:
            out.append(C.callout(ft.Row([
                C.body(tr("The Frame's Steam library still shows the old artwork."), T.TEXT, expand=True),
@@ -61,6 +61,12 @@ def check_apk(apk: Path, package: str | None = None, expect_adapter: bool = True
            ("not in the APK or the system list: " + ", ".join(sorted(unresolved))) if unresolved else "")
        missing = missing_ovr_symbols({k: v for k, v in libs.items() if elf.is_elf(v)})
        add("Meta platform functions resolvable", not missing, ", ".join(sorted(missing)[:6]))
+        vrapi = libs.get("libvrapi.so")
+        if vrapi and elf.is_elf(vrapi):  # BlazeRush needed 4 the VrApi bridge lacked (GitHub #57): no start at all
+            have = elf.dyn_symbols(vrapi, True)
+            lacking = sorted({s for n, d in libs.items() if n != "libvrapi.so" and elf.is_elf(d)
+                              for s in elf.dyn_symbols(d, False) if s.startswith("vrapi_")} - have)
+            add("VrApi functions resolvable", not lacking, ", ".join(lacking[:6]))
        if expect_adapter:
            have = {"libopenxr_loader_generic.so", "libopenxr_loader_original.so", "libframe_settings.so"} <= set(libs)
            add("FrameBridge adapter", have, "" if have else "adapter/original loader/settings missing")
@@ -109,4 +109,36 @@ def triage(log: str, state: str = "UNKNOWN", package: str | None = None, crash:
    fps = re.findall(r"pacing: ([0-9.]+) fps", text)
    if fps:
        res.fps = float(fps[-1])
+    stopped = frames_stopped(lines)
+    if stopped and state == "RUNNING" and not any(f.severity == "fatal" for f in res.findings):
+        res.findings.append(Finding(
+            "frames-stopped", "fatal",
+            f"The game stopped sending frames {stopped:.0f} s before the test ended although its process kept "
+            "running (a crashed or stuck render thread: a frozen picture in the headset).", [],
+            "last FrameBridge pacing line"))
    return res
+
+
+LOGCAT_TIME = re.compile(r"^\d\d-\d\d (\d\d):(\d\d):(\d\d)\.(\d{3})")
+
+
+def frames_stopped(lines: list[str], gap: float = 20.0) -> float | None:
+    """Seconds between FrameBridge's last pacing line and the end of the log when that is over `gap` (the frame loop
+    died while the process lived on, e.g. The Room VR's render thread crash, PowerWash Simulator's rejected frames)."""
+    def secs(line):
+        m = LOGCAT_TIME.match(line)
+        return int(m[1]) * 3600 + int(m[2]) * 60 + int(m[3]) + int(m[4]) / 1000 if m else None
+    last_pacing = last = None
+    for ln in lines:  # logcat lines aren't strictly in time order: the latest time counts, not the last line
+        t = secs(ln)
+        if t is None:
+            continue
+        if last is not None and t < last - 43200:  # past midnight
+            t += 86400
+        last = t if last is None else max(last, t)
+        if "FrameBridge: pacing:" in ln:
+            last_pacing = t
+    if last_pacing is None or last is None:
+        return None
+    delta = last - last_pacing
+    return delta if delta > gap else None
@@ -0,0 +1,22 @@
+// Test fixture for patches/frame/ovr_microphone.py: OVRPort's unchecked ovr_Microphone_GetOutputBufferMaxSize
+// (same instructions as OVRPort 1.2.5's libovrplatformloader.so).
+// Build: aarch64-linux-android29-clang -shared -fPIC -nostdlib fakemicrophone.S -o ../libfakemicrophone_arm64.so
+    .text
+    .globl AAudioStream_getFramesPerBurst
+    .type AAudioStream_getFramesPerBurst, %function
+AAudioStream_getFramesPerBurst:
+    ldr w0, [x0]
+    ret
+    .size AAudioStream_getFramesPerBurst, .-AAudioStream_getFramesPerBurst
+
+    .globl ovr_Microphone_GetOutputBufferMaxSize
+    .type ovr_Microphone_GetOutputBufferMaxSize, %function
+ovr_Microphone_GetOutputBufferMaxSize:
+    stp x29, x30, [sp, #-16]!
+    mov x29, sp
+    ldr x0, [x0, #0x18]
+    bl AAudioStream_getFramesPerBurst
+    sxtw x0, w0
+    ldp x29, x30, [sp], #16
+    ret
+    .size ovr_Microphone_GetOutputBufferMaxSize, .-ovr_Microphone_GetOutputBufferMaxSize
@@ -911,6 +911,43 @@ def test_reinstall_with_unchanged_shortcut_does_not_restart_steam(monkeypatch, t
    assert (cfg / "grid").is_dir() and any(p.name.endswith("p.jpg") for p in (cfg / "grid").iterdir())


+
+def test_devkit_games_get_art_without_a_steam_restart(monkeypatch, tmp_path):
+    # GitHub #41: on Frames whose Steam drops FramePort's shortcuts.vdf entries, every install/art update restarted
+    # Steam, which also dropped the live devkit entry: the next Play then restarted Steam once more
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "Applications/quest-frame/com.x.y"
+    (anchor / "artwork").mkdir(parents=True)
+    (anchor / "artwork/portrait.jpg").write_bytes(b"art")
+    (anchor / "deployment.json").write_text(json.dumps({"package": "com.x.y", "appid": 1, "title": "X", "base": "b"}))
+    (tmp_path / ".local/share/Steam/userdata/42/config").mkdir(parents=True)
+    monkeypatch.setattr(a, "devkit_gameid", lambda pkg: "X")
+    monkeypatch.setattr(a, "devkit_appid", lambda gid: 777)
+    art = []
+    monkeypatch.setattr(a, "copy_grid_art", lambda pkg, appid, users=None: art.append((pkg, appid)))
+    stops = []
+    monkeypatch.setattr(a, "stop_steam", lambda: stops.append(1) or True)
+    monkeypatch.setattr(a, "start_steam", lambda s: stops.append(2))
+    a.shortcuts_worker(json.dumps({"packages": ["com.x.y"], "remove": []}))
+    status = json.load(open(a.STATUS_FILE))
+    assert not stops and art == [("com.x.y", 777)] and status["devkit"] == ["com.x.y"] and status["state"] == "done"
+
+
+def test_launch_re_adds_a_forgotten_devkit_entry_live(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "Applications/quest-frame/com.x.y"
+    anchor.mkdir(parents=True)
+    (anchor / "deployment.json").write_text(json.dumps({"package": "com.x.y", "appid": 111, "title": "X",
+                                                        "base": str(anchor)}))
+    monkeypatch.setattr(a, "run", lambda cmd, **k: SimpleNamespace(returncode=0, stdout=""))
+    monkeypatch.setattr(a, "shortcut_appid_for", lambda exe: None)  # Steam has no shortcut either
+    monkeypatch.setattr(a, "devkit_gameid", lambda pkg: "X")
+    monkeypatch.setattr(a, "devkit_appid", lambda gid: None)  # Steam restarted and forgot the devkit entry
+    monkeypatch.setattr(a, "devkit_register", lambda pkg: 333)
+    monkeypatch.setattr(a, "steam_launch", lambda appid, wait=10: {"result": "started", "appid": appid})
+    got = a.cmd_launch({"package": "com.x.y"})  # no NOT_IN_LIBRARY (whose repair restarts Steam)
+    assert got["via"] == "devkit" and got["steam"]["appid"] == 333
+
 def test_shortcuts_lost_after_steam_restart(monkeypatch, tmp_path):
    a = load_agent(monkeypatch, tmp_path)
    anchor = tmp_path / "Applications/quest-frame/com.x.y"
@@ -1149,8 +1186,8 @@ def test_dashboard_worker_hides_dashboard_after_first_frames(monkeypatch, tmp_pa
    clock = iter(range(0, 10000))
    monkeypatch.setattr(a.time, "time", lambda: next(clock))
    log.write_text("Lepton starting\nI FrameBridge: pacing: 72.0 fps\n")
-    a.dashboard_worker(str(log), os.getpid(), wait_start=10, window=8)
-    assert calls.count("SteamClient.OpenVR.VROverlay.HideDashboard()") == 3  # at most three times
+    a.dashboard_worker(str(log), os.getpid(), wait_start=10, window=8, max_hides=3)
+    assert calls.count("SteamClient.OpenVR.VROverlay.HideDashboard()") == 3  # at most max_hides times


 def test_dashboard_worker_starts_at_the_first_submitted_frame(monkeypatch, tmp_path):
@@ -1323,10 +1360,11 @@ def test_devkit_appid_from_steams_console_log(monkeypatch, tmp_path):
    logs = Path(a.STEAM) / "logs"
    logs.mkdir(parents=True, exist_ok=True)
    exe = f"{a.DEVKIT_GAMES}/I_Am_Cat/launch.sh"
+    why = "reason: k_unAppIdInvalid"
    (logs / "console_log.txt").write_text(
-        f'[2026-10-05 14:45:37] sanitize shortcut app id "{exe}": replacing 0 with 3849978641, reason: k_unAppIdInvalid\n'
+        f'[2026-10-05 14:45:37] sanitize shortcut app id "{exe}": replacing 0 with 3849978641, {why}\n'
        f'[2026-10-05 14:45:38] sanitize shortcut app id "{a.DEVKIT_GAMES}/Other/launch.sh": replacing 0 with 5\n'
-        f'[2026-10-05 15:29:14] sanitize shortcut app id "{exe}": replacing 0 with 3849978642, reason: k_unAppIdInvalid\n')
+        f'[2026-10-05 15:29:14] sanitize shortcut app id "{exe}": replacing 0 with 3849978642, {why}\n')
    assert a.devkit_appid("I_Am_Cat") == 3849978642  # nothing in shortcuts.vdf: the newest log line
    assert a.devkit_appid("Missing") is None

@@ -1343,7 +1381,8 @@ def test_devkit_appid_ignores_the_previous_steam_session(monkeypatch, tmp_path):


 def test_launch_registers_a_lost_devkit_entry_again(monkeypatch, tmp_path):
-    """After a Steam restart Steam forgot the (never saved) devkit entry: Play gets AppError_9 and registers it again."""
+    """After a Steam restart Steam forgot the (never saved) devkit entry: Play gets AppError_9 and registers it
+    again."""
    a = load_agent(monkeypatch, tmp_path)
    monkeypatch.setattr(a, "check_pkg", lambda p: p)
    monkeypatch.setattr(a, "deployment", lambda p: {"appid": 111, "title": "Batman"})
@@ -1361,3 +1400,62 @@ def test_launch_registers_a_lost_devkit_entry_again(monkeypatch, tmp_path):
    out = a.cmd_launch({"package": "com.camouflaj.manta"})
    assert registered == ["com.camouflaj.manta"] and launches == [222, 333]
    assert out["via"] == "devkit" and out["steam"]["result"] == "started"
+
+
+@pytest.mark.skipif(sys.platform == "win32" or not __import__("shutil").which("flock"), reason="bash + flock")
+def test_second_launch_while_starting_is_ignored(monkeypatch, tmp_path):
+    """Play pressed again while Lepton still boots made the second Lepton stop the first one's container (both died:
+    Vader Immortal, BattleSisters). The launcher holds a lock for the game's lifetime; a second launch leaves it."""
+    import time
+
+    a = load_agent(monkeypatch, tmp_path)
+    base = tmp_path / "game"
+    (base / "lepton-app").mkdir(parents=True)
+    lepton = tmp_path / "lepton"
+    lepton.write_text(f"#!/bin/bash\necho started >>{tmp_path}/starts\nsleep ${{FAKE_RUN:-30}}\n")
+    lepton.chmod(0o755)
+    text = a.LAUNCH_SH.format(title="T", pkg="com.x.y", base_q=str(base), appid=1, lepton_q=str(lepton), extra_env="",
+                              watchdog=a.WATCHDOG, dashboard="true", single=a.SINGLE_LINE, plays_start="true",
+                              plays_end="true")
+    launcher = tmp_path / "launch.sh"
+    launcher.write_text(text)
+    launcher.chmod(0o755)
+    first = subprocess.Popen([str(launcher)], start_new_session=True)
+    try:
+        for _ in range(100):
+            if (tmp_path / "starts").exists():
+                break
+            time.sleep(0.05)
+        second = subprocess.run([str(launcher)], timeout=10)
+        assert second.returncode == 0 and first.poll() is None  # ignored, the first keeps running
+        assert (tmp_path / "starts").read_text().count("started") == 1
+        assert "second launch ignored" in (base / "launch-dup.log").read_text()
+    finally:
+        os.killpg(first.pid, 15)
+        first.wait(timeout=10)
+    third = subprocess.run([str(launcher)], timeout=20, env={**os.environ, "FAKE_RUN": "0"})
+    assert third.returncode == 0 and (tmp_path / "starts").read_text().count("started") == 2  # free again
+
+
+def test_upgrade_launchers_adds_the_single_launch_lock(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "Applications/quest-frame/com.x.y"
+    anchor.mkdir(parents=True)
+    old = ('#!/bin/bash\napp_dir=/x\n[[ -d "$app_dir/lepton-app" ]] || { exit 1; }\nfix_perms\nparent=$PPID\n'
+           '( while sleep 2; do fix_perms; if true; then kill -TERM $$; fi; done ) & permfix=$!\nexport SteamAppId=1\n')
+    (anchor / "launch.sh").write_text(old)
+    a.upgrade_launchers()
+    text = (anchor / "launch.sh").read_text()
+    assert text.index(".launch.lock") < text.index("fix_perms") and "done ) 9>&- & permfix=$!" in text
+    assert text.count(".launch.lock") == 1
+    a.upgrade_launchers()
+    assert (anchor / "launch.sh").read_text().count(".launch.lock") == 1
+
+
+def test_dashboard_worker_keeps_watching_for_two_minutes(monkeypatch, tmp_path):
+    """Agent 59: Steam's menu came back after the first 30 s in headset sessions (The Boys, BONELAB)."""
+    a = load_agent(monkeypatch, tmp_path)
+    import inspect
+
+    sig = inspect.signature(a.dashboard_worker)
+    assert sig.parameters["window"].default == 120 and sig.parameters["max_hides"].default == 10
@@ -71,3 +71,26 @@ def test_turned_off(github, monkeypatch):
    assert catalog.refresh_remote(force=True) == 0
    assert "com.x.good" not in catalog.load(refresh=True)
    assert json.dumps(catalog.remote_status())  # still reports (never checked)
+
+
+def test_library_load_with_a_cold_catalog_does_not_recurse(monkeypatch):
+    """GitHub #58: library.load() refreshes recipes from the catalog; the catalog's first load read a setting through
+    library.load(), which refreshed recipes again before the catalog was cached (~140 nested loads, blank window or a
+    crash at start-up)."""
+    from frameport.core import library
+
+    monkeypatch.delenv("FRAMEPORT_NO_CATALOG_UPDATE", raising=False)  # remote_enabled() must read the setting
+    monkeypatch.setattr(library, "REFRESH_ON_UPDATE", True)
+    library.save({"games": {"com.x.mine": {"recipe": {"source": "user", "patches": {}}, "analysis": {"package": "x"}}},
+                  "settings": {"catalog.auto_update": False}})
+    catalog._cache = None
+    loads = []
+    real = library.load
+
+    def counting():
+        loads.append(1)
+        assert len(loads) < 10, "library.load() recursed"
+        return real()
+    monkeypatch.setattr(library, "load", counting)
+    library.load()
+    assert catalog.remote_enabled() is False and len(loads) <= 2
@@ -414,3 +414,73 @@ def test_games_already_in_the_library_get_their_language_packs_after_an_app_upda
    assert library._refresh_data_fields(g, g["analysis"])
    assert g["analysis"]["extra"]["lang_packs"] == ["de"]
    assert not library._refresh_data_fields(g, g["analysis"])  # once
+
+
+DOWNLOADBYID, DOWNLOADUPDATE = 0x2D008992, 0x2FDD0CCD
+
+
+def _list(api):
+    api.f("ovr_AssetFile_GetList", C.c_uint64)()
+    m = api.pop()
+    arr = api.f("ovr_Message_GetAssetDetailsArray", VOIDP, VOIDP)(m)
+    get = api.f("ovr_AssetDetailsArray_GetElement", VOIDP, VOIDP, C.c_size_t)
+    items = []
+    for i in range(api.f("ovr_AssetDetailsArray_GetSize", C.c_size_t, VOIDP)(arr)):
+        d = get(arr, i)
+        items.append({**api.details(d), "iap": api.f("ovr_AssetDetails_GetIapStatus", C.c_char_p, VOIDP)(d)})
+    api.free(m)
+    return items
+
+
+def test_content_files_are_listed_only_when_switched_on(api, packs, monkeypatch):
+    (packs / "Season1Taco-Android_ASTC.pak").write_bytes(b"x" * 10)
+    monkeypatch.delenv("FRAMEPORT_ASSET_FILES", raising=False)
+    assert not [i for i in _list(api) if i["type"] == b"default"]  # language-pack builds don't change
+    monkeypatch.setenv("FRAMEPORT_ASSET_FILES", "1")
+    content = [i for i in _list(api) if i["type"] == b"default"]
+    assert content == [{"id": content[0]["id"], "type": b"default", "status": b"installed", "iap": b"free",
+                        "path": str(packs / "Season1Taco-Android_ASTC.pak").encode()}]
+    assert content[0]["id"] >> 48 == 0x4650 and "tag" not in content[0]
+    m = api.ask("ovr_LanguagePack_GetCurrent")  # content files are never a language pack
+    assert api.is_error(m)
+    api.free(m)
+
+
+def test_download_of_a_content_file_completes_at_once(api, packs, monkeypatch):
+    (packs / "WwiseBanksCoreTaco-Android_ASTC.pak").write_bytes(b"y" * 12)
+    monkeypatch.setenv("FRAMEPORT_ASSET_FILES", "1")
+    asset = next(i["id"] for i in _list(api) if i["type"] == b"default")
+    req = api.f("ovr_AssetFile_DownloadById", C.c_uint64, C.c_uint64)(asset)
+    update = api.pop()  # Star Wars Tales waits for the update's "completed", then for the result
+    assert api.msg_type(update) == DOWNLOADUPDATE and api.req_id(update) == 0
+    u = api.f("ovr_Message_GetAssetFileDownloadUpdate", VOIDP, VOIDP)(update)
+    assert api.f("ovr_AssetFileDownloadUpdate_GetAssetFileId", C.c_uint64, VOIDP)(u) == asset
+    assert api.f("ovr_AssetFileDownloadUpdate_GetBytesTotal", C.c_uint64, VOIDP)(u) == 12
+    assert api.f("ovr_AssetFileDownloadUpdate_GetBytesTransferred", C.c_longlong, VOIDP)(u) == 12
+    assert api.f("ovr_AssetFileDownloadUpdate_GetCompleted", C.c_bool, VOIDP)(u)
+    api.free(update)
+    m = api.pop()
+    assert api.msg_type(m) == DOWNLOADBYID and api.req_id(m) == req and not api.is_error(m)
+    res = api.f("ovr_Message_GetAssetFileDownloadResult", VOIDP, VOIDP)(m)
+    assert api.f("ovr_AssetFileDownloadResult_GetFilepath", C.c_char_p, VOIDP)(res) == \
+        str(packs / "WwiseBanksCoreTaco-Android_ASTC.pak").encode()
+    api.free(m)
+    m = api.ask("ovr_AssetFile_DownloadById", asset + 1)  # ours by prefix, but unknown
+    assert api.is_error(m)
+    api.free(m)
+
+
+def test_asset_files_patch_switches_the_library_on(built, tmp_path):
+    lib = built["lib"].read_bytes()
+    on = patch_mod.with_assets(lib)
+    assert len(on) == len(lib) and patch_mod.ASSETS_MARK + b"1" in on and patch_mod.with_assets(on) == on
+    data = tmp_path / "obb"
+    data.mkdir()
+    (data / "main.1.com.x.obb").write_bytes(b"o")
+    (data / "Season1Taco-Android_ASTC.pak").write_bytes(b"p")
+    assert langpacks.find_content_files(data) == ["Season1Taco-Android_ASTC.pak"]
+    p = base.get("frame.asset_files")
+    a = _analysis(libs=["libovrplatformloader.so", "libUE4.so"],
+                  extra={"size": 1, "asset_files": ["Season1Taco-Android_ASTC.pak"], "asset_file_api": True})
+    assert p.applies(a) and p.detect(a)
+    assert not p.detect(_analysis(libs=["libovrplatformloader.so"], extra={"size": 1, "asset_files": ["a.pak"]}))
@@ -0,0 +1,42 @@
+"""Meta Platform SDK tracer (native/ovrtrace + patch frame.ovr_trace)."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from frameport.analysis import elf
+from frameport.core.models import Analysis
+from frameport.patches import base
+from frameport.patches.frame import ovr_trace
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _names():
+    return re.findall(r"^N\((ovr_\w+)\)$", (ROOT / "native/ovrtrace/names.inc").read_text(), re.M)
+
+
+def test_artifact_exports_every_traced_name():
+    names = _names()
+    assert len(names) == len(set(names)) > 1000
+    lib = (ROOT / "artifacts/arm64-v8a" / ovr_trace.LIB).read_bytes()
+    exported = elf.dyn_symbols(lib, True)
+    assert set(names) <= exported
+    assert "ovr_PopMessage" in names and "ovr_Message_GetRequestID" in names
+
+
+def _a(abis, libs):
+    return Analysis(package="x", version="1.0", label="X", abis=abis, engine="Unreal", xr="VrApi", graphics="GLES",
+                    direct_vrapi=False, libs=libs, launcher_activity=None, has_info_category=True, meta_permissions=[],
+                    uses_glad_gl=False, unity_msaa_levels=0, oculus_os_classes=False, is_overport_output=False,
+                    debuggable=False, extra={})
+
+
+def test_applies_only_to_arm64_games_with_the_platform_loader():
+    base.load_all()
+    p = base.REGISTRY["frame.ovr_trace"]
+    assert p.applies(_a(["arm64-v8a"], ["libUE4.so", "libovrplatformloader.so"]))
+    assert not p.applies(_a(["arm64-v8a"], ["libUE4.so"]))
+    assert not p.applies(_a(["armeabi-v7a"], ["libovrplatformloader.so"]))
+    assert p.detect(_a(["arm64-v8a"], ["libovrplatformloader.so"])) is None
+    assert p.experimental and not p.default_on
@@ -156,6 +156,16 @@ def test_per_game_session_settings_are_off_unless_selected():
        assert patch.detect(_analysis()) is None


+
+def test_vk_hide_fdm_is_a_per_game_unreal_setting():
+    """Metro Awakening: Unreal's Vulkan isn't always detected, so it's offered for every Unreal game; off by default."""
+    from frameport.patches.settings import UI
+
+    patch = base.get("adapter.vk_hide_fdm")
+    assert patch.applies(_analysis(engine="Unreal", graphics="GLES or unknown (no Vulkan declaration)"))
+    assert not patch.applies(_analysis(engine="Unity"))
+    assert "vk_hide_fdm" not in adapter_settings({}) and UI["vk_hide_fdm"]["group"] == "troubleshooting"
+
 def test_detect_direct_vrapi_suggests_bridge_and_shim():
    a = _analysis(xr="VrApi", direct_vrapi=True, uses_glad_gl=True, graphics="GLES or unknown", package="x.y.unknown")
    from frameport.recommend import engine
@@ -216,6 +226,29 @@ def test_swapchain_limit_raises_overport_guard():
    assert raise_swapchain_limit(_fixture("libfakeengine_arm64.so")) == (None, 0)  # no xrCreateSwapchain


+def test_ovr_microphone_guards_unopened_stream():
+    from frameport.analysis import elf
+    from frameport.patches.frame.ovr_microphone import guard_microphone
+
+    lib = _fixture("libfakemicrophone_arm64.so")
+    out = guard_microphone(lib)
+    assert out is not None and len(out) == len(lib)
+    ins = [(m, o) for a, m, o in elf.text_instructions(out)]
+    start = ins.index(("ldr", "x0, [x0, #0x18]"))
+    assert [m for m, _ in ins[start:start + 7]] == ["ldr", "cbz", "stp", "bl", "ldp", "sxtw", "ret"]
+    calls = lambda data: [o for _, m, o in elf.text_instructions(data) if m == "bl"]  # noqa: E731
+    assert calls(out) == calls(lib)  # still calls AAudioStream_getFramesPerBurst
+    assert guard_microphone(out) is None  # idempotent
+    assert guard_microphone(_fixture("libfakeoverport_arm64.so")) is None  # no such function
+
+
+def test_ovr_microphone_suggested_only_for_microphone_games():
+    p = base.get("frame.ovr_microphone")
+    assert p.detect(_analysis(engine="Unreal", libs=["libUE4.so"], extra={"ovr_microphone": True})).recommended
+    assert p.detect(_analysis(engine="Unreal", libs=["libUE4.so"])) is None
+    assert not p.default_on
+
+
 def test_swapchain_limit_suggested_for_video_players():
    p = base.get("frame.swapchain_limit")
    assert p.detect(_analysis(engine="Other", libs=["libavcodec4x.so", "libvr4p-oculus.so"])).recommended
@@ -510,3 +543,222 @@ def test_start_activity_after_overport_conversion(tmp_path):
        ctx = base.ApkContext(ws, a, {}, Reporter(), {"frame.start_activity": {}})
        assert patch.apply(ctx)
        assert patch.validate(ctx) == [("Only the VR activity is a launcher", True, "org.x.game.QuestActivity")]
+
+
+def test_haptic_fix_suggested_for_ovrplugin_games():
+    base.load_all()
+    p = base.REGISTRY["adapter.haptic_fix"]
+    s = p.detect(_analysis(libs=["libunity.so", "libOVRPlugin.so"]))
+    assert s and s.recommended and s.params == {"value": 1}
+    assert p.detect(_analysis(libs=["libunity.so"])) is None
+
+
+def test_foveation_choice_sets_the_launcher_env_and_wins_over_lepton_env():
+    from frameport.install.installer import install_context
+
+    assert base.get("device.foveation").CHOICES[0][0] == ""  # Valve's default needs no patch
+    r = Recipe("com.x.game", patches={"device.foveation": {"mode": "off"},
+                                      "device.lepton_env": {"env": {"VK_INSTANCE_LAYERS": "VK_LAYER_x"}}})
+    assert install_context(r).env["VK_INSTANCE_LAYERS"] == ""  # applied last, whatever the recipe's order
+    r = Recipe("com.x.game", patches={"device.foveation": {"mode": "fixed"}})
+    assert install_context(r).env == {"FDM_DEBUG": "disable_offsets"}
+
+
+def test_catalog_foveation_reaches_the_recipe(monkeypatch):
+    from frameport.recommend import catalog, engine
+
+    entry = catalog.CatalogEntry(package="com.drbeef.rtcwquest", title="RTCWQuest", status="works", foveation="off")
+    assert catalog.CatalogEntry.from_dict(yaml_load(catalog.to_yaml(entry)), "bundled").foveation == "off"
+    monkeypatch.setattr(catalog, "lookup", lambda package: entry)
+    r = engine.suggest(_analysis(package="com.drbeef.rtcwquest", engine="Other", libs=["libopenxr_loader.so"],
+                                 extra={"size": 1}))
+    assert r.params("device.foveation") == {"mode": "off"}
+
+
+def yaml_load(text):
+    import yaml
+
+    return yaml.safe_load(text)
+
+
+def test_vrapi_stub_keeps_every_function_of_metas_loader(tmp_path, quest_manifest):
+    from frameport.analysis import elf
+
+    apk = _apk(tmp_path, quest_manifest)
+    metas = build_stub_library(["vrapi_Initialize", "vrapi_SetPropertyInt", "vrapi_GetHmdInfo"], soname="libvrapi.so")
+    metas = metas.replace(b"\x00\x00\x80\xd2", b"\x20\x00\x80\xd2")  # different code, same exports (mov x0, #1)
+    with ApkWorkspace(apk) as ws:
+        ws.put(ws.lib("libvrapi.so"), metas)
+        ws.put(ws.lib("libOVRPlugin.so"), build_stub_library(["ovrp_GetVersion"], soname="libOVRPlugin.so"))
+        patch = base.get("frame.vrapi_stub")
+        a = _analysis(libs=["libvrapi.so", "libOVRPlugin.so"], direct_vrapi=False)
+        assert patch.applies(a) and patch.detect(a) is None  # suggested by triage only
+        assert not patch.applies(_analysis(libs=["libvrapi.so"], direct_vrapi=True))  # that's the bridge's case
+        ctx = base.ApkContext(ws, a, {}, Reporter(), {"frame.vrapi_stub": {}})
+        assert patch.apply(ctx)
+        stub = ws.read_lib("libvrapi.so")
+        assert elf.dyn_symbols(stub, True) == {"vrapi_Initialize", "vrapi_SetPropertyInt", "vrapi_GetHmdInfo"}
+        assert elf.soname(stub) == "libvrapi.so" and not patch.apply(ctx)  # applying twice changes nothing
+    assert "frame.vrapi_bridge" in base.get("frame.vrapi_stub").conflicts
+
+
+def test_vrapi_stub_covers_jurassic_world_aftermath():
+    """With the real APK's libraries (FRAMEPORT_GAMES): every vrapi_* OVRPlugin imports is in the stub."""
+    import os
+    from pathlib import Path
+
+    from frameport.analysis import elf
+
+    root = os.environ.get("FRAMEPORT_GAMES")
+    if not root:
+        import pytest
+        pytest.skip("FRAMEPORT_GAMES not set")
+    apks = list(Path(root).glob("Jurassic World Aftermath*/com.coatsink.alone.apk"))
+    if not apks:
+        import pytest
+        pytest.skip("Jurassic World Aftermath not in FRAMEPORT_GAMES")
+    with zipfile.ZipFile(apks[0]) as z:
+        vrapi, plugin = (z.read(f"lib/arm64-v8a/{n}") for n in ("libvrapi.so", "libOVRPlugin.so"))
+    exports = sorted(s for s in elf.dyn_symbols(vrapi, True) if s.startswith(("vrapi_", "ovr")))
+    need = {s for s in elf.dyn_symbols(plugin, False) if s.startswith("vrapi_")}
+    assert need and need <= elf.dyn_symbols(build_stub_library(exports, soname="libvrapi.so"), True)
+
+
+def test_static_check_finds_vrapi_functions_the_bridge_lacks(tmp_path, monkeypatch, quest_manifest):
+    from frameport.apk import sign
+    from frameport.validate import static
+
+    monkeypatch.setattr(sign, "verify", lambda apk: (True, ""))
+    monkeypatch.setattr(sign, "alignment_problems", lambda apk: [])
+    apk = tmp_path / "game.apk"
+    game = build_stub_library(["game_main"], soname="libtargemapp.so")
+    with zipfile.ZipFile(apk, "w") as z:
+        z.writestr("AndroidManifest.xml", quest_manifest)
+        z.writestr("lib/arm64-v8a/libvrapi.so", build_stub_library(["vrapi_Initialize"], soname="libvrapi.so"))
+        z.writestr("lib/arm64-v8a/libtargemapp.so", game)
+    monkeypatch.setattr(static.elf, "dyn_symbols", lambda data, defined: (
+        {"vrapi_Initialize"} if defined else {"vrapi_Initialize", "vrapi_PollEvent"}) if data == game or defined
+        else set())
+    check = next(c for c in static.check_apk(apk, expect_adapter=False) if c["name"] == "VrApi functions resolvable")
+    assert check["ok"] is False and check["detail"] == "vrapi_PollEvent"  # BlazeRush (GitHub #57)
+
+
+def test_bridge_exports_what_blazerush_imports():
+    from frameport.analysis import elf
+    from frameport.patches.frame import artifact
+
+    have = elf.dyn_symbols(artifact("arm64-v8a", "libvrapi.so"), True)
+    assert {"vrapi_PollEvent", "vrapi_GetSystemPropertyFloatArray", "vrapi_RecenterPose",
+            "vrapi_SetDisplayRefreshRate"} <= have
+
+
+def test_tbxr_vendor_adds_the_valve_loader(tmp_path, quest_manifest):
+    from frameport.analysis import elf
+
+    apk = _apk(tmp_path, quest_manifest)
+    patch = base.get("frame.tbxr_vendor")
+    a = _analysis(libs=["libxash.so", "libopenxr_loader_meta.so"], extra={"size": 1, "tbxr_libs": ["libxash.so"]})
+    assert patch.applies(a) and patch.detect(a) and not patch.applies(_analysis())
+    with ApkWorkspace(apk) as ws:
+        assert patch.apply(base.ApkContext(ws, a, {}, Reporter(), {patch.id: {}}))  # (libxash.so absent here)
+        loader = ws.read_lib("libopenxr_loader_valve.so")
+        assert elf.soname(loader) == "libopenxr_loader_valve.so"  # loadLibrary("openxr_loader_valve") finds it
+        assert not patch.apply(base.ApkContext(ws, a, {}, Reporter(), {patch.id: {}}))
+
+
+def test_tbxr_vendor_on_lambda1vr():
+    """With the real APK (FRAMEPORT_GAMES): the six "meta" checks of libxash.so now match "valve"."""
+    import os
+    from pathlib import Path
+
+    import pytest
+
+    from frameport.analysis import elf
+
+    root = os.environ.get("FRAMEPORT_GAMES")
+    apks = list(Path(root).glob("Half Life 1 VR*/com.drbeef.lambda1vr.apk")) if root else []
+    if not apks:
+        pytest.skip("Lambda1VR not in FRAMEPORT_GAMES")
+    with zipfile.ZipFile(apks[0]) as z:
+        xash = z.read("lib/arm64-v8a/libxash.so")
+    assert b"\0OPENXR_HMD\0" in xash and b"\0meta\0" in xash
+    fixed, count = elf.replace_rodata_string(xash, "meta", "alve")
+    assert count == 1 and b"\0alve\0" in fixed and len(fixed) == len(xash)
+
+
+def test_unity_user_presence_points_the_xr_plugin_at_the_shim(tmp_path, quest_manifest):
+    """BONELAB: OVRPlugin reported the worn headset as not worn and the Marrow rig froze (no tracking, no controls)."""
+    from frameport.analysis import elf
+    from frameport.patches.frame import unity_user_presence as P
+
+    fake = _fixture("libfakeovrplugin_arm64.so")
+    xr_plugin, n = elf.replace_rodata_string(fake, "xrGetInstanceProcAddr", P.CALL)  # a stand-in with the lookup name
+    assert n == 1
+    apk = _apk(tmp_path, quest_manifest)
+    with zipfile.ZipFile(apk, "a") as z:
+        z.writestr("lib/arm64-v8a/libOculusXRPlugin.so", xr_plugin)
+        z.writestr("lib/arm64-v8a/libOVRPlugin.so", fake)
+    p = base.get("frame.unity_user_presence")
+    a = _analysis(engine="Unity", libs=["libunity.so", "libOVRPlugin.so", "libOculusXRPlugin.so"])
+    assert p.applies(a) and p.detect(a) is None  # per game, from the catalog
+    assert not p.applies(_analysis(engine="Unity", libs=["libunity.so", "libOVRPlugin.so"]))
+    with ApkWorkspace(apk) as ws:
+        ctx = base.ApkContext(ws, a, {}, Reporter(), {})
+        assert p.apply(ctx)
+        assert p.validate(ctx) == [("User presence shim loaded", True, P.SHIM)]
+        out = ws.write(tmp_path / "out.apk")
+    with zipfile.ZipFile(out) as z:
+        patched = z.read("lib/arm64-v8a/libOculusXRPlugin.so")
+        assert len(patched) == len(xr_plugin) and P.SHIM_CALL.encode() + b"\0" in patched
+        assert P.SHIM in elf.needed(z.read("lib/arm64-v8a/libOVRPlugin.so"))
+        shim = z.read(f"lib/arm64-v8a/{P.SHIM}")
+    assert P.SHIM_CALL in elf.dyn_symbols(shim, True)  # the rebuilt artifact exports the wrapper
+
+
+def test_microphone_fix_is_not_suggested_for_unitys_platform_wrapper(quest_manifest, tmp_path):
+    """Unity's C# platform wrapper (libil2cpp.so) names every Meta function, used or not: no reason to patch."""
+    from frameport.analysis.detect import analyze
+
+    def apk(lib):
+        p = tmp_path / f"{lib}.apk"
+        with zipfile.ZipFile(p, "w") as z:
+            z.writestr("AndroidManifest.xml", quest_manifest)
+            z.writestr(f"lib/arm64-v8a/{lib}", b"\x7fELF\0ovr_Microphone_GetOutputBufferMaxSize\0")
+        return p
+    assert not analyze(apk("libil2cpp.so")).extra["ovr_microphone"]
+    assert analyze(apk("libUE4.so")).extra["ovr_microphone"]  # Unreal's voice code calls it (TWD Ch. 2)
+
+
+def test_to_string_stubs_return_an_empty_string():
+    """ovrPeerConnectionState_ToString & co. (BlazeRush): OVRPort's loader lacks them; NULL could crash the caller."""
+    import struct
+
+    from frameport.analysis import detect, elf
+
+    lib = build_stub_library(["ovr_Foo", "ovrPeerConnectionState_ToString"], soname="libovrstubs.so")
+    syms = elf._elf(lib).get_section_by_name(".dynsym")
+    at = syms.get_symbol_by_name("ovrPeerConnectionState_ToString")[0]["st_value"]
+    word = struct.unpack_from("<I", lib, at)[0]
+    imm = ((word >> 29) & 3) | ((word >> 5) & 0x7FFFF) << 2
+    imm -= (1 << 21) if imm & (1 << 20) else 0
+    assert word & 0x9F00001F == 0x10000000 and lib[at + imm] == 0  # adr x0, <a zero byte>
+    foo = syms.get_symbol_by_name("ovr_Foo")[0]["st_value"]
+    assert struct.unpack_from("<I", lib, foo)[0] == 0xD2800000  # everything else still returns 0
+    assert detect.OVR_TO_STRING.match("ovrVoipMuteState_ToString")
+    assert not detect.OVR_TO_STRING.match("ovrAvatar_Create")
+
+
+def test_avatar_stub_keeps_the_loaders_functions(tmp_path, quest_manifest):
+    from frameport.analysis import elf
+
+    apk = _apk(tmp_path, quest_manifest)
+    with ApkWorkspace(apk) as ws:
+        real = build_stub_library(["ovrAvatar_InitializeAndroid", "ovrAvatarMessage_Pop"],
+                                  soname="libovravatarloader.so")
+        ws.put(ws.lib("libovravatarloader.so"), real.replace(b"\x00\x00\x80\xd2", b"\x20\x00\x80\xd2"))
+        p = base.get("frame.avatar_stub")
+        a = _analysis(libs=["libovravatarloader.so"])
+        assert p.applies(a) and p.detect(a) is None
+        assert p.apply(base.ApkContext(ws, a, {}, Reporter(), {p.id: {}}))
+        stub = ws.read_lib("libovravatarloader.so")
+        assert elf.dyn_symbols(stub, True) == {"ovrAvatar_InitializeAndroid", "ovrAvatarMessage_Pop"}
@@ -83,3 +83,64 @@ def test_swapchain_rect_invalid_is_recognised():

    log = "10-05 08:13:02.100  1149  1312 I FrameBridge: xrEndFrame failed -25\n"
    assert "swapchain-rect-invalid" in [f.id for f in triage.triage(log).findings]
+
+
+def test_frames_stopped_and_unity_render_crash():
+    """The Room VR passed its launch test although Unity's render thread had crashed in libgallium (GitHub #38)."""
+    from frameport.validate import triage
+
+    log = ("10-05 23:16:30.000  1  2 I FrameBridge: pacing: 59.0 fps\n"
+           "10-05 23:16:33.137  1  3 E CRASH   : \t#01  pc 0000000000c3fe18  /vendor/lib64/libgallium_dri.so ()\n"
+           "10-05 23:16:59.000  1  4 I OvrAudio: ovrAudio_Enable\n")
+    r = triage.triage(log, "RUNNING")
+    assert [f.id for f in r.findings] == ["unity-render-crash"] and r.verdict == "fail"
+    alone = triage.triage(log.replace("libgallium_dri", "libother"), "RUNNING")
+    assert "frames-stopped" in [f.id for f in alone.findings]
+    assert triage.frames_stopped(["10-05 23:16:30.000 x FrameBridge: pacing: 72 fps", "10-05 23:16:40.000 y"]) is None
+
+
+def test_vrapi_called_before_init_suggests_the_stub_not_the_bridge():
+    log = ("10-06 02:04:56.040  1154  1180 I OVRPlugin: OVRPlugin 1.89.1 initialized\n"
+           "10-06 02:04:56.324  1154  1180 F VrApiLoader: vrapi_SetPropertyInt was called before vrapi_Initialize()!\n")
+    r = triage(log, "EXITED", "com.coatsink.alone")
+    ids = {f.id for f in r.findings}
+    assert "vrapi-before-init" in ids and "direct-vrapi" not in ids  # Jurassic World Aftermath (GitHub #62)
+    assert r.suggestions() == ["frame.vrapi_stub"]
+
+
+def test_missing_vrapi_function():
+    log = ('10-06 00:53:00.662  1124  1124 E AndroidRuntime: java.lang.UnsatisfiedLinkError: Unable to load native '
+           'library "/data/app/x/lib/arm64-v8a/libtargemapp.so": dlopen failed: cannot locate symbol '
+           '"vrapi_PollEvent" referenced by "libtargemapp.so"\n')
+    ids = {f.id for f in triage(log, "EXITED", "ru.targem.blazerush").findings}
+    assert "vrapi-symbol-missing" in ids and "java-crash" not in ids
+
+
+def test_unreal_vulkan_driver_crash_and_missing_fdm():
+    """Metro Awakening (Unreal 5.2): Turnip crashed on Unreal's render passes, null-image barriers and FDM views."""
+    tomb = ("10-06 08:04:22.702  1236  1236 F DEBUG   :       #00 pc 0000000000ad74d0  "
+            "/vendor/lib64/hw/vulkan.freedreno.so (BuildId: 052b)\n"
+            "10-06 08:04:22.703  1236  1236 F DEBUG   :       #03 pc 0000000004822ab4  "
+            "/data/app/x/lib/arm64/libUnreal.so (BuildId: 7a70)\n")
+    r = triage(LOG_OK, "EXITED", "com.example.game", crash=tomb)
+    f = next(f for f in r.findings if f.id == "unreal-vulkan-driver-crash")
+    assert "adapter.vk_hide_fdm" in f.suggest and not any(f.id == "native-crash" for f in r.findings)
+    fdm = ("10-06 08:10:51.264  1147  1241 I FrameBridge: vk shim: left out 1 image barrier(s) without an image "
+           "(first: layout 0 -> 1000218000, aspect 0x1, layers 4294967295)\n")
+    assert "unreal-fdm-missing" in [f.id for f in triage(LOG_OK + fdm, "RUNNING", "com.example.game").findings]
+    hidden = ("10-06 08:10:47.924  1147  1165 I FrameBridge: vk shim: fragment density map extensions hidden from "
+              "the game\n")
+    found = triage(LOG_OK + hidden + fdm, "RUNNING", "com.example.game").findings
+    assert "unreal-fdm-missing" not in [f.id for f in found]
+
+
+def test_session_without_graphics_requirements():
+    log = "10-06 18:13:02.714  1115  1157 E TBXR    : Failed to create XR session: -50.\n"
+    assert "graphics-requirements-missing" in {f.id for f in triage(log, "EXITED", "com.drbeef.lambda1vr").findings}
+
+
+def test_avatar_driver_missing():
+    log = ("10-06 18:42:51.349  1130  1158 I OVRAvatar-Loader: ovrAvatar_Initialize: Failed to load AvatarSDK "
+           "driver (-1)!\n10-06 18:42:51.351  1130  1158 F OVRAvatar-Loader: DisplayErrorAndExit: Failed to launch "
+           "SystemActivities\n")
+    assert triage(log, "EXITED", "ru.targem.blazerush").suggestions() == ["frame.avatar_stub"]
@@ -143,7 +143,7 @@ def test_packaged_app_shows_artwork_by_file_path(tmp_path, monkeypatch):
        thumbs.use_file_paths(False)


-def test_unity_oculus_check_only_for_old_unity_with_the_check():
+def test_unity_oculus_check_for_unity_with_the_check():
    base.load_all()
    p = base.get("frame.unity_oculus_check")
    old = _analysis(libs=["libunity.so", "libOVRPlugin.so"],
@@ -151,7 +151,15 @@ def test_unity_oculus_check_only_for_old_unity_with_the_check():
    assert p.applies(old) and p.detect(old).recommended
    new = _analysis(libs=["libunity.so", "libOVRPlugin.so"],
                    extra={"unity_version": "2019.4.35f1", "unity_oculus_check": True})
-    assert not p.applies(new) and p.detect(new) is None  # 2019+ runs without it: builds stay byte-identical
+    # 2019 too (BattleSisters, Unity 2019.4, stayed a 2D app without it)
+    assert p.applies(new) and p.detect(new).recommended
+    # the frame-wait shim: Unity's built-in VR loop (2017-2018, 2019 without the Oculus XR Plugin), not XR Plugin games
+    assert p.legacy_loop(old) and p.legacy_loop(new)
+    assert not p.legacy_loop(_analysis(libs=["libunity.so", "libOVRPlugin.so", "libOculusXRPlugin.so"],
+                                       extra={"unity_version": "2019.4.35f1"}))
+    assert not p.legacy_loop(_analysis(libs=["libunity.so"], extra={"unity_version": "2022.3.19f1"}))
+    none = _analysis(libs=["libunity.so", "libOVRPlugin.so"], extra={"unity_version": "2019.4.35f1"})
+    assert not p.applies(none) and p.detect(none) is None  # no check in libunity.so: nothing to change
    log = "10-04 15:08:01.000  1213  1235 I Unity   : [NewtonVR] Critical Error: Oculus / SteamVR not setup properly"
    assert "frame.unity_oculus_check" in {s for f in triage(log, "RUNNING", None).findings for s in f.suggest}

@@ -219,6 +227,32 @@ def test_uninstall_can_delete_the_games_files_on_this_pc(tmp_path):
    assert key.exists() and shared.exists()  # signing keys and other games' files stay


+def test_deleting_a_games_files_takes_its_download_manifest(tmp_path):
+    from frameport import pipeline
+    from frameport.core import library
+
+    def release(name, extra=""):
+        d = tmp_path / name
+        (d / "com.x.game").mkdir(parents=True)
+        (d / "com.x.game.apk").write_bytes(b"PK")
+        (d / "com.x.game/main.1.com.x.game.obb").write_bytes(b"o")
+        (d / "release.manifest").write_text(
+            "#VRPRELEASEMANIFEST 1.0\nGame Name;Release Name\nGame;Game v1\n\n#filelist\ntype;name;size\n"
+            "f;./com.x.game.apk;2\nd;./com.x.game;0\nf;./com.x.game/main.1.com.x.game.obb;1\n" + extra,
+            encoding="utf-8")
+        return d
+
+    game = release("Game v1")
+    library.upsert_game("com.x.game", apk=str(game / "com.x.game.apk"), data_dir=str(game / "com.x.game"))
+    assert game / "release.manifest" in pipeline.local_game_files("com.x.game")
+    pipeline.delete_local_files("com.x.game")
+    assert not game.exists()  # the folder went too: a download manager no longer lists the game
+
+    other = release("Game v2", extra="f;./notes.txt;5\n")  # lists a file that isn't the game's: stays
+    library.upsert_game("com.x.game", apk=str(other / "com.x.game.apk"), data_dir=str(other / "com.x.game"))
+    assert other / "release.manifest" not in pipeline.local_game_files("com.x.game")
+
+
 def test_scan_finds_games_in_download_manager_layouts(tmp_path, monkeypatch):
    import zipfile

@@ -242,3 +276,67 @@ def test_scan_finds_games_in_download_manager_layouts(tmp_path, monkeypatch):
    found = {g.apk.name: g for g in quest_dump.scan(root)}
    assert set(found) == {"stray.app.apk", "com.a.game.apk", "com.b.game.apk"}
    assert found["com.a.game.apk"].data_dir == root / "Manager/Game A v1/com.a.game"
+
+
+def test_user_recipes_get_a_catalog_update_offer(tmp_path, monkeypatch):
+    """GitHub #10: a recipe whose Game settings were saved once ("user") never followed a catalog fix again; now
+    the game is flagged, and taking the offer re-derives it keeping the user's own FrameBridge settings."""
+    from frameport import pipeline
+    from frameport.core import library
+    from frameport.recommend import catalog
+
+    monkeypatch.setattr(library, "_path", lambda: tmp_path / "library.json")
+    entry = catalog.CatalogEntry(package="com.x.vr4", title="VR4", adapter={"vk_shader_fix": "1:2:3:4"})
+    monkeypatch.setattr(catalog, "lookup", lambda pkg: entry if pkg == "com.x.vr4" else None)
+    an = {"package": "com.x.vr4", "engine": "Unreal", "libs": ["libUE4.so"], "abis": ["arm64-v8a"]}
+    recipe = {"package": "com.x.vr4", "patches": {"adapter.scale": {"value": 0.9}}, "source": "user",
+              "catalog_rev": "old"}
+    (tmp_path / "library.json").write_text(__import__("json").dumps(
+        {"games": {"com.x.vr4": {"package": "com.x.vr4", "analysis": an, "recipe": recipe}}, "settings": {}}))
+    assert library.game("com.x.vr4")["catalog_update"] == entry.rev()
+    pipeline.apply_catalog_update("com.x.vr4")
+    g = library.game("com.x.vr4")
+    assert "catalog_update" not in g and g["recipe"]["patches"]["adapter.scale"] == {"value": 0.9}
+    assert g["recipe"].get("source") != "user" and "adapter.vk_shader_fix" in g["recipe"]["patches"]
+
+
+
+def test_oculus_model_checks_accept_any_device_but_the_go():
+    import struct
+
+    from frameport.patches.frame import unity_oculus_check as C
+
+    # .text: adrp x1, page(0x1000); add x1, x1, #0x10; orr w2, wzr, #6; bl ...  -> strncmp(model, "Oculus", 6)
+    code = struct.pack("<4I", 0xB0000001, 0x91004021, C.ORR_W2_6, 0x94000000)
+    other = struct.pack("<4I", 0xB0000001, 0x91008021, C.ORR_W2_6, 0x94000000)  # a different string: untouched
+    data = bytearray(0x2000)
+    data[0:16], data[16:32] = code, other
+    data[0x100F:0x1017] = b"\0Oculus\0"  # the literal at 0x1010
+    data[0x1020:0x1028] = b"OculusX\0"
+    out, n = C.oculus_model_checks(bytes(data))
+    assert n == 1
+    assert struct.unpack_from("<I", out, 8)[0] == C.MOV_W2_0 and struct.unpack_from("<I", out, 24)[0] == C.ORR_W2_6
+    assert out[0x1010:0x1016] == b"Oculus"  # the string itself stays (Unity's VR device name)
+
+
+def test_install_builds_a_game_that_was_never_built(tmp_path, monkeypatch):
+    from types import SimpleNamespace
+
+    from frameport import pipeline
+    from frameport.core import library
+    from frameport.core.models import Recipe
+
+    library.upsert_game("com.x.fresh", apk=str(tmp_path / "in.apk"),
+                        recipe=library.recipe_to_dict(Recipe("com.x.fresh")))
+    out = tmp_path / "built.apk"
+    out.write_bytes(b"PK")
+
+    def build(package, reporter):
+        library.upsert_game(package, build={"apk": str(out)})
+    monkeypatch.setattr(pipeline, "build_game", build)
+    monkeypatch.setattr(pipeline, "remove_converted_copies", lambda package: 0)
+    installed = []
+    target = SimpleNamespace(label="frame", install=lambda *a: installed.append(a[2]) or {"ok": True},
+                             add_to_library=lambda pkgs, rep: None)
+    pipeline.install_game("com.x.fresh", target, None)  # used to fail with KeyError 'apk'
+    assert installed == [out]
Author	SHA1	Message	Date
spoopyghosty0	474be9d34b	FramePort 0.12.0	2026-10-06 18:21:32 -04:00
spoopyghosty0	7b4dff7d84	Notes: 2026-10-06 issue triage round (headset results, what was ruled out)	2026-10-06 18:19:12 -04:00
spoopyghosty0	885070a00c	Catalog: Metro Awakening plays with space warp off and without Valve's VALVE_rpo layer (random jumping polygons otherwise; owner's headset test)	2026-10-06 17:22:56 -04:00
spoopyghosty0	67b58238a0	Catalog: Pinball FX VR with space warp off (stutters gone after loading in the owner's headset test)	2026-10-06 17:08:10 -04:00
spoopyghosty0	a1c87618f6	VrApi bridge: upstream-patches/input.cpp.patch (FramePort's input diagnostics)	2026-10-06 17:07:40 -04:00
spoopyghosty0	b4cec19283	VrApi bridge: input diagnostics also log the controller types asked for (and refused), button bits seen and thumbstick deflection (BlazeRush: no thumbstick, no hands)	2026-10-06 17:07:30 -04:00
spoopyghosty0	109c7e449c	FrameBridge: a vibration with amplitude 0 becomes xrStopHapticFeedback (OVRPlugin stops vibrations that way; the last buzz otherwise ran its full 2 s in Jurassic World, The Boys VR, Creed)	2026-10-06 16:28:45 -04:00
spoopyghosty0	05ad7e4d25	GL shim: with GL_EXT_multisampled_render_to_texture hidden, its two functions become single-sampled stand-ins (TBXR calls them regardless: GL_FRAMEBUFFER_INCOMPLETE_MULTISAMPLE, black eyes in Lambda1VR); frame.tbxr_vendor links the shim into TBXR's library	2026-10-06 15:37:08 -04:00
spoopyghosty0	1e96abebbb	Agent v59: close Steam's 'Resume game' menu for 120 s after the first VR frame, up to 10 times (it came back after the first 30 s); still stops once the player opens the dashboard	2026-10-06 15:24:16 -04:00
spoopyghosty0	69da709ea2	Vibration: haptic_fix converts envelopes with their RMS instead of their peak (vibrations felt far stronger than on a Quest); new per-game setting haptic_scale ('Vibration strength') scales every vibration in FrameBridge and logs the first requests. VrApi bridge: input/vibration diagnostics every 5 s (BlazeRush controllers)	2026-10-06 15:22:57 -04:00
spoopyghosty0	d5f9c248e0	frame.avatar_stub: replace Meta's avatar loader with a do-nothing library when it can't find its driver and aborts the game (BlazeRush: OVRAvatar-Loader DisplayErrorAndExit); suggested by triage avatar-driver-missing	2026-10-06 14:53:53 -04:00
spoopyghosty0	cc39547e33	FrameBridge: add XR_KHR_opengl_es_enable when an app enables no graphics API extension (Lambda1VR's TBXR creates a GLES session without it; Meta's runtime tolerates that); log the final instance extension list once per launch. Lambda1VR now runs headless at 72 fps	2026-10-06 14:50:34 -04:00
spoopyghosty0	096d24e42b	FrameBridge: when xrCreateSession fails with XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING, ask for the graphics requirements on the app's behalf and retry once (Lambda1VR: Failed to create XR session: -50); triage graphics-requirements-missing	2026-10-06 14:33:02 -04:00
spoopyghosty0	2995413434	VrApi bridge: vrapi_PollEvent returns ovrSuccess_EventUnavailable (1002), vrapi_SetTrackingSpace returns an ovrResult, vrapi_CreateTextureSwapChain/2 take VrApi's 32-bit format enum (found while preparing the upstream PRs)	2026-10-06 14:31:40 -04:00
spoopyghosty0	4b34dbd218	Platform stubs: also stub ovr<Enum>_ToString helpers OVRPort's loader lacks (BlazeRush: ovrPeerConnectionState_ToString); ToString stubs return an empty string, not NULL; triage missing-ovr-symbol matches them	2026-10-06 14:08:20 -04:00
spoopyghosty0	a775e63e6d	Install: build a game that was never built instead of failing with KeyError 'apk' (frameport install right after a scan)	2026-10-06 14:01:08 -04:00
spoopyghosty0	3cd4affcf6	frame.ovr_microphone: don't suggest it from libil2cpp.so (Unity's C# platform wrapper names every Meta function, so every Unity game with the Platform SDK matched); triage ovr-microphone-crash still finds a Unity game that crashes there	2026-10-06 13:58:56 -04:00
spoopyghosty0	51e553039a	Catalog: Beat Saber (com.beatgames.beatsaber.lj369vr) (works) Closes #68	2026-10-06 13:53:36 -04:00
spoopyghosty0	27ff49a137	Catalog: Creed (works) Closes #60	2026-10-06 13:53:33 -04:00
spoopyghosty0	e70acf9269	Catalog: BodyCombat (works) Closes #56	2026-10-06 13:53:29 -04:00
spoopyghosty0	1f6fce0fcc	Catalog: Pinball FX VR (works with issues, MR not yet) Closes #50	2026-10-06 13:53:25 -04:00
spoopyghosty0	188cb8fe68	Metro Awakening: libfp_vk.so rebuilt with the shim's new fixes; catalog entry with the contributor's recipe (use_alt, vk_spec_fixes, vk_hide_fdm); docs/GAMES.md regenerated; lint	2026-10-06 13:46:53 -04:00
UnicronNL	0744a126cb	Vulkan shim: drop depth resolves of subpasses without depth, leave out null-image barriers and refuse null-image views (vk_spec_fixes), vk_hide_fdm hides fragment density maps (Metro Awakening crashed in the Frame's Vulkan driver, GitHub #65 )	2026-10-06 13:46:52 -04:00
spoopyghosty0	1c8a0d63e7	BONELAB: libfp_ovrp.so rebuilt with the user-presence wrapper; catalog status 'issues' (1.2068 plays, the newer 1.2974 still crashes at start); docs/GAMES.md regenerated	2026-10-06 13:46:51 -04:00
UnicronNL	124ec594a6	frame.unity_user_presence: report the headset as worn to Unity's Oculus XR Plugin (BONELAB 1.2068's rig froze: OVRPlugin's ovrp_GetUserPresent2 turns 0 while worn, GitHub #66 )	2026-10-06 13:46:31 -04:00
spoopyghosty0	90b528f9f2	Lint: wrap a long comment	2026-10-06 13:46:30 -04:00
UnicronNL	2da6082166	frame.ovr_microphone: guard OVRPort's ovr_Microphone_GetOutputBufferMaxSize against a not-yet-opened stream (The Walking Dead: Saints & Sinners Ch. 2 crashed after the logo, GitHub #67 )	2026-10-06 13:46:30 -04:00
spoopyghosty0	3e61b07254	frame.asset_files: list the game data's *.pak content files as installed default asset files and answer DownloadById at once with the path (Star Wars: Tales from the Galaxy's Edge went black after loading, GitHub #61 ); shares the language-pack library	2026-10-06 13:46:08 -04:00
spoopyghosty0	48c3716ef5	frame.tbxr_vendor: Team Beef ports load openxr_loader_<maker> and pick Meta's path only for "meta": add an empty libopenxr_loader_valve.so and let "valve" match those checks (Lambda1VR stopped at start, GitHub #59 )	2026-10-06 13:28:10 -04:00
spoopyghosty0	dca2d8b762	VrApi bridge: vrapi_PollEvent, RecenterPose, SetDisplayRefreshRate, GetSystemPropertyFloatArray (BlazeRush couldn't load: cannot locate symbol vrapi_PollEvent, GitHub #57 ); static check 'VrApi functions resolvable', triage vrapi-symbol-missing; upstream-patches regenerated (graphics.cpp.patch was stale: the Vulkan format twin was missing from it)	2026-10-06 13:23:52 -04:00
spoopyghosty0	2c4bbdbfec	frame.vrapi_stub: replace Meta's leftover VrApi loader with a same-exports library that answers 0 (OVRPlugin on OpenXR called vrapi_SetPropertyInt before init and the loader aborted, GitHub #62 ); triage vrapi-before-init, direct-vrapi no longer matches it	2026-10-06 13:12:59 -04:00
spoopyghosty0	8a08733be8	Agent v58: Play re-adds a devkit entry Steam forgot (no NOT_IN_LIBRARY, no Steam restart); installs and art updates of devkit games only copy art; the app treats Steam's AppError_16 as already starting and ignores repeated Play clicks for 20 s (GitHub #41/#42)	2026-10-06 13:09:39 -04:00
spoopyghosty0	d7193bea19	device.foveation: per-game choice for Valve's eye-tracked foveation layer (default / fixed = FDM_DEBUG=disable_offsets / off = VK_INSTANCE_LAYERS=""), catalog field foveation (GitHub #69 )	2026-10-06 13:06:36 -04:00
spoopyghosty0	c3522a05bb	macOS: keep the entitlements when ad-hoc signing (re-signing stripped them; Scan a folder failed with ENTITLEMENT_NOT_FOUND, GitHub #63 )	2026-10-06 13:06:35 -04:00
spoopyghosty0	8a9a428f1e	Delete files on this PC: also remove the download manifest next to the game when it lists only the game's files (the folder stayed, so the download manager still listed the game)	2026-10-06 13:06:34 -04:00
spoopyghosty0	919d059add	Notes: the jni build override and re-tagging a failed release build	2026-10-06 12:14:37 -04:00
spoopyghosty0	674c26f2d9	Build: override jni to 1.1.0 instead (jni_flutter 1.0.4 also generates bindings that require jni ^1.1.0; Flet's template pins 1.0.0)	2026-10-06 12:04:20 -04:00
spoopyghosty0	a6daa5cccb	Build: pin jni_flutter 1.0.4 (1.0.4+1, published today, requires jni ^1.1.0 but Flet pins jni 1.0.0; all flet build bundles failed)	2026-10-06 11:54:47 -04:00
spoopyghosty0	6f89123017	FramePort 0.11.1	2026-10-06 11:44:01 -04:00
spoopyghosty0	518c94d79f	Vader Immortal: Episode I catalog entry (works with issues, GitHub #49 ): plays the intro, then stays on its loading card; plain recipe without diagnostics	2026-10-06 11:42:04 -04:00
spoopyghosty0	edf9f494e8	Agent v57: one launcher per game (flock on <base>/.launch.lock). Play pressed again while Lepton still booted made the second Lepton stop the first container and both died (Vader Immortal, BattleSisters); a second launch now exits and leaves the first running. upgrade_launchers adds it to existing launchers; verified on the device	2026-10-06 11:25:56 -04:00
spoopyghosty0	0db053c31f	FrameBridge snapshot=N: every N seconds the left-eye image a GLES game submits is saved as fb_snap_0-7.ppm in its files folder (headless launches have a black headset view). Vader Immortal: the intro plays, then its loading card never advances	2026-10-06 09:26:38 -04:00
spoopyghosty0	7439f082db	BattleSisters works (owner-verified 2026-10-06: buttons via the Oculus device-model fix; its first controller vibration ran OVRPort's haptic-envelope bug into an 11 GB OOM kill). haptic_fix is now suggested for every game that ships Meta's OVRPlugin; existing FramePort recipes pick it up after the next update	2026-10-06 09:01:40 -04:00
spoopyghosty0	f12f4aec4c	FrameBridge layer_debug: count xrAcquire/Wait/ReleaseSwapchainImage per 5 s (Vader Immortal's per-frame leak in SteamVR's runtime; hooked only with layer_debug, after the other wait/release hooks)	2026-10-06 01:23:58 -04:00
spoopyghosty0	8d95592f53	Unity 2019 built-in Oculus input on Lepton (BattleSisters, GitHub #48 ): libunity only reports controllers when the device model starts with "Oculus"; Lepton's Android is "Valve Lepton", so Unity polled only Go-style controllers and the game's buttons never arrived. unity_oculus_check revision 4 gives those strncmp calls length 0 (in place); on the device libunity now polls the Touch controllers	2026-10-06 01:19:47 -04:00
spoopyghosty0	44d23f778d	FrameBridge diagnostics from Vader Immortal (GitHub #49 ): layer_debug logs xrDestroySwapchain and per-5 s xrBeginFrame/xrEndFrame counts; strip_color_bias (drop XR_KHR_composition_layer_color_scale_bias, 2 = the layer's whole extension chain) and frame_balance (end an open frame before the next begin), both opt-in. Vader leaks ~430 GPU mappings a second inside SteamVR's runtime (GPU timing command buffers per frame); none of these stop it	2026-10-06 01:07:11 -04:00
spoopyghosty0	7a40e47e67	FramePort 0.11.0	2026-10-06 00:21:37 -04:00
spoopyghosty0	9401b7fc87	Accounting+ works (owner-verified 2026-10-06: the motion warning continues with the click emulation); catalog entry needs FramePort 0.10.1	2026-10-06 00:18:20 -04:00
spoopyghosty0	e510ea88f0	ovrpshim: log ovrp_GetNodePresent for Unity's built-in XR input and report a hand node present while its Touch controller is connected (BattleSisters: Unity's XR controller devices, which its buttons are read from, never appeared)	2026-10-06 00:17:25 -04:00
spoopyghosty0	4c2b6c9dee	Start-up recursion (GitHub #58 ): library.load() refreshes recipes from the catalog, and the catalog's first load read its auto-update setting through library.load(), which refreshed recipes again before the catalog was cached (~140 nested loads: a long blank window, or a crash in the Windows bundle). The setting is read as stored (library.peek_setting) and the catalog step can't re-enter itself	2026-10-06 00:17:14 -04:00
spoopyghosty0	cb689c576a	ovrpshim: Touch trigger or A/B/X/Y presses count as Unity mouse clicks (GetMouseButtonDown icall replaced): Accounting+'s motion warning waits for a click Lepton never delivers; input probe logs trigger/grip values	2026-10-06 00:06:18 -04:00
spoopyghosty0	bd2e1a8410	unity_oculus_check revision 3: Unity's built-in Oculus input creates Touch controllers only on device model 'Oculus Quest'; Lepton's Android is 'Valve Lepton', so the compared string is repointed in place (BattleSisters: hands tracked, buttons dead although OVRPlugin reported every press)	2026-10-05 23:39:53 -04:00
spoopyghosty0	608fac9d68	unity_oculus_check: the input probe can be switched on for a diagnostic build (FRAMEPORT_INPUT_PROBE=1)	2026-10-05 23:18:14 -04:00
spoopyghosty0	919c0e291e	focus_hold on by default with 5 s (the Frame's wear sensor flickers "HMD off" for 0.5-2 s while worn and Quest games pause each time; Lucky's Tale); Unity 2019 games on the built-in VR loop (no Oculus XR Plugin) get the ovrpshim frame wait (BattleSisters flooded 'outside of frame bounds' and hung the GPU); frame.ovr_trace: opt-in Meta Platform SDK request tracer (native/ovrtrace) for games stuck waiting (Vader Immortal, GitHub #49 ); catalog: I Am Cat pose_consistency, Lucky's Tale haptic_fix, The Room VR (all owner-verified)	2026-10-05 22:02:06 -04:00
spoopyghosty0	23f4192cfd	Game page offers a newer catalog config for recipes the user edited (GitHub #10 : a saved Game settings dialog stopped catalog fixes; saving without a change no longer marks the recipe as the user's); launch tests fail when frames stop while the process lives on (frames-stopped) and on Unity render-thread crashes in the GL driver (unity-render-crash)	2026-10-05 21:03:02 -04:00
spoopyghosty0	3391a981b8	Unity fixes from the 2026-10-05 headset round: unity_runtime_msaa_off also no-ops QualitySettings.set_antiAliasing; frame.unity_no_overlay_copy (The Room VR: OVROverlay's fade copy crashed Zink; works now); unity_oculus_check also for Unity 2019 without the frame-wait shim (BattleSisters starts VR; then a GPU lockup); frame.unity_gl_shim + gl_hide_msrtt (GL shim reads every settings source); xrshim converts haptic amplitude envelopes before OVRPort's dispatcher (haptic_fix; GitHub #9 , found by Klownicle); FrameBridge pose_consistency (GitHub #8 , proposed by Klownicle)	2026-10-05 20:55:36 -04:00