Docs: update screenshots and videos

32-bit Gear VR / Oculus Go / early Quest games through the a32 bridge (frame.a32_bridge, experimental, on by default for 32-bit-only games).

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -38,6 +38,6 @@ body:
     id: logs
     attributes:
       label: Diagnostics
-      description: Drag the FramePort-diag-*.zip here (max 25 MB)
+      description: "Drag the FramePort-diag-*.zip here (max 25 MB). If the box won't take it, submit the report and attach the zip in a comment."
     validations:
       required: true

.gitignore

@@ -9,7 +9,7 @@ parity-report.md
 *.keystore
 *.apk
 .pytest_cache/
-native/.cache/
+native/.cache
 native/**/build/
 # per-machine Claude Code settings (contain home paths)
 .claude/settings.local.json
@@ -30,3 +30,8 @@ site/src/assets/media/
 site/media-hq/
 site/public/s
 site/public/setup.sh
+
+# Impeccable design-tool files (kept local, not in the repo)
+/PRODUCT.md
+/DESIGN.md
+/.impeccable/

CLAUDE.md

@@ -69,6 +69,10 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
     Live Frame data comes from one app-owned `app.monitor_hub` (`frame/monitor_hub.py`): subscribers name modules +
     interval, the hub runs one agent `_monitor` stream (union of modules, fastest interval; per-module collection
     needs agent v73), reconnects after a lost stream and stops it when nobody subscribes; `_poll` retries an "error".
+    Games in a sample (agent v81): FramePort's own (launch.sh / container / Proton folder), any other game Steam's
+    reaper runs (`steam:<appid>`, title from the appmanifest, e.g. Job Simulator from Steam's store; not SteamVR, not
+    devkit entries; End game = Steam's Exit game), overlay apps flagged `overlay` and listed last; newest first. The
+    UI takes `frame/monitor.main_game(sample)` (never an overlay app alone). The agent's own workers never count.
     Subscribers: "monitor" (the Monitor tab, everything, only while shown) and "card" = the sidebar's live Frame card
     (`ui/frame_card.py` helpers: battery ring, "now playing" row with fps + 2-min sparkline → click opens Monitor;
     games + battery every 5 s, paused while a job's stage is "Upload…", only while connected and setting
@@ -308,6 +312,66 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
 - `native/` — sources of the prebuilt binaries in `artifacts/` (adapter, VrApi bridge patches, GL shim, stubs).
   `native/build.py` rebuilds them with NDK r27c (downloaded on demand into `native/.cache`, git-ignored; uses
   `-ffile-prefix-map` so no local paths get embedded; zip symlinks are restored as copies). Users never need the NDK.
+  `native/a32translator/` (not an artifact, not shipped) = `a32run`, an AArch32 → AArch64 user-mode translator
+  (interpreter + JIT, ARM/Thumb-2/VFP/NEON) for running 32-bit ARM Linux programs on the Frame; its README has the
+  design, the qemu-arm differential fuzzer and program tests. `native/a32translator/bridge/` = the in-APK Android
+  bridge (32-bit JNI/NativeActivity libraries in a 64-bit app: stub + liba32bridge.so + guest runtime liba32rt.so;
+  harness with a fake JVM; test APK org.frameport.a32test passes in Lepton; GLES/EGL, OpenSL ES via AAudio, VrApi 1.x
+  -> the 64-bit VrApi bridge, controller input as Gear VR touchpad/back events; `bridge/convert.py` converts an APK).
+  First game: AFFECTED The Manor (Gear VR, Unity 5.6 + Mono) runs in the headset with picture and sound
+  (2026-10-10); Spunky Dungeon (Unity 2019.2, OVRPlugin 1.46 on VrApi 1.31, Platform SDK) plays at 72 fps.
+  In FramePort: patch `frame.a32_bridge` (`patches/frame/a32_bridge.py`: `convert()` is shared with the dev script
+  `bridge/convert.py`; artifacts `liba32bridge.so`/`liba32rt.so`/`liba32stub.so` from `native/build.py --only a32`)
+  is suggested for every 32-bit-only APK; the recipe then has `overport: False` (OVRPort is 64-bit only; the patch
+  ships OVRPort's loader chain + its 32-bit platform dispatcher itself, `overport.ensure_runtime_lib`), only
+  frame.a32_bridge/adapter/launcher of the frame patches, and `device.text_input_window` for Unity (`engine.a32_recipe`,
+  also run by `pipeline.set_recipe` + builds, so a bridge turned on by hand drops OVRPort & the 64-bit fixes; which
+  patches work there = `base.works_on_a32` (`Patch.a32`; overport/frame off unless `a32 = True`, adapter settings in
+  `settings.XRSHIM_SETTINGS` off); `build.check_a32` refuses anything else, `engine.warnings(recipe, analysis)` says
+  so; a catalog entry for a 32-bit game that neither names nor removes the bridge predates it: bridge kept, status
+  unknown; parity gives bridge builds without a bridge known-good "new build (no baseline)"; library migration
+  `a32_bridge_on` turned the bridge on once in every 32-bit recipe, user ones too, unless the catalog's frame_remove
+  names it).
+  Analysis `extra.headset` (ANALYSIS_VERSION 15): gearvr / go / quest → "Gear VR" / "Oculus Go" platform + Steam tag.
+  Catalog: `headset:` field; com.fallen.affected, net.mobilemischief.spunkydungeon, com.ccpgames.gunjack (works, 2026-10-12). Learned: Unity 2019 contexts
+  have no EGLConfig (EGL_KHR_no_config_context: the VrApi bridge takes the window's or an RGBA8 ES3 config); Unity's
+  floor origin = vrapi_SetTrackingSpace(1) (the VrApi bridge now honours LOCAL_FLOOR/STAGE); mapped GL buffers are
+  per buffer object (a per-target guest copy leaked ~10 MB/s and garbled vertices); the guest runtime's own scudo
+  names its maps `[anon:scudo:*]` below 4 GiB (watch them for guest leaks). The Go controller = the right Frame
+  controller (stick = touchpad touch, sideways > 0.6 or press = click). Gunjack (CCP, UE 4.10 NativeActivity, Gear VR,
+  2026-10-10): needed the native_app_glue imports (ALooper/AInputQueue/AConfiguration/AAsset*, imports.txt), an arm64
+  libvrapi.so for Java's System.loadLibrary("vrapi") and MOUNTED under OVP_HEADLESS_TEST; it then loads its map and
+  quit on purpose: AndroidMain compares AndroidThunkCpp_GetSignature() with an obfuscated copy. **Works since
+  2026-10-11 (owner-verified in the headset):** GameActivity.AndroidThunkJava_GetSignature() = Base64.DEFAULT(SHA-1(
+  signing certificate DER)) (jadx); `a32_bridge.original_signature` computes it from the original APK's
+  META-INF/*.RSA|DSA|EC, `convert()` stores it as `assets/fp_a32_signature.txt` for libUE4.so games, the bridge loads
+  it at activity creation (native_activity.c) and jni.c answers Call*Method on the method ID of
+  `AndroidThunkJava_GetSignature()Ljava/lang/String;` with it. After loading, Unreal leaves VR mode and enters it again on
+  the same GL context; a second OpenXR session there aborted in vrclient (CSharedSemaphoreLinux::WaitFromGPU from the GL
+  binding's PreBeginFrame, also with OVP_HEADLESS_TEST) → the VrApi bridge keeps a running GLES session across
+  LeaveVrMode and reuses it for an EnterVrMode with the same context (upstream-patches/runtime.cpp.patch).
+  Debugging aids added: A32_BREAK=<guest addr>[,..] (stack of the first hits; guest libs load at fixed addresses, e.g.
+  libUE4 0xf25d5000), A32_STRACE in bridge mode = path/exit calls to logcat, activity lifecycle + LeaveVrMode caller
+  logs. Lepton's logcat mirror often dies for these games: read `podman exec <container> logcat` instead. Gunjack input
+  (2026-10-11): it imports no vrapi input functions and reads the Gear VR touchpad/back as AInputEvents from its
+  AInputQueue (native_app_glue), so dispatchKeyEvent never reached it (no control at all) → input.c queues synthetic
+  events there (ALooper_poll* return the queue's ident while one waits; AInputQueue_getEvent/finishEvent and the
+  AInputEvent/AKeyEvent/AMotionEvent getters are hand-written "!" imports that know them; touch positions scaled to the
+  window size). Same mapping as AFFECTED: trigger = hold touchpad, A = tap, right stick = swipe, B = back; for NativeActivity games the stick's up/down = swipe forward/back (touchpad X: Gunjack's OnFlick = reload at ~0°, special weapon at ~180°). Not yet
+  headset-verified. Quest builds on the bridge (2026-10-13, Sports Scramble = a 32-bit Santa Cruz build,
+  UE 4.21 + OVRPlugin on VrApi 1.21): manifest requires `android.hardware.vr.headtracking` version 1
+  (`detect.requires_6dof`, headset "quest", ANALYSIS_VERSION 16) → convert writes `assets/fp_a32_headset.txt`
+  = "quest" → vrapi.c `quest_touch` (read in vrapi_Initialize via the activity's AssetManager; A32_TOUCH=1/0
+  overrides) passes the 64-bit bridge's Touch controllers through (enumerate/caps/state/tracking/haptics, struct
+  tails per VrApi minor) and starts no synthetic input. It also needed AAsset_getBuffer (guest copy, freed in
+  AAsset_close), AKeyEvent_getFlags and the other AConfiguration getters. Headset (owner, 2026-10-13): plays,
+  both controllers work. Recenter (holding the Frame's menu button) turned VrApi games ~90-120 degrees aside: the bridge's app space is LOCAL + the start yaw and the runtime moves LOCAL to the head → the bridge now takes the origin from the head again on XR_TYPE_EVENT_DATA_REFERENCE_SPACE_CHANGE_PENDING (LOCAL) and on vrapi_RecenterPose (owner-verified with Gunjack, 2026-10-13). Next: the other 32-bit catalog games (Journey of the Gods, Shadow Point: still "unsupported" until
+  tested), translator speed. Profiled on the Frame
+  (2026-10-12, `A32_PERFMAP` + perf): FPCR switches are negligible (8 of 86k samples); the cost was the run loop
+  (a mutex + hash-chain walk on every dispatch, a contended counter, inline-lookup slots never refilled: Gunjack
+  ~45 % of its CPU) and `jit_invalidate` scanning every block on each Mono `cacheflush` (72 % of Spunky Dungeon's
+  main thread). Now lock-free lookups, ltab refill, per-thread flags, per-page block lists: Gunjack's dispatcher
+  23.6 % -> 1.6 %, CPU in the same phase about -55 %, still 72 fps.
 - `scripts/` — `package.py` (flet build/pack), `eval_heuristics.py` (score heuristics), `ui_smoke.py` (GUI screenshots).
 - `docs/` — PLAYBOOK, FRAME_RUNTIME, ARCHITECTURE, INSTALL (end users), parity reports (offline + device).
 
@@ -323,8 +387,17 @@ Games tests: `pytest -m games` (FRAMEPORT_GAMES=<downloads dir>); on-device chec
 native layer test: `FRAMEPORT_NATIVE_TESTS=1 pytest -m native` (compiles with the NDK, ~2 min on NTFS).
 Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattributes`).
 - `FRAMEPORT_HOME=<dir>` isolates all app data (tests use it); `FRAMEPORT_JAVA/_OVERPORT_JAR/_APKSIGNER_JAR` override
-  managed tools. Real app data (WSL): `~/.local/share/frameport` (tools, overport workspace + game keystores, library,
-  artwork, frames.json, the app's SSH key which the dev Frame authorizes).
+  managed tools. **The owner's real app data is the Windows copy's: `%LOCALAPPDATA%\FramePort`** (= `/mnt/c/Users/
+  <user>/AppData/Local/FramePort`; tools, overport workspace + game keystores, library, artwork, frames.json, the app's
+  SSH key which the dev Frame authorizes; moved from WSL's `~/.local/share/frameport` on 2026-10-11, which is now only
+  a stale backup). The desktop shortcut "FramePort (dev)" runs the source checkout natively on Windows
+  (`%LOCALAPPDATA%\FramePort-dev\launch-frameport-dev.vbs`: venv `FramePort-dev\venv` via `UV_PROJECT_ENVIRONMENT`,
+  `uv sync --frozen`, log `FramePort\logs\dev-gui.log`). **WSL runs on that data need `FRAMEPORT_WINDOWS_DATA=1`**
+  (set in `.claude/settings.local.json`; `paths.shares_windows_data`): the data folder becomes the Windows one, saved
+  paths from the other side are translated on load (`paths.localize`: /mnt/d/X <-> D:\X in library.json, tools.json,
+  PC deployment records), Java/Cpp2IL keep one copy per OS (tools.json `java-<os>-<arch>`), and the link handler isn't
+  registered (it would point the Windows copy's links at WSL). Don't run a WSL GUI and the Windows GUI at once
+  (the gui.lock flock/msvcrt locks don't see each other; only the gui.alive heartbeat does).
 - Device checks: `frameport test <pkg>` / `frameport parity-device --results <parity.json> --baseline <launch.txt>
   [--test-only]`; the pre-FramePort baseline is `PATCHED/_known-good-2026-09-28/_frame-state/baseline-launch.txt`.
 - Docs screenshots + videos (docs/SHOWCASE.md): never by hand. `uv run python scripts/showcase/render_docs.py`
@@ -352,6 +425,11 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
   `T.px(n)`, Material defaults through the theme's text_theme; never hardcode a bare pixel number in ui/.
   `scripts/ui_smoke.py --scale 1.5 --viewport 2560x1440` renders it. Flet draws a grey box for invalid layouts (e.g.
   an `expand` child in a `wrap=True` Row).
+- One GUI per data folder (`core/instance.py`, 2026-10-11): `<data>/gui.lock` (flock/msvcrt, pid inside); a second
+  start asks the open window to come to the front (`gui.focus`, read by `_watch_links`) and exits; a lock held with no
+  window (no `gui.alive`) and older than 30 s is a leftover FramePort process and is ended. `main()` ends the process
+  (`os._exit`) once `ft.run` returns: background threads (re-analysis, session triage) used to keep a windowless
+  process running. Session triage shows one pop-up for all games of a burst (`_announce_sessions`).
 - Stopping the GUI: `pkill -f` patterns match your own shell — use `pgrep -f "[b]in/frameport-gui|[f]let-desktop-light"`.
 
 ## Round-2 polish (2026-10-02)
@@ -375,7 +453,7 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
 
 ## Hard-won facts (don't re-learn these)
 **Frame runtime (SteamOS 0.3.0, build 20260922):**
-- No AArch32: 32-bit-only APKs fail with `INSTALL_FAILED_NO_MATCHING_ABIS`. Unfixable; point to Rift + Revive.
+- No AArch32: 32-bit-only APKs fail with `INSTALL_FAILED_NO_MATCHING_ABIS` → `frame.a32_bridge` (the a32 translator inside the app, see native/a32translator below).
 - GLES swapchains: only `GL_SRGB8_ALPHA8`/`GL_SRGB8` (35907/35905), no MSAA. Vulkan: format 43 (sRGB) but not 37 (UNORM).
 - Missing: XR_FB_passthrough (emulate via ALPHA_BLEND), XR_FB_scene/spatial entities (emulated room from STAGE bounds),
   XR_KHR_composition_layer_equirect2/cylinder, XR_FB_composition_layer_image_layout (flip emulated by Vulkan blit).
@@ -625,7 +703,9 @@ reaches its OVRInput cleanly (probe: both Touch connected 0x63, individual butto
 "outside of frame bounds" warnings stay (~2/frame) and are harmless.
 Steam library (GitHub #4/#21/#27, agent v38): shortcuts go to every Steam account (signed-in first; MostRecent isn't
 always the account on the Frame); stop_steam also waits for Steam's helpers; after the restart the agent re-reads
-shortcuts.vdf and writes once more if Steam put its old copy back (`shortcuts_lost`), else reports it. 0.6.3's Play
+shortcuts.vdf and writes once more if Steam put its old copy back (`shortcuts_lost`); lost again (agent v89): Steam
+ignores FramePort's entries on that Frame, so `add_devkit_entry` adds the devkit entry instead (`added` gets `via:
+devkit`) and only reports an error if that fails too. 0.6.3's Play
 auto-repair (`_add_then_play`) crashed (its job got a Job, not a reporter). Uploads resume on a transient OSError.
 Lepton's Android 11 has no clipboard service (134 services; checked with `podman exec … service check clipboard`):
 SDL/LÖVE apps crashed at start → `frame.sdl_clipboard` (`apk/dex.py`: in-place dex edit, nops one invoke, fixes
@@ -723,6 +803,22 @@ own context and saved as `files/fb_snap_0-7.ppm` (quarter size) — headless lau
 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).
 **SteamVR overlay apps (agent v75, 2026-10-10):** host OpenVR overlays (VRApplication_Overlay) are composited over Lepton (Quest) games on the Frame (probe checker seen over 4XVR in the headset view, `native/vroverlay_probe`); Windows ones register through Proton's vrclient too (Temporal Reality's Windows build created its overlays; fpsVR never reaches OpenVR under Proton). Detection `analysis/vroverlay.py` (bundled `.vrmanifest` with `is_dashboard_overlay`, else OpenVR + IVROverlay + self-registration markers, engine Other; Rift fingerprint `RIFT_ANALYSIS`), patch `pcvr.vr_overlay` (param autostart), Linux entry fields `vr_overlay`/`vr_overlay_autostart` (game page switch); agent `register_vr_overlay`/`unregister_vr_overlay`/`launch_vr_overlay` (IVRApplications via ctypes, live; manifest `<anchor>/frameport-overlay.vrmanifest`, the app's own key, binary = launch.sh). **SteamVR on the Frame reads only `binary_path_linux_arm`** (binary_path_linux alone is skipped). Overlay apps: no launch test, no Linux Steam-parent watchdog (`FRAMEPORT_OVERLAY`), not a "running game". A Steam overlay-app shortcut and a game shortcut run together. SteamVR's SetApplicationAutoLaunch didn't persist on the dev Frame (the watch never started by itself) → **agent v76: FramePort's own autostart**: the deployment's `overlay.autostart` is the source of truth; `ensure_host_fixes` (`ensure_overlay_service`) keeps the user service `frameport-vr-overlays.service` (`_vr_overlay_watch`, 5 s polls of the known vrserver's /proc stat) only while an overlay app has autostart on (register/unregister, uninstall, purge and the kill switch `~/.local/share/frameport/vr-overlays.disabled` / `FRAMEPORT_NO_OVERLAY_AUTOSTART` update it); a new vrserver (pid + start time, kept in `~/.cache/frameport-vr-overlays.json` across agent updates) → child `_vr_overlay_round`: wait for IVRApplications, 15 s grace, `launch_vr_overlay` for apps not running (folder process or GetApplicationProcessId); log `~/.local/share/frameport/vr-overlays.log`. Dev Frame: adopted the running vrserver, skipped the already running watch; a start after a real SteamVR start/boot is not yet seen. Details: docs/FRAME_RUNTIME.md "Overlay apps".
+**Vader's leak solved / AC Nexus flips (2026-10-14):** Vader Immortal leaves GL errors pending on its context; SteamVR's GL interop (`openxr_graphics_gl_openvr.cpp`, `xrclient_<pkg>.txt` in Steam's logs: `SXR_GL_CHECK: error:0x502 ... glGenTextures`) takes the stale error as its own failure once, and from then on `CVRCompositorSharedTextures::BeginCommandBuffer` allocates a command buffer every frame (perf page-fault stacks; ~430 renderD128 mappings + 22 MB/s). Adapter `gl_error_clear` (GLES, catalog on for Vader ep1-3) clears them before xrCreateSwapchain/xrBeginFrame/xrEndFrame: flat memory, no SXR_GL_CHECK (headless). The per-game `xrclient_<pkg>.txt` logs are worth reading for runtime errors. The Frame's runtime caps swapchains per session (XR_ERROR_LIMIT_REACHED from ~15; AC Nexus asks for more): flip emulation now turns quads upright in place (scratch VkImage, once per acquire; transfer usage added to single-layer colour swapchains) instead of a shadow swapchain per quad, which ran into the cap (#138). Headless sessions don't draw AC Nexus's panels (adapter `flip_dump` saves before/after images of flipped quads, for headset runs).
+**Unreal's self-restart (agent v90, 2026-10-13):** UE 4.21+ restarts the app once after its first-run shader
+precompile ("optimizing" screen; `r.ProgramBinaryCache.RestartAndroidAfterPrecompile`): it starts its own LAUNCHER
+activity and calls System.exit(0); Lepton ends the container with the first process (the restarted one with it).
+Skipping `AndroidThunkJava_RestartApplication` or the cvar = 0 (accepted via UE4CommandLine.txt `-ini:`) left Sports
+Scramble on that level for good. launch.sh (RESTART_BLOCK, `upgrade_launchers` adds it) starts Lepton once more when
+`_restart_requested` sees the app's own LAUNCHER start (system log, uid >= 10000) <= 5 s before its exit; first run
+kept as `launch-before-restart.log`; `FRAMEPORT_NO_RESTART=1` off. Owner-verified with Sports Scramble's first start (2026-10-13).
+**xrWaitFrame runs ahead (Journey of the Gods, 2026-10-14, owner-verified):** with real frames (headset on) the
+Frame's runtime sometimes returns from xrWaitFrame at once with a display time less than one refresh after the frame
+just submitted, and then rejects the second submission for that refresh (`VRCompositorError_AlreadySubmitted` in
+Steam's `logs/xrclient_<pkg>.txt`; FrameBridge pacing above the display rate). VrApi games that render faster than
+the display ran ahead (~120 submits/s at 90 Hz) and the scene slid and snapped back. The VrApi bridge re-waits when
+the new display time is under half a period after the last submitted one (`pacing 2s:` counters). Headless runs only
+submit empty frames and never show it. Lepton's logcat mirror also missed the whole verifying session (launch.log =
+Lepton's own lines only), so the keeper doesn't catch every failure.
 **Lepton's logcat mirror dies (agent v67, 2026-10-09):** occasionally launch.log ends with `logcat: Unexpected EOF!` right after the game starts (about 1 launch in 50, Lepton 2.8.14 and 3.0.5): no dashboard auto-hide, no launch-test result. launch.sh's `_logcat_keeper` then reads `podman exec lepton-steamlaunch-<appid> logcat` itself into launch.log (up to 5 restarts while the game runs).
 **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
@@ -790,6 +886,24 @@ index lines; no index (fp_spirv) = the old newest-by-mtime 4 MB. One JSON line (
 is read whole by `Frame.agent` (fine at that size); `_Writer.fit` drops the least recently used modules last, after
 cutting logs, to stay under the 24 MB zip limit.
 **Unreal OBB check (GitHub #159, 2026-10-10):** Epic's DownloaderActivity checks OBB name+size (OBBData), then with `bVerifyOBBOnStartUp=true` CRCs the whole OBB; its screens are invisible in Lepton (stuck at `Displayed …/.DownloaderActivity`, triage `unreal-obb-check-stuck`) → `frame.unreal_skip_obb_check` (analysis `unreal_verify_obb`, ANALYSIS_VERSION 11) flips the manifest boolean (`axml.set_meta_data_bool`); skips only the CRC pass. Host-tested only.
+**Issue round 2026-10-12 (agent v83):** Lepton pastes STEAM_COMPAT_DATA_PATH unquoted into `sh -c "ln -s …/internal/<pkg>
+/data/data/<pkg>"` (mounting.sh): a game on a card named "Steam Frame 512g" got no internal storage (no saves/prefs;
+Beyond Sandbox's EOS then looped `createKeychain→resetKeychain` forever, 1.85 GB log). Quest launchers with an unsafe
+path now `ln -sfn <base> ~/.local/share/frameport/lepton-paths/<pkg>` at every start and give Lepton that path
+(`app_dir_lines`/`set_app_dir`/`launcher_base`; upgrade_launchers converts; deployment.json keeps the real base).
+Verified on the device with a spaced copy of Stremio (old: the `ln` error; new: /data/data link, shared_prefs
+writable). `frame.eos_keychain_loop` (opt-in, triage `eos-keychain-loop`) returns from EOSSDK.resetKeychain. Wander
+0.3570 (Unity 6.5, Firebase, Gecko) ran out of bionic's 128 pthread keys → `frame.unity_tls_key_pool` (Klownicle's
+approach, #198: libunity's 4 key imports renamed `fp_tkey_*` via `elf.rename_imports`, `libfp_tkeys.so` pools
+destructor-less keys behind one real key); device: past Firestore, 72 fps. Cpp2IL releases can't read metadata v107
+(Unity 6.5) → `tools/cpp2il.py` falls back to the development CI build (nightly.link) on that error. Vermillion's canvas
+is an OVROverlay quad (drawn above the hand) → `frame.vermillion_scene_canvas` (PaintableMesh getters → false;
+installed build checked, 72 fps headless; headset not yet). Linux apps: `desktop_icon` switch, a deleted desktop copy
+stays deleted (#212). Findings: OLAR (#201) RHIThread null deref in libUnreal (`ldr x8,[x19,#792]`, x19=0) not fixed by
+hide_space_warp / vk_hide_fdm / no Valve layers; FNAF HW (#135) "freeze" = first-start GL program-binary-cache compile
+on Zink (threads busy in zink/disk cache), not a hang; VR4 (#199) reporter's patch.203 OBB truncated. Upload benchmark
+(`scripts/upload_bench.py`, #242): home Wi-Fi caps every method at ~11 MB/s; paramiko uses ~3x OpenSSH's CPU; Windows
+OpenSSH refuses FramePort's key file (ACL "bad permissions") until its permissions are tightened.
 **Meta user id (GitHub #182, 2026-10-11):** OVRPort's platform loader (runtimes 3.4.3-23204ea and -aa54c3f) answers
 `ovr_GetLoggedInUserID` (and two other callers) without a Meta account with a made-up id from a helper (`stp; mov x29,
 sp; bl random; …; mov/movk x9 = 0x53444835ec580000 (6e18); add x0, x8, x9; ldp; ret`), kept only in memory → a new id
@@ -827,7 +941,8 @@ on the dev Frame) in `files/framebridge-vrapi-fov.txt` and answers with it at th
 r_3dwidth/height, r_width/height from the runtime eye size (FrameBridge logs `runtime recommended eye size`) × scale,
 written at finalize, set_settings and by launch.sh before Lepton starts (`_config_sync`). Headless runs at scale 1.7
 end in `zink: DEVICE LOST` right after the bridge's 30 s no-tracking deadline tears the session down (gpu fault at the
-teardown; not at scale 1.0): a headless-only artifact, the headset never hits that deadline.
+teardown; not at scale 1.0): a headless-only artifact, the headset never hits that deadline. Launch tests count an exit/crash after
+such a line as a pass (triage.yaml `headless_end`, finding `headless-end`; GitHub #57 "Failed to launch" on install).
 **Session triage (agent v70, 2026-10-09):** launch tests never reach FOCUSED, so real play sessions are triaged
 too. list_installed gives each game `last_play` {start, end, test} from `<anchor>/plays.log` (launch tests write a
 `test <unix>` line first → test sessions are only marked); `session_log` returns the newest session's launch.log

THIRD_PARTY_NOTICES.md

@@ -5,6 +5,7 @@ FramePort is GPL-3.0-only (see `LICENSE`). It includes or downloads the followin
 ## Included in this repository / the release bundles
 | Component | Where | License |
 |---|---|---|
+| LuaJIT (Lua engine for verified xLua pointer compatibility, github.com/LuaJIT/LuaJIT) | `artifacts/arm64-v8a/libfp_luajit.so`; pinned build in `native/luajit/build.py` | MIT (`native/luajit/COPYRIGHT`, included in bundles as `artifacts/licenses/LuaJIT.txt`) |
 | OVRPort VrApi → OpenXR adapter (`native/vrapi`, github.com/Android-XR-Bridge/OVRPort), with FramePort's changes | `native/vrapi-bridge/`, `artifacts/arm64-v8a/libvrapi.so` | GPL-3.0 (`native/vrapi-bridge/LICENSE.upstream`) |
 | OVRPort platform compatibility library (`native/platform`) | `native/platformcompat/`, `artifacts/arm64-v8a/libovrplatformcompat.so` | GPL-3.0; Meta Platform SDK headers under the Meta Platform Technologies SDK License (`native/platformcompat/licenses/OCULUS-PLATFORM-SDK.txt`) |
 | Khronos OpenXR SDK headers | used to build the native layers | Apache-2.0 / MIT (`native/vrapi-bridge/licenses/OPENXR-SDK.txt`) |

agent/frameport_agent.py

@@ -44,7 +44,7 @@ try:
 except ImportError:  # Windows: pc_revive loads this file for its VDF code only (GitHub #131)
     fcntl = None
 
-AGENT_VERSION = 79
+AGENT_VERSION = 90
 HOME = os.path.expanduser("~")
 STEAM = os.path.join(HOME, ".local/share/Steam")
 ANCHORS = os.path.join(HOME, "Applications/quest-frame")
@@ -74,10 +74,21 @@ OLD_CODEC_LINES = ('[[ ! -x "$app_dir/frameport-codec/bin/podman" ]] || '
 # LEPTON_ENV_<NAME> to the app as <NAME>). Off for one game: FRAMEPORT_NO_GAMEPAD=1 in its launch options.
 GAMEPAD_PATCH = "device.steam_gamepad"
 PODMAN_BIN = os.path.join(HOME, ".local/share/frameport/agent/bin")
+# Pads come and go (Steam makes its virtual pad only while the Frame's controllers are awake): the container gets the
+# host's /dev/input at /dev/fp-input, and _gamepad_links keeps /dev/input/eventN links to Steam's pads in step while
+# the game runs (Android's EventHub adds and removes them through inotify; agent v85, before only the pads present at
+# the start were bound).
+OLD_GAMEPAD_LINES = ('[[ "${FRAMEPORT_NO_GAMEPAD:-0}" != 0 ]] || { export FRAMEPORT_GAMEPAD=1 '
+                     'LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD=1; '
+                     '[[ ! -x "$HOME/.local/share/frameport/agent/bin/podman" ]] || '
+                     'export PATH="$HOME/.local/share/frameport/agent/bin:$PATH"; }',)
 GAMEPAD_LINE = ('[[ "${FRAMEPORT_NO_GAMEPAD:-0}" != 0 ]] || { export FRAMEPORT_GAMEPAD=1 '
                 'LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD=1; '
                 '[[ ! -x "$HOME/.local/share/frameport/agent/bin/podman" ]] || '
-                'export PATH="$HOME/.local/share/frameport/agent/bin:$PATH"; }')
+                'export PATH="$HOME/.local/share/frameport/agent/bin:$PATH"; '
+                'python3 "$HOME/.local/share/frameport/agent/frameport_agent.py" _gamepad_links "$SteamAppId" $$ '
+                '>"$app_dir/gamepad.log" 2>&1 9>&- & }')
+PAD_DIR = "/dev/fp-input"  # the host's /dev/input inside the container
 
 
 class AgentError(Exception):
@@ -891,6 +902,32 @@ def shortcut_appid(exe, title):
     return zlib.crc32((exe + title).encode("utf-8")) | 0x80000000
 
 
+class VdfMap(dict):
+    """Steam's KeyValues names are case-insensitive; keep their spelling when writing back (#263)."""
+
+    def _key(self, key):
+        return next((k for k in self if k.casefold() == key.casefold()), key)
+
+    def __contains__(self, key):
+        return super().__contains__(self._key(key))
+
+    def __getitem__(self, key):
+        return super().__getitem__(self._key(key))
+
+    def __setitem__(self, key, value):
+        super().__setitem__(self._key(key), value)
+
+    def get(self, key, default=None):
+        return super().get(self._key(key), default)
+
+    def setdefault(self, key, default=None):
+        return super().setdefault(self._key(key), default)
+
+    def update(self, *args, **kwargs):
+        for key, value in dict(*args, **kwargs).items():
+            self[key] = value
+
+
 def vdf_decode(data):
     pos = 0
 
@@ -903,7 +940,7 @@ def vdf_decode(data):
 
     def node():
         nonlocal pos
-        out = {}
+        out = VdfMap()
         while True:
             kind = data[pos]
             pos += 1
@@ -1219,7 +1256,7 @@ def _shortcuts_worker(payload):
         if service or args.get("restart", True):
             start_steam(service)
             lost = shortcuts_lost(users, args["packages"])
-            if lost:  # Steam wrote its old copy back over ours (it was still saving): once more, then report
+            if lost:  # Steam wrote its old copy back over ours (it was still saving): once more, then the devkit entry
                 result["retried"] = lost
                 service = stop_steam()
                 for user in users:
@@ -1227,7 +1264,7 @@ def _shortcuts_worker(payload):
                 start_steam(service)
                 for pkg in shortcuts_lost(users, lost):
                     result["added"] = [a for a in result["added"] if a["package"] != pkg]
-                    result["errors"].append(f"{pkg}: Steam removed the new library entry again after restarting")
+                    add_devkit_entry(pkg, result)
     except Exception as exc:  # noqa: BLE001
         result["state"] = "failed"
         result["errors"].append(str(exc))
@@ -1237,6 +1274,19 @@ def _shortcuts_worker(payload):
         json.dump(result, f)
 
 
+def add_devkit_entry(pkg, result):
+    """Steam dropped the game's shortcuts.vdf entry twice: this Frame's Steam ignores FramePort's entries (GitHub #41),
+    so add it the way Valve's devkit tool does (Steam is running again). That entry is the one Steam keeps."""
+    try:
+        appid = devkit_register(pkg)
+    except Exception as exc:  # noqa: BLE001
+        result["errors"].append(f"{pkg}: Steam removed the new library entry again after restarting, and the devkit "
+                                f"entry failed too: {exc}")
+        return
+    result["added"].append({"package": pkg, "appid": appid, "expected": (deployment(pkg) or {}).get("appid"),
+                            "via": "devkit"})
+
+
 def remove_from_library(user, remove, result):
     """Remove uninstalled games' shortcuts + grid art from one Steam account (Steam is closed)."""
     vdf = os.path.join(STEAM, "userdata", user, "config/shortcuts.vdf")
@@ -1489,10 +1539,17 @@ def is_overlay(dep):
     return bool(isinstance(dep, dict) and dep.get("overlay"))
 
 
+def deployment_summary(dep):
+    """Keep routine connection/monitor samples small; detailed data manifests are fetched only for an update."""
+    return {key: value for key, value in dep.items()
+            if key not in ("data_manifest", "configuration", "managed_config_files")}
+
+
 def cmd_list_installed(args):
     games = []
     table = mounts()
-    for dep_path in sorted(glob.glob(os.path.join(ANCHORS, "*/deployment.json"))):
+    selected = check_pkg(args["package"]) if args.get("package") else "*"
+    for dep_path in sorted(glob.glob(os.path.join(ANCHORS, selected, "deployment.json"))):
         try:
             dep = json.load(open(dep_path))
         except (OSError, ValueError):
@@ -1529,7 +1586,7 @@ def cmd_list_installed(args):
             dep["apk_present"] = os.path.exists(apk)
             dep["apk_size"] = os.path.getsize(apk) if dep["apk_present"] else 0
         dep["last_play"] = last_play(dep["anchor"])  # agent v70: the PC triages a finished play session's log
-        games.append(dep)
+        games.append(dep if args.get("details") else deployment_summary(dep))
     return {"games": games}
 
 
@@ -2890,10 +2947,57 @@ def cmd_prepare(args):
             "free_bytes": free, "lepton": lepton}
 
 
+# Valve's Lepton pastes the game's paths unquoted into shell commands (liblepton mounting.sh: `sh -c "... ln -s
+# ${STEAM_COMPAT_DATA_PATH}/internal/<pkg> /data/data/<pkg>"`, `lepton_basename ${APK}`), so a game on a drive whose
+# name has a space ("Steam Frame 512g") never gets its internal storage: no saves, no SharedPreferences, and e.g. Epic's
+# EOS SDK retries its keychain forever (GitHub #213/#214/#215/#221). Such games reach Lepton through a link without
+# spaces, made again at every start (a card can be mounted elsewhere); deployment.json keeps the real path.
+LEPTON_PATHS = os.path.join(HOME, ".local/share/frameport/lepton-paths")
+LEPTON_SAFE_RE = re.compile(r"[A-Za-z0-9._/+@%=:,-]+")
+APP_DIR_RE = re.compile(r"^(?:mkdir -p \S*lepton-paths\S* && ln -sfn .*\n)?app_dir=(.*)$", re.M)
+
+
+def app_dir_lines(base, pkg):
+    """The launcher's app_dir line for a game in `base` (a link line first when Lepton can't take that path)."""
+    if LEPTON_SAFE_RE.fullmatch(base):
+        return "app_dir=" + shlex.quote(base)
+    link = os.path.join(LEPTON_PATHS, pkg)
+    return (f"mkdir -p {shlex.quote(LEPTON_PATHS)} && ln -sfn {shlex.quote(base)} {shlex.quote(link)}"
+            f"  # Lepton can't take paths with spaces\napp_dir={shlex.quote(link)}")
+
+
+def remove_lepton_path(pkg):
+    try:
+        os.remove(os.path.join(LEPTON_PATHS, pkg))
+    except OSError:
+        pass
+
+
+def set_app_dir(text, base, pkg):
+    """launch.sh with its app_dir line(s) for `base`; (text, False) when it has none."""
+    text, n = APP_DIR_RE.subn(lambda m: app_dir_lines(base, pkg), text, count=1)
+    return text, bool(n)
+
+
+def launcher_base(text, pkg):
+    """The game folder a Quest launcher points at (the link's target when it goes through LEPTON_PATHS), or None."""
+    m = APP_DIR_RE.search(text)
+    if not m:
+        return None
+    try:
+        words = shlex.split(m.group(0).splitlines()[0], comments=True)
+    except ValueError:
+        return None
+    if m.group(0).startswith("mkdir -p ") and len(words) >= 8 and words[3:6] == ["&&", "ln", "-sfn"]:
+        return words[6]
+    value = shlex.split(m.group(1)) if m.group(1) else []
+    return value[0] if len(value) == 1 else None
+
+
 LAUNCH_SH = (r"""#!/usr/bin/env bash
 # Steam Frame launcher for {title} ({pkg}). Generated by FramePort.
 set -euo pipefail
-app_dir={base_q}
+{app_dir}
 [[ -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
@@ -2907,6 +3011,9 @@ r""" true; }}
 r""" here.
 mkdir -p "$app_dir/lepton-data/external/Android/data/{pkg}/files" """
 r""""$app_dir/lepton-data/external/Android/data/{pkg}/cache" 2>/dev/null || true
+# Prepare cloud saves before startup: a newly created cloud folder can have mode 1700, and the game may try to
+# create its data subfolder before the permission watchdog repairs it (Jurassic World Aftermath, GitHub #239).
+{cloud_dirs}
 fix_perms
 {watchdog}
 export SteamAppId={appid}
@@ -2936,7 +3043,7 @@ setsid {lepton_q} start >"$app_dir/launch.log" 2>&1 &
 child=$!
 {dashboard}
 {logcat}
-wait "$child"
+{restart}
 """)
 
 
@@ -2970,11 +3077,82 @@ SINGLE_LINE = ('exec 9>"$app_dir/.launch.lock"; flock -n 9 || '
 LOGCAT_LINE = ('python3 {agent_q} _logcat_keeper "$app_dir/launch.log" "$SteamAppId" $$ '
                '>"$app_dir/logcat-keeper.log" 2>&1 9>&- &')
 
+CLOUD_DIRS_LINE = 'mkdir -p "$app_dir/lepton-data/external/Android/data/{pkg}/files/cloud/data" 2>/dev/null || true'
+
+
+def cloud_dirs_line(pkg):
+    return CLOUD_DIRS_LINE.format(pkg=pkg)
+
 
 def dashboard_line():
     return DASHBOARD_LINE.format(agent_q=shlex.quote(os.path.abspath(__file__)))
 
 
+# Unreal (4.21+, r.ProgramBinaryCache.RestartAndroidAfterPrecompile) restarts the app once after its first-run shader
+# precompile (the "optimizing" screen): it starts its own launcher activity and exits. Lepton ends the container when
+# the first process exits, the restarted game with it (Sports Scramble stopped after its first start; skipping the
+# restart left it on that screen). The launcher then starts Lepton once more, in the same Steam launch
+# (_restart_requested reads the two logs). FRAMEPORT_NO_RESTART=1 turns it off.
+RESTART_BLOCK = """rc=0; wait "$child" || rc=$?
+if [[ -z "${{FRAMEPORT_NO_RESTART:-}}" ]] && python3 {agent_q} _restart_requested "$app_dir/launch.log" "$SteamAppId" \\
+        {pkg_q} 9>&-; then
+    mv -f "$app_dir/launch.log" "$app_dir/launch-before-restart.log" 2>/dev/null || true
+    setsid {lepton_q} start >"$app_dir/launch.log" 2>&1 &
+    child=$!
+    {dashboard}
+    rc=0; wait "$child" || rc=$?
+fi
+exit $rc"""
+
+
+def restart_block(pkg, lepton):
+    return RESTART_BLOCK.format(agent_q=shlex.quote(os.path.abspath(__file__)), pkg_q=shlex.quote(pkg),
+                                lepton_q=shlex.quote(lepton), dashboard=dashboard_line())
+
+
+LOGCAT_TIME = re.compile(r"^(?:\x1b\[[0-9;]*m)?(\d\d-\d\d \d\d:\d\d:\d\d\.\d{3})")
+
+
+def restart_requested(log, appid, pkg, max_gap=5.0):
+    """Whether the game that just ended asked to be started again (RESTART_BLOCK): in Lepton's system log (dumped to
+    lepton-logcats/steamlaunch-<appid>/ when the container ends) the app itself (uid >= 10000; Lepton's own start is
+    uid 0) started its LAUNCHER activity by package, and at most max_gap s later the game's process called
+    System.exit(0) (launch.log; Android's WebView helper does too at every boot)."""
+    def when(line):
+        m = LOGCAT_TIME.match(line)
+        if not m:
+            return None
+        try:
+            t = time.strptime("2000-" + m.group(1)[:14], "%Y-%m-%d %H:%M:%S")
+        except ValueError:
+            return None
+        return time.mktime(t) + float(m.group(1)[14:])
+    try:
+        with open(log, errors="replace") as f:
+            exits = [when(ln) for ln in f if "System.exit called, status: 0" in ln and "WebViewLoader" not in ln]
+        syslog = os.path.join(STEAM, "logs", "lepton-logcats", f"steamlaunch-{appid}", "logcat-system.log")
+        with open(syslog, errors="replace") as f:
+            starts = []
+            for ln in f:
+                m = re.search(r"ActivityTaskManager: START u0 \{act=android\.intent\.action\.MAIN "
+                              r"cat=\[android\.intent\.category\.LAUNCHER\][^}]* pkg=" + re.escape(pkg)
+                              + r"[ }][^\n]* from uid (\d+)", ln)
+                if m and int(m.group(1)) >= 10000:
+                    starts.append(when(ln))
+    except OSError:
+        return False
+    for e in exits:
+        if e is not None and any(s is not None and 0 <= e - s <= max_gap for s in starts):
+            try:
+                with open(log, "a") as f:
+                    f.write("FramePort: the game restarted itself (e.g. Unreal after its first-run shader "
+                            "precompile): starting it again\n")
+            except OSError:
+                pass
+            return True
+    return False
+
+
 def logcat_line():
     return LOGCAT_LINE.format(agent_q=shlex.quote(os.path.abspath(__file__)))
 
@@ -3000,10 +3178,17 @@ def upgrade_launchers():
         # the codec line follows the game's deployment (only Lepton launchers have this variable; Proton/Linux
         # launchers are never touched). Running launchers keep reading their old file.
         if "export LEPTON_ENV_FRAMEBRIDGE_CONFIG=" in new:
+            cloud = cloud_dirs_line(os.path.basename(os.path.dirname(path)))
+            if cloud not in new:
+                new = new.replace("\nfix_perms\n", "\n" + cloud + "\nfix_perms\n", 1)
             new = set_codec_line(new, wants_hw_video(os.path.dirname(path)))
             new = set_gamepad_line(new, wants_gamepad(os.path.dirname(path)))
             new = set_config_sync_line(new, os.path.basename(os.path.dirname(path)),
                                        wants_config_sync(os.path.dirname(path)))
+            pkg = os.path.basename(os.path.dirname(path))
+            base = launcher_base(new, pkg)
+            if base:  # games on a drive whose path has a space reach Lepton through a link (agent v83)
+                new = set_app_dir(new, base, pkg)[0]
         if "a Linux app. Generated by FramePort" in new and "FRAMEPORT_DESKTOP" not in new:
             new = upgrade_linux_launcher(new)
         if OLD_WATCHDOG in new and "parent=$PPID" not in new:
@@ -3019,6 +3204,15 @@ def upgrade_launchers():
             # 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 "_restart_requested" not in new and new.endswith('\nwait "$child"\n') and "_dashboard_worker" in new:
+            m = re.search(r'\nsetsid (\S+) start >', new)
+            pkg = os.path.basename(os.path.dirname(path))
+            try:
+                lepton = shlex.split(m.group(1))[0] if m else None
+            except ValueError:
+                lepton = None
+            if lepton:
+                new = new[:-len('wait "$child"\n')] + restart_block(pkg, lepton) + "\n"
         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
@@ -3109,7 +3303,8 @@ def wrapper_lines(hw_video, gamepad):
 def set_gamepad_line(text, want):
     """A Lepton launcher with the gamepad line (want) or without it. It always follows the codec line (when there is
     one), else stands where the codec line would."""
-    text = text.replace(GAMEPAD_LINE + "\n", "")
+    for line in (GAMEPAD_LINE, *OLD_GAMEPAD_LINES):
+        text = text.replace(line + "\n", "")
     if not want:
         return text
     i = text.find(VIDEO_CODEC_LINE + "\n")
@@ -3122,7 +3317,9 @@ def set_gamepad_line(text, want):
 
 # Android's layout for an Xbox 360 pad (AOSP's Vendor_045e_Product_028e.kl, with Select as BUTTON_SELECT instead of
 # BACK, which would close many apps): Steam's virtual pad reports Valve's ids, so Android would fall back to Generic.kl
-# (triggers on Z/RZ, right stick on RX/RY: games then mix up the right stick and the triggers).
+# (triggers on Z/RZ, right stick on RX/RY: games then mix up the right stick and the triggers). The D-pad keys
+# (BTN_DPAD_*, as AOSP's Generic.kl) cover a pad that sends its D-pad as buttons rather than the hat axes: the Frame's
+# controllers have no D-pad, so it only comes from a Steam Input layout (e.g. a stick set to D-pad, GitHub #162).
 GAMEPAD_KL = """# Steam Input virtual gamepad (Xbox 360 layout). Written by FramePort (device.steam_gamepad).
 key 304   BUTTON_A
 key 305   BUTTON_B
@@ -3135,6 +3332,10 @@ key 315   BUTTON_START
 key 316   BUTTON_MODE
 key 317   BUTTON_THUMBL
 key 318   BUTTON_THUMBR
+key 544   DPAD_UP
+key 545   DPAD_DOWN
+key 546   DPAD_LEFT
+key 547   DPAD_RIGHT
 axis 0x00 X flat 4096
 axis 0x01 Y flat 4096
 axis 0x03 Z flat 4096
@@ -3188,9 +3389,11 @@ def steam_gamepads(sys_root="/sys", dev_root="/dev"):
 
 def podman_run_args(args, env, sys_root="/sys", dev_root="/dev"):
     """FramePort's Podman wrapper (PODMAN_WRAPPER) for `podman run`: the game's own container
-    (lepton-steamlaunch-<SteamAppId>, launcher env) gets Steam's virtual gamepads and their key layout when its
-    launcher asked for them (FRAMEPORT_GAMEPAD=1, the gamepad line). Anything else: the arguments unchanged. Lepton
-    mounts a tmpfs over /dev, so a `--device` node would vanish under it: bind mounts, like Lepton's own GPU nodes."""
+    (lepton-steamlaunch-<SteamAppId>, launcher env) gets the host's /dev/input at PAD_DIR and the gamepad key layout
+    when its launcher asked for them (FRAMEPORT_GAMEPAD=1, the gamepad line); _gamepad_links then links Steam's pads
+    into the container's /dev/input. Anything else: the arguments unchanged. Lepton mounts a tmpfs over /dev, so a
+    `--device` node would vanish under it, and its /dev/input holds its own Wayland input pipes: a bind mount next to
+    it, like Lepton's own GPU nodes."""
     if args[:1] != ["run"] or env.get("FRAMEPORT_GAMEPAD") != "1" or \
             env.get("FRAMEPORT_NO_GAMEPAD", "0") not in ("", "0"):
         return args
@@ -3213,13 +3416,10 @@ def podman_run_args(args, env, sys_root="/sys", dev_root="/dev"):
                 taken.add(value)
     pads = steam_gamepads(sys_root, dev_root)
     extra = []
-    for pad in pads:
-        node = f"/dev/input/{pad['event']}"
-        if node not in taken:
-            extra += ["--mount", f"type=bind,source={os.path.join(dev_root, 'input', pad['event'])},"
-                                 f"destination={node},rw"]
+    if PAD_DIR not in taken:
+        extra += ["--mount", f"type=bind,source={os.path.join(dev_root, 'input')},destination={PAD_DIR},rw"]
     layout = gamepad_layout_file() if extra else ""
-    for product in sorted({p["product"] for p in pads}):
+    for product in sorted({"11ff", *(p["product"] for p in pads)}):  # 11ff: Steam's pad, also when it comes later
         target = f"/system/usr/keylayout/Vendor_28de_Product_{product}.kl"
         if layout and target not in taken and re.fullmatch(r"[0-9a-f]{4}", product):
             extra += ["--mount", f"type=bind,source={layout},destination={target},ro"]
@@ -3228,6 +3428,44 @@ def podman_run_args(args, env, sys_root="/sys", dev_root="/dev"):
     return [args[0], *extra, *args[1:]] if extra else args
 
 
+def pid_alive(pid):
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except OSError:
+        return True
+
+
+def gamepad_link_script(want, linked):
+    """Shell for the container: /dev/input links to Steam's pads (want: event names) instead of linked ones."""
+    gone = sorted(set(linked) - set(want))
+    parts = [f"rm -f /dev/input/{e}" for e in gone if re.fullmatch(r"event[0-9]+", e)]
+    parts += [f"[ -e /dev/input/{e} ] || ln -s {PAD_DIR}/{e} /dev/input/{e}" for e in sorted(want)
+              if re.fullmatch(r"event[0-9]+", e)]
+    return "; ".join(parts) or "true"
+
+
+def gamepad_links(appid, parent, poll=1.0, refresh=15.0, exec_=None, pads=steam_gamepads, alive=pid_alive):
+    """While the launcher (parent) runs: keep the game's container's /dev/input links in step with Steam's virtual
+    pads (made when the Frame's controllers wake up, gone when they sleep). Re-applied every `refresh` s, so a
+    container Lepton started again gets them too."""
+    container = f"lepton-steamlaunch-{int(appid)}"
+    exec_ = exec_ or (lambda script: run(["podman", "exec", container, "sh", "-c", script], timeout=20))
+    linked, last = set(), 0.0
+    while alive(int(parent)):
+        want = {p["event"] for p in pads()}
+        now = time.monotonic()
+        if want != linked or (want and now - last >= refresh):
+            r = exec_(gamepad_link_script(want, linked))
+            if r.returncode == 0:
+                if want != linked:
+                    print(f"{time.strftime('%H:%M:%S')} pads: {', '.join(sorted(want)) or 'none'}", flush=True)
+                linked, last = want, now
+        time.sleep(poll)
+
+
 def gamepad_layout_file():
     path = os.path.join(os.path.dirname(PODMAN_BIN), "steam-gamepad.kl")
     try:
@@ -3361,12 +3599,13 @@ def upgrade_linux_launcher(text):
 def write_launcher(anchor, base, pkg, title, appid, lepton, env, hw_video=False, gamepad=False, config_sync=False):
     extra = "".join(f"export {k}={shlex.quote(str(v))}\n" for k, v in (env or {}).items()
                     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,
+    text = LAUNCH_SH.format(title=title.replace("\n", " "), pkg=pkg, app_dir=app_dir_lines(base, pkg), appid=appid,
                             lepton_q=shlex.quote(lepton), extra_env=extra, watchdog=WATCHDOG,
                             dashboard=dashboard_line(), logcat=logcat_line(), single=SINGLE_LINE,
+                            cloud_dirs=cloud_dirs_line(pkg),
                             video_codec=wrapper_lines(hw_video, gamepad),
                             plays_start=plays_lines(anchor)[0],
-                            plays_end=plays_lines(anchor)[1])
+                            plays_end=plays_lines(anchor)[1], restart=restart_block(pkg, lepton))
     text = set_config_sync_line(text, pkg, config_sync)
     path = os.path.join(anchor, "launch.sh")
     with open(path + ".tmp", "w") as f:
@@ -3683,7 +3922,7 @@ def cmd_finalize(args):
     pkg = check_pkg(args["package"])
     title = args["title"]
     prep = cmd_prepare({"package": pkg, "title": title, "dest": args.get("dest")})
-    base, anchor, appid, incoming = prep["base"], prep["anchor"], prep["appid"], prep["incoming"]
+    base, anchor, incoming = prep["base"], prep["anchor"], prep["incoming"]
     lepton = prep["lepton"]
     if not lepton:
         raise AgentError("Lepton is not installed (Developer Mode → install/launch 'Lepton Development' once)")
@@ -3704,6 +3943,10 @@ def cmd_finalize(args):
         bad = [k for k, v in expected.items() if have.get(k) != v]
         if bad:
             raise AgentError(f"{len(bad)} data file(s) missing or incomplete, e.g. {bad[0]}")
+    if args.get("existing_only") and os.path.exists(new_apk):
+        raise AgentError("an interrupted APK upload is pending; finish that install before updating data")
+    if args.get("existing_only"):
+        verify_installed_apk(deployment(pkg), args.get("apk_sha256"))
     if os.path.exists(new_apk):
         if args.get("apk_sha256") and sha256_file(new_apk) != args["apk_sha256"]:
             raise AgentError("uploaded APK checksum mismatch (transfer corrupted?)")
@@ -3714,16 +3957,67 @@ def cmd_finalize(args):
     elif not os.path.exists(os.path.join(app, "game.apk")):
         raise AgentError("no APK uploaded and none installed")
     moved = 0
-    for root, _, files in os.walk(inc_obb):
-        for name in files:
-            if name.endswith(".part"):
-                continue
-            src = os.path.join(root, name)
-            dst = os.path.join(app, "obb", os.path.relpath(src, inc_obb))
-            os.makedirs(os.path.dirname(dst), exist_ok=True)
-            os.replace(src, dst)
-            moved += 1
-    shutil.rmtree(incoming, ignore_errors=True)
+    if not args.get("preserve_data"):
+        for root, _, files in os.walk(inc_obb):
+            for name in files:
+                if name.endswith(".part"):
+                    continue
+                src = os.path.join(root, name)
+                rel = os.path.relpath(src, inc_obb)
+                if expected is not None and rel not in expected:
+                    continue  # an older interrupted upload is not part of this install
+                dst = os.path.join(app, "obb", rel)
+                os.makedirs(os.path.dirname(dst), exist_ok=True)
+                os.replace(src, dst)
+                moved += 1
+        shutil.rmtree(incoming, ignore_errors=True)
+    return configure_install({**args, "consume_artwork": args.get("consume_artwork", True)}, prep, moved)
+
+
+def verify_installed_apk(dep, expected):
+    apk = os.path.join(dep["base"], "lepton-app", "game.apk")
+    if not expected or dep.get("sha256") != expected or not os.path.isfile(apk):
+        raise AgentError("installed APK is missing or changed; refresh and reinstall it")
+    st = os.stat(apk)
+    identity = {"size": st.st_size, "mtime_ns": st.st_mtime_ns}
+    if identity != dep.get("apk_stat") and sha256_file(apk) != expected:
+        raise AgentError("installed APK content changed; reinstall it")
+
+
+def cmd_configure(args):
+    """Apply runtime configuration to an existing, matching APK without staging/replacing game files."""
+    pkg = check_pkg(args["package"])
+    dep = deployment(pkg)
+    if not dep or dep.get("kind", "quest") != "quest":
+        raise AgentError(f"{pkg} is not an installed Quest/Android app")
+    base, _ = new_base(args, pkg, dep)  # validates a removable drive; never silently falls back
+    verify_installed_apk(dep, args.get("apk_sha256"))
+    if container_running(dep["appid"]):
+        raise AgentError("Close the game before updating its configuration")
+    lepton, _ = lepton_path()
+    if not lepton:
+        raise AgentError("Lepton is not installed")
+    return configure_install({**args, "title": dep["title"]},
+                             {"base": base, "anchor": os.path.join(ANCHORS, pkg),
+                              "appid": dep["appid"], "lepton": lepton}, 0)
+
+
+def configure_install(args, prep, moved):
+    pkg, title = check_pkg(args["package"]), args["title"]
+    base, anchor, appid, lepton = prep["base"], prep["anchor"], prep["appid"], prep["lepton"]
+    app = os.path.join(base, "lepton-app")
+    previous = deployment(pkg) or {}
+    files_dir = data_files_dir(base, pkg)
+    for rel in set(args.get("files") or {}) | set(previous.get("managed_config_files") or {}):
+        target = os.path.realpath(os.path.join(files_dir, rel))
+        if not _inside(target, os.path.realpath(files_dir)) or target == os.path.realpath(files_dir):
+            raise AgentError(f"refusing to write outside the game's files dir: {rel}")
+        backup = os.path.join(files_dir, rel) + ".frameport-config-backup"
+        if os.path.islink(backup):
+            raise AgentError(f"refusing a linked configuration backup: {rel}")
+    for key, value in (args.get("settings") or {}).items():
+        if not re.fullmatch(r"[a-z_]+", key) or any(c in str(value) for c in "\r\n\x00"):
+            raise AgentError(f"bad setting {key}")
     if "flatscreen" in args:  # older clients don't send it: leave the marker as it is
         set_flatscreen(app, args["flatscreen"])
     # settings: settings.conf (read by the adapter via LEPTON_ENV_FRAMEBRIDGE_CONFIG) + framebridge.conf copy
@@ -3740,13 +4034,37 @@ def cmd_finalize(args):
             f.write(text)
         with open(os.path.join(files_dir, "framebridge.conf"), "w") as f:
             f.write(text)
+    managed = previous.get("managed_config_files") or {}
+    wanted = args.get("files") or {}
+    for rel, record in managed.items():
+        if rel in wanted:
+            continue
+        target = os.path.realpath(os.path.join(files_dir, rel))
+        if not _inside(target, os.path.realpath(files_dir)):
+            raise AgentError(f"invalid previously managed path: {rel}")
+        if os.path.isfile(target) and sha256_file(target) == record["sha256"]:
+            backup = target + ".frameport-config-backup"
+            if record.get("backup") and os.path.isfile(backup):
+                os.replace(backup, target)
+            else:
+                os.unlink(target)
+    new_managed = {}
     for rel, content in (args.get("files") or {}).items():
         target = os.path.normpath(os.path.join(files_dir, rel))
         if not target.startswith(files_dir + os.sep):
             raise AgentError(f"refusing to write outside the game's files dir: {rel}")
         os.makedirs(os.path.dirname(target), exist_ok=True)
+        record = managed.get(rel)
+        backup = target + ".frameport-config-backup"
+        # no record: an existing file is the user's, unless it already has exactly this content (written by
+        # FramePort before agent v86 kept records; backing it up would bring it back when the recipe drops it)
+        had_original = bool(record.get("backup")) if record else os.path.isfile(target) and \
+            open(target, "rb").read() != content.encode()
+        if not record and had_original:
+            shutil.copy2(target, backup)
         with open(target, "w") as f:
             f.write(content)
+        new_managed[rel] = {"sha256": sha256_file(target), "backup": had_original}
     models = install_controller_models(files_dir, str(settings.get("controller_models", 0)) not in ("0", "0.0"))
     recipe = args.get("recipe") if isinstance(args.get("recipe"), dict) else {}
     hw_video = HW_VIDEO_PATCH in (recipe.get("patches") or [])  # the shared codec (install_video_codec)
@@ -3756,22 +4074,40 @@ def cmd_finalize(args):
     config_sync = args.get("config_sync") if isinstance(args.get("config_sync"), dict) else {}
     write_launcher(anchor, base, pkg, title, appid, lepton, args.get("env"), hw_video, gamepad, bool(config_sync))
     art_in = os.path.join(base, "incoming-artwork")
-    if os.path.isdir(art_in):
+    art_moved = False
+    if args.get("consume_artwork") and os.path.isdir(art_in):
         shutil.rmtree(os.path.join(anchor, "artwork"), ignore_errors=True)
         shutil.move(art_in, os.path.join(anchor, "artwork"))
-    previous = deployment(pkg) or {}
-    dep = {"package": pkg, "appid": int(appid), "base": base, "title": title, "tags": args.get("tags") or [],
-           "apk": args.get("apk_name", "game.apk"),
-           "sha256": args.get("apk_sha256"), "recipe": args.get("recipe"), "installed_by": "frameport",
+        art_moved = True
+    dep = {**previous, "package": pkg, "appid": int(appid), "base": base, "title": title,
+           "tags": args.get("tags", previous.get("tags")) or [],
+           "apk": args.get("apk_name", previous.get("apk", "game.apk")),
+           "sha256": args.get("apk_sha256") or previous.get("sha256"),
+           "recipe": args.get("recipe"), "installed_by": "frameport",
            "hw_video_decode": hw_video, "steam_gamepad": gamepad, "config_sync": config_sync,
            "agent_version": AGENT_VERSION, "time": time.time()}
     if previous.get("eye_base"):  # the runtime's eye size learned from an earlier start (device.config_sync)
         dep["eye_base"] = previous["eye_base"]
-    with open(os.path.join(anchor, "deployment.json"), "w") as f:
-        json.dump(dep, f, indent=2)
+    dep["managed_config_files"] = new_managed
+    # An app before agent v86 records none of these: what it installed is unknown, so a newer PC mustn't skip work
+    # on the strength of an older record. Art the agent didn't replace keeps its record.
+    art_replaced = bool(args.get("consume_artwork")) and art_moved
+    for key in ("configuration", "configuration_fp", "apk_recipe_fp", "source_version", "artwork_manifest"):
+        if key in args:
+            dep[key] = args[key]
+        elif key != "artwork_manifest" or art_replaced:
+            dep.pop(key, None)
+    if args.get("obb_manifest") is not None:
+        dep["data_manifest"] = args["obb_manifest"]
+    if "data_manifest" in dep:
+        dep["data_fp"] = hashlib.sha256(json.dumps(dep["data_manifest"], sort_keys=True).encode()).hexdigest()[:32]
+    st = os.stat(os.path.join(app, "game.apk"))
+    dep["apk_size"] = st.st_size
+    dep["apk_stat"] = {"size": st.st_size, "mtime_ns": st.st_mtime_ns}
     synced = sync_game_config(pkg, dep)
+    write_deployment(pkg, dep)
     return {"ok": True, "base": base, "appid": appid, "moved_data_files": moved, "controller_models": models,
-            "config_sync": synced}
+            "config_sync": synced, "deployment": deployment_summary(dep)}
 
 
 # --------------------------------------------------------------- Steam Frame controller models (XR_FB_render_model)
@@ -4529,7 +4865,8 @@ def cmd_finalize_linux(args):
            "sha256": args.get("exe_sha256"),
            "missing_libraries": missing, "recipe": args.get("recipe"), "installed_by": "frameport",
            "launcher": {"env": args.get("env") or {}}, "desktop_entry": args.get("desktop_entry", True) is not False,
-           "files": {"app": want or {}}, "agent_version": AGENT_VERSION, "time": time.time()}
+           "desktop_icon": args.get("desktop_icon", True) is not False, "files": {"app": want or {}},
+           "agent_version": AGENT_VERSION, "time": time.time()}
     with open(os.path.join(anchor, "deployment.json"), "w") as f:
         json.dump(dep, f, indent=2)
     try:  # the app's own icon (GitHub #99), found again for every install: a new version may bring another
@@ -4832,9 +5169,11 @@ def desktop_entries(pkg=None, folder=None):
     return out
 
 
-def write_desktop_entry(pkg):
-    """The app's menu entry, plus a copy on ~/Desktop when that folder exists (Plasma starts executable .desktop files
-    there without asking). Returns {"menu": path, "desktop": path or None, "changed": bool}."""
+def write_desktop_entry(pkg, refresh=False):
+    """The app's menu entry, plus a copy on ~/Desktop when that folder exists and deployment.json's "desktop_icon"
+    isn't off (Plasma starts executable .desktop files there without asking). `refresh` (every connection) only
+    updates a desktop copy that is there: one the user deleted stays deleted (GitHub #212). Returns {"menu": path,
+    "desktop": path or None, "changed": bool}."""
     anchor = os.path.join(ANCHORS, pkg)
     dep = deployment(pkg)
     if not dep:
@@ -4846,10 +5185,16 @@ def write_desktop_entry(pkg):
             os.remove(path)
     menu = os.path.join(DESKTOP_APPS, name)
     changed = _write_if_changed(menu, text, 0o755)
-    desk = None
-    if os.path.isdir(DESKTOP_DIR):
-        desk = os.path.join(DESKTOP_DIR, name)
+    desk = os.path.join(DESKTOP_DIR, name)
+    if dep.get("desktop_icon", True) is False:
+        if os.path.exists(desk):
+            os.remove(desk)
+            changed = True
+        desk = None
+    elif os.path.isdir(DESKTOP_DIR) and not (refresh and not os.path.exists(desk)):
         changed = _write_if_changed(desk, text, 0o755) or changed
+    else:
+        desk = None
     return {"menu": menu, "desktop": desk, "changed": changed}
 
 
@@ -4879,7 +5224,7 @@ def refresh_desktop_entries():
             continue
         wanted.add(dep["package"])
         try:
-            if write_desktop_entry(dep["package"])["changed"]:
+            if write_desktop_entry(dep["package"], refresh=True)["changed"]:
                 changed.append(dep["package"])
         except (OSError, AgentError):
             pass
@@ -4891,7 +5236,8 @@ def refresh_desktop_entries():
 
 
 def cmd_desktop_entry(args):
-    """Turn a Linux app's Desktop Mode entry on or off (deployment.json keeps the choice)."""
+    """Turn a Linux app's Desktop Mode entry on or off, and with `icon` its copy on the desktop (agent v83; deployment
+    .json keeps both choices)."""
     pkg = check_pkg(args["package"])
     dep = deployment(pkg)
     if not dep or dep.get("kind") != "linux":
@@ -4901,6 +5247,8 @@ def cmd_desktop_entry(args):
     with open(path) as f:
         raw = json.load(f)
     raw["desktop_entry"] = on
+    if args.get("icon") is not None:
+        raw["desktop_icon"] = bool(args["icon"])
     with open(path + ".tmp", "w") as f:
         json.dump(raw, f, indent=2)
     os.replace(path + ".tmp", path)
@@ -5018,8 +5366,8 @@ def cmd_set_settings(args):
             if k:
                 current[k] = v
     for k, v in (args.get("settings") or {}).items():
-        if not re.fullmatch(r"[a-z_]+", k) or not re.fullmatch(r"-?[0-9.]+", str(v)):
-            raise AgentError(f"bad setting {k}={v}")
+        if not re.fullmatch(r"[a-z_]+", k) or not re.fullmatch(r"-?(?:[0-9]+\.?[0-9]*|\.[0-9]+)", str(v)):
+            raise AgentError(f"bad setting {k}={v}")  # checked before anything is written
         current[k] = str(v)
     text = "".join(f"{k}={v}\n" for k, v in current.items())
     with open(conf, "w") as f:
@@ -5029,7 +5377,19 @@ def cmd_set_settings(args):
     with open(os.path.join(files_dir, "framebridge.conf"), "w") as f:
         f.write(text)
     models = install_controller_models(files_dir, current.get("controller_models", "0") not in ("0", "0.0"))
-    return {"settings": current, "controller_models": models, "config_sync": sync_game_config(pkg, dep)}
+    synced = sync_game_config(pkg, dep)
+    if isinstance(dep.get("configuration"), dict):
+        applied = dep["configuration"]
+        settings = applied.get("settings") or {}
+        for key, value in (args.get("settings") or {}).items():
+            if key in settings:
+                number = float(value)
+                # keep the recorded type (the PC's fingerprint uses it); an int setting given 1.5 stays 1.5
+                settings[key] = number if isinstance(settings[key], float) or not number.is_integer() \
+                    else int(number)
+        dep["configuration_fp"] = hashlib.sha256(json.dumps(applied, sort_keys=True).encode()).hexdigest()[:32]
+        write_deployment(pkg, dep)
+    return {"settings": current, "controller_models": models, "config_sync": synced}
 
 
 TITLE_MAX = 128
@@ -5043,6 +5403,26 @@ def clean_title(title):
     return text[:TITLE_MAX]
 
 
+def cmd_record_artwork(args):
+    """Record artwork only after verifying the files actually uploaded to the game's anchor."""
+    pkg = check_pkg(args["package"])
+    dep = deployment(pkg)
+    if not dep:
+        raise AgentError(f"{pkg} is not installed")
+    manifest = args.get("manifest") or {}
+    root = os.path.join(ANCHORS, pkg, "artwork")
+    for name, digest in manifest.items():
+        if (not re.fullmatch(r"(?:portrait|landscape|hero|logo|icon)\.[a-zA-Z0-9]+|\.icon-source", name)
+                or not re.fullmatch(r"[a-f0-9]{64}", str(digest))):
+            raise AgentError("invalid artwork manifest")
+        path = os.path.join(root, name)
+        if not os.path.isfile(path) or sha256_file(path) != digest:
+            raise AgentError(f"artwork missing or checksum mismatch: {name}")
+    dep["artwork_manifest"] = manifest
+    write_deployment(pkg, dep)
+    return {"verified": True}
+
+
 def cmd_rename(args):
     """Rename an installed game (agent v77): deployment.json's title is what its Steam shortcut shows. The shortcut
     keeps its appid (upsert_shortcut matches by Exe, deployment.json keeps the appid), so Play, its grid art, launch
@@ -5095,6 +5475,7 @@ def cmd_uninstall(args):
         remove_empty_drive_dir(base)
     if linux:
         remove_desktop_entries(pkg)
+    remove_lepton_path(pkg)
     anchor = os.path.join(ANCHORS, pkg)
     removed_sc = False
     if args.get("remove_shortcut") and steam_users():
@@ -5181,7 +5562,7 @@ def rebase_launcher(dep, anchor, new):
     kind = dep.get("kind", "quest")
     launcher = dep.get("launcher")
     if kind == "quest":
-        text, n = re.subn(r"^app_dir=.*$", lambda m: "app_dir=" + shlex.quote(new), text, count=1, flags=re.M)
+        text, n = set_app_dir(text, new, pkg)
         if not n:
             raise AgentError("launch.sh has no app_dir line; reinstall the game once, then move it")
     elif kind == "linux" and launcher is not None:
@@ -6604,6 +6985,10 @@ MON_CRITICAL = ("steam", "steamwebhelper", "reaper", "vrserver", "vrcompositor",
 # processes whose command line can name a game (only these are read: cmdlines of ~500 processes cost too much)
 MON_ROOT_COMMS = ("conmon", "launch.sh", "reaper", "bash", "sh")
 MON_ROOT_PREFIXES = ("python", "proton", "pv-", "wine", "steam-runtime")
+AGENT_FILES = {os.path.abspath(__file__), os.path.realpath(__file__)}
+STEAM_GAME = "steam:"  # monitor: a game Steam started that FramePort didn't install ("steam:<appid>", e.g. a Lepton
+# game from Steam's store); its title comes from the appmanifest
+REAPER_APPID = re.compile(r"\bAppId=(\d+)")
 MON_GROUPS = (  # (group, comm prefixes), first match wins; games are found by their process tree
     ("steamvr", ("vr", "XRService", "V4L2Cam", "eyetracking", "proxmicmute", "systemlayer")),
     ("steam", ("steam", "reaper", "fossilize")),
@@ -6935,6 +7320,7 @@ class Monitor:
         self.logs = {}      # launch.log path -> [offset, fps, avg ms, time of the line]
         self.deps = []
         self.deps_at = -1e9
+        self.steam_titles = {}
         self.tick = 0
         self.last = None    # time of the previous sample
         self.disk_at = -1e9
@@ -7035,10 +7421,16 @@ class Monitor:
                     m = re.search(r"lepton-steamlaunch-(\d+)", cmd)
                     if m and m.group(1) in by_appid:
                         root = (by_appid[m.group(1)]["package"], "container")
-                else:
+                elif not any(a in cmd for a in AGENT_FILES):
+                    # the agent's own workers name a game's launch.sh too (uninstall's shortcut removal while Steam
+                    # restarts): they aren't the game (helpers launch.sh starts still count, as its children)
                     pkg = next((k for path, k in anchors if path in cmd), None) or \
                         next((k for base, k in bases if base in cmd), None)
                     root = (pkg, "launcher") if pkg else None
+                    m = REAPER_APPID.search(cmd) if comm == "reaper" and not pkg else None
+                    # any other game Steam runs (its reaper); not SteamVR itself, not a devkit entry of ours
+                    if m and m.group(1) not in by_appid and m.group(1) != STEAMVR_APPID and "/devkit-game/" not in cmd:
+                        root = (STEAM_GAME + m.group(1), "steam")
                 self.root_cache[key] = root
             if self.root_cache[key]:
                 roots[pid] = self.root_cache[key]
@@ -7116,7 +7508,7 @@ class Monitor:
         deps = {d["package"]: d for d in self.deployments(now)}
         out = []
         for pkg in sorted({v[0] for v in self.roots.values()}):
-            d = deps.get(pkg) or {}
+            d = deps.get(pkg) or (self.steam_game(pkg[len(STEAM_GAME):]) if pkg.startswith(STEAM_GAME) else {})
             pids = [p["pid"] for p in self.procs if p["game"] == pkg]
             cpu = sum(p["cpu"] for p in self.procs if p["game"] == pkg)
             rss = sum(p["rss"] for p in self.procs if p["game"] == pkg)
@@ -7136,10 +7528,25 @@ class Monitor:
                         "appid": d.get("appid"), "elapsed": max(ages) if ages else None,
                         "cpu": round(max(cpu, 0.0), 1), "mem": mem if mem is not None else rss,
                         "gpu": round(sum(self.gpu_pct.get(p, 0.0) for p in pids), 1),
-                        "fps": fps, "frame_ms": ms, "processes": len(pids)})
+                        "fps": fps, "frame_ms": ms, "processes": len(pids), "overlay": is_overlay(d)})
+        # the game in front first: overlay apps (they run next to games) last, then the most recently started
+        out.sort(key=lambda g: (g["overlay"], g["elapsed"] is None, g["elapsed"] or 0))
         self.games = out
         return out
 
+    def steam_game(self, appid):
+        """{title, kind, appid} of a Steam game FramePort didn't install (cached: appmanifest/shortcuts reads)."""
+        if appid not in self.steam_titles:
+            app = find_app_id(appid)
+            name = (app or {}).get("name")
+            if not name:
+                for user in steam_users():
+                    name = shortcut_names(user).get(appid)
+                    if name:
+                        break
+            self.steam_titles[appid] = name or f"App {appid}"
+        return {"title": self.steam_titles[appid], "kind": "steam", "appid": appid}
+
     def filtered(self, now=None):
         procs = self.procs
         span = (now - self.scan_prev) if now is not None and self.scan_prev is not None else 0.0
@@ -7285,8 +7692,29 @@ class Monitor:
         return {"ended": False, "pid": pid, "name": comm}
 
 
+def steam_app_running(appid):
+    """A Steam reaper runs this app id (a Steam game FramePort didn't install)."""
+    for name in os.listdir(PROC):
+        if name.isdigit() and _rd(f"{PROC}/{name}/comm").strip() == "reaper" and \
+                re.search(rf"\bAppId={appid}\b", _rd(f"{PROC}/{name}/cmdline").replace("\0", " ")):
+            return True
+    return False
+
+
 def monitor_end_game(pkg, wait=6.0):
-    """Steam's Exit game for a FramePort game (so Steam's session ends cleanly), then cmd_stop if it still runs."""
+    """Steam's Exit game for a FramePort game (so Steam's session ends cleanly), then cmd_stop if it still runs.
+    A Steam game FramePort didn't install ("steam:<appid>"): Steam's Exit game only."""
+    if str(pkg).startswith(STEAM_GAME):
+        appid = str(pkg)[len(STEAM_GAME):]
+        if not appid.isdigit():
+            raise AgentError(f"bad Steam app id {appid!r}")
+        if not steam_app_running(appid):
+            return {"ended": True, "via": None, "package": pkg, "note": "not running"}
+        steam_js(f"SteamClient.Apps.TerminateApp('{appid}', false)")
+        end = time.monotonic() + wait
+        while time.monotonic() < end and steam_app_running(appid):
+            time.sleep(0.5)
+        return {"ended": not steam_app_running(appid), "via": "steam", "package": pkg}
     pkg = check_pkg(pkg)
     dep = deployment(pkg)
     if not dep:
@@ -7428,6 +7856,11 @@ def main():
     if len(sys.argv) >= 5 and sys.argv[1] == "_logcat_keeper":
         logcat_keeper(sys.argv[2], sys.argv[3], sys.argv[4])
         return 0
+    if len(sys.argv) >= 4 and sys.argv[1] == "_gamepad_links":
+        gamepad_links(sys.argv[2], sys.argv[3])
+        return 0
+    if len(sys.argv) >= 5 and sys.argv[1] == "_restart_requested":
+        return 0 if restart_requested(sys.argv[2], sys.argv[3], sys.argv[4]) else 1
     if len(sys.argv) >= 4 and sys.argv[1] == "_dashboard_worker":
         dashboard_worker(sys.argv[2], sys.argv[3])
         return 0

artifacts/SHA256SUMS

@@ -1,22 +1,30 @@
+1a4dce5c4a6d0dfc5f20e55ac29e70c73cc2cc124c21ca6a7e1b316e6afb1c79  ./arm64-v8a/libVkLayer_fdm_darken.so
 5becb96ee86fbda0ce98c0e0fd064f8ba092314aceaa400e3dcc785705dc3c23  ./arm64-v8a/libVkLayer_fp_shaderfix.so
-e7554c6343ee2989b0a273ee6230e65c25bfe6499eefd00de19f5f0fee58754f  ./arm64-v8a/libfp_langpack.so
+fbc3b0238462d976d234fee6740db92b873c85d6bb22a6b01428e64e9058ed83  ./arm64-v8a/liba32bridge.so
+c9c3da5cac224c38e2210b781bd12b7f97e02bd6b0ebb0ef85543e4ea4b76671  ./arm64-v8a/liba32rt.so
+18d8d917e83a6d87008f41908eb478dff635e798844e125abd1e8a5cf31805e2  ./arm64-v8a/liba32stub.so
+d6337034fb0bdcca7ef9b7063d85b7586b8508b63b435959e8fffaba0691091c  ./arm64-v8a/libfp_langpack.so
+69102b128e00fa1809489a7308e09c1505f563bf7091bbdd3fe5a58e4cc96c2c  ./arm64-v8a/libfp_luajit.so
 321da502e0f8f46f0880aad39fe6b84bdef88f925164568814cf704a1b31a577  ./arm64-v8a/libfp_ovrp.so
 40defdaddcda53bd2649eb48076fae1622bfc2bfc88e9e03c94fc8b45af2a4f2  ./arm64-v8a/libfp_ovrtrace.so
+0167c2fde5dfde62897f9d85afc4fc8e97784e988b5b8df6cea8c407240b3424  ./arm64-v8a/libfp_tkeys.so
 e8c0965c188665a4e565e4a3af983ef1866d1cf9225665cc90d8df286bc96ef3  ./arm64-v8a/libfp_vk.so
 383054f8b3b41dde76d062c71856cd3163655e50009c08454bc1793f393ead65  ./arm64-v8a/libfpg.so
 5432674a59d02f411cd853a5dc57e3fa547d1ac518f25bf433fc54c43677177a  ./arm64-v8a/libfpglmv.so
 8a8f6b1da8952cb3933a5b53558424a5fc56043b2527a16bb6dd62a00d2de01a  ./arm64-v8a/libframe_xrshim.so
 19ba5ed3c4b780f5ae46251f6958f552acfc5f13c8bb39f995579593fa8990c6  ./arm64-v8a/libglshim.so
-449e13bbe58de6718d4e530177924e09552a95d748a082739899144e2cb3ccf3  ./arm64-v8a/libopenxr_loader_generic.so
+51f5e0c5b3d3556baab27ece2936257782d6b590183ae59601cc6d8158c96ee2  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
-1d83eb94ec1df44f29a5f525dce4d5b608dbbb13a9c7a5efeb80a4b1dc54a721  ./arm64-v8a/libvrapi.so
-47f736dfeffce6aa56be2fc049c2d11b87b0d1f7389db7ee1737fcded9457811  ./armeabi-v7a/libopenxr_loader_generic.so
+a4ed80ae45ca90758239f152ea5a2e8c127d491e1e697ea5680db6fd7f72db07  ./arm64-v8a/libvrapi.so
+a4ed80ae45ca90758239f152ea5a2e8c127d491e1e697ea5680db6fd7f72db07  ./arm64-v8a/libvrapi_foveation.so
+6927f100536283a8c26b784af73ee400140dd910e9294e4a9d55f855547ffaf2  ./armeabi-v7a/libopenxr_loader_generic.so
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 b634ab5640e258563c536e658cad87080553df6f34f62269a21d554844e58bfe  ./hevc/COPYING.FFmpeg
 141de01f0d40b97d4f9a720db5ab8ea442f6aa35db5272048899292884994a1c  ./hevc/libstagefrighthw.so
 4516971bbb2b635e19b14d2d37b9353962876f7de02043e7457327052c1fcbc0  ./hevc/manifest.json
 46c3dcad2c43cc30bea3b3680b362ed84a99c15d60714bbbbb422c80ecf90405  ./hevc/media_codecs_frameport.xml
 529ea35d5d82474afe9e09ad1216d269317f56dd24a05fb100fced52b7b4dbca  ./hevc/podman.py.txt
+6cda3076a8c09b31bb1f90da614ea89e7ee194589626eeac613e522849604e47  ./licenses/LuaJIT.txt
 1aa733117cf57ccff7cf23f0425dbfd73b0332a3ef1c905ceeca0ccd0449c4e0  ./linux-arm64/XR_APILAYER_FRAMEPORT_timefix.json
 28c2430a02bbd8902c5bfb9562c6fd0e318654f9e05c095bfeb94b0450ab1b07  ./linux-arm64/libxr_frameport_timefix.so
 b10b3a5c10c3339fc63fd9f6cb4d01ea29be11a863d0ebad1389ea69fd471940  ./linux-arm64-bin/fp_venc

artifacts/licenses/LuaJIT.txt

@@ -0,0 +1,56 @@
+===============================================================================
+LuaJIT -- a Just-In-Time Compiler for Lua. https://luajit.org/
+
+Copyright (C) 2005-2026 Mike Pall. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+[ MIT license: https://www.opensource.org/licenses/mit-license.php ]
+
+===============================================================================
+[ LuaJIT includes code from Lua 5.1/5.2, which has this license statement: ]
+
+Copyright (C) 1994-2012 Lua.org, PUC-Rio.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+===============================================================================
+[ LuaJIT includes code from dlmalloc, which has this license statement: ]
+
+This is a version (aka dlmalloc) of malloc/free/realloc written by
+Doug Lea and released to the public domain, as explained at
+https://creativecommons.org/licenses/publicdomain
+
+===============================================================================

catalog/games/com.Aldin.WotW.yaml

@@ -10,12 +10,14 @@ frame:
 - frame.unity_text_input
 device:
 - device.text_input_window
+adapter:
+  haptic_fix: 1
 verified:
-  date: '2026-10-05'
-  known_good_sha256: 522cfebf954e1cab6054798479b0b32c5ba9e38cca83dd98db2ac0f7e3c0802a
-  app: 0.9.1
+  date: '2026-10-11'
+  known_good_sha256: 0e55a80ed420395b7eaf8075230fad1fae288f6c25d2ce8cc6aa49899e9b7596
+  app: 1.0.4
   overport_cli: 1.2.5
-  frame_build: '20260922.6101926'
-  agent: 48
-  issue: 44
-source_hint: WotW
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 211
+source_hint: Waltz

catalog/games/com.Armature.SportsScramble.yaml

@@ -4,14 +4,19 @@ tested_version: '1.0'
 source_hint: Sports Scramble
 engine: Unreal
 xr: VrApi
-status: unsupported
-notes: 32-bit only; the Frame has no AArch32.
-details: 32-bit (armeabi-v7a) only; the Frame has no AArch32.
-alt_overport:
-- patch_remove_unreal_force_quit
+status: works
+notes: 32-bit only (armeabi-v7a), runs through FramePort's 32-bit bridge (experimental). Both controllers work as
+  Touch controllers. The first start shows a one-time "optimizing" screen (a bit jittery) and then starts the game
+  again by itself.
+details: 'Unreal Engine 4 NativeActivity with OVRPlugin + VrApi, GLES, OBB. The bridge needed AAsset_getBuffer
+  (copied into guest memory), AKeyEvent_getFlags and the remaining AConfiguration getters. A Santa Cruz (early
+  Quest) build: it requires 6DoF head tracking, so the bridge passes both Frame controllers through as Touch
+  controllers (assets/fp_a32_headset.txt) instead of the Gear VR remote. Unreal restarts the app after its
+  first-run shader precompile; the launcher starts Lepton again for it (agent 86). Plays in the headset (owner,
+  2026-10-13).'
+frame:
+- frame.a32_bridge
 pcvr_alternative: Rift only; not on the Revive compatibility list.
 verified:
-  date: '2026-09-28'
-  overport_cli: 1.2.3
-  overport_runtime: 3.4.3-23204ea
-  known_good_sha256: e2e6788da99e2a38ea8f1e83e997ab44fed5492ce117d99ee3d376e6faeb0de4
+  date: '2026-10-13'
+min_app: 0.12.1

catalog/games/com.GenderGames.Ladder.yaml

@@ -0,0 +1,21 @@
+package: com.GenderGames.Ladder
+title: Ladder
+status: works
+tested_version: Release
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-12'
+  known_good_sha256: 7d23692149d40fe469dbf2e13446ceeb94a8a32807e09ddad7731158de9be0a2
+  app: 1.0.4
+  overport_cli: 1.2.5
+  issue: 243
+source_hint: Ladder

catalog/games/com.HarmonixMusic.DCVRQuest.yaml

@@ -0,0 +1,23 @@
+package: com.HarmonixMusic.DCVRQuest
+title: Dance Central
+status: works
+tested_version: 1.2.2
+engine: Unreal
+xr: VrApi
+alt_overport:
+- patch_remove_unreal_force_quit
+frame:
+- frame.unreal_skip_obb_check
+- frame.hw_video_decode
+adapter:
+  haptic_fix: 1
+  pose_time_fix: 1
+verified:
+  date: '2026-10-12'
+  known_good_sha256: cbaf2eb594cb25d6a345b50612f9e7ca3e2b2f05abaa072632e8fc0d91277c61
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 228
+source_hint: com.HarmonixMusic.DCVRQuest

catalog/games/com.ILMxLAB.VaderImmortal.ep1.yaml

@@ -13,8 +13,9 @@ details: Unreal Engine 4 (GLES). Found and verified in gameplay on a Frame by Kl
   the captured modules are from Lepton 2.8.14 and stop matching if a Frame update changes the driver's output -
   the layer logs that). OVRPlugin asks for poses at its own clock (pose_time_fix). Unreal's Oculus input animates the
   thumbs from near-touch, which the Frame never reports (frame.unreal_thumb_touch reads the touches instead; binding
-  the proximity to the touch inputs in FrameBridge didn't reach the game). The Frame's SteamVR runtime
-  leaks about 20 MB a second while the game runs (reported to Valve).
+  the proximity to the touch inputs in FrameBridge didn't reach the game). The game leaves GL errors
+  pending; the runtime's GL check took one as its own failure and then allocated a command buffer every frame
+  (~20 MB a second until the frame rate collapsed). gl_error_clear clears them first (GitHub #285).
 tested_version: 1.1.1+667256.cl.387770
 engine: Unreal
 xr: VrApi
@@ -27,10 +28,11 @@ frame:
 - frame.zink_shader_fix
 adapter:
   pose_time_fix: 1
+  gl_error_clear: 1
   zink_shader_fix: 12016:b2919629761ad268e0b21c72ac8520f81b76e72c3adc26897f97eae9a3e70a66:3092:0x0003003e,166,82,0x0003003e,177,82,0x0003003e,183,82,0x0003003e,189,82,0x0003003e,256,82,0x0003003e,266,82,0x0003003e,272,82,0x0003003e,278,82,0x0003003e,318,82,0x0003003e,328,82,0x0003003e,334,82,0x0003003e,340,82;11436:6f18be49f2aaa2452f962eb16f7af744c5c22a7b25f37ce681e0d6399e35a869:2932:0x0003003e,164,80,0x0003003e,175,80,0x0003003e,181,80,0x0003003e,187,80,0x0003003e,254,80,0x0003003e,264,80,0x0003003e,270,80,0x0003003e,276,80,0x0003003e,316,80,0x0003003e,326,80,0x0003003e,332,80,0x0003003e,338,80
 verified:
   date: '2026-10-09'
   issue: 49
-updated: '2026-10-09'
+updated: '2026-10-14'
 min_app: 0.12.1
 source_hint: Vader Immortal- Episode I

catalog/games/com.ILMxLAB.VaderImmortal.ep2.yaml

@@ -18,7 +18,9 @@ frame:
 - frame.unreal_thumb_touch
 adapter:
   pose_time_fix: 1
+  gl_error_clear: 1
 verified:
   date: '2026-10-09'
+updated: '2026-10-14'
 min_app: 0.12.1
 source_hint: Vader Immortal- Episode II

catalog/games/com.ILMxLAB.VaderImmortal.ep3.yaml

@@ -18,7 +18,9 @@ frame:
 - frame.unreal_thumb_touch
 adapter:
   pose_time_fix: 1
+  gl_error_clear: 1
 verified:
   date: '2026-10-09'
+updated: '2026-10-14'
 min_app: 0.12.1
 source_hint: Vader Immortal- Episode III

catalog/games/com.InnoverseLtd.FrenzyVR.yaml

@@ -0,0 +1,20 @@
+package: com.InnoverseLtd.FrenzyVR
+title: FrenzyVR
+status: works
+notes: Works, runs good
+tested_version: '107'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-11'
+  known_good_sha256: 0d87e78dcbe1c705af0d01cda8eabbea514849f7403e5904f0ef49b5cf0653fb
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 216
+source_hint: Frenzy VR

catalog/games/com.LocoMotionDevs.Superfly.yaml

@@ -0,0 +1,22 @@
+package: com.LocoMotionDevs.Superfly
+title: Superfly
+status: works
+notes: Works, take a bit to launch but works
+tested_version: 1.3.3
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-11'
+  known_good_sha256: e180b6c58b80c1c2d0cc49e75d645a41d3d4bc63ed7ffe1e6f91eac51e486a17
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 217
+source_hint: Superfly

catalog/games/com.NiVision.RacketPinball.yaml

@@ -0,0 +1,19 @@
+package: com.NiVision.RacketPinball
+title: RacketPinball
+status: works
+tested_version: '2.06'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-13'
+  known_good_sha256: 80e850f81c24112e8c35a560a333846163a3e783da391290db7663b9015ca58f
+  app: 1.0.4
+  overport_cli: 1.2.5
+  issue: 262
+source_hint: RacketPinball

catalog/games/com.PubTest.PubTest.yaml

@@ -0,0 +1,20 @@
+package: com.PubTest.PubTest
+title: Drunkn Bar Fight 2 - Early Access
+status: works
+notes: Game launches and plays fine
+tested_version: '0.515'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-11'
+  known_good_sha256: f340b5ba70ee9368ead6bfe2c287eda6c5686280ddb8e12b8c9a8d720326de36
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 218
+source_hint: Drunkn Bar Fight 2 - Early Access

catalog/games/com.StatusPro.NFLProEra2.yaml

@@ -0,0 +1,21 @@
+package: com.StatusPro.NFLProEra2
+title: NFL PRO ERA II
+status: works
+tested_version: 2.4.0
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-11'
+  known_good_sha256: caf2e8f148ca4929ba5e73112fa7e0958c00d7ee0c5f28926c3f39714db6c923
+  app: 1.0.4
+  overport_cli: 1.2.3
+  issue: 226
+source_hint: com.StatusPro.NFLProEra2

catalog/games/com.TinyBuild.killitwithfirevr.yaml

@@ -0,0 +1,23 @@
+package: com.TinyBuild.killitwithfirevr
+title: Kill It With Fire VR
+status: works
+notes: Works
+tested_version: 1.0.5.4208
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+frame:
+- frame.unreal_skip_obb_check
+- frame.hw_video_decode
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-11'
+  known_good_sha256: fcadbdaf3255e2909edf763d0c61fb55808ba448d4f277e91ba37b0a0ff9f497
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 219
+source_hint: Kill It With Fire VR

catalog/games/com.Ubisoft.ACNexusVR.yaml

@@ -4,9 +4,9 @@ tested_version: MAIN.450412.207706.final
 source_hint: Assassins Creed Nexus VR
 engine: Unity
 xr: OpenXR
-status: issues
-notes: Some launch warning text is still upside down; the rest of the UI is fixed by flip emulation. Ubisoft login
-  may not work.
+status: works
+notes: FrameBridge turns its upside-down UI panels upright (flip emulation, in place since FramePort 1.1.2). Ubisoft
+  login may not work.
 details: Ubisoft online login may not work. Data folder holds raw assets (start0..2, .climb, bundles), not .obb
   files; install to obb as-is.
 overport_extra:
@@ -17,3 +17,6 @@ verified:
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 89644a12bf8df956fa3d3a9a40540ba9e1fb62f63494714a05c9f05984383ac8
   no_appsw_90: '2026-10-02, OVRPort 1.2.5 (owner: 90 Hz felt better than 72 Hz; same known issues)'
+  flip_in_place: '2026-10-14, owner in the headset: launch warnings and tutorial pop-ups upright (GitHub #138)'
+updated: '2026-10-14'
+min_app: 1.1.2

catalog/games/com.WfelisCorp.MunkrFunkrTheLegacyDays.yaml

@@ -0,0 +1,21 @@
+package: com.WfelisCorp.MunkrFunkrTheLegacyDays
+title: Munkr Funkr (The Legacy Days)
+status: works
+tested_version: '2'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-12'
+  known_good_sha256: 94079c1a2a802322f907058964c4ebbb22edba1dc0f3ec26e3c121ed9d8b0379
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 241
+source_hint: Munkrfunkr

catalog/games/com.YourCompany.RoboRecall.yaml

@@ -5,6 +5,8 @@ notes: Needed the LAUNCHER category fix.
 details: Source APK is a community 'patch+savefix+90Hz' build. Shares Vader Immortal's Unreal 4 Oculus input (GitHub
   49) - thumbs follow the touches (frame.unreal_thumb_touch) and controller poses are located at the right time
   (pose_time_fix); added 2026-10-09 from Vader's headset results, not yet checked in this game.
+  sync_guard added 2026-10-11 for a vrclient xrSyncActions crash on the loading splash after the intro (GitHub
+  #188; the same runtime race as Myst).
 tested_version: '1.0'
 engine: Unreal
 xr: VrApi
@@ -14,10 +16,11 @@ frame:
 - frame.unreal_thumb_touch
 adapter:
   pose_time_fix: 1
+  sync_guard: 1
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 4ce6e3563da131e288645f4b62a634ac98043e55bc42b7c0ad5f461207d5f53c
-updated: '2026-10-09'
+updated: '2026-10-11'
 source_hint: Robo Recall- Unplugged

catalog/games/com.arkio.arkio.yaml

@@ -0,0 +1,25 @@
+package: com.arkio.arkio
+title: Arkio
+status: works
+notes: The quest version allows for passthrough mode
+tested_version: 2.3.1
+engine: Unity
+xr: OpenXR
+overport_extra:
+- patch_force_passthrough
+frame:
+- frame.meta_permissions
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  scene_emul: 1
+verified:
+  date: '2026-10-13'
+  known_good_sha256: e17f9b2dc56cb49b4469d81f2e075ca5953f73152804ff1a00fba0931048e103
+  app: 1.1.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 85
+  issue: 266
+source_hint: com.arkio.arkio

catalog/games/com.beatgames.beatsaber.yaml

@@ -2,19 +2,22 @@ package: com.beatgames.beatsaber
 title: Beat Saber
 status: works
 notes: Purchased DLC isn't detected (ownership comes from Meta's servers).
-tested_version: 1.40.8_7379
+tested_version: 1.45.2_28848
 engine: Unity
 xr: OpenXR
 frame:
 - frame.unity_text_input
 device:
 - device.text_input_window
+adapter:
+  haptic_fix: 1
+  pose_time_fix: 1
 verified:
-  date: '2026-10-03'
-  known_good_sha256: ee720e040931f2547f7611e58ec5ad72d86e800dd4cf3135f576019683f2f359
-  app: 0.6.1
+  date: '2026-10-11'
+  known_good_sha256: b7976f36d39b22eb0fd9c8eb6cce204125430cd2a3e2bfab8ba5d1f7c86f0ac6
+  app: 1.0.4
   overport_cli: 1.2.5
-  frame_build: '20260930.6234839'
-  agent: 33
-  issue: 6
-source_hint: Beat Saber
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 210
+source_hint: beat-saber

catalog/games/com.camouflaj.manta.yaml

@@ -16,11 +16,12 @@ frame:
 adapter:
   sync_guard: 1
   surface_native: 1
+  fade_quad: 1
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 796d1cab08f614d72c50d9702974c719c0908f5de91183cfe02d1fd5eb09551a
-updated: '2026-10-10'
-min_app: 0.12.1
+updated: '2026-10-13'
+min_app: 1.1.0
 source_hint: Batman- Arkham Shadow

catalog/games/com.camouflaj.salmon.yaml

@@ -8,6 +8,8 @@ frame:
 - frame.unity_text_input
 device:
 - device.text_input_window
+adapter:
+  fade_quad: 1
 verified:
   date: '2026-10-05'
   known_good_sha256: 41e0ab90f622afd50accb0b6e2553520d30a6cc82e5ab4cbb2341b48f7316a71
@@ -15,3 +17,5 @@ verified:
   overport_cli: 1.2.5
   issue: 47
 source_hint: Marvel's Iron Man VR
+updated: '2026-10-13'
+min_app: 1.1.0

catalog/games/com.ccpgames.gunjack.yaml

@@ -0,0 +1,20 @@
+package: com.ccpgames.gunjack
+title: Gunjack
+status: works
+notes: 'Gear VR game (32-bit only), runs through FramePort''s 32-bit bridge (experimental). Controls (right
+  controller): trigger = fire (hold the touchpad), A = tap, stick down = reload (swipe back), stick up = special
+  weapon (swipe forward), B = back.'
+details: 'Unreal Engine 4.10 NativeActivity, VrApi, GLES, OBB inside the APK (assets/main.obb.png). The bridge answers
+  the game''s APK signature check with the original APK''s certificate and keeps the GLES session when Unreal leaves
+  and re-enters VR after loading. Controller input goes into the game''s AInputQueue as Gear VR touchpad events.
+  Runs in the headset (owner, 2026-10-12).'
+tested_version: 1.4.1
+engine: Unreal
+xr: VrApi
+headset: gearvr
+frame:
+- frame.a32_bridge
+verified:
+  date: '2026-10-12'
+min_app: 0.12.1
+source_hint: Gunjack (Gear VR)

catalog/games/com.coatsink.nexus.yaml

@@ -4,13 +4,16 @@ tested_version: '1.4'
 source_hint: Shadow Point
 engine: Unity
 xr: VrApi
-status: unsupported
-notes: 32-bit only; the Frame has no AArch32.
-details: 32-bit (armeabi-v7a) only; the Frame has no AArch32. 64-bit conversion was researched and dropped (IL2CPP
-  + FMOD + custom rasterizer).
+status: works
+notes: 32-bit only (armeabi-v7a), runs through FramePort's 32-bit bridge (experimental). Plays in the headset.
+details: 'Unity with OVRPlugin + VrApi, GLES. Needed the bridge''s vrapi_GetTrackingTransform/SetTrackingTransform
+  (the game sets its floor level through them; without them the player stood below the floor). Plays in the headset
+  (owner, 2026-10-14).'
+frame:
+- frame.a32_bridge
+device:
+- device.text_input_window
 pcvr_alternative: Rift version via Revive + SteamVR.
 verified:
-  date: '2026-09-28'
-  overport_cli: 1.2.3
-  overport_runtime: 3.4.3-23204ea
-  known_good_sha256: ea0c0d09d2c3d8da04d165732ead64875fef7573a5739608de0de9c93654007e
+  date: '2026-10-14'
+min_app: 1.1.2

catalog/games/com.edde746.plezy.yaml

@@ -0,0 +1,20 @@
+package: com.edde746.plezy
+title: Plezy
+status: issues
+notes: Some videos play with strong artifacts and wrong colours; the cause is unknown, possibly hardware video decoding.
+    Otherwise works.
+tested_version: 2.22.0
+engine: Other
+xr: '?'
+frame:
+- frame.hw_video_decode
+as_is: true
+verified:
+  date: '2026-10-13'
+  known_good_sha256: 893ae7c01d3d7688b27cbf4e7fc1260fb617614baeaf378fe5ca0af41febc92f
+  app: 1.1.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 85
+  issue: 270
+source_hint: plezy

catalog/games/com.fallen.affected.yaml

@@ -0,0 +1,21 @@
+package: com.fallen.affected
+title: 'AFFECTED: The Manor'
+status: issues
+notes: 'Gear VR game (32-bit only), runs through FramePort''s 32-bit bridge (experimental). Controls:
+  left stick = walk and strafe (the touchpad), right stick sideways = turn, stick press or A = touchpad click, right
+  trigger = trigger, B = back.'
+details: 'Unity 5.6 + Mono, VrApi 1.0.4, GLES. The bridge translates its 32-bit libraries and VrApi to the 64-bit VrApi
+  bridge on OpenXR. Picture and sound confirmed in the headset by the owner (2026-10-10); the controller mapping was
+  reworked afterwards and is not yet confirmed.'
+tested_version: '1.52'
+engine: Unity
+xr: VrApi
+headset: gearvr
+frame:
+- frame.a32_bridge
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-10'
+min_app: 0.12.1
+source_hint: AFFECTED The Manor (Gear VR)

catalog/games/com.fulldivegames.majorasmaskvr.yaml

@@ -0,0 +1,20 @@
+package: com.fulldivegames.majorasmaskvr
+title: Majora's Mask VR
+status: issues
+notes: Audio on the file select screen sounds crunchy. Controls may need rebinding in the game. Quest build from https://github.com/fulldivegames/Majoras-Mask-VR.
+tested_version: '0.36'
+engine: Other
+xr: OpenXR
+frame:
+- frame.sdl_clipboard
+adapter:
+  refresh_rate: 144.0
+verified:
+  date: '2026-10-13'
+  known_good_sha256: 220096c70fb515ec7b8db1cc7a9075836b4d09f7df63026908af3c30e9fdb7e5
+  app: 1.1.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 85
+  issue: 268
+source_hint: MMVR-Quest-0.36

catalog/games/com.greensky.swarm2.yaml

@@ -0,0 +1,23 @@
+package: com.greensky.swarm2
+title: Swarm 2
+status: issues
+notes: MSAA creates visible seams around edge geometry and also the skybox edge
+tested_version: '8472'
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-12'
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 79
+  issue: 224
+source_hint: SWARM 2

catalog/games/com.halfbrick.fruitninjavr.yaml

@@ -0,0 +1,25 @@
+package: com.halfbrick.fruitninjavr
+title: Fruit Ninja
+status: works
+notes: Works, launches and plays
+tested_version: 1.7.3.696775
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.hw_video_decode
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-11'
+  known_good_sha256: 5afd1383c6f4aab50425bea955202c74e1706a8a8ba4219689ef5b6e0c984318
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 220
+source_hint: Fruit Ninja

catalog/games/com.ilmxlab.tales.yaml

@@ -1,15 +1,22 @@
 package: com.ilmxlab.tales
 title: 'Star Wars: Tales from the Galaxy''s Edge'
-status: unknown
-notes: Not working yet - after the intro logos and a loading animation the picture goes black (GitHub issue 61).
-  Gets the controller fixes found for Vader Immortal (same studio) to test.
+status: works
+notes: >-
+  Headset tested for GitHub issue 61: full view, loading into gameplay, both eyes, controller input and sound
+  work with the splash bypass and multiview depth-size fix. Keep the main OBB and all three content/sound-bank PAKs.
 details: Unreal Engine 4 (GLES) by ILMxLAB, like Vader Immortal, but a different engine build - it has none of Vader's
   Quest-only branches (no GetQuestShaderPrecompilePercent or RPOC key map; it precompiles shaders through Unreal's
   own pipeline cache), so frame.unreal_quest_precompile/_keymap don't apply. Its seasons and Wwise banks are Meta
   platform asset files (frame.asset_files). Vader's OVRPlugin findings apply to it as well - poses asked for at
   OVRPlugin's own clock (pose_time_fix) and thumbs from near-touch, which the Frame never reports (frame.unreal_thumb_touch).
-  Ruled out for the black picture so far (see the diagnostics in issue 61) - asset-file paks, Valve's foveation,
-  GL errors; the game's own eye image reads back black.
+  Map travel stalls with the game thread waiting in FlushRenderingCommands and the render thread waiting in
+  FSplash::RenderFrame_RenderThread / ovrp_WaitToBeginFrame. frame.unreal_splash_bypass lets loading finish.
+  SideQuest backups with sibling apk/ and obb/ folders must include all three PAKs; old scans omitted them and
+  lost sound. The scanner and library refresh recover that layout. Eye clipping came from cached Android window
+  dimensions for the depth attachment (1920x1016 versus the 1728x1728 eye color texture).
+  frame.unreal_multiview_depth refreshes both cached dimensions from the current eye render size; multiview and
+  multisampling remain enabled. The two engine fixes check exported symbols, function sizes and instruction bytes
+  before changing one instruction each; unrecognized engine builds are left unchanged.
 tested_version: 1.1.9+734762.cl.439699
 engine: Unreal
 xr: VrApi
@@ -18,10 +25,12 @@ alt_overport:
 frame:
 - frame.asset_files
 - frame.unreal_thumb_touch
+- frame.unreal_splash_bypass
+- frame.unreal_multiview_depth
 adapter:
   pose_time_fix: 1
 verified:
   issue: 61
-updated: '2026-10-09'
-min_app: 0.12.1
+updated: '2026-10-12'
+min_app: 1.0.4
 source_hint: Star Wars- Tales from the Galaxys Edge

catalog/games/com.nDreams.Ghostbusters.yaml

@@ -0,0 +1,26 @@
+package: com.nDreams.Ghostbusters
+title: 'Ghostbusters: Rise of the Ghost Lord'
+status: works
+notes: 'Needs the game''s offline mode: it is built for online play, and without a profile the player name is a random
+    number. The flat loading screen floats in front of you instead of following your head, so assets can be seen loading
+    in behind it.'
+tested_version: 1.325635.prod.shipping
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+frame:
+- frame.unreal_ovrp_entrypoints
+- frame.hw_video_decode
+adapter:
+  haptic_fix: 1
+  scene_emul: 1
+verified:
+  date: '2026-10-14'
+  known_good_sha256: 7556a78c8772aed70c38fc4781677c0900e9dfd4be085a79c421a31323af7888
+  app: 1.1.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 85
+  issue: 279
+source_hint: GBRotgl

catalog/games/com.notdead.COMPOUNDQUEST.yaml

@@ -0,0 +1,23 @@
+package: com.notdead.COMPOUNDQUEST
+title: COMPOUND
+status: works
+tested_version: 1.0.12
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-13'
+  known_good_sha256: 5da7aac9863412daec7ba909dcfd2d5cfa6cb5d078150011c006165058cd76bd
+  app: 1.1.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 85
+  issue: 260
+source_hint: COMPOUND

catalog/games/com.othergate.doe.yaml

@@ -0,0 +1,24 @@
+package: com.othergate.doe
+title: Dungeons of Eternity
+status: issues
+notes: It can not connect to servers
+tested_version: '1.3'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.vivox_audio_route
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+  pose_time_fix: 1
+verified:
+  date: '2026-10-11'
+  known_good_sha256: 006a53b81988f1bb088ccb0847c9e4085ee89743ed6b4d5acf161abf99e30365
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 206
+source_hint: com.othergate.doe

catalog/games/com.owlchemylabs.jobsimulator.yaml

@@ -1,13 +1,12 @@
 package: com.owlchemylabs.jobsimulator
 title: Job Simulator
 status: works
+notes: 'Without Lepton''s Android window: with it, the hands froze after a few seconds (GitHub #193).'
 tested_version: 1.4.0.6515
 engine: Unity
 xr: OpenXR
-frame:
+frame_remove:
 - frame.unity_text_input
-device:
-- device.text_input_window
 verified:
   date: '2026-10-03'
   known_good_sha256: 64638d7f93bb93cc61f422a43a08bb0d35b9bb4b463e90a42da7002147f03d1b
@@ -16,4 +15,5 @@ verified:
   frame_build: '20260930.6234839'
   agent: 33
   issue: 11
+updated: '2026-10-11'
 source_hint: Job Simulator

catalog/games/com.owlchemylabs.vacationsimulator.yaml

@@ -1,14 +1,13 @@
 package: com.owlchemylabs.vacationsimulator
 title: Vacation Simulator
-status: issues
-notes: Controllers aren't tracked (reported; not yet diagnosed).
+status: works
+notes: 'Without Lepton''s Android window: with it (or after clicking it), the hands stayed on the floor (GitHub
+  #163).'
 tested_version: 1.3.0.40142
 engine: Unity
 xr: OpenXR
-frame:
+frame_remove:
 - frame.unity_text_input
-device:
-- device.text_input_window
 adapter:
   haptic_fix: 1
   refresh_rate: 90.0
@@ -20,4 +19,5 @@ verified:
   frame_build: '20261007.6125817'
   agent: 59
   issue: 163
+updated: '2026-10-11'
 source_hint: com.owlchemylabs.vacationsimulator

catalog/games/com.parkline.wander.yaml

@@ -1,12 +1,15 @@
 package: com.parkline.wander
 title: Wander
 status: works
-tested_version: '0.3569'
+notes: 0.3570 (Unity 6.5) runs out of thread keys at start without the thread-key pool (fix found by Klownicle,
+  GitHub #198).
+tested_version: '0.3570'
 engine: Unity
 xr: OpenXR
 frame:
 - frame.unity_text_input
 - frame.unity_runtime_msaa_off
+- frame.unity_tls_key_pool
 device:
 - device.text_input_window
 verified:
@@ -17,4 +20,5 @@ verified:
   frame_build: '20260930.6234839'
   agent: 35
   issue: 17
+updated: '2026-10-12'
 source_hint: Wander

catalog/games/com.polyarc.Moss2.yaml

@@ -0,0 +1,22 @@
+package: com.polyarc.Moss2
+title: 'Moss: Book II'
+status: works
+notes: Just played the very begining but controlls worked.  Did nothing other than install it.
+tested_version: 1.0.3.149619
+engine: Unreal
+xr: VrApi
+alt_overport:
+- patch_remove_unreal_force_quit
+frame:
+- frame.hw_video_decode
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-12'
+  known_good_sha256: 686db536ced97d8a151c82955174ec01d67987c466ecd326d3deb557d8c4fd1d
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 248
+source_hint: Moss- Book II

catalog/games/com.poncle.vampiresurvivorsvr.yaml

@@ -0,0 +1,21 @@
+package: com.poncle.vampiresurvivorsvr
+title: Vampire Survivors
+status: works
+tested_version: 1.0.717
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-12'
+  known_good_sha256: 42c3c18fd6b69a79d9e337d359aa9940428b9193a9ffc3ef987571be6aa6901a
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 234
+source_hint: Vampire Survivors

catalog/games/com.themunky.drunknbarfightQuest.yaml

@@ -0,0 +1,24 @@
+package: com.themunky.drunknbarfightQuest
+title: Drunkn Bar Fight
+status: works
+notes: Works
+tested_version: '11.00'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-11'
+  known_good_sha256: a66895bf0fde60a7ccd9bea6b8b1e922650cf1692fe26c1d08bee5b5c866b8b6
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 222
+source_hint: Drunkn Bar Fight

catalog/games/com.viewerready.totallybaseball.yaml

@@ -0,0 +1,23 @@
+package: com.viewerready.totallybaseball
+title: Totally Baseball
+status: works
+notes: Game Launches and works
+tested_version: '2.5886'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-11'
+  known_good_sha256: 80d53ee2c59cd1846e42a1c309bd8b0c365841d0aaea4092854fa01d2902a839
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 223
+source_hint: TOTALLY BASEBALL

catalog/games/com.vrmonkey.skyclimb.yaml

@@ -0,0 +1,23 @@
+package: com.vrmonkey.skyclimb
+title: MacacoVR
+status: issues
+notes: 2d loading screens are glitchy, otherwise main gameplay is fine
+tested_version: '1.1325'
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+frame:
+- frame.unreal_skip_obb_check
+- frame.hw_video_decode
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-12'
+  known_good_sha256: 78de47cf0200a6e8e06feeef4a02da0737393b5007e71ba8f62f01dfa93cec0a
+  app: 1.0.4
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 236
+source_hint: MacacoVR

catalog/games/gg.trs.grappa.yaml

@@ -4,14 +4,17 @@ tested_version: 1.0.479431
 source_hint: Journey of the Gods
 engine: Unreal
 xr: VrApi
-status: unsupported
-notes: 32-bit only; the Frame has no AArch32.
-details: 32-bit (armeabi-v7a) only; the Frame has no AArch32. UE4 cannot be rebuilt for arm64.
+status: works
+notes: 32-bit only (armeabi-v7a), runs through FramePort's 32-bit bridge (experimental). Plays in the headset.
+details: 'Unreal Engine 4 NativeActivity with OVRPlugin + VrApi, GLES. Needed DT_ANDROID_RELR relocations in the 32-bit
+  loader (it crashed at start) and the VrApi bridge''s frame pacing: the Frame''s runtime can return from
+  xrWaitFrame early, and this light game then ran at ~120 fps on a 90 Hz display, so the scene slid and snapped
+  back. Plays in the headset (owner, 2026-10-14).'
 alt_overport:
 - patch_remove_unreal_force_quit
+frame:
+- frame.a32_bridge
 pcvr_alternative: Rift (Meta PC) version via Revive + SteamVR.
 verified:
-  date: '2026-09-28'
-  overport_cli: 1.2.3
-  overport_runtime: 3.4.3-23204ea
-  known_good_sha256: e85141e3e9a8a3226f653d8ffbd21b44268101f3a207f56e657454a3639b3201
+  date: '2026-10-14'
+min_app: 1.1.2

catalog/games/net.mobilemischief.spunkydungeon.yaml

@@ -0,0 +1,21 @@
+package: net.mobilemischief.spunkydungeon
+title: Spunky Dungeon
+status: issues
+notes: 'Gear VR / Oculus Go game (32-bit only), runs through FramePort''s 32-bit bridge (experimental).
+  Controls: left stick = walk and strafe (the touchpad), right stick sideways = turn, stick press or A = touchpad
+  click, right trigger = trigger, B = back.'
+details: 'Unity 2019.2 + Mono, OVRPlugin 1.46 on VrApi 1.31, GLES, Meta Platform SDK (OVRPort''s 32-bit dispatcher).
+  Played in the headset by the owner (2026-10-10): picture at 72 fps, floor-level tracking and walking work; turning
+  without a stick press was added afterwards and is not yet confirmed.'
+tested_version: '1.4'
+engine: Unity
+xr: VrApi
+headset: gearvr
+frame:
+- frame.a32_bridge
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-10'
+min_app: 0.12.1
+source_hint: Spunky Dungeon

catalog/games/pl.idreams.zombirds.yaml

@@ -0,0 +1,24 @@
+package: pl.idreams.zombirds
+title: Shoot The Zombirds VR
+status: works
+tested_version: 1.0.2
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_oculus_check
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-13'
+  known_good_sha256: 2d06d1b6aac83d232e9f559c1cd3188642e7a34ef515605763ee7afa04730156
+  app: 1.1.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 85
+  issue: 259
+source_hint: Shoot The Zombirds

catalog/games/quest.eleven.forfunlabs.yaml

@@ -1,11 +1,16 @@
 package: quest.eleven.forfunlabs
 title: Eleven Table Tennis
-status: unsupported
-notes: Stops at the splash screen. The game needs Meta's online services after start, which aren't available on
-  the Frame.
+status: works
+notes: Works great for me, tried the tutorial and an online match. Quest 2 apk.
+tested_version: 0.436.37_2026.9.4.18.35.33.415
 engine: Unity
 xr: OpenXR
-pcvr_alternative: The PC VR (Rift) version works on the Frame through FramePort.
+adapter:
+  haptic_fix: 1
 verified:
-  date: '2026-10-10'
-  issue: 160
+  date: '2026-10-13'
+  known_good_sha256: f4d996db1c913639f8b981bf87834e053ee2d9267383da3c1a8372ba755e5ac8
+  app: 1.1.0
+  overport_cli: 1.2.5
+  issue: 267
+source_hint: quest.eleven.forfunlabs

catalog/games/xyz.TheAviary.Vermillion.yaml

@@ -0,0 +1,25 @@
+package: xyz.TheAviary.Vermillion
+title: Vermillion
+status: issues
+notes: Runs. The canvas used to hide the hand and brush while painting (the Frame draws the game's canvas layer in
+  front of everything); the recipe makes the game draw canvases in the scene instead (fix found by Klownicle, GitHub
+  #200). Not yet confirmed in the headset with this patch.
+tested_version: 1.7.2
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.vermillion_scene_canvas
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+  scene_emul: 1
+verified:
+  date: '2026-10-11'
+  app: 1.0.1
+  frame_build: '20261007.6125817'
+  agent: 79
+  issue: 200
+updated: '2026-10-12'
+source_hint: Vermillion - VR Painting

catalog/triage.yaml

@@ -6,6 +6,36 @@
 # with diagnostics. Launch tests and real play sessions (agent session_log, `frameport session`) are both matched.
 # Sources: every failure we hit porting 34 games to the Steam Frame (see docs/PLAYBOOK.md).
 signatures:
+  - id: meta-asset-status-error
+    pattern: 'Asset status error\s+\(code 100\)'
+    severity: error
+    diagnosis: A DLC manager reports a Meta asset-file status error after VR starts (e.g. PixelRipped 1995). The asset-file check failed; the log does not identify the native call or asset ID. Try the experimental asset-file bypass (empty list, installed status with no file path); this does not supply DLC and has not been verified in the game.
+    suggest: [frame.asset_files_stub]
+  - id: lua-lightuserdata-pointer
+    pattern: 'bad light userdata pointer'
+    severity: fatal
+    diagnosis: The Lua runtime rejected a pointer outside its supported address range. In the verified older xLua build, valid wider Frame pointers trigger this failure; a scoped compatible engine is available. For other builds, inspect the rejected pointer before assuming this cause.
+    suggest: [frame.luajit_pointers]
+    supersedes: [native-crash]
+  - id: lua-startup-exit
+    pattern: '(?s)\A(?=.*libxlua\.so[^\r\n]*lj_err_throw)(?=.*(?:__cxa_finalize|exit\+\d+))(?=.*(?:Fatal signal 6|FORTIFY:))'
+    severity: error
+    diagnosis: An uncaught Lua error triggered process exit, followed by a crash during Unity cleanup. The mutex failure is secondary; capture the original Lua error before choosing a fix. This stack alone does not identify a pointer-range problem.
+    suggest: []
+    supersedes: [native-crash]
+  - id: vrapi-frame-rejected
+    pattern: 'OVRPortVrApi:\s+Unsupported frame flags or swap interval'
+    severity: fatal
+    diagnosis: The VrApi bridge rejected the game's frame options, so no picture reaches the headset even though frame pacing can appear in the log. Rebuild and reinstall with the updated bridge; it accepts the old texture-density debug flag used by The Climb (GitHub #238). Other unsupported options are logged with their flags and swap interval.
+    suggest: [frame.vrapi_bridge]
+  - id: foveation-instance-skipped
+    pattern: 'fdm_injection_CreateInstance: skipped'
+    severity: info
+    diagnosis: Valve's foveation layer skipped a Vulkan instance. This may be a helper instance; it does not prove
+      that every game render pass lacks foveation. Compare with instance-created and render-pass diagnostics.
+      For a compatible renderer, Customize > Eye-tracked foveation > Eye-tracked explicitly enables injection.
+      Verify image quality and GPU time before retaining it; a loaded layer alone is not proof of active foveation.
+    suggest: []
   - id: no-launcher
     pattern: 'APP_ACTIVITY is empty'
     severity: fatal
@@ -19,8 +49,8 @@ signatures:
   - id: no-arm64
     pattern: 'INSTALL_FAILED_NO_MATCHING_ABIS'
     severity: fatal
-    diagnosis: This game is 32-bit only and can't run on the Frame (no AArch32). Use the PC (Rift) version through Revive.
-    suggest: []
+    diagnosis: 32-bit-only APK (e.g. a Gear VR or Oculus Go game). The Steam Frame has no 32-bit ARM support; FramePort's 32-bit bridge translates the game (experimental).
+    suggest: [frame.a32_bridge]
   - id: android-too-new
     pattern: '(NoClassDefFoundError|ClassNotFoundException|NoSuchMethodError)\b.*(Landroid/window/|android\.window\.|(storeStoreFence|loadLoadFence)\(\)V in class Ljava/lang/invoke/VarHandle)'
     severity: fatal
@@ -41,6 +71,17 @@ signatures:
     severity: fatal
     diagnosis: The game's graphics crashed a few seconds after start. Its render thread jumped to address 0x10000 in the Frame's GL driver (Mesa/Zink), which reads past a render-pass cache when a game uses multisampled render-to-texture (Unreal's mobile MSAA, for example Star Wars Pinball VR); the GL shim hides that extension.
     suggest: [frame.unreal_gl_shim, frame.unity_gl_shim]
+  - id: unreal-splash-frame-stall
+    pattern: '(?s)\A(?=.*CSxrSession::WaitFrame)(?=.*FSplash::RenderFrame_RenderThread)(?=.*FlushRenderingCommands)'
+    severity: error
+    diagnosis: Unreal's map loading waits for rendering while its separate Oculus splash waits for an unbegun VR frame (Tales from the Galaxy's Edge, issue 61). Bypass the splash renderer to let loading finish; the last image stays visible during loading.
+    suggest: [frame.unreal_splash_bypass]
+  # Attachment sizes captured by the issue 61 GL diagnostic probe, not ordinary launch logs.
+  - id: unreal-multiview-depth-size
+    pattern: '(?s)\A(?=.*ViewLog[^\n]*attachment 8ce0[^\n]*renderbuffer=1728x1728)(?=.*ViewLog[^\n]*attachment 8d00[^\n]*renderbuffer=1920x10(?:16|20))'
+    severity: warning
+    diagnosis: The measured multiview depth attachment keeps the initial Android window dimensions and clips the taller eye color target (Tales from the Galaxy's Edge, issue 61). Refresh Unreal's cached depth dimensions from its eye render size; menu panels use separate layers and remain intact.
+    suggest: [frame.unreal_multiview_depth]
   - id: pac-unpaired
     pattern: 'ILL_ILLOPN\), fault addr 0x[0-9a-f]+ \(\*pc=0xd50323bf\)'
     severity: fatal
@@ -227,6 +268,7 @@ signatures:
     supersedes: [direct-vrapi, native-crash]
   - id: direct-vrapi
     pattern: '(?<!called before )vrapi_Initialize|VrApi.*not supported|libvrapi\.so.*(not found|failed)'
+    unless: 'a32bridge: '  # a 32-bit game on the a32 bridge: it translates VrApi itself
     severity: warning
     diagnosis: The game uses Meta's VrApi directly and needs the VrApi bridge.
     suggest: [frame.vrapi_bridge]
@@ -308,6 +350,28 @@ signatures:
     diagnosis: The game's Vivox voice-chat SDK calls Android 12 audio-routing methods (AudioManager communication devices) without checking the Android version; Lepton runs Android 11, so the app crashes (for example Green Hell VR). The patch makes Vivox's audio-route check return early (voice chat keeps the default route).
     suggest: [frame.vivox_audio_route]
     supersedes: [java-crash]
+  - id: lepton-data-link-failed
+    pattern: "ln: cannot create symbolic link from '[^']*' to '/data/data/|Couldn't create directory for SharedPreferences file /data/user/0/"
+    severity: fatal
+    diagnosis: The game has no internal storage (saves, settings) inside Lepton. Usually its folder's path has a space (a microSD card named for example "Steam Frame 512g"), which Lepton's own scripts can't handle; FramePort's launcher (agent 83 and newer) gives Lepton a path without spaces. Connect FramePort once so the launcher is updated, then start the game again.
+    report: true
+    supersedes: [java-crash, native-crash]
+  - id: bhaptics-permission-prompt
+    pattern: 'GrantPermissionsActivity: Permission grant result .*permission=android\.permission\.BLUETOOTH_CONNECT'
+    severity: error
+    diagnosis: The game asked for Android 12's Bluetooth permission (bHaptics' vest SDK, for example Yupitergrad). Lepton runs Android 11, so Android's permission screen opens for a moment, the game is paused, and Meta's OVRPlugin may stop drawing (a frozen loading screen). The patch makes that request return at once.
+    suggest: [frame.bhaptics_permission]
+  - id: eos-keychain-loop
+    pattern: 'LogEos: Resetting EOS SDK keychain: Failed to create'
+    severity: error
+    diagnosis: Epic Online Services can't save its login keychain and retries without end (a start that never finishes, 100 % CPU). The usual cause is missing internal storage (see lepton-data-link-failed); the patch stops the loop, and EOS then reports the failure to the game once.
+    suggest: [frame.eos_keychain_loop]
+  - id: pthread-keys-exhausted
+    pattern: 'cannot create thread specific key'
+    severity: fatal
+    diagnosis: The game ran out of thread keys (Android allows 128 per process; Unity 6 plus large native libraries such as Firebase or Gecko, and the Frame's own graphics/OpenXR libraries, use them up), so a library aborted at start (for example Wander in Firebase's Firestore). The patch lets Unity's keys without a clean-up function share one real key.
+    suggest: [frame.unity_tls_key_pool]
+    supersedes: [native-crash]
   - id: unreal-obb-check-stuck
     pattern: 'Displayed \S+/\S*DownloaderActivity\b'
     # the downloader returned (the engine's main init resumed, OpenXR started) or the game crashed (its own finding)
@@ -317,10 +381,19 @@ signatures:
       The game stays on Unreal's OBB check screen (DownloaderActivity), which the Frame doesn't show, and never
       starts VR (for example Contractors, GitHub #159). Unreal checks that the data file (.obb) has the name and size
       this APK expects, and with bVerifyOBBOnStartUp it also reads the whole file to check it; a failed check waits
-      on an error screen. "Unreal - start without the OBB check" skips the content check. If the game still stops
-      here, the OBB doesn't match this APK version - copy the APK and the OBB from the same install, add the game
-      again and reinstall.
-    suggest: [frame.unreal_skip_obb_check]
+      on an error screen. "Unreal - start without the OBB check" skips the content check. Copy the APK and OBB
+      from the same install, add the game again and reinstall.
+      If the downloader still appears with bVerifyOBBOnStartUp=false (the skip patch already applied), try
+      "Unreal: skip the OBB delivery check", an experimental bypass of the separate Java name and size gate
+      (e.g. Into The Radius, GitHub #283). An external-storage path or visibility failure can reject an uploaded
+      OBB; the native engine still needs complete, matching, readable data.
+    suggest: [frame.unreal_skip_obb_check, frame.unreal_skip_obb_delivery]
+  - id: tbxr-fdm-shutdown-crash
+    pattern: '(?s)\A(?=.*Fatal signal 11)(?=.*fdm_injection_xrDestroySwapchain)(?=.*TBXR_LeaveVR)'
+    severity: error
+    diagnosis: The game crashed while leaving VR, inside Valve's foveation layer when it destroys a swapchain (for example Lambda1VR). This can happen after manually quitting; it is not a startup crash and does not explain distorted geometry seen before quitting.
+    suggest: []
+    supersedes: [native-crash]
   - id: native-crash
     pattern: 'Fatal signal (\d+) \(SIG[A-Z]+\)'
     severity: fatal
@@ -358,6 +431,11 @@ signatures:
     severity: fatal
     diagnosis: The game can't read its own data files (OBB/data folder) - they are incomplete or from another version of the game than the APK. Copy the whole data folder again from the same install as the APK, add the game again and reinstall.
     suggest: []
+  - id: fmod-bank-missing
+    pattern: 'Error loading FMOD bank "/(sdcard|storage/emulated/\d+)/Android/obb/[^"\r\n]+\.bank": (ERROR|ERR_[A-Z_]+)\b'
+    severity: fatal
+    diagnosis: The game can't load its external sound banks, so it may show a file-loading error even while rendering frames. Copy the whole obb folder from the same backup as the APK, including the .bank files (not just .obb files). Keep apk/ and obb/ beside each other, add the backup folder again and reinstall.
+    suggest: []
   - id: permission-denied-save
     pattern: 'Permission denied.*(Android/data|/sdcard)|EACCES.*Android/data'
     severity: warning
@@ -463,6 +541,12 @@ signatures:
     severity: error
     diagnosis: The game can't write to a folder it created, so it may quit at start (for example SUPERHOT's cloud/data, mode 1700). FramePort's launcher (agent 41 or newer) gives such folders owner and group write permission before and during every launch; reinstall the game to get the new launcher. A folder the game creates and checks in the same moment on its very first start can't be repaired in time, so start the game again.
     suggest: []
+  - id: startup-save-permission
+    pattern: '(?s)UnauthorizedAccessException: Access to the path "/(?:sdcard|storage/emulated/0)/Android/data/[^"\r\n]+/files/cloud/data" is denied\.[^\n]*(?:\n[^\n]*){0,25}?StartupLoading\+<Start>'
+    severity: fatal
+    diagnosis: The startup routine stopped because it couldn't create the cloud-save directory, so the game stays on its loading screen even while rendering frames (Jurassic World Aftermath). The launcher's permission repair happens after this first-start error; close the game and start it again without uninstalling. Agent 84 prepares the cloud-save directory before startup to avoid this race on fresh installs.
+    suggest: []
+    supersedes: [save-folder-permission]
   - id: surface-swapchain-emulated
     pattern: 'surface_emul: emulated Android surface swapchain'
     severity: info
@@ -481,6 +565,13 @@ signatures:
       the video was decoded in software instead, which is slow for 4K/8K. Turn off hardware video decoding in Steam's
       settings, restart Steam, then start the game again.
     suggest: []
+# Launch tests run without a worn headset. Some parts give up on tracking after a while and end the VR session; what
+# the game does after that (often a crash in the GPU driver while its renderer tears down) never happens in the
+# headset. In a launch test that already had paced frames before such a line, a later exit or crash still passes,
+# with a note (finding `headless-end`). Play sessions ignore this list.
+headless_end:
+  - label: the VrApi bridge's 30 s tracking deadline
+    pattern: 'EnterVrMode: no tracked head pose before deadline'
 milestones:  # progress markers, in order; the furthest one reached is reported
   - {id: pcvr-launch, kind: pcvr, pattern: 'FramePort: launching|Launched injector with', label: Launcher started}
   - {id: pcvr-oculus-hmd, kind: pcvr, pattern: 'FramePort oculushmd: OculusHMDConnected event ready', label: Oculus headset event provided}

docs/COMPATIBILITY.md

@@ -11,10 +11,11 @@ Got a game working? [Share its recipe](INSTALL.md#share-a-recipe-or-report-a-pro
 | Kind of game | On the Steam Frame |
 |---|---|
 | Quest games | Converted to OpenXR (the VR standard the Frame uses) by OVRPort and patched; they run in Lepton, Valve's Android runtime |
+| 32-bit Gear VR, Oculus Go and early Quest games | Run through FramePort's 32-bit bridge (experimental): it translates the game's 32-bit code inside the app; the Frame's right controller acts as the Gear VR / Go controller |
 | Other Android VR apps using OpenXR (for example Pico builds) | Converted the same way; the other headset's own features and store services aren't available |
 | Android apps without VR | Installed unchanged and shown as a window in the headset |
 | PC VR games | On the Frame through Proton (experimental), or on your PC and streamed to the Frame: see [PC VR games](INSTALL.md#pc-vr-games) |
-| Can't run | 32-bit-only or x86-only Android apps, apps for Pico's or HTC's own VR system, Android XR apps, and games that check their license through the Oculus app |
+| Can't run | x86-only Android apps, apps for Pico's or HTC's own VR system, Android XR apps, and games that check their license through the Oculus app |
 
 Automatic launch tests show that a game starts; only the headset shows whether it looks right.
 

docs/DIAGNOSTICS.md

@@ -23,6 +23,9 @@ manifest.json                versions (app, agent, tools, SteamOS build, Proton)
 app/app.log                  the app's log (<data>/logs/app.log, rotated 2 MB × 3)
 app/jobs/*.log               saved GUI job logs (<data>/logs/jobs, last 30): build, install, test, ...
 app/settings.json            library settings, catalog sources
+app/display.json             Flet/Flutter versions and last window state; on native Windows, display layout,
+                             resolution, refresh rate, GPU driver metadata and up to 60 recent display/device
+                             System event records (last 30 minutes; timestamps, providers and IDs only)
 frame/info.json              agent `info` (SteamOS build, Lepton, Proton, installed games, kernel keys)
 frame/host.json              OpenXR runtime + explicit layers, podman containers, containers.conf, uptime
 frame/XRService-*.log        the Frame's OpenXR runtime (SteamVR XRService) log, newest
@@ -57,6 +60,12 @@ after the logs were cut); OpenGL ES (no index): the newest modules (by time writ
 the kernel's `hangcheck detected gpu lockup` line (this-boot-kernel.txt). All modules stay in the game's storage on
 the Frame (`Android/data/<pkg>/files/fp_vk_shaders/`, Files tab → the game's storage).
 
+Display queries run only while collecting logs. The Windows event query has a five-second timeout and runs without
+a console window; the result distinguishes no matching events from a failed or timed-out query. Window visibility,
+focus and completed move/resize events are recorded in `app.log`, with UTC timestamps for comparison with Windows
+events. There is no display polling loop or change to display settings. Empty System event results do not rule out
+a rendering or monitor-link problem.
+
 ## Redaction
 `diag/redact.py` runs on every file and on the issue text.
 - **Exact values:** the data dir → `<data>`, home dirs → `<home>`, user names → `<user>`, PC and Frame host names and

docs/FRAME_RUNTIME.md

@@ -28,7 +28,7 @@
   200 keys, so ~200 launches after boot every container fails ("create keyring … Disk quota exceeded"). FramePort sets
   `keyring = false` in `~/.config/containers/containers.conf`; a reboot clears already-leaked keys.
 - Picks the activity with category LAUNCHER (`APP_ACTIVITY`). Game data is visible at `/sdcard/Android/{obb,data}/<pkg>`.
-- 64-bit only (no AArch32).
+- 64-bit only (no AArch32): 32-bit-only APKs run through FramePort's a32 bridge (`frame.a32_bridge`).
 - `<install>/lepton-shaders/` holds Mesa's shader cache (Lepton sets `mesa.shader.cache.dir=/data/shaders`):
   `foz_cache.foz` + `foz_cache_idx.foz` per graphics driver (Turnip Vulkan, zink GL), typically 4–6 files and 7–19 MB
   per game, 2D apps included. It speeds up later starts; deleting it only costs one slower start.
@@ -84,7 +84,41 @@
 - Display 72 Hz by default in tests. Head pose is only tracked while the headset is worn; otherwise flags 0x3 and
   the session stays below FOCUSED.
 
+## Lua native pointer compatibility
+
+Frame's Android processes can map libraries above the lowest 2^47 bytes of address space. The verified xLua API 105
+engine in BattleTalent 4.7 rejects those otherwise valid pointers in `lua_pushlightuserdata`. This was isolated using
+the unchanged library from the source APK: a real allocation at `0x10000000` round-trips, but its own native `xlua_tag`
+pointer above 47 bits raises `bad light userdata pointer` and exits. With `frame.luajit_pointers`, both round-trip
+exactly. No game scripts or account checks are changed. This validates an address-layout compatibility requirement;
+the APK was not run on an actual Quest during this investigation.
+
+The patch is restricted to SHA-256 `6d5860e4a4f1cc2b05c600c63297ed467369739666edca79413fff4374ff2684`.
+It redirects only the Lua engine's public API to a pinned full-pointer LuaJIT, keeping the original xLua bindings,
+LuaSocket and game helpers. The patched build survives a 60 s headless launch and creates OpenXR swapchains.
+Early frame-rectangle errors and backend login errors remain in the capture; this does not verify rendering or play.
+An arbitrary `lj_err_throw` followed by Unity destructor failures does not prove this pointer issue: first capture the
+Lua error text. `Unknown Platform` also appears after this crash is fixed, so it was not the fatal cause here.
+
 ## Graphics stack
+
+- Explicit foveation injection probe (SteamOS 0.4.5, 20261007.6125817, Lepton 3.0.5, 2026-10-11):
+  Batman's normal Steam environment requested the FDM Vulkan layer but supplied no `FDM_DEBUG` flag.
+  Appending `debug` while preserving inherited flags showed `fdm_injection_CreateInstance: skipped`.
+  A temporary `FDM_DEBUG=enable,debug` launch created the Unity/Manta Vulkan instance and device,
+  detected a 54x54 two-layer density map for 1728x1728 eye buffers, and logged render passes with
+  `fdm 1`, `already_has_fdm=1`, and changing offsets for both eyes. This verifies the injection path,
+  not visual quality, gaze calibration, sustained gameplay stability, or an FPS/power improvement.
+  `device.foveation` mode `tracked` now explicitly loads the layer and sets `FDM_DEBUG=enable` without
+  debug spam. It is opt-in; do not enable it globally or assume all GLES/Zink and Vulkan renderers work.
+  Follow-up wearer test on 2026-10-11 FAILED in Batman: large rainbow glitches outside the gaze region
+  and jitter even in clear regions. Restoring the original launcher and restarting removed BOTH symptoms,
+  confirmed by the wearer. Do not recommend forced injection for this Batman build. Reaching foveated
+  render passes was only a technical probe, not a working visual implementation. Eye-tracking logs also
+  showed left-eye filter resets, but they do not establish the rendering bug's root cause.
+  Keep `adapter.foveation_fix` separate: hiding the game's Quest extensions does not prevent the
+  independent Valve injection path. A swapchain sample count of 1 also does not prove the absence of
+  internal MSAA: the enabled Batman render-pass trace reported `samples 2`.
 - 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
@@ -155,6 +189,8 @@
 ## Steam integration
 - Non-Steam shortcut: binary `userdata/<id>/config/shortcuts.vdf`; appid = crc32(exe+title) | 0x80000000;
   artwork in `config/grid/<appid>p.*` (portrait), `<appid>.*` (landscape), `<appid>_hero.*`, `<appid>_logo.*`.
+  KeyValues names are case-insensitive: Steam may save `Shortcuts` / `AppName` after a devkit registration
+  (GitHub #263). Agent v86 reads and updates keys case-insensitively, keeping Steam's spelling and existing appids.
   Steam reads the file only at start → stop steam.service, edit, start (FramePort does it once per batch).
 - Processes started from Steam (Konsole, SSH sessions?) share steam.service's cgroup: use `systemd-run --user`.
 - SSH: `sshd` must be enabled (`sudo systemctl enable --now sshd`), which needs a user password (`passwd`).
@@ -324,6 +360,45 @@ over Quest games.
 - Unity text fields close without a system keyboard; see `frame.unity_text_input` in PLAYBOOK.md.
 
 
+## Shared foveation controls (tested 2026-10-12)
+
+Under a Quest game's Advanced patches, choose **Foveated rendering → Eye-tracked**, then **Update on Frame**.
+The full-resolution area selector defaults to **Default (30% radius)**: no radius override, preserving the
+runtime profile used in the headset experiments. Larger radii retain more detail and save less shading work.
+Custom radii set `FOVE_INNER`; `FOVE_OUTER` is twice that value, matching the runtime's profile proportions.
+The inspected runtime's built-in inner/outer pairs are 0.30/0.60, 0.25/0.50 and 0.20/0.40.
+The shared-texture injection path selects profile 1: 0.30 inner radius and 0.60 outer radius.
+
+`device.foveation` enables Valve's shared Vulkan injection and suppresses competing native foveation through
+`foveation_fix=1`. Recipes and shared catalog entries preserve mode, radius and test selection. This remains
+experimental: complete images were confirmed in RE4, Batman, Deadpool, The Climb 2 and Asgard's Wrath 2,
+not all Quest games or renderers. RE4 and Batman checks include title/calibration scenes; these are not
+equivalent to extended gameplay coverage. Asgard gameplay was visually confirmed, without an on/off benchmark.
+Batman additionally receives the verified ordinary shared-allocation patch, guarded by the full original
+OVRPlugin hash; unknown Batman versions fail explicitly rather than receiving unchecked binary offsets.
+
+The Climb 2 uses a private `libvrapi_foveation.so` bridge, installed only into that game's APK after the
+standard bridge patch. It retains images during held-focus visibility dips, separates mono overlay output
+storage from stereo density-map storage, and rate-limits its view-cache writes. Its process-local Valve layer
+correction supplies both eye offsets and avoids the invalid subpass mask-table reads seen during Alps loading;
+`yflip` corrects vertical gaze direction. The renderer SHA-256 and 1.0 resolution scale are checked before
+installation. The runtime correction additionally checks the exact Valve library SHA-256 and all four original
+instructions before touching executable memory; unsupported libraries request injection be disabled and log
+the reason. No system library is changed. A SteamOS update requires revalidation of this compatibility path.
+Both-eye gaze following was confirmed in Climb's darkening diagnostic, but long-session stability remains
+experimental. Off rebuilds from the source APK and removes this private support, including its visibility fix.
+
+**Darken lower-resolution regions (test)** adds an optional Vulkan shader diagnostic. It dims RGB where the
+actual `FragSizeEXT` footprint exceeds one pixel; alpha is unchanged. Deadpool's shaded regions were confirmed
+to follow gaze in the headset. Unsupported shader output interfaces are skipped, and multiple passes may
+compound darkening, so this is a diagnostic rather than a precise composited mask. Do not benchmark with it on.
+Uncheck it and update from the original source APK to remove the diagnostic library, except in Climb where
+the same library also carries the compatibility correction. Darkening stays dormant without its launcher opt-in.
+
+High-resolution Deadpool samples crossed from about 45 to 90 FPS with injection enabled, but temperatures and
+power rose as it rendered twice as many frames. Foveation does not guarantee lower temperature at uncapped FPS.
+The new configurable radii have configuration/build coverage; each radius has not been separately play-tested.
+
 ## Monitoring sources (probed 2026-10-07, SteamOS 0.4.3, kernel 6.18; used by the Monitor tab, agent `_monitor`)
 
 All readable by the steamos user without root; the agent reads them directly (no programs started per sample).

docs/GAMES.md

@@ -10,7 +10,9 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Accounting+ | Quest | ✅ Works |  |
 | AgeOfJoy | Quest | ✅ Works |  |
 | AllInOneSports | Quest | ✅ Works |  |
+| Arkio | Quest | ✅ Works |  |
 | Asgard's Wrath 2 | Quest | ✅ Works |  |
+| Assassin's Creed Nexus | Quest | ✅ Works |  |
 | Audica | Quest | ✅ Works |  |
 | BAM | Quest | ✅ Works |  |
 | BARTENDER VR SIMULATOR | Quest | ✅ Works |  |
@@ -22,32 +24,47 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Beat Saber | PC VR | ✅ Works |  |
 | Beat Saber (co-existence build) | Quest | ✅ Works |  |
 | Blade & Sorcery: Nomad | Quest | ✅ Works |  |
+| BlazeRush | Quest | ✅ Works |  |
 | BodyCombat | Quest | ✅ Works |  |
 | BONELAB | Quest | ✅ Works |  |
 | Carve Snowboarding | Quest | ✅ Works |  |
 | Caves | Quest | ✅ Works |  |
 | Clockwork | Quest | ✅ Works |  |
+| COMPOUND | Quest | ✅ Works |  |
 | Cook-Out | Quest | ✅ Works |  |
+| Cosmodread | Quest | ✅ Works |  |
 | Creed | Quest | ✅ Works |  |
 | cubism | Quest | ✅ Works |  |
+| Dance Central | Quest | ✅ Works |  |
 | Deep Cuts | Quest | ✅ Works |  |
 | Demeter | Quest | ✅ Works |  |
 | Dinosaur Island | Quest | ✅ Works |  |
 | Doom3Quest | Quest | ✅ Works |  |
 | Down the Rabbit Hole | Quest | ✅ Works |  |
+| Drunkn Bar Fight | Quest | ✅ Works |  |
+| Drunkn Bar Fight 2 - Early Access | Quest | ✅ Works |  |
+| Eleven Table Tennis | Quest | ✅ Works |  |
 | Eleven: Table Tennis VR | PC VR | ✅ Works |  |
 | Espire 2 | Quest | ✅ Works |  |
+| FrenzyVR | Quest | ✅ Works |  |
+| Fruit Ninja | Quest | ✅ Works |  |
+| Fruit Salon | Quest | ✅ Works |  |
 | Genotype | Quest | ✅ Works |  |
+| Ghostbusters: Rise of the Ghost Lord | Quest | ✅ Works |  |
 | GORN2 | Quest | ✅ Works |  |
 | Gravity Lab | Quest | ✅ Works |  |
+| Gunjack | Quest | ✅ Works |  |
 | H.U.N.T | Quest | ✅ Works |  |
 | I Am Cat | Quest | ✅ Works |  |
 | I Am Monkey | Quest | ✅ Works |  |
+| IEYTD3 | Quest | ✅ Works |  |
 | In Death: Unchained | Quest | ✅ Works |  |
 | Into The Radius 2 | Quest | ✅ Works |  |
 | Job Simulator | Quest | ✅ Works |  |
 | Jurassic World Aftermath Collection | Quest | ✅ Works |  |
 | Keep Talking and Nobody Explodes | Quest | ✅ Works |  |
+| Kill It With Fire VR | Quest | ✅ Works |  |
+| Ladder | Quest | ✅ Works |  |
 | Lambda1VR | Quest | ✅ Works |  |
 | LEGO® Bricktales | Quest | ✅ Works |  |
 | Lucky's Tale | Quest | ✅ Works |  |
@@ -57,8 +74,11 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Medieval Dynasty New Settlement | Quest | ✅ Works |  |
 | Metro Awakening | Quest | ✅ Works |  |
 | Mobile Suit Gundam: Silver Phantom | Quest | ✅ Works |  |
+| Moss: Book II | Quest | ✅ Works |  |
+| Munkr Funkr (The Legacy Days) | Quest | ✅ Works |  |
 | Nano | Quest | ✅ Works |  |
 | NEX Player | Quest | ✅ Works |  |
+| NFL PRO ERA II | Quest | ✅ Works |  |
 | NOPE CHALLENGE | Quest | ✅ Works |  |
 | palazzo_santacruz | Quest | ✅ Works |  |
 | Path of the Warrior | Quest | ✅ Works |  |
@@ -68,6 +88,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | PowerWash Simulator VR | Quest | ✅ Works |  |
 | QuestCraft | Quest | ✅ Works |  |
 | Racket: Nx | Quest | ✅ Works |  |
+| RacketPinball | Quest | ✅ Works |  |
 | RC Pilot Trainer | Quest | ✅ Works |  |
 | Retronika | Quest | ✅ Works |  |
 | Retropolis | Quest | ✅ Works |  |
@@ -76,26 +97,37 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Riven | Quest | ✅ Works |  |
 | Robo Recall | Quest | ✅ Works |  |
 | RUINSMAGUS | Quest | ✅ Works |  |
+| Shoot The Zombirds VR | Quest | ✅ Works |  |
 | Shores of Loci | Quest | ✅ Works |  |
+| SilentSlayer | Quest | ✅ Works |  |
 | Sniper Elite VR | Quest | ✅ Works |  |
 | Sniper Elite VR: Winter Warrior | Quest | ✅ Works |  |
 | Space Pirate Trainer Quest | Quest | ✅ Works |  |
+| Sports Scramble (Santa Cruz) | Quest | ✅ Works |  |
 | Star Wars Pinball VR | Quest | ✅ Works |  |
+| Star Wars: Tales from the Galaxy's Edge | Quest | ✅ Works |  |
 | Stremio | Quest | ✅ Works |  |
+| Superfly | Quest | ✅ Works |  |
 | SUPERHOT VR | PC VR | ✅ Works |  |
 | SUPERHOT VR | Quest | ✅ Works |  |
 | SynthRiders | Quest | ✅ Works |  |
+| Taskmaster | Quest | ✅ Works |  |
 | TetrisEffect | Quest | ✅ Works |  |
 | The Boys VR | Quest | ✅ Works |  |
 | The Climb 2 | Quest | ✅ Works |  |
 | The Room VR | Quest | ✅ Works |  |
 | The Tale of Onogoro | Quest | ✅ Works |  |
+| Time Crisis II VR (Test) | Quest | ✅ Works |  |
 | Time Crisis VR (Experimental) | Quest | ✅ Works |  |
+| Totally Baseball | Quest | ✅ Works |  |
 | Toy Master | Quest | ✅ Works |  |
+| TRIANGLE STRATEGY | Quest | ✅ Works |  |
 | Under Cover | Quest | ✅ Works |  |
+| Vacation Simulator | Quest | ✅ Works |  |
 | Vader Immortal: Episode I | Quest | ✅ Works |  |
 | Vader Immortal: Episode II | Quest | ✅ Works |  |
 | Vader Immortal: Episode III | Quest | ✅ Works |  |
+| Vampire Survivors | Quest | ✅ Works |  |
 | VR HOT Quest | Quest | ✅ Works |  |
 | VR4 | Quest | ✅ Works |  |
 | Walkabout Mini Golf | Quest | ✅ Works |  |
@@ -103,26 +135,32 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Waltz of the Wizard: Extended Edition | Quest | ✅ Works |  |
 | Wander | Quest | ✅ Works |  |
 | ZombielandVR | Quest | ✅ Works |  |
+| AFFECTED: The Manor | Quest | ⚠️ Works with issues | Gear VR game (32-bit only), runs through FramePort's 32-bit bridge (experimental). |
 | Ancient_Dungeon | Quest | ⚠️ Works with issues | Multiplayer isn't available (offline). |
 | 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. |
 | Does it Stack? | Quest | ⚠️ Works with issues | Mixed reality mode does not work (works on Demeo), everything else seems to be OK |
+| Dungeons of Eternity | Quest | ⚠️ Works with issues | It can not connect to servers |
 | End Space | Quest | ⚠️ Works with issues | Controls stop responding after the first mission loads. |
 | ExploreVR | Quest | ⚠️ Works with issues | The 3D world warps and shifts with head movement (wrong perspective). |
+| Fisherman | Quest | ⚠️ Works with issues | Loading screens have corruption, but everything works otherwise. |
 | Freedom | Quest | ⚠️ Works with issues | Volume can't be changed in the game. |
+| MacacoVR | Quest | ⚠️ Works with issues | 2d loading screens are glitchy, otherwise main gameplay is fine |
+| Majora's Mask VR | Quest | ⚠️ Works with issues | Audio on the file select screen sounds crunchy. |
 | 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. |
+| Plezy | Quest | ⚠️ Works with issues | Some videos play with strong artifacts and wrong colours; the cause is unknown, possibly hardware video decoding. |
 | Silhouette | Quest | ⚠️ Works with issues | Hand-tracking game; the Frame synthesizes hands from controllers, so it is janky. |
+| Spunky Dungeon | Quest | ⚠️ Works with issues | Gear VR / Oculus Go game (32-bit only), runs through FramePort's 32-bit bridge (experimental). |
+| Swarm 2 | Quest | ⚠️ Works with issues | MSAA creates visible seams around edge geometry and also the skybox edge |
 | The Light Brigade | Quest | ⚠️ Works with issues | Judder in weapons |
+| The Thrill Of The Fight | Quest | ⚠️ Works with issues | Right eye doesn't draw the opponent or the referee. |
 | Time Stall | Quest | ⚠️ Works with issues | Both eyes distort during movement (unresolved). |
+| Vermillion | Quest | ⚠️ Works with issues | Runs. |
 | 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… |
-| BlazeRush | Quest | ❌ Doesn't run | Starts and reaches the menu room, but the room shows no controllers and ignores all input (it all reaches the game); no fix yet. |
-| Eleven Table Tennis | Quest | ❌ Doesn't run | Stops at the splash screen. |
 | Espire 1: VR Operative (Quest Edition) | Quest | ❌ Doesn't run | Mesa GL driver crash during texture upload. |
 | GOLF+ | Quest | ❌ Doesn't run | Black screen. |
 | 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. |
 | Roblox | Quest | ❌ Doesn't run | Crashes on its first VR frame on the Frame. |
 | Shadow Point | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |
-| Sports Scramble (Santa Cruz) | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |

docs/INSTALL.md

@@ -19,6 +19,9 @@ On first start FramePort downloads the tools it uses (Settings → Tools shows t
 
 ## First launch
 
+Starting FramePort again brings its existing window to the front. If a previous instance was left running after
+its window closed, FramePort recovers it automatically, including on Windows where the GUI lock cannot be read.
+
 FramePort isn't signed with a paid certificate, so the first start shows a warning:
 
 - **Windows:** "Windows protected your PC" → **More info** → **Run anyway**.

docs/PATCHES.md

@@ -2,7 +2,7 @@
 
 # Patches
 
-Every patch and game setting FramePort knows: 156 entries in 5 groups. A game's recipe is its chosen patches and settings; tested games get theirs from the catalog ([GAMES.md](GAMES.md)), and other games get the patches FramePort suggests from its analysis. You change them on the game page under Customize.
+Every patch and game setting FramePort knows: 169 entries in 5 groups. A game's recipe is its chosen patches and settings; tested games get theirs from the catalog ([GAMES.md](GAMES.md)), and other games get the patches FramePort suggests from its analysis. You change them on the game page under Customize.
 
 Each entry says what the patch does, whether it changes the APK or only the install, when FramePort suggests it, its options, the catalog games whose recipe names it and the launch-test signatures that suggest it. Patches that are on by default are on for every game, so the catalog rarely names them.
 
@@ -11,8 +11,8 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 ## Groups
 
 - [Patches from OVRPort](#group-overport) (25)
-- [Steam Frame patches](#group-frame) (45)
-- [Game settings](#group-adapter) (65)
+- [Steam Frame patches](#group-frame) (55)
+- [Game settings](#group-adapter) (68)
 - [Files and settings on the Frame](#group-device) (8)
 - [PC VR (Proton and Revive)](#group-pcvr) (13)
 
@@ -30,7 +30,7 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Disable application space warp if used](#patch_disable_space_warp) | `patch_disable_space_warp` | Patches from OVRPort | 3 |
 | [Fix minimal Android SDK](#patch_fix_min_android_sdk) | `patch_fix_min_android_sdk` | Patches from OVRPort | default |
 | [Fix UE4 crash with Unity stub](#patch_fix_unreal_crash) | `patch_fix_unreal_crash` | Patches from OVRPort | default |
-| [Force enable passthrough](#patch_force_passthrough) | `patch_force_passthrough` | Patches from OVRPort | 2 |
+| [Force enable passthrough](#patch_force_passthrough) | `patch_force_passthrough` | Patches from OVRPort | 3 |
 | [Generate OVRPort config](#patch_generate_config) | `patch_generate_config` | Patches from OVRPort | default |
 | [Fix launcher icon entry](#patch_launcher_entry) | `patch_launcher_entry` | Patches from OVRPort | default |
 | [Mark application to allow backup](#patch_mark_allow_backup) | `patch_mark_allow_backup` | Patches from OVRPort | default |
@@ -39,53 +39,63 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Patch Oculus detection for Unity](#patch_oculus_unity) | `patch_oculus_unity` | Patches from OVRPort | default |
 | [Patch Oculus detection for Unreal](#patch_oculus_unreal) | `patch_oculus_unreal` | Patches from OVRPort | default |
 | [Remove localized app names](#patch_remove_localized_names) | `patch_remove_localized_names` | Patches from OVRPort | default |
-| [Remove Unreal's ForceQuit](#patch_remove_unreal_force_quit) | `patch_remove_unreal_force_quit` | Patches from OVRPort | 31 |
+| [Remove Unreal's ForceQuit](#patch_remove_unreal_force_quit) | `patch_remove_unreal_force_quit` | Patches from OVRPort | 35 |
 | [Remove uses-library](#patch_remove_uses_library) | `patch_remove_uses_library` | Patches from OVRPort | default |
 | [Remove VrApi library](#patch_remove_vrapi) | `patch_remove_vrapi` | Patches from OVRPort |  |
 | [Replace application label and icon](#patch_replace_icon_label) | `patch_replace_icon_label` | Patches from OVRPort | default |
 | [Pico/YVR/Quest metadata](#patch_vr_metadata) | `patch_vr_metadata` | Patches from OVRPort | default |
 | [VrApi → OpenXR adapter (OVRPort)](#patch_vrapi_openxr) | `patch_vrapi_openxr` | Patches from OVRPort |  |
+| [32-bit ARM bridge (Gear VR / Go games)](#frame-a32_bridge) | `frame.a32_bridge` | Steam Frame patches | 6 |
 | [FrameBridge OpenXR adapter](#frame-adapter) | `frame.adapter` | Steam Frame patches | default |
 | [Content files from the game's data](#frame-asset_files) | `frame.asset_files` | Steam Frame patches | 1 |
+| [Asset-file service bypass](#frame-asset_files_stub) | `frame.asset_files_stub` | Steam Frame patches |  |
 | [Skip Meta avatars](#frame-avatar_stub) | `frame.avatar_stub` | Steam Frame patches | 1 |
+| [bHaptics: skip the Bluetooth permission request](#frame-bhaptics_permission) | `frame.bhaptics_permission` | Steam Frame patches |  |
 | [BlazeRush: controllers without Meta avatars, own shader cache](#frame-blazerush) | `frame.blazerush` | Steam Frame patches | 1 |
+| [Epic Online Services: stop the keychain retry loop](#frame-eos_keychain_loop) | `frame.eos_keychain_loop` | Steam Frame patches |  |
 | [OpenGL ES: multiview shaders on flat panels (HUD, menus)](#frame-gl_multiview_fbo) | `frame.gl_multiview_fbo` | Steam Frame patches | 1 |
 | [GL shim (Mesa GLSL compatibility)](#frame-gl_shim) | `frame.gl_shim` | Steam Frame patches | 2 |
 | [Godot apps: start without a clipboard service](#frame-godot_clipboard) | `frame.godot_clipboard` | Steam Frame patches |  |
-| [Hardware video decoding (H.264, HEVC, VP9)](#frame-hw_video_decode) | `frame.hw_video_decode` | Steam Frame patches | 2 |
+| [Hardware video decoding (H.264, HEVC, VP9)](#frame-hw_video_decode) | `frame.hw_video_decode` | Steam Frame patches | 9 |
 | [Language packs from the game's files](#frame-langpacks) | `frame.langpacks` | Steam Frame patches |  |
 | [Launcher category (INFO → LAUNCHER)](#frame-launcher) | `frame.launcher` | Steam Frame patches | default |
 | [GL wrapper: OpenGL ES depth formats (Minecraft)](#frame-ltw_depth) | `frame.ltw_depth` | Steam Frame patches | default |
-| [Declare Meta-only permissions](#frame-meta_permissions) | `frame.meta_permissions` | Steam Frame patches | 1 |
+| [Fix Lua startup crashes on Frame](#frame-luajit_pointers) | `frame.luajit_pointers` | Steam Frame patches |  |
+| [Declare Meta-only permissions](#frame-meta_permissions) | `frame.meta_permissions` | Steam Frame patches | 2 |
 | [Meta XR Audio: skip Quest telemetry class](#frame-metaxr_telemetry) | `frame.metaxr_telemetry` | Steam Frame patches | default |
 | [Clear android:debuggable](#frame-nodebug) | `frame.nodebug` | Steam Frame patches | 3 |
-| [Oculus OS telemetry class stubs](#frame-oculusos) | `frame.oculusos` | Steam Frame patches | 14 |
+| [Oculus OS telemetry class stubs](#frame-oculusos) | `frame.oculusos` | Steam Frame patches | 15 |
 | [Fix crash when the game prepares the microphone](#frame-ovr_microphone) | `frame.ovr_microphone` | Steam Frame patches |  |
 | [Keep the same Meta user between starts](#frame-ovr_stable_user) | `frame.ovr_stable_user` | Steam Frame patches | default |
 | [Trace Meta platform requests (diagnostics)](#frame-ovr_trace) | `frame.ovr_trace` | Steam Frame patches |  |
 | [Platform compat (ovrMessageType_ToString)](#frame-ovrplatformcompat) | `frame.ovrplatformcompat` | Steam Frame patches | default |
 | [Stub missing Meta platform functions](#frame-ovrstubs) | `frame.ovrstubs` | Steam Frame patches | default |
 | [Unpaired pointer-authentication checks](#frame-pac_hints) | `frame.pac_hints` | Steam Frame patches | 1 |
-| [SDL apps: start without a clipboard service](#frame-sdl_clipboard) | `frame.sdl_clipboard` | Steam Frame patches | 3 |
+| [SDL apps: start without a clipboard service](#frame-sdl_clipboard) | `frame.sdl_clipboard` | Steam Frame patches | 4 |
 | [Stress Level Zero: let Unity start Vulkan itself](#frame-slz_vulkan_hooks) | `frame.slz_vulkan_hooks` | Steam Frame patches | 1 |
 | [Start straight in VR (skip the 2D launcher)](#frame-start_activity) | `frame.start_activity` | Steam Frame patches |  |
 | [Allow swapchains larger than 4096 px](#frame-swapchain_limit) | `frame.swapchain_limit` | Steam Frame patches | default |
 | [Team Beef ports: treat the Frame as a Meta headset](#frame-tbxr_vendor) | `frame.tbxr_vendor` | Steam Frame patches | 1 |
-| [GL shim for Unity (no multisampled render-to-texture)](#frame-unity_gl_shim) | `frame.unity_gl_shim` | Steam Frame patches | 12 |
+| [GL shim for Unity (no multisampled render-to-texture)](#frame-unity_gl_shim) | `frame.unity_gl_shim` | Steam Frame patches | 19 |
 | [Unity: render each eye separately (no multiview)](#frame-unity_multipass) | `frame.unity_multipass` | Steam Frame patches | 1 |
 | [Unity: disable MSAA](#frame-unity_no_msaa) | `frame.unity_no_msaa` | Steam Frame patches | 7 |
 | [Unity: skip OVROverlay layers (fades, splash screens)](#frame-unity_no_overlay_copy) | `frame.unity_no_overlay_copy` | Steam Frame patches | 2 |
-| [Unity: start VR without Meta's system apps](#frame-unity_oculus_check) | `frame.unity_oculus_check` | Steam Frame patches | 9 |
-| [Unity: keep MSAA off at runtime (OVRManager)](#frame-unity_runtime_msaa_off) | `frame.unity_runtime_msaa_off` | Steam Frame patches | 17 |
-| [Make Unity text fields work](#frame-unity_text_input) | `frame.unity_text_input` | Steam Frame patches | 58 |
+| [Unity: start VR without Meta's system apps](#frame-unity_oculus_check) | `frame.unity_oculus_check` | Steam Frame patches | 10 |
+| [Unity: keep MSAA off at runtime (OVRManager)](#frame-unity_runtime_msaa_off) | `frame.unity_runtime_msaa_off` | Steam Frame patches | 24 |
+| [Make Unity text fields work](#frame-unity_text_input) | `frame.unity_text_input` | Steam Frame patches | 73 |
+| [Unity: share thread keys (games that run out of them)](#frame-unity_tls_key_pool) | `frame.unity_tls_key_pool` | Steam Frame patches | 1 |
 | [Unity: headset always counts as worn](#frame-unity_user_presence) | `frame.unity_user_presence` | Steam Frame patches | 1 |
 | [GL shim for Unreal (no multisampled render-to-texture)](#frame-unreal_gl_shim) | `frame.unreal_gl_shim` | Steam Frame patches | 1 |
-| [Unreal: stand-ins for OVRPlugin functions OVRPort lacks](#frame-unreal_ovrp_entrypoints) | `frame.unreal_ovrp_entrypoints` | Steam Frame patches | 1 |
+| [Unreal: match multiview depth to the eye size](#frame-unreal_multiview_depth) | `frame.unreal_multiview_depth` | Steam Frame patches | 1 |
+| [Unreal: stand-ins for OVRPlugin functions OVRPort lacks](#frame-unreal_ovrp_entrypoints) | `frame.unreal_ovrp_entrypoints` | Steam Frame patches | 2 |
 | [Unreal: Quest controller bindings (RPOC key map)](#frame-unreal_quest_keymap) | `frame.unreal_quest_keymap` | Steam Frame patches | 3 |
 | [Unreal: don't wait for the Quest shader precompile](#frame-unreal_quest_precompile) | `frame.unreal_quest_precompile` | Steam Frame patches | 3 |
-| [Unreal: start without the OBB check](#frame-unreal_skip_obb_check) | `frame.unreal_skip_obb_check` | Steam Frame patches |  |
+| [Unreal: start without the OBB check](#frame-unreal_skip_obb_check) | `frame.unreal_skip_obb_check` | Steam Frame patches | 3 |
+| [Unreal: skip the OBB delivery check](#frame-unreal_skip_obb_delivery) | `frame.unreal_skip_obb_delivery` | Steam Frame patches |  |
+| [Unreal: bypass the stalled loading splash](#frame-unreal_splash_bypass) | `frame.unreal_splash_bypass` | Steam Frame patches | 1 |
 | [Unreal: thumb follows the capacitive touches](#frame-unreal_thumb_touch) | `frame.unreal_thumb_touch` | Steam Frame patches | 7 |
-| [Vivox voice chat: skip Android 12 audio routing](#frame-vivox_audio_route) | `frame.vivox_audio_route` | Steam Frame patches |  |
+| [Vermillion: paint canvases in the scene](#frame-vermillion_scene_canvas) | `frame.vermillion_scene_canvas` | Steam Frame patches | 1 |
+| [Vivox voice chat: skip Android 12 audio routing](#frame-vivox_audio_route) | `frame.vivox_audio_route` | Steam Frame patches | 1 |
 | [Vulkan: drop invalid render-pass pointers](#frame-vk_sanitize) | `frame.vk_sanitize` | Steam Frame patches | default · 1 |
 | [VrApi → OpenXR bridge](#frame-vrapi_bridge) | `frame.vrapi_bridge` | Steam Frame patches | 3 |
 | [Quiet Meta's VrApi loader (OpenXR games)](#frame-vrapi_stub) | `frame.vrapi_stub` | Steam Frame patches | 2 |
@@ -104,17 +114,20 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [360° sharpness](#adapter-equirect_res) | `adapter.equirect_res` | Game settings |  |
 | [360° 3D](#adapter-equirect_stereo) | `adapter.equirect_stereo` | Game settings |  |
 | [Per-eye diagnostics (log)](#adapter-eye_debug) | `adapter.eye_debug` | Game settings |  |
+| [Draw fades over the picture](#adapter-fade_quad) | `adapter.fade_quad` | Game settings | 2 |
+| [Upside-down panel images (diagnostics)](#adapter-flip_dump) | `adapter.flip_dump` | Game settings |  |
 | [Fix upside-down menus](#adapter-flip_emul) | `adapter.flip_emul` | Game settings |  |
 | [Rotate panels 180°](#adapter-flip_quads) | `adapter.flip_quads` | Game settings |  |
 | [Don't pause on short interruptions](#adapter-focus_hold) | `adapter.focus_hold` | Game settings | 4 |
 | [Ignore focus dips up to](#adapter-focus_hold_ms) | `adapter.focus_hold_ms` | Game settings | 2 |
 | [Hide Quest foveation](#adapter-foveation_fix) | `adapter.foveation_fix` | Game settings |  |
+| [Clear the game's GL errors (GLES)](#adapter-gl_error_clear) | `adapter.gl_error_clear` | Game settings | 3 |
 | [Hide fast anti-aliasing (OpenGL ES)](#adapter-gl_hide_msrtt) | `adapter.gl_hide_msrtt` | Game settings | 1 |
 | [Draw each eye separately (OpenGL ES)](#adapter-gl_hide_multiview) | `adapter.gl_hide_multiview` | Game settings | 1 |
 | [GL shim: high-precision vertex shaders](#adapter-gl_highp_markers) | `adapter.gl_highp_markers` | Game settings | 1 |
 | [GL shim: integer vertex inputs](#adapter-gl_int_attribs) | `adapter.gl_int_attribs` | Game settings | 1 |
 | [Flat panel diagnostics (log)](#adapter-gl_mv_debug) | `adapter.gl_mv_debug` | Game settings |  |
-| [Fix freezes when controllers vibrate](#adapter-haptic_fix) | `adapter.haptic_fix` | Game settings | 44 |
+| [Fix freezes when controllers vibrate](#adapter-haptic_fix) | `adapter.haptic_fix` | Game settings | 66 |
 | [Vibration strength](#adapter-haptic_scale) | `adapter.haptic_scale` | Game settings |  |
 | [Turn off space warp](#adapter-hide_space_warp) | `adapter.hide_space_warp` | Game settings | 4 |
 | [Controller input diagnostics (log)](#adapter-input_diag) | `adapter.input_diag` | Game settings |  |
@@ -126,16 +139,16 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [See your room](#adapter-passthrough_emul) | `adapter.passthrough_emul` | Game settings |  |
 | [Steadier head tracking](#adapter-pose_consistency) | `adapter.pose_consistency` | Game settings | 1 |
 | [Pose timing diagnostics (log)](#adapter-pose_debug) | `adapter.pose_debug` | Game settings |  |
-| [Fix hands lagging behind controllers](#adapter-pose_time_fix) | `adapter.pose_time_fix` | Game settings | 8 |
+| [Fix hands lagging behind controllers](#adapter-pose_time_fix) | `adapter.pose_time_fix` | Game settings | 11 |
 | [Treat newer Quest controllers as Touch](#adapter-profile_remap) | `adapter.profile_remap` | Game settings |  |
 | [Animate fingers from touch](#adapter-proximity_emul) | `adapter.proximity_emul` | Game settings |  |
 | [Keep pictures in bounds](#adapter-rect_clamp) | `adapter.rect_clamp` | Game settings |  |
-| [Refresh rate](#adapter-refresh_rate) | `adapter.refresh_rate` | Game settings | 2 |
+| [Refresh rate](#adapter-refresh_rate) | `adapter.refresh_rate` | Game settings | 3 |
 | [Wait for the game's GPU](#adapter-release_wait) | `adapter.release_wait` | Game settings |  |
 | [Re-create play space](#adapter-respace_kick) | `adapter.respace_kick` | Game settings |  |
 | [Sharpness](#adapter-scale) | `adapter.scale` | Game settings | 4 |
 | [Room depth](#adapter-scene_depth) | `adapter.scene_depth` | Game settings |  |
-| [Pretend room layout](#adapter-scene_emul) | `adapter.scene_emul` | Game settings | 1 |
+| [Pretend room layout](#adapter-scene_emul) | `adapter.scene_emul` | Game settings | 4 |
 | [Room height](#adapter-scene_height) | `adapter.scene_height` | Game settings |  |
 | [Room width](#adapter-scene_width) | `adapter.scene_width` | Game settings |  |
 | [Eye-image snapshots (diagnostics)](#adapter-snapshot) | `adapter.snapshot` | Game settings |  |
@@ -146,7 +159,7 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Native video surfaces (Batman renderer)](#adapter-surface_native) | `adapter.surface_native` | Game settings | 1 |
 | [Swap eyes](#adapter-swap_eyes) | `adapter.swap_eyes` | Game settings |  |
 | [Retry refused picture formats](#adapter-swapchain_fix) | `adapter.swapchain_fix` | Game settings |  |
-| [Steady controller input after focus](#adapter-sync_guard) | `adapter.sync_guard` | Game settings | 2 |
+| [Steady controller input after focus](#adapter-sync_guard) | `adapter.sync_guard` | Game settings | 3 |
 | [Hide Vulkan foveation](#adapter-vk_hide_fdm) | `adapter.vk_hide_fdm` | Game settings | 1 |
 | [Stop objects popping in and out](#adapter-vk_query_slots) | `adapter.vk_query_slots` | Game settings |  |
 | [Vulkan shader dump (diagnostics)](#adapter-vk_shader_dump) | `adapter.vk_shader_dump` | Game settings |  |
@@ -158,11 +171,11 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Keep the game's saved resolution in step](#device-config_sync) | `device.config_sync` | Files and settings on the Frame | 1 |
 | [Show as VR or as a flat window](#device-display_mode) | `device.display_mode` | Files and settings on the Frame |  |
 | [Settings files for the game](#device-files) | `device.files` | Files and settings on the Frame | 2 |
-| [Eye-tracked foveation (Valve)](#device-foveation) | `device.foveation` | Files and settings on the Frame |  |
+| [Foveated rendering (Valve)](#device-foveation) | `device.foveation` | Files and settings on the Frame |  |
 | [Hide Android's navigation bar](#device-hide_navbar) | `device.hide_navbar` | Files and settings on the Frame |  |
 | [Extra Lepton settings](#device-lepton_env) | `device.lepton_env` | Files and settings on the Frame | 3 |
 | [Controllers as a gamepad (Steam Input)](#device-steam_gamepad) | `device.steam_gamepad` | Files and settings on the Frame |  |
-| [Show the app's Android window (for typing)](#device-text_input_window) | `device.text_input_window` | Files and settings on the Frame | 58 |
+| [Show the app's Android window (for typing)](#device-text_input_window) | `device.text_input_window` | Files and settings on the Frame | 76 |
 | [Launch options (SteamVR or OpenXR)](#pcvr-launch_args) | `pcvr.launch_args` | PC VR (Proton and Revive) | 2 |
 | [Provide the Oculus runtime from Revive (Frame)](#pcvr-libovr_redirect) | `pcvr.libovr_redirect` | PC VR (Proton and Revive) |  |
 | [No Unreal crash reporter](#pcvr-no_crash_reporter) | `pcvr.no_crash_reporter` | PC VR (Proton and Revive) |  |
@@ -305,7 +318,7 @@ Lets mixed-reality games start even though they insist on a camera view of your
 - `patch_force_passthrough`
 - **Changes:** Changes the APK (during the OVRPort conversion).
 - **Suggested (on):** Mixed-reality-only game (passthrough required, no guardian): force passthrough on.
-- **Catalog games (2):** BAM, Demeter.
+- **Catalog games (3):** Arkio, BAM, Demeter.
 - **Suggested by launch-test signatures:**
   - `passthrough-missing` (error): The game needs Meta passthrough (the camera view), which the Frame lacks; the adapter emulates it.
 - **Source:** [patches/overport.py](../src/frameport/patches/overport.py)
@@ -407,7 +420,7 @@ Stops some Unreal games from closing themselves right after starting.
 - `patch_remove_unreal_force_quit`
 - **Changes:** Changes the APK (during the OVRPort conversion).
 - **Offered (off):** Built as the alternate APK for Unreal games (use it if the game quits itself).
-- **Catalog games (31):** Asgard's Wrath 2, BARTENDER VR SIMULATOR, Carve Snowboarding, Creed, Espire 1: VR Operative (Quest Edition), Espire 2, ExploreVR, Fisherman and 23 more.
+- **Catalog games (35):** Asgard's Wrath 2, BARTENDER VR SIMULATOR, Carve Snowboarding, Creed, Dance Central, Espire 1: VR Operative (Quest Edition), Espire 2, ExploreVR and 27 more.
 - **Suggested by launch-test signatures:**
   - `force-quit` (error): The game quit itself right after starting.
 - **Source:** [patches/overport.py](../src/frameport/patches/overport.py)
@@ -475,6 +488,20 @@ OVRPort's own converter for games that use Meta's oldest VR interface (experimen
 
 FramePort's own changes to a converted Quest game, for what the Steam Frame lacks or does differently.
 
+### <a id="frame-a32_bridge"></a>32-bit ARM bridge (Gear VR / Go games)
+
+Runs a 32-bit game (Gear VR, Oculus Go, early Quest) on the Frame, which only runs 64-bit code. Experimental.
+
+- `frame.a32_bridge` · experimental · also for 2D apps
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Suggested (on):** 32-bit-only game: the Frame can't run 32-bit ARM code, the bridge translates it.
+- **Catalog games (6):** AFFECTED: The Manor, Gunjack, Journey of the Gods, Shadow Point, Sports Scramble (Santa Cruz), Spunky Dungeon.
+- **Suggested by launch-test signatures:**
+  - `no-arm64` (fatal): 32-bit-only APK (e.g. a Gear VR or Oculus Go game).
+- **Source:** [patches/frame/a32_bridge.py](../src/frameport/patches/frame/a32_bridge.py)
+
+> Runs a 32-bit-only game (armeabi-v7a: Gear VR, Oculus Go and early Quest games) on the Frame, which has no 32-bit ARM support: an AArch32 → AArch64 translator inside the app runs the game's own libraries, with GLES/EGL, OpenSL ES and VrApi translated to the Frame's 64-bit ones (VrApi through the VrApi → OpenXR bridge). The Gear VR / Go controller: left stick = touchpad (walk, strafe), right stick sideways = turn (a click at the touchpad's edge), stick press or A = click, right trigger, B = back. Experimental: games run slower than native ones.
+
 ### <a id="frame-adapter"></a>FrameBridge OpenXR adapter
 
 FramePort's layer between the game and the Steam Frame: fills in what the Frame lacks (controllers, room, passthrough). Needed for every converted game.
@@ -503,6 +530,19 @@ Lets the game find extra content it keeps next to its data (for example Star War
 
 > Some games keep content in separate files next to their OBB (for example 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.
 
+### <a id="frame-asset_files_stub"></a>Asset-file service bypass
+
+Experimental bypass for a failed Meta asset-file check at startup. Reports an empty asset list and installed status without a file path; does not provide DLC. Experimental.
+
+- `frame.asset_files_stub` · experimental
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Suggested by launch-test signatures:**
+  - `meta-asset-status-error` (error): A DLC manager reports a Meta asset-file status error after VR starts (e.g.
+- **Source:** [patches/frame/langpack.py](../src/frameport/patches/frame/langpack.py)
+
+> Experimental bypass for a DLC manager blocked on Meta asset-file service errors at startup (e.g. PixelRipped 1995: Asset status error (code 100)). Returns an empty successful asset list and reports requested asset IDs as installed, with an empty file path. Does not supply DLC or change download requests. Enable only to test this startup failure; disable with FRAMEPORT_ASSET_FILES_STUB=0. Shares the language-pack library and needs no language packs.
+
 ### <a id="frame-avatar_stub"></a>Skip Meta avatars
 
 Lets games start that would stop at Meta's avatars (for example BlazeRush). No Meta avatars.
@@ -517,6 +557,19 @@ Lets games start that would stop at Meta's avatars (for example BlazeRush). No M
 
 > 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", for example BlazeRush). Replaces it with a library that does nothing, so the game runs without Meta avatars.
 
+### <a id="frame-bhaptics_permission"></a>bHaptics: skip the Bluetooth permission request
+
+Stops bHaptics from asking for a Bluetooth permission the Frame doesn't have (the game would freeze on its loading screen).
+
+- `frame.bhaptics_permission` · also for 2D apps
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Suggested (on):** bHaptics asks for an Android 12 Bluetooth permission at start; the permission screen interrupts the game on the Frame.
+- **Suggested by launch-test signatures:**
+  - `bhaptics-permission-prompt` (error): The game asked for Android 12's Bluetooth permission (bHaptics' vest SDK, for example Yupitergrad).
+- **Source:** [patches/frame/bhaptics_permission.py](../src/frameport/patches/frame/bhaptics_permission.py)
+
+> bHaptics' vest SDK asks for an Android 12 Bluetooth permission at start; on Lepton's Android 11 the permission screen takes the foreground for a moment and Meta's OVRPlugin stops drawing (for example Yupitergrad freezing on its loading screen). The request returns at once instead (an in-place edit of classes.dex).
+
 ### <a id="frame-blazerush"></a>BlazeRush: controllers without Meta avatars, own shader cache
 
 Makes BlazeRush's menus and controllers work without Meta's avatars, and lets its shader fixes take effect.
@@ -530,6 +583,19 @@ Makes BlazeRush's menus and controllers work without Meta's avatars, and lets it
 
 > BlazeRush 1.0.349 only (Klownicle's guide, GitHub #57). Its menus wait for Meta's avatar, which never comes on the Frame, before they create the game's own controllers: the second menu ignored all input. Two instructions in libtargemapp.so skip that wait and the avatar mesh drawing; the game's shader cache gets a new folder name (cache/br_shader_v1), so programs compiled before the GL shim's shader fixes aren't reused. Only this exact build is changed (code fingerprint and every instruction checked); anything else is left as it is.
 
+### <a id="frame-eos_keychain_loop"></a>Epic Online Services: stop the keychain retry loop
+
+Stops Epic Online Services from retrying its login keychain forever (the game would never finish starting).
+
+- `frame.eos_keychain_loop` · also for 2D apps
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Suggested by launch-test signatures:**
+  - `eos-keychain-loop` (error): Epic Online Services can't save its login keychain and retries without end (a start that never finishes, 100 % CPU).
+- **Source:** [patches/frame/eos_keychain_loop.py](../src/frameport/patches/frame/eos_keychain_loop.py)
+
+> Epic Online Services (EOS) keeps its login keychain in the app's settings storage. When it can't write there, it resets the keychain and tries again without end (for example Beyond Sandbox: a start that never finishes, 100 % CPU, a log of gigabytes). The reset method returns at once instead (an in-place edit of classes.dex), so EOS reports the failure to the game once.
+
 ### <a id="frame-gl_multiview_fbo"></a>OpenGL ES: multiview shaders on flat panels (HUD, menus)
 
 Experimental: shows HUDs, menus and other flat panels that stay black on the Frame (for example Doom3Quest's HUD and PDA).
@@ -577,7 +643,7 @@ Plays the game's videos on the Frame's video hardware, so 4K and 8K video runs s
 - `frame.hw_video_decode` · also for 2D apps
 - **Changes:** Install only: written on the Frame when the game is installed; the APK isn't changed.
 - **Suggested (on):** The game plays video through Android's decoders (MediaCodec, ExoPlayer or VLC): decode it on the Frame's hardware.
-- **Catalog games (2):** 4XVR Video Player, Batman: Arkham Shadow.
+- **Catalog games (9):** 4XVR Video Player, Batman: Arkham Shadow, Dance Central, Fruit Ninja, Ghostbusters: Rise of the Ghost Lord, Kill It With Fire VR, MacacoVR, Moss: Book II and 1 more.
 - **Source:** [patches/frame/hw_video_decode.py](../src/frameport/patches/frame/hw_video_decode.py)
 
 > Decodes the game's videos on the Frame's hardware video decoder instead of Android's software decoders, which stutter or fall behind with 4K/8K video (for example video players, Batman: Arkham Shadow's cutscenes). Adds FramePort's codec plugin (OMX.frameport.avc/hevc/vp9.decoder) to this game's container only; the APK isn't changed. When the hardware is busy (for example Steam's own hardware video decoding is on) the video is decoded in software as before.
@@ -618,6 +684,19 @@ Stops a black picture in Minecraft launchers (for example QuestCraft).
 
 > 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.
 
+### <a id="frame-luajit_pointers"></a>Fix Lua startup crashes on Frame
+
+Lets games with a verified older Lua engine get past a startup crash on the Frame.
+
+- `frame.luajit_pointers`
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Suggested (on):** The bundled Lua engine rejects Frame's wider native pointers; use the compatible full-pointer engine while retaining the game's bindings.
+- **Suggested by launch-test signatures:**
+  - `lua-lightuserdata-pointer` (fatal): The Lua runtime rejected a pointer outside its supported address range.
+- **Source:** [patches/frame/luajit_pointers.py](../src/frameport/patches/frame/luajit_pointers.py)
+
+> Older xLua/LuaJIT engines reject native pointers outside their 47-bit range, causing a startup error and sometimes a second crash during Unity shutdown (e.g. BattleTalent). Uses a Lua engine that preserves full pointer values while keeping the game's original xLua bindings and native helpers. Applied only to the verified compatible library build.
+
 ### <a id="frame-meta_permissions"></a>Declare Meta-only permissions
 
 Declares Meta's permissions some mixed-reality games ask for, so they don't stop.
@@ -625,7 +704,7 @@ Declares Meta's permissions some mixed-reality games ask for, so they don't stop
 - `frame.meta_permissions`
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Mixed-reality game that needs the room model: its 'use spatial data' permission must be granted (for example Demeter).
-- **Catalog games (1):** Demeter.
+- **Catalog games (2):** Arkio, Demeter.
 - **Source:** [patches/frame/manifest_fixes.py](../src/frameport/patches/frame/manifest_fixes.py)
 
 > Declares com.oculus.permission.* / horizonos.permission.* that the app uses, so Android grants them at install (for example the 'use spatial data' permission of mixed-reality games like Demeter).
@@ -668,7 +747,7 @@ Provides stand-ins for Quest system calls some games make at start.
 - **Suggested (on):** The Unreal build of Meta XR Audio looks up com.oculus.os.AnalyticsEvent and aborts without it (for example NOPE Challenge).
 - **Suggested (on):** Several Meta SDK libraries look up com.oculus.os.AnalyticsEvent (…); games like this abort without the stub (for example Nano).
 - **Offered (off):** … references com.oculus.os.AnalyticsEvent; usually harmless (for example Batman: Arkham Shadow and LEGO Bricktales run without it). Enable if the game aborts with ClassNotFoundException.
-- **Catalog games (14):** AgeOfJoy, AllInOneSports, Caves, Deep Cuts, Does it Stack?, Nano, NOPE CHALLENGE, RC Pilot Trainer and 6 more.
+- **Catalog games (15):** AgeOfJoy, AllInOneSports, Caves, Deep Cuts, Does it Stack?, Nano, NOPE CHALLENGE, RC Pilot Trainer and 7 more.
 - **Suggested by launch-test signatures:**
   - `oculus-os-class` (fatal): The game looks up a Quest-only system class and aborts.
 - **Source:** [patches/frame/telemetry.py](../src/frameport/patches/frame/telemetry.py)
@@ -757,7 +836,7 @@ Lets SDL and LÖVE games start on the Frame (they'd crash looking for a clipboar
 - `frame.sdl_clipboard` · also for 2D apps
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** SDL app: it crashes at start in Lepton, which has no clipboard service.
-- **Catalog games (3):** Time Crisis II VR (Test), Time Crisis VR (Experimental), WiiCompiled VR.
+- **Catalog games (4):** Majora's Mask VR, Time Crisis II VR (Test), Time Crisis VR (Experimental), WiiCompiled VR.
 - **Suggested by launch-test signatures:**
   - `sdl-no-clipboard` (fatal): The app crashed at start because the Frame's Android has no clipboard.
 - **Source:** [patches/frame/sdl_clipboard.py](../src/frameport/patches/frame/sdl_clipboard.py)
@@ -808,13 +887,13 @@ Allows very large pictures (8K video, theaters) instead of quitting.
 
 Lets Team Beef ports (for example Lambda1VR) start on the Frame.
 
-- `frame.tbxr_vendor`
+- `frame.tbxr_vendor` · revision 2
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Team Beef port: it picks its OpenXR setup by headset maker, which the Frame reports as "valve".
 - **Catalog games (1):** Lambda1VR.
 - **Source:** [patches/frame/tbxr_vendor.py](../src/frameport/patches/frame/tbxr_vendor.py)
 
-> Team Beef's ports (for example 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.
+> Team Beef's ports (for example 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. Keeps GL4ES in charge of its desktop OpenGL draw calls so animated models don't turn into stretched triangles.
 
 ### <a id="frame-unity_gl_shim"></a>GL shim for Unity (no multisampled render-to-texture)
 
@@ -823,7 +902,7 @@ Stops a gray or frozen screen in Unity games that turn on anti-aliasing while ru
 - `frame.unity_gl_shim`
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Unity GLES game that may switch to MSAA at runtime: hide multisampled render-to-texture, which crashes the Frame's GL driver (for example The Room VR).
-- **Catalog games (12):** Audica, BattleSisters, Beat Saber, Clockwork, Cosmodread, Down the Rabbit Hole, End Space, Gravity Lab and 4 more.
+- **Catalog games (19):** Audica, BattleSisters, Beat Saber, Clockwork, COMPOUND, Cosmodread, Down the Rabbit Hole, Drunkn Bar Fight and 11 more.
 - **Suggested by launch-test signatures:**
   - `unreal-msrtt-crash` (fatal): The game's graphics crashed a few seconds after start.
 - **Source:** [patches/frame/vrapi_bridge.py](../src/frameport/patches/frame/vrapi_bridge.py)
@@ -878,7 +957,7 @@ Lets older Unity games start VR without Meta's system apps (they'd stay on a 2D
 - `frame.unity_oculus_check` · revision 5
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Unity with built-in Oculus support: it checks for Meta's system apps before starting VR, else it runs as a 2D app (for example Accounting+, BattleSisters).
-- **Catalog games (9):** Accounting+, Audica, BattleSisters, Cosmodread, End Space, Jurassic World Aftermath Collection, Sniper Elite VR, SUPERHOT VR and 1 more.
+- **Catalog games (10):** Accounting+, Audica, BattleSisters, Cosmodread, End Space, Jurassic World Aftermath Collection, Shoot The Zombirds VR, Sniper Elite VR and 2 more.
 - **Suggested by launch-test signatures:**
   - `unity-vr-device-none` (fatal): Unity didn't start VR, so the game runs as a hidden 2D app.
 - **Source:** [patches/frame/unity_oculus_check.py](../src/frameport/patches/frame/unity_oculus_check.py)
@@ -892,7 +971,7 @@ Keeps a smoothing setting off that the game turns on itself and that can freeze
 - `frame.unity_runtime_msaa_off` · revision 2
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** GLES Unity game whose OVRManager turns 4x MSAA on at runtime: multisampled render-to-texture can hang the Frame's GPU.
-- **Catalog games (17):** Audica, BattleSisters, Beat Saber, Clockwork, Cosmodread, Down the Rabbit Hole, End Space, Gravity Lab and 9 more.
+- **Catalog games (24):** Audica, BattleSisters, Beat Saber, Clockwork, COMPOUND, Cosmodread, Down the Rabbit Hole, Drunkn Bar Fight and 16 more.
 - **Suggested by launch-test signatures:**
   - `unity-render-crash` (fatal): The game's graphics crashed, so the picture freezes or stays gray.
   - `unity-runtime-msaa` (info): The game turns MSAA on at runtime, which can hang the Frame's GPU.
@@ -908,11 +987,25 @@ Lets you type into this app's text fields on the Frame (they'd close at once).
 - `frame.unity_text_input` · also for 2D apps
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Unity app with text fields (…): they close at once on the Frame because it has no system keyboard.
-- **Catalog games (58):** AgeOfJoy, AllInOneSports, Ancient_Dungeon, Audica, BattleSisters, Beat Saber, Beat Saber (co-existence build), Blade & Sorcery: Nomad and 50 more.
+- **Catalog games (73):** AgeOfJoy, AllInOneSports, Ancient_Dungeon, Arkio, Audica, BattleSisters, Beat Saber, Beat Saber (co-existence build) and 65 more.
 - **Source:** [patches/frame/unity_text_input.py](../src/frameport/patches/frame/unity_text_input.py)
 
 > 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 -&gt; false and isKeyboardUsingEvents (TMP) / InPlaceEditing (uGUI) -&gt; 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.
 
+### <a id="frame-unity_tls_key_pool"></a>Unity: share thread keys (games that run out of them)
+
+Lets Unity 6 games with many native libraries start when they run out of thread keys (they'd abort with "cannot create thread specific key"), for example Wander.
+
+- `frame.unity_tls_key_pool` · also for 2D apps
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Offered (off):** Unity 6 with …: turn on if the game aborts at start with "cannot create thread specific key" (for example Wander).
+- **Catalog games (1):** Wander.
+- **Suggested by launch-test signatures:**
+  - `pthread-keys-exhausted` (fatal): The game ran out of thread keys (Android allows 128 per process; Unity 6 plus large native libraries such as Firebase or Gecko, and the Frame's own graphics/OpenXR libraries, use them up), so a library aborted at start (for example Wander in Firebase's Firestore).
+- **Source:** [patches/frame/unity_tls_key_pool.py](../src/frameport/patches/frame/unity_tls_key_pool.py)
+
+> Android gives a process 128 thread keys (pthread keys, per-thread storage slots). Unity 6 takes about 40, and on the Frame the graphics and OpenXR libraries take more than on a Quest, so games with many other native libraries run out: Wander aborted at start ("cannot create thread specific key" in Firebase). Unity's keys without a clean-up function become slots behind one real key (libfp_tkeys.so); every other key and every other library keep real ones. Approach by Klownicle (GitHub #198).
+
 ### <a id="frame-unity_user_presence"></a>Unity: headset always counts as worn
 
 Counts the headset as worn, so games that only move the player while it's worn get head tracking and controls (for example BONELAB).
@@ -939,6 +1032,20 @@ Stops a crash a few seconds after start in some Unreal games with anti-aliasing
 
 > Loads the GL shim into an Unreal GLES game and hides GL_EXT_multisampled_render_to_texture. Unreal's mobile MSAA renders through multisampled render-to-texture, and the Frame's GL driver (Mesa/Zink) can crash on it: SIGSEGV with fault address 0x10000 in libgallium_dri.so on the RHIThread a few seconds after start (Zink looks up a render-pass cache slot past its end, for example Star Wars Pinball VR). Hidden, Unreal renders without that path. Unreal's multiview stays on: Unreal only uses it when GL_OVR_multiview_multisampled_render_to_texture is listed too, so for Unreal the shim keeps that one visible and draws its multiview MSAA attachments single-sampled (glFramebufferTextureMultiviewOVR).
 
+### <a id="frame-unreal_multiview_depth"></a>Unreal: match multiview depth to the eye size
+
+Shows the full environment when its upper part is clipped but menu panels look correct.
+
+- `frame.unreal_multiview_depth`
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Catalog games (1):** Star Wars: Tales from the Galaxy's Edge.
+- **Suggested by launch-test signatures:**
+  - `unreal-multiview-depth-size` (warning): The measured multiview depth attachment keeps the initial Android window dimensions and clips the taller eye color target (Tales from the Galaxy's Edge, issue 61).
+- **Source:** [patches/frame/unreal_multiview_depth.py](../src/frameport/patches/frame/unreal_multiview_depth.py)
+
+> Some UE4 games keep the initial Android window size for their stereo depth buffer, clipping the upper part of the environment while menu panels look correct. Refreshes the cached depth dimensions from the current eye render target before allocation. Preserves multiview and multisampling. Verified in Tales from the Galaxy's Edge 1.1.9; changes one branch only when the function size and surrounding code match.
+
 ### <a id="frame-unreal_ovrp_entrypoints"></a>Unreal: stand-ins for OVRPlugin functions OVRPort lacks
 
 Lets older Unreal games start VR on the Frame (for example Star Wars Pinball VR).
@@ -946,7 +1053,7 @@ Lets older Unreal games start VR on the Frame (for example Star Wars Pinball VR)
 - `frame.unreal_ovrp_entrypoints`
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Unreal looks up OVRPlugin function(s) OVRPort's OVRPlugin lacks: ……. Without them Unreal starts no VR.
-- **Catalog games (1):** Star Wars Pinball VR.
+- **Catalog games (2):** Ghostbusters: Rise of the Ghost Lord, Star Wars Pinball VR.
 - **Source:** [patches/frame/unreal_ovrp.py](../src/frameport/patches/frame/unreal_ovrp.py)
 
 > Unreal's Oculus module looks up every OVRPlugin function it was built against and starts no VR when one is missing; OVRPort's OpenXR OVRPlugin lacks some old ones (for example ovrp_GetPTWNear, which Unreal 4.25 builds like Star Wars Pinball VR look up). The game then never starts an OpenXR session and crashes a few seconds in. Adds a generated library to libOVRPlugin.so with a stand-in for each missing function that reports failure (ovrpFailure), so Unreal's Oculus support starts. The functions OVRPort has are untouched.
@@ -982,12 +1089,40 @@ Starts Unreal games without re-checking their data file (they'd seem to hang on
 - `frame.unreal_skip_obb_check` · also for 2D apps
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Unreal checks the OBB's contents before starting (bVerifyOBBOnStartUp); on the Frame a failed or slow check can't be seen and the game seems to hang.
+- **Catalog games (3):** Dance Central, Kill It With Fire VR, MacacoVR.
 - **Suggested by launch-test signatures:**
   - `unreal-obb-check-stuck` (fatal): The game stays on Unreal's OBB check screen (DownloaderActivity), which the Frame doesn't show, and never starts VR (for example Contractors, GitHub #159).
 - **Source:** [patches/frame/unreal_obb_check.py](../src/frameport/patches/frame/unreal_obb_check.py)
 
 > Unreal games can check their whole data file (.obb) before starting (bVerifyOBBOnStartUp). On the Frame that check's progress and error screens are invisible (Lepton runs VR games without an Android window), so the game seems to hang on its DownloaderActivity, for example Contractors. This turns the check off in the manifest; Unreal still checks that the OBB is there with the right size, so a missing or wrong-version OBB still stops the game.
 
+### <a id="frame-unreal_skip_obb_delivery"></a>Unreal: skip the OBB delivery check
+
+Skips a separate data-file check when an Unreal game still hangs at startup with the content check off. Experimental; the game still needs its data.
+
+- `frame.unreal_skip_obb_delivery` · experimental · also for 2D apps
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Suggested by launch-test signatures:**
+  - `unreal-obb-check-stuck` (fatal): The game stays on Unreal's OBB check screen (DownloaderActivity), which the Frame doesn't show, and never starts VR (for example Contractors, GitHub #159).
+- **Source:** [patches/frame/unreal_obb_check.py](../src/frameport/patches/frame/unreal_obb_check.py)
+
+> Unreal's Java OBB delivery check can leave a game on an invisible DownloaderActivity screen even with the manifest CRC check off (e.g. Into The Radius). Makes known Unreal expansionFilesDelivered methods return true, bypassing the Java name and size gate. Experimental: the native engine still needs complete, matching, readable OBB data.
+
+### <a id="frame-unreal_splash_bypass"></a>Unreal: bypass the stalled loading splash
+
+Lets the game finish loading when its separate loading splash stalls the render thread.
+
+- `frame.unreal_splash_bypass`
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Catalog games (1):** Star Wars: Tales from the Galaxy's Edge.
+- **Suggested by launch-test signatures:**
+  - `unreal-splash-frame-stall` (error): Unreal's map loading waits for rendering while its separate Oculus splash waits for an unbegun VR frame (Tales from the Galaxy's Edge, issue 61).
+- **Source:** [patches/frame/unreal_splash.py](../src/frameport/patches/frame/unreal_splash.py)
+
+> Some UE4 Oculus games stall during map loading: the game waits for the render thread, and the separate loading splash waits for an unbegun VR frame. Bypasses the splash renderer so loading finishes; the last image stays visible during loading. The normal environment and menu rendering continue. Verified in Tales from the Galaxy's Edge 1.1.9; changes one instruction only when the function size and prologue match.
+
 ### <a id="frame-unreal_thumb_touch"></a>Unreal: thumb follows the capacitive touches
 
 Makes the hands' thumbs follow what your thumb touches (they always pointed up: the Frame doesn't sense a thumb hovering, for example Vader Immortal).
@@ -1000,6 +1135,18 @@ Makes the hands' thumbs follow what your thumb touches (they always pointed up:
 
 > Unreal 4's Oculus input sets the ThumbUp axis (games animate the hand's thumb with it) from Meta's near-touch sensing, which the Frame never reports: the thumb always points up. Uses the touches instead (left X/Y/stick/thumb rest, right A/B/stick/thumb rest). Changes three instructions in OculusInput::SendControllerEvents, only where the code matches exactly (UE4 Oculus games of one engine generation, for example Vader Immortal, Robo Recall). Found by Klownicle (GitHub #49).
 
+### <a id="frame-vermillion_scene_canvas"></a>Vermillion: paint canvases in the scene
+
+Keeps the hand and brush visible over Vermillion's painting canvas (the canvas is drawn in the scene instead of as a layer in front).
+
+- `frame.vermillion_scene_canvas`
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Catalog games (1):** Vermillion.
+- **Source:** [patches/frame/vermillion_canvas.py](../src/frameport/patches/frame/vermillion_canvas.py)
+
+> Vermillion shows a canvas being painted as a separate compositor layer, which the Frame draws in front of everything: the hand and brush disappear over the canvas while they still paint. Rewrites PaintableMesh.HasCompositorLayerAvailable and ShouldUseCompositorOverlay -&gt; false in libil2cpp.so (found with Cpp2IL), so the game uses its own fallback and draws the canvas in the scene. The canvas may look a little less sharp.
+
 ### <a id="frame-vivox_audio_route"></a>Vivox voice chat: skip Android 12 audio routing
 
 Lets games with Vivox voice chat start on the Frame (they'd crash on an Android 12 audio call).
@@ -1007,6 +1154,7 @@ Lets games with Vivox voice chat start on the Frame (they'd crash on an Android
 - `frame.vivox_audio_route` · also for 2D apps
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Vivox voice chat: it calls Android 12 audio methods, which Lepton (Android 11) lacks, and crashes.
+- **Catalog games (1):** Dungeons of Eternity.
 - **Suggested by launch-test signatures:**
   - `vivox-api31` (fatal): The game's Vivox voice-chat SDK calls Android 12 audio-routing methods (AudioManager communication devices) without checking the Android version; Lepton runs Android 11, so the app crashes (for example Green Hell VR).
 - **Source:** [patches/frame/vivox_audio_route.py](../src/frameport/patches/frame/vivox_audio_route.py)
@@ -1040,6 +1188,7 @@ Lets games built on Meta's oldest VR interface run on the Frame.
 - **Catalog games (3):** BlazeRush, Path of the Warrior, The Climb 2.
 - **Suggested by launch-test signatures:**
   - `direct-vrapi` (warning): The game uses Meta's VrApi directly and needs the VrApi bridge.
+  - `vrapi-frame-rejected` (fatal): The VrApi bridge rejected the game's frame options, so no picture reaches the headset even though frame pacing can appear in the log.
 - **Source:** [patches/frame/vrapi_bridge.py](../src/frameport/patches/frame/vrapi_bridge.py)
 
 > 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 (for example The Climb 2, Path of the Warrior); OVRPort cannot translate those.
@@ -1278,6 +1427,35 @@ Logs details when one eye looks wrong. No effect on the game.
 
 > For one eye looking wrong (for example 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.
 
+### <a id="adapter-fade_quad"></a>Draw fades over the picture
+
+For games whose fades to black don't show, so you see the level loading (for example Batman: Arkham Shadow).
+
+- `adapter.fade_quad`
+- **Changes:** Game setting: stored in the build and on the Frame (settings.conf); can be changed without a rebuild.
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Options:**
+  - Value: int, default `0`.
+  - Game settings → Picture → "Draw fades over the picture" (advanced).
+- **Catalog games (2):** Batman: Arkham Shadow, Marvel's Iron Man VR.
+- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
+
+> Games that fade to black by dimming their picture with a layer color scale (XR_KHR_composition_layer_color_scale_bias, for example Batman: Arkham Shadow's loading screens) can show the level loading instead of black on the Frame. FrameBridge then draws the fade itself: a black quad in front of the eyes whose opacity follows the game's dimming. 2 also removes the game's own dimming (if both show, the fade is doubled).
+
+### <a id="adapter-flip_dump"></a>Upside-down panel images (diagnostics)
+
+Saves a few UI panels before and after FrameBridge turns them upright, for testing without the headset.
+
+- `adapter.flip_dump`
+- **Changes:** Game setting: stored in the build and on the Frame (settings.conf); can be changed without a rebuild.
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Options:**
+  - Value: int, default `0`.
+  - Game settings → Troubleshooting → "Upside-down panel images (diagnostics)" (advanced).
+- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
+
+> Saves the first N UI panels that FrameBridge turns upright (Vulkan games whose panels are stored upside down), before and after the flip, as fb_flip_&lt;n&gt;_raw.ppm / fb_flip_&lt;n&gt;_upright.ppm in the game's files folder on the Frame. Shows what the runtime gets without anyone wearing the headset.
+
 ### <a id="adapter-flip_emul"></a>Fix upside-down menus
 
 Turns menus and text the right way up.
@@ -1352,6 +1530,21 @@ Hides a Quest-only way of saving GPU power that the Frame lacks. Leave it on.
 
 > Hides Quest foveation extensions the Frame runtime lacks.
 
+### <a id="adapter-gl_error_clear"></a>Clear the game's GL errors (GLES)
+
+For OpenGL ES games whose memory use keeps growing (e.g. Vader Immortal).
+
+- `adapter.gl_error_clear`
+- **Changes:** Game setting: stored in the build and on the Frame (settings.conf); can be changed without a rebuild.
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Options:**
+  - Value: int, default `0`.
+  - Game settings → Troubleshooting → "Clear the game's GL errors (GLES)" (advanced).
+- **Catalog games (3):** Vader Immortal: Episode I, Vader Immortal: Episode II, Vader Immortal: Episode III.
+- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
+
+> Clears OpenGL errors the game left pending before FrameBridge calls the Frame's runtime. The runtime's GL code fails on any pending error; after one such failure at the start it allocated GPU memory every frame without freeing it (e.g. Vader Immortal, ~20 MB a second).
+
 ### <a id="adapter-gl_hide_msrtt"></a>Hide fast anti-aliasing (OpenGL ES)
 
 For Unity games that crash when they turn on anti-aliasing (for example The Room VR).
@@ -1436,7 +1629,7 @@ For games that freeze the Frame when a controller vibrates (for example Lucky's
 - **Options:**
   - Value: int, default `0`.
   - Game settings → Controllers → "Fix freezes when controllers vibrate" (advanced).
-- **Catalog games (44):** AgeOfJoy, Ancient_Dungeon, Audica, BattleSisters, Caves, Clockwork, Cosmodread, cubism and 36 more.
+- **Catalog games (66):** AgeOfJoy, Ancient_Dungeon, Audica, BattleSisters, Beat Saber, Caves, Clockwork, COMPOUND and 58 more.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
 > 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 (for example Lucky's Tale's save slots, GitHub #9). Needs a rebuild.
@@ -1614,7 +1807,7 @@ For games whose hands trail the controllers when you move them (for example Batt
 - **Options:**
   - Value: int, default `0`.
   - Game settings → Controllers → "Fix hands lagging behind controllers" (advanced).
-- **Catalog games (8):** BattleSisters, Phantom: Covert Ops, Robo Recall, Star Wars: Tales from the Galaxy's Edge, Time Stall, Vader Immortal: Episode I, Vader Immortal: Episode II, Vader Immortal: Episode III.
+- **Catalog games (11):** BattleSisters, Beat Saber, Dance Central, Dungeons of Eternity, Phantom: Covert Ops, Robo Recall, Star Wars: Tales from the Galaxy's Edge, Time Stall and 3 more.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
 > Poses a game asks for at a CLOCK_MONOTONIC time, or more than 0.5 s before the frame's display time, are located at the same moment in the runtime's time (or now). Meta's OVRPlugin passes the monotonic clock on as the OpenXR time, which on the Frame runs seconds behind the runtime's clock, so its "now" poses (Unity's physics step, controller poses) came from the past: hands trailing the controllers (for example BattleSisters, Sniper Elite VR).
@@ -1671,7 +1864,7 @@ How often the picture updates. Higher is smoother if the game can keep up.
 - **Options:**
   - Value: float, default `0.0`.
   - Game settings → Picture → "Refresh rate": Game's choice (`0`), 72 Hz (`72`), 80 Hz (`80`), 90 Hz (`90`), 96 Hz (`96`), 108 Hz (`108`), 120 Hz (`120`), 144 Hz (`144`).
-- **Catalog games (2):** Does it Stack?, Vacation Simulator.
+- **Catalog games (3):** Does it Stack?, Majora's Mask VR, Vacation Simulator.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
 > Display refresh rate for this game (72, 80, 90, 96, 108, 120 or 144; 0 = the game's choice). A video's frame rate that divides the refresh rate plays smoothest (for example 30 fps at 90 Hz, 24 fps at 72 Hz).
@@ -1744,7 +1937,7 @@ Mixed-reality games that build their level from your room get a simple room with
 - **Options:**
   - Value: int, default `0`.
   - Game settings → Mixed reality → "Pretend room layout".
-- **Catalog games (1):** Demeter.
+- **Catalog games (4):** Arkio, Demeter, Ghostbusters: Rise of the Ghost Lord, Vermillion.
 - **Suggested by launch-test signatures:**
   - `scene-missing` (warning): The game wants Meta's room data (scene API), which the Frame lacks.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
@@ -1810,7 +2003,7 @@ For games whose menus or screens jump to wherever you look.
 
 ### <a id="adapter-strip_color_bias"></a>Drop layer color fades
 
-For games whose memory use keeps growing (for example Vader Immortal). Some fades no longer show.
+Diagnostics: removes layer color fades. Some fades no longer show.
 
 - `adapter.strip_color_bias`
 - **Changes:** Game setting: stored in the build and on the Frame (settings.conf); can be changed without a rebuild.
@@ -1820,7 +2013,7 @@ For games whose memory use keeps growing (for example Vader Immortal). Some fade
   - Game settings → Troubleshooting → "Drop layer color fades" (advanced).
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
-> 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, for example Vader Immortal leaked ~20 MB/s on its loading screen. Fades done this way no longer show.
+> Removes the color scale/bias (XR_KHR_composition_layer_color_scale_bias) from the game's layers, so the runtime doesn't apply it (diagnostics). Fades done this way no longer show.
 
 ### <a id="adapter-strip_depth"></a>Strip depth layers
 
@@ -1854,7 +2047,7 @@ Shows videos that games play on a flat panel (for example an intro video).
 
 Shows Batman: Arkham Shadow's cutscenes; set by that game's recipe.
 
-- `adapter.surface_native`
+- `adapter.surface_native` · revision 4
 - **Changes:** Game setting: stored in the build and on the Frame (settings.conf); can be changed without a rebuild.
 - **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
 - **Options:**
@@ -1905,7 +2098,7 @@ For games that crash right after you return to them (for example after the Steam
 - **Options:**
   - Value: int, default `0`.
   - Game settings → Troubleshooting → "Steady controller input after focus" (advanced).
-- **Catalog games (2):** Batman: Arkham Shadow, Myst.
+- **Catalog games (3):** Batman: Arkham Shadow, Myst, Robo Recall.
 - **Suggested by launch-test signatures:**
   - `runtime-input-crash` (fatal): The Frame's runtime crashed in its controller code, usually right after the game got focus. sync_guard runs input syncs (xrSyncActions) one at a time and pauses them briefly after focus returns.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
@@ -2073,24 +2266,27 @@ Puts settings files next to the game on the Frame, for example to turn off an un
 
 - `device.files` · also for 2D apps
 - **Changes:** Install only: written on the Frame when the game is installed; the APK isn't changed.
-- **Suggested (on):** CryEngine: variable-rate shading isn't supported on the Frame, so user.cfg turns it off (r_variable_rate_shading = 0; for example The Climb 2).
+- **Suggested (on):** CryEngine: variable-rate shading isn't supported on the Frame, so user.cfg turns it off (… = 0; The Climb / The Climb 2).
 - **Options:** `files`: text, default none — path relative to files/ -&gt; content
 - **Catalog games (2):** SUPERHOT VR, The Climb 2.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
 > Writes config files into the game's Android/data/&lt;package&gt;/files/ on the Frame, to turn off engine features the Frame doesn't support (for example a CryEngine user.cfg with r_variable_rate_shading = 0, as The Climb 2 needs).
 
-### <a id="device-foveation"></a>Eye-tracked foveation (Valve)
+### <a id="device-foveation"></a>Foveated rendering (Valve)
 
-Try Fixed or Off if one eye shimmers or jitters while menus look fine.
+Render less detail outside your gaze; adjust the full-resolution area or darken coarse regions to test it.
 
-- `device.foveation`
-- **Changes:** Install only: written on the Frame when the game is installed; the APK isn't changed.
+- `device.foveation` · experimental · revision 3
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
-- **Options:** `mode`: str, default empty — fixed or off (empty = Valve's default)
+- **Options:**
+  - `mode`: str, default empty — tracked, fixed or off (empty = Valve's default)
+  - `radius`: float, default `0.0`, 0–0.45 — Full-resolution radius; 0 keeps the current runtime default
+  - `test`: bool, default `False` — Darken lower-resolution regions (diagnostic)
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
-> 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).
+> Reduces shading away from the full-resolution area, following each eye's gaze. Default area size keeps the runtime's current profile unchanged. Custom radius is a fraction of the shorter eye-image dimension; the transition ends at twice that radius. Larger areas retain more detail but save less GPU work. Fixed stops the area following your eyes. The optional test darkens actual coarse-shaded fragments; rebuild/reinstall to toggle it. Tested on RE4, Deadpool and Asgard's Wrath 2. The Climb 2 gets a version-guarded private bridge at 1.0 scale; Batman gets its hash-verified allocation fix (unsupported OVRPlugin versions are refused). Other games may need additional fixes; turn this off if artifacts appear.
 
 ### <a id="device-hide_navbar"></a>Hide Android's navigation bar
 
@@ -2134,7 +2330,7 @@ Lets typing reach this app from Steam's on-screen keyboard or your PC's keyboard
 - `device.text_input_window`
 - **Changes:** Install only: written on the Frame when the game is installed; the APK isn't changed.
 - **Suggested (on):** App with text fields: key presses only reach a shown Android window.
-- **Catalog games (58):** AgeOfJoy, AllInOneSports, Ancient_Dungeon, Audica, Beat Saber, Beat Saber (co-existence build), Blade & Sorcery: Nomad, BodyCombat and 50 more.
+- **Catalog games (76):** AFFECTED: The Manor, AgeOfJoy, AllInOneSports, Ancient_Dungeon, Arkio, Audica, Beat Saber, Beat Saber (co-existence build) and 68 more.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
 > 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".

docs/PLAYBOOK.md

@@ -5,7 +5,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 
 ## Fast path for a new game
 1. `frameport scan <folder>` → check the suggested recipe (`frameport show <pkg>`). Direct-VrApi engines get the bridge.
-2. `frameport build <pkg>` → all static checks must pass (32-bit-only → stop, it can't run).
+2. `frameport build <pkg>` → all static checks must pass (32-bit-only → `frame.a32_bridge`, experimental).
 3. `frameport install <pkg>` → `frameport test <pkg>`: want **RUNNING** + "Submitting frames" at ~72 fps.
 4. Put the headset on and look. Headless tests can't judge visuals (no FOCUSED state without the headset worn).
 5. Fix by symptom below, rebuild, repeat. When it's good: **Save as known-good** (GUI) or add a catalog YAML.
@@ -13,12 +13,22 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 ## Startup failures (visible in launch.log)
 | Symptom | Cause | Fix |
 |---|---|---|
+| Startup exits through `libxlua.so (lj_err_throw)`, then Unity aborts in mutex cleanup; captured Lua error is `bad light userdata pointer` (GitHub #257, BattleTalent 4.7) | This older LuaJIT encodes lightuserdata in 47 bits; Frame supplies valid wider native pointers. Controlled tests with the unchanged library pass a real low-address allocation and fail its own high-address static pointer | `frame.luajit_pointers` automatically selects a full-pointer Lua engine only for the verified library SHA-256, retaining xLua bindings and custom helpers. The scoped patch reaches OpenXR startup for 60 s headless; rendering and gameplay remain unverified. A `lj_err_throw` cleanup stack without the original error message is insufficient to infer this cause |
+| A GL4ES Team Beef game draws stretched triangles or spikes across characters and the scene (GitHub #191, Lambda1VR) | The newer GL shim exports GLES draw functions that intercept GL4ES's desktop OpenGL calls, bypassing its client-array and immediate-mode translation | `frame.tbxr_vendor` keeps the shim's five draw symbols private when the APK bundles `libgl4es.so`. GL queries and single-sampled framebuffer fixes remain active; other games retain the draw hooks. A/B eye captures on SteamOS 0.4.5: old shim normal, current shim spikes, current shim with private draw symbols normal at ~72 fps. Worn-headset gameplay still needs confirmation |
+| A Team Beef game reports a crash after manually quitting: `fdm_injection_xrDestroySwapchain` → `TBXR_LeaveVR` (GitHub #191, Lambda1VR) | Valve's foveation layer dereferences a null pointer during swapchain cleanup | Triage `tbxr-fdm-shutdown-crash` identifies this as a teardown crash, separate from startup and distorted geometry. No verified cleanup fix yet |
+| Conversion fails with `NoSuchElementException: Sequence is empty` in `PatcherContext.appName` (GitHub #269, Accounting+) | OVRPort assumes an application label exists; some APKs only label their activity | FramePort retries that exact failure once using a temporary APK whose application inherits the activity's label; existing labels and the original APK are kept |
+| Updating a flat Android app after saving its recipe fails with `no OVRPort patches selected` (GitHub #271, Plezy) | older FramePort loads the saved recipe without restoring its unchanged-install setting or applying the flat-app build rules, then tries an empty VR conversion | update FramePort: saved recipes keep `as_is`, and flat apps still skip OVRPort; existing catalog-derived recipes refresh at the next app update. Until then, enable "Install as is" for an app whose APK needs no fixes |
 | A launch test suggests a patch (for example triage `sdl-no-clipboard` → `frame.sdl_clipboard`) but the game page doesn't show it / lists it as not applicable; or a game added long ago lacks warnings newer ones get (Android version, web wrapper, missing OBB) (GitHub #104, Dramatic Shape) | the library entry was analyzed by an older FramePort: the analysis field the patch reads (`sdl_java`, `min_sdk`, `web_wrapper`, `expects_obb`, …) is missing, so `applies()` is false | entries whose `analysis.extra.analysis_version` is below `detect.ANALYSIS_VERSION` are analyzed again at the GUI's start (background) and before a build (`pipeline.refresh_analyses`); by hand: game menu → "Analyze again", then Update on Frame. An unreadable APK is marked `analysis_failed` (retried after the next version bump). Adding an analysis field: bump `ANALYSIS_VERSION` |
-| One eye (usually the right) shimmers or jitters in the 3D view while menus and panels look steady; pacing is clean (GitHub #69, for example 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:` |
+| FDM layer loads but diagnostic logging reports `fdm_injection_CreateInstance: skipped` | Layer loading alone does not enable injection on the tested SteamOS 0.4.5 build; a skipped helper instance alone also does not establish game-wide inactivity | Opt-in `device.foveation` mode `tracked`: loads Valve's layer and sets `FDM_DEBUG=enable`. Batman probe reached foveated render passes with changing per-eye offsets. Validate graphics and matched gameplay GPU time; do not enable globally. Use `debug` only for brief diagnostics, preserving existing flags; never benchmark with debug spam. See FRAME_RUNTIME.md. |
+| 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`; verify injection remains active on the installed runtime) 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) |
+| Black screen after VR starts; `Asset status error  (code 100)` in `DLC_Manager:AssetStatusCallback` (GitHub #203, e.g. PixelRipped 1995) | Meta asset-file status fails after entitlement succeeds; the log does not identify the native call or asset ID | Try `frame.asset_files_stub` (opt-in, triage-only): native/langpack answers GetList with an empty successful list and StatusById with installed status, an empty path and the requested ID. No DLC files are supplied; download requests retain their existing behavior. Disable with `FRAMEPORT_ASSET_FILES_STUB=0`. Host-tested only; whether this fixes startup needs a game/device test |
+| Missing sound or extra content in a game whose OBB folder has separate `*.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 list them | copy every content/sound-bank PAK and use `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). Tales also needs the splash and depth-size fixes below |
+| A SideQuest backup has `apk/` and a sibling `obb/` with content/sound-bank PAKs, but the Frame only has the main OBB (GitHub #61, Tales from the Galaxy's Edge) | older scans treated that layout as loose expansion files and selected only the named OBBs; the asset-file patch then found no PAKs | the scanner chooses the OBB folder by version first, then keeps the whole sibling data folder when all its expansion files are selected for this APK; app updates repair affected library entries and refresh asset/language-pack detection. Reinstall to copy the missing files, or scan the backup again first. Folders with other packages or unselected OBB versions still send only the selected OBBs |
+| Tales from the Galaxy's Edge stops during map loading (GitHub #61): game thread in `FlushRenderingCommands` / `UEngine::LoadMap`, render thread in `FSplash::RenderFrame_RenderThread` / `ovrp_WaitToBeginFrame` / SteamVR `WaitFrame` | the separate Oculus loading splash waits for an unbegun frame while map travel waits for rendering | `frame.unreal_splash_bypass`: returns from the splash renderer, with a checked symbol, size and prologue. The last image stays visible during loading; the normal renderer and menu layers continue. Headset test with the depth-size fix: gameplay, both eyes, controller input and sound work |
+| Upper part of the intro/environment is black or clipped, but a separate menu panel is intact (GitHub #61, Tales from the Galaxy's Edge) | `FSceneRenderTargets::AllocMobileMultiViewDepth` caches the initial Android window dimensions (1920x1016/1020), leaving the depth attachment shorter than the eye color texture (1728x1728); drawing is limited by the smaller attachment | `frame.unreal_multiview_depth`: refreshes both cached depth dimensions from the current scene `BufferSize` before allocation. Checks the exported symbol, function size and surrounding instructions, then replaces only the branch that skips refresh. Keeps multiview and multisampling. Headset test: full view and gameplay work |
 | `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 |
@@ -31,13 +41,15 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | An overlay app (fpsVR, a wrist watch) installed on the Frame never appears, or SteamVR doesn't start it | not registered with the Frame's SteamVR, or registered with a manifest SteamVR skips: on the Frame vrserver reads only `binary_path_linux_arm` (vrserver.txt: "must specify binary_path for launch_type binary. Skipping") | `pcvr.vr_overlay` (Windows) / a Linux app with a bundled `.vrmanifest` (`is_dashboard_overlay`): agent v75 `register_vr_overlay` (check `vrcmd --overlays`, `~/.config/openvr/config/appconfig.json` manifest_paths); the app's own `--install` writes binary_path_linux only. fpsVR under Proton never loads OpenVR (quits after 60 s): unsupported for now |
 | An overlay app with **Start with SteamVR** on doesn't start by itself after the Frame or SteamVR starts (it works when started by hand) | SteamVR's own auto-launch flag (SetApplicationAutoLaunch) didn't persist on the Frame (no autolaunch entry in `~/.config/openvr/config/steamvr.vrsettings`) | agent v76: FramePort's service `frameport-vr-overlays.service` starts it at every new vrserver. Check `systemctl --user status frameport-vr-overlays`, `~/.local/share/frameport/vr-overlays.log` (`new SteamVR (vrserver N)` → `<pkg>: started` / `running` / `couldn't start it: …`), the deployment's `overlay.autostart`, and that `~/.local/share/frameport/vr-overlays.disabled` doesn't exist; `frameport frame info` (ensure_host_fixes) installs a missing service |
 | 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 |
+| Launch test "failed" although the game runs in the headset: frames paced, then `OVRPortVrApi: EnterVrMode: no tracked head pose before deadline`, then a crash (e.g. `zink: DEVICE LOST` + SIGSEGV in a `gdrv` thread) (GitHub #57, BlazeRush) | the VrApi bridge ends the VR session after 30 s without head tracking, which only happens without a worn headset; the game's renderer then crashes while tearing down | none needed: launch tests (`triage(..., headless=True)`) treat an exit or crash after a `headless_end` line (catalog/triage.yaml) as a pass when frames were paced before it (info finding `headless-end`); play sessions ignore it. Add new such markers to `headless_end` |
 | Launch test EXITED, launch.log has `Target app (<pkg>) did not start` and no `Start proc …:<pkg>` (GitHub #179) | Lepton occasionally doesn't start the app on the first start after an APK change; Android's `WebViewLoader-: System.exit` at boot is not the game (triage `app-not-started`) | start it again |
 | A game keeps no progress between starts although it saves (its storage gets a new `Profiles/Oculus/<id>/`-style folder per start; Walkabout Mini Golf, GitHub #182) | OVRPort's platform loader answers `ovr_GetLoggedInUserID` with a made-up id (6e18 + `random()`), new at every start; games file saves under the user id | `frame.ovr_stable_user` (default for games with the platform library): a fixed id per game and keystore. Old progress: copy the newest old profile into the new id's folder |
 | A Unity app's text field shows a caret for a moment and loses focus; no keyboard appears (for example Stremio VR login) | Unity's TMP_InputField/InputField wait for Android's on-screen keyboard and close themselves without one (Lepton has none); headless VR apps also have no focused Android window, so no key press reaches them | `frame.unity_text_input` (Cpp2IL finds `TouchScreenKeyboardShouldBeUsed`/`isKeyboardUsingEvents`, rewritten to false/true) + `device.text_input_window` (lepton-show-flatscreen: Steam's keyboard and Type on Frame work) |
-| Play gives Steam's "Game configuration unavailable"; Steam's console_log: `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` | this Frame's Steam never loaded FramePort's shortcuts.vdf entry (it treats the id as a store app); cause unknown (GitHub #21/#30) | automatic since agent v43: Play registers the game through Steam's devkit interface ("Devkit Game: …", `devkit_register`) and starts that; uninstall removes it. Agent v58: a devkit entry Steam forgot after a restart is added again live on Play (no NOT_IN_LIBRARY → no Steam restart), and installs/art updates of devkit games only copy art (no Steam restart, GitHub #41) |
+| FramePort's games disappear after Steam restarts, especially after a devkit registration (GitHub #263) | Steam saves `Shortcuts` / `AppName` with capital letters; older FramePort reads them case-sensitively and writes a second shortcut map that Steam ignores | agent v86 reads and updates keys case-insensitively, keeping Steam's spelling, appids and tags; update FramePort and add the missing games to the library again |
+| 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); see the casing fix above, other causes remain unconfirmed (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 (for example 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` (for example SUPERHOT) | The game created a save folder with mode 1700; inside Lepton the app writes through the folder's group | launch.sh `fix_perms` adds owner + group write to every folder in the game's storage (agent 41); reinstall to get the new launcher |
+| The game quits right after start: `Something failed to initialize. Quitting!` / `We don't have write permission to …/files/cloud/data` (for example SUPERHOT); or stays at loading with `UnauthorizedAccessException` in `StartupLoading.Start` (GitHub #239, Jurassic World Aftermath) | The game created a cloud-save folder with mode 1700; inside Lepton the app writes through the folder's group. Its startup routine can fail before the permission watchdog repairs the newly created folder | launch.sh `fix_perms` adds owner + group write to every folder in the game's storage (agent 41). Close and start the game again without uninstalling: the folders are now repaired (Aftermath confirmed in the headset). Agent 84 creates `files/cloud/data` before `fix_perms` and startup, including in upgraded launchers, to prevent the first-start race. Triage `startup-save-permission` fails the launch test despite rendering frames |
 | The whole Frame slows to a halt, then the game is killed (`Out of memory: Killed process … anon-rss:10+ GB`), for example Lucky's Tale | The game's own memory grows ~1 GB/s on Unity's `Loading.PreloadManager` thread (perf page-fault profile); not the flat window, not the text-input patches | none yet: mark unsupported; profile with `perf record -p <pid> -e page-faults --call-graph fp` (works as steamos, `perf_event_paranoid` 2) |
 | A Linux app exits at once: `cannot execute binary file: Exec format error` in launch.log | an x86_64 program started directly (installed before FramePort ran x86 builds through FEX, or by hand) | reinstall it: x86_64 Linux apps install FEX on the Frame and start through it (agent v61, `kind: linux_x86`; FEX also needs `STEAM_COMPAT_DATA_PATH`: "No compat data path?" in launch.log = an agent v60 launcher, reinstall); triage `linux-x86-no-fex`. Prefer an arm64 build when the app offers one |
 | `APP_ACTIVITY is empty`, nothing starts | Manifest has category INFO only; Lepton needs LAUNCHER | `frame.launcher` (automatic) |
@@ -49,16 +61,26 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Oculus Rift game won't run on the Frame | Oculus/LibOVR game: needs Revive, whose hooks don't work under Proton-arm64, and FramePort won't defeat the Oculus runtime signature check | Play it on this PC (SteamVR + Revive). Only OpenVR/OpenXR-native Rift games run on the Frame |
 | Un-cracked Oculus PC VR game: "Initializing OVR session" then exits / signature check on the runtime | Revive's hooks don't install on Proton-arm64; the Oculus shim rejects the unsigned Revive runtime | Not runnable on the Frame without the repack's crack extracted (not done by FramePort); use the PC version |
 | PC VR game: `Failed to initialize Oculus API (-3001)` / `Unable to load LibOVRRT DLL` | Revive's LoadLibrary hook doesn't work under Proton arm64 (ARM64EC kernelbase); the game's LibOVR shim finds no runtime DLL | Symlink `LibOVRRT64_1.dll` → Revive's DLL in the prefix's system32 (manual so far) → then -3021 (runtime signature check; open) |
-| Uploads to the Frame are slow (~15 MB/s) | PC and Frame both on Wi-Fi through the home router | Connect the PC to the Frame's own hotspot (or a USB cable): FramePort uses the direct link automatically (~80-100 MB/s); job log line "Transfer link" |
+| Uploads to the Frame are slow | The link, storage or transfer backend can limit throughput | Check the job's "Transfer link"; try the Frame's hotspot or USB cable. Large install files prefer system OpenSSH SFTP, retaining paired-host checks and `.part` resume; unavailable or failed native uploads fall back to Paramiko. The log names the backend. Settings → Installing → Parallel uploads accepts 1–8 (default 3; saved preferences are preserved). More is not always faster. Measure the production path with `scripts/upload_bench.py --methods app-files-3 --check-resume` (three repetitions, checksum verification) |
 | PC VR game exits right away: `Unhandled Exception: 0xc06d007e` (after `FOnlineSubsystemOculus::InitWithWindowsPlatform`) | Delay-loaded `LibOVRPlatform64_1.dll` (Oculus Platform SDK, installed with the Oculus app) is missing | None on the Frame (entitlement check; FramePort doesn't replace it). PC mode with the Oculus app |
 | Unity PC VR game (Oculus + SteamVR build: `OVRPlugin.dll` and `openvr_api.dll` in `<Name>_Data/Plugins`) opens a window and quits after ~20 s; no VR Vulkan instance after the game's DXVK device in launch.log; Unity log (`unity log … Player.log`, agent v67): `OpenVR failed initialization` / `Initialization of device … failed` | Unity's built-in VR tries its SDKs in list order (Oculus first) unless `-vrmode` picks one; a catalog recipe verified with another build of the game (for example SUPERHOT VR's OpenXR build, GitHub #105) used to drop the build's own arguments | `pcvr.launch_args` = `-vrmode OpenVR` (detected for such builds; kept when the catalog's `xr` differs from the build's). A game's Electron launcher next to it (SHVR.exe) is ranked below the game |
 | Unreal PC VR game opens the crash reporter instead of closing | UE starts CrashReportClient.exe on a crash | `pcvr.no_crash_reporter` (default for Unreal Rift games): `-nocrashreports` + CrashReportClient.exe renamed `.disabled` in the Frame copy |
 | A backup's game was added without its data (library `data_dir` null, `data_bytes` 0) although the folder has .obb files | The OBBs sit in a layout the scan didn't know: `<game>/obb/<package>/`, `Android/obb/<package>/`, or SideQuest-style `<game>/apk/x.apk` + `<game>/obb/<package>/` | `sources/quest_dump.find_data_dir` finds a `<package>` folder with .obb files ≤3 levels below the APK's folder or ≤2 below its parent (skipping neighboring folders with APKs: other games); an `apk`/`apks` folder counts as part of its game folder. Add the folder again (Analyze again doesn't look for data) |
+| "Failed to correctly load the game files" at the menu; `Error loading FMOD bank "…/Android/obb/<package>/Master.bank": ERROR` (GitHub #239, Jurassic World Aftermath Collection); launch test previously passed at 72 fps | SideQuest's `<package>/<backup time>/apk/x.apk` + `obb/Master.bank` + `obb/Master.strings.bank` backup was scanned without data: these are raw sound banks, not .obb expansion files, so the sibling-folder search missed them | `quest_dump.find_data_dir` checks the parent game folder's `obb/` (or `obbs/`) when the APK is in `apk/` or `apks/`, including raw assets with or without a package subfolder. Add the backup folder again and reinstall; triage `fmod-bank-missing` fails the launch test even when the error screen renders frames. Copy the whole data folder from the same backup as the APK |
 | A game from an AXRB download starts and stops at once (Steam shows Resume), no OBB on the Frame; or a SideQuest backup adds a second game named after an APK in its `obb/` folder (reddit 2026-10-11) | AXRB keeps its own PC builds in `AXRB/patched/<package>/*-axrb.apk` (OVRPort-converted for its runtime, no OBBs); the scan added them over the original `AXRB/<app id>/<binary id>/base.apk`. SideQuest's VR4 backup has Unreal's `VR4-Android-Shipping-arm64.apk` next to the OBBs | `quest_dump._axrb_patched` skips AXRB's patched copies; a rescan replaces entries made from them; AXRB downloads send every non-APK file next to `base.apk` (DLC, assets) and are named after the package; APKs inside another game's data folder are ignored; SideQuest backups are named after the package folder, not the backup time. docs/FAQ.md has both layouts |
 | Game hangs at start / never loads although its .obb files are right there: next to the APK, in an `obb` folder beside an `apk` folder inside a `<package>` folder, or a SideQuest backup (`<timestamp>_<versionCode>.apk`) (GitHub #85, #91) | No folder named after the package, so the folder-layout checks found nothing and no OBB was uploaded | `quest_dump.find_data` then looks for the files by name, `(main\|patch).<versionCode>.<package>.obb` (any case), in the APK's folder, its parent and up to 3 levels below each (folders with their own APKs are other games); prefers the folder and files of the APK's own versionCode, else the newest older, else any version. When that folder also holds other things (the APK itself, other games' OBBs), the library entry gets `data_files` and only those files are uploaded, counted and deleted with the game. Add the folder again |
+| CryEngine game: `Powered by CRYENGINE`, then SIGTRAP in `libAndroidLauncher.so` during `CreateSystemInterface`, before any OpenXR instance (GitHub #238, The Climb 666.0) | Installed without its OBB: the SideQuest backup has `apk/com.crytek.climb.apk` + `obb/main.com.crytek.climb.obb`, but the scan required a versionCode in the OBB name and skipped it. The reported backtrace's fatal-error call formats `Engine initialization failed: Open Engine Paks: Unable to find "engine" pak files (%s)` | `quest_dump.find_data` accepts `(main\|patch).<package>.obb` as well as numbered names, keeping the original filename. Update on Frame finds the previously skipped data; a rescan finds it too. Analysis version 12 recognizes monolithic CryEngine through `assets/game.cryproject`, Vulkan through `assets/system.cfg` (`r_Driver = vk`), and an expected OBB through the launcher's expansion-path format strings; a missing OBB now gets the existing `missing-obb` warning/finding. This fixes the original missing-content startup failure; the rendering failures below were found once the data was installed |
+| The Climb 666.0: audio with no headset picture, `OVRPortVrApi: Unsupported frame flags or swap interval`; then SIGSEGV in `vulkan.freedreno.so` during `vkCmdEndRenderPass` once frames are accepted (GitHub #238) | The game submits the obsolete Quest texture-density debug flag (`0x100`), which the bridge rejected. It also binds the bridge's full-rate texture as a fragment-density attachment even though foveation support is reported off; Turnip reads density maps on the CPU, but an ordinary sampled image has no mapped backing memory | Updated `frame.vrapi_bridge` accepts the compositor debug/volume flags and creates the compatibility texture with `VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT`. Do not gate that usage on the advertised format features (the Frame reports R8G8_UNORM without the density bit). `device.files` selects `r_vr_foveated = 0` when the engine contains that cvar; The Climb 2 keeps `r_variable_rate_shading = 0`. Triage `vrapi-frame-rejected` marks rejected frames as fatal despite pacing logs. Picture confirmed on the headset. With the corrected config, an uncapped launch stayed running for over four minutes at a median 72 fps with no native crash or GPU fault. The user confirmed working menus and gameplay on 2026-10-12 |
 | Unreal game: `JNI_OnLoad` (OVRPlugin), then silence: no OpenXR instance, no crash, no frames (GitHub #85 TRIANGLE STRATEGY; launch-test finding `missing-obb`) | Installed without its OBB: the manifest says `com.epicgames.ue4.GameActivity.bHasOBBFiles` = true (UE5: `com.epicgames.unreal.…`) but the library has no data folder (`data_dir` null, `data_bytes` 0) | Put the .obb files in a `<package>` (or `obb/`) folder next to the APK, add the folder again, reinstall. Analysis `extra.expects_obb`; the game page, the install question and `frameport scan`/`install` warn; launch tests that sent no frames get the `missing-obb` finding from the library (the game logs nothing). Unity split-binary builds count too (`extra.unity_split`, `analysis/unity_split.py`): an XR-plugin build (Oculus XR Plugin / Unity OpenXR library) without `assets/bin/Data/UnitySubsystems/` in the APK, or BuildSettings listing more scenes than the APK has `levelN` files (globalgamemanagers loose or read from the head of data.unity3d); exact on the 48 Unity APKs of the dumps (13 split, 17 full games; OBBs of full builds are asset bundles or sound banks) |
 | Unreal game: launch.log ends with `ActivityTaskManager: START u0 {… cmp=<pkg>/.DownloaderActivity}` and `Displayed <pkg>/.DownloaderActivity`, then nothing: no OpenXR instance, no crash (GitHub #159 Contractors; triage `unreal-obb-check-stuck`, also when the OBB is on the Frame) | Epic's DownloaderActivity (started by GameActivity.onResume before the engine's main init) checks every OBB's name + size compiled into the APK (OBBData); with manifest meta-data `com.epicgames.ue4.GameActivity.bVerifyOBBOnStartUp=true` it then reads the whole OBB and compares each entry's CRC32 (cached in `files/cacheFile.txt` by the OBB's mtime). Its progress and error screens are invisible in Lepton (headless VR); a CRC mismatch waits for a button forever. A missing / wrong-size OBB starts Google Play's downloader (or a "No Google Play Store Key" dialog) and also waits | `frame.unreal_skip_obb_check` (suggested by analysis `unreal_verify_obb`): sets that meta-data to false (one boolean in the manifest, `axml.set_meta_data_bool`), which skips only the CRC pass. Still stuck: the OBB doesn't match the APK version (name `main.<versionCode>.<pkg>.obb` and its size) - copy APK + OBB from the same install |
-| `INSTALL_FAILED_NO_MATCHING_ABIS` | 32-bit-only APK; Frame has no AArch32 | None. PC/Rift version via Revive |
+| Unreal game still stays on `DownloaderActivity` with CRC checking off (`bVerifyOBBOnStartUp=false`) and a fully uploaded matching OBB (GitHub #283, Into The Radius) | The separate Java `expansionFilesDelivered()` name and size gate can reject an OBB through Android external storage in Lepton; disabling CRC does not bypass it | Try `frame.unreal_skip_obb_delivery` (opt-in, experimental, triage-only). It returns true from known Unreal/package delivery predicates in every dex, preserving normal downloader success and main init. Analysis `unreal_obb_delivery` (version 16) controls applicability. The native engine still needs complete, matching, readable OBB data; unverified on a device |
+| `INSTALL_FAILED_NO_MATCHING_ABIS` | 32-bit-only APK (Gear VR / Go / early Quest); Frame has no AArch32 | `frame.a32_bridge` (suggested for every 32-bit-only APK, experimental): the a32 translator runs the game's 32-bit libraries inside the 64-bit app (native/a32translator/bridge) |
+| a32 bridge faults at a low Thumb PC while loading a library, with the same unrelocated pointer in `.init_array` (e.g. Journey of the Gods: `0x1259e9` in OVRPlugin) | The guest loader ignored the older `DT_ANDROID_RELR` / `DT_ANDROID_RELRSZ` tags, leaving relative pointers at their link addresses | Fixed in the guest loader: both Android and standard RELR tags use the existing RELR decoder. Rebuild the a32 runtime and APK; host regression tests cover both tag families, but game startup still needs a Frame run |
+| 32-bit game on the bridge: framerate falls over minutes, purple/garbled geometry, then `Could not allocate memory: System out of memory!` (Spunky Dungeon) | The bridge's guest copies of mapped GL buffers were tracked per buffer target: a second buffer mapped on the same target lost the first one's copy (never written back: garbage vertices; never freed: ~10 MB/s until the guest's 4 GiB were full) | Fixed in the bridge (gl.c: mappings per buffer object). Check: the guest's `[anon:scudo:*]` maps below 4 GiB in /proc/<pid>/maps must stay flat |
+| 32-bit game on the bridge loads, leaves VR and its engine threads end, no crash, no finish() (Gunjack) | The game checks its own APK signature (UE4 `AndroidThunkJava_GetSignature` = Base64 of the signing certificate's SHA-1, compared in AndroidMain): every FramePort build is re-signed | `frame.a32_bridge` stores the original APK's value in `assets/fp_a32_signature.txt` (Unreal games) and the bridge answers the guest's call with it (log `AndroidThunkJava_GetSignature: original signature returned`). Find other such checks with `A32_BREAK` on the game's exit path (vrapi_LeaveVrMode logs its caller) |
+| 32-bit NativeActivity game on the bridge ignores every controller (Gunjack, UE 4.10 Gear VR: no vrapi input functions, it reads the Gear VR touchpad/back button as Android input events from its AInputQueue) | The bridge sent its controller events through `Activity.dispatchKeyEvent`, which a NativeActivity never passes to native code | input.c puts synthetic touchpad (motion, touchscreen source) and back-key events in front of the game's AInputQueue: `ALooper_pollAll/pollOnce` return the queue's ident while one waits, `AInputQueue_getEvent` hands it out, the AInputEvent/AKeyEvent/AMotionEvent imports answer for it. Right trigger = hold the touchpad, A = tap, right stick = swipe (up/down = swipe forward/back along the touchpad's X axis: Gunjack's `OnFlick` takes flick angles <45°/>315° as reload, 135-225° as special weapon), B/left menu = back (log `controllers: the game reads its AInputQueue`) |
+| GLES VrApi game aborts in `vrclient.so` (`CSharedSemaphoreLinux::WaitFromGPU` ← `CSxrGraphicsBindingGLOpenVR::PreBeginFrame`) right after it left VR mode and entered it again (Gunjack after loading) | The Frame's runtime fails the first frame of a second OpenXR session on the same GL context | VrApi bridge: `vrapi_LeaveVrMode` keeps a running GLES session, `vrapi_EnterVrMode` with the same context reuses it (log `Entered VR mode again (kept GLES session)`) |
+| 32-bit Unity game on the bridge: player stands in the floor (Spunky Dungeon) | Unity's floor-level tracking origin: `vrapi_SetTrackingSpace(1)` (LOCAL_FLOOR) was ignored | The VrApi bridge puts the origin on the STAGE floor for LOCAL_FLOOR/STAGE |
 | Crash at start: `NoClassDefFoundError: … Landroid/window/OnBackInvokedCallback;` or `NoSuchMethodError: No static method storeStoreFence()V in class Ljava/lang/invoke/VarHandle;` (GitHub #71/#72, triage `android-too-new`) | The APK needs Android 13+ (minSdk 33 or more; those were 34) and calls its classes at start; Lepton's Android is 11 (API 30). OVRPort lowers minSdk to 29, so it installs anyway. minSdk ≤ 32 (Quest's Android 12L) is fine: 16 working catalog games declare 32 | None (analysis `extra.min_sdk` > 32 → a warning on the game page/CLI and in the recipe notes; never unsupported from the manifest alone, the launch test's triage decides). Waits for Valve to update Lepton's Android |
 | Nothing opens; `TWALauncherActivity: Using URL from Manifest (https://…)`, `Creating TwaLauncher for com.oculus.browser`, `NameNotFoundException: com.oculus.browser` (GitHub #86 Mahjong Table VR, triage `web-wrapper`) | The APK is a Trusted Web Activity (Bubblewrap / Meta's PWA packaging): a website that opens in Meta's browser, which Lepton doesn't have | None: open the URL in a browser. Analysis `extra.web_wrapper` (manifest meta-data `android.support.customtabs.trusted.DEFAULT_URL`, resolved through resources.arsc, or androidbrowserhelper's LauncherActivity) → a warning with the URL (not unsupported: the manifest alone never decides) |
 | `UnsatisfiedLinkError` / `cannot locate symbol "ovr_…"` | overport's platform loader lacks Meta platform functions | `frame.ovrstubs` (automatic, generated stubs) |
@@ -66,6 +88,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | The game stays in its built-in language or waits at start although its OBB / files hold language packs (`<tag>.lang`, for example `de.lang`) | overport's platform loader answers `ovr_LanguagePack_GetCurrent/SetCurrent` with request id 0, so the game never gets the pack's path | `frame.langpacks` (opt-in, experimental, shown for games whose data has `*.lang`; `native/langpack`, build it with `python native/build.py --only langpack`). Default pack: the one the game applies, else env `FRAMEPORT_LANGPACK=<tag>`, else the only pack; search path override `FRAMEPORT_LANGPACK_DIRS`. Unreal games (Deadpool VR) gray out a pack whose asset `Metadata` differs from the game's version string: the patch writes the APK's versionName as Metadata (env `FRAMEPORT_LANGPACK_META` overrides) and reports the pack under the `/storage/emulated/0/Android/obb/<pkg>/` spelling of its path; with `/sdcard/…` the text switched but the dialogue stayed silent (verified in the headset with Deadpool VR) |
 | `ClassNotFoundException com.oculus.os.AnalyticsEvent` → abort | Quest telemetry lookup in Meta XR Audio (Unreal build) or native code | `frame.metaxr_telemetry` + `frame.oculusos` (automatic) |
 | `JNI DETECTED ERROR`, `GetStringUTFChars … NULL` | CheckJNI is on because overport marks the app debuggable | `frame.nodebug` |
+| Unreal game shows a one-time "optimizing" screen on its very first start, then closes (`System.exit` status 0 right after the system log's `ActivityTaskManager: START … LAUNCHER … pkg=<own package> … from uid 10xxx`, Lepton "Exited!"); the next start works | UE 4.21+ restarts the app after its first-run shader precompile (`r.ProgramBinaryCache.RestartAndroidAfterPrecompile`, `AndroidThunkJava_RestartApplication`); Lepton ends the container with the first process, the restarted one with it (Sports Scramble). Skipping the restart or setting the cvar to 0 (`-ini:Engine:[ConsoleVariables]:…` in UE4CommandLine.txt: read, no restart requested) left Sports Scramble on the "optimizing" level for good: the game relies on the restart | launch.sh starts Lepton once more (agent v86 `_restart_requested` matches both log lines within 5 s; `launch-before-restart.log` keeps the first run; `FRAMEPORT_NO_RESTART=1` turns it off). Works for 32- and 64-bit games |
 | 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` (for example The Walking Dead: Saints & Sinners Ch. 2) | OVRPort's platform loader opens the microphone's AAudio stream only in `ovr_Microphone_Start`, but `GetOutputBufferMaxSize` reads that stream unchecked; Unreal's Oculus voice asks for the size right after `Create` | `frame.ovr_microphone` (NULL check rewritten in place; size 0 until the microphone starts). OVRPort runtime 3.4.3-aa54c3f has the check itself: builds made with it leave the patch out (log "not needed: frame.ovr_microphone", `patches/upstream.py`) |
 | `xrCreateSwapchain` -26 / format unsupported (GLES) | Frame takes only sRGB formats, no MSAA | adapter `swapchain_fix` (default on) |
@@ -75,9 +98,12 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | SIGABRT right after start, backtrace `libopenxr_loader.so (xrCreateSwapchain+…)` | overport's dispatcher aborts on swapchains > 4096 px ("Wrong createInfo size"); video players use 7680×3840 theater textures | `frame.swapchain_limit` (default on; guard → 16384 px; triage `swapchain-size-abort`), for example 4XVR |
 | Video/menu panel missing, log `dropped N unusable layer(s)` with cylinder (1000017000) or equirect2 (1000091000) layers | the Frame runtime lacks XR_KHR_composition_layer_cylinder/equirect(2)/cube (its SteamVR runtime only composites quad + projection layers) | adapter shows cylinders as flat strips (setting `cylinder_strips`, default on); 360° equirect layers (theaters, 360° videos): `adapter.equirect_emul` (GLES only, per game) |
 | 360° theater / 360° video black or missing (for example 4XVR) | equirect layers dropped | `adapter.equirect_emul=1`: a worker thread with a shared GLES context converts each 360° image to a cube map when it changes and draws one adapter projection layer from it for every frame with exactly that frame's views; it replaces the 360° layers in place, so the game's own projection layer (balcony, controllers, 360° videos it draws itself) stays on top. Quads can't be used: the Frame draws quad layers above every projection layer whatever the order. Log: `first 360 view ready`, `in 5 s: N 360 image update(s) … M view redraw(s)`. Upside down / mirrored / behind you: `equirect_flip` 1/2/4 (`frameport settings <pkg> equirect_flip=1`, no rebuild). Never Vulkan (a Vulkan renderer hung the Frame's GPU in AC Nexus) |
+| Fades to black don't show: you see the level loading behind a loading screen (Batman: Arkham Shadow, GitHub #197); with `layer_debug=1` launch.log shows `color scale 0.00 0.00 0.00 …` on the projection layer | the game fades by dimming its eye image with XR_KHR_composition_layer_color_scale_bias; whether the Frame's runtime applies it isn't confirmed in the headset yet | `adapter.fade_quad=1` (opt-in, `native/adapter/fade_quad.c`): FrameBridge adds a black, alpha-blended quad right after the dimmed projection layer (VIEW space, 1 m ahead, 6×6 m; opacity = 1 − scale in 16 steps from one 8×8 swapchain refilled only when the step changes: Vulkan clear / GLES clear; one swapchain per step hit XR_ERROR_LIMIT_REACHED in Batman), log `fade_quad: drawing fades over the picture`; `fade_quad=2` also removes the layer's own scale (if both show, the fade is doubled) |
+| Vermillion: the hand and brush disappear over the canvas while painting, but still paint (GitHub #200) | the game shows a canvas being painted as its own compositor (quad) layer and turns the canvas's scene renderer off; the Frame draws quad layers above every projection layer whatever the order, so the canvas covers the hand (Vulkan game: no GL layer emulation) | `frame.vermillion_scene_canvas` (catalog): `PaintableMesh.HasCompositorLayerAvailable` / `ShouldUseCompositorOverlay` -> false in libil2cpp.so (Cpp2IL), so the game's own fallback draws the canvas in the scene (Klownicle's finding) |
 | Unity game hangs right after its first frames, no `pacing:` lines; SIGQUIT dump shows UnityMain in a game library's `JNI_OnLoad` → `usleep` (for example SKYBOX: `libskybox.so`, `SignatureChecker`) | the game checks its APK signing certificate; every port is re-signed | can't be fixed without defeating anti-tamper (FramePort doesn't): mark "Can't run". Diagnose hangs: `podman exec <container> kill -3 <pid>` writes all thread stacks to launch.log |
 | Video player doesn't list sent videos (for example 4XVR "Internal Storage" only shows some) | the player lists its own /sdcard folder (4XVR: /sdcard/4XPlayer), not /sdcard/Movies; Android's media index doesn't work in Lepton | game page "Add videos" / game menu "Add videos and files" (Videos + the app's own folder, hard links) or `frameport frame send <files> --app <pkg>` |
 | One eye gray in a stereo video, log `xrCreateSwapchain … result=-10` | the runtime refused a swapchain (XR_ERROR_LIMIT_REACHED) | fewer/smaller swapchains: lower `equirect_res`; unresolved |
+| VrApi game (32-bit bridge or `frame.vrapi_bridge`): holding the menu button to recenter turns the view ~90-120 degrees to the side | the bridge's app space is LOCAL + the head's yaw at the start; the Frame's recenter moves LOCAL to the head, so the old yaw was added again | fixed in the VrApi bridge (2026-10-13): on XR_TYPE_EVENT_DATA_REFERENCE_SPACE_CHANGE_PENDING (LOCAL) and on `vrapi_RecenterPose` it takes the origin from the head again (log `recentered: head yaw …`); rebuild the game |
 | Menu/screen jumps to where you look (for example 4XVR) | the app re-creates LOCAL spaces (4XVR: every 2–4 s) and the Frame places them at the current head yaw, or the app recenters after the Frame's brief focus dips | turn on `adapter.layer_debug`, check `that LOCAL space sits at … deg` vs `focus_hold: hid a … ms focus dip`; patches: `adapter.stable_local` (new LOCAL spaces line up with the first) / `adapter.focus_hold` (on by default: hides dips up to `focus_hold_ms` once the game has been focused for a second; never at start-up: a global debounce broke AC Nexus) |
 | Pointer misses menu items | the Frame's aim pose differs from Touch's | `adapter.layer_debug` logs `aim in grip … pitch/yaw`; correct with `aim_pitch`/`aim_yaw`/`aim_forward` (`frameport settings`, no rebuild) |
 | Video stutters although fps is steady | video frame rate doesn't divide the refresh rate (30 fps at 72 Hz) | `adapter.refresh_rate` (for example 90 for 30 fps, 72 for 24 fps); `layer_debug` logs the offered rates and the app's own requests |
@@ -106,6 +132,10 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | SDL / LÖVE app crashes at start: `NullPointerException … ClipboardManager.addPrimaryClipChangedListener` in `SDLClipboardHandler.<init>` (for example Dramatic Shape) | Lepton's Android has no clipboard service (`service check clipboard`: not found) | `frame.sdl_clipboard` (that call → nops in classes.dex, in place, `apk/dex.py`); reproduced and verified with LÖVE for Android 11.5 |
 | Godot 4 app crashes at start: `java.lang.NullPointerException: null cannot be cast to non-null type android.content.ClipboardManager` at `org.godotengine.godot.Godot.<init>` (Godot 4.3/4.4; 4.2 when the clipboard is first used, in `Godot$mClipboard$2.invoke`) (for example EndoparasiticVR, GitHub #134); triage `godot-no-clipboard` | Lepton's Android has no clipboard service and Godot's Kotlin code casts it with a non-null `as ClipboardManager` (`Intrinsics.checkNotNull` before the check-cast). Godot 4.1 (Java) and 4.5+ (`as?`) don't throw | `frame.godot_clipboard` (suggested by analysis `godot_clipboard`): that checkNotNull call → nops in classes.dex (check-cast accepts null), and Godot's getClipboard/hasClipboard/setClipboard return at once ("" / false / nothing; `Dex.return_early`), in place; matched exactly, other dex files untouched. Checked against the Maven godot-lib 4.2.2/4.3.0/4.4.1 and the 4.3/4.4.1 release export templates (D8 re-reads the result); not yet run on the device |
 | Game crashes at start: `java.lang.NoSuchMethodError: No virtual method getAvailableCommunicationDevices()… in class Landroid/media/AudioManager` at `com.vivox.sdk.AudioChangeListener.checkAudioRouteAndApplyChanges` (for example Green Hell VR, GitHub #101); triage `vivox-api31` | Newer Vivox (voice chat) builds call Android 12 audio-routing methods without a version check; Lepton is Android 11. Older Vivox builds (Eleven Table Tennis, BattleSisters) don't have that code | `frame.vivox_audio_route` (suggested by analysis `vivox_api31`): every AudioChangeListener method that calls one of them returns at once (`Dex.return_early`: return-void / `const/4 v0, 0; return v0`, in place); voice chat keeps the default audio route |
+| A game on a microSD card or another drive doesn't start, loses its saves or loops at start; launch.log has `ln: cannot create symbolic link from 'Frame' to '/data/data/<pkg>'` or `Couldn't create directory for SharedPreferences file /data/user/0/<pkg>/…` (GitHub #213/#214/#215/#221: a card named "Steam Frame 512g"); triage `lepton-data-link-failed` | Valve's Lepton pastes `STEAM_COMPAT_DATA_PATH` unquoted into `sh -c "ln -s …/internal/<pkg> /data/data/<pkg>"` (liblepton mounting.sh) and APK paths into unquoted substitutions, so a path with a space never gets the app's internal storage | agent v83: the Quest launcher links the game folder to `~/.local/share/frameport/lepton-paths/<pkg>` at every start and gives Lepton that path (`app_dir_lines`); `upgrade_launchers` converts existing launchers at the next connection; deployment.json keeps the real path |
+| Start never finishes, 100 % CPU, launch.log of gigabytes repeating `EOSSDK.createKeychain` / `resetKeychain` (Beyond Sandbox, GitHub #214); triage `eos-keychain-loop` | Epic Online Services' Java keychain can't write its SharedPreferences and resets/creates without end (seen when the app had no internal storage, row above) | fix the storage first; `frame.eos_keychain_loop` (opt-in, offered by triage; analysis `eos_keychain`) makes `EOSSDK.resetKeychain` return at once (`Dex.return_early`) |
+| Unity game freezes on its loading screen ~10-15 s in (Yupitergrad, GitHub #235); launch.log has `GrantPermissionsActivity: Permission grant result … permission=android.permission.BLUETOOTH_CONNECT`, then OVRPlugin `SetupDisplayObjects(): Unable to find EGLConfig for configId 0` and no more frames; triage `bhaptics-permission-prompt` | bHaptics' vest SDK (`com.bhaptics.commons.PermissionUtils.requestBluetoothPermission`) asks for Android 12's BLUETOOTH_CONNECT; on Lepton's Android 11 it can't be granted at install, so Android's permission screen takes the foreground for a moment, the game pauses/resumes and OVRPlugin's GLES compositor stops drawing | `frame.bhaptics_permission` (suggested by analysis `bhaptics_permission`): the request returns at once (`Dex.return_early`) |
+| Unity game aborts at start: `Abort message: 'cannot create thread specific key for __cxa_get_globals()'` (SIGABRT in a library such as `libFirebaseCppApp-*.so`, for example Wander 0.3570, GitHub #198); triage `pthread-keys-exhausted` | Bionic allows 128 pthread keys per process; Unity 6 takes ~40 (most without a destructor), large native libraries (Gecko `libxul.so`, Firebase, avatar SDKs) and the Frame's own libraries (Mesa/Zink, FrameBridge, OVRPort, Valve's Vulkan layers) take the rest | `frame.unity_tls_key_pool` (opt-in; suggested for Unity 6 with Firebase C++ or Gecko): libunity.so's `pthread_key_*`/`pthread_get/setspecific` imports are renamed to `fp_tkey_*` (`elf.rename_imports`, versions set global) and `libfp_tkeys.so` (`native/tlskeys`) is added to its DT_NEEDED; destructor-less keys become slots behind one real key (logs `fp_tkeys: pooling Unity's thread keys`). Approach by Klownicle (#198) |
 | Controllers do nothing (for example stuck on a setup screen); log: `xrSuggestInteractionProfileBindings … XR_ERROR_PATH_UNSUPPORTED` | the game only suggests bindings for Meta's newer profiles (Touch Plus / Touch Pro); the Frame's Android runtime knows `oculus/touch_controller`, not those | adapter `profile_remap` (default on): the bindings are suggested again for Touch (log: `controller profile … -> oculus/touch_controller`) |
 | Some buttons do nothing or the wrong thing (for example a Quest game's X/Y on the Frame's left controller) | the game binds only Quest Touch and SteamVR maps Touch onto the Frame controllers with its own remap (Touch left X/Y land on the d-pad, right X and Y repeat B), or the runtime rejected a profile or an input call | turn on adapter `input_diag` (diagnostics, off by default; `frameport settings <pkg> input_diag=1`) and look for `input_diag:` lines: `bindings: <profile> accepted` or `unsupported: interaction profile <profile> -> <result>` with the rejected paths, `bindings: /user/hand/<hand> uses <profile>`, `unsupported: function <name>`, `unsupported: xrCreateAction -> <result> (<action>)` |
 | Unity game hangs or the whole Frame restarts (for example in a menu); log: `The current MSAA level is 0, but the recommended MSAA level is 4. Switching to the recommended level.` (for example Lucky's Tale) | Meta's OVRManager (`useRecommendedMSAALevel`) turns 4x MSAA on at runtime, past QualitySettings; multisampled render-to-texture on GLES/Zink hangs the GPU | `frame.unity_runtime_msaa_off` (Cpp2IL: `OVRDisplay.get_recommendedMSAALevel` → 0) |
@@ -126,11 +156,12 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Unreal game (ILMxLAB, for example Vader Immortal): controllers track but grip/trigger do nothing, grabbing never works (Unreal's own input values move, the game's stay 0) | `URPOCKeyMapManagerComponent` picks the Quest or the Gear VR key set by `IsRunningOnSantaCruz()`; on the Frame it takes Gear VR, empty in a Quest build | `frame.unreal_quest_keymap` (the Oculus case keeps the Quest set, for action and axis mappings; found by Klownicle, GitHub #49) |
 | The hands' thumbs never move when you touch the thumbstick or buttons (Unreal `ThumbUp` stays 1, for example Vader Immortal) | OVRPlugin reports thumb proximity from XR_FB_touch_controller_proximity, which the Frame's runtime lacks; OVRPort's loader offers it anyway and the proximity actions never get a binding | adapter `proximity_emul=1` (thumb proximity from the touch inputs: thumbstick, face buttons, thumb rest; 2 = also the index finger from trigger touch); log `proximity_emul: finger proximity bound to touch`. **For UE4 Oculus games this didn't animate the thumbs** (Vader, GitHub #49): use `frame.unreal_thumb_touch` (found by Klownicle): `OculusInput::FOculusInput::SendControllerEvents` computes ThumbUp from NearTouches (masks 0x2/0x8); the patch makes it read Touches (the slot 4 bytes before) with masks 0x0f00 (X/Y/stick/thumb rest) / 0x000f (A/B/stick/thumb rest), keeping the inversion; three instructions, matched exactly (build note `OculusInput ThumbUp: from the capacitive touches`). Matches Vader Immortal Ep. I, Robo Recall, Phantom: Covert Ops, Time Stall, Star Wars: Tales from the Galaxy's Edge; newer UE4 builds (for example Asgard's Wrath 2, RE4, In Death) compile it differently (shared mask registers) and aren't matched |
 | Vulkan game (Unreal / own engine with the Vulkan shim): the GPU hangs at one effect or cutscene (kernel `hangcheck detected gpu lockup`, freeze/exit; for example a VR4 cutscene, GitHub #140) | a SPIR-V shader reads a loop counter/accumulator before setting it (VR4's campaign shader, GitHub #10) | adapter `vk_shader_dump=1` (`frame.vk_sanitize`'s shim; log `vk shim: dumping SPIR-V modules to …`) writes every distinct module once to `files/fp_vk_shaders/<size>_<sha256>.spv` + `index.txt` (`<seq> <ms> <unix ms> <name> new\|known\|again`); play to the hang, collect diagnostics (`target/shaders/fp_vk_shaders/`, newest 4 MB) and take the modules first created (`new`) shortly before the kernel's hangcheck time; disassemble (`spirv-dis`), find the variable read before its first store, write a `vk_shader_fix` (`<size>:<sha256>:<byte offset>:<words>` = inserted OpStores; log `vk shim: fixed shader module`); switch the dump off again |
+| OpenGL ES game: memory and GPU mappings grow every frame (~20 MB/s, `/dev/dri/renderD128` mappings ~6 per frame) until the frame rate collapses; the game's `xrclient_<package>.txt` (Steam logs) has one `SXR_GL_CHECK: error:0x502 ... glGenTextures` before the session starts (GitHub #285, Vader Immortal) | The game leaves GL errors pending on its context; the runtime's GL interop reads glGetError after its own calls and takes the stale error as its own failure. From then on `CVRCompositorSharedTextures::BeginCommandBuffer` allocates a new command buffer every frame instead of reusing one (perf page-fault stacks) | Adapter `gl_error_clear=1` (GLES only) clears pending GL errors before xrCreateSwapchain/xrBeginFrame/xrEndFrame; Vader's catalog recipes set it. Verified headless 2026-10-14: 191 GPU mappings and ~1.07 GB flat over 100 s (before: +430 mappings/s, +22 MB/s), no SXR_GL_CHECK |
 | OpenGL ES game: the GPU hangs at one effect (freeze/exit, compositor watchdog, for example Vader Immortal's lightspeed jump) | a shader (as Zink compiles it) reads loop counters/accumulators before setting them | capture the SPIR-V (adapter `zink_shader_dump=1` writes every module to `files/fp_spirv/`, or a GPU capture), then a `zink_shader_fix` entry (same format as `vk_shader_fix`) + `frame.zink_shader_fix` (Vulkan layer under Zink, activated through GraphicsEnv's debug layer list); log `shader fix layer: fixed shader module N`; triage `zink-shader-fix-mismatch` when a Frame update changed the driver's output |
 | 2D Android app: Steam says it's running but nothing shows | Lepton runs apps headless unless the app folder has `lepton-show-flatscreen` | FramePort adds it for apps without VR (agent v28+); reinstall apps installed before |
 | A phone/tablet app shows nothing in the headset, or a VR app opens as a flat window | FramePort's VR/2D guess (`vr_kind`) is wrong for this app | patch `device.display_mode` → **Flat window** or **VR** (Customize → "Show as VR or as a flat window"), then Update on Frame |
 | An install button opens another program (or nothing) instead of FramePort | another program owns the link type, or the switch is off, or macOS (Flet can't receive links there) | Settings → Install links → **Use FramePort for these links**; else Add games → Install from a link… (paste the button's address) |
-| 2D Android game ignores the controllers: they only move a pointer, an SDL game keeps its touch controls ("no controller attached"); Android's log lists only `wayland_touch`/`wayland_keyboard`/`wayland_pointer` (GitHub #162, Skate 3) | Lepton's Android gets keyboard, pointer and touch from the Wayland seat only: no gamepad device | patch `device.steam_gamepad` (2D apps; suggested when the manifest declares `android.hardware.gamepad` or `LEANBACK_LAUNCHER`; no APK change, reinstall): the launcher puts FramePort's Podman wrapper (`~/.local/share/frameport/agent/bin/podman`) first on PATH, which bind-mounts Steam Input's virtual pads (uinput, 28de, "Microsoft X-Box 360 pad N") at `/dev/input/eventN` plus an Xbox 360 key layout, and exports `LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD=1`. Check: launch.log `FramePort gamepad: Steam Input virtual gamepads for this container: event5 (…)` ("none" = Steam had no pad when the game started: Steam only makes it while the controllers are on), `podman exec lepton-steamlaunch-<appid> dumpsys input` lists the pad. Steam Input must be on for the shortcut. A pad Steam makes after the start (controllers woke later, reconnect) isn't seen until the next start. Off for one start: `FRAMEPORT_NO_GAMEPAD=1 %command%` |
+| 2D Android game ignores the controllers: they only move a pointer, an SDL game keeps its touch controls ("no controller attached"); Android's log lists only `wayland_touch`/`wayland_keyboard`/`wayland_pointer` (GitHub #162, Skate 3) | Lepton's Android gets keyboard, pointer and touch from the Wayland seat only: no gamepad device | patch `device.steam_gamepad` (2D apps; suggested when the manifest declares `android.hardware.gamepad` or `LEANBACK_LAUNCHER`; no APK change, reinstall): the launcher puts FramePort's Podman wrapper (`~/.local/share/frameport/agent/bin/podman`) first on PATH, which binds the host's `/dev/input` at `/dev/fp-input` plus an Xbox 360 key layout (Vendor_28de_Product_11ff.kl, incl. D-pad buttons), and exports `LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD=1`; the launcher's `_gamepad_links` worker (agent v85) keeps `/dev/input/eventN` links to Steam Input's virtual pads (uinput, 28de, "Microsoft X-Box 360 pad N") in step while the game runs, so a pad Steam makes later (controllers woke up, reconnected) is added and a gone one removed (Android's EventHub follows through inotify). Check: `<base>/gamepad.log` (`pads: event5` / `pads: none`), launch.log `EventHub: New device … pad`, `podman exec lepton-steamlaunch-<appid> dumpsys input` lists the pad. Steam Input must be on for the shortcut; Steam activates the shortcut's own layout while the game has focus (controller.txt `Queueing activation for controller: 0 app: <shortcut appid as signed int>`), and Steam's UI layout (app 769) while the dashboard is open. Off for one start: `FRAMEPORT_NO_GAMEPAD=1 %command%` |
 | 2D Android app: back/home/recents buttons cover the app's own buttons | Android's navigation bar | patch `device.hide_navbar` (on by default for apps without VR) sets `qemu.hw.mainkeys=1`; reinstall to apply |
 | Black screen, audio works, GLES engine with direct VrApi | Mesa rejects Quest-style GLSL | `frame.gl_shim` (logs `GLShim: SHADER COMPILE FAILED` + source lines) |
 | Black screen, audio works, log `Unsupported VrApi layer type N` | bridge drops frames containing that layer | extend the bridge (cylinder=3 is converted to a quad already) |
@@ -144,6 +175,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | MR game stuck waiting for room data (Demeter) | no Meta scene API | adapter `scene_emul=1` (+ `frame.meta_permissions`) |
 | Hand-tracking game janky (Silhouette) | Frame synthesizes hands from controllers | `controller_fix=0` passes hands through; not really fixable |
 | Eye distortion while moving (Arcsmith, Time Stall) | unknown (not eye swap, tracking, Valve layers, depth or pacing) | unresolved |
+| The Climb 666.0: hand outlines ripple in both eyes while menus and gameplay work (GitHub #238) | Unknown. Sessions paced around 72 fps, controller tracking reported valid, and SteamVR motion smoothing was already off; these checks do not establish the cause | Unresolved after wearer comparisons on 2026-10-12: disabling Valve's Vulkan layers, setting `r_AntialiasingMode = 1`, and setting `r_AntialiasingMode = 0` with `r_MotionBlur = 0` each gave the same or worse result. These were config comparisons; runtime cvar values were not verified. Restored the playable configuration (`r_vr_foveated = 0` with the default Vulkan layers), retaining the startup/rendering crash fixes above. Do not keep the unsuccessful experimental settings as a fix |
 | One eye gray / 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 0.5-2 s now and then, no flicker (for example 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) |

docs/SURFACE_VIDEO.md

@@ -73,6 +73,42 @@ panoramas retain their layer rotation and have no translational parallax.
 
 ## Stable composition
 
+Adapter-owned video outputs explicitly request a static
+`XR_FOVEATION_LEVEL_NONE_FB` runtime profile before image enumeration. This
+prevents shared Valve foveation from coarsening the side-by-side video output.
+The profile applies only to those outputs; application eye swapchains retain
+foveation and gaze tracking. The runtime result is logged as
+`surface_video: full-rate runtime profile result=...`.
+
+Composition retains the original raster pipeline, linear-light blending and
+sRGB colour attachment. A compute compositor was also tested, but did not alone
+fix pixelation and added a private full-size image copy. The full-rate runtime
+profile fixed pixelation in the headset; the restored raster path was confirmed sharp and improved in-game presentation
+from roughly 40–44 to 65–71 FPS in the sampled cutscene. It still needs further
+performance work. Fully opaque video pixels skip the invisible scene texture
+sample and colour transform; partially transparent pixels retain the full blend. The next live cutscene run reported about 84 FPS across its first five post-startup samples, versus about 69 in the preceding run, with decoding steady at 60 FPS. These separate samples do not control for head motion or temperature; smooth playback is not yet fully established. The video surface patch revision marks affected
+recipes for rebuilding without forcing unrelated game updates.
+
+Once native video composition is active, the compositor can sample an sRGB view
+of the worker's shared hardware buffer directly. The renderer retains the slot
+across repeated frames; replacement queues a foreign-queue ownership handoff
+behind earlier compositor reads, and only its signalled fence makes the old slot
+reusable by the worker. Missing compatible views and initial/fallback presentation
+retain the copy path. The full-rate video profile and output resolution are
+unchanged. Deployment/performance validation is initially limited to Batman.
+The headset playback check confirmed good performance, and the live log confirms
+`direct shared-buffer sampling; cache copy skipped`. During active video,
+recorded application pacing was approximately 105–107 FPS, with decoding around
+60 FPS and visible-view GPU waits around 4.0–4.8 ms, versus roughly 6 ms in the
+preceding copy-path run. These are separate live runs, not a thermally controlled
+benchmark. The 8192x4096 decoded input and 2560x2560-per-eye output are retained;
+other games have not been redeployed or performance-tested with this change.
+
+The native GPU fixture checks stereo pixels, fades, image orientation, colour
+transforms, held frames and teardown, plus single-pixel alternating detail across
+both eyes including edges and corners. This is a compositor regression check;
+in-game playback with injection still needs visual confirmation on the headset.
+
 A separately submitted projected video layer can alternate with the main game
 projection as opaque coverage changes during head movement. That presentation
 path exhibited snap-back/doubled video in headset tests even when rendering
@@ -104,6 +140,19 @@ combined output with the exact camera that produced it; old pixels are never
 relabelled with a newer pose. Teardown retires snapshot writers and compositor
 readers. Depth/motion-vector images from another render are not attached.
 
+## Loading-screen blackout
+
+The native video adapter also preserves Batman's fully black loading state.
+When the first opaque projection requests zero RGB scale, unit alpha scale and
+zero bias, it omits that scene projection so the opaque runtime background stays
+black. Later loading UI layers retain their order. This avoids displaying assets
+as they stream in, without adding a GPU pass or changing the video resolution.
+Partially faded scenes, alpha-blended projections and composed video retain their
+existing paths. This fallback is limited to the native video adapter setting;
+other games do not gain it automatically. In-headset testing confirmed the black
+loading screen is restored. Revision 4 requests a rebuild of older native-video
+installs while leaving ordinary game recipes unchanged.
+
 ## Building and validation
 
 Rebuild FrameBridge with Android NDK r27c:

docs/TRANSFER_BENCHMARK.md

@@ -0,0 +1,195 @@
+# Transfer measurements and incremental installs
+
+## Production OpenSSH follow-up
+
+OpenSSH is now the preferred installer backend for files >=8 MiB. The new default is three workers (range 1–8),
+with saved preferences preserved. Fresh files use `put`; existing partial files use `reput`. Each worker keeps
+one SFTP batch session. Progress is polled through a separate bounded SFTP channel. Native failures resume via
+Paramiko; cancellation stops the owned SFTP/SSH process trees and does not trigger fallback.
+
+Windows matched production comparison: eight 64 MiB files, 512 MiB total, three shuffled repetitions per backend,
+three workers, same home Wi-Fi/internal storage. OpenSSH median **15.51 MB/s**, Paramiko median **11.08 MB/s**
+(about 40% faster). All six checksums passed. OpenSSH trials ranged 9.5–16.8 MB/s, so link variability still
+matters; it was slower than Paramiko in one pass. Native credential/progress setup took 0.12–0.13 seconds.
+
+The separate Windows 128 MiB production test also passed every checksum. Native cancellation left a partial file
+of 74,752,000 bytes; resuming with OpenSSH produced the expected SHA-256. The log confirmed no fallback for the
+resumed production upload. Reports:
+`/mnt/c/Users/Austin/AppData/Local/Temp/frameport-upload-native-production-comparison-windows.json` and
+`/mnt/c/Users/Austin/AppData/Local/Temp/frameport-upload-native-production-windows.json`.
+
+The earlier sections below preserve measurements made before the production backend switch.
+
+The WSL production validation (128 MiB, three workers, three repetitions) measured 14.1 / 19.1 / 15.0 MB/s,
+with every checksum passing and native backend logs recorded. Production cancellation left a 72,330,240-byte
+partial file; OpenSSH resumed it in 4.23 seconds with the expected SHA-256 and no Paramiko fallback. Report:
+`/tmp/frameport-upload-native-production-wsl.json`.
+
+## Measurements (2026-10-14)
+
+Both runs used the same paired Frame, the home-router connection and internal ext4 storage under the paired user's
+home. Each large-file trial sent the same 128 MiB random payload; each small-file trial sent 512 files of 64 KiB
+(32 MiB total). Methods were shuffled for each of three repetitions. Windows and WSL runs were sequential, not
+concurrent. Every completed transfer passed SHA-256 verification. Rates below include connection/setup and transfer
+completion, but exclude checksum verification and cleanup; MB/s uses decimal bytes.
+
+| Method | WSL2 median MB/s | Windows 11 native median MB/s |
+|---|---:|---:|
+| FramePort pipelined SFTP | 10.4 | 6.1 |
+| Paramiko SFTP, 64 MiB window | 17.1 | 4.5 |
+| OpenSSH SFTP | 16.8 | 15.4 |
+| OpenSSH SCP (default protocol) | 11.1 | 10.1 |
+| OpenSSH `ssh` + streamed file | 9.9 | 8.1 |
+| FramePort tar stream | 14.9 | 6.8 |
+| OpenSSH tar stream | 15.0 | 7.2 |
+
+The network varied considerably: WSL's application trials ranged from 9.6–12.8 MB/s, native SFTP from
+16.2–17.3 MB/s, and some other methods dropped below 5 MB/s. Windows application trials ranged from 5.6–6.4 MB/s;
+native SFTP ranged from 9.1–16.5 MB/s. These are useful end-to-end comparisons on this setup, not a measurement of
+the maximum throughput each transport can achieve. Window tuning did not help the Windows run.
+
+Cancellation/resume checks interrupted the application upload at 64 MiB, then independently resumed that partial
+file with the application and with OpenSSH SFTP `reput`. All four resumed files passed SHA-256 verification. This
+checks application cancellation and both resume paths; native SFTP cancellation itself remains unmeasured.
+
+The Frame's USB and hotspot interfaces were up, but neither direct endpoint was reachable from the PC. No removable
+storage was mounted. USB, hotspot and microSD performance remain **unmeasured** in this round. The Frame's router
+connection used 5 GHz / 80 MHz Wi-Fi, with roughly -56 dBm signal during a read-only probe. This does not reproduce
+the 6 GHz direct-hotspot setup in [discussion #242](https://github.com/spoopyghosty0/frameport/discussions/242), where
+the reporter measured about 114 MB/s with OpenSSH versus 23 MB/s with Paramiko.
+
+**Recommendation:** prototype an optional OpenSSH SFTP backend for large files, retaining `.part`/`reput`,
+cancellation, retries, strict paired-host verification and Paramiko fallback. Validate it on a fast direct link
+before making it the default. On this Windows run SFTP was about 2.5 times faster than the current application,
+and it beat SCP. The small-file tar measurements do not justify selecting a new tar transport yet. Production
+transport selection remains Paramiko pending that decision. The bounded parallel-file setting described below
+uses independent Paramiko connections.
+
+## Parallel-file uploads
+
+### Matched native OpenSSH comparison
+
+The later comparison tested both backends sequentially on Windows and WSL, with three shuffled repetitions of
+the same eight 16 MiB files per worker count. Native `sftp-files-N` balances files across N persistent OpenSSH
+SFTP batch processes. Setup and completion are included; checksum verification is excluded. All 60 transfers
+passed SHA-256 checks. This is benchmark code; the production uploader still uses Paramiko.
+
+| Workers | Windows Paramiko MB/s | Windows OpenSSH MB/s | WSL Paramiko MB/s | WSL OpenSSH MB/s |
+|---|---:|---:|---:|---:|
+| 1 | 6.22 | 14.96 | 6.17 | 14.64 |
+| 2 | 10.61 | 17.73 | 14.41 | 14.45 |
+| 3 | 8.90 | 18.89 | 13.65 | 17.75 |
+| 4 | 14.90 | 16.80 | 15.67 | 16.63 |
+| 8 | 13.50 | 20.16 | 17.03 | 16.82 |
+
+Three is a reasonable default candidate for a future OpenSSH backend: versus two it improved median throughput
+by 6.5% on Windows and 22.8% on WSL. Eight was faster on Windows but slower on WSL. The production Paramiko
+default remains two because three regressed by 16.1% on Windows and 5.3% on WSL in this matched comparison.
+Link variability remains substantial, and no fast hotspot/USB result is claimed.
+
+Reports: `/mnt/c/Users/Austin/AppData/Local/Temp/frameport-upload-native-parallel-windows.json` and
+`/tmp/frameport-upload-native-parallel-wsl.json`.
+
+Settings → Installing → **Parallel uploads** accepts **1–8**, default **2**. It controls large files within one
+install; the FIFO still runs one install job at a time. A single APK is not split into chunks. Large files are
+scheduled largest first, with at most one authenticated SSH connection per active worker and never more workers
+than files. Small files still use tar batches after the large-file uploads. Choose 1 on a busy network; a higher
+count can consume all available bandwidth and is not automatically faster.
+
+The parallel comparison uses the same eight 16 MiB OBB-shaped files (128 MiB total) for every worker count, with
+three shuffled repetitions. The production uploader is used by `app-files-N`, including its aggregate progress,
+resume baselines, cancellation checks and connection cleanup. A failed or cancelled cohort stops queued work and
+closes only its worker transports; completed files and interrupted `.part` files remain resumable.
+
+| Workers | WSL2 production median MB/s | Windows 11 production median MB/s |
+|---|---:|---:|
+| 1 | 9.6 | 5.6 |
+| 2 (default) | 9.1 | 10.9 |
+| 3 | 6.5 | Not measured in the final production run |
+| 4 | 12.4 | 14.8 |
+| 8 | 11.2 | 17.3 |
+
+On Windows, the production uploader improved from 5.6 to 10.9 MB/s with 2 workers (**1.95 times faster**), and
+17.3 MB/s with 8 (**3.08 times faster**). All twelve Windows production transfers passed SHA-256 verification.
+The preceding Windows prototype also tested 3 workers (12.2 MB/s median), before aggregate progress/cancellation
+were integrated; that is not included as a production measurement in the table.
+
+WSL was noisy: four workers improved its median by about 29%, but 2 did not improve its median, and 3 was slower.
+There is no evidence that a particular worker count is universally fastest. The option is retained because it
+produced a repeatable benefit on Windows and higher counts improved the WSL median. Default 2 limits competing
+transfers while retaining a measured Windows benefit; users can measure higher counts or select 1 in their own
+environment. Production code, including cleanup and progress checks, was used for both final comparisons.
+
+```sh
+uv run python scripts/upload_bench.py --mib 128 --repeat 3 --methods app-files-1,app-files-2,app-files-3,app-files-4,app-files-8 --json parallel.json
+```
+
+`install.upload_threads` persists the setting. Malformed values use 2 and numeric values are clamped to 1–8.
+The serial setting reuses the existing control connection; parallel workers verify that the new transport reaches
+the same paired headset before sending any files.
+
+## Reproducing the measurements
+
+Run from the checkout using the Python environment for the platform being measured:
+
+```sh
+uv run python scripts/upload_bench.py --mib 512 --repeat 3 --check-resume --json uploads.json
+uv run python scripts/upload_bench.py --fast-link --probe
+uv run python scripts/upload_bench.py --fast-link --remote-dir /path/on/card --mib 512 --repeat 3 --json card.json
+```
+
+`--host` selects a specific paired endpoint; `--fast-link` uses the same authenticated direct-link discovery as an
+install. Inspect the reported endpoint and link before comparing methods. Join the Frame's hotspot or connect its
+USB cable before testing those paths; the benchmark does not change PC networking. Keep the headset awake and avoid
+other network traffic. A 512 MiB payload is preferred for follow-up tests on fast links; the available-link runs
+above used 128 MiB.
+
+The script creates a unique scratch directory on the selected filesystem, checks content outside the timed upload,
+and removes its own temporary remote files and temporary key copy. It never modifies the pairing key's ACL. Windows
+OpenSSH rejects an `OWNER RIGHTS` ACL entry; the temporary copy grants only the current user, without Python's
+Windows `chmod` behaviour that can introduce that entry. Native clients use the application's key and known-hosts
+file with strict host verification.
+
+JSON rows contain bytes, total seconds, separately measured setup seconds where available, payload and total rates,
+verification duration and checksums. SCP/SFTP's setup is included in total time because their command-line clients
+do not expose its completion separately. On POSIX, CPU includes the Python parent and child processes; on Windows,
+`os.times()` measures only the parent, so native subprocess CPU numbers must not be compared with Paramiko's CPU.
+An error is recorded rather than counted as a successful trial. `--methods` can restrict the run; `--small-files`
+controls the tar corpus. Cipher comparisons are available as `ssh-gcm` and `ssh-chacha`.
+
+## Incremental install behaviour
+
+`game_update.plan_update` is the shared, I/O-free Quest/Android classifier used by badges and installation. Recipe
+source, notes and catalog revision do not affect it. A newer tested catalog recipe remains a separate suggestion
+when the user customized their recipe.
+
+- Build records keep an APK recipe fingerprint, source hash/stat, selected native-asset identities, converter
+  identity and the existing validated APK hashes. Reusable local APKs are checksum-checked before installation.
+- Deployment records keep applied runtime configuration and its fingerprint, APK stat/hash, source version,
+  data manifest/digest and artwork hashes. Routine device samples carry only the digest, and updates fetch a
+  detailed manifest only when necessary. Live numeric settings writes update only the applied runtime configuration,
+  leaving APK build identity intact. Desired data manifests are cached locally for badges, without render-path I/O.
+- Runtime-only updates use agent v87 `configure`: no conversion, signing, APK transfer, artwork, Steam restart or
+  automatic launch test. They still require the installed APK identity and an available destination, and refuse
+  changes while the game is running. Defaults explicitly reset overrides embedded in an older APK. Generated
+  configuration files are restored or removed only when they still match FramePort's last write; user edits survive.
+- Build support dependencies remain conservative: controller models/native surfaces/haptic support, Zink-layer
+  selection, mixed foveation patches and revised adapter support can require a new APK. A recorded alternate
+  variant can be reused when switching variants.
+- Data-only updates transfer missing/different-size data using the resumable uploader. Recipe/APK updates skip
+  data synchronization when the source data manifest is unchanged, preserving Frame-side mods; explicit forced
+  reinstalls still check/repair data. Artwork-only
+  updates send changed slots; unchanged artwork avoids a Steam refresh. APK/data changes retain the configured
+  automatic launch test. Settings/artwork changes skip it.
+- APK-only updates preserve installed OBBs, including mods, and do not apply old staged OBBs or artwork from an
+  interrupted upload. Ordinary data comparison still uses sizes, matching existing behaviour; equal-size content
+  replacement is not detected automatically. Explicit rebuild/reinstall remains available (`install --force`).
+- Legacy build identities take the full path once because their original build inputs cannot be established
+  safely. Converted-copy cleanup and `build.keep_copies` remain in effect; a configuration/data update does not
+  require the deleted converted APK.
+
+Install results record `stage_seconds` in the library's install history. This includes planning, conversion,
+validation, transfer and finalization stages reached by that operation; the GUI's subsequent optional launch test
+is separate. Use these timings to distinguish build cost, network transfer and device/Steam work when reviewing a
+slow install. Configuration success is recorded after writing the configuration and completing its sync; a failed
+operation leaves the prior applied fingerprint so it remains retryable.

docs/showcase/shots.yaml

@@ -93,7 +93,7 @@ shots:
     docs: [docs/SHOWCASE.md]
     steps:
       - go: live
-      - wait_for: "What the player sees"
+      - wait_for: "Ready when you are"
 
   - name: install-progress
     docs: [docs/SHOWCASE.md]

docs/showcase/videos/install.yaml

@@ -62,7 +62,7 @@ scenes:
     caption: ["Connect your Steam Frame", "Once: one line on the Frame"]
     hold: 1.5
     steps:
-      - click: "Set up the Frame"
+      - click: "Set up your Frame"
       - wait: 1.6
       - click: "Start setup"
       - wait_for: "Waiting for your Frame to ask"
@@ -111,7 +111,7 @@ scenes:
       - hook: {name: pairing_done, args: [1.6]}
       - wait_for: "Ready to play"
       - wait: 1.2
-      - hover: "Quest games (Lepton)"
+      - hover: "Quest games"
       - wait: 1.6
 
   - name: add-games

native/README.md

@@ -11,12 +11,14 @@ embeds debug paths (`-g`) and the dex depends on the d8 version, so those differ
 
 | Dir | Artifact | What / why |
 |---|---|---|
+| `luajit/` | `arm64-v8a/libfp_luajit.so` | Pinned upstream LuaJIT with full-width lightuserdata (`frame.luajit_pointers`). Only the verified old Lua engine's shared public functions become imports; the original xLua API 105 bindings, LuaSocket helpers and `luaopen_perflib` remain in the game. No game library is bundled. Build: `python native/build.py --only luajit`; source revision + archive SHA-256 in `luajit/build.py`, MIT notices in `luajit/COPYRIGHT` and `artifacts/licenses/LuaJIT.txt`. `runtime.c` checks GC64 and the retained `xlua_gl` global-reference offset. `smoke.c` compares a real low-address allocation with the original library's own native static pointer; the unmodified library fails only the high-address case, the patched one round-trips both exactly. Startup verified on Frame; gameplay unverified. |
 | `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`, `proximity_emul` = finger proximity (XR_FB_touch_controller_proximity, which the Frame lacks) from the capacitive touch inputs: OVRPlugin's `hand_thumb_proximity`/`hand_trigger_proximity` actions get extra Touch bindings); `input_diag.c` = controller-input diagnostics (setting `input_diag`, off by default and hooked only when on; logs suggested interaction profiles and the runtime's answers, each hand's current profile, functions the runtime lacks and failing input/haptics/perf calls, each line once; tested on the host by `tests/test_input_diag.py`); `layer_emul_gl.c` = `equirect_emul` (GLES sessions only): 360° equirect/equirect2 layers become one adapter projection layer, drawn by a worker thread with its own EGL context shared with the app's: each 360° image is converted to a cube map only when it changes, and the view is redrawn only after a 4° head turn (GL/EGL resolved with dlopen, so Vulkan games never load them); `layer_math.h` = their pose/face math, tested on the host by `tests/test_layer_emul.py`. `render_model.c` = XR_FB_render_model emulation (setting `controller_models`, off by default): serves `files/framebridge/controller_{left,right}.glb`, which the agent converts on the Frame from SteamVR's own Frame controller render models (never shipped by FramePort); tested on the host by `tests/test_render_model.py`. Settings: `libframe_settings.so` in the APK + `settings.conf`/`framebridge.conf` on the Frame. |
-| `vrapi-bridge/` | `arm64-v8a/libvrapi.so` | VrApi → OpenXR bridge from [Android-XR-Bridge/OVRPort](https://github.com/Android-XR-Bridge/OVRPort) `native/vrapi` at 5e7df52 (GPL-3.0, `LICENSE.upstream`; unchanged upstream as of OVRPort v1.2.5, which ships the unpatched code as its opt-in `patch_vrapi_openxr` in experimental CLI builds), with our changes in `upstream-patches/`: GLES sessions + GL texture swapchains, cylinder→quad layers, GL vertical flip, UNORM↔sRGB format twins, 30 s VR-mode deadline, VALID-only recenter, loading-icon layers skipped, `vrapi_PollEvent`/`RecenterPose`/`SetDisplayRefreshRate`/`GetSystemPropertyFloatArray` (BlazeRush imports them, GitHub #57), diagnostics behind `-DOVP_GL_DIAG`. `upstream-patches/` reproduces these sources from the fork's `native/vrapi` (checked 2026-10-06 against its latest commit); upstream PRs Android-XR-Bridge/OVRPort#3-#8, tracked in GitHub #75. |
+| `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), legacy compositor debug/volume frame flags accepted, full-rate Vulkan foveation images allocated as density attachments (The Climb, GitHub #238), diagnostics behind `-DOVP_GL_DIAG`. `upstream-patches/` reproduces these sources from the fork's `native/vrapi` (checked 2026-10-06 against its latest commit); upstream PRs Android-XR-Bridge/OVRPort#3-#8, tracked in GitHub #75. |
 | `platformcompat/` | `arm64-v8a/libovrplatformcompat.so` | Real `ovrMessageType_ToString` (same fork, `native/platform`). |
 | `langpack/` | `arm64-v8a/libfp_langpack.so` | Language packs for the Meta Platform SDK (patch `frame.langpacks`, opt-in). overport's platform loader is a dispatcher in front of Meta's own loader and answers `ovr_LanguagePack_GetCurrent/SetCurrent` with `return 0` (no reply ever). This library becomes the loader's first DT_NEEDED; the loader's own exports of the 31 functions it defines are made STB_LOCAL in `.dynsym` (`elf.hide_exports`, nothing moves), so symbol lookups reach the library first. It serves `<tag>.lang` files found in the game's OBB / app files (`$FRAMEPORT_LANGPACK_DIRS` overrides the search path) through `ovr_LanguagePack_*`, `ovr_AssetFile_GetList` (the loader's list + the packs) and `ovr_AssetFile_StatusById`; its own message queue is merged into `ovr_PopMessage`, and every handle that is not ours (an address-range check) goes to the loader's original function, whose address is read at run time from the loader's in-memory `.dynsym`. With patch `frame.asset_files` (marker byte `@FPASSETS@`, or env `FRAMEPORT_ASSET_FILES=1`) it also lists the data's `*.pak` content files as installed `default` asset files and answers `ovr_AssetFile_DownloadById` for them at once (a completed `DownloadUpdate`, then the result with the path). Host-tested against a stand-in loader (`tests/test_langpack.py`, plain `cc`, no NDK); the bionic/headset side is unverified. |
 | `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. |
 | `glmv/` | `arm64-v8a/libfpglmv.so` | Single-view draws of OVR_multiview programs (patch `frame.gl_multiview_fbo`, opt-in, GitHub #77). Mesa enforces OVR_multiview's rule that a draw's program declares as many views as the draw framebuffer has; engines that compile every shader with `num_views=2` and also draw into ordinary 2D framebuffers (Doom3Quest's HUD/PDA pool) lose those draws. The engine library gets it as first DT_NEEDED (direct `gl*` imports) and its `dlopen("libGLESv3.so")` string is rewritten to `libfpglmv.so` (same length; its `qgl*` dlsym table); linked `--no-as-needed` to libGLESv3 so dlsym on its handle finds everything it doesn't wrap. It records stage sources at glLinkProgram, caches the draw framebuffer's color-attachment view count per bind, and when a multiview program draws into a 0-view framebuffer it binds a lazily built twin (`glmv_rewrite.h`: num_views layout blanked, `gl_ViewID_OVR` -> `(0u)`; attribute locations + uniform block bindings copied, default-block uniforms copied before every such draw with a shadow to skip unchanged ones), draws, rebinds the original. Logcat tag `GLMV`; `gl_mv_debug=1`. The rewriter is host-tested on Doom3Quest's 19 shaders (`tests/test_gl_multiview_fbo.py`); untested on the device. |
+| `tlskeys/` | `arm64-v8a/libfp_tkeys.so` | Thread-key pool for Unity (patch `frame.unity_tls_key_pool`, opt-in, GitHub #198; approach and the first helper by Klownicle). Bionic allows 128 pthread keys per process; Unity 6 plus large native libraries (Firebase, Gecko) and the Frame's own libraries use them up (Wander: `cannot create thread specific key for __cxa_get_globals()`). libunity.so's four key imports are renamed to `fp_tkey_create/_delete/_get/_set` (`elf.rename_imports`, same `.dynstr` bytes, versions set global) and this library is added to its DT_NEEDED: keys without a destructor become slots (512, generation-tagged, `0x40000000 + slot`) in a per-thread table under one real key; keys with a destructor and all other libraries keep real keys. Lock-free get/set. Logs `fp_tkeys: pooling Unity's thread keys` once (tag FrameBridge). Host-tested (rename); not yet run on the device. |
 | `zinkfix/` | `arm64-v8a/libVkLayer_fp_shaderfix.so` | Shader-fix Vulkan layer `VK_LAYER_FP_shader_fix` for OpenGL ES games (patch `frame.zink_shader_fix`): sits between Zink (Mesa's GL on Vulkan) and the driver and inserts the words of `zink_shader_fix` (same format as the Vulkan shim's `vk_shader_fix`: size + SHA-256 match) into SPIR-V modules; `zink_shader_dump=1` writes every distinct module to `files/fp_spirv/`. The engine library loads it first (DT_NEEDED); its constructor puts the layer in front of Android's GraphicsEnv debug layer list (private Android 11 `getDebugLayers`/`setDebugLayers`, found through libvulkan.so's dependencies) before EGL starts, so the loader picks it up from the app's lib dir. Exports only the enumeration functions and `VK_LAYER_FP_shader_fixGet*ProcAddr` (never plain `vk*` entry points). Vader Immortal's lightspeed shaders (Klownicle, GitHub #49). |
 | `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). |

native/a32translator/.gitignore

@@ -0,0 +1,6 @@
+out/
+out-dev/
+*.core
+# generated by bridge/gen_stubs.py at every build
+bridge/guest/gen/
+bridge/host/gen/

native/a32translator/README.md

@@ -0,0 +1,220 @@
+# a32translator: AArch32 → AArch64 dynamic binary translator
+
+`a32run` runs 32-bit ARM Linux programs (ARM, Thumb-2, VFPv4, NEON, plus the ARMv8 AArch32 additions) on an
+AArch64 host without AArch32 support, such as the Steam Frame's SteamOS. It is a user-mode translator (like
+`qemu-arm`). It decodes guest instructions, runs them through a JIT that emits native A64 code, and translates
+system calls to the host kernel.
+
+Status: proof of concept. It runs static bionic (Android NDK) programs, including C++ with exceptions, pthreads,
+signals, fork, self-modifying code and NEON. The Android bridge (below) runs 32-bit JNI and NativeActivity
+libraries inside a 64-bit app, verified in a Lepton container on the Frame; games additionally need GLES/EGL,
+OpenSL/AAudio, libandroid and VrApi thunks (see "Next steps").
+
+```
+python native/a32translator/build.py          # -> native/a32translator/out/a32run (static AArch64, NDK clang)
+a32run [--interp] [--strace] [--trace] [--sysroot DIR] [-v] program [args...]
+```
+
+Environment: `A32_STATS=1` (block/chain statistics at exit), `A32_DUMP=file` (translated code, see
+`tools/jitdump.py`), `A32_EXACT_ADDR=1` (guest address arithmetic modulo 2^32, see below), `A32_CACHE_KB=n`
+(small code cache, exercises flushes), `A32_INTERP=1`, `A32_STRACE=1`, `A32_PERFMAP=<file>|1` (a perf map of the
+translated code: `a32:<pc>` block bodies, `a32:exits` exit stubs, `a32:fpcr` FPCR writes; `1` writes
+`/tmp/perf-<pid>.map`, which `perf report` reads).
+
+32-bit bionic refuses pids above 65535, which hosts with a large `pid_max` (SteamOS: 4194304) exceed. Start such
+programs in a fresh pid namespace: `unshare -Urpf --kill-child a32run prog`.
+
+## How it works
+
+```
+ guest bytes ─┬─ a32_decode.c (A32) ───┐
+              └─ t32_decode.c (T32) ───┼─► insn_t ─┬─► interp*.c  (reference semantics, fallback)
+   vfp_neon_decode.c (VFP/NEON) ◄──────┘           └─► jit.c / jit_vfp.c (A64 code) ─► code cache
+```
+
+- **One instruction form, two backends.** Both decoders produce `insn_t` (`insn.h`). T32 VFP/NEON encodings are
+  rewritten to their A32 form first, so one decoder serves both instruction sets. The interpreter (`interp.c`,
+  `interp_vfp.c`, `interp_neon.c`) defines the semantics of everything. The JIT translates the common
+  instructions natively and calls the interpreter for the rest (`jx_call_helper`), so every instruction the
+  interpreter knows also works in JIT mode.
+- **Register mapping.** Guest r0-r14 are pinned in x0-x14 (upper halves always zero), q0-q15 in v16-v31, and the
+  guest NZCV lives in the host NZCV. x19 points to the `a32_cpu` state. The guest PC is a translation-time
+  constant. Scratch registers: x15-x17, x20-x23, v0-v7. Within a block, scalar VFP values are cached in v8-v15:
+  writing a lane of a pinned Q register would chain loop iterations through the merge. The cache is flushed at
+  exits, helper calls and branches.
+- **Flags.** A64 ADDS/SUBS/ADCS/SBCS set NZCV exactly like AArch32. Logical flag-setting instructions get N/Z
+  from the result, C from the shifter and V unchanged (`set_nzc`). Conditional instructions branch over their
+  code (the condition encodings match).
+- **Floating point.** Guest FP operations run as the identical A64 instructions with the guest's FPSCR control
+  bits in FPCR (FPCR/FPSR share FPSCR's bit layout), so rounding, flush-to-zero, default NaN and exception flags
+  match by construction. Advanced SIMD floating point runs with the "standard FPSCR value" (DN, FZ, round to
+  nearest). Blocks switch FPCR only around such operations. VMLA/VMLS stay unfused (multiply, then add) and
+  VRECPS/VRSQRTS go to the interpreter (non-fused in AArch32, fused in A64). The interpreter uses inline A64
+  instructions as well.
+- **Blocks.** A block (a superblock) ends at the first unconditional branch or other PC write, an SVC/UDF, or
+  after 96 instructions. Conditional branches and CBZ/CBNZ are side exits: translation continues on the
+  fall-through path, so a loop with an early exit is still one block. Blocks are keyed by (pc, Thumb, ITSTATE), so
+  IT blocks may span block boundaries. Direct exits are patchable `b` instructions that get chained to their
+  target. Indirect branches (BX LR, POP {pc}, LDR pc, TBB) look the target up inline in a direct-mapped table. A
+  branch back to the block's own start is a plain `b`/`b.cond`. Every block starts with a check of
+  `cpu->interrupt`, which signals and code flushes set, so chained loops still stop.
+- **Code quality.** Conditional data-processing instructions that don't set flags become compute + `csel`
+  (branchless). VCMP followed by VMRS APSR_nzcv leaves the compare's flags in NZCV directly. LDREX/STREX (all
+  sizes) are an inline compare-and-swap loop (`ldxr`/`stxr`). Thumb's flag-setting register shifts
+  (LSLS/LSRS/ASRS/RORS Rdn, Rm) compute the AArch32 carry for 0-255 bit amounts inline. In the benchmark below,
+  no instruction goes to the interpreter (`A32_STATS=1` lists the ones that do).
+- **Memory.** Guest addresses are host addresses: the low 4 GiB are reserved at start-up (`mem.c`) and the
+  guest's mappings live there, so loads and stores need no translation and most syscalls pass pointers through.
+  Translated code uses A64 addressing modes (`[xn, #imm]`). They differ from AArch32 only when guest address
+  arithmetic wraps past 4 GiB: such an access then faults above 4 GiB, and the fault is still delivered to the
+  guest. `A32_EXACT_ADDR=1` computes every address modulo 2^32 instead. Unaligned LDRD/LDM/VLDn are allowed
+  (newer arm64 kernels fix them up for AArch32 too); qemu raises SIGBUS. The host page size must be 4 KiB.
+- **Self-modifying code.** `cacheflush` (what `__builtin___clear_cache` calls on ARM), `mprotect`, `munmap` and
+  `mremap` invalidate the translated blocks of the affected pages and unlink chains into them. Each guest page keeps
+  a list of its blocks, so an invalidation only visits those (Unity's Mono JIT flushes new code next to translated
+  code all the time; scanning every block made that 72 % of Spunky Dungeon's main thread). A full cache
+  (128 MiB) is flushed once every thread has left translated code.
+- **Faults.** A guest memory fault in translated code is mapped back to the guest instruction (per-instruction
+  host offsets, plus the VFP cache state). The guest registers are rebuilt from the signal context, and the
+  guest's handler gets a proper ARM `rt_sigframe` (VFP state included). Returning from it restarts the
+  instruction.
+- **Syscalls** (`syscall.c`): ARM EABI numbers (generated from the NDK headers, `tools/gen_syscalls.py`) map to
+  AArch64 ones. Structures whose 32-bit layout differs are converted: stat64, statfs64, timespec/timeval, iovec,
+  rusage, sysinfo, rlimit, flock, msghdr with control messages, getdents. The guest persona (`PER_LINUX32`) is
+  emulated, because hosts without AArch32 refuse it. ARM private calls (set_tls, cacheflush) and kuser helpers
+  (0xffff0fxx) are implemented. `execve` of a 32-bit ARM ELF re-executes `a32run`.
+- **Signals** (`signals.c`): host handlers queue signals; delivery happens at block boundaries with the ARM
+  kernel's frame layouts (`sigframe`/`rt_sigframe`, `sigaltstack`, SA_RESTORER, SA_NODEFER, SA_RESETHAND).
+  Guest SIG_DFL/SIG_IGN dispositions stay on the host, so the kernel applies default actions itself.
+- **Threads** (`threads.c`): `clone` with CLONE_VM|CLONE_THREAD starts a host pthread running its own `a32_cpu`.
+  Other clones become `fork`. The code cache is shared: a mutex guards translation and chaining only. The run loop
+  finds blocks without it (the inline lookup table first, then the hash chains) and puts each block it dispatched
+  back into the inline table, so a block translated later into the same slot can't shut a hot return target out.
+  Each thread flags itself while it is in the run loop or translated code; a cache flush waits for the flags (a
+  shared counter cost every dispatch a contended atomic).
+  LDREX/STREX are emulated as compare-and-swap on the exclusive value; ABA changes are not detected.
+
+Not supported: big-endian data (SETEND BE), ARMv8.1+ AArch32 extensions (FP16 arithmetic, RDM, JSCVT, dot
+product), VFP short vectors (Len/Stride, absent on ARMv8 anyway), robust futex lists, and the iWMMXt/ThumbEE
+relics. FPSCR exception *traps* are not emulated (flags are).
+
+## Android bridge
+
+A converted APK runs its 32-bit libraries in its own 64-bit process, without Android's native-bridge mechanism
+(Lepton would need `ro.dalvik.vm.native.bridge` and 32-bit ABI lists for that). Every 32-bit library `libX.so`
+moves to `lib/arm64-v8a/libX.a32.so`; `libX.so` becomes a copy of the stub, next to the bridge and the guest
+runtime:
+
+```
+python native/a32translator/bridge/build.py [--test]
+  out/bridge/liba32stub.so    arm64 stub (copied as libX.so): JNI_OnLoad, ANativeActivity_onCreate -> bridge
+  out/bridge/liba32bridge.so  arm64: the translator + bridge/host (exports a32b_*, bridge/host/a32bridge.h)
+  out/bridge/liba32rt.so      32-bit ARM static PIE: the guest runtime and the guest's "system libraries"
+```
+
+- **Guest runtime** (`bridge/guest`): bionic's static libc/libm/libz/libstdc++/libunwind, linked whole and
+  exported through a table (`gen/exports.S`), plus a loader for the game's libraries (bionic's lookup order, packed
+  relocations, RELR, `dlopen`/`dlsym`/`dladdr`/`dl_iterate_phdr`, ARM EHABI unwinding through
+  `dl_unwind_find_exidx`). Symbols nothing defines become stubs that log their name and return 0. Libraries the
+  guest knows as system libraries (`libGLESv2.so`, ...) resolve against the export table.
+- **Hypercalls** (`bridge/abi.h`): guest code calls the host with `SVC 0` and `r7 = 0x0a32xxxx`; host-to-guest
+  calls return through a trampoline in the kuser page. The thread that starts the bridge becomes the guest's main
+  thread; any other host thread gets its own guest thread on its first call (the runtime's service thread creates
+  it, and the clone is handed to the waiting host thread). Calls nest: Java -> guest -> JNI -> Java -> guest.
+- **JNI** (`bridge/host`): the guest gets 32-bit `JNIEnv`/`JavaVM` tables whose entries are hypercalls.
+  `gen_stubs.py` generates the simple functions from `jni.h`; `jni.c` has the rest (variadic/`va_list`/`jvalue[]`
+  calls read with the method's shorty, strings and arrays: shared when the data lies below 4 GiB, as ART's heap
+  does, else copied and written back). Objects, method and field IDs are 32-bit handles (`handles.c`). Native
+  methods (RegisterNatives, and exported `Java_*` functions, matched to their Java declarations by reflection) get a
+  trampoline slot (`tramp.S`, `natives.c`) that converts AAPCS64 arguments to AAPCS32.
+- **NativeActivity** (`native_activity.c`): a 32-bit `ANativeActivity` mirrors the host's; the host callbacks
+  forward to the guest's. Windows, input queues and asset managers are handles. libandroid functions are listed in
+  `bridge/imports.txt` (generated host side).
+- The bridge shares the low 4 GiB with the host process: `mem.c` reads `/proc/self/maps` and never hands out host
+  mappings; host faults go to the host's own handlers (ART's); translator reports on stderr go to logcat (tag
+  `a32`).
+
+- **GLES/EGL** (`gen_gl.py`, `host/gl.c`): every function of the NDK's GLES 3.2 + extension and EGL headers is a
+  hypercall stub (Unity fetches most through `dlsym`/`eglGetProcAddress`); EGL objects and GLsyncs are handles,
+  driver strings are copied, buffer mappings outside the guest's reach get a guest copy written back at flush/unmap.
+- **VrApi 1.x** (`host/vrapi.c`): Gear VR-era games call the old API (`vrapi_SubmitFrame` with `ovrFrameParms`,
+  `vrapi_GetPredictedTracking`). The runtime exports it itself (`libvrapi.so` is a system library; the game's copy is
+  Oculus' loader and is dropped) and translates it to FramePort's 64-bit VrApi -> OpenXR bridge (shipped as
+  `libfp_vrapi64.so`, with OVRPort's OpenXR dispatcher and the FrameBridge adapter). Layouts are VrApi 1.5's.
+- **OpenSL ES** (`guest/opensles.c`): engine, output mix and PCM players with an Android buffer queue, implemented in
+  the guest (OpenSL objects are function tables); a guest thread per player writes to AAudio on the host.
+- **Signals**: host handlers never use SA_RESTART; a blocking system call interrupted by a guest signal is
+  restarted after the guest's handler (as the kernel's -ERESTARTSYS), and a thread running host code (Java, a JNI or
+  GL call) runs the guest handler at once. Boehm GC (Unity's Mono) stops the world with signals and hung without it.
+- `bridge/convert.py IN.apk OUT.apk` (prototype of the FramePort patch): moves the 32-bit libraries, adds the stubs,
+  bridge, runtime and VR libraries, sets LAUNCHER and targetSdkVersion >= 23 (an older one gets Android's "built for
+  an older version" dialog, which takes the focus: Unity never starts), and points libunity's Oculus check at
+  "android" (like `frame.unity_oculus_check`). Unity games also need the flat window (`device.text_input_window`):
+  Unity only renders with window focus.
+- Debugging: `A32_WATCH=<s>` logs every guest thread's pc and the return addresses on its stack as `lib+offset`;
+  `A32B_TRACE=1` logs native registrations and calls; `A32_STRACE`, `A32_INTERP` as for a32run. Set them through the
+  recipe's `device.lepton_env` (`LEPTON_ENV_<NAME>`).
+
+Learned on the way: `-static-pie` links `crtbegin_dynamic.o`, which leaves `.init_array` to a dynamic linker (so
+none of libc's own constructors ran: bionic's systrace property crashed in an Android process); bionic's arm32
+static start-up code also reads `PT_TLS`/`PT_GNU_RELRO` as if the program sat at its link address, so the loader
+moves both by the load bias.
+
+Tests:
+- `python bridge/test/run.py [--interp]` (after `build.py --test`): the harness (`bridge/test/harness.c`) plays ART
+  with a fake JVM (`fakejni.c`) for three guest libraries: RegisterNatives and `Java_*` exports, 12-argument
+  natives (stack arguments on both sides), floats/doubles/bytes, strings, arrays below and above 4 GiB, every
+  Call*Method style, NewObject, nested calls, guest threads that attach, several host threads, exceptions, a
+  NativeActivity with a DT_NEEDED library, and C++ exceptions in guest libraries using ordinary REL,
+  standard RELR and Android's older RELR tags (with APS2). Runs under qemu-aarch64 or
+  natively (passes on the Frame with JIT and interpreter).
+- `uv run python bridge/test/make_apk.py`: `org.frameport.a32test`, a NativeActivity APK without Java code whose
+  library is 32-bit (`bridge/test/libapktest.c`). Installed with FramePort (`frameport scan`, then `frameport
+  install org.frameport.a32test --apk ...`, `frameport test`), it logs `A32TEST ok|FAIL` lines (tag `a32test`):
+  real ART calls (`Build.MODEL`, `String.format`, `Math.hypot`, arrays, exceptions), a guest thread, a dlopen'd C++
+  library, and the activity's callbacks with the real window. All pass in Lepton (2026-10-10).
+
+## Testing
+
+All of these run on an x86-64 PC through `qemu-aarch64`, with `qemu-arm` as the reference, or natively on an
+AArch64 machine with `--runner ""`.
+
+- `tests/test_a64.py`: every A64 encoder in `src/a64.h` against `llvm-mc` (400 encodings).
+- `tests/fuzz.py`: differential instruction fuzzer. Random encodings per class (`arm-dp`, `arm-ldst`,
+  `arm-media`, `arm-ldm`, `arm-vfp`, `arm-neon`, `arm-neon-ldst`, `arm-v8`, `t16`, `t32`, `t32-neon`,
+  `t32-vfp`) are filtered with `arm-none-eabi-objdump` and with the translator's own UNPREDICTABLE flag
+  (`tools/a32dis.c`). Each runs once in a harness that loads random registers, flags, FPSCR and NEON state, and
+  dumps them afterwards together with a hash of the touched memory. The harness's own signal handler records
+  UNDEF and memory faults per test, so UNDEF decoding is compared too. Runs `qemu-arm -cpu max`, then `a32run
+  --interp`, then `a32run`. Known, deliberate differences are filtered: qemu's alignment faults, ARMv8.1+
+  features, and encodings in ARMv7's unallocated space that qemu executes.
+- `tests/run_programs.py`: C/C++ programs built with the NDK for ARM and Thumb (static bionic), compared with
+  `qemu-arm` in both modes: libc/libm/printf, memory and string routines, NEON intrinsics, pthreads and atomics,
+  signals (handlers, SIGSEGV recovery, itimers, fork), file system calls, C++ exceptions/RTTI/STL/std::thread,
+  run-time generated code (`jitguest`) and a benchmark. `A32_CACHE_KB=300` exercises cache flushes.
+
+Benchmark (`tests/programs/bench.c 10`) on the Steam Frame, medians of three runs (the headset's clocks vary by
+up to ±30 % between runs), against the same source built natively for AArch64:
+
+| | native AArch64 | a32run, ARM build | a32run, Thumb build |
+|---|---|---|---|
+| sieve | 0.11 s | 0.12 s | 0.10 s |
+| crc32 + sha256 | 0.39 s | 0.42 s | 0.57 s |
+| qsort | 0.15 s | 0.21 s | 0.25 s |
+| float matmul | 0.017 s (auto-vectorized) | 0.27 s (scalar VFP: ARMv7 compilers don't vectorize float) | 0.27 s |
+| double mandelbrot | 0.21 s | 0.44 s | 0.41 s |
+| libm | 0.06 s | 0.25 s | 0.27 s |
+
+## Next steps
+
+1. First game: AFFECTED The Manor (Gear VR, Unity 5.6.0f3 + Mono, OVRPlugin 1.12, 2017). Headless on the Frame
+   (2026-10-10): Unity and its C# scripts run, audio plays, the OpenXR session starts and submits frames at 72 fps.
+   Not yet seen in a headset. Open: Gear VR input (touchpad/back, controller API reports no devices), the rest of
+   libandroid (ALooper callbacks, AInputQueue, AAsset*), host-to-guest callbacks (GL debug output, sensor queues).
+2. A FramePort patch that converts an APK (libraries moved, stubs, bridge, runtime, `extractNativeLibs=true`) +
+   triage signature + PLAYBOOK row.
+3. Bridge gaps: guest threads of host threads that exit are never freed; `Java_*` functions of libraries the guest
+   dlopens itself aren't registered; `GetDirectBufferAddress` of buffers above 4 GiB returns 0; signals the guest
+   handles are only delivered to guest threads.
+4. JIT: VLDn single-lane/all-lanes forms, flag liveness (skip unused C/V computations), keeping the VFP cache
+   across a loop's back edge, and VRECPS/VRSQRTS/VCVTR natively.

native/a32translator/bridge/abi.h

@@ -0,0 +1,41 @@
+/* Interface between the guest runtime (liba32rt.so, 32-bit ARM) and the host bridge (arm64).
+ *
+ * The guest calls the host with a hypercall: SVC 0 with r7 = A32_HYPERCALL | n, arguments in r0-r3 and on the
+ * stack (AAPCS, softfp), result in r0 (r0:r1 for 64-bit values). The host calls guest functions on the calling
+ * thread's guest context; they return through A32_RETURN_TRAMPOLINE. Keep both sides in sync. */
+#ifndef A32_BRIDGE_ABI_H
+#define A32_BRIDGE_ABI_H
+
+#define A32B_VERSION 1
+
+/* hypercall numbers (low 16 bits of r7) */
+#define HC_RETURN 1       /* end of a host-to-guest call; also parks a thread that has nothing to do */
+#define HC_READY 2        /* r0 = struct grt_info *: the runtime is initialised (main thread parks here) */
+#define HC_WAIT_WORK 3    /* service thread: blocks until the host has work; returns a WORK_* code */
+#define HC_LOG 4          /* r0 = priority, r1 = tag, r2 = message */
+#define HC_UNRESOLVED 5   /* r0 = symbol name: a guest library called a symbol nothing defines */
+#define HC_ABORT 6        /* r0 = message: the guest runtime gave up */
+#define HC_JNI 0x100      /* + JNINativeInterface index (0..232) */
+#define HC_VM 0x200       /* + JNIInvokeInterface index (0..7) */
+#define HC_IMPORT 0x300   /* + index into the host import table (bridge/imports.txt) */
+#define HC_GL 0x1000      /* + index into the GLES/EGL table (gen_gl.py) */
+
+/* service thread work */
+#define WORK_NONE 0
+#define WORK_ATTACH 1     /* pthread_create a thread that the waiting host thread adopts (threads.h) */
+
+#define JNI_TABLE_SIZE 233
+#define VM_TABLE_SIZE 8
+
+/* Guest addresses the host needs, passed with HC_READY. All fields are 32-bit guest addresses. */
+struct grt_info {
+    unsigned version;
+    unsigned jni_env;       /* JNIEnv: one for every thread (the host finds the thread itself) */
+    unsigned java_vm;       /* JavaVM */
+    unsigned fn_malloc, fn_free;
+    unsigned fn_dlopen, fn_dlsym, fn_dlerror;  /* the runtime's loader (bionic semantics, LP32 RTLD_* values) */
+    unsigned fn_attached_entry;
+    unsigned fn_list_symbols; /* (handle, prefix) -> malloc'd (name, address) pairs, 0-terminated */
+};
+
+#endif

native/a32translator/bridge/build.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Builds the Android bridge with the NDK (see ../README.md, "Android bridge"):
+
+  out/bridge/liba32rt.so      guest runtime: static 32-bit ARM bionic program (static PIE), the "system libraries"
+  out/bridge/liba32bridge.so  host bridge (arm64): the translator + JNI/NativeActivity/libandroid glue
+  out/bridge/liba32stub.so    host stub (arm64), copied once per 32-bit library as libX.so
+  --test: out/bridge/test/harness (static arm64 program: fake JNI + the bridge) and libbtest.a32.so (armv7 guest
+          library); python bridge/test/run.py runs them
+
+    python bridge/build.py [--test] [--debug] [--ndk PATH]
+"""
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parent
+NDK_DEFAULT = ROOT.parent / ".cache" / "ndk-27.2.12479018"
+OUT = ROOT / "out" / "bridge"
+TRANSLATOR = ["dispatch.c", "mem.c", "loader.c", "syscall.c", "signals.c", "threads.c", "interp.c", "interp_vfp.c",
+              "interp_neon.c", "a32_decode.c", "t32_decode.c", "vfp_neon_decode.c", "jit.c", "jit_vfp.c",
+              "jit_glue.S"]
+HOST = ["bridge.c", "handles.c", "jni.c", "natives.c", "native_activity.c", "android.c", "vrapi.c", "input.c", "tramp.S", "gen/jni_gen.c",
+        "gen/imports.c"]
+HOST_GL = ["gl.c", "gen/gl.c"]  # not in the PC harness (no GLES there)
+GUEST = ["main.c", "loader.c", "compat.c", "log.c", "gl.c", "opensles.c", "hc.S", "gen/stubs.S", "gen/gl_stubs.S", "gen/exports.S"]
+WARN = ["-Wall", "-Wextra", "-Wno-unused-parameter", "-Wno-missing-field-initializers"]
+
+
+def run(cmd):
+    print(" ".join(str(c) for c in cmd[:1]) + " ... -o " + str(cmd[cmd.index("-o") + 1]))
+    r = subprocess.run([str(c) for c in cmd])
+    if r.returncode:
+        sys.exit(r.returncode)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--ndk", default=str(NDK_DEFAULT))
+    ap.add_argument("--debug", action="store_true")
+    ap.add_argument("--test", action="store_true")
+    a = ap.parse_args()
+    bin_ = Path(a.ndk) / "toolchains/llvm/prebuilt/linux-x86_64/bin"
+    if not bin_.exists():
+        sys.exit(f"{bin_} not found (run python native/build.py once to fetch the NDK)")
+    cc64 = bin_ / "aarch64-linux-android30-clang"
+    cc32 = bin_ / "armv7a-linux-androideabi30-clang"
+    OUT.mkdir(parents=True, exist_ok=True)
+    subprocess.run([sys.executable, str(HERE / "gen_stubs.py"), "--ndk", a.ndk], check=True)
+    opt = ["-O0", "-g"] if a.debug else ["-O2", "-g"]
+    # The cache can be symlinked into a worktree. Clang records both the spelling
+    # used on the command line and the resolved NDK path, plus the compilation cwd.
+    prefix = [f"-ffile-prefix-map={ROOT.parent.parent}=frameport",
+              f"-ffile-prefix-map={ROOT}=a32translator",
+              f"-ffile-prefix-map={Path(a.ndk).absolute()}=ndk",
+              f"-ffile-prefix-map={Path(a.ndk).resolve()}=ndk"]
+
+    # guest runtime: everything a guest library may link against comes from the static archives (exports.S
+    # references each symbol, so the linker keeps them)
+    g = HERE / "guest"
+    # -static-pie links crtbegin_dynamic.o, which leaves .init_array to a dynamic linker that isn't there: use the
+    # static start files (libc's own constructors run from them)
+    crt = Path(a.ndk) / "toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/arm-linux-androideabi/30"
+    run([cc32, *opt, *prefix, *WARN, "-mthumb", "-mfpu=neon-vfpv4", "-std=gnu11", "-static-pie", "-nostartfiles",
+         crt / "crtbegin_static.o", *[g / s for s in GUEST], "-lz", "-lm", "-lstdc++", "-Wl,--no-gc-sections", "-Wl,--wrap=dl_unwind_find_exidx", crt / "crtend_android.o", "-o",
+         OUT / "liba32rt.so"])
+
+    h = HERE / "host"
+    src = ROOT / "src"
+    common = [*opt, *prefix, *WARN, "-march=armv8-a+crypto", "-std=gnu11", "-fno-strict-aliasing", "-fPIC"]
+    run([cc64, *common, "-shared", "-fvisibility=hidden", *[src / s for s in TRANSLATOR], *[h / s for s in HOST + HOST_GL],
+         "-llog", "-landroid", "-laaudio", "-lEGL", "-lGLESv3", "-ldl", "-lm", "-Wl,--no-undefined", "-Wl,-soname,liba32bridge.so", "-o", OUT / "liba32bridge.so"])
+    run([cc64, *common, "-shared", "-fvisibility=hidden", h / "stub.c", "-L", OUT, "-la32bridge",
+         "-Wl,--no-undefined", "-o", OUT / "liba32stub.so"])
+
+    if a.test:
+        t = HERE / "test"
+        to = OUT / "test"
+        to.mkdir(exist_ok=True)
+        # the harness is static (runs under qemu-aarch64 or on any arm64 Linux): high image base keeps the
+        # low 4 GiB free, like a32run's
+        run([cc64, *common, "-DA32B_STDERR_LOG", "-DA32B_TEST", "-static", "-Wl,--image-base=0x7000000000", "-I", h,
+             t / "harness.c", t / "fakejni.c", *[src / s for s in TRANSLATOR], *[h / s for s in HOST], "-lm", "-ldl",
+             "-o", to / "harness"])
+        run([cc32, *opt, *prefix, *WARN, "-mthumb", "-mfpu=neon-vfpv4", "-shared", "-fPIC", t / "libbtest.c",
+             "-Wl,-soname,libbtest.so", "-llog", "-o", to / "libbtest.a32.so"])
+        run([cc32, *opt, *prefix, *WARN, "-marm", "-mfpu=neon-vfpv4", "-shared", "-fPIC", t / "libbtest2.c",
+             to / "libbtest.a32.so", "-landroid", "-llog", "-o", to / "libbtest2.a32.so"])
+        run([bin_ / "armv7a-linux-androideabi30-clang++", *opt, *prefix, *WARN, "-mthumb", "-shared", "-fPIC",
+             "-static-libstdc++", t / "libbtest3.cpp", "-o", to / "libbtest3.a32.so"])
+        # Exercise both RELR tag families through the real guest loader. C++ constructors,
+        # pointer tables and exceptions need relative relocations; Android's older tags
+        # occur in Quest libraries (e.g. Journey of the Gods' OVRPlugin).
+        for tags in ("android", "standard"):
+            run([bin_ / "armv7a-linux-androideabi30-clang++", *opt, *prefix, *WARN, "-mthumb", "-shared", "-fPIC",
+                 "-static-libstdc++", t / "libbtest3.cpp", "-Wl,--pack-dyn-relocs=android+relr",
+                 "-Wl,--use-android-relr-tags" if tags == "android" else "-Wl,--no-use-android-relr-tags",
+                 "-o", to / f"libbtest3_{tags}.a32.so"])
+        shutil.copy(OUT / "liba32rt.so", to / "liba32rt.so")
+
+
+if __name__ == "__main__":
+    main()

native/a32translator/bridge/convert.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Converts a 32-bit-only APK to run on arm64 through the bridge, for bridge development (FramePort builds do the
+same with the patch frame.a32_bridge, src/frameport/patches/frame/a32_bridge.py, which this script uses):
+
+  lib/armeabi-v7a/libX.so -> lib/arm64-v8a/libX.a32.so (the guest code) + lib/arm64-v8a/libX.so (the stub)
+  + lib/arm64-v8a/liba32bridge.so, liba32rt.so; other ABIs dropped; extractNativeLibs forced on; signed with
+  FramePort's key for the package; INFO-only start activities get LAUNCHER (Lepton needs it); targetSdkVersion
+  raised to 23 (older ones get a dialog that takes the focus).
+
+    uv run python native/a32translator/bridge/convert.py IN.apk OUT.apk [--replace libvrapi.so=FILE ...]
+
+Build the bridge first (python native/a32translator/bridge/build.py). --replace puts FILE (a 32-bit library) in
+place of the APK's own copy.
+"""
+import argparse
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+OUT = HERE.parent / "out" / "bridge"
+REPO = HERE.parents[2]
+# test builds instead of the artifacts: A32_VRAPI_BRIDGE (the 64-bit VrApi bridge), A32_FRAME_SETTINGS (FrameBridge
+# settings, "key=value;..."); the bridge itself always comes from out/bridge (this script is for bridge development)
+VRAPI_BRIDGE = Path(os.environ.get("A32_VRAPI_BRIDGE") or REPO / "artifacts/arm64-v8a/libvrapi.so")
+FRAME_SETTINGS = (b"scale=1.0\nfoveation_fix=1\ncontroller_fix=1\n"
+                  + os.environ.get("A32_FRAME_SETTINGS", "").replace(";", "\n").encode())
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("apk")
+    ap.add_argument("out")
+    ap.add_argument("--replace", action="append", default=[], metavar="LIB=FILE")
+    a = ap.parse_args()
+    sys.path.insert(0, str(REPO / "src"))
+    from pyaxmlparser import APK
+
+    from frameport.apk import axml, sign
+    from frameport.apk.workspace import ApkWorkspace
+    from frameport.core.events import Reporter
+    from frameport.patches.frame import a32_bridge
+    from frameport.tools import overport
+
+    package = APK(a.apk).package
+    replace = {k: Path(v).read_bytes() for k, v in (r.split("=", 1) for r in a.replace)}
+
+    def prebuilt(name: str) -> bytes:
+        if name == "libvrapi.so":
+            return VRAPI_BRIDGE.read_bytes()
+        return (OUT / name if name.startswith("liba32") else REPO / "artifacts/arm64-v8a" / name).read_bytes()
+
+    def ovrport(name: str, abi: str) -> bytes:
+        return overport.ensure_runtime_lib(name, abi, Reporter()).read_bytes()
+
+    with ApkWorkspace(Path(a.apk)) as ws, tempfile.TemporaryDirectory() as td:
+        libs = a32_bridge.convert(ws, prebuilt, ovrport, replace)
+        if ws.has(a32_bridge.SIGNATURE_ASSET):
+            print("original APK signature for the UE4 check:", ws.read(a32_bridge.SIGNATURE_ASSET).decode().strip())
+        manifest = ws.read("AndroidManifest.xml")
+        ws.put("AndroidManifest.xml", axml.fix_launcher(manifest) or manifest)  # Lepton starts the LAUNCHER activity
+        if ws.has(ws.lib("libopenxr_loader_generic.so")):  # FrameBridge's settings (frame.adapter in a build)
+            ws.put(ws.lib("libframe_settings.so"), FRAME_SETTINGS)
+        unsigned = Path(td) / "unsigned.apk"
+        ws.write(unsigned)
+        sign.sign(unsigned, Path(a.out), package)
+    print(f"{a.out}: {package}, {len(libs)} libraries converted")
+
+if __name__ == "__main__":
+    main()

native/a32translator/bridge/gen_gl.py

@@ -0,0 +1,162 @@
+"""GLES/EGL thunks, generated from the NDK's headers (called by gen_stubs.py):
+
+  guest/gen/gl_stubs.S  one hypercall stub per function (HC_GL + index), exported by the runtime
+  host/gen/gl.c         the host side: arguments read per type, the host function called through a pointer that
+                        gl_resolve() looks up (libGLESv3/libEGL, else eglGetProcAddress)
+
+Functions whose arguments can't be passed through as they are (pointer arrays, host pointers as results, callbacks)
+are written by hand in host/gl.c (SPECIAL), or left out: their stub logs the name and returns 0.
+"""
+import re
+from pathlib import Path
+
+HEADERS = ["GLES3/gl32.h", "GLES2/gl2ext.h", "EGL/egl.h", "EGL/eglext.h"]
+HC_GL = 0x1000
+# host pointers the guest sees as handles (handles.c ptr2h)
+HANDLES = {"EGLDisplay", "EGLSurface", "EGLContext", "EGLConfig", "EGLImageKHR", "EGLImage", "EGLSyncKHR", "EGLSync",
+           "EGLClientBuffer", "EGLNativeWindowType", "EGLNativePixmapType", "EGLNativeDisplayType", "EGLStreamKHR",
+           "GLeglImageOES", "EGLDeviceEXT", "EGLOutputLayerEXT", "EGLOutputPortEXT", "GLeglClientBufferEXT",
+           "EGLLabelKHR", "EGLObjectKHR", "EGLSyncNV"}
+SYNC = {"GLsync"}  # freed with glDeleteSync: their own table (gl.c)
+FLOAT = {"GLfloat", "GLclampf"}
+INT64 = {"GLint64", "GLuint64", "GLint64EXT", "GLuint64EXT", "EGLTimeKHR", "EGLTime", "EGLuint64KHR",
+         "EGLnsecsANDROID", "EGLuint64NV", "EGLTimeNV"}
+INTPTR = {"GLintptr", "GLsizeiptr", "GLintptrARB", "EGLAttrib", "EGLAttribKHR", "EGLsizeiANDROID"}
+CALLBACK = re.compile(r"PROC|Func")
+# hand-written in host/gl.c as gl_<name>(a32_cpu *c, argreader *R, void *fn)
+SPECIAL = {
+    "glShaderSource", "glGetString", "glGetStringi", "eglQueryString", "glMapBufferRange", "glMapBufferRangeEXT",
+    "glMapBufferOES", "glUnmapBuffer", "glUnmapBufferOES", "glFlushMappedBufferRange",
+    "glFlushMappedBufferRangeEXT", "eglChooseConfig", "eglGetConfigs", "glTransformFeedbackVaryings",
+    "glGetUniformIndices", "glDeleteSync", "glDebugMessageCallback", "glDebugMessageCallbackKHR",
+}
+GUEST_IMPL = {"eglGetProcAddress"}  # implemented inside the runtime (guest/gl.c)
+
+
+def parse(include: Path):
+    funcs = {}
+    for h in HEADERS:
+        text = (include / h).read_text()
+        text = re.sub(r"/\*.*?\*/", "", text, flags=re.S)
+        for m in re.finditer(r"(?:GL_APICALL|EGLAPI)\s+(.+?)\s*(?:GL_APIENTRY|EGLAPIENTRY)\s+(\w+)\s*\(([^;]*?)\)\s*;",
+                             text, re.S):
+            ret, name, params = " ".join(m.group(1).split()), m.group(2), " ".join(m.group(3).split())
+            if name in funcs:
+                continue
+            ps = [] if params in ("", "void") else [p.strip() for p in params.split(",")]
+            types = []
+            for p in ps:
+                # drop the parameter name (the last identifier, unless the whole thing is a type)
+                t = re.sub(r"\b(\w+)\s*(\[\s*\w*\s*\])?$", "", p).strip() if not p.endswith("*") else p
+                if not t or t in ("const",):
+                    t = p
+                if re.search(r"\[\s*\w*\s*\]$", p):
+                    t += " *"
+                types.append(" ".join(t.split()))
+            funcs[name] = (ret, types)
+    return funcs
+
+
+def kind(t: str) -> str:
+    t = t.replace("const", "").strip()
+    stars = t.count("*")
+    base = t.replace("*", "").strip()
+    if stars >= 2:
+        return "?"
+    if stars == 1:
+        if base in HANDLES or base in SYNC or base in INTPTR:
+            return "?"  # arrays of host-sized values: by hand
+        return "P"
+    if CALLBACK.search(base):
+        return "?"
+    if base == "void":
+        return "v"
+    if base in HANDLES:
+        return "H"
+    if base in SYNC:
+        return "Y"
+    if base in FLOAT:
+        return "f"
+    if base in INT64:
+        return "J"
+    if base in INTPTR:
+        return "Z"
+    if base.startswith("__egl"):  # eglGetProcAddress's result type
+        return "?"
+    return "I"
+
+
+def generate(ndk: str, gdir: Path, hdir: Path) -> list[str]:
+    include = Path(ndk) / "toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/include"
+    funcs = parse(include)
+    names = sorted(n for n in funcs if n not in GUEST_IMPL)
+    out = ["/* generated by bridge/gen_gl.py from the NDK's GLES/EGL headers: do not edit */", "",
+           "#define GL_GLEXT_PROTOTYPES 1", "#define EGL_EGLEXT_PROTOTYPES 1", "#include <EGL/egl.h>",
+           "#include <EGL/eglext.h>", "#include <GLES3/gl32.h>", "#include <GLES2/gl2ext.h>",
+           '#include "../gl_internal.h"', ""] + [f"void gl_{n}(a32_cpu *c, argreader *R, void *fn);" for n in sorted(SPECIAL)] + ["",
+           f"const int gl_count = {len(names)};", "const char *const gl_names[] = {"]
+    out += [f'    "{n}",' for n in names] + ["};", "",
+                                              "int gl_dispatch_generated(a32_cpu *c, int index, argreader *R, void *fn)",
+                                              "{", "    switch (index) {"]
+    skipped = []
+    for i, n in enumerate(names):
+        ret, types = funcs[n]
+        if n in SPECIAL:
+            out += [f"    case {i}: gl_{n}(c, R, fn); return 1;"]
+            continue
+        ks = [kind(t) for t in types]
+        rk = kind(ret)
+        if "?" in ks or rk == "?" or "v" in ks or (rk == "P" and not re.search(r"char|GLubyte", ret)):
+            skipped.append(n)
+            continue
+        decl, args = [], []
+        for k, (kd, t) in enumerate(zip(ks, types)):
+            v = f"a{k}"
+            ct = t
+            if kd == "I":
+                decl.append(f"{ct} {v} = ({ct})rd32(R);")
+            elif kd == "f":
+                decl.append(f"{ct} {v} = rdf(R);")
+            elif kd == "J":
+                decl.append(f"{ct} {v} = ({ct})rd64(R);")
+            elif kd == "Z":
+                decl.append(f"{ct} {v} = ({ct})(int32_t)rd32(R);")
+            elif kd == "H":
+                decl.append(f"{ct} {v} = ({ct})h2ptr(rd32(R));")
+            elif kd == "Y":
+                decl.append(f"{ct} {v} = ({ct})h2sync(rd32(R));")
+            elif kd == "P":
+                decl.append(f"{ct} {v} = ({ct})g2p(rd32(R));")
+            args.append(v)
+        call = f"((__typeof__(&{n}))fn)({', '.join(args)})"
+        body = ["        " + d for d in decl]
+        if rk == "v":
+            body.append(f"        {call};")
+        elif rk == "I":
+            body.append(f"        ret32(c, (uint32_t){call});")
+        elif rk == "f":
+            body.append(f"        retf(c, {call});")
+        elif rk == "J":
+            body.append(f"        ret64(c, (uint64_t){call});")
+        elif rk == "Z":
+            body.append(f"        ret32(c, (uint32_t)(intptr_t){call});")
+        elif rk == "H":
+            body.append(f"        ret32(c, ptr2h((void *){call}));")
+        elif rk == "Y":
+            body.append(f"        ret32(c, sync2h((void *){call}));")
+        elif rk == "P":
+            body.append(f"        ret32(c, gl_guest_string((const char *){call}));")
+        out += [f"    case {i}: {{ /* {n} */"] + body + ["        return 1;", "    }"]
+    out += ["    }", "    return 0;", "}", ""]
+    (hdir / "gl.c").write_text("\n".join(out))
+
+    st = ["/* generated by bridge/gen_gl.py: do not edit */", "    .syntax unified", "    .arm", "    .text",
+          "    .p2align 2"]
+    for i, n in enumerate(names):
+        hc = 0x0A320000 | (HC_GL + i)
+        st += [f"    .global {n}", f"    .type {n}, %function", f"{n}:", "    push {r7, lr}",
+               f"    movw r7, #{hc & 0xffff:#x}", f"    movt r7, #{hc >> 16:#x}", "    svc 0", "    pop {r7, pc}"]
+    st += ["    .section .note.GNU-stack, \"\", %progbits", ""]
+    (gdir / "gl_stubs.S").write_text("\n".join(st))
+    (gdir / "gl_skipped.txt").write_text("\n".join(skipped) + "\n")
+    return names + sorted(GUEST_IMPL), len(skipped)

native/a32translator/bridge/gen_stubs.py

@@ -0,0 +1,342 @@
+#!/usr/bin/env python3
+"""Generates the bridge's tables from the NDK:
+
+  guest/gen/exports.S  the runtime's "system library" exports: every libc/libm/libstdc++/libz symbol of the NDK's
+                       arm API stubs that bionic's static archives define, plus the runtime's own dl*/liblog
+                       implementations and the host import stubs; (name, address) pairs sorted by name
+  guest/gen/stubs.S    JNIEnv / JavaVM function tables and host import stubs (each one a hypercall)
+  host/gen/jni_gen.c   host side of every JNI function, marshalled from jni.h's signatures (special cases are
+                       written by hand in host/jni.c)
+  host/gen/imports.c   host side of the imports listed in imports.txt
+
+    python bridge/gen_stubs.py [--ndk PATH]
+"""
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+NDK_DEFAULT = HERE.parents[1] / ".cache" / "ndk-27.2.12479018"
+API = 30
+HC_JNI, HC_VM, HC_IMPORT = 0x100, 0x200, 0x300
+
+# exported names implemented by the runtime itself (name -> symbol)
+OVERRIDES = {
+    "dlopen": "grt_dlopen", "dlsym": "grt_dlsym", "dlclose": "grt_dlclose", "dlerror": "grt_dlerror",
+    "dladdr": "grt_dladdr", "dl_iterate_phdr": "dl_iterate_phdr",
+    "dl_unwind_find_exidx": "__wrap_dl_unwind_find_exidx", "android_dlopen_ext": "grt_android_dlopen_ext",
+    "dlvsym": "grt_dlvsym", "eglGetProcAddress": "grt_eglGetProcAddress",
+}
+COMPAT = ["_tolower_tab_", "_toupper_tab_", "__isthreaded", "bsd_signal", "pthread_atfork",  # pthread_atfork: crtbegin_static.o
+          "fdprintf", "vfdprintf",
+          "putw", "get_malloc_leak_info", "free_malloc_leak_info", "__page_size", "getdtablesize", "tkill",
+          "SHA1Init", "SHA1Update", "SHA1Final", "__google_potentially_blocking_region_begin",
+          "__google_potentially_blocking_region_end",  # guest/compat.c
+          "slCreateEngine", "slQueryNumSupportedEngineInterfaces", "slQuerySupportedEngineInterfaces", "SL_IID_NULL",
+          "SL_IID_OBJECT", "SL_IID_ENGINE", "SL_IID_PLAY", "SL_IID_BUFFERQUEUE", "SL_IID_ANDROIDSIMPLEBUFFERQUEUE",
+          "SL_IID_VOLUME", "SL_IID_ANDROIDCONFIGURATION", "SL_IID_RECORD", "SL_IID_OUTPUTMIX"]  # guest/opensles.c
+LIBLOG = ["__android_log_write", "__android_log_print", "__android_log_vprint", "__android_log_buf_write",
+          "__android_log_buf_print", "__android_log_assert", "__android_log_is_loggable"]
+# libc symbols that must not be exported (static-only internals)
+SKIP = {"__libc_init", "__libc_preinit", "_start"}
+
+OBJ = {"jobject", "jclass", "jstring", "jthrowable", "jarray", "jobjectArray", "jbooleanArray", "jbyteArray",
+       "jcharArray", "jshortArray", "jintArray", "jlongArray", "jfloatArray", "jdoubleArray", "jweak"}
+INT = {"jint", "jsize", "jboolean", "jbyte", "jchar", "jshort", "jobjectRefType"}
+# JNI functions written by hand in host/jni.c (pointer results, varargs, freeing handles, natives)
+SPECIAL = re.compile(r"^(Call\w*Method[VA]?|NewObject[VA]?|Get\w*ArrayElements|Release\w*ArrayElements|"
+                     r"GetStringUTFChars|ReleaseStringUTFChars|GetStringChars|ReleaseStringChars|"
+                     r"GetStringCritical|ReleaseStringCritical|GetPrimitiveArrayCritical|"
+                     r"ReleasePrimitiveArrayCritical|RegisterNatives|GetJavaVM|GetDirectBufferAddress|"
+                     r"Delete\w*Ref|NewGlobalRef|NewWeakGlobalRef|PopLocalFrame|GetMethodID|GetStaticMethodID|"
+                     r"FromReflectedMethod)$")
+
+
+def tool(ndk, name):
+    return Path(ndk) / "toolchains/llvm/prebuilt/linux-x86_64/bin" / name
+
+
+def defined(ndk, path, dynamic):
+    args = [str(tool(ndk, "llvm-nm")), "--defined-only", "-g", "-j"] + (["-D"] if dynamic else []) + [str(path)]
+    out = subprocess.run(args, capture_output=True, text=True).stdout
+    return {l.strip().split("@")[0] for l in out.splitlines() if l.strip() and not l.endswith(":")}
+
+
+def code(t):
+    t = t.replace("const", "").strip()
+    if t.endswith("*") or "*" in t:
+        return "E" if t.replace(" ", "") in ("JNIEnv*", "JavaVM*") else "P"
+    if t in OBJ:
+        return "O"
+    if t == "jmethodID":
+        return "M"
+    if t == "jfieldID":
+        return "F"
+    if t in INT:
+        return "I"
+    if t == "jlong":
+        return "J"
+    if t == "jfloat":
+        return "f"
+    if t == "jdouble":
+        return "D"
+    if t == "va_list":
+        return "V"
+    if t == "...":
+        return "."
+    if t == "void":
+        return "v"
+    raise ValueError(t)
+
+
+def parse_jni(ndk):
+    h = (Path(ndk) / "toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/include/jni.h").read_text()
+    body = h[h.index("struct JNINativeInterface {"):]
+    body = body[:body.index("};")]
+    body = re.sub(r"/\*.*?\*/", "", body, flags=re.S)
+    funcs = []
+    for m in re.finditer(r"(void\*\s+reserved\d;)|([\w ]+?\**)\s*\(\*(\w+)\)\s*\(([^)]*)\);", body):
+        if m.group(1):
+            funcs.append(None)
+            continue
+        ret, name, params = m.group(2).strip(), m.group(3), m.group(4)
+        ptypes = []
+        for p in params.split(","):
+            p = p.strip()
+            if p == "...":
+                ptypes.append("...")
+                continue
+            p = re.sub(r"\b\w+$", "", p).strip() if not p.endswith("*") and len(p.split()) > 1 else p
+            ptypes.append(p)
+        funcs.append((name, ret, ptypes))
+    if len(funcs) != 233:
+        sys.exit(f"jni.h: {len(funcs)} JNINativeInterface entries, expected 233")
+    return funcs
+
+
+CTYPE = {"O": "jobject", "M": "jmethodID", "F": "jfieldID", "I": "jint", "J": "jlong", "f": "jfloat",
+         "D": "jdouble", "P": "void *"}
+
+
+def gen_jni_host(funcs, out):
+    lines = ["/* generated by bridge/gen_stubs.py from the NDK's jni.h: do not edit */", "",
+             '#include "../jni_internal.h"', "",
+             "int jni_dispatch_generated(a32_cpu *c, JNIEnv *env, int index, argreader *R)", "{",
+             "    switch (index) {"]
+    names = []
+    for i, f in enumerate(funcs):
+        if f is None:
+            names.append("reserved")
+            continue
+        name, ret, ptypes = f
+        names.append(name)
+        if SPECIAL.match(name):
+            continue
+        codes = [code(p) for p in ptypes]
+        rc = code(ret)
+        assert codes[0] == "E", name
+        if any(c in ".V" for c in codes) or rc == "P":
+            sys.exit(f"{name}: needs a hand-written implementation (varargs or pointer result)")
+        decl, args = [], ["env"]
+        for k, (cd, t) in enumerate(zip(codes[1:], ptypes[1:]), 1):
+            v = f"a{k}"
+            if cd == "O":
+                decl.append(f"{t.replace('const', '').strip()} {v} = ({t.replace('const', '').strip()})h2o(rd32(R));")
+            elif cd == "M":
+                decl.append(f"jmethodID {v} = h2mid(rd32(R));")
+            elif cd == "F":
+                decl.append(f"jfieldID {v} = h2fid(rd32(R));")
+            elif cd == "I":
+                decl.append(f"{t} {v} = ({t})rd32(R);")
+            elif cd == "J":
+                decl.append(f"jlong {v} = (jlong)rd64(R);")
+            elif cd == "f":
+                decl.append(f"jfloat {v} = rdf(R);")
+            elif cd == "D":
+                decl.append(f"jdouble {v} = rdd(R);")
+            elif cd == "P":
+                decl.append(f"{t} {v} = ({t})g2p(rd32(R));")
+            args.append(v)
+        call = f"(*env)->{name}({', '.join(args)})"
+        lines.append(f"    case {i}: {{ /* {name} */")
+        lines += ["        " + d for d in decl]
+        if rc == "v":
+            lines.append(f"        {call};")
+        elif rc == "O":
+            lines.append(f"        ret32(c, o2h_local({call}));")
+        elif rc == "M":
+            lines.append(f"        ret32(c, mid2h({call}));")
+        elif rc == "F":
+            lines.append(f"        ret32(c, fid2h({call}));")
+        elif rc == "I":
+            lines.append(f"        ret32(c, (uint32_t){call});")
+        elif rc == "J":
+            lines.append(f"        ret64(c, (uint64_t){call});")
+        elif rc == "f":
+            lines.append(f"        retf(c, {call});")
+        elif rc == "D":
+            lines.append(f"        retd(c, {call});")
+        lines += ["        return 1;", "    }"]
+    lines += ["    }", "    return 0;", "}", "",
+              "const char *const jni_names[JNI_TABLE_SIZE] = {"]
+    lines += [f'    "{n}",' for n in names]
+    lines += ["};", ""]
+    out.write_text("\n".join(lines))
+
+
+def parse_imports():
+    out = []
+    for line in (HERE / "imports.txt").read_text().splitlines():
+        line = line.split("#")[0].strip()
+        if not line:
+            continue
+        m = re.match(r"(!\s*)?(\w)\s+(\w+)\s*\((\w*)\)$", line)
+        if not m:
+            sys.exit(f"imports.txt: bad line {line!r}")
+        out.append((m.group(3), m.group(2), m.group(4), bool(m.group(1))))
+    return out
+
+
+def gen_imports_host(imports, out):
+    lines = ["/* generated by bridge/gen_stubs.py from imports.txt: do not edit */", "",
+             "#pragma clang diagnostic ignored \"-Wdeprecated-declarations\"",
+             "#include <android/asset_manager_jni.h>", "#include <android/configuration.h>", "#include <android/input.h>", "#include <android/looper.h>",
+             "#include <android/native_window_jni.h>", "#include <android/sensor.h>",
+             '#include "../imports_internal.h"', ""]
+    for name, ret, args, manual in imports:
+        if manual:
+            lines.append(f"void imp_{name}(a32_cpu *c, argreader *R);")
+        else:
+            lines.append(f"extern __typeof__({name}) {name} __attribute__((weak));")
+    lines += ["", "int import_dispatch(a32_cpu *c, int index, argreader *R)", "{", "    switch (index) {"]
+    for i, (name, ret, args, manual) in enumerate(imports):
+        if manual:
+            lines.append(f"    case {i}: imp_{name}(c, R); return 1;")
+            continue
+        decl, vals = [], []
+        for k, a in enumerate(args):
+            v = f"a{k}"
+            if a == "I":
+                decl.append(f"int32_t {v} = (int32_t)rd32(R);")
+            elif a == "J":
+                decl.append(f"int64_t {v} = (int64_t)rd64(R);")
+            elif a == "f":
+                decl.append(f"float {v} = rdf(R);")
+            elif a == "P":
+                decl.append(f"void *{v} = g2p(rd32(R));")
+            elif a == "H":
+                decl.append(f"void *{v} = h2ptr(rd32(R));")
+            elif a == "A":
+                decl.append(f"ANativeActivity *{v} = guest_activity(rd32(R));")
+            elif a == "E":
+                decl.append(f"JNIEnv *{v} = (rd32(R), host_env());")
+            elif a == "O":
+                decl.append(f"jobject {v} = h2o(rd32(R));")
+            else:
+                sys.exit(f"imports.txt: {name}: unknown argument type {a}")
+            vals.append(v)
+        call = f"{name}({', '.join(vals)})"
+        lines.append(f"    case {i}: {{ /* {name} */")
+        lines.append(f"        if (!{name}) return 0;")
+        lines += ["        " + d for d in decl]
+        if ret == "v":
+            lines.append(f"        {call};")
+        elif ret == "I":
+            lines.append(f"        ret32(c, (uint32_t){call});")
+        elif ret == "J":
+            lines.append(f"        ret64(c, (uint64_t){call});")
+        elif ret == "f":
+            lines.append(f"        retf(c, {call});")
+        elif ret == "H":
+            lines.append(f"        ret32(c, ptr2h((void *){call}));")
+        elif ret == "S":
+            lines.append(f"        ret32(c, guest_cstr({call}));")
+        else:
+            sys.exit(f"imports.txt: {name}: unknown result type {ret}")
+        lines += ["        return 1;", "    }"]
+    lines += ["    }", "    return 0;", "}", "", "const char *const import_names[] = {"]
+    lines += [f'    "{n}",' for n, _, _, _ in imports]
+    lines += ["    0,", "};", ""]
+    out.write_text("\n".join(lines))
+
+
+def stub(label, n):
+    hc = 0x0a320000 | n
+    return [f"{label}:", "    push {r7, lr}",
+            f"    movw r7, #{hc & 0xffff:#x}", f"    movt r7, #{hc >> 16:#x}",
+            "    svc 0", "    pop {r7, pc}"]
+
+
+def gen_guest(ndk, imports, gdir, extra):
+    sysroot = Path(ndk) / "toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/arm-linux-androideabi"
+    want = set()
+    for so in ("libc.so", "libm.so", "libstdc++.so", "libz.so"):
+        want |= defined(ndk, sysroot / str(API) / so, True)
+    have = set()
+    for a in ("libc.a", "libm.a", "libstdc++.a", "libz.a"):
+        have |= defined(ndk, sysroot / a, False)
+    have |= defined(ndk, Path(ndk) / "toolchains/llvm/prebuilt/linux-x86_64/lib/clang/18/lib/linux/arm/libunwind.a",
+                    False)
+    names = {n: n for n in want & have if n not in SKIP}
+    for n in OVERRIDES:
+        names[n] = OVERRIDES[n]
+    for n in LIBLOG + COMPAT:
+        names[n] = n
+    for n, *_ in imports:
+        names[n] = n
+    for n in extra:
+        names.setdefault(n, OVERRIDES.get(n, n))
+    missing = sorted(want - have - set(OVERRIDES) - SKIP - set(COMPAT))
+    (gdir / "missing.txt").write_text("\n".join(missing) + "\n")
+
+    ex = ["/* generated by bridge/gen_stubs.py: do not edit */", "    .section .rodata.grt_names, \"aMS\", %progbits, 1"]
+    order = sorted(names, key=lambda s: s.encode())
+    for k, n in enumerate(order):
+        ex.append(f".Ln{k}: .asciz \"{n}\"")
+    ex += ["    .section .data.rel.ro.grt_exports, \"aw\"", "    .p2align 2", "    .global grt_export_table",
+           "grt_export_table:"]
+    for k, n in enumerate(order):
+        ex.append(f"    .word .Ln{k}, {names[n]}")
+    ex += ["    .global grt_export_count", "grt_export_count:", f"    .word {len(order)}", ""]
+    (gdir / "exports.S").write_text("\n".join(ex))
+
+    st = ["/* generated by bridge/gen_stubs.py: do not edit */", "    .syntax unified", "    .arm", "    .text",
+          "    .p2align 2"]
+    for i in range(233):
+        st += stub(f"jni_{i}", HC_JNI + i)
+    for i in range(8):
+        st += stub(f"vm_{i}", HC_VM + i)
+    for i, (n, *_) in enumerate(imports):
+        st += [f"    .global {n}", f"    .type {n}, %function"] + stub(n, HC_IMPORT + i)
+    st += ["    .section .data.rel.ro.grt_tables, \"aw\"", "    .p2align 2", "grt_jni_table:"]
+    st += [f"    .word jni_{i}" for i in range(233)]
+    st += ["grt_vm_table:"] + [f"    .word vm_{i}" for i in range(8)]
+    st += ["    .global grt_jni_env", "grt_jni_env:", "    .word grt_jni_table",
+           "    .global grt_java_vm", "grt_java_vm:", "    .word grt_vm_table", ""]
+    (gdir / "stubs.S").write_text("\n".join(st))
+    return len(order), len(missing)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--ndk", default=str(NDK_DEFAULT))
+    a = ap.parse_args()
+    imports = parse_imports()
+    gdir, hdir = HERE / "guest" / "gen", HERE / "host" / "gen"
+    gdir.mkdir(parents=True, exist_ok=True)
+    hdir.mkdir(parents=True, exist_ok=True)
+    import gen_gl
+    gl_names, gl_skipped = gen_gl.generate(a.ndk, gdir, hdir)
+    n, miss = gen_guest(a.ndk, imports, gdir, gl_names)
+    funcs = parse_jni(a.ndk)
+    gen_jni_host(funcs, hdir / "jni_gen.c")
+    gen_imports_host(imports, hdir / "imports.c")
+    print(f"{n} exports ({miss} stub symbols without a static definition, see guest/gen/missing.txt), "
+          f"{len(imports)} imports, {len(funcs)} JNI functions, {len(gl_names)} GLES/EGL functions ({gl_skipped} "
+          "not supported, see guest/gen/gl_skipped.txt)")
+
+
+if __name__ == "__main__":
+    main()

native/a32translator/bridge/guest/compat.c

@@ -0,0 +1,111 @@
+/* LP32 bionic symbols that only libc.so has (old NDK binaries still link against them). */
+#include <ctype.h>
+#include <signal.h>
+#include <stdarg.h>
+#include <stdio.h>
+
+static short lower_tab[257], upper_tab[257];
+const short *_tolower_tab_ = lower_tab;
+const short *_toupper_tab_ = upper_tab;
+int __isthreaded = 1;
+
+__attribute__((constructor)) static void init_tabs(void)
+{
+    lower_tab[0] = upper_tab[0] = -1; /* EOF */
+    for (int c = 0; c < 256; c++) {
+        lower_tab[c + 1] = (short)tolower(c);
+        upper_tab[c + 1] = (short)toupper(c);
+    }
+}
+
+sighandler_t bsd_signal(int sig, sighandler_t h) { return signal(sig, h); }
+
+int vfdprintf(int fd, const char *fmt, va_list ap) { return vdprintf(fd, fmt, ap); }
+int fdprintf(int fd, const char *fmt, ...)
+{
+    va_list ap;
+    va_start(ap, fmt);
+    int r = vdprintf(fd, fmt, ap);
+    va_end(ap);
+    return r;
+}
+
+int putw(int w, FILE *f) { return fwrite(&w, sizeof w, 1, f) == 1 ? 0 : EOF; }
+void get_malloc_leak_info(void **info, size_t *overall, size_t *isize, size_t *total, size_t *backtrace)
+{
+    *info = 0;
+    *overall = *isize = *total = *backtrace = 0;
+}
+void free_malloc_leak_info(void *info) { (void)info; }
+
+/* old LP32 libc.so also exported these (Unity 5 and Mono builds link against them) */
+#include <stdint.h>
+#include <string.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+
+unsigned int __page_size = 4096;
+int getdtablesize(void) { return (int)sysconf(_SC_OPEN_MAX); }
+int tkill(int tid, int sig) { return (int)syscall(__NR_tkill, tid, sig); }
+
+typedef struct {
+    uint32_t state[5];
+    uint32_t count[2];
+    uint8_t buffer[64];
+} SHA1_CTX;
+
+#define ROL(v, b) (((v) << (b)) | ((v) >> (32 - (b))))
+
+static void sha1_block(uint32_t st[5], const uint8_t b[64])
+{
+    uint32_t w[80], a = st[0], bb = st[1], c = st[2], d = st[3], e = st[4];
+    for (int i = 0; i < 16; i++) w[i] = (uint32_t)b[4 * i] << 24 | (uint32_t)b[4 * i + 1] << 16 | (uint32_t)b[4 * i + 2] << 8 | b[4 * i + 3];
+    for (int i = 16; i < 80; i++) w[i] = ROL(w[i - 3] ^ w[i - 8] ^ w[i - 14] ^ w[i - 16], 1);
+    for (int i = 0; i < 80; i++) {
+        uint32_t f, k;
+        if (i < 20) f = (bb & c) | (~bb & d), k = 0x5a827999;
+        else if (i < 40) f = bb ^ c ^ d, k = 0x6ed9eba1;
+        else if (i < 60) f = (bb & c) | (bb & d) | (c & d), k = 0x8f1bbcdc;
+        else f = bb ^ c ^ d, k = 0xca62c1d6;
+        uint32_t t = ROL(a, 5) + f + e + k + w[i];
+        e = d, d = c, c = ROL(bb, 30), bb = a, a = t;
+    }
+    st[0] += a, st[1] += bb, st[2] += c, st[3] += d, st[4] += e;
+}
+
+void SHA1Init(SHA1_CTX *ctx)
+{
+    static const uint32_t init[5] = {0x67452301, 0xefcdab89, 0x98badcfe, 0x10325476, 0xc3d2e1f0};
+    memcpy(ctx->state, init, sizeof init);
+    ctx->count[0] = ctx->count[1] = 0;
+}
+
+void SHA1Update(SHA1_CTX *ctx, const uint8_t *data, uint32_t len)
+{
+    uint32_t j = (ctx->count[0] >> 3) & 63;
+    if ((ctx->count[0] += len << 3) < (len << 3)) ctx->count[1]++;
+    ctx->count[1] += len >> 29;
+    uint32_t i = 0;
+    if (j + len > 63) {
+        memcpy(&ctx->buffer[j], data, (i = 64 - j));
+        sha1_block(ctx->state, ctx->buffer);
+        for (; i + 63 < len; i += 64) sha1_block(ctx->state, &data[i]);
+        j = 0;
+    }
+    memcpy(&ctx->buffer[j], &data[i], len - i);
+}
+
+void SHA1Final(uint8_t digest[20], SHA1_CTX *ctx)
+{
+    uint8_t final[8];
+    for (int i = 0; i < 8; i++) final[i] = (uint8_t)(ctx->count[i >= 4 ? 0 : 1] >> ((3 - (i & 3)) * 8));
+    uint8_t c = 0x80;
+    SHA1Update(ctx, &c, 1);
+    c = 0;
+    while ((ctx->count[0] & 504) != 448) SHA1Update(ctx, &c, 1);
+    SHA1Update(ctx, final, 8);
+    for (int i = 0; i < 20; i++) digest[i] = (uint8_t)(ctx->state[i >> 2] >> ((3 - (i & 3)) * 8));
+}
+
+void __google_potentially_blocking_region_begin(void) {}
+void __google_potentially_blocking_region_end(void) {}

native/a32translator/bridge/guest/gl.c

@@ -0,0 +1,4 @@
+/* eglGetProcAddress for guest code: the runtime's own GLES/EGL stubs (gen/gl_stubs.S), found by name. */
+#include "grt.h"
+
+void *grt_eglGetProcAddress(const char *name) { return name ? (void *)(uintptr_t)grt_export(name) : 0; }

native/a32translator/bridge/guest/grt.h

@@ -0,0 +1,27 @@
+/* Guest runtime (liba32rt.so): a static 32-bit bionic program that loads the game's libraries and connects them
+ * to the host bridge. */
+#ifndef GRT_H
+#define GRT_H
+
+#include <stdint.h>
+#include "../abi.h"
+
+#define A32_HYPERCALL 0x0a320000u
+
+uint32_t grt_hc_raw(uint32_t r7, uint32_t a0, uint32_t a1, uint32_t a2, uint32_t a3); /* hc.S */
+
+static inline uint32_t grt_hc(uint32_t n, uint32_t a0, uint32_t a1, uint32_t a2, uint32_t a3)
+{
+    return grt_hc_raw(A32_HYPERCALL | n, a0, a1, a2, a3);
+}
+
+void grt_log(int prio, const char *tag, const char *fmt, ...) __attribute__((format(printf, 3, 4)));
+uint32_t grt_export(const char *name); /* exports.S + main.c: address of a "system" symbol, 0 if none */
+
+void loader_set_dir(const char *dir);
+void *grt_dlopen(const char *name, int flags);
+void *grt_dlsym(void *handle, const char *name);
+char *grt_dlerror(void);
+uint32_t *grt_list_symbols(void *handle, const char *prefix);
+
+#endif

native/a32translator/bridge/guest/hc.S

@@ -0,0 +1,19 @@
+/* grt_hc_raw(r7 value, a0, a1, a2, a3): a hypercall (SVC 0 with r7 = A32_HYPERCALL | n), result in r0. Out of line
+ * because r7 is the Thumb frame pointer. */
+    .syntax unified
+    .arm
+    .text
+    .p2align 2
+    .global grt_hc_raw
+    .type grt_hc_raw, %function
+grt_hc_raw:
+    push {r7, lr}
+    mov r7, r0
+    mov r0, r1
+    mov r1, r2
+    mov r2, r3
+    ldr r3, [sp, #8]
+    svc 0
+    pop {r7, pc}
+    .size grt_hc_raw, . - grt_hc_raw
+    .section .note.GNU-stack, "", %progbits