tests: Unreal Vulkan detection test assumes direct mode can be had

tests: ruff line length
PC: Vulkan Quest games use AXRB's emulator until direct mode is installed, built or released (testers had no way to get it)
2026-10-17 16:02:22 +02:00 · 2026-10-16 15:30:07 -04:00 · 2026-10-16 15:25:08 -04:00 · 2026-10-16 15:24:22 -04:00 · 2026-10-16 15:05:34 -04:00 · 2026-10-16 15:02:43 -04:00
266 changed files with 36455 additions and 800 deletions
@@ -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
@@ -146,6 +146,23 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    `launcher` field, else text swap), list_installed `drive`/`drive_missing` (install_state keeps such games
    "installed"). PC: `install/drives.py`, library setting `install.drive` (Frame page → Storage), game menu
    "Move to…" (job kind tool-frame), CLI `frame drives`/`frame move`/`install --dest`. Untested on the device.
+  - **Quest games on this PC via AXRB** (experimental, branch `worktree-pc-android-axrb`, docs/PC_ANDROID.md): the
+    "This PC" target (`PcReviveTarget`) installs APKs through `targets/pc_android.py` + `tools/axrb.py`. AXRB
+    (Android-XR-Bridge/AXRB, Windows: x86_64 Android 16 emulator + libndk_translation + its own OpenXR runtime →
+    `axrb-host-bridge.exe` → SteamVR) is downloaded only on first use (`AXRB-Setup-<v>.exe /S`, SHA256SUMS, per user
+    → `%LOCALAPPDATA%\Programs\axrb-launcher`), never bundled/modified (host code: AXRB Source-Available License).
+    Its runtime setup lives only in AXRB's Electron JS, so FramePort repeats it (pins read from the installed
+    `app.asar` `core/components.json`, AVD `axrb-managed-api36` port 5584, adb `-P 5038`, receipts `ready.json`/
+    `license-acceptance.json`, so AXRB's own launcher shares it). Spike 2026-10-10 (headless): **unconverted APKs
+    abort** (Meta platform loader) → PC build = OVRPort patches + `Patch.on_pc` APK fixes (`base.pc_selection`,
+    `build(pc=True)`, library `build_pc`, `pc_recipe_fingerprint`); Lucky's Tale ran a full OpenXR session in AXRB's
+    runtime; Pinball FX VR crashed in gfxstream vkAllocateMemory (AXRB's layer). SteamVR can't stand in for a headset
+    (null driver: no D3D11 adapter; vrlink without a Frame: no instance) → frames need the owner. Play = Steam
+    shortcut `powershell.exe -File %LOCALAPPDATA%\FramePort\axrb\fp-axrb-run.ps1 -Package …` → AXRB's
+    `run_windows_game.ps1`; all such shortcuts share Exe, so agent v71 `upsert/remove_shortcut(options_key=
+    "-Package <pkg> ")`. AXRB scripts start through WMI (`axrb.spawn_detached`): QEMU/adb inherit any handle, and
+    even /dev/null through WSL interop kept the call hanging; PowerShell 5.1 `*>>` logs are UTF-16 (`read_log`). Triage
+    `kind: axrb`. Full uninstall in AXRB deletes OBB + saves; a signature change needs one.
  - **PC VR repacks are pre-patched to run directly** (proven: Rick and Morty, Vader Immortal run when the exe is
    launched directly; Revive breaks them). So Rift games default to `as_is` = install the copy unchanged and launch
    the exe directly (`pcvr.xr_timefix` for the Frame OpenXR-1.1→1.0 fix, `pcvr.no_crash_reporter` for Unreal).
@@ -312,6 +329,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).

@@ -393,7 +470,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).
@@ -643,7 +720,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
@@ -741,7 +820,23 @@ 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".
-**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).
+**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): the keeper now catches a silent mirror too (agent v91).
+**Lepton's logcat mirror dies (agent v67, 2026-10-09; v91 2026-10-14):** Lepton's mirror (`podman exec -it <container> logcat -v threadtime,color`) fails three ways: `logcat: Unexpected EOF!` right after the game starts, `Logcat read failure`, or running and writing nothing at all (Lepton 3.0.5: seen twice on 2026-10-14, once in the owner's session, once headless). launch.sh's `_logcat_keeper` reads `podman exec <container> logcat -v threadtime -T <epoch>` itself into launch.log after a failure line or 20 s without a logcat line (from the launcher's start when the mirror never wrote, else from just before its last line), restarts it from where it ended (≤5), stops it when Lepton's coloured lines come back, sets the container's log buffer to 16 MiB (`logcat -G`), and logs every decision to `<base>/logcat-keeper.log`. Checked on the dev Frame: a mirror killed mid-game (hand-over without a gap) and a silent mirror (the whole session recovered).
 **Double launch (agent v57, 2026-10-06):** a second Play while Lepton still boots (~10 s with nothing to see) made
 the second Lepton stop the first one's container ("Waiting for steamlaunch-<appid> (PID …) to exit", exit 137
 "(starting)", "Clearing baked app data due to early exit") and both died (Vader, BattleSisters). launch.sh now takes
@@ -972,6 +1067,49 @@ Installed apps find the release themselves (self-update), so the notes are what
 - **The repo is public: never commit personal data** — the Frame's IP address, the Steam user id, the owner's email,
  local home paths (native builds use `-ffile-prefix-map`). History was rewritten once to remove them.

+## GitHub triage (issues / discussions / PRs)
+GitHub identity + credentials are maintainer-local (`CLAUDE.local.md`): check `gh api user --jq .login` before any
+GitHub write. **The owner approves before posting, labelling or closing anything.** Reply style: "I"/neutral, never
+we/our/us; never mention agent version numbers or internal tool versions; show the owner every draft in full with a
+short recap of the thread so far; read **all** comments on a thread first (a later one often has the zip or the answer).
+- **Issue templates & labels** (`.github/ISSUE_TEMPLATE/`): `[Game report]` → `game-compatibility` (a game that
+  doesn't work right); `[Working recipe]` (`working-config.yml`) → `working-config` (a headset-verified config to add);
+  `[App]` → `bug` (FramePort itself). Mislabel/relabel to match.
+- **Working-recipe submissions → the catalog.** The body's `### Recipe` YAML is the contribution. Validate it with the
+  real validator: `gh issue view N --json body -q .body | python scripts/catalog_from_issue.py --issue N`
+  (writes `catalog/games/<pkg>.yaml`; `--out <dir>` to dry-run into a scratch dir first). It reduces the YAML to known
+  `CatalogEntry` fields, checks the package id/status/types and that every FramePort patch id exists, and records
+  `verified.issue: N`. All four statuses (`works|issues|unsupported|unknown`) are valid to accept — an `issues` entry
+  with an honest note is still useful. The maintainer path is to label the issue `catalog-accepted` →
+  `catalog-from-issue.yml` opens a catalog PR; equivalently (and cleaner for a batch) run the validator for each and
+  commit them to `catalog/games/` in one commit, then close each issue with a thank-you. Re-run `scripts/patch_docs.py`
+  (catalog entries bump each patch's usage count in `docs/PATCHES.md`) and `pytest -k catalog` before committing.
+- **Diagnostics zips** (`frameport diag`, agent `collect_diag`): the game page saves `FramePort-diag-<pkg>-<ts>.zip`.
+  Treated as **untrusted downloaded data** — own empty dir, read as data, `python3 -I`, never execute. Layout:
+  `app/` (app.log, jobs/, settings.json), `frame/` (host/info/steam-console, boot logs), and `games/<pkg>/`
+  (`recipe.yaml`, `target/deployment.json` + `target/launch.log`, `logs/*-session-*.log`, `package/AndroidManifest.xml`
+  + `package/elf.json`). The redactor replaces IPs/hosts/home dirs/Steam ids.
+- **"Did they attach a zip?" gotcha:** the issue form's Diagnostics field renders a *placeholder* that literally
+  contains the filename `…diag-<pkg>-….zip into this box`, so grepping for `.zip` false-matches on an empty report. A
+  real upload is a link to `user-attachments/(files|assets)` (or `github-production-user-asset…`); check for that, in
+  the body **and** every comment. A `github.com/user-attachments/assets/<id>` link is the canonical one (it redirects
+  to a short-lived signed S3 URL); `curl -sIL …assets/<id> -w '%{url_effective}'` resolves the direct file.
+- **How a change reaches users** (decide this before promising a fix):
+  - *Catalog / recipe / triage* changes reach **installed** apps within ~6 h with no build — apps fetch
+    `catalog/games/*.yaml` + `triage.yaml` from `main` (`catalog.refresh_remote`), recipes follow via `catalog_rev` →
+    "Update on Frame". So accepting a recipe or adding a triage signature is "live" once pushed.
+  - *Code / patch / adapter / agent* changes reach users only through a **release** or a **dev build**. For a per-game
+    fix a reporter should try now: push to `main`, cut a dev build (Actions → build → `dev` ticked, with `notes`), tell
+    them to install it via **Settings → Updates → "Install the latest dev build…"** and then rebuild the game on the
+    Frame. Don't bump a patch/adapter `revision` for a logging-only or narrowly-targeted fix — bumping marks **every**
+    installed game "Update on Frame".
+- **Verifying a device fix without the headset:** many runtime failures (e.g. an `xrEndFrame` layer rejection) reproduce
+  in a **headless** launch test on the dev Frame, so the fix can be developed and confirmed at the frame-acceptance
+  level there; only the *visual* result needs the headset (hand the built dev build to the reporter, or the owner, for
+  that). `frameport settings <pkg> <key>=<value>` toggles adapter settings (e.g. `layer_debug=1`) live, no rebuild.
+  To reproduce a reporter's exact build, grab their APK from its upstream source (e.g. the linked GitHub release), scan
+  → build → install → test in an isolated `FRAMEPORT_HOME` (see "Dev commands" / the Frame-busy rules).
+
 ## Heuristics (games not in the catalog)
 Each patch's `detect()` suggests itself from the Analysis; `applies()` says whether it can matter at all (the UI/CLI
 hide non-applicable patches; enabled ones are always shown). Rules learned from the 34 games:
@@ -111,7 +111,8 @@ Out of date? [Report a problem](https://github.com/spoopyghosty0/frameport/issue
 Most of the work is done by these projects:
 [OVRPort](https://github.com/Android-XR-Bridge/OVRPort) (Quest → OpenXR, originally
 [ovrport/app](https://github.com/ovrport/app)) · Valve Lepton, Proton and SteamVR ·
-[Revive](https://github.com/LibreVR/Revive) · Mesa (Zink) · [Khronos OpenXR SDK](https://github.com/KhronosGroup/OpenXR-SDK)
+[Revive](https://github.com/LibreVR/Revive) · [AXRB](https://github.com/Android-XR-Bridge/AXRB) (Quest games on a PC,
+experimental) · Mesa (Zink) · [Khronos OpenXR SDK](https://github.com/KhronosGroup/OpenXR-SDK)
 · Eclipse Temurin, Android apksigner and NDK · [Flet](https://flet.dev) · OculusDB and Steam store data.
 What FramePort adds: [Architecture](docs/ARCHITECTURE.md).

@@ -25,6 +25,8 @@ FramePort's own native code (the FrameBridge adapter, GL/Vulkan/OpenXR shims, th
 | Eclipse Temurin JRE | api.adoptium.net | GPL-2.0 with Classpath Exception |
 | apksigner (Android build-tools) | dl.google.com Android repository | Apache-2.0 |
 | Revive (portable copy, only if Revive isn't installed) | github.com/LibreVR/Revive releases | GPL-3.0 |
+| AXRB / Android XR Bridge (official installer, only when a Quest game is installed on this PC; run unmodified) | github.com/Android-XR-Bridge/AXRB releases | mixed: launcher GPL-3.0-or-later, host/clock code AXRB Source-Available License 1.0, other parts MIT (AXRB's `LICENSE`) |
+| Android Emulator, platform-tools, build-tools, Android 16 system image (pinned by AXRB) | dl.google.com Android repository | Android SDK License |

 Valve's Lepton, Proton and SteamVR, and Meta's software, are used on your devices as installed by Steam / Meta;
 FramePort doesn't distribute them.
@@ -44,7 +44,7 @@ try:
 except ImportError:  # Windows: pc_revive loads this file for its VDF code only (GitHub #131)
    fcntl = None

-AGENT_VERSION = 86
+AGENT_VERSION = 92  # v92: upsert/remove_shortcut options_key (the PC's Quest games share powershell.exe as Exe)
 HOME = os.path.expanduser("~")
 STEAM = os.path.join(HOME, ".local/share/Steam")
 ANCHORS = os.path.join(HOME, "Applications/quest-frame")
@@ -957,7 +957,10 @@ def vdf_decode(data):
            else:
                raise AgentError(f"unsupported VDF value type {kind}; not modifying shortcuts.vdf")
            if key in out:
-                raise AgentError("duplicate VDF key; not modifying shortcuts.vdf")
+                old_key = out._key(key)
+                # Older agents wrote lowercase twins of Steam's capitalized keys. Keep their position.
+                if key[:1].isupper() and not old_key[:1].isupper():
+                    out = VdfMap((key if k == old_key else k, v) for k, v in out.items())
            out[key] = value

    root = node()
@@ -979,8 +982,14 @@ def vdf_encode(obj):
    return bytes(out) + bytes([TYPE_END])


+def _shortcut_matches(v, exe, options_key=None):
+    """A shortcut is the game's when its Exe matches; with options_key (games sharing one Exe, e.g. Quest games on a
+    PC all start powershell.exe) its LaunchOptions must also contain that key."""
+    return isinstance(v, dict) and v.get("Exe") == exe and (not options_key or options_key in v.get("LaunchOptions", ""))
+
+
 def upsert_shortcut(vdf_path, exe, title, start_dir, icon="", tag="Quest on Frame", launch_options="", tags=None,
-                    openvr=True, write=True):
+                    openvr=True, write=True, options_key=None):
    """Add/update a non-Steam shortcut (matched by Exe, so its appid never changes). `tags` (genres, the user's tags)
    are merged with tags already on the shortcut, so ones set in Steam are kept. write=False: change nothing, return
    (appid, whether shortcuts.vdf would change)."""
@@ -994,7 +1003,7 @@ def upsert_shortcut(vdf_path, exe, title, start_dir, icon="", tag="Quest on Fram
    def game_of(options):  # the game's program in the injector's arguments (its flags may change)
        found = re.findall(r'"([^"]+\.exe)"|(\S+\.exe)', options or "", re.IGNORECASE)
        return (found[-1][0] or found[-1][1]).lower() if found else (options or "")
-    entry = next((v for v in shortcuts.values() if isinstance(v, dict) and v.get("Exe") == exe
+    entry = next((v for v in shortcuts.values() if _shortcut_matches(v, exe, options_key)
                  and (not shared or game_of(v.get("LaunchOptions", "")) == game_of(launch_options))), None)
    ident = entry["appid"] if entry else shortcut_appid(exe, title)
    if entry is None:
@@ -1089,12 +1098,12 @@ def grid_files(grid, appid):
        return []


-def remove_shortcut(vdf_path, exe):
+def remove_shortcut(vdf_path, exe, options_key=None):
    if not os.path.exists(vdf_path):
        return False
    root = vdf_decode(open(vdf_path, "rb").read())
    sc = root.get("shortcuts", {})
-    keep = [v for v in sc.values() if not (isinstance(v, dict) and v.get("Exe") == exe)]
+    keep = [v for v in sc.values() if not _shortcut_matches(v, exe, options_key)]
    if len(keep) == len(sc):
        return False
    root["shortcuts"] = {str(i): v for i, v in enumerate(keep)}
@@ -1256,7 +1265,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:
@@ -1264,7 +1273,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))
@@ -1274,6 +1283,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")
@@ -1526,10 +1548,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):
@@ -1566,7 +1595,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}


@@ -3023,7 +3052,7 @@ setsid {lepton_q} start >"$app_dir/launch.log" 2>&1 &
 child=$!
 {dashboard}
 {logcat}
-wait "$child"
+{restart}
 """)


@@ -3050,10 +3079,11 @@ SINGLE_LINE = ('exec 9>"$app_dir/.launch.lock"; flock -n 9 || '
               'exit 0; }')


-# Lepton mirrors the game's logcat into launch.log, and that reader sometimes dies right after the game starts
-# ("logcat: Unexpected EOF!", seen with Vader Immortal on Lepton 3.0.5 and Under Cover on 2.8.14). The game runs on,
-# but launch.log stays empty: no dashboard auto-hide, no launch-test result. _logcat_keeper then reads the
-# container's logcat itself and appends it to launch.log.
+# Lepton mirrors the game's logcat into launch.log, and that reader sometimes fails: it dies right after the game
+# starts ("logcat: Unexpected EOF!", Vader Immortal on Lepton 3.0.5, Under Cover on 2.8.14), can't read ("Logcat read
+# failure"), or runs and writes nothing (Lepton 3.0.5, 2026-10-14). The game runs on, but launch.log stays empty: no
+# dashboard auto-hide, no launch-test result, no session triage. _logcat_keeper then reads the container's logcat
+# itself and appends it to launch.log.
 LOGCAT_LINE = ('python3 {agent_q} _logcat_keeper "$app_dir/launch.log" "$SteamAppId" $$ '
               '>"$app_dir/logcat-keeper.log" 2>&1 9>&- &')

@@ -3068,6 +3098,71 @@ 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__)))

@@ -3119,6 +3214,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
@@ -3511,7 +3615,7 @@ def write_launcher(anchor, base, pkg, title, appid, lepton, env, hw_video=False,
                            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:
@@ -3828,7 +3932,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)")
@@ -3849,6 +3953,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?)")
@@ -3859,16 +3967,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
@@ -3885,13 +4044,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)
@@ -3901,22 +4084,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)
@@ -5175,8 +5376,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:
@@ -5186,7 +5387,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
@@ -5200,6 +5413,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
@@ -6629,15 +6862,42 @@ def user_opened_dashboard(log, pos):


 LOGCAT_EOF = "logcat: Unexpected EOF"
+# Lepton's mirror fails in more ways than one: it ends ("Unexpected EOF"), can't read ("Logcat read failure"), or
+# prints nothing at all after "Waiting for app" (seen on a first start after an APK change, 2026-10-14)
+LOGCAT_FAILURES = (LOGCAT_EOF, "logcat: Logcat read failure")
+LOGCAT_ROW = re.compile(r"\d\d-\d\d \d\d:\d\d:\d\d\.\d{3} +\d+ +\d+ [VDIWEF] ")  # a logcat -v threadtime line
+LEPTON_ROW = re.compile(r"\x1b\[[0-9;]*m\d\d-\d\d \d\d:\d\d:\d\d\.\d{3} ")  # Lepton's mirror colours its lines
+LOGCAT_SILENCE = 20.0  # seconds without a logcat line after "Waiting for app" = the mirror isn't working (a running
+# game's container logs all the time: FrameBridge alone every 5 s)
+LOGCAT_BUFFER = "16M"  # the container's log buffer: a chatty game overwrote its own first minutes in the default one


-def logcat_keeper(log, appid, parent, poll=2.0, restarts=5, popen=None):
-    """Keep launch.log filling when Lepton's logcat mirror dies while the game runs (LOGCAT_LINE): once the log shows
-    LOGCAT_EOF after "Waiting for app", read the container's logcat ourselves (from its last 2000 lines, so the start
-    of the game isn't lost) and append it; restart it if it ends while the game still runs (at most `restarts` times).
-    Ends with the launcher."""
+def logcat_keeper(log, appid, parent, poll=2.0, restarts=5, popen=None, run=None, clock=None,
+                  silence=LOGCAT_SILENCE):
+    """Keep launch.log filling when Lepton's logcat mirror doesn't (LOGCAT_LINE): after "Waiting for app", a failure
+    line (LOGCAT_FAILURES) or `silence` seconds without a logcat line start our own reader of the container's logcat
+    (`logcat -T <epoch>`: from the launcher's start when the mirror never wrote a line, else from just before its
+    last one; nothing is lost while the buffer holds it); restarted from where it stopped if it ends while the game
+    runs (at most `restarts` times), stopped again when Lepton's own (coloured) lines come back. Enlarges the
+    container's log buffer once it has booted. Every decision is printed (the launcher sends it to
+    logcat-keeper.log). Ends with the launcher."""
    popen = popen or subprocess.Popen
+    run = run or subprocess.run
+    clock = clock or time.time
    container = f"lepton-steamlaunch-{appid}"
+    start = clock()  # the keeper starts with the launcher
+    # (Steam's LD_PRELOAD overlay libraries only add "ld.so: ... cannot be preloaded" lines to the log)
+    env = {k: v for k, v in os.environ.items() if k != "LD_PRELOAD"}
+
+    def say(text):
+        print(f"{time.strftime('%H:%M:%S')} {text}", flush=True)
+
+    def note(text):  # also into launch.log, where triage and the dashboard worker read
+        try:
+            with open(log, "a") as f:
+                f.write(f"FramePort: {text}\n")
+        except OSError:
+            pass

    def alive():
        try:
@@ -6646,31 +6906,79 @@ def logcat_keeper(log, appid, parent, poll=2.0, restarts=5, popen=None):
        except (OSError, ValueError):
            return False

-    proc, started = None, 0
+    pos, booted, buffer_tries, waiting_since = 0, False, 0, None
+    lepton_rows, last_row, failure, proc, started = False, None, None, None, 0
    while alive():
-        if proc is None or proc.poll() is not None:
+        try:
+            with open(log, "rb") as f:
+                f.seek(pos)
+                chunk = f.read().decode("utf-8", "replace")
+                pos = f.tell()
+        except OSError:
+            chunk = ""
+        if not booted and "Boot complete!" in chunk:
+            booted = True
+        if booted and buffer_tries < 5:
+            buffer_tries += 1
            try:
-                with open(log, errors="replace") as f:
-                    text = f.read()
-            except OSError:
-                text = ""
-            i = text.find("Waiting for app")
-            if i >= 0 and LOGCAT_EOF in text[i:] and started < restarts:
+                r = run(["podman", "exec", container, "logcat", "-G", LOGCAT_BUFFER], capture_output=True,
+                        text=True, timeout=15, env=env)
+                ok = r.returncode == 0
+                say(f"log buffer {LOGCAT_BUFFER}: {'set' if ok else (r.stdout + r.stderr).strip()[:200]}")
+            except (OSError, subprocess.SubprocessError) as exc:
+                ok = False
+                say(f"log buffer {LOGCAT_BUFFER}: {exc}")
+            if ok:
+                buffer_tries = 5
+        if waiting_since is None:
+            i = chunk.find("Waiting for app")
+            if i >= 0:
+                waiting_since, chunk = clock(), chunk[i:]
+                say("Lepton is waiting for the app; watching its logcat mirror")
+        if waiting_since is not None and chunk:
+            ours = proc is not None and proc.poll() is None
+            if ours and LEPTON_ROW.search(chunk):
+                proc.terminate()
+                proc, failure, lepton_rows, last_row = None, None, True, clock()
+                say("Lepton's mirror is writing again: stopped our reader")
+                note("Lepton's logcat is back; stopped FramePort's reader")
+            elif not ours:
+                if any(m in chunk for m in LOGCAT_FAILURES):
+                    failure = next(m for m in LOGCAT_FAILURES if m in chunk)
+                elif LOGCAT_ROW.search(chunk):
+                    lepton_rows, last_row = True, clock()
+        if waiting_since is not None and (proc is None or proc.poll() is not None):
+            if proc is not None:  # our reader ended while the game runs: go on from where it stopped
+                say(f"our reader ended ({proc.poll()})")
+                proc, lepton_rows, last_row = None, True, clock()  # (go on from about now)
+                failure = failure or "FramePort's reader ended"
+            quiet = clock() - (last_row or waiting_since)
+            after = "" if lepton_rows else " after the app started"
+            reason = failure or (None if quiet < silence else f"no logcat line for {quiet:.0f} s{after}")
+            if reason and started < restarts:
                started += 1
-                with open(log, "a") as f:
-                    f.write(f"FramePort: Lepton's logcat ended; reading {container}'s logcat again ({started})\n")
+                # nothing came through yet: everything since the start; else from just before the last line seen
+                since = start if not lepton_rows else last_row - poll - 1
+                say(f"reading {container}'s logcat ourselves since {since:.3f} ({started}): {reason}")
+                note(f"Lepton's logcat isn't coming through ({reason}); reading {container}'s logcat ({started})")
                out = open(log, "ab")
                try:
-                    proc = popen(["podman", "exec", container, "logcat", "-v", "threadtime", "-T", "2000"],
-                                 stdout=out, stderr=subprocess.STDOUT, stdin=subprocess.DEVNULL)
+                    proc = popen(["podman", "exec", container, "logcat", "-v", "threadtime", "-T", f"{since:.3f}"],
+                                 stdout=out, stderr=subprocess.STDOUT, stdin=subprocess.DEVNULL, env=env)
                except OSError as exc:
-                    print(f"logcat_keeper: {exc}", flush=True)
+                    say(f"could not start logcat: {exc}")
                    proc = None
                finally:
                    out.close()
+                # what our reader writes is ours: only Lepton's coloured lines count from here on
+                try:
+                    pos = os.path.getsize(log)
+                except OSError:
+                    pass
        time.sleep(poll)
    if proc is not None and proc.poll() is None:
        proc.terminate()
+    say("launcher ended")


 def dashboard_worker(log, parent, wait_start=240, window=120, poll=0.5, ui_log=None, max_hides=10):
@@ -7636,6 +7944,8 @@ def main():
    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
@@ -1,20 +1,24 @@
 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
+e2465e8960b4dd591d303e30c9d80b8a7c7c7eeff53736419c7105a697725732  ./arm64-v8a/libfp_ovrp.so
 40defdaddcda53bd2649eb48076fae1622bfc2bfc88e9e03c94fc8b45af2a4f2  ./arm64-v8a/libfp_ovrtrace.so
 0167c2fde5dfde62897f9d85afc4fc8e97784e988b5b8df6cea8c407240b3424  ./arm64-v8a/libfp_tkeys.so
 e8c0965c188665a4e565e4a3af983ef1866d1cf9225665cc90d8df286bc96ef3  ./arm64-v8a/libfp_vk.so
+7fa29014eed2881ee0d7ac486434de9c5fe46710e640b15f697030ad052acfc4  ./arm64-v8a/libfp_vkext.so
 383054f8b3b41dde76d062c71856cd3163655e50009c08454bc1793f393ead65  ./arm64-v8a/libfpg.so
 5432674a59d02f411cd853a5dc57e3fa547d1ac518f25bf433fc54c43677177a  ./arm64-v8a/libfpglmv.so
 8a8f6b1da8952cb3933a5b53558424a5fc56043b2527a16bb6dd62a00d2de01a  ./arm64-v8a/libframe_xrshim.so
-19ba5ed3c4b780f5ae46251f6958f552acfc5f13c8bb39f995579593fa8990c6  ./arm64-v8a/libglshim.so
-e44ded778758de33ad87bb31398281d7ec94c1ecd43dcf55b1dc99311f011859  ./arm64-v8a/libopenxr_loader_generic.so
+227626fcd96ea31a5c4fbd006e971b40f9b5a1e10d1bb30456f0a2792fa2c9e2  ./arm64-v8a/libglshim.so
+34ae4e6757adf83942d179a098ae91b4da187fead17e02a3a65dd6507daf2073  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
-7f30861c770361a4e311e3f486dcd2e48cd99a7f907961829ce68e24af17d775  ./arm64-v8a/libvrapi.so
-7f30861c770361a4e311e3f486dcd2e48cd99a7f907961829ce68e24af17d775  ./arm64-v8a/libvrapi_foveation.so
-d2361ee8b6ff62d2ff6b3f59f7b15730b95bdbe0e9dcee469ffa1117411e7288  ./armeabi-v7a/libopenxr_loader_generic.so
+f7f8349b0d3e9a29305b4d2aa1eb3ec6b394feff4d3e2ea07b8a65f6df1d15f9  ./arm64-v8a/libvrapi.so
+71b3df219f331bcb42a483550e35371475b1aa886762ddcf5d0d739d74c51ead  ./arm64-v8a/libvrapi_foveation.so
+c7dea9e3435f36e281341121a9e43102f008cc08bba08191c21bac14912e6b87  ./armeabi-v7a/libopenxr_loader_generic.so
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 b634ab5640e258563c536e658cad87080553df6f34f62269a21d554844e58bfe  ./hevc/COPYING.FFmpeg
 141de01f0d40b97d4f9a720db5ab8ea442f6aa35db5272048899292884994a1c  ./hevc/libstagefrighthw.so
@@ -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
@@ -0,0 +1,22 @@
+package: com.FireproofStudios.GhostTown
+title: Ghost Town
+status: works
+tested_version: '1.01'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.hw_video_decode
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-14'
+  known_good_sha256: 248b59ade696bdd4808fc05c2117aa9e8debe133d3d0874a276cc8cb67439f58
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 299
+source_hint: Ghost Town
@@ -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
@@ -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
@@ -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
@@ -0,0 +1,24 @@
+package: com.MeatSpace.Nakatomi
+title: Vendetta Forever
+status: works
+tested_version: 1.0.4.0
+engine: Unity
+xr: OpenXR
+frame:
+- frame.bhaptics_permission
+- 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-15'
+  known_good_sha256: 72885ad42f1b730a1bd7fad271b87665914e3cf14fde60409395868458ac7b06
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 321
+source_hint: com.MeatSpace.Nakatomi
@@ -0,0 +1,23 @@
+package: com.PotamWorks.SmashDrums
+title: Smash Drums
+status: works
+tested_version: 5.2.1.4
+engine: Unity
+xr: OpenXR
+frame:
+- frame.bhaptics_permission
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+  scene_emul: 1
+verified:
+  date: '2026-10-15'
+  known_good_sha256: 67d36cdcadaf14c2f744849ae25af4f92bf8ea14ff935318562f40d7f2ddc88f
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 320
+source_hint: com.PotamWorks.SmashDrums
@@ -0,0 +1,24 @@
+package: com.RuneSkovboJohansen.EyeOfTheTemple
+title: Eye of the Temple
+status: works
+tested_version: '1.528'
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_no_msaa
+- frame.unity_oculus_check
+- 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-15'
+  known_good_sha256: 78ad96eaf4383b02666e0a1af99c5985f718f97982466e5dca9ebb636974af00
+  app: 1.1.1
+  overport_cli: 1.2.5
+  issue: 302
+source_hint: Eye of the Temple
@@ -0,0 +1,25 @@
+package: com.TacticalNounours.QuantumVoid
+title: Quantum Void
+status: issues
+notes: no hands
+tested_version: '1.11'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.bhaptics_permission
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+  pose_time_fix: 1
+foveation: tracked
+verified:
+  date: '2026-10-14'
+  known_good_sha256: 1c7afccbd627b9bd2342884679aeca0efc2429df700f3c73ec162498db320098
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 307
+source_hint: Quantum Void
@@ -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.2.0). 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.2.0
@@ -0,0 +1,22 @@
+package: com.Virtuallyz.OperationWolf
+title: 'Operation Wolf Returns: First Mission VR'
+status: works
+tested_version: '0.28'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.hw_video_decode
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-15'
+  known_good_sha256: aff311f10d3e938e1eeef22263da7fe84ca38f25786ca4483543596de335c702
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 318
+source_hint: com.Virtuallyz.OperationWolf
@@ -0,0 +1,19 @@
+package: com.Virtuos.R6DLM
+title: 'Medal of Honor: Above and Beyond'
+status: unknown
+notes: 'Not yet tested on the Frame (the game is ~41 GB, too large to install on the dev unit). Its first-run
+  Downloader screen is invisible in Lepton, so it stayed stuck there; frame.unreal_skip_obb_delivery skips the check.
+  The OBB files still have to be present. Please report back whether it reaches the game (GitHub 159).'
+details: 'Medal of Honor packs its data in OBBs behind Epic''s DownloaderActivity, whose name/size check is
+  obfuscated (its methods are renamed), so FramePort didn''t recognise it and the "skip the OBB delivery check"
+  option never appeared. Detection now recognises the obfuscated predicate and frame.unreal_skip_obb_delivery
+  rewrites it to pass. frame.hw_video_decode gives the game''s videos the Frame''s hardware decoder.'
+tested_version: '0.518'
+engine: Unreal
+xr: VrApi
+frame:
+- frame.hw_video_decode
+- frame.unreal_skip_obb_delivery
+updated: '2026-10-15'
+min_app: 1.2.0
+source_hint: Medal of Honor
@@ -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)
@@ -0,0 +1,23 @@
+package: com.coatsink.augmentedempireremastered
+title: AugmentedEmpire
+status: works
+tested_version: '1.1'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.hw_video_decode
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+  scene_emul: 1
+verified:
+  date: '2026-10-15'
+  known_good_sha256: e07afd561c305493cf09efe9c869be892e475a48538dfdf617e33a0be2e6c678
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 311
+source_hint: com.coatsink.augmentedempireremastered
@@ -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.2.0
@@ -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
@@ -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)
@@ -0,0 +1,22 @@
+package: com.farbridge.vastreaches
+title: 'Homeworld: Vast Reaches'
+status: issues
+notes: The game starts but after selecting to start a new game it seems to crash.
+tested_version: 1.2.0-25215
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-15'
+  known_good_sha256: 6c5cb4b56fd01d20cb854e834b1611c2b2e8f10d889585606e631104d2a9323e
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 314
+source_hint: com.farbridge.vastreaches
@@ -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
@@ -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
@@ -0,0 +1,26 @@
+package: com.nextgenreality.mmrx
+title: Mini Motor Racing X
+status: works
+tested_version: 1.3.6
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_no_msaa
+- frame.unity_oculus_check
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+  pose_time_fix: 1
+verified:
+  date: '2026-10-15'
+  known_good_sha256: f1df011117c918794b9d9da0c5a170fc7ac7cb7ec10eddc2dd4db649d855a531
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 317
+source_hint: com.nextgenreality.mmrx
@@ -0,0 +1,27 @@
+package: com.picselica.OceanRiftFullQuest
+title: Ocean Rift
+status: works
+notes: eye tracked foveated rendering works great!
+tested_version: '2.09'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  controller_models: 1
+  haptic_fix: 1
+  scene_emul: 1
+foveation: tracked
+verified:
+  date: '2026-10-14'
+  known_good_sha256: 63020505f27af3d463798679999000e2d9bc671e72913138a16171461e3c95d2
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 304
+source_hint: Ocean Rift
@@ -0,0 +1,22 @@
+package: com.polyarc.MossGame
+title: Moss
+status: works
+notes: The initial loading image looks glitchy, but otherwise it works well.
+tested_version: 1.0.3.151047
+engine: Unreal
+xr: VrApi
+alt_overport:
+- patch_remove_unreal_force_quit
+frame:
+- frame.hw_video_decode
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-15'
+  known_good_sha256: 4aaae261dcc67de1d04309e31c0ea17dbc980b431adc8ce1917ae72ac4f9d417
+  app: 1.2.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 91
+  issue: 315
+source_hint: com.polyarc.MossGame
@@ -0,0 +1,22 @@
+package: com.resolutiongames.demeo
+title: Demeo
+status: works
+tested_version: 1.42.40696-release
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+  scene_emul: 1
+verified:
+  date: '2026-10-15'
+  known_good_sha256: adae217584c956e5574c5248868afdbb50a1f3ffd0609783215412d39b54e9ee
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 313
+source_hint: com.resolutiongames.demeo
@@ -0,0 +1,24 @@
+package: com.resolutiongames.jade
+title: Battlemarked
+status: works
+tested_version: 7.2.39817-release
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.hw_video_decode
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+  pose_time_fix: 1
+  scene_emul: 1
+verified:
+  date: '2026-10-15'
+  known_good_sha256: 670c7c16ec8d85b3865b120d143143dc73387ec325feaa028320608b1f377e7d
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 312
+source_hint: com.resolutiongames.jade
@@ -0,0 +1,21 @@
+package: com.voidroom.TeaForGodEmperor
+title: Tea For God
+status: works
+tested_version: 1.1.1
+engine: Other
+xr: OpenXR+VrApi
+frame:
+- frame.bhaptics_permission
+- frame.hw_video_decode
+adapter:
+  equirect_emul: 1
+foveation: tracked
+verified:
+  date: '2026-10-14'
+  known_good_sha256: 89b0b20d5a5b414604163def76b50aaed26961ac283dab08ff7eb469f5bacde6
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 295
+source_hint: Tea For God
@@ -0,0 +1,23 @@
+package: com.wanadev.ragnarockquest
+title: Ragnarock
+status: issues
+tested_version: 2.8.0
+engine: Unreal
+xr: VrApi
+alt_overport:
+- patch_remove_unreal_force_quit
+frame:
+- frame.unreal_skip_obb_check
+- frame.bhaptics_permission
+- frame.hw_video_decode
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-15'
+  known_good_sha256: 365f26d9a4991e2340311dfb40d14f097a066653f97fff55c632aa1876519d70
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 319
+source_hint: com.wanadev.ragnarockquest
@@ -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.2.0
@@ -0,0 +1,22 @@
+package: io.doublejack.maestro
+title: Maestro
+status: works
+tested_version: 0.0.397
+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-15'
+  known_good_sha256: 4ca71bf4464691ab2c675fbeca1ecc5f4d34599c0a810fd3a67374c91d47f6ee
+  app: 1.1.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 88
+  issue: 316
+source_hint: io.doublejack.maestro
@@ -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
@@ -6,6 +6,11 @@
 # 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
@@ -44,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
@@ -86,7 +91,7 @@ signatures:
    pattern: 'xrCreateSwapchain \d+x\d+ .*faces=6 .*result=-\d+'
    unless: 'cube_standin: runtime refused'
    severity: fatal
-    diagnosis: The game asked for a cube-map swapchain (for example an OVROverlay skybox or loading cube), which the Frame's runtime doesn't have. OVRPlugin goes on without images and crashes in ovrp_EndFrame4 (Unity's render thread SIGSEGV in memset, for example Budget Cuts Ultimate). FrameBridge from FramePort 0.12 serves such swapchains itself and drops their cube layers (cube_standin, GLES games) - rebuild and reinstall the game.
+    diagnosis: The game asked for a cube-map swapchain (for example an OVROverlay skybox or loading cube), which the Frame's runtime doesn't have. OVRPlugin goes on without images and crashes in ovrp_EndFrame4 (Unity's render thread SIGSEGV in memset, for example Budget Cuts Ultimate). FrameBridge from FramePort 0.12 serves such swapchains itself and drops their cube layers (cube_standin, GLES games); rebuild and reinstall a GLES game to try this workaround. For a Vulkan game, the current build cannot stand in for the cube swapchain yet.
    suggest: [frame.adapter]
    supersedes: [unity-render-crash, native-crash]
  - id: swapchain-rect-invalid
@@ -94,6 +99,11 @@ signatures:
    severity: fatal
    diagnosis: The runtime rejects the game's frames, so it stops drawing (for example stuck at a "Waiting" box). An image rect reaches a few pixels past its swapchain on some Frames; FrameBridge from FramePort 0.11.0 clamps the rects, so rebuild and reinstall the game.
    suggest: [frame.adapter]
+  - id: cylinder-menu-layers-rejected
+    pattern: 'xrEndFrame failed -16\b'
+    severity: error
+    diagnosis: The game draws a curved (cylinder) screen to each eye separately (for example the Doom3Quest / PreyVR menu). The Frame's runtime has no cylinder layers, so FrameBridge shows each as flat quad strips; a per-eye pair makes too many quad layers for one frame and the runtime rejects the whole frame (XR_ERROR_LAYER_INVALID), leaving the menu black while the game runs. FrameBridge from this build shows the left eye's strips to both eyes to halve the count; rebuild and reinstall the game to try it.
+    suggest: [frame.adapter]
  - id: missing-ovr-symbol
    pattern: '(UnsatisfiedLinkError|cannot locate symbol) .*"?(ovr_[A-Za-z0-9_]+|ovr[A-Z][A-Za-z0-9]*_ToString)'
    severity: fatal
@@ -263,6 +273,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]
@@ -375,10 +386,13 @@ 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" (frame.unreal_skip_obb_check) skips only the CRC content check and applies only when the APK enables bVerifyOBBOnStartUp. Copy the APK and OBB
+      from the same install, add the game again and reinstall.
+      If the downloader still appears with bVerifyOBBOnStartUp=false (already disabled in the APK or by the skip patch), try
+      "Unreal: skip the OBB delivery check" (frame.unreal_skip_obb_delivery), 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; neither option is a guaranteed fix, and 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
@@ -556,6 +570,132 @@ 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: []
+  # ---- Quest games on this PC (AXRB, docs/PC_ANDROID.md): AXRB's host.err/session.json + guest log
+  - id: axrb-no-headset
+    kind: axrb
+    pattern: 'failed to find D3D11 adapter requested by OpenXR runtime|xrCreateInstance failed: XR_ERROR_RUNTIME_FAILURE'
+    severity: fatal
+    diagnosis: The PC's OpenXR runtime (SteamVR) has no headset to show the game on, so AXRB's bridge couldn't open its VR session. Connect the headset (Steam Link / cable) and let SteamVR show it before starting the game.
+    suggest: []
+  - id: axrb-host-not-ready
+    kind: axrb
+    pattern: 'Host pose server did not become ready|Host failed to start'
+    severity: fatal
+    diagnosis: AXRB's Windows bridge (axrb-host-bridge.exe) didn't start, so the game was never launched. Its reason is in host.err (diagnostics); a missing headset is the usual one.
+    suggest: []
+    report: true
+  - id: axrb-gfxstream-crash
+    kind: axrb
+    pattern: 'vulkan\.ranchu\.so \(gfxstream::vk::'
+    severity: fatal
+    diagnosis: The game crashed inside the Android emulator's Vulkan driver (gfxstream), reached through AXRB's runtime layer (e.g. Pinball FX VR at its first Vulkan allocations). That's AXRB's GPU path, not FramePort's build - report it to AXRB with the diagnostics.
+    suggest: []
+    report: true
+  - id: axrb-translation-crash
+    kind: axrb
+    pattern: 'libndk_translation\.so \(berberis::|DEBUG\s*:.*#00 pc \S+\s+/system/lib64/libndk_translation\.so'
+    severity: fatal
+    diagnosis: The game crashed in Android's ARM translation (libndk_translation), which runs Quest games' arm64 code on the PC's x86 CPU (known for some Unity games, AXRB issue #9). Nothing to patch in the game; AXRB plans another translator.
+    suggest: []
+  # AXRB's direct mode (axrb-direct.exe, no emulator): direct.log lines are "<s> <tid> E/<tag>: ..." from the runner
+  # and "E/<tag>(<tid>): ..." from the game's Android log; direct.out has AppProcess's AXRB_AOSP_* lines
+  - id: axrb-direct-incomplete
+    kind: axrb
+    pattern: 'Direct mode installation is incomplete|Direct mode is missing |AXRB Direct is incomplete|Preparing the AOSP application failed'
+    severity: fatal
+    diagnosis: AXRB's direct mode is missing part of itself or of its Android system root, so the game was never started. Reinstall AXRB-Emulatorless (or rebuild the local build FRAMEPORT_AXRB_DIRECT_DIR points at), then `frameport pc install-axrb --backend direct` sets the system root up again.
+    suggest: []
+  - id: axrb-direct-no-vulkan
+    kind: axrb
+    pattern: 'vulkan-1\.dll is not installed|E/vulkan: \S+ is not available on the host'
+    severity: fatal
+    diagnosis: AXRB's direct mode found no usable Vulkan driver on this PC (or the driver lacks a function the game calls). Install the graphics card's current driver.
+    suggest: []
+  - id: axrb-direct-no-gles
+    kind: axrb
+    pattern: 'eglInitialize\b.*(?:fail|0x3008)|Failed to initiali[sz]e EGL|Unable to initiali[sz]e (?:EGL|the OpenGL)|EGL_BAD_DISPLAY|Unable to retrieve the default EGL display'
+    # Unreal Vulkan builds probe EGL at start too (eglInitialize -> EGL_BAD_DISPLAY in direct mode), then create
+    # their Vulkan device: only a session without one is a GLES game (Deadpool VR, 2026-10-15)
+    # ... and one that died first on something AXRB's direct mode lacks (a dialog window, a framework call) never
+    # got that far: that is the blocker, not EGL (Of Lies and Rain, NOPE CHALLENGE, 2026-10-16)
+    unless: '(?m)I/vulkan: vkCreateDevice\(.*\) = 0$|UnsupportedOperationException: addToDisplayAsUser|^AXRB_SERVICE_UNIMPLEMENTED '
+    severity: fatal
+    diagnosis: The game draws with OpenGL ES, and AXRB's direct mode only has a Vulkan renderer. Install it for AXRB's emulator instead (the "AXRB mode on this PC" option, pc.axrb_backend backend=emulator, or `frameport install <game> --to pc --axrb-backend emulator`).
+    suggest: []
+  - id: axrb-direct-no-native-window
+    kind: axrb
+    pattern: '(?m)^AXRB_AOSP_HOST_SURFACES 0'
+    unless: 'APP_CMD_INIT_WINDOW|AXRB_AOSP_TAKEN_SURFACE|AXRB\.Space|session state='
+    severity: warning
+    diagnosis: The game's activity got no window in AXRB's direct mode. NativeActivity games (CryEngine, other own engines) take their surface with Window.takeSurface, which AXRB's direct mode doesn't serve yet (it only hands SurfaceViews one), so they wait for APP_CMD_INIT_WINDOW forever and never start VR (The Climb 2 stopped after "Loading plug-in CryHTTP"). That's AXRB's side; AXRB's emulator may run the game.
+    suggest: []
+    report: true
+  - id: axrb-direct-vulkan-extensions
+    kind: axrb
+    pattern: 'Renderer initialization[\s\S]{0,600}?CrySystem initialization failed'
+    unless: 'fp_vkext: listing'
+    severity: fatal
+    diagnosis: CryEngine found its Vulkan device without extensions every Quest has (VK_EXT_fragment_density_map, Android's external memory) and gave up before creating it; the PC's graphics driver doesn't have them. "Vulkan - list Android's external-memory extensions (this PC)" lists them for the game in builds for this PC, and AXRB leaves them out again when the device is created.
+    suggest: [frame.vk_android_extensions]
+  - id: axrb-direct-unhandled-instruction
+    kind: axrb
+    pattern: 'fatal signal 4 \(SIGILL\)|unhandled synchronous signal 4 '
+    severity: fatal
+    diagnosis: AXRB's direct mode met an arm64 instruction its translator can't run (Dynarmic, or Digitalis when chosen) and the game stopped. That's AXRB's side - report it to AXRB with the diagnostics (direct.log has the instruction's address); the other translator (pc.axrb_backend translator=digitalis / dynarmic) or AXRB's emulator may get further.
+    suggest: []
+    report: true
+  - id: axrb-direct-guest-crash
+    kind: axrb
+    pattern: 'E/cpu: thread \d+ \(.*\): fatal signal (?:5|6|7|11) '
+    severity: fatal
+    diagnosis: The game's own arm64 code crashed in AXRB's direct mode (a SIGSEGV/SIGBUS/SIGABRT, or the SIGTRAP Unity raises on a fatal error; direct.log has the backtrace by library). Often a missing Android service or a translation bug rather than the game; try the other translator (pc.axrb_backend translator=digitalis) or AXRB's emulator, and report it to AXRB with the diagnostics.
+    suggest: []
+    report: true
+  - id: axrb-direct-host-fault
+    kind: axrb
+    pattern: 'E/host-fault: |E/fatal: '
+    severity: fatal
+    diagnosis: axrb-direct.exe itself crashed (its translator or Linux/Binder layer, not the game). That's AXRB's side - report it to AXRB with the diagnostics.
+    suggest: []
+    report: true
+  - id: axrb-direct-dialog-window
+    kind: axrb
+    pattern: 'UnsupportedOperationException: addToDisplayAsUser'
+    severity: fatal
+    diagnosis: The game opened a second Android window (a Dialog, for example Unreal's message box or a Unity plugin's dialog) and AXRB's direct mode can only show the game's own activity, so the game stopped ("Adding window failed"). Seen with Medieval Dynasty, Under Cover and Of Lies and Rain. That's AXRB's side; AXRB's emulator shows dialogs, so `--axrb-backend emulator` may get further (Vulkan games there go through gfxstream).
+    suggest: []
+    report: true
+  - id: axrb-direct-unimplemented-service
+    kind: axrb
+    pattern: '(?m)^AXRB_SERVICE_UNIMPLEMENTED \S+'
+    severity: error
+    diagnosis: The game (or a library in it, often Google Play services) called an Android framework service function AXRB's direct mode doesn't implement yet (the line names it, e.g. IActivityManager.getMyMemoryState for NOPE CHALLENGE); the call throws, and an uncaught one ends the game. That's AXRB's side - report it to AXRB with the diagnostics; AXRB's emulator has the full framework.
+    suggest: []
+    report: true
+  - id: axrb-direct-java-crash
+    kind: axrb
+    pattern: 'E/app: the application crashed|FATAL EXCEPTION: |Runtime aborting|JNI DETECTED ERROR IN APPLICATION'
+    severity: fatal
+    diagnosis: The game's Java side (or Android's ART runtime under it) ended with an uncaught exception or an abort in AXRB's direct mode. direct.log / direct.err have the stack; a framework service AXRB's direct mode doesn't provide yet (Meta/Play services, account, DRM) is the usual cause.
+    suggest: []
+  - id: axrb-direct-missing-function
+    kind: axrb
+    pattern: 'guest called unknown host function|unimplemented JNI function|call to unregistered host function'
+    severity: error
+    diagnosis: The game called an Android/JNI function AXRB's direct mode doesn't implement yet; it may fail right after. Report it to AXRB with the diagnostics.
+    suggest: []
+  - id: axrb-direct-unsupported-syscall
+    kind: axrb
+    pattern: 'W/syscall: unimplemented syscall|W/binder: unsupported (?:command|ioctl|object type)|execve\(.*\) refused: one process image only'
+    severity: warning
+    diagnosis: The game asked for a Linux system call or Binder feature (or a second process) AXRB's direct mode doesn't provide. Often harmless; when the game then fails, it's the first thing to report to AXRB.
+    suggest: []
+  - id: axrb-direct-slow-stop
+    kind: axrb
+    pattern: 'the game did not close within 25 seconds'
+    severity: info
+    diagnosis: The game didn't finish its activity shutdown when the session ended, so AXRB stopped it; anything it hadn't saved yet may be lost.
+    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,
@@ -564,6 +704,13 @@ 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: axrb-host, kind: axrb, pattern: 'AXRB TCP: listening', label: AXRB bridge started}
+  - {id: axrb-direct-art, kind: axrb, pattern: '(?m)^AXRB_AOSP_BOOTSTRAP', label: Android runtime (ART) started (direct mode)}
+  - {id: axrb-direct-activity, kind: axrb, pattern: '(?m)^AXRB_AOSP_ACTIVITY_CREATED ', label: Game activity created (direct mode)}
+  - {id: axrb-runtime, kind: axrb, pattern: 'AXRB\.PoseClient|Got runtime: package: com\.axrb\.openxrruntime', label: AXRB's OpenXR runtime loaded}
+  - {id: axrb-instance, kind: axrb, pattern: 'xrCreateInstance\(\) succeeded|LoaderInstance::CreateInstance succeeded', label: OpenXR instance created}
+  - {id: axrb-direct-vulkan, kind: axrb, pattern: '(?m)I/vulkan: vkCreateDevice\(.*\) = 0$', label: Vulkan device created on the PC's GPU (direct mode)}
+  - {id: axrb-frames, kind: axrb, pattern: 'AXRB\.Perf end-frame', label: Submitting frames}
  - {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}
  - {id: pcvr-inject, kind: pcvr, pattern: 'Succesfully injected|Successfully injected', label: Revive injected into the game}
@@ -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.

@@ -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.
@@ -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 |  |
@@ -28,6 +30,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Carve Snowboarding | Quest | ✅ Works |  |
 | Caves | Quest | ✅ Works |  |
 | Clockwork | Quest | ✅ Works |  |
+| COMPOUND | Quest | ✅ Works |  |
 | Cook-Out | Quest | ✅ Works |  |
 | Cosmodread | Quest | ✅ Works |  |
 | Creed | Quest | ✅ Works |  |
@@ -40,14 +43,17 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | 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 |  |
@@ -68,6 +74,7 @@ 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 |  |
@@ -81,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 |  |
@@ -89,11 +97,13 @@ 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 |  |
@@ -125,9 +135,9 @@ 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. |
@@ -135,21 +145,22 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | 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… |
-| 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. |
@@ -0,0 +1,470 @@
+# Quest games on this PC (AXRB)
+
+FramePort's PC target ("This PC") already runs Oculus Rift games through Revive. For Quest/Android games it uses
+**AXRB** (Android XR Bridge, github.com/Android-XR-Bridge/AXRB): an Android 16 emulator (x86_64 Google APIs image,
+WHPX) that runs arm64 games through Android's ARM translation (`libndk_translation`), with AXRB's own OpenXR runtime
+inside Android and a Windows host process (`axrb-host-bridge.exe`) that opens a real OpenXR session on the PC's
+runtime (SteamVR, Virtual Desktop, ...). FramePort only drives it: it downloads AXRB's official release when a user
+first installs a Quest game on the PC, never bundles or modifies it (AXRB's host/clock code is under the AXRB
+Source-Available License 1.0, which allows running it and interoperating through its public interfaces).
+
+Status: **experimental**. AXRB is young (v1.0.4, 2026-10-06) and many games still fail in it; Steam Frame
+controllers don't work in AXRB yet (AXRB issue #20).
+
+## Two backends: the emulator (1.0.4) and direct mode (2.x, "AXRB-Emulatorless")
+
+AXRB's main branch (2026-10-15, launcher 2.0.0) became **AXRB-Emulatorless**: a separate program (own installer,
+app id `org.axrb.emulatorless`, `%LOCALAPPDATA%\Programs\axrb-emulatorless-launcher`, runtime
+`%LOCALAPPDATA%\AXRB-Emulatorless Runtime`, profile `%APPDATA%\AXRB-Emulatorless`) whose **direct mode** runs the
+game without an emulator: `axrb-direct.exe` translates the game's arm64 code (Dynarmic JIT; Digitalis optional) and
+runs the real AOSP ART + framework from Google's Android 16 arm64 system image, with its own Linux syscall/Binder
+layer; Vulkan goes to the Windows driver, frames and tracking through the same `axrb-host-bridge.exe`. **Vulkan only:**
+its EGL is a stub, there is no GLES renderer. Both programs can be installed side by side; FramePort keeps one
+`axrb.Install` record per backend (`backend`, `version`, app folder, AXRB's root = `resources\runtime`, runtime
+folder) and picks per game:
+
+- **Choice** (`targets/pc_android.choose_backend`): `--axrb-backend direct|emulator` on `frameport install --to pc`,
+  else the recipe's `pc.axrb_backend` (device category, `on_pc`: part of the PC build's selection, no-op on the
+  Frame), else **direct for `graphics` Vulkan, emulator for GLES / unknown**. Unreal games never declare
+  `android.hardware.vulkan`; since analysis version 20 their manifest meta-data
+  `com.epicgames.{ue4,unreal}.GameActivity.bSupportsVulkan` = true makes them "Vulkan (Unreal bSupportsVulkan)"
+  (UE 4.25+ Quest builds, e.g. Deadpool VR, Pinball FX VR, Myst; false or missing = GLES: Espire 1, Vader Immortal). `deployment.json` records `backend`
+  and the launcher `flags`; installs from before have none (= emulator). Switching leaves the other backend's copy
+  and saves alone.
+- **Per-game options** (`pc.axrb_backend` params → `run_direct_game.ps1` switches): `translator` (`dynarmic` =
+  AXRB's default, `digitalis`), `precompose` (`-PrecomposeProjectionLayers`, also for the emulator's
+  `run_windows_game.ps1`; also taken from AXRB's own `core/game-compatibility.json` profile for the game, e.g. The
+  Climb 2), `legacy_oculus_driver` / `quest_identity` / `controllers_only` (for unconverted store APKs with older
+  Oculus loaders; off by default and never taken from AXRB's profiles: FramePort always hands AXRB an OVRPort build;
+  `controllers_only` only works with the legacy driver, as `prepare_art_session.py` requires).
+- **Install/upgrade** (`tools/axrb.install`): `releases/latest` when it has the backend's installer
+  (`AXRB-Setup-*.exe` / `AXRB-Emulatorless-Setup-*.exe`, SHA256SUMS checked, `/S`), else the known-good release
+  (`KNOWN_GOOD = {"emulator": "1.0.4"}`, `releases/tags/v1.0.4`). An install older than the known-good one is
+  upgraded on use; `frameport pc install-axrb --backend … --update` upgrades to the release on offer. No 2.x release
+  is published yet: **`FRAMEPORT_AXRB_DIRECT_DIR`** names a local build (AXRB's source tree after
+  `scripts\build\build_direct.ps1` + the host build, its `out\direct`, or a folder laid out like the installed
+  `resources\runtime`): it needs the files of AXRB's `core/direct-runtime-files.cjs` (`out\direct\axrb-direct.exe`,
+  `art\axrb-bootstrap.dex`, `art\lib64\*`, `guest\lib64\*`, `guest\axrb-systemdriver.apk`) plus
+  `scripts\run\run_direct_game.ps1`, `scripts\run\stop_game.ps1`, `scripts\paths.ps1`,
+  `direct\tools\make_sysroot.py`, `direct\tools\prepare_art_session.py`, `out\host\bin\Release\axrb-host-bridge.exe`
+  (+ `openxr_loader.dll`, `out\gpu\Release` for the GPU-share layer) and ideally `tools\python` (else Python from
+  PATH). A local build is set up but never replaced. `FRAMEPORT_AXRB_DIRECT_RUNTIME` overrides the runtime folder
+  (default: the launcher's `library.json` `settings.managedDirectory`, else `%LOCALAPPDATA%\AXRB-Emulatorless Runtime`).
+- **Direct setup** (`axrb.setup_direct`, what `core/direct.mjs ensureDirectSystem` does): the pinned image
+  (`arm64-v8a-36_r02.zip`, 810,736,863 bytes, SHA-1 `62ad6714…`; values read from the installed `core/direct.mjs`,
+  only `dl.google.com`) into its own empty folder, AXRB's `make_sysroot.py <zip> <runtime>\direct\sysroot.new --art`
+  with AXRB's embedded Python, receipt `.axrb-sysroot.json` `{"digest","format"}`, rename to `sysroot`, archive
+  deleted; `license-acceptance.json` like AXRB's DirectSetup. Ready = receipt matches + the key files exist and
+  aren't empty + AXRB's direct files complete. Requirements: ≥ 6 GB RAM, `vulkan-1.dll` (no hypervisor, no GPU
+  vendor gate).
+- **Direct install** (no adb): the PC build is copied to `%LOCALAPPDATA%\FramePort\axrb\games\<pkg>\<pkg>.apk`
+  (FramePort removes its converted copies after an install; `FRAMEPORT_AXRB_LAUNCHER_DIR` moves FramePort's `axrb`
+  folder, for isolated `FRAMEPORT_HOME` runs), the launch activity comes from the APK's manifest
+  (`axml.launcher_activity`, `pkg/fully.qualified.Class`), the data files become AXRB's content list `assets.txt`
+  (`Android/obb/<pkg>/<file>\t<Windows path>`, read-only mounts of the files where they are; WSL-only folders, which
+  Windows reads only through `\\wsl$`, are copied next to the APK). AXRB's `prepare_art_session.py` turns every
+  content file into one `--mount-ro` argument of `axrb-direct.exe` (with the path resolved: junctions and 8.3 names
+  don't shorten it), and Batman's 90 files from a long dump folder made a 32,876-character command line (Windows'
+  limit is 32,767: "The filename or extension is too long"). A list over 25,000 characters therefore goes through
+  hard links in `games\<pkg>\content` (no extra space; only on the drive FramePort's folder is on), else the install
+  stops with a clear message. App data and saves: `<runtime>\direct\data\data\<pkg>` and
+  `direct\sdcard\Android\data\<pkg>`.
+- **Play**: Steam shortcut → `%LOCALAPPDATA%\FramePort\axrb\fp-axrb-direct.ps1 -Package … -Activity … [flags]` →
+  sets `AXRB_DATA_HOME=<runtime>\output` (as AXRB's launcher does) → AXRB's `run_direct_game.ps1 -Apk -Package
+  -Activity -GameName -Executable <root>\out\direct\axrb-direct.exe -DataDirectory <runtime>\direct -Sysroot
+  <runtime>\direct\sysroot [-AssetList] -Translator …`. Exit 4 = host lost.
+- **Launch test**: watches `direct.out` for `AXRB_AOSP_ACTIVITY_CREATED` / `AXRB_AOSP_LIFECYCLE` (5 min for ART's
+  interpreted first start), runs, then stops through AXRB's `stop_game.ps1 -ParentPid` (closes the bridge window;
+  the run script lets the game pause/stop/save). Logs `<runtime>\output\logs\game\{direct.out, direct.err,
+  direct.log, host.err, host.log, session.json}` (diagnostics: `axrb/direct/*`); triage signatures
+  `axrb-direct-*` and milestones ART started → activity created → OpenXR → Vulkan device (`catalog/triage.yaml`).
+
+**Tested end to end with a local build** (2026-10-15, AXRB `windows-android16` @ 59626ac built on the dev PC,
+`FRAMEPORT_AXRB_DIRECT_DIR` = its staged `runtime\`, the staged sysroot reached through a junction
+`<FRAMEPORT_AXRB_DIRECT_RUNTIME>\direct\sysroot`; Monado's simulated HMD, see below): scan → PC build → direct
+install → `frameport test --to pc --sim --axrb-backend direct` → launcher → AXRB's run script → bridge + runner →
+milestones → AXRB's Stop. Still untested: the 2.x NSIS installer (no release yet), `setup_direct`'s download +
+`make_sysroot.py` path, the upgrade of an installed 1.0.x, AXRB's launcher seeing FramePort-set-up runtimes.
+
+### Direct-mode results (2026-10-15, Monado simulated HMD at 72 Hz, Dynarmic, no headset)
+
+PC build = the catalog recipe's PC selection (OVRPort's patches + `on_pc` fixes + FrameBridge with `focus_hold=0`),
+no `pc.axrb_backend` options. "fps" = AXRB.Perf `end-frame` (game) / `host-fresh-submit` (bridge → Monado), the
+median of the last summaries. What is drawn was judged from Monado's window and AXRB's layer captures.
+
+| Game (engine, graphics) | Reached | fps | Picture | Blocker / notes |
+|---|---|---|---|---|
+| Batman: Arkham Shadow 1.4.1-350961 (Unity, Vulkan; 90 content files, 27 GB) | menu (SELECT REGION) in ~25 s | 63.7 / 62.9 | stereo menu over the Batcave scene, both eyes correct | none; needed the content-list fix (command line overflow) and hard links; stop clean (activities stopped) |
+| PowerWash Simulator VR 2.5.0 (Unity 2020.3, Vulkan) | in game: the garage hub (~3-4 min; at 90 s still its loading logo) | 70.5 / 69.8 | garage in both eyes, both hands drawn at the simulated controllers | none; Meta multiplayer callbacks throw NullReferenceExceptions (no Meta services, harmless so far) |
+| LEGO Bricktales 2.1 (Unity, Vulkan, URP) | scene `Diorama_Hub_Startup` loaded (~3 min) | 72 / 72 | intro text panel ("You want to free the simulation? Follow the white rabbit.") on black, both eyes | stop slow: the game didn't finish its activity shutdown in 25 s (`axrb-direct-slow-stop`); Meta achievements fail (no Meta services, harmless) |
+| Toy Master 1.1.2 (Unity 2022.3, **GLES**) | activity created, then crash in 18 s | - | - | not a Vulkan game: "Vulkan (Unity boot.config)" came from the Oculus plugin's `xr-vulkan-*` keys; Unity: "Unable to retrieve the default EGL display!" + SIGTRAP. Automatic choice now sends such games to the emulator |
+| Marvel's Deadpool VR 1.0.40 (UE 4.27, Vulkan; `frame.vk_sanitize` in the build) | first-run LANGUAGE menu (~3 min; at 90 s still loading at 1-2 fps) | 64 (FrameBridge pacing) | game-drawn stereo menu, both eyes | none; AXRB transcodes ASTC to BC on the GPU; stop slow (`axrb-direct-slow-stop`) |
+| Pinball FX VR 1.9 (UE 5.3, Vulkan, 7 GB OBB) | 3D lobby with the Terms & Conditions panel (~4 min) | ~60 (FrameBridge pacing) | arcade hall + panel in both eyes | none of the emulator's blockers (gfxstream `vkAllocateMemory` SIGSEGV, and Refract's FRSQRTE SIGILL / ASTC layout probe / promoted extension names) showed up in direct mode (no SIGILL under Dynarmic, no ASTC or device-loss failure; AXRB stores ASTC as BC); OVRPlugin's xrPerfSettingsSetPerformanceLevelEXT unsupported (harmless) |
+| Myst 3.3.0 (UE 5.3, Vulkan) | loading screen (book), then its starfield intro | 72 | stereo, both eyes | a white splash quad at first (texture not shown yet), then normal |
+| Metro Awakening 1.0-916944 (UE 5.2, Vulkan) | splash art, then the USER DATA COLLECTION consent screen with the laser pointer | 72 | stereo, both eyes | stop slow (`axrb-direct-slow-stop`) |
+
+Unreal Vulkan games: before analysis version 20 every Unreal game was "GLES or unknown" (Unreal never declares
+`android.hardware.vulkan`), so the automatic choice sent them to the emulator; now `GameActivity.bSupportsVulkan`
+picks direct mode (Myst and Metro above were installed without `--axrb-backend`). Unreal probes EGL before it
+creates its Vulkan device, which tripped `axrb-direct-no-gles`; the signature now needs no Vulkan device. None of
+the four needed a recipe change for the PC.
+
+Integration bugs found and fixed on the way: AXRB's trap message never reached FramePort's log; the content list
+overflowed the command line (Batman); Unity's EGL failure and SIGTRAP weren't triaged; long sessions lost their
+start-up milestones; the boot.config Vulkan label picked direct mode for GLES games. Open, AXRB's side: the content
+list should reach `axrb-direct.exe` as a file (FramePort's hard links only work when the data is on the drive of
+FramePort's folder; drafted as an upstream issue). Needs a headset: picture and latency through SteamVR, sound,
+controllers (the simulated ones hold still), Batman beyond its region menu.
+
+### VrApi-direct games (2026-10-16, direct mode, Monado simulated HMD, Dynarmic, no headset)
+
+Games whose engine calls VrApi itself (no OVRPlugin), so OVRPort can't translate them: they need a `libvrapi.so`
+that translates VrApi to OpenXR. Two candidates: FramePort's `frame.vrapi_bridge` (OVRPort's translator + FramePort's
+changes) and OVRPort's own `patch_vrapi_openxr` (the unpatched translator; only in experimental CLI builds made with
+`-PwithVrApi=true`, e.g. the `OVRPort-CLI-1.2.5-experimental-5e7df52.jar` AXRB's v1.0.0/1.0.1 releases attached;
+AXRB's own profile for The Climb 2 uses it with `-PrecomposeProjectionLayers`). Only converted copies of both games
+were at hand, so the comparison swapped the one file (OVRPort's = the v1.2.5 build from the 2026-10-02 Frame tests).
+
+| Game (engine, graphics) | VrApi route | Reached | fps | Picture | Blocker / notes |
+|---|---|---|---|---|---|
+| The Climb 2 2.2 (CryEngine, Vulkan VrApi) | FramePort's bridge | first-start menu (gender/skin selection) in ~60 s | 69.8 / 69.8 | menu, both hands and controllers, both eyes (AXRB layer captures + Monado's window) | needs AXRB's HostWindow fix (below, AXRB's side) + `frame.vk_android_extensions`; crash only during AXRB's stop (forgiven by triage); no `-PrecomposeProjectionLayers` needed |
+| The Climb 2 2.2 | OVRPort's translator | the same menu | 70.2 / 70.2 | identical | same blockers; passes AXRB's AHB device-extension request through unchanged (worked only because `libfp_vkext.so` lists AHB) |
+| Path of the Warrior (own engine, **GLES** VrApi) | - | not run | - | - | GLES: direct mode can't run it; the emulator (1.0.4) had a copy signed with another key installed by another test, so it wasn't replaced. OVRPort's translator can't run it anywhere (no GLES path: `cannot locate symbol "vrapi_GetTextureSwapChainHandle"`, Frame test 2026-10-02); FramePort's bridge has one |
+
+**Default for PC builds: FramePort's bridge** (`frame.vrapi_bridge`, now `on_pc = True`; recipes keep it as they
+are, nothing to switch). Both translators give the same picture and frame rate in direct mode, but OVRPort's needs
+an unpublished experimental CLI (stable jars list `patch_vrapi_openxr` but fail), has no GLES path (POTW, every GLES
+VrApi game on the emulator) and lacks the device-extension filter; FramePort's is the same code the Frame builds
+use, so one recipe serves both.
+
+Blockers found on the way (in order):
+1. **No window for NativeActivity** (AXRB's side, drafted upstream): CryEngine's `EngineActivity` takes its surface
+   with `Window.takeSurface`; direct mode's `HostWindow.attach` only bridges SurfaceViews (`AXRB_AOSP_HOST_SURFACES
+   0`), so `APP_CMD_INIT_WINDOW` never comes and the game waits after `Loading plug-in CryHTTP` (triage
+   `axrb-direct-no-native-window`). A ~40-line HostWindow patch (`mTakeSurfaceCallback` → `registerSurface` +
+   `surfaceCreated/Changed`, bootstrap dex rebuilt with AXRB's `build_art_bootstrap.py` into a test copy of the
+   local build) fixed it. Likely the same for every NativeActivity engine.
+2. **Quest Vulkan device extensions**: CryEngine checks its list before vkCreateDevice and gave up
+   (`CrySystem initialization failed!`): AXRB's runtime asks for `VK_ANDROID_external_memory_android_hardware_buffer`
+   also in direct mode, and the game requires `VK_EXT_fragment_density_map` (NVIDIA's Windows driver has neither).
+   The bridge now leaves runtime extensions no device offers out; `frame.vk_android_extensions` lists the missing
+   Quest ones to the renderer (AXRB drops them at vkCreateDevice). Triage `axrb-direct-vulkan-extensions`.
+3. **Simulator only**: Monado's head lacks POSITION_TRACKED, so AXRB's host never made its LOCAL origin and the
+   bridge never got a tracked head (empty frames, `initial recenter: head flags=0x0`) → `--sim` sets AXRB's
+   `AXRB_TEST_SYNTHETIC_HMD=2`.
+4. The analysis called The Climb 2 "GLES or unknown" (no manifest declaration) → analysis 20: engines importing
+   `vrapi_CreateSystemVulkan` are "Vulkan (VrApi Vulkan system)", so it goes to direct mode automatically.
+
+Debugging aid: `FRAMEPORT_AXRB_TEST_ENV="AXRB_DIRECT_TRACE=syscall,vulkan;AXRB_CAPTURE_FIRST_SEQUENCE=4500"` passes
+variables to a launch test's AXRB processes (`AXRB_DIRECT_DUMP` only works in AXRB's own VM mode, not with ART).
+Needs a headset: the picture through SteamVR, controllers past the first menu (the simulated ones hold still),
+climbing, sound; and a released AXRB-Emulatorless with the window fix.
+
+### Library sweep 2026-10-16
+
+Every other Quest game of the owner's library that `pipeline.pc_installable` accepts and whose APK still exists,
+installed with `frameport install <pkg> --to pc --no-library` (automatic backend, isolated `FRAMEPORT_HOME`, catalog
+recipe or heuristics, no per-game changes) and tested with `frameport test <pkg> --to pc --sim --seconds 150` (240 for
+Unreal) under Monado's simulated HMD at 72 Hz. Direct mode = the local AXRB build of 59626ac **with the HostWindow
+patch** (above; upstream had no newer commit or 2.x release on 2026-10-16); emulator = AXRB 1.0.4 with this branch's
+`adb install -g`, `projection_only=2` and qwerty-head fixes. "fps" = game submits / bridge to Monado (AXRB.Perf
+medians); "Picture" = Monado's window (both eyes) at the end of the run, plus AXRB's layer captures. Not run: the
+three 32-bit-only games (Sports Scramble, Shadow Point, Journey of the Gods: AXRB has no AArch32, and the PC build
+drops the 32-bit bridge), and the emulator games after NEX Player (disk, see the end).
+
+| Game (engine) | Backend | Reached | fps | Picture | Blocker / notes |
+|---|---|---|---|---|---|
+| Arcsmith 1.128 (Unity) | direct | frames | 59 / 51.7 | in game: the workshop, both hands with tools, both eyes | none |
+| QuestCraft 6.0.0-RC4 (Unity) | direct | frames | 65.1 / 63.6 | launcher room, QuestCraft EULA panel, laser pointers | none (Minecraft itself is behind its Continue button) |
+| BattleGlide 0.4.1 (UE) | direct | frames | 62.2 / 54.8 | title screen (START), both hands | none |
+| In Death: Unchained 1.8.0 (UE) | direct | frames | 64.1 / 56.9 | sky + PRIVACY UPDATE panel | none |
+| The Boys VR 1.1.0 (Unity) | direct | frames | 62.4 / 59.9 | ANALYTICS DISCLAIMER panel over a lit floor, laser | slow stop |
+| Creed: Rise to Glory CE (UE) | direct | frames | 60.6 / 55.5 | IMPORTANT SAFETY INFORMATION panel, both hands, laser | none |
+| Wallace & Gromit: The Grand Getaway 1.0.34 (UE) | direct | frames | 61.5 / 53.5 | space scene (nebula, planets), both gloved hands | none |
+| VR4 2.3 (UE) | direct | frames | 71.9 / 72 | title scene: church interior, "resident evil 4" logo, both hands | none (slow stop) |
+| Demeter 1.1.0 (Unity, MR) | direct | frames, FrameBridge scene emulation active | 62.3 / 57.3 | "PERMISSION REQUIRED ... access to your spatial data" panel, controllers | AXRB's direct mode grants only 8 allow-listed permissions (`HostPackageManager.permission`): `com.oculus.permission.USE_SCENE` stays denied although the build declares it (`frame.meta_permissions`). AXRB's side |
+| Green Hell VR 2.5.2 (Unity) | direct | frames | 11.8 / 11.7 | loading screen at "50%" after 180 s | slow load |
+| TRIANGLE STRATEGY 1.0 (UE) | direct | frames | 44.6 / 40.2 | both controllers with a "Control Guide" label, rest black at 280 s | still loading? |
+| Riven 1.9.0 (UE) | direct | frames | 29.8 / 25.2 | white splash quad (AXRB captures), black window at 274 s | still loading (as Myst's white splash) |
+| Espire 2 1.7.13 (UE) | direct | frames | 72 / 71.8 | white splash quad low in both eyes at 289 s | splash texture never shown |
+| Carve Snowboarding 1.09 (UE) | direct | frames | 64.5 / 59.3 | both hands, rest black at 270 s | scene never appears; not diagnosed |
+| Asgard's Wrath 2 12.1 (UE, 33 GB) | direct | frames | 30.6 / 21.9 | black at 287 s | still loading |
+| Assassin's Creed Nexus 207706 (Unity) | direct | frames | 42.6 / 42.6 | black at 180 s (captures too) | loading or no visible layer yet |
+| BARTENDER VR SIMULATOR 1.9.2.7 (UE) | direct | frames (in a second process) | 62.7 / 53.6 | black for 260 s (window + captures all 0) | not diagnosed (no Unreal log lines in direct.log) |
+| Vermillion 1.7.2 (Unity) | direct | frames, OVRManager focused | 63.8 / 60.3 | black with its brush loading icon | stays there (Vuplex 3D WebView starts, then nothing) |
+| H.U.N.T 0.1.2 (Unity OpenXR) | direct | session created, no frame in 200 s | - | bridge splash | never submits a frame; not diagnosed |
+| WiiCompiled VR 0.4.0 | direct | 2D launcher activity, no OpenXR | - | bridge splash | its launcher imports games through a document picker; the VR part is a second activity |
+| Medieval Dynasty New Settlement 2.4 (Unity) | direct | OpenXR FOCUSED, exit(1) at 30 s | - | - | **opens an Android Dialog** (right after "initOculus Java!"); direct mode can't add a second window (`UnsupportedOperationException: addToDisplayAsUser`, "Adding window failed"). Triage `axrb-direct-dialog-window` |
+| Under Cover 1.1.3r2 (Unity) | direct | Vulkan device, exit(1) at 33 s | - | - | the same Dialog |
+| Of Lies and Rain 1.1.0 (UE) | direct | vkCreateInstance, exit(1) at 32 s | - | - | Unreal's `MessageBox01` (an error box before its Vulkan device; its text is lost with the window) |
+| NOPE CHALLENGE 1.0.964 (UE) | direct | ART, crash at 15 s | - | - | Google Play services call `IActivityManager.getMyMemoryState`: `AXRB_SERVICE_UNIMPLEMENTED` -> uncaught exception. Triage `axrb-direct-unimplemented-service` |
+| BAM 1.2 (Unity) | direct (manifest declares Vulkan) | activity, crash at 33 s | - | - | runs GLES: "Unable to retrieve the default EGL display!"; the manifest's Vulkan feature doesn't say which API Unity picks first. Emulator run not reached |
+| Mobile Suit Gundam: Silver Phantom 1.1.58 (Unity) | direct | install refused | - | - | 257 content files with ~80-character names don't fit axrb-direct.exe's command line even through hard links (the guest paths alone are too long); needs AXRB to read the list from a file or mount the folder. Emulator run not reached |
+| Silhouette 1.3.0 (Unity) | emulator | frames | 30.2 / 30.1 | title menu (Play / Options / Quit), both eyes | none headless |
+| Yupitergrad 2.6.1 (Unity) | emulator | frames | 13.8 / 14 | splash ("Loading...") in both eyes | still loading at 174 s |
+| 4XVR Video Player 2.0.22 | emulator | frames | 34.9 / 32.2 | black | gfxstream rejects its GL every frame: `glEnable(GL_FRAMEBUFFER_SRGB_EXT)`, a `glTexParameteri` value, vertex attribute index >= `CODEC_MAX_VERTEX_ATTRIBUTES` |
+| NEX Player 1.3.1 (Unity) | emulator | frames | 9.3 / 9.3 | black | not diagnosed |
+| Lambda1VR 1.7.3 (Team Beef) | emulator | Java crash at start | - | - | `libopenxr_loader_google.so not found`: TBXR ports load `openxr_loader_<Build.MANUFACTURER>`; `frame.tbxr_vendor` handles "valve" and isn't in PC builds; AXRB's Android says "google" (a PC variant: add that library and match "google" in the maker checks) |
+
+Summary (31 games run): **8 reach a menu or the game in both eyes** in direct mode (Arcsmith in game; QuestCraft,
+BattleGlide, In Death, The Boys, Creed, Wallace & Gromit, VR4 at their first menu/panel) and 1 in the emulator
+(Silhouette); Demeter shows its own "permission required" panel; 12 submit frames but were still loading or black at
+the end of the run (big Unreal games at 30-45 fps while loading under Dynarmic); 9 never submit a frame. The most
+common blockers, all on AXRB's side:
+1. **No second window in direct mode** (3 games: Medieval Dynasty, Under Cover, Of Lies and Rain): any Android
+   Dialog ends the game. Upstream candidate together with the permission allow-list (Demeter's `USE_SCENE`) and the
+   unimplemented framework calls (Play services' `getMyMemoryState`, NOPE).
+2. **Long or loading-heavy starts**: under Dynarmic the large Unreal games need more than 4-5 minutes to their first
+   picture (Riven, Asgard's Wrath 2, TRIANGLE STRATEGY, Espire 2's white splash); a longer `--seconds` would show more.
+3. **The content list on the command line** (Gundam): a list file or folder mounts in `axrb-direct.exe` would fix it
+   for good (drafted upstream).
+4. GLES-in-direct-mode mislabels: a Unity manifest that declares Vulkan can still run GLES (BAM).
+
+FramePort changes from the sweep: triage `axrb-direct-dialog-window` and `axrb-direct-unimplemented-service`
+(`axrb-direct-no-gles` no longer blames Unreal's EGL probe when one of those ended the game first); the
+command-line message suggests the emulator; and **direct-mode uninstalls and reinstalls remove the libraries AXRB's
+`prepare_art_session.py` extracts per APK** into `<runtime>\direct\installed\<identity>`, which AXRB never deletes
+(5 GB after 25 games; `pc_android.staged_libraries` computes AXRB's identity: the APK's Windows path + every
+`lib/arm64-v8a` entry's name, CRC and size; unit-tested, not yet seen on a real uninstall).
+
+The emulator half stopped after NEX Player: the WSL disk and C: filled up (other jobs; C: 14 GB free, below the 60
+GB the sweep keeps), so the remaining emulator games were not run: The Room VR, Pixel Ripped 1995, Time Stall, Five
+Nights at Freddy's: HW, Star Wars Pinball VR, I Am Cat, Vader Immortal 1-3, Genotype, Phantom: Covert Ops, Sniper Elite
+VR (+ Winter Warrior), Robo Recall, Budget Cuts Ultimate, Espire 1, BodyCombat, Star Wars: Tales from the Galaxy's
+Edge, HITMAN 3, Jurassic World Aftermath, Nano, Wander, Stremio, Eleven Table Tennis, BlazeRush, plus BAM and Gundam
+in the emulator.
+
+## Spike results (2026-10-10, Windows 11 26200, i7-14700K, RTX 4080 SUPER, 64 GB; headless)
+
+| Step | Result |
+|---|---|
+| AXRB install | `AXRB-Setup-<v>.exe /S` (electron-builder one-click NSIS, per user, no UAC) → `%LOCALAPPDATA%\Programs\axrb-launcher`, 462 MB. Release assets: Setup exe + `SHA256SUMS-<v>-setup.txt` + source zip (no portable zip since 1.0.4). |
+| Runtime setup | Not scriptable through AXRB (it lives in the Electron launcher's JS), so FramePort reproduces it: 4 pinned `dl.google.com` zips from AXRB's `core/components.json` (emulator 36.5.11, platform-tools r37.0.1, build-tools 36.1, `sys-img/google_apis/x86_64-36_r07`), hash-checked, into `%LOCALAPPDATA%\AXRB Runtime\sdk`, AVD `axrb-managed-api36` written as AXRB writes it, `ready.json` / `license-acceptance.json` receipts so AXRB's own launcher sees the same runtime as set up. 2.4 GB download, ~3 min on a fast line; 26 GB on disk after one 7 GB game. |
+| Emulator boot | AXRB's `scripts\emulator\windows_android_emulator.ps1 -Action Start` (headless QEMU, AXRB clock adapter + GPU layer). First cold boot ~6 min (TSC-corrected clock cold-boots every time). ABIs `x86_64,arm64-v8a`. QEMU (`Start-Process`) and the adb server inherit the caller's handles: a pipe, a file through WSL interop, even `/dev/null` through interop (its relay stays open) all left the FramePort call hanging after the script had ended → FramePort starts AXRB scripts through WMI (`Win32_Process.Create`, hidden, nothing inherited), polls the PID and reads an `FP_EXIT <code>` line from the log. Windows PowerShell 5.1's `*>>` writes UTF-16. |
+| AXRB runtime | `adb install --no-incremental --force-queryable -r axrb-openxr-runtime-debug.apk` (0.3 s); found by the OpenXR loader through the system runtime broker. |
+| Data | `adb push` of OBB/pak files: 25-35 MB/s (7.2 GB Pinball FX VR in 5.5 min). A full uninstall (or a signature change: `INSTALL_FAILED_UPDATE_INCOMPATIBLE`) deletes the OBB folder and the saves → FramePort's stable per-game keys matter here too. |
+| **Original APK** (Pinball FX VR) | No launcher activity (Meta's VR category only), started explicitly: **SIGABRT 0.3 s after loading Meta's `libovrplatformloader.so`**. Unconverted Quest APKs don't run. |
+| **OVRPort-only build** (Lucky's Tale, Unity 2019 GLES) | OVRPort's loader → AXRB runtime → instance + session, frames submitted (2 s each without a host: the image send times out), no crash in 40 s. |
+| **OVRPort-only build** (Pinball FX VR, UE5 Vulkan) | OVRPlugin pre-init OK (AXRB reports "Oculus 67.522.0"), then exits (ForceQuit) / with the no-ForceQuit build SIGSEGV in `gfxstream vkAllocateMemory` called from AXRB's runtime Vulkan layer. Not decided headless (no host attached, see below). |
+| Host bridge | Needs an OpenXR runtime with a D3D11 adapter. Headless options all failed: SteamVR's null driver (`failed to find D3D11 adapter requested by OpenXR runtime`), `vrlink` without a headset (`xrCreateInstance` -2), Meta XR Simulator (binary download needs a Meta developer login). → frames-to-SteamVR need a real headset. |
+
+**Build decision: FramePort hands AXRB an OVRPort-only build** (the recipe's OVRPort patches, no Steam Frame fixes,
+signed with the game's FramePort key). The original APK crashes; FramePort's Frame fixes (FrameBridge adapter, Lepton
+and Frame-runtime workarounds) target the Frame. The recipe's alternate (no-ForceQuit) build is used when the recipe
+says so. (Since 2026-10-15 the PC build also carries the runtime-independent APK fixes and FrameBridge, see below.)
+
+## Which patches reach the build for this PC
+
+One recipe serves both builds; `patches/base.pc_selection(patches, analysis)` picks the PC part (used by
+`build.build(pc=True)`, `pipeline.pc_recipe_fingerprint`, the PC deployment record and `ui/components.pc_outdated`).
+`docs/PATCHES.md` marks each kept patch "also in builds for this PC (AXRB)".
+
+- **All of OVRPort's patches** (category `overport`).
+- **APK fixes that don't depend on Lepton or the Frame's runtime** (`Patch.on_pc = True`): they fix the game's own
+  code or its Meta libraries, which misbehave the same way in AXRB's Android (no Meta services, not a Quest device
+  model, no Horizon app): `frame.ovrplatformcompat`, `frame.ovrstubs`, `frame.swapchain_limit` (OVRPort's
+  dispatcher), `frame.ovr_stable_user`, `frame.unreal_ovrp_entrypoints`, `frame.avatar_stub`, `frame.vrapi_stub`,
+  `frame.metaxr_telemetry`, `frame.oculusos`, `frame.ovr_microphone`, `frame.langpacks`, `frame.asset_files`,
+  `frame.asset_files_stub`, `frame.ovr_trace`, `frame.blazerush`, `frame.unity_oculus_check` (with its ovrpshim),
+  `frame.unity_text_input`, `frame.unreal_quest_precompile`, `frame.unreal_quest_keymap`,
+  `frame.unreal_thumb_touch`, `frame.unreal_skip_obb_check`, `frame.unreal_skip_obb_delivery`, `frame.nodebug`,
+  `frame.meta_permissions`, `frame.launcher`, and `frame.vrapi_bridge` (VrApi → OpenXR through OVRPort's loader,
+  so AXRB's runtime; seen working in direct mode with The Climb 2, see "VrApi-direct games" below; the bridge
+  doesn't need the GL shim, but GLES games keep `frame.gl_shim` for gfxstream, see "GLES games in the emulator").
+- **Experimental on the PC, for GLES games in the emulator**: `frame.gl_shim` (only with a GLES analysis,
+  `Patch.pc_keeps`; Vulkan VrApi games never get it), `frame.unity_multipass` (also added by `pc_detect`), and the
+  GLES FrameBridge defaults `scale` ≤ 0.5, `scale_max=1`, `projection_only=1`.
+- **Experimental on the PC** (`on_pc = "experimental"`, kept but not yet seen working in AXRB): `frame.vk_sanitize`
+  (the Vulkan shim; gfxstream / the host driver instead of Lepton's Fossilize), `frame.unity_tls_key_pool`,
+  `frame.eos_keychain_loop`.
+- **PC-only APK fix** `frame.vk_android_extensions` (`pc_detect`: direct-VrApi games whose engine creates VrApi's
+  Vulkan system, analysis `graphics` "Vulkan (VrApi Vulkan system)"): the renderer's
+  `vkEnumerateDeviceExtensionProperties` import goes to `libfp_vkext.so`, which also lists the Quest device
+  extensions the PC's driver lacks (VK_EXT_fragment_density_map, Android external memory); AXRB's vkCreateDevice
+  leaves them out again.
+- **FrameBridge** (`frame.adapter`) with its settings in `lib/<abi>/libframe_settings.so`: it wraps OVRPort's loader
+  the same way in AXRB (scale, haptic_fix, pose_time_fix, rect_clamp, profile_remap, ...). Left out
+  (`settings.PC_DENY`): `sync_guard` (a race in the Frame's vrclient.so), `focus_hold` / `focus_hold_ms` (the
+  Frame's flickering wear sensor; FrameBridge's built-in default is on, so the PC build writes `focus_hold=0`,
+  `settings.PC_VALUES`), `controller_models` (models the agent converts from the Frame's SteamVR at install) and the
+  settings only the GL shim / Zink shader layer read (`gl_*`, `zink_*`). `controller_fix` stays: it is the game's
+  choice (0 = hand tracking) and its Touch mapping of `/valve/` and generic profiles is runtime-independent.
+  FrameBridge finds `libframe_settings.so` next to its own path (dladdr); on the Frame the agent also passes the
+  settings as files, in AXRB the library is the only source, so the PC build turns `extractNativeLibs` on
+  (`build.extract_native_libs`; apps with `extractNativeLibs="false"` would map their libraries from base.apk).
+  Without OVRPort (a 32-bit recipe) the PC build drops FrameBridge: there is no loader to wrap.
+- **PC-only:** OVRPort's `patch_disable_meta_xr_audio_telemetry` (for x86_64 ARM translation, which AXRB is) is
+  never in a Steam Frame recipe (`applies()` is False); `pc_selection` adds it, given the analysis, to games with
+  Meta XR Audio (`Patch.pc_detect`; AXRB's own profile turns it on for North Star).
+- **Off on the PC:** Lepton/Android 11 workarounds (clipboard, Vivox audio route, start activity, ...), the Zink/Mesa
+  GL shims and shader layer, pac_hints/luajit, hardware video decoding, every `device.*` option, the 32-bit bridge.
+- TODO: `device.files` (files written into the game's storage at install) could be reproduced with `adb push` in
+  `targets/pc_android.py`.
+
+### FramePort end to end (same day, headless, this branch)
+
+`frameport install com.playful.LuckysTale --to pc --no-library` (isolated `FRAMEPORT_HOME`): PC build (19 patches:
+OVRPort's + `frame.ovrplatformcompat`/`frame.ovrstubs`/`frame.swapchain_limit`; static checks pass without the
+FrameBridge check) → AXRB found, requirements met → emulator → AXRB runtime → `adb install` → 3.7 GB OBB in ~95 s
+(39 MB/s) → `deployment.json` + launcher script. `frameport test com.playful.LuckysTale --to pc`: launcher → AXRB run
+script → host bridge → triage `axrb-no-headset` (expected without a headset). The Steam shortcut write (needs a Steam
+restart) is unit-tested only.
+
+## How FramePort drives AXRB
+
+- `tools/axrb.py`: find (env `FRAMEPORT_AXRB_DIR` > installed AXRB) / install (Setup exe, SHA256SUMS checked, `/S`) /
+  runtime setup (above) / requirements (WHPX via AXRB's `check_windows.ps1`, ≥ 12 GB RAM, x64).
+- Environment for every AXRB script (the installed build sets none of it itself): `AXRB_DATA_HOME=<Runtime>\output`,
+  `ANDROID_AVD_HOME=<Runtime>\avd`, `ANDROID_USER_HOME=<Runtime>\android`, `ANDROID_HOME`/`ANDROID_SDK_ROOT=<Runtime>\sdk`,
+  `ANDROID_ADB_SERVER_PORT=5038`, `ADB_USB_LEGACY=1`, `ADB_LOCAL_TRANSPORT_MAX_PORT=5683`, AXRB's embedded Python
+  (`resources\runtime\tools\python`) first on PATH; arguments `-Sdk <Runtime>\sdk -Avd axrb-managed-api36 -Port 5584`.
+- Install: start the emulator if needed (and stop it again if FramePort started it), install the AXRB runtime APK,
+  `adb install -r` the build, push OBB/data to `/sdcard/Android/obb|data/<pkg>/`, record `<data>/pc/<pkg>/deployment.json`
+  (`kind: "android"`).
+- Play: a Steam shortcut runs FramePort's small launcher script (`%LOCALAPPDATA%\FramePort\axrb\fp-axrb-run.ps1`),
+  which sets the environment above and calls AXRB's `scripts\run\run_windows_game.ps1` (boots the emulator when
+  needed and then owns it, registers a SteamVR app identity, starts the host bridge, `am start`, waits; exit codes
+  0 ok, 1 error, 3 game lost, 4 host lost; `logs\game\session.json`, `host.err`).
+- Logs for diagnostics: `<Runtime>\output\logs\game\{host.log,host.err,session.json,guest.log}`,
+  `logs\emulator\emulator.std{out,err}.log`.
+
+## Headset results (2026-10-10, Steam Frame streaming to the PC through Steam Link / vrlink, 96 Hz)
+
+AXRB's bridge opened a SteamVR session on the Frame each time (session state up to FOCUSED, both hands active), started
+through FramePort's launcher with the emulator booted by AXRB's run script (~1 min), and shut down cleanly.
+
+- **Lucky's Tale (Unity, GLES): black.** GLES games go through AXRB's raw image path (eye readback → TCP), sized
+  by SteamVR's recommended resolution: 3412×3412 per eye at the owner's 250 % supersampling = 93 MB per frame,
+  ~10 s per frame; at a lowered resolution 2644×2644 = 56 MB, 6.6 s per frame (~8.5 MB/s). AXRB's zero-copy GPU
+  path covers Vulkan games only. The ~8.5 MB/s was the transport, not the readback: see "GLES games in the
+  emulator" below (adb reverse: ~100 MB/s, half-size eyes, multipass: Lucky's Tale draws at 30 fps).
+- **Pinball FX VR (UE5, Vulkan): crash 4 s after start**, the same gfxstream `vkAllocateMemory` SIGSEGV from AXRB's
+  runtime layer as headless (so not a headless artefact). AXRB's side.
+
+Not reached: sound, controllers. Next candidates: a Vulkan game AXRB reports playable (Deadpool VR, Batman: Arkham
+Shadow); an AXRB issue for the Pinball crash.
+
+## GLES games in the emulator (2026-10-16, headless under Monado's simulated HMD)
+
+AXRB 1.0.4's emulator is the only backend with GLES (direct mode's EGL is a stub). A GLES frame is read back with
+`glReadPixels` on the game's thread inside `xrEndFrame` (`runtime/src/frame_transport.cpp`), sent as raw RGBA to the
+host (two eyes per frame) and uploaded there; `xrEndFrame` returns only after the send. Measured with
+`AXRB.Perf eye-readback` / `image-send` (guest log) and `host-image-arrival` (host.err):
+
+| Eye size (per eye) | Bytes/frame | Route | Send | Frame rate |
+|---|---|---|---|---|
+| 896×1007 (Monado's recommendation) | 7.2 MB | default: TCP to 10.0.2.2 (QEMU user-mode network) | 850-950 ms | 1.1 fps |
+| 448×504 (`scale=0.5`) | 1.8 MB | default | 200-230 ms | 4.4 fps |
+| 896×1008 | 7.2 MB | **adb reverse** (`debug.axrb.image_transport=adb`) | 87 ms (~83 MB/s) | 9.4 fps |
+| 640×720 (`scale=0.7`) | 3.7 MB | adb reverse | 38 ms (~96 MB/s) | 17.6 fps |
+| 448×512 (`scale=0.5`) | 1.8 MB | adb reverse | 14.5 ms (~125 MB/s) | 30.5-30.8 fps |
+
+The readback itself is 1-3 ms. The default route caps at ~8 MB/s (the same rate as in the headset run above); AXRB's
+adb reverse route (AXRB sets up `adb reverse tcp:38491` anyway) is 10-15x faster. For SteamVR's resolutions the math
+stays hard: 2016² per eye = 32.5 MB/frame (~3 fps), at half size 8.1 MB (~10 fps); the owner's 2644² at half size
+14 MB (~6 fps). Lowering SteamVR's resolution for the game is what helps further (AXRB has a minimum-extent setting,
+`AXRB_MIN_EYE_EXTENT`, but no maximum).
+
+What FramePort does for GLES games on this PC (all in the PC build / launcher, nothing on the Frame changes):
+- FramePort's launcher (`fp-axrb-run.ps1`) starts Android itself when it isn't running (AXRB's Start action, as the run
+  script would; the run script then gets `-OwnsEmulator` and shuts it down), sets `debug.axrb.image_transport=adb`
+  (`FRAMEPORT_AXRB_IMAGE_TRANSPORT=default` leaves AXRB's choice) and `debug.wm.disable_deprecated_target_sdk_dialog=1`.
+- `pc_selection` with a GLES analysis: FrameBridge `scale` at most 0.5 (FrameBridge's minimum), `scale_max=1` (the
+  maximum eye size reported is the scaled one too), `projection_only=2`: AXRB's emulator refuses every GLES frame with
+  more than one layer (`xrEndFrame` -2), so FrameBridge submits the projection layer alone after drawing the quad
+  layers that follow it into its eye images (`native/adapter/quad_compose_gl.c`, on the game's GL context, per eye at
+  the eye's view and FOV, blending by the quad's flags); `projection_only=1` only drops them.
+- Game installs use `adb install -g` (runtime permissions granted, as Lepton does on the Frame): Android's permission
+  dialog over the game's activity pauses Unity for good (BattleSisters asks for the microphone in its menu).
+- The VrApi bridge copies the game's eye textures into the OpenXR images with `glBlitFramebuffer` when the context
+  has no `glCopyImageSubData` (the emulator's GLES translator is "OpenGL ES 3.1" without `GL_EXT_copy_image`; its stub
+  only logs `libEGL: called unimplemented OpenGL ES API`, so every eye reached the runtime black).
+- `frame.unity_multipass` (experimental on the PC, `pc_detect` for Unity GLES + Oculus XR Plugin): gfxstream lists
+  `GL_OVR_multiview2` but its encoder finds a multiview framebuffer incomplete and drops every draw
+  (`GL2Encoder.cpp:s_glDrawElements … GL error 0x506 checkFramebufferCompleteness`): both eyes black.
+- `frame.gl_shim` (experimental on the PC, GLES only, `Patch.pc_keeps`): gfxstream has no
+  `GL_EXT_disjoint_timer_query`; the shim lists it and hands out stand-ins ("available, 0 ns") so GLAD engines that
+  call the timer queries unconditionally don't jump to NULL. Its multiview hiding also suits gfxstream.
+- FrameBridge settings without a rebuild: `frameport settings <pkg> --to pc key=value` writes
+  `/sdcard/Android/data/<pkg>/files/framebridge.conf` (emulator: adb push, Android started for it if needed; direct
+  mode: the file in AXRB's runtime folder); an empty value removes a key.
+
+Per game (AXRB 1.0.4 emulator, Monado simulated HMD at 72 Hz, FramePort's PC build; Windows 11, RTX 4080 SUPER):
+
+| Game | Build / settings | Furthest | Frame rate / time | Blocker |
+|---|---|---|---|---|
+| Lucky's Tale 1.0.55 (Unity 2019.4 + Oculus XR Plugin, GLES) | PC build + `frame.unity_multipass`, `scale=0.5`, adb route | **title scene drawn in both eyes** (Monado window captured) | 30.5-30.8 fps, image-send 14.5 ms | none headless; needs the headset (picture through SteamVR at its resolution, controllers) |
+| Accounting+ 1.24.35 (Unity 2017.4 built-in Oculus, GLES) | PC build (`frame.unity_oculus_check`), `projection_only`, old-SDK dialog off | **stance selection screen drawn in both eyes** | 10 fps, image-send 82 ms: its OVRPlugin makes 896×1024 eye buffers whatever FrameBridge's scale/max say | its quads (OVROverlay) were dropped by `projection_only=1` (AXRB rejects every multi-layer GLES frame with -2); rebuilt with `projection_only=2` (2026-10-16, qwerty head): same screen at 9.9 fps, no regression (its controller pointers are missing there because qwerty's controllers are inactive); eye size only shrinks with the PC runtime's resolution |
+| Path of the Warrior 21.11.10 (VrApi-direct GLES, own engine; from the `PATCHED/` copy) | VrApi bridge (blit copies) + GL shim (timer-query stand-ins), `scale=0.5`, `projection_only=2`, `--sim` with Monado's qwerty head | **its first screen drawn in both eyes**: the "Please ensure that your Oculus Touch Controllers are properly connected" panel (a VrApi cylinder → quad, drawn into the projection) | 38 fps, image-send ~15 ms | the simulator's controllers: Monado's qwerty builder (needed for a tracked head here, see `--sim` notes) has WMR controllers, which AXRB's bindings don't cover. Found on the way: (1) the simulated head: no tracked pose, `EnterVrMode` gave up after 30 s; (2) every frame -2 (projection + the cylinder quad); (3) black eyes: no `glCopyImageSubData` in the emulator's GLES. Before the stand-ins: SIGSEGV at pc 0 in `EgHalGrTimestampQueryGL` (NULL `glad_glGenQueriesEXT`). Needs a headset: controllers past this screen, gameplay |
+| BattleSisters 1.2.4 (Unity 2019.4 built-in VR, GLES) | PC build (ovrpshim frame loop), `scale=0.5`, installed with `-g`, `--sim` with Monado's qwerty head | **main menu drawn in both eyes** (Continue / New game / Level select hub / Last Bastion / Settings) | 31 fps for 90 s, no stall | none headless. The "hang after 3 frames" was Android's permission dialog: a few seconds into its menu the game asks for a runtime permission (microphone), `GrantPermissionsActivity` became the resumed activity over the game, Unity paused (AAudio pause, no Update2/WaitToBeginFrame/BeginFrame/EndFrame in progress per `ovrp_trace`) and nobody can answer it; not the ovrpshim frame wait and not AXRB's pacing. Fixed by installing with `adb install -g` (as Lepton does). Needs a headset: controllers, gameplay |
+
+`--sim` notes: AXRB 1.0.4's emulator host only reads `AXRB_TEST_SYNTHETIC_HMD=1` (direct mode's `=2` is newer) and
+applies it only to a head *without* valid flags; Monado's simulated head is valid but not tracked, so the host never
+sets its LOCAL origin and VrApi games never get a tracked head. For games on the emulator backend `frameport test
+--sim` therefore runs Monado's **qwerty** builder (`SIMULATED_ENABLE=0`, `QWERTY_ENABLE=1`: its head reports
+POSITION_TRACKED; host.err `AXRB OpenXR: LOCAL origin in tracking world=(0.000 1.600 0.000)`). Its controllers are
+WMR ones, which AXRB's suggested bindings (Touch/Index/Vive) don't cover: no hands. `FRAMEPORT_PC_XR_SIM_HEAD=simulated`
+keeps the simulated head (and its ml2 controllers), `=tracked` forces qwerty. Monado's `remote` builder (tracked head +
+Index controllers) would cover both but listens on 0.0.0.0:4242 (a firewall prompt), so it isn't used. FrameBridge's
+`ovrp_trace=1` (ovrpshim, Unity 2017-2019 legacy frame loop) logs every 5 s how many Update2/WaitToBeginFrame/
+BeginFrame/EndFrame calls went through and which one is in progress (thread, frame, how long): where a stalled game
+waits. AXRB's opt-in host capture (`AXRB_CAPTURE_PREFIX`) only starts at sequence 2000 in 1.0.4 (hard-coded;
+`AXRB_CAPTURE_FIRST_SEQUENCE` isn't read), which GLES games at 10-30 fps don't reach in a test: use the Monado
+window captures and FrameBridge `snapshot=N`. AXRB's guest log only keeps warnings plus AXRB's own tags: read
+`adb logcat -d` for FrameBridge/OVRPlugin lines. `debuggerd -b <pid>` works from `adb shell` (stacks).
+
+## Open (needs the owner + a headset)
+
+- A game in the headset through SteamVR (picture, audio, controllers; Steam Frame controllers: AXRB #20).
+- Pinball FX VR's Vulkan crash with the host attached happens in the emulator only; in direct mode it reaches its lobby
+  headless. Needs the headset: picture/latency through SteamVR, controllers, a table played.
+- Play from the PC's Steam library (shortcut → launcher script → AXRB).
+
+## Testing without a headset (Monado's simulated HMD, 2026-10-15)
+
+AXRB's host bridge needs an OpenXR session with a D3D11 binding, which SteamVR doesn't give without a headset. For
+unattended tests FramePort can run the bridge against **Monado for Windows** with Monado's simulated HMD instead,
+without changing the system's OpenXR runtime or touching SteamVR:
+
+- **Monado build:** an official CI artifact of `monado/monado` (gitlab.freedesktop.org, project 2685), job `windows`
+  of a `main` pipeline (there is no Windows release asset; the job's `install/` folder is the portable runtime:
+  `bin\monado-service.exe`, `bin\openxr_monado.dll`, `openxr_monado.json`, SDL2/Vulkan loader DLLs). Tested build:
+  pipeline 1766968, job 112793105, commit 8b259763f (`v25.1.0-917-g8b259763f`). Unpacked by hand into
+  `%LOCALAPPDATA%\FramePort-dev\monado\install` (or `FRAMEPORT_MONADO_DIR`): no installer, no UAC, no registry. Its
+  `share\steamvr-monado` (a SteamVR driver) is never registered.
+- **Selection per process only:** the OpenXR loader's `XR_RUNTIME_JSON=<monado>\openxr_monado.json`. HKLM's
+  `ActiveRuntime` stays SteamVR. AXRB's run script registers an app identity with SteamVR whenever HKLM names SteamVR
+  (an OpenVR utility client, which starts SteamVR), so under the simulator FramePort's launcher call answers that one
+  `python steamvr_app_identity.py` call "failed" (the script only warns).
+- **Service settings** (`tools/xr_sim.SERVICE_ENV`): `SIMULATED_ENABLE=1` (the simulated builder; the Windows build
+  only has the qwerty/remote/simulated builders, so no real device is probed), `SIMULATED_LEFT/RIGHT=ml2` (the only
+  simulated controllers whose bindings cover the Vive wand profile: AXRB suggests Touch/Index/Vive, so with `simple`
+  or `wmr` its hands stay inactive), `XRT_COMPOSITOR_DEFAULT_FRAMERATE=72`. Headless variant: `XRT_COMPOSITOR_NULL=1`
+  + `XRT_COMPOSITOR_NULL_FPS=72` (no window, nothing to capture).
+- **D3D11 + adapter:** Monado's D3D11 client compositor works (timeline semaphores); it renders on the discrete GPU
+  (Vulkan device 0, RTX 4080 SUPER here; `XRT_COMPOSITOR_FORCE_GPU_INDEX` would change it) and asks D3D11 clients for
+  that adapter's LUID, which DXGI finds.
+- **Results:** a minimal D3D11 client (`native/xrsimprobe/xr_sim_probe.cpp`, built with VS Build Tools against the
+  Khronos `openxr_loader_windows` 1.1.63 release) went IDLE → READY → SYNCHRONIZED → VISIBLE → FOCUSED in 0.01 s
+  and submitted 72 frames/s until it asked to exit. AXRB's host bridge (`--serve-openxr 38490 0 <title>`, no
+  emulator) reached `D3D11 graphics binding ready`, session state 5 (FOCUSED), `AXRB TCP: listening on
+  0.0.0.0:38490`, both controllers active with valid poses, `host-end-frame: rate=72.0/s`, its splash in both eyes.
+  No game was run yet.
+- **Seeing what is drawn:** the windowed compositor ("Monado (Windowed)", 1264×681, both eyes side by side without
+  distortion) can be saved with `native/xrsimprobe/xr_sim_capture.cpp` (`PrintWindow`, works behind other windows;
+  `xr_sim.capture(path)`), and `--sim` also sets AXRB's own opt-in `AXRB_CAPTURE_PREFIX` (4 PPM readbacks of the
+  submitted layers, 5 s apart, from frame 300) into `<data>/logs/xr-sim/`. A launch test that reached RUNNING saves
+  Monado's window there too, just before it stops the game (`<time>-<pkg>-headset.bmp`, `pc_android.sim_capture`),
+  and every AXRB launch test reports the frame rate from AXRB's `AXRB.Perf` summaries (game submits / bridge). Monado itself has no screenshot function;
+  `XRT_WINDOW_PEEK` and `XRT_DEBUG_GUI` exist but only show windows.
+- **Use:** `frameport test <pkg> --to pc --sim` (or `FRAMEPORT_PC_XR_SIM=1`): starts `monado-service.exe` hidden
+  (WMI, like AXRB's scripts; ready when its pipe `\\.\pipe\<%TEMP%>\monado_comp_ipc` exists), passes the environment to
+  the AXRB launch (`pc_android.launch_test(extra_env=…)`, default `xr_sim.active_env()`), stops the service afterwards
+  (an already running Monado is used and left running). Service log: `<data>/logs/xr-sim-service.log`.
+- **Head per backend:** when every game tested is on AXRB's emulator backend, the service runs Monado's qwerty builder
+  instead of the simulated one (a tracked head; AXRB 1.0.4's emulator host has no synthetic head for Monado's
+  untracked one, see the GLES section's `--sim` notes); its controllers stay inactive in AXRB.
+  `FRAMEPORT_PC_XR_SIM_HEAD=tracked|simulated` overrides the choice. An already running Monado is used as it is.
+- **Limits:** the simulated head wobbles slowly and the controllers hold still with no buttons pressed, so it proves
+  startup, frame submission and what is drawn, not gameplay; the windowed compositor opens a visible window on the
+  desktop; frame pacing is Monado's, not a headset's.
@@ -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.
@@ -24,6 +24,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | 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`) |
+| 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 |
@@ -60,7 +61,7 @@ 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 |
@@ -72,7 +73,15 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | 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 has CRC verification off but the delivery bypass is unavailable (GitHub #159, Medal of Honor: Above and Beyond) | Obfuscation renamed `expansionFilesDelivered`: MoH calls boolean predicates `a()` and `d()` from its package DownloaderActivity.onCreate, both logging `Checking for file : ` and calling Google expansion filename/delivery helpers. The second gate can show “Select OBB to use” | Analysis recognizes these predicates by activity, caller, log and helper return types; stuck-downloader triage offers `frame.unreal_skip_obb_delivery` as an experimental opt-in. CRC stays off. The inspected build checks three Java OBB entries and has native indexed-patch filename support; its backup has 22 OBBs and 34 MP4s, all selected from the package folder. Bypassing Java delivery does not establish native data completeness or headset success |
+| 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) |
@@ -80,6 +89,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) |
@@ -94,6 +104,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | 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 |
@@ -102,11 +113,11 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | upload in the Files tab (Videos = /sdcard/Movies) and browse folders in the app |
 | Batman: Arkham Shadow closes during smoke-bomb effects; later input-tree corruption | Meta XR Audio Wwise deletes queued metadata still referenced by the current audio frame, then writes through the stale pointer | FrameBridge automatically retires metadata after current-frame references disappear, for the verified AArch64 SDK build only; see [AUDIO_METADATA.md](AUDIO_METADATA.md) |
 | Game stays on a loading or "Waiting" box although it reached FOCUSED; log `FrameBridge: xrEndFrame failed -25` then no more `pacing:` lines (for example PowerWash Simulator on some Frames, GitHub #39) | The eye image rect ends a few pixels past its swapchain (Unity rounds the swapchain width, the runtime's recommended size differs per Frame); SteamVR rejects every frame with XR_ERROR_SWAPCHAIN_RECT_INVALID | FrameBridge clamps every projection/quad image rect to its swapchain (`rect_clamp`, default on since 0.11.0; log `rect_clamp: view N image rect clamped`): rebuild + reinstall the game |
-| Unity game (OVRPlugin, GLES) crashes ~10 s in: `FrameBridge: xrCreateSwapchain … faces=6 … result=-2`, OVRPlugin `CreateSwapchain for eye 0: 0x0, 0 stages`, then render-thread SIGSEGV in memset ← libOVRPlugin ← `ovrp_EndFrame4` (libgallium/ANR follow; for example Budget Cuts Ultimate, GitHub #107); triage `cube-swapchain-refused` | The game shows a cube-map layer (OVROverlay cubemap); the Frame's runtime has no cube layers and refuses cube swapchains (XR_ERROR_RUNTIME_FAILURE); OVRPlugin doesn't check and writes into the image list it never got | FrameBridge `cube_standin` (default on): a refused cube swapchain is served as a GL cube map in the game's context and its layers are dropped (log `cube_standin: runtime refused …`): rebuild + reinstall. GLES only; a Vulkan game keeps the error |
+| Unity game (OVRPlugin, GLES or Vulkan) crashes ~10 s in: `FrameBridge: xrCreateSwapchain … faces=6 … result=-2`, OVRPlugin `CreateSwapchain for eye 0: 0x0, 0 stages`, then render-thread SIGSEGV in memset ← libOVRPlugin ← `ovrp_EndFrame4` (libgallium/ANR follow; for example Budget Cuts Ultimate, GitHub #107); triage `cube-swapchain-refused` | The game shows a cube-map layer (OVROverlay cubemap); the Frame's runtime has no cube layers and refuses cube swapchains (XR_ERROR_RUNTIME_FAILURE); OVRPlugin doesn't check and writes into the image list it never got | FrameBridge `cube_standin` (default on): a refused cube swapchain is served as a GL cube map in the game's context or a device-local Vulkan cube image transitioned to COLOR_ATTACHMENT_OPTIMAL, and its layers are dropped (log `cube_standin: runtime refused …`): rebuild + reinstall. Vulkan path covers UNDERDOGS (GitHub #296); host-tested, headset verification pending |
 | Game (Unity, GLES) freezes, `zink: DEVICE LOST` | multisampled render-to-texture hangs the GPU | `frame.unity_no_msaa`; if it persists: unfixable → PC version |
 | Unreal GLES game crashes ~3 s after start: `Fatal signal 11 … fault addr 0x10000 in tid … (RHIThread)`, `#01 … libgallium_dri.so` (GitHub #83 Star Wars Pinball VR, triage `unreal-msrtt-crash`) | Unreal's mobile MSAA renders through multisampled render-to-texture; Zink's `find_rp_state` then indexes `rendering_state_cache[6]` one past its end (sample count ≥ 32) and calls a junk hash function (0x10000). Mesa bug (no bounds check) | `frame.unreal_gl_shim` (GL shim with `gl_hide_msrtt`, multiview kept for Unreal: Unreal 4.25 only enables multiview with GL_OVR_multiview, GL_OVR_multiview2 **and** GL_OVR_multiview_multisampled_render_to_texture, so the shim keeps the last one visible for Unreal and maps glFramebufferTextureMultisampleMultiviewOVR to the single-sampled glFramebufferTextureMultiviewOVR; log `multiview multisampled render-to-texture (N samples) drawn single-sampled`) |
 | Crash with `SIGILL (ILL_ILLOPN)` and `*pc=0xd50323bf` (autiasp), for example on Unreal's HttpManager thread (GitHub #83 Star Wars Pinball VR, triage `pac-unpaired`) | The engine's OpenSSL ARMv8 assembly has autiasp without a matching paciasp (libUE4.so: 38 paciasp, 40 autiasp; Poly1305 NEON). Quest CPUs treat PAC hints as NOPs, the Frame's CPU checks them | `frame.pac_hints`: in a library with unpaired counts every paciasp/autiasp becomes a NOP (in place) |
-| launch.log ends with `logcat: Unexpected EOF!` right after `Waiting for app …`; the game runs, but Steam's "Resume game" menu isn't closed and the launch test shows nothing (Vader Immortal on Lepton 3.0.5, Under Cover on 2.8.14; about 1 launch in 50) | Lepton's logcat mirror died | Agent v67 `_logcat_keeper` (started by launch.sh, added to older launchers by `upgrade_launchers`) reads the container's logcat itself (`podman exec lepton-steamlaunch-<appid> logcat -v threadtime -T 2000`) and appends it to launch.log; log `<base>/logcat-keeper.log` |
+| launch.log stops at `Waiting for app …` (nothing after it, `logcat: Unexpected EOF!` or `Logcat read failure`); the game runs, but Steam's "Resume game" menu isn't closed, the launch test shows nothing and session triage has no log (Vader Immortal on Lepton 3.0.5, Under Cover on 2.8.14; a silent mirror twice on 3.0.5 on 2026-10-14) | Lepton's logcat mirror died or never wrote | `_logcat_keeper` (started by launch.sh, added to older launchers by `upgrade_launchers`; agent v91) reads the container's logcat itself after a failure line or 20 s without a logcat line (`podman exec lepton-steamlaunch-<appid> logcat -v threadtime -T <epoch>`: from the launcher's start, or from just before the mirror's last line), sets a 16 MiB log buffer and appends to launch.log; log `<base>/logcat-keeper.log` |
 | A game no longer starts after a reinstall that was launch-tested right away: logcat `Zip: EOCD not found, …/base.apk is not zip` / `Failed to parse …base.apk`, no `Start proc` for the game (VR HOT, 2026-10-09) | The launch test's 45 s ran from the launcher, but the first start after an APK change spends ~1–2 min booting Lepton and installing the app: stopping the container mid-install left a broken installed copy | Agent v68: the test window counts from Lepton's `Waiting for app` (at most 240 s extra for boot + install). Repair a broken one: `touch <base>/lepton-app/game.apk` (Lepton re-installs it on the next start) |
 | Unreal game (OVRPlugin) never starts VR: launch.log has `OVRPlugin: JNI_OnLoad` but never `CompositorOpenXR::PreInitialize`, no OpenXR session, then a crash a few seconds in (for example Star Wars Pinball VR, UE 4.25: null pointer in `FSceneRenderer::GetMultiViewSceneColor`, GitHub #83) | Unreal's Oculus module looks up every `ovrp_*` function of the OVRPlugin it was built against (`InitializeOculusPluginWrapper`, all ANDed); OVRPort's OpenXR OVRPlugin lacks a few old ones (UE 4.25 / OVRPlugin 1.44: `ovrp_GetPTWNear`), so the wrapper fails and OculusHMD is never pre-initialized | `frame.unreal_ovrp_entrypoints` (suggested when analysis `unreal_ovrp_lookups` name functions the shipped OVRPlugin lacks): generated `libfp_ovrpstubs.so` (DT_NEEDED of libOVRPlugin.so; dlsym on the plugin's handle searches its dependencies) with a stand-in per missing name returning ovrpFailure (-1000); build note lists the names |
 | Only the Android home screen shows; the log has Unity's VR device as `None` (for example Accounting+, Unity 2017) | Unity 2017–2018 built-in Oculus support starts VR only when `com.oculus.systemactivities` is installed; Lepton has no Meta system apps, so Unity falls back to non-VR | `frame.unity_oculus_check`: that package name in libunity.so → `android`, plus `native/ovrpshim` (libfp_ovrp.so): Unity 2017's legacy frame loop (`ovrp_Update2`/`ovrp_BeginFrame`) never calls `ovrp_WaitToBeginFrame`, so without the shim no `xrWaitFrame` happens, `CompositorOpenXR::Update … outside of frame bounds` floods the log and the dashboard freezes. With it: log `ovrp frame loop shim: waited for frame N`, ~71 fps. Accounting+ then stops at "press any button" although its OVRInput gets clean input (`INPUT_PROBE` in the patch logs connected controllers/buttons/input focus per call) — unresolved |
@@ -146,6 +157,7 @@ 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 |
@@ -255,3 +267,28 @@ Scan a folder with Rift game dumps (Windows game folders) like Quest dumps; they
 | Proton game hangs at start in a headless/SSH launch; log `no driver could be loaded` / `explorer process failed to start` | no display session (DISPLAY/GAMESCOPE_WAYLAND_DISPLAY) | the Proton launch.sh takes them from the running Steam (built in) |
 | Unreal game starts (window created) then `CrashReportClient` runs | the game crashed under Proton; often no VR runtime reached it (Revive off) | keep `pcvr.revive` on (repacks' bundled LibRevive64.dll isn't loaded by itself); read the game log + crash summary in the launch log |
 | `VK_ERROR_DEVICE_LOST` under DXVK | freedreno GPU hang | `pcvr.proton_log` to capture; PC mode |
+
+## Quest games on this PC (AXRB, `docs/PC_ANDROID.md`)
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Unconverted Quest APK in AXRB: no launcher activity, SIGABRT ~0.3 s after `libovrplatformloader.so` loads | Meta's platform loader aborts outside a Quest | FramePort always gives AXRB its OVRPort build (the PC build: OVRPort + `on_pc` APK fixes, no Steam Frame fixes) |
+| `axrb-no-headset`: host.err `failed to find D3D11 adapter requested by OpenXR runtime` / `xrCreateInstance failed: XR_ERROR_RUNTIME_FAILURE` | SteamVR has no headset (null driver: no D3D11 adapter; vrlink with no Frame connected: no instance) | connect the headset and let SteamVR show it first; for unattended tests use Monado's simulated headset: `frameport test <pkg> --to pc --sim` (docs/PC_ANDROID.md "Testing without a headset") |
+| Testing a PC (AXRB) game without a headset: need a D3D11 OpenXR session, but SteamVR must stay untouched | SteamVR without a headset gives no D3D11 adapter / no instance | `--sim` (or `FRAMEPORT_PC_XR_SIM=1`): portable Monado for Windows, simulated HMD + `ml2` controllers, selected per process with `XR_RUNTIME_JSON` (the system runtime stays SteamVR); AXRB's SteamVR app registration is skipped; frames in `<data>/logs/xr-sim/` (AXRB_CAPTURE_PREFIX), Monado's window via `xr_sim.capture()`. Service log `<data>/logs/xr-sim-service.log` |
+| `axrb-gfxstream-crash`: SIGSEGV in `vulkan.ranchu.so (gfxstream::vk::ResourceTracker::on_vkAllocateMemory)` from `libVkLayer_AXRB_runtime.so` (Pinball FX VR, UE5 Vulkan, headless) | the emulator's Vulkan path through AXRB's runtime layer | report to AXRB with diagnostics (`axrb/*` logs); recheck with the host attached |
+| `axrb-translation-crash`: crash in `libndk_translation.so (berberis::…)` | Android's ARM translation (AXRB issue #9, some Unity games) | nothing to patch; wait for AXRB's other translator |
+| Reinstall fails `INSTALL_FAILED_UPDATE_INCOMPATIBLE`, or the game data must be copied again | a copy signed with another key was installed in AXRB (e.g. by AXRB's own launcher); a full uninstall deletes the OBB folder and saves | uninstall it in AXRB first; FramePort keeps one key per game, so its own updates keep data |
+| A FramePort call that runs an AXRB script never returns although the script ended (emulator already up) | QEMU (`Start-Process`) and the adb server inherit the caller's handles; through WSL interop even a file or /dev/null keeps the relay open | `axrb.spawn_detached` starts the script through WMI (`Win32_Process.Create`, nothing inherited) and polls its PID; exit code from the log's `FP_EXIT` line |
+| Which AXRB runs a game? (`deployment.json` `backend`) | AXRB 2.x (AXRB-Emulatorless) has a direct mode (`axrb-direct.exe`, no emulator) that only renders Vulkan; 1.0.4 is the emulator | automatic: direct for `graphics` Vulkan, emulator for GLES/unknown; `pc.axrb_backend` (backend / translator / precompose / legacy-driver options) or `frameport install <pkg> --to pc --axrb-backend direct\|emulator`; a switch leaves the other backend's copy and saves where they are |
+| `axrb-direct-no-gles`: direct.log `eglInitialize … EGL_BAD_DISPLAY` / `Unable to initialize EGL` / Unity's `Unable to retrieve the default EGL display!` | the game draws with OpenGL ES; direct mode's EGL is a stub (no GLES renderer). Not reported once a Vulkan device exists (Unreal Vulkan builds probe EGL first) | install it for the emulator (`pc.axrb_backend` backend=emulator); automatic choice already does this when the analysis says GLES |
+| `axrb-direct-incomplete`: `Direct mode installation is incomplete` / `Direct mode is missing …` / `Preparing the AOSP application failed` | a direct-mode file of AXRB is missing, or the sysroot (`<runtime>\direct\sysroot`, receipt `.axrb-sysroot.json` digest + format) isn't complete | reinstall AXRB-Emulatorless or rebuild the local build (`FRAMEPORT_AXRB_DIRECT_DIR`), then `frameport pc install-axrb --backend direct` (re-runs AXRB's `make_sysroot.py --art`) |
+| `axrb-direct-no-vulkan`: `vulkan-1.dll is not installed: the guest has no GPU` | no Windows Vulkan loader/driver | install the GPU's current driver |
+| `axrb-direct-unhandled-instruction`: `fatal signal 4 (SIGILL)` in direct.log | Dynarmic (or Digitalis) can't execute an arm64 instruction | report to AXRB with diagnostics (`axrb/direct/*`); try `pc.axrb_backend` translator=digitalis (or dynarmic) or the emulator |
+| `axrb-direct-guest-crash` (`E/cpu: thread … fatal signal 11/7/6/5`), `axrb-direct-host-fault` (`E/host-fault:` / `E/fatal:` = axrb-direct.exe itself), `axrb-direct-java-crash` (`FATAL EXCEPTION`, `Runtime aborting`) | a crash under direct mode's translator/ART; usually a missing Android service (Meta/Play/account/DRM), a translation bug or an unsupported syscall/Binder call (`axrb-direct-unsupported-syscall`, warning) | the other translator or the emulator; report to AXRB with the backtrace in direct.log |
+| `axrb-direct-no-native-window`: `AXRB_AOSP_HOST_SURFACES 0`, then nothing (The Climb 2: last line `Loading plug-in CryHTTP`, the main thread busy-polls its looper) | NativeActivity games take their surface with `Window.takeSurface`; AXRB's direct mode (`HostWindow.attach`) only bridges SurfaceViews, so `APP_CMD_INIT_WINDOW` never comes | AXRB's side (drafted upstream issue + a ~40-line HostWindow patch, tested); FramePort can't fix it in the APK. With the patched bootstrap the game gets its window (`AXRB_AOSP_TAKEN_SURFACE`) |
+| `axrb-direct-vulkan-extensions`: CryEngine `Renderer initialization` → `CrySystem initialization failed!` with no vkCreateDevice (The Climb 2, direct mode) | the PC's driver lacks Quest-only device extensions (VK_EXT_fragment_density_map is the one Climb 2 requires; Android external memory too); AXRB's runtime also asks for AHB in direct mode | `frame.vk_android_extensions` (PC builds only, added automatically for direct-VrApi Vulkan games): the renderer's `vkEnumerateDeviceExtensionProperties` import → `libfp_vkext.so`, which lists them; AXRB drops them again at vkCreateDevice. The VrApi bridge leaves runtime extensions no device has out of `vrapi_GetDeviceExtensionsVulkan` |
+| AXRB under Monado's simulator: VrApi games only submit empty frames; bridge `initial recenter: head flags=0x0`, `EnterVrMode: no tracked head pose before deadline` | Monado's simulated head lacks POSITION_TRACKED, so AXRB's host never sets up its LOCAL origin (`local_origin_flags` 0) and every pose in LOCAL has flags 0 | `--sim` sets AXRB's test-only `AXRB_TEST_SYNTHETIC_HMD=2` (fixed standing head + valid LOCAL; direct mode's host only: AXRB 1.0.4's emulator host only knows `=1`, which it ignores for a valid head) and, for games on the emulator backend, runs Monado's qwerty head instead (POSITION_TRACKED, the host sets LOCAL: `AXRB OpenXR: LOCAL origin in tracking world=(0.000 1.600 0.000)`; its WMR controllers stay inactive in AXRB, `FRAMEPORT_PC_XR_SIM_HEAD=simulated` keeps the simulated head); real headsets need neither |
+| AXRB emulator, GLES VrApi game (Path of the Warrior): frames submitted but both eyes pure black (FrameBridge `snapshot` of the eye images: all 0), guest log `libEGL: called unimplemented OpenGL ES API` about once a second | the emulator's GLES translator ("OpenGL ES 3.1") has no `glCopyImageSubData`: the VrApi bridge's copy of the game's eye texture into the OpenXR image did nothing | the bridge copies with `glBlitFramebuffer` when the context lacks ES 3.2 / `GL_EXT_copy_image` (log `GLES eye copies: glBlitFramebuffer, no glCopyImageSubData (OpenGL ES 3.1 …)`) |
+| AXRB emulator, GLES game with menus/messages as quad layers (VrApi cylinders, OVROverlay): `xrEndFrame failed: -2` on every frame, or with `projection_only=1` the menus missing | AXRB 1.0.4's emulator refuses GLES frames with more than one layer | FrameBridge `projection_only=2` (the PC default for GLES): the quads after the projection layer are drawn into its eye images on the game's GL context, then the projection layer goes alone (log `projection_only=2: 1 quad layer(s) drawn into the main picture`) |
+| A direct-mode launch test ran its full time but ends in `axrb-direct-guest-crash` | the game crashed during AXRB's own stop (after `AXRB_AOSP_ACTIVITIES_STOPPED`; The Climb 2 after `ovr_Shutdown finished`) | triage turns it into the info finding `axrb-direct-crash-at-stop`; the verdict passes |
+| Direct-mode launch test: "NEVER_STARTED" although AXRB's bridge ran | direct.out never printed `AXRB_AOSP_ACTIVITY_CREATED`/`AXRB_AOSP_LIFECYCLE` (ART's first start is interpreted, `-Xint`: slow); the run script stops when the bridge loses its headset | check host.err (`axrb-no-headset`), direct.out/err; the test waits 5 min for the activity and stops through AXRB's `stop_game.ps1` (closes the bridge window, the game pauses and saves) |
@@ -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.
@@ -13,12 +13,13 @@ embeds debug paths (`-g`) and the dex depends on the d8 version, so those differ
 |---|---|---|
 | `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), 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. |
+| `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, runtime device extensions no Vulkan device offers left out of `vrapi_GetDeviceExtensionsVulkan` (AXRB's runtime asks for AHB also in its direct mode; not in `upstream-patches/` yet), `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. |
+| `vkext/` | `arm64-v8a/libfp_vkext.so` | Quest Vulkan device extensions for builds for this PC (patch `frame.vk_android_extensions`, never on the Frame). AXRB's direct mode gives the game the Windows driver's device, which lacks `VK_EXT_fragment_density_map` and Android's external memory; CryEngine (The Climb 2) refuses to create its device without them. The renderer's `vkEnumerateDeviceExtensionProperties` import is renamed to `fpEnumerateDeviceExtensionProperties` (same length, `elf.rename_imports`) and this library added to its DT_NEEDED: it lists the real extensions plus the missing ones; AXRB's vkCreateDevice leaves those out again. Logs `fp_vkext: listing …` (tag FrameBridge). Seen working in direct mode (2026-10-16, headless). |
 | `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). |
@@ -0,0 +1,6 @@
+out/
+out-dev/
+*.core
+# generated by bridge/gen_stubs.py at every build
+bridge/guest/gen/
+bridge/host/gen/
@@ -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.
@@ -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
@@ -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()
@@ -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()
@@ -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)
@@ -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()
@@ -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) {}
@@ -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; }
@@ -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
@@ -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
@@ -0,0 +1,731 @@
+/* Guest dynamic loader: loads 32-bit ARM shared libraries (the game's) into the runtime, which is a static
+ * executable. Symbols resolve against the library itself, its DT_NEEDED libraries, every library loaded before,
+ * and the runtime's exports (libc, libm, liblog, ... = "system" libraries). Implements the bionic dl* API for
+ * guest code. */
+#include <dlfcn.h>
+#include <elf.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <link.h>
+#include <pthread.h>
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/mman.h>
+#include <unistd.h>
+#include "grt.h"
+
+#ifndef PT_ARM_EXIDX
+#define PT_ARM_EXIDX 0x70000001
+#endif
+#define DT_ANDROID_REL 0x6000000f
+#define DT_ANDROID_RELSZ 0x60000010
+/* Android used these OS-specific tags before RELR received standard ELF tags.
+ * The table encoding is identical (including ARM32's 31-bit bitmaps). */
+#define DT_ANDROID_RELR 0x6fffe000
+#define DT_ANDROID_RELRSZ 0x6fffe001
+#define DT_RELR_ 36
+#define DT_RELRSZ_ 35
+#define R_ARM_NONE 0
+#define R_ARM_ABS32 2
+#define R_ARM_REL32 3
+#define R_ARM_TLS_DTPMOD32 17
+#define R_ARM_TLS_DTPOFF32 18
+#define R_ARM_TLS_TPOFF32 19
+#define R_ARM_GLOB_DAT 21
+#define R_ARM_JUMP_SLOT 22
+#define R_ARM_RELATIVE 23
+#define R_ARM_IRELATIVE 160
+
+typedef struct lib {
+    char name[128];   /* as requested (basename) */
+    char path[512];
+    uint32_t base;         /* load bias */
+    uint32_t start, size;  /* mapped range */
+    const Elf32_Phdr *phdr;
+    int phnum;
+    Elf32_Dyn *dyn;
+    const Elf32_Sym *symtab;
+    const char *strtab;
+    const uint32_t *hash;      /* DT_HASH */
+    const uint32_t *gnu_hash;  /* DT_GNU_HASH */
+    uint32_t nsyms;
+    uint32_t exidx, exidx_count;
+    struct lib **needed;
+    int nneeded;
+    int refs;
+    int initialised;
+    struct lib *next;
+} lib;
+
+/* "system" libraries: no file, symbols come from the runtime's export table */
+static const char *const SYSTEM_LIBS[] = {
+    "libc.so", "libm.so", "libdl.so", "liblog.so", "libandroid.so", "libstdc++.so", "libz.so", "libEGL.so",
+    "libGLESv1_CM.so", "libGLESv2.so", "libGLESv3.so", "libOpenSLES.so", "libvulkan.so", "libjnigraphics.so",
+    "libaaudio.so", "libmediandk.so", "libnativewindow.so", "libsync.so", "libOpenMAXAL.so", "libcamera2ndk.so",
+    "libamidi.so", "libbinder_ndk.so", "libneuralnetworks.so",
+    "libvrapi.so", /* VrApi 1.x: translated by the host (host/vrapi.c); a game's own copy is the Oculus loader */
+};
+static lib system_lib = {.name = "libc.so", .refs = 1, .initialised = 1};
+
+static lib *libs, *libs_tail;
+static pthread_mutex_t lock = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;
+static __thread char err_buf[512];
+static __thread int err_set;
+static const char *lib_dir = ".";
+
+void loader_set_dir(const char *dir) { lib_dir = dir; }
+
+static void vset_error(int log, const char *fmt, va_list ap)
+{
+    vsnprintf(err_buf, sizeof err_buf, fmt, ap);
+    err_set = 1;
+    if (log) grt_log(5, "a32rt", "%s", err_buf);
+}
+
+static void set_error(const char *fmt, ...)
+{
+    va_list ap;
+    va_start(ap, fmt);
+    vset_error(1, fmt, ap);
+    va_end(ap);
+}
+
+/* failures callers expect (dlsym probes, Mono looking for AOT images "X.dll.so"): not logged */
+static void set_error_quiet(const char *fmt, ...)
+{
+    va_list ap;
+    va_start(ap, fmt);
+    vset_error(0, fmt, ap);
+    va_end(ap);
+}
+
+/* ------------------------------------------------------------------------------------------------ symbols */
+
+static uint32_t elf_hash(const char *n)
+{
+    uint32_t h = 0, g;
+    while (*n) {
+        h = (h << 4) + (uint8_t)*n++;
+        g = h & 0xf0000000u;
+        h ^= g >> 24;
+        h &= ~g;
+    }
+    return h;
+}
+
+static uint32_t gnu_hash(const char *n)
+{
+    uint32_t h = 5381;
+    while (*n) h = h * 33 + (uint8_t)*n++;
+    return h;
+}
+
+static int sym_defined(const Elf32_Sym *s)
+{
+    int bind = ELF32_ST_BIND(s->st_info);
+    return s->st_shndx != SHN_UNDEF && (bind == STB_GLOBAL || bind == STB_WEAK || bind == 10 /* GNU_UNIQUE */);
+}
+
+/* a defined, exported symbol of l, or NULL */
+static const Elf32_Sym *lib_lookup(const lib *l, const char *name)
+{
+    if (l == &system_lib) return NULL;
+    if (l->gnu_hash) {
+        const uint32_t *g = l->gnu_hash;
+        uint32_t nbuckets = g[0], symoffset = g[1], bloom_size = g[2], bloom_shift = g[3];
+        const uint32_t *bloom = g + 4, *buckets = bloom + bloom_size, *chain = buckets + nbuckets;
+        uint32_t h = gnu_hash(name);
+        uint32_t word = bloom[(h / 32) % bloom_size];
+        if (!((word >> (h % 32)) & (word >> ((h >> bloom_shift) % 32)) & 1)) return NULL;
+        uint32_t k = buckets[h % nbuckets];
+        if (k < symoffset) return NULL;
+        for (;; k++) {
+            uint32_t h2 = chain[k - symoffset];
+            if ((h | 1) == (h2 | 1)) {
+                const Elf32_Sym *s = &l->symtab[k];
+                if (sym_defined(s) && !strcmp(l->strtab + s->st_name, name)) return s;
+            }
+            if (h2 & 1) break;
+        }
+        return NULL;
+    }
+    if (l->hash) {
+        uint32_t nbucket = l->hash[0];
+        const uint32_t *bucket = l->hash + 2, *chain = bucket + nbucket;
+        for (uint32_t k = bucket[elf_hash(name) % nbucket]; k; k = chain[k]) {
+            const Elf32_Sym *s = &l->symtab[k];
+            if (sym_defined(s) && !strcmp(l->strtab + s->st_name, name)) return s;
+        }
+    }
+    return NULL;
+}
+
+/* address of name in l (or the runtime's exports for system libraries), 0 if absent */
+static uint32_t lib_sym_addr(const lib *l, const char *name)
+{
+    if (l == &system_lib) return grt_export(name);
+    const Elf32_Sym *s = lib_lookup(l, name);
+    return s ? l->base + s->st_value : 0;
+}
+
+/* bionic's order: the library itself, its DT_NEEDED (breadth first), then everything else that is loaded */
+static uint32_t resolve(const lib *l, const char *name)
+{
+    const lib *q[64];
+    int n = 0, h = 0;
+    q[n++] = l;
+    while (h < n) {
+        const lib *c = q[h++];
+        uint32_t a = lib_sym_addr(c, name);
+        if (a) return a;
+        for (int k = 0; k < c->nneeded && n < 64; k++) {
+            int seen = 0;
+            for (int j = 0; j < n; j++) seen |= q[j] == c->needed[k];
+            if (!seen) q[n++] = c->needed[k];
+        }
+    }
+    for (const lib *c = libs; c; c = c->next) {
+        uint32_t a = lib_sym_addr(c, name);
+        if (a) return a;
+    }
+    return grt_export(name);
+}
+
+/* code that reports the name of an unresolved symbol when called and returns 0: movw/movt r0, name; movw/movt r7;
+ * svc 0; bx lr */
+static uint32_t unresolved_stub(const char *name)
+{
+    static uint32_t *page, used;
+    static pthread_mutex_t m = PTHREAD_MUTEX_INITIALIZER;
+    pthread_mutex_lock(&m);
+    if (!page || used + 6 > 1024) {
+        page = mmap(NULL, 4096, PROT_READ | PROT_WRITE | PROT_EXEC, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
+        used = 0;
+    }
+    uint32_t *p = page + used, a = (uint32_t)(uintptr_t)strdup(name), hc = A32_HYPERCALL | HC_UNRESOLVED;
+    p[0] = 0xe3000000u | ((a & 0xf000) << 4) | (a & 0xfff);                  /* movw r0, #lo */
+    p[1] = 0xe3400000u | ((a >> 12) & 0xf0000) | ((a >> 16) & 0xfff);        /* movt r0, #hi */
+    p[2] = 0xe3007000u | ((hc & 0xf000) << 4) | (hc & 0xfff);                /* movw r7, #lo */
+    p[3] = 0xe3407000u | ((hc >> 12) & 0xf0000) | ((hc >> 16) & 0xfff);      /* movt r7, #hi */
+    p[4] = 0xef000000u;                                                      /* svc 0 */
+    p[5] = 0xe12fff1eu;                                                      /* bx lr */
+    used += 6;
+    __builtin___clear_cache((char *)p, (char *)(p + 6));
+    pthread_mutex_unlock(&m);
+    return (uint32_t)(uintptr_t)p;
+}
+
+/* ------------------------------------------------------------------------------------------------ relocation */
+
+static int reloc_one(lib *l, uint32_t offset, uint32_t info)
+{
+    uint32_t type = ELF32_R_TYPE(info), symi = ELF32_R_SYM(info);
+    uint32_t *where = (uint32_t *)(uintptr_t)(l->base + offset);
+    uint32_t s = 0;
+    if (symi) {
+        const Elf32_Sym *sym = &l->symtab[symi];
+        const char *name = l->strtab + sym->st_name;
+        if (ELF32_ST_BIND(sym->st_info) == STB_LOCAL) {
+            s = l->base + sym->st_value;
+        } else {
+            s = resolve(l, name);
+            if (!s) {
+                if (ELF32_ST_BIND(sym->st_info) == STB_WEAK) {
+                    s = 0;
+                } else if (type == R_ARM_JUMP_SLOT || (ELF32_ST_TYPE(sym->st_info) == STT_FUNC)) {
+                    grt_log(5, "a32rt", "%s: unresolved function %s", l->name, name);
+                    s = unresolved_stub(name);
+                } else if (type == R_ARM_GLOB_DAT || type == R_ARM_ABS32) {
+                    /* untyped (functions referenced through the GOT): report when called */
+                    grt_log(5, "a32rt", "%s: unresolved symbol %s", l->name, name);
+                    s = unresolved_stub(name);
+                } else {
+                    set_error("%s: cannot resolve %s", l->name, name);
+                    return -1;
+                }
+            }
+        }
+    }
+    switch (type) {
+    case R_ARM_NONE: break;
+    case R_ARM_ABS32: *where += s; break;
+    case R_ARM_REL32: *where += s - (uint32_t)(uintptr_t)where; break;
+    case R_ARM_GLOB_DAT:
+    case R_ARM_JUMP_SLOT: *where = s; break;
+    case R_ARM_RELATIVE: *where += l->base; break;
+    case R_ARM_IRELATIVE: *where = ((uint32_t (*)(void))(uintptr_t)(l->base + *where))(); break;
+    case R_ARM_TLS_DTPMOD32:
+    case R_ARM_TLS_DTPOFF32:
+    case R_ARM_TLS_TPOFF32:
+        set_error("%s: ELF TLS relocations are not supported yet (type %u)", l->name, type);
+        return -1;
+    default:
+        set_error("%s: unsupported relocation type %u", l->name, type);
+        return -1;
+    }
+    return 0;
+}
+
+static int reloc_rel(lib *l, uint32_t addr, uint32_t size)
+{
+    const Elf32_Rel *r = (const Elf32_Rel *)(uintptr_t)(l->base + addr);
+    for (uint32_t k = 0; k < size / sizeof *r; k++)
+        if (reloc_one(l, r[k].r_offset, r[k].r_info)) return -1;
+    return 0;
+}
+
+static int32_t sleb(const uint8_t **p)
+{
+    int32_t v = 0;
+    int shift = 0;
+    uint8_t b;
+    do {
+        b = *(*p)++;
+        v |= (int32_t)(b & 0x7f) << shift;
+        shift += 7;
+    } while (b & 0x80);
+    if (shift < 32 && (b & 0x40)) v |= -(1 << shift);
+    return v;
+}
+
+/* Android's packed relocations ("APS2", bionic linker_reloc_iterators.h) */
+static int reloc_android(lib *l, uint32_t addr, uint32_t size)
+{
+    const uint8_t *p = (const uint8_t *)(uintptr_t)(l->base + addr);
+    if (size < 4 || memcmp(p, "APS2", 4)) {
+        set_error("%s: unknown packed relocation format", l->name);
+        return -1;
+    }
+    p += 4;
+    int32_t count = sleb(&p);
+    uint32_t offset = (uint32_t)sleb(&p), info = 0;
+    while (count > 0) {
+        int32_t gsize = sleb(&p), flags = sleb(&p), delta = 0;
+        if (flags & 2) delta = sleb(&p);
+        if (flags & 1) info = (uint32_t)sleb(&p);
+        if (flags & 8) {
+            set_error("%s: packed relocations with addends on a REL target", l->name);
+            return -1;
+        }
+        for (int32_t k = 0; k < gsize; k++) {
+            offset += (flags & 2) ? (uint32_t)delta : (uint32_t)sleb(&p);
+            if (!(flags & 1)) info = (uint32_t)sleb(&p);
+            if (reloc_one(l, offset, info)) return -1;
+        }
+        count -= gsize;
+    }
+    return 0;
+}
+
+static void reloc_relr(lib *l, uint32_t addr, uint32_t size)
+{
+    const uint32_t *r = (const uint32_t *)(uintptr_t)(l->base + addr);
+    uint32_t *where = NULL;
+    for (uint32_t k = 0; k < size / 4; k++) {
+        uint32_t e = r[k];
+        if (!(e & 1)) {
+            where = (uint32_t *)(uintptr_t)(l->base + e);
+            *where++ += l->base;
+        } else {
+            for (uint32_t j = 0; (e >>= 1) != 0; j++)
+                if (e & 1) where[j] += l->base;
+            where += 31;
+        }
+    }
+}
+
+/* ------------------------------------------------------------------------------------------------ loading */
+
+static lib *load_lib(const char *name);
+
+static int is_system(const char *base)
+{
+    for (size_t k = 0; k < sizeof SYSTEM_LIBS / sizeof *SYSTEM_LIBS; k++)
+        if (!strcmp(base, SYSTEM_LIBS[k])) return 1;
+    return 0;
+}
+
+static const char *basename_of(const char *p)
+{
+    const char *s = strrchr(p, '/');
+    return s ? s + 1 : p;
+}
+
+/* The guest copy of libX.so is stored as libX.a32.so next to the host libraries (the package manager extracts
+ * lib*.so files only, and libX.so itself is the host stub). */
+static int open_lib(const char *name, char *path, size_t n)
+{
+    int fd;
+    size_t len = strlen(name);
+    if (strchr(name, '/')) {
+        /* a path into the app's library folder names the host stub: its guest code is next to it */
+        if (len > 3 && !strcmp(name + len - 3, ".so")) {
+            snprintf(path, n, "%.*s.a32.so", (int)(len - 3), name);
+            if ((fd = open(path, O_RDONLY | O_CLOEXEC)) >= 0) return fd;
+        }
+        snprintf(path, n, "%s", name);
+        if ((fd = open(path, O_RDONLY | O_CLOEXEC)) >= 0) return fd;
+        name = basename_of(name);
+        len = strlen(name);
+    }
+    if (len > 3 && !strcmp(name + len - 3, ".so")) {
+        snprintf(path, n, "%s/%.*s.a32.so", lib_dir, (int)(len - 3), name);
+        if ((fd = open(path, O_RDONLY | O_CLOEXEC)) >= 0) return fd;
+    }
+    snprintf(path, n, "%s/%s", lib_dir, name);
+    return open(path, O_RDONLY | O_CLOEXEC);
+}
+
+static int map_lib(lib *l, int fd)
+{
+    Elf32_Ehdr eh;
+    if (pread(fd, &eh, sizeof eh, 0) != sizeof eh || memcmp(eh.e_ident, ELFMAG, SELFMAG) ||
+        eh.e_ident[EI_CLASS] != ELFCLASS32 || eh.e_machine != EM_ARM || eh.e_type != ET_DYN || eh.e_phnum > 64) {
+        set_error("%s: not a 32-bit ARM shared library", l->path);
+        return -1;
+    }
+    Elf32_Phdr ph[64];
+    if (pread(fd, ph, eh.e_phnum * sizeof *ph, eh.e_phoff) != (ssize_t)(eh.e_phnum * sizeof *ph)) return -1;
+    uint32_t lo = 0xffffffffu, hi = 0;
+    for (int k = 0; k < eh.e_phnum; k++)
+        if (ph[k].p_type == PT_LOAD) {
+            if (ph[k].p_vaddr < lo) lo = ph[k].p_vaddr;
+            if (ph[k].p_vaddr + ph[k].p_memsz > hi) hi = ph[k].p_vaddr + ph[k].p_memsz;
+        }
+    lo &= ~4095u;
+    hi = (hi + 4095) & ~4095u;
+    void *res = mmap(NULL, hi - lo, PROT_NONE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
+    if (res == MAP_FAILED) {
+        set_error("%s: no room for %u bytes", l->path, hi - lo);
+        return -1;
+    }
+    l->start = (uint32_t)(uintptr_t)res;
+    l->base = l->start - lo;
+    l->size = hi - lo;
+    for (int k = 0; k < eh.e_phnum; k++) {
+        const Elf32_Phdr *p = &ph[k];
+        if (p->p_type == PT_DYNAMIC) l->dyn = (Elf32_Dyn *)(uintptr_t)(l->base + p->p_vaddr);
+        if (p->p_type == PT_ARM_EXIDX) {
+            l->exidx = l->base + p->p_vaddr;
+            l->exidx_count = p->p_memsz / 8;
+        }
+        if (p->p_type != PT_LOAD || !p->p_memsz) continue;
+        uint32_t va = l->base + p->p_vaddr, start = va & ~4095u;
+        uint32_t fend = va + p->p_filesz, mend = va + p->p_memsz, fpend = (fend + 4095) & ~4095u;
+        /* writable while relocating; final protections are applied afterwards */
+        if (p->p_filesz) {
+            void *m = mmap((void *)(uintptr_t)start, fpend - start, PROT_READ | PROT_WRITE | PROT_EXEC,
+                           MAP_PRIVATE | MAP_FIXED, fd, p->p_offset - (va - start));
+            if (m == MAP_FAILED) {
+                set_error("%s: mapping a segment failed (%s)", l->path, strerror(errno));
+                return -1;
+            }
+            if (mend > fend && fpend > fend) memset((void *)(uintptr_t)fend, 0, fpend - fend);
+        } else {
+            fpend = start;
+        }
+        uint32_t mpend = (mend + 4095) & ~4095u;
+        if (mpend > fpend &&
+            mmap((void *)(uintptr_t)fpend, mpend - fpend, PROT_READ | PROT_WRITE | PROT_EXEC,
+                 MAP_PRIVATE | MAP_ANONYMOUS | MAP_FIXED, -1, 0) == MAP_FAILED) {
+            set_error("%s: mapping .bss failed", l->path);
+            return -1;
+        }
+        if (!l->phdr && eh.e_phoff >= p->p_offset && eh.e_phoff < p->p_offset + p->p_filesz)
+            l->phdr = (const Elf32_Phdr *)(uintptr_t)(va + (eh.e_phoff - p->p_offset));
+    }
+    l->phnum = eh.e_phnum;
+    if (!l->dyn) {
+        set_error("%s: no dynamic section", l->path);
+        return -1;
+    }
+    return 0;
+}
+
+static void protect_lib(lib *l)
+{
+    for (int k = 0; k < l->phnum; k++) {
+        const Elf32_Phdr *p = &l->phdr[k];
+        if (p->p_type != PT_LOAD || !p->p_memsz) continue;
+        int prot = (p->p_flags & PF_R ? PROT_READ : 0) | (p->p_flags & PF_W ? PROT_WRITE : 0) |
+                   (p->p_flags & PF_X ? PROT_EXEC : 0);
+        uint32_t s = (l->base + p->p_vaddr) & ~4095u, e = (l->base + p->p_vaddr + p->p_memsz + 4095) & ~4095u;
+        mprotect((void *)(uintptr_t)s, e - s, prot);
+    }
+    for (int k = 0; k < l->phnum; k++) {
+        const Elf32_Phdr *p = &l->phdr[k];
+        if (p->p_type != PT_GNU_RELRO) continue;
+        uint32_t s = (l->base + p->p_vaddr) & ~4095u, e = (l->base + p->p_vaddr + p->p_memsz) & ~4095u;
+        if (e > s) mprotect((void *)(uintptr_t)s, e - s, PROT_READ);
+    }
+}
+
+static void init_lib(lib *l)
+{
+    if (l->initialised) return;
+    l->initialised = 1;
+    for (int k = 0; k < l->nneeded; k++) init_lib(l->needed[k]);
+    uint32_t init = 0, arr = 0, arrsz = 0;
+    for (Elf32_Dyn *d = l->dyn; d->d_tag != DT_NULL; d++) {
+        if (d->d_tag == DT_INIT) init = l->base + d->d_un.d_ptr;
+        else if (d->d_tag == DT_INIT_ARRAY) arr = l->base + d->d_un.d_ptr;
+        else if (d->d_tag == DT_INIT_ARRAYSZ) arrsz = d->d_un.d_val;
+    }
+    extern char **environ;
+    if (init) ((void (*)(int, char **, char **))(uintptr_t)init)(0, NULL, environ);
+    for (uint32_t k = 0; k < arrsz / 4; k++) {
+        uint32_t f = ((uint32_t *)(uintptr_t)arr)[k];
+        if (f && f != 0xffffffffu) ((void (*)(int, char **, char **))(uintptr_t)f)(0, NULL, environ);
+    }
+}
+
+static lib *find_loaded(const char *base)
+{
+    for (lib *l = libs; l; l = l->next)
+        if (!strcmp(l->name, base)) return l;
+    return NULL;
+}
+
+static lib *load_lib(const char *name)
+{
+    const char *base = basename_of(name);
+    lib *l = find_loaded(base);
+    if (l) {
+        l->refs++;
+        return l;
+    }
+    /* VrApi is always the runtime's: lib/ may hold a host libvrapi.so of that name (the app's Java side loads one) */
+    if (!strcmp(base, "libvrapi.so")) return &system_lib;
+    char path[512];
+    int fd = open_lib(name, path, sizeof path);
+    if (fd < 0) {
+        if (is_system(base)) return &system_lib;
+        size_t nl = strlen(name);
+        if (nl > 7 && !strcmp(name + nl - 7, ".dll.so")) set_error_quiet("dlopen failed: library \"%s\" not found", name);
+        else set_error("dlopen failed: library \"%s\" not found", name);
+        return NULL;
+    }
+    l = calloc(1, sizeof *l);
+    snprintf(l->name, sizeof l->name, "%s", base);
+    snprintf(l->path, sizeof l->path, "%s", path);
+    l->refs = 1;
+    int r = map_lib(l, fd);
+    close(fd);
+    if (r) {
+        free(l);
+        return NULL;
+    }
+    uint32_t rel = 0, relsz = 0, jmprel = 0, jmprelsz = 0, arel = 0, arelsz = 0, relr = 0, relrsz = 0;
+    int nneeded = 0;
+    for (Elf32_Dyn *d = l->dyn; d->d_tag != DT_NULL; d++) {
+        uint32_t v = d->d_un.d_val;
+        switch (d->d_tag) {
+        case DT_SYMTAB: l->symtab = (const Elf32_Sym *)(uintptr_t)(l->base + v); break;
+        case DT_STRTAB: l->strtab = (const char *)(uintptr_t)(l->base + v); break;
+        case DT_HASH: l->hash = (const uint32_t *)(uintptr_t)(l->base + v); break;
+        case DT_GNU_HASH: l->gnu_hash = (const uint32_t *)(uintptr_t)(l->base + v); break;
+        case DT_REL: rel = v; break;
+        case DT_RELSZ: relsz = v; break;
+        case DT_JMPREL: jmprel = v; break;
+        case DT_PLTRELSZ: jmprelsz = v; break;
+        case DT_ANDROID_REL: arel = v; break;
+        case DT_ANDROID_RELSZ: arelsz = v; break;
+        case DT_ANDROID_RELR:
+        case DT_RELR_: relr = v; break;
+        case DT_ANDROID_RELRSZ:
+        case DT_RELRSZ_: relrsz = v; break;
+        case DT_NEEDED: nneeded++; break;
+        case DT_RELA: set_error("%s: RELA relocations on ARM32?", l->name); return NULL;
+        }
+    }
+    if (l->hash) l->nsyms = l->hash[1];
+    /* published before its dependencies load: a cycle finds it instead of loading it twice */
+    if (libs_tail) libs_tail->next = l;
+    else libs = l;
+    libs_tail = l;
+    l->needed = calloc(nneeded ? nneeded : 1, sizeof *l->needed);
+    for (Elf32_Dyn *d = l->dyn; d->d_tag != DT_NULL; d++) {
+        if (d->d_tag != DT_NEEDED) continue;
+        const char *dep = l->strtab + d->d_un.d_val;
+        lib *dl = load_lib(dep);
+        if (!dl) {
+            grt_log(5, "a32rt", "%s: needed library %s missing (%s)", l->name, dep, err_buf);
+            continue;
+        }
+        l->needed[l->nneeded++] = dl;
+    }
+    if ((relr && relrsz && (reloc_relr(l, relr, relrsz), 0)) || (arel && reloc_android(l, arel, arelsz)) ||
+        (rel && reloc_rel(l, rel, relsz)) || (jmprel && reloc_rel(l, jmprel, jmprelsz))) {
+        grt_log(6, "a32rt", "%s: relocation failed: %s", l->name, err_buf);
+        return NULL;
+    }
+    protect_lib(l);
+    grt_log(4, "a32rt", "loaded %s at 0x%08x (%u KiB)", l->path, l->start, l->size / 1024);
+    return l;
+}
+
+/* ------------------------------------------------------------------------------------------------ dl* API */
+
+void *grt_dlopen(const char *name, int flags)
+{
+    (void)flags;
+    if (!name) return &system_lib; /* the "main program": global lookup */
+    pthread_mutex_lock(&lock);
+    lib *l = load_lib(name);
+    if (l) init_lib(l);
+    pthread_mutex_unlock(&lock);
+    return l;
+}
+
+void *grt_dlsym(void *handle, const char *name)
+{
+    uint32_t a = 0;
+    pthread_mutex_lock(&lock);
+    if (handle == RTLD_DEFAULT || handle == RTLD_NEXT || handle == &system_lib) {
+        for (lib *l = libs; l && !a; l = l->next) a = lib_sym_addr(l, name);
+        if (!a) a = grt_export(name);
+    } else {
+        a = resolve(handle, name);
+    }
+    pthread_mutex_unlock(&lock);
+    if (!a) set_error_quiet("undefined symbol: %s", name);
+    return (void *)(uintptr_t)a;
+}
+
+int grt_dlclose(void *handle)
+{
+    (void)handle; /* libraries stay loaded (as bionic does for most of them) */
+    return 0;
+}
+
+char *grt_dlerror(void)
+{
+    if (!err_set) return NULL;
+    err_set = 0;
+    return err_buf;
+}
+
+static lib *lib_at(uint32_t a)
+{
+    for (lib *l = libs; l; l = l->next)
+        if (a >= l->start && a - l->start < l->size) return l;
+    return NULL;
+}
+
+/* number of entries in l's dynamic symbol table */
+static uint32_t lib_nsyms(const lib *l)
+{
+    uint32_t n = l->nsyms;
+    if (!n && l->gnu_hash) {
+        /* the highest symbol index in the GNU hash chains */
+        const uint32_t *g = l->gnu_hash;
+        uint32_t nb = g[0], so = g[1], bs = g[2];
+        const uint32_t *b = g + 4 + bs, *ch = b + nb;
+        for (uint32_t k = 0; k < nb; k++)
+            if (b[k] >= n) n = b[k];
+        if (n >= so)
+            while (!(ch[n - so] & 1)) n++;
+        n++;
+    }
+    return n;
+}
+
+/* The defined symbols of a library whose names start with prefix: a malloc'd array of (name, address) pairs,
+ * ended by a 0 name. For the host bridge (Java_* functions). */
+uint32_t *grt_list_symbols(void *handle, const char *prefix)
+{
+    lib *l = handle;
+    size_t plen = strlen(prefix), n = 0, cap = 16;
+    uint32_t *v = malloc(cap * 8);
+    pthread_mutex_lock(&lock);
+    if (l && l != &system_lib) {
+        uint32_t ns = lib_nsyms(l);
+        for (uint32_t k = 1; k < ns; k++) {
+            const Elf32_Sym *s = &l->symtab[k];
+            const char *nm = l->strtab + s->st_name;
+            if (!sym_defined(s) || strncmp(nm, prefix, plen)) continue;
+            if (n + 2 > cap) v = realloc(v, (cap *= 2) * 8);
+            v[2 * n] = (uint32_t)(uintptr_t)nm;
+            v[2 * n + 1] = l->base + s->st_value;
+            n++;
+        }
+    }
+    pthread_mutex_unlock(&lock);
+    v[2 * n] = v[2 * n + 1] = 0;
+    return v;
+}
+
+int grt_dladdr(const void *addr, Dl_info *info)
+{
+    uint32_t a = (uint32_t)(uintptr_t)addr;
+    pthread_mutex_lock(&lock);
+    lib *l = lib_at(a);
+    if (!l) {
+        pthread_mutex_unlock(&lock);
+        return 0;
+    }
+    info->dli_fname = l->path;
+    info->dli_fbase = (void *)(uintptr_t)l->base;
+    info->dli_sname = NULL;
+    info->dli_saddr = NULL;
+    uint32_t best = 0;
+    uint32_t n = lib_nsyms(l);
+    for (uint32_t k = 1; k < n; k++) {
+        const Elf32_Sym *s = &l->symtab[k];
+        if (!sym_defined(s) || !s->st_value) continue;
+        uint32_t sa = l->base + s->st_value;
+        if (sa <= a && sa > best && (a - sa < s->st_size || !s->st_size)) {
+            best = sa;
+            info->dli_sname = l->strtab + s->st_name;
+            info->dli_saddr = (void *)(uintptr_t)sa;
+        }
+    }
+    pthread_mutex_unlock(&lock);
+    return 1;
+}
+
+int dl_iterate_phdr(int (*cb)(struct dl_phdr_info *, size_t, void *), void *data)
+{
+    int r = 0;
+    for (lib *l = libs; l && !r; l = l->next) {
+        struct dl_phdr_info i;
+        memset(&i, 0, sizeof i);
+        i.dlpi_addr = l->base;
+        i.dlpi_name = l->path;
+        i.dlpi_phdr = l->phdr;
+        i.dlpi_phnum = (Elf32_Half)l->phnum;
+        r = cb(&i, sizeof i, data);
+    }
+    return r;
+}
+
+/* libc.a has its own dl_unwind_find_exidx, which only knows the runtime itself: the link wraps it (--wrap), so
+ * the runtime's unwinder sees guest libraries too */
+uint32_t __real_dl_unwind_find_exidx(uint32_t pc, int *count);
+
+uint32_t __wrap_dl_unwind_find_exidx(uint32_t pc, int *count)
+{
+    lib *l = lib_at(pc);
+    if (!l) return __real_dl_unwind_find_exidx(pc, count);
+    if (!l->exidx) {
+        *count = 0;
+        return 0;
+    }
+    *count = (int)l->exidx_count;
+    return l->exidx;
+}
+
+/* the "(see bionic)" variants */
+void *grt_android_dlopen_ext(const char *name, int flags, const void *extinfo)
+{
+    (void)extinfo;
+    return grt_dlopen(name, flags);
+}
+
+void *grt_dlvsym(void *handle, const char *name, const char *version)
+{
+    (void)version;
+    return grt_dlsym(handle, name);
+}
@@ -0,0 +1,65 @@
+/* liblog for guest libraries: formatted here, written by the host's liblog. */
+#include <android/log.h>
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include "grt.h"
+
+int __android_log_write(int prio, const char *tag, const char *msg)
+{
+    grt_hc(HC_LOG, (uint32_t)prio, (uint32_t)(uintptr_t)(tag ? tag : ""), (uint32_t)(uintptr_t)(msg ? msg : ""), 0);
+    return 1;
+}
+
+int __android_log_vprint(int prio, const char *tag, const char *fmt, va_list ap)
+{
+    char buf[1024];
+    vsnprintf(buf, sizeof buf, fmt, ap);
+    return __android_log_write(prio, tag, buf);
+}
+
+int __android_log_print(int prio, const char *tag, const char *fmt, ...)
+{
+    va_list ap;
+    va_start(ap, fmt);
+    int r = __android_log_vprint(prio, tag, fmt, ap);
+    va_end(ap);
+    return r;
+}
+
+int __android_log_buf_write(int buf, int prio, const char *tag, const char *msg)
+{
+    (void)buf;
+    return __android_log_write(prio, tag, msg);
+}
+
+int __android_log_buf_print(int buf, int prio, const char *tag, const char *fmt, ...)
+{
+    (void)buf;
+    va_list ap;
+    va_start(ap, fmt);
+    int r = __android_log_vprint(prio, tag, fmt, ap);
+    va_end(ap);
+    return r;
+}
+
+void __android_log_assert(const char *cond, const char *tag, const char *fmt, ...)
+{
+    char buf[1024];
+    if (fmt) {
+        va_list ap;
+        va_start(ap, fmt);
+        vsnprintf(buf, sizeof buf, fmt, ap);
+        va_end(ap);
+    } else {
+        snprintf(buf, sizeof buf, "assertion failed: %s", cond ? cond : "");
+    }
+    __android_log_write(ANDROID_LOG_FATAL, tag, buf);
+    abort();
+}
+
+int __android_log_is_loggable(int prio, const char *tag, int def)
+{
+    (void)tag;
+    return prio >= def;
+}
@@ -0,0 +1,83 @@
+/* Runtime entry: started by the host bridge as `liba32rt.so <library dir>`. Starts the service thread, reports
+ * the addresses the host needs (HC_READY) and parks; from then on the host calls guest functions directly. */
+#include <pthread.h>
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "grt.h"
+
+extern const uint32_t grt_export_table[]; /* gen/exports.S: (name, address) pairs sorted by name */
+extern const uint32_t grt_export_count;
+extern const uint32_t grt_jni_env, grt_java_vm; /* gen/stubs.S */
+
+uint32_t grt_export(const char *name)
+{
+    uint32_t lo = 0, hi = grt_export_count;
+    while (lo < hi) {
+        uint32_t mid = (lo + hi) / 2;
+        int c = strcmp(name, (const char *)(uintptr_t)grt_export_table[2 * mid]);
+        if (!c) return grt_export_table[2 * mid + 1];
+        if (c < 0) hi = mid;
+        else lo = mid + 1;
+    }
+    return 0;
+}
+
+void grt_log(int prio, const char *tag, const char *fmt, ...)
+{
+    char msg[1024];
+    va_list ap;
+    va_start(ap, fmt);
+    vsnprintf(msg, sizeof msg, fmt, ap);
+    va_end(ap);
+    grt_hc(HC_LOG, (uint32_t)prio, (uint32_t)(uintptr_t)tag, (uint32_t)(uintptr_t)msg, 0);
+}
+
+/* a host thread adopted this guest thread (WORK_ATTACH): it only ever runs host-to-guest calls */
+static void *attached_entry(void *arg)
+{
+    (void)arg;
+    for (;;) grt_hc(HC_RETURN, 0, 0, 0, 0);
+    return NULL;
+}
+
+static void *service(void *arg)
+{
+    (void)arg;
+    pthread_attr_t attr;
+    pthread_attr_init(&attr);
+    pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
+    for (;;) {
+        uint32_t w = grt_hc(HC_WAIT_WORK, 0, 0, 0, 0);
+        if (w == WORK_ATTACH) {
+            pthread_t t;
+            int e = pthread_create(&t, &attr, attached_entry, NULL);
+            if (e) grt_log(6, "a32rt", "attach: pthread_create failed (%d)", e);
+        }
+    }
+    return NULL;
+}
+
+int main(int argc, char **argv)
+{
+    if (argc > 1) loader_set_dir(argv[1]);
+    pthread_t svc;
+    if (pthread_create(&svc, NULL, service, NULL)) {
+        grt_hc(HC_ABORT, (uint32_t)(uintptr_t)"cannot start the service thread", 0, 0, 0);
+        return 1;
+    }
+    static struct grt_info info;
+    info.version = A32B_VERSION;
+    info.jni_env = (uint32_t)(uintptr_t)&grt_jni_env;
+    info.java_vm = (uint32_t)(uintptr_t)&grt_java_vm;
+    info.fn_malloc = (uint32_t)(uintptr_t)malloc;
+    info.fn_free = (uint32_t)(uintptr_t)free;
+    info.fn_dlopen = (uint32_t)(uintptr_t)grt_dlopen;
+    info.fn_dlsym = (uint32_t)(uintptr_t)grt_dlsym;
+    info.fn_dlerror = (uint32_t)(uintptr_t)grt_dlerror;
+    info.fn_attached_entry = (uint32_t)(uintptr_t)attached_entry;
+    info.fn_list_symbols = (uint32_t)(uintptr_t)grt_list_symbols;
+    grt_hc(HC_READY, (uint32_t)(uintptr_t)&info, 0, 0, 0);
+    for (;;) grt_hc(HC_RETURN, 0, 0, 0, 0);
+}
@@ -0,0 +1,455 @@
+/* OpenSL ES for guest code: the part audio engines use for output (an engine, an output mix and PCM audio players
+ * fed by an Android simple buffer queue), implemented here in the guest and played through the host's AAudio
+ * (a32_audio_*, host/android.c). OpenSL's objects are tables of function pointers, so keeping them on the guest side
+ * needs no thunks; each playing player has a guest thread that writes its queued buffers (blocking, which paces the
+ * queue like a real device) and calls the buffer-queue callback. Recording and everything else report "not
+ * supported". */
+#include <SLES/OpenSLES.h>
+#include <SLES/OpenSLES_Android.h>
+#include <pthread.h>
+#include <stddef.h>
+#include <stdlib.h>
+#include <string.h>
+#include "grt.h"
+
+/* host/android.c (imports.txt) */
+uint32_t a32_audio_open(int rate, int channels, int bits);
+int a32_audio_write(uint32_t stream, const void *data, int frames);
+void a32_audio_start(uint32_t stream);
+void a32_audio_pause(uint32_t stream);
+void a32_audio_close(uint32_t stream);
+
+/* interface IDs: only their addresses matter (callers pass ours back) */
+static const struct SLInterfaceID_ ids[] = {
+    {0xc7b1b6a0, 0, 0, 0, {0}}, {1, 0, 0, 0, {0}}, {2, 0, 0, 0, {0}}, {3, 0, 0, 0, {0}}, {4, 0, 0, 0, {0}},
+    {5, 0, 0, 0, {0}},          {6, 0, 0, 0, {0}}, {7, 0, 0, 0, {0}}, {8, 0, 0, 0, {0}}, {9, 0, 0, 0, {0}},
+};
+const SLInterfaceID SL_IID_NULL = &ids[0];
+const SLInterfaceID SL_IID_OBJECT = &ids[1];
+const SLInterfaceID SL_IID_ENGINE = &ids[2];
+const SLInterfaceID SL_IID_PLAY = &ids[3];
+const SLInterfaceID SL_IID_BUFFERQUEUE = &ids[4];
+const SLInterfaceID SL_IID_ANDROIDSIMPLEBUFFERQUEUE = &ids[5];
+const SLInterfaceID SL_IID_VOLUME = &ids[6];
+const SLInterfaceID SL_IID_ANDROIDCONFIGURATION = &ids[7];
+const SLInterfaceID SL_IID_RECORD = &ids[8];
+const SLInterfaceID SL_IID_OUTPUTMIX = &ids[9];
+
+enum { K_ENGINE, K_MIX, K_PLAYER };
+#define QMAX 64
+
+typedef struct obj {
+    const struct SLObjectItf_ *object;
+    const struct SLEngineItf_ *engine;
+    const struct SLPlayItf_ *play;
+    const struct SLAndroidSimpleBufferQueueItf_ *queue;
+    const struct SLVolumeItf_ *volume;
+    const struct SLAndroidConfigurationItf_ *config;
+    int kind;
+    SLuint32 state;
+    /* player */
+    int rate, channels, bits;
+    SLuint32 play_state;
+    slAndroidSimpleBufferQueueCallback qcb;
+    void *qctx;
+    slPlayCallback pcb;
+    void *pctx;
+    SLuint32 pmask;
+    struct { const void *data; SLuint32 size; } q[QMAX];
+    SLuint32 qhead, qcount, qindex;
+    SLmillibel level;
+    SLboolean mute;
+    uint32_t stream;
+    uint64_t frames_played;
+    pthread_t thread;
+    int quit, has_thread;
+    pthread_mutex_t lock;
+    pthread_cond_t cond;
+} obj;
+
+#define OBJ(self, field) ((obj *)((char *)(self) - offsetof(obj, field)))
+
+/* ---------------------------------------------------------------- the player thread */
+
+static void *player_thread(void *arg)
+{
+    obj *o = arg;
+    pthread_mutex_lock(&o->lock);
+    for (;;) {
+        while (!o->quit && (o->play_state != SL_PLAYSTATE_PLAYING || !o->qcount)) pthread_cond_wait(&o->cond, &o->lock);
+        if (o->quit) break;
+        const void *data = o->q[o->qhead].data;
+        SLuint32 size = o->q[o->qhead].size;
+        pthread_mutex_unlock(&o->lock);
+        int frame = o->channels * o->bits / 8;
+        if (o->stream && frame) a32_audio_write(o->stream, data, (int)(size / (SLuint32)frame));
+        pthread_mutex_lock(&o->lock);
+        if (o->qcount && o->q[o->qhead].data == data) { /* not cleared meanwhile */
+            o->qhead = (o->qhead + 1) % QMAX;
+            o->qcount--;
+            o->qindex++;
+            o->frames_played += frame ? size / (SLuint32)frame : 0;
+            slAndroidSimpleBufferQueueCallback cb = o->qcb;
+            void *ctx = o->qctx;
+            pthread_mutex_unlock(&o->lock);
+            if (cb) cb((SLAndroidSimpleBufferQueueItf)&o->queue, ctx);
+            pthread_mutex_lock(&o->lock);
+        }
+    }
+    pthread_mutex_unlock(&o->lock);
+    return NULL;
+}
+
+/* ---------------------------------------------------------------- SLObjectItf */
+
+static SLresult obj_realize(SLObjectItf self, SLboolean async)
+{
+    obj *o = OBJ(self, object);
+    if (o->kind == K_PLAYER && !o->stream) {
+        o->stream = a32_audio_open(o->rate, o->channels, o->bits);
+        if (!o->stream) return SL_RESULT_RESOURCE_ERROR;
+        o->has_thread = !pthread_create(&o->thread, NULL, player_thread, o);
+    }
+    o->state = SL_OBJECT_STATE_REALIZED;
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult obj_resume(SLObjectItf self, SLboolean async) { return SL_RESULT_SUCCESS; }
+
+static SLresult obj_get_state(SLObjectItf self, SLuint32 *state)
+{
+    *state = OBJ(self, object)->state;
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult obj_get_interface(SLObjectItf self, const SLInterfaceID iid, void *out)
+{
+    obj *o = OBJ(self, object);
+    void **p = out;
+    if (iid == SL_IID_OBJECT) *p = &o->object;
+    else if (iid == SL_IID_ENGINE && o->kind == K_ENGINE) *p = &o->engine;
+    else if (iid == SL_IID_PLAY && o->kind == K_PLAYER) *p = &o->play;
+    else if ((iid == SL_IID_ANDROIDSIMPLEBUFFERQUEUE || iid == SL_IID_BUFFERQUEUE) && o->kind == K_PLAYER) *p = &o->queue;
+    else if (iid == SL_IID_VOLUME && o->kind == K_PLAYER) *p = &o->volume;
+    else if (iid == SL_IID_ANDROIDCONFIGURATION && o->kind == K_PLAYER) *p = &o->config;
+    else return SL_RESULT_FEATURE_UNSUPPORTED;
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult obj_register_callback(SLObjectItf self, slObjectCallback cb, void *ctx) { return SL_RESULT_SUCCESS; }
+static void obj_abort(SLObjectItf self) {}
+
+static void obj_destroy(SLObjectItf self)
+{
+    obj *o = OBJ(self, object);
+    if (o->kind == K_PLAYER) {
+        pthread_mutex_lock(&o->lock);
+        o->quit = 1;
+        pthread_cond_broadcast(&o->cond);
+        pthread_mutex_unlock(&o->lock);
+        if (o->has_thread) pthread_join(o->thread, NULL);
+        if (o->stream) a32_audio_close(o->stream);
+    }
+    pthread_mutex_destroy(&o->lock);
+    pthread_cond_destroy(&o->cond);
+    free(o);
+}
+
+static SLresult obj_set_priority(SLObjectItf self, SLint32 p, SLboolean pre) { return SL_RESULT_SUCCESS; }
+static SLresult obj_get_priority(SLObjectItf self, SLint32 *p, SLboolean *pre)
+{
+    *p = 0, *pre = SL_BOOLEAN_FALSE;
+    return SL_RESULT_SUCCESS;
+}
+static SLresult obj_set_loss(SLObjectItf self, SLint16 n, SLInterfaceID *ids_, SLboolean enabled)
+{
+    return SL_RESULT_SUCCESS;
+}
+
+static const struct SLObjectItf_ object_itf = {obj_realize, obj_resume, obj_get_state, obj_get_interface,
+                                               obj_register_callback, obj_abort, obj_destroy, obj_set_priority,
+                                               obj_get_priority, obj_set_loss};
+
+/* ---------------------------------------------------------------- SLPlayItf */
+
+static SLresult play_set_state(SLPlayItf self, SLuint32 state)
+{
+    obj *o = OBJ(self, play);
+    pthread_mutex_lock(&o->lock);
+    SLuint32 old = o->play_state;
+    o->play_state = state;
+    if (state == SL_PLAYSTATE_STOPPED) { /* stopping drops the queue */
+        o->qcount = 0;
+        o->frames_played = 0;
+    }
+    pthread_cond_broadcast(&o->cond);
+    pthread_mutex_unlock(&o->lock);
+    if (o->stream && old != state) {
+        if (state == SL_PLAYSTATE_PLAYING) a32_audio_start(o->stream);
+        else a32_audio_pause(o->stream);
+    }
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult play_get_state(SLPlayItf self, SLuint32 *state)
+{
+    *state = OBJ(self, play)->play_state;
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult play_get_duration(SLPlayItf self, SLmillisecond *ms)
+{
+    *ms = SL_TIME_UNKNOWN;
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult play_get_position(SLPlayItf self, SLmillisecond *ms)
+{
+    obj *o = OBJ(self, play);
+    *ms = o->rate ? (SLmillisecond)(o->frames_played * 1000 / (uint64_t)o->rate) : 0;
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult play_register_callback(SLPlayItf self, slPlayCallback cb, void *ctx)
+{
+    obj *o = OBJ(self, play);
+    o->pcb = cb, o->pctx = ctx;
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult play_set_mask(SLPlayItf self, SLuint32 mask)
+{
+    OBJ(self, play)->pmask = mask;
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult play_get_mask(SLPlayItf self, SLuint32 *mask)
+{
+    *mask = OBJ(self, play)->pmask;
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult play_set_ms(SLPlayItf self, SLmillisecond ms) { return SL_RESULT_SUCCESS; }
+static SLresult play_clear(SLPlayItf self) { return SL_RESULT_SUCCESS; }
+static SLresult play_get_ms(SLPlayItf self, SLmillisecond *ms)
+{
+    *ms = 0;
+    return SL_RESULT_SUCCESS;
+}
+
+static const struct SLPlayItf_ play_itf = {play_set_state, play_get_state, play_get_duration, play_get_position,
+                                           play_register_callback, play_set_mask, play_get_mask, play_set_ms,
+                                           play_clear, play_get_ms, play_set_ms, play_get_ms};
+
+/* ---------------------------------------------------------------- SLAndroidSimpleBufferQueueItf */
+
+static SLresult queue_enqueue(SLAndroidSimpleBufferQueueItf self, const void *buf, SLuint32 size)
+{
+    obj *o = OBJ(self, queue);
+    pthread_mutex_lock(&o->lock);
+    if (o->qcount == QMAX) {
+        pthread_mutex_unlock(&o->lock);
+        return SL_RESULT_BUFFER_INSUFFICIENT;
+    }
+    static int logged;
+    if (logged < 8 || logged % 2000 == 0)
+        grt_log(4, "a32sles", "enqueue #%d: %u bytes (%u ms), %u queued", logged, size,
+                o->rate && o->channels ? size * 1000u / (SLuint32)(o->rate * o->channels * 2) : 0, o->qcount);
+    logged++;
+    SLuint32 at = (o->qhead + o->qcount) % QMAX;
+    o->q[at].data = buf, o->q[at].size = size;
+    o->qcount++;
+    pthread_cond_broadcast(&o->cond);
+    pthread_mutex_unlock(&o->lock);
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult queue_clear(SLAndroidSimpleBufferQueueItf self)
+{
+    obj *o = OBJ(self, queue);
+    pthread_mutex_lock(&o->lock);
+    o->qcount = 0;
+    pthread_mutex_unlock(&o->lock);
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult queue_get_state(SLAndroidSimpleBufferQueueItf self, SLAndroidSimpleBufferQueueState *st)
+{
+    obj *o = OBJ(self, queue);
+    pthread_mutex_lock(&o->lock);
+    st->count = o->qcount, st->index = o->qindex;
+    pthread_mutex_unlock(&o->lock);
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult queue_register_callback(SLAndroidSimpleBufferQueueItf self, slAndroidSimpleBufferQueueCallback cb,
+                                        void *ctx)
+{
+    obj *o = OBJ(self, queue);
+    o->qcb = cb, o->qctx = ctx;
+    return SL_RESULT_SUCCESS;
+}
+
+static const struct SLAndroidSimpleBufferQueueItf_ queue_itf = {queue_enqueue, queue_clear, queue_get_state,
+                                                                 queue_register_callback};
+
+/* ---------------------------------------------------------------- SLVolumeItf (kept, not applied) */
+
+static SLresult vol_set_level(SLVolumeItf self, SLmillibel l)
+{
+    OBJ(self, volume)->level = l;
+    return SL_RESULT_SUCCESS;
+}
+static SLresult vol_get_level(SLVolumeItf self, SLmillibel *l)
+{
+    *l = OBJ(self, volume)->level;
+    return SL_RESULT_SUCCESS;
+}
+static SLresult vol_get_max(SLVolumeItf self, SLmillibel *l)
+{
+    *l = 0;
+    return SL_RESULT_SUCCESS;
+}
+static SLresult vol_set_mute(SLVolumeItf self, SLboolean m)
+{
+    OBJ(self, volume)->mute = m;
+    return SL_RESULT_SUCCESS;
+}
+static SLresult vol_get_mute(SLVolumeItf self, SLboolean *m)
+{
+    *m = OBJ(self, volume)->mute;
+    return SL_RESULT_SUCCESS;
+}
+static SLresult vol_enable_pos(SLVolumeItf self, SLboolean e) { return SL_RESULT_SUCCESS; }
+static SLresult vol_is_pos(SLVolumeItf self, SLboolean *e)
+{
+    *e = SL_BOOLEAN_FALSE;
+    return SL_RESULT_SUCCESS;
+}
+static SLresult vol_set_pos(SLVolumeItf self, SLpermille p) { return SL_RESULT_SUCCESS; }
+static SLresult vol_get_pos(SLVolumeItf self, SLpermille *p)
+{
+    *p = 0;
+    return SL_RESULT_SUCCESS;
+}
+
+static const struct SLVolumeItf_ volume_itf = {vol_set_level, vol_get_level, vol_get_max, vol_set_mute, vol_get_mute,
+                                               vol_enable_pos, vol_is_pos, vol_set_pos, vol_get_pos};
+
+/* ---------------------------------------------------------------- SLAndroidConfigurationItf */
+
+static SLresult cfg_set(SLAndroidConfigurationItf self, const SLchar *key, const void *value, SLuint32 size)
+{
+    return SL_RESULT_SUCCESS;
+}
+static SLresult cfg_get(SLAndroidConfigurationItf self, const SLchar *key, SLuint32 *size, void *value)
+{
+    return SL_RESULT_PARAMETER_INVALID;
+}
+
+static const struct SLAndroidConfigurationItf_ config_itf = {cfg_set, cfg_get};
+
+/* ---------------------------------------------------------------- SLEngineItf */
+
+static obj *new_obj(int kind)
+{
+    obj *o = calloc(1, sizeof *o);
+    o->object = &object_itf;
+    o->kind = kind;
+    o->state = SL_OBJECT_STATE_UNREALIZED;
+    pthread_mutex_init(&o->lock, NULL);
+    pthread_cond_init(&o->cond, NULL);
+    return o;
+}
+
+static SLresult unsupported(void) { return SL_RESULT_FEATURE_UNSUPPORTED; }
+
+static SLresult engine_create_player(SLEngineItf self, SLObjectItf *player, SLDataSource *src, SLDataSink *sink,
+                                     SLuint32 n, const SLInterfaceID *iids, const SLboolean *required)
+{
+    SLuint32 loc = src && src->pLocator ? *(SLuint32 *)src->pLocator : 0;
+    SLuint32 fmt = src && src->pFormat ? *(SLuint32 *)src->pFormat : 0;
+    if ((loc != SL_DATALOCATOR_ANDROIDSIMPLEBUFFERQUEUE && loc != SL_DATALOCATOR_BUFFERQUEUE) ||
+        (fmt != SL_DATAFORMAT_PCM && fmt != SL_ANDROID_DATAFORMAT_PCM_EX)) {
+        grt_log(5, "a32sles", "audio player source (locator %u, format %u) isn't supported", loc, fmt);
+        return SL_RESULT_CONTENT_UNSUPPORTED;
+    }
+    const SLDataFormat_PCM *pcm = src->pFormat;
+    if (fmt == SL_ANDROID_DATAFORMAT_PCM_EX && ((const SLAndroidDataFormat_PCM_EX *)pcm)->representation ==
+                                                   SL_ANDROID_PCM_REPRESENTATION_FLOAT) {
+        grt_log(5, "a32sles", "float PCM isn't supported");
+        return SL_RESULT_CONTENT_UNSUPPORTED;
+    }
+    obj *o = new_obj(K_PLAYER);
+    o->play = &play_itf;
+    o->queue = &queue_itf;
+    o->volume = &volume_itf;
+    o->config = &config_itf;
+    o->rate = (int)(pcm->samplesPerSec / 1000); /* milliHz */
+    o->channels = (int)pcm->numChannels;
+    o->bits = (int)pcm->bitsPerSample;
+    o->play_state = SL_PLAYSTATE_STOPPED;
+    grt_log(4, "a32sles", "audio player: %d Hz, %d channels, %d bits", o->rate, o->channels, o->bits);
+    *player = (SLObjectItf)&o->object;
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult engine_create_mix(SLEngineItf self, SLObjectItf *mix, SLuint32 n, const SLInterfaceID *iids,
+                                  const SLboolean *required)
+{
+    obj *o = new_obj(K_MIX);
+    *mix = (SLObjectItf)&o->object;
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult engine_query_num_ext(SLEngineItf self, SLuint32 *n)
+{
+    *n = 0;
+    return SL_RESULT_SUCCESS;
+}
+
+static SLresult engine_is_ext(SLEngineItf self, const SLchar *name, SLboolean *supported)
+{
+    *supported = SL_BOOLEAN_FALSE;
+    return SL_RESULT_SUCCESS;
+}
+
+static const struct SLEngineItf_ engine_itf = {
+    .CreateLEDDevice = (void *)unsupported,
+    .CreateVibraDevice = (void *)unsupported,
+    .CreateAudioPlayer = engine_create_player,
+    .CreateAudioRecorder = (void *)unsupported,
+    .CreateMidiPlayer = (void *)unsupported,
+    .CreateListener = (void *)unsupported,
+    .Create3DGroup = (void *)unsupported,
+    .CreateOutputMix = engine_create_mix,
+    .CreateMetadataExtractor = (void *)unsupported,
+    .CreateExtensionObject = (void *)unsupported,
+    .QueryNumSupportedInterfaces = (void *)unsupported,
+    .QuerySupportedInterfaces = (void *)unsupported,
+    .QueryNumSupportedExtensions = engine_query_num_ext,
+    .QuerySupportedExtension = (void *)unsupported,
+    .IsExtensionSupported = engine_is_ext,
+};
+
+SLresult slCreateEngine(SLObjectItf *engine, SLuint32 n_opts, const SLEngineOption *opts, SLuint32 n,
+                        const SLInterfaceID *iids, const SLboolean *required)
+{
+    obj *o = new_obj(K_ENGINE);
+    o->engine = &engine_itf;
+    *engine = (SLObjectItf)&o->object;
+    return SL_RESULT_SUCCESS;
+}
+
+SLresult slQueryNumSupportedEngineInterfaces(SLuint32 *n)
+{
+    *n = 1;
+    return SL_RESULT_SUCCESS;
+}
+
+SLresult slQuerySupportedEngineInterfaces(SLuint32 index, SLInterfaceID *id)
+{
+    if (index) return SL_RESULT_PARAMETER_INVALID;
+    *id = SL_IID_ENGINE;
+    return SL_RESULT_SUCCESS;
+}
@@ -0,0 +1,48 @@
+/* Public API of the host bridge (liba32bridge.so), used by the per-library stubs (stub.c) and the PC harness.
+ *
+ * A converted APK keeps every 32-bit library libX.so as libX.a32.so next to the 64-bit ones. libX.so itself
+ * becomes a copy of the stub, which forwards JNI_OnLoad and ANativeActivity_onCreate to the bridge. The bridge
+ * runs the guest runtime (liba32rt.so, from the same folder) in this process and loads the guest libraries into
+ * it. */
+#ifndef A32BRIDGE_H
+#define A32BRIDGE_H
+
+#include <jni.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#define A32B_API __attribute__((visibility("default")))
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct ANativeActivity;
+
+/* Starts the guest runtime once (later calls return at once). libdir holds liba32rt.so and the guest libraries.
+ * Returns 0 on success. */
+A32B_API int a32b_init(JavaVM *vm, const char *libdir);
+
+/* Loads the guest library for the stub at stub_path (".../libX.so" -> guest libX.so). Returns a guest handle, 0 on
+ * failure. */
+A32B_API uint32_t a32b_load(const char *stub_path);
+
+/* What a stub's JNI_OnLoad does: init, load, the guest JNI_OnLoad, then registers the library's exported Java_*
+ * functions with their classes. Returns the JNI version for ART (JNI_ERR on failure). */
+A32B_API jint a32b_jni_onload(JavaVM *vm, const char *stub_path);
+
+/* What a stub's ANativeActivity_onCreate does (the guest library's own ANativeActivity_onCreate). */
+A32B_API void a32b_native_activity_oncreate(struct ANativeActivity *activity, void *saved, size_t saved_size,
+                                            const char *stub_path);
+
+/* Address of a guest symbol (0 if none). */
+A32B_API uint32_t a32b_sym(uint32_t handle, const char *name);
+
+/* Calls a guest function (AAPCS words: 64-bit values as an even-aligned pair). Returns r0 | r1 << 32. */
+A32B_API uint64_t a32b_call(uint32_t fn, const uint32_t *words, int n);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
@@ -0,0 +1,332 @@
+/* libandroid functions that gen_stubs.py can't generate (imports.txt "!" lines). */
+#include <android/sensor.h>
+#include <stdlib.h>
+#include "imports_internal.h"
+
+extern __typeof__(ASensorManager_getSensorList) ASensorManager_getSensorList __attribute__((weak));
+extern __typeof__(ASensorManager_createEventQueue) ASensorManager_createEventQueue __attribute__((weak));
+
+/* the list is an array of host pointers: the guest gets an array of handles (made once per call; tiny) */
+void imp_ASensorManager_getSensorList(a32_cpu *c, argreader *R)
+{
+    ASensorManager *m = h2ptr(rd32(R));
+    uint32_t out = rd32(R);
+    ASensorList list = NULL;
+    int n = ASensorManager_getSensorList ? ASensorManager_getSensorList(m, &list) : 0;
+    uint32_t g = guest_malloc(n > 0 ? 4u * (uint32_t)n : 4);
+    for (int k = 0; k < n && g; k++) st32(g + 4u * (uint32_t)k, ptr2h((void *)list[k]));
+    if (out) st32(out, g);
+    ret32(c, (uint32_t)n);
+}
+
+void imp_ASensorManager_createEventQueue(a32_cpu *c, argreader *R)
+{
+    ASensorManager *m = h2ptr(rd32(R));
+    ALooper *looper = h2ptr(rd32(R));
+    int ident = (int)rd32(R);
+    uint32_t cb = rd32(R), data = rd32(R);
+    if (cb) bridge_log(ANDROID_LOG_WARN, "ASensorManager_createEventQueue: guest callbacks aren't supported yet");
+    ASensorEventQueue *q = ASensorManager_createEventQueue ? ASensorManager_createEventQueue(m, looper, ident, NULL, g2p(data)) : NULL;
+    ret32(c, ptr2h(q));
+}
+
+/* ---------------------------------------------------------------- audio output (guest/opensles.c) */
+
+#include <aaudio/AAudio.h>
+
+#define W(f) extern __typeof__(f) f __attribute__((weak))
+W(AAudio_createStreamBuilder); W(AAudioStreamBuilder_setSampleRate); W(AAudioStreamBuilder_setChannelCount);
+W(AAudioStreamBuilder_setFormat); W(AAudioStreamBuilder_setPerformanceMode); W(AAudioStreamBuilder_openStream);
+W(AAudioStreamBuilder_delete); W(AAudioStream_requestStart); W(AAudioStream_requestPause);
+W(AAudioStream_requestFlush); W(AAudioStream_write); W(AAudioStream_close); W(AAudio_convertResultToText);
+W(AAudioStream_setBufferSizeInFrames); W(AAudioStream_getBufferCapacityInFrames); W(AAudioStream_getXRunCount);
+#undef W
+
+typedef struct {
+    AAudioStream *stream;
+    int frame_bytes;
+} audio_out;
+
+void imp_a32_audio_open(a32_cpu *c, argreader *R)
+{
+    int rate = (int)rd32(R), channels = (int)rd32(R), bits = (int)rd32(R);
+    AAudioStreamBuilder *b = NULL;
+    if (!AAudio_createStreamBuilder || bits != 16 || AAudio_createStreamBuilder(&b) != AAUDIO_OK) {
+        bridge_log(ANDROID_LOG_ERROR, "audio: can't open a %d Hz, %d channel, %d bit stream", rate, channels, bits);
+        ret32(c, 0);
+        return;
+    }
+    AAudioStreamBuilder_setSampleRate(b, rate);
+    AAudioStreamBuilder_setChannelCount(b, channels);
+    AAudioStreamBuilder_setFormat(b, AAUDIO_FORMAT_PCM_I16);
+    /* a roomy buffer: the guest's mixer is fed back through the translator and would underrun a low-latency one */
+    AAudioStreamBuilder_setPerformanceMode(b, AAUDIO_PERFORMANCE_MODE_NONE);
+    AAudioStream *s = NULL;
+    aaudio_result_t r = AAudioStreamBuilder_openStream(b, &s);
+    AAudioStreamBuilder_delete(b);
+    if (r != AAUDIO_OK) {
+        bridge_log(ANDROID_LOG_ERROR, "audio: AAudio open failed: %s", AAudio_convertResultToText(r));
+        ret32(c, 0);
+        return;
+    }
+    /* ~40 ms: writes block at the device's pace. A larger buffer let the player thread drain the guest's queue
+     * faster than real time, and the guest's mixer (FMOD) fell behind: crackling */
+    if (AAudioStream_setBufferSizeInFrames) AAudioStream_setBufferSizeInFrames(s, rate / 25);
+    audio_out *o = calloc(1, sizeof *o);
+    o->stream = s;
+    o->frame_bytes = channels * 2;
+    bridge_log(ANDROID_LOG_INFO, "audio: %d Hz, %d channels through AAudio", rate, channels);
+    ret32(c, ptr2h(o));
+}
+
+/* blocking, like a full OpenSL buffer queue: this paces the guest's audio thread */
+void imp_a32_audio_write(a32_cpu *c, argreader *R)
+{
+    audio_out *o = h2ptr(rd32(R));
+    const void *data = g2p(rd32(R));
+    int frames = (int)rd32(R);
+    aaudio_result_t r = o ? AAudioStream_write(o->stream, data, frames, 1000000000LL) : 0;
+    static int xruns;
+    if (o && AAudioStream_getXRunCount) {
+        int x = AAudioStream_getXRunCount(o->stream);
+        if (x > xruns && (xruns < 20 || x % 100 == 0)) bridge_log(ANDROID_LOG_WARN, "audio: %d underruns", x);
+        xruns = x;
+    }
+    ret32(c, (uint32_t)r);
+}
+
+void imp_a32_audio_start(a32_cpu *c, argreader *R)
+{
+    audio_out *o = h2ptr(rd32(R));
+    if (o) AAudioStream_requestStart(o->stream);
+}
+
+void imp_a32_audio_pause(a32_cpu *c, argreader *R)
+{
+    audio_out *o = h2ptr(rd32(R));
+    if (o) AAudioStream_requestPause(o->stream);
+}
+
+void imp_a32_audio_close(a32_cpu *c, argreader *R)
+{
+    audio_out *o = h2ptr(rd32(R));
+    if (!o) return;
+    AAudioStream_close(o->stream);
+    free(o);
+}
+
+/* ---------------------------------------------------------------- looper, input queue, assets (native_app_glue) */
+
+#include <android/asset_manager.h>
+#include <dlfcn.h>
+#include <pthread.h>
+#include <string.h>
+#include <android/input.h>
+#include <android/looper.h>
+
+#define W(f) extern __typeof__(f) f __attribute__((weak))
+W(ALooper_addFd); W(ALooper_pollOnce); W(AInputQueue_attachLooper); W(AInputQueue_getEvent); W(ALooper_forThread);
+W(AAssetDir_getNextFileName); W(AAsset_openFileDescriptor); W(AAsset_openFileDescriptor64);
+W(AAsset_getBuffer); W(AAsset_getLength64); W(AAsset_close);
+#undef W
+
+/* a guest ALooper callback int (*)(int fd, int events, void *data), called on the polling (guest) thread */
+typedef struct {
+    uint32_t fn, data;
+} looper_cb;
+
+static int looper_call(int fd, int events, void *p)
+{
+    looper_cb *cb = p;
+    uint32_t w[3] = {(uint32_t)fd, (uint32_t)events, cb->data};
+    return (int)guest_call(cb->fn, w, 3);
+}
+
+/* host data for a guest (callback, data) pair: the callback's own record (kept: the looper may call it until the
+ * fd is removed), or the guest's data pointer itself when there is no callback */
+static void *looper_data(uint32_t fn, uint32_t data, ALooper_callbackFunc *host_fn)
+{
+    *host_fn = NULL;
+    if (!fn) return g2p(data);
+    looper_cb *cb = malloc(sizeof *cb);
+    if (!cb) return NULL;
+    cb->fn = fn, cb->data = data;
+    *host_fn = looper_call;
+    return cb;
+}
+
+void imp_ALooper_addFd(a32_cpu *c, argreader *R)
+{
+    ALooper *l = h2ptr(rd32(R));
+    int fd = (int)rd32(R), ident = (int)rd32(R), events = (int)rd32(R);
+    uint32_t fn = rd32(R), data = rd32(R);
+    ALooper_callbackFunc host_fn;
+    void *d = looper_data(fn, data, &host_fn);
+    ret32(c, ALooper_addFd ? (uint32_t)ALooper_addFd(l, fd, ident, events, host_fn, d) : (uint32_t)-1);
+}
+
+void imp_AInputQueue_attachLooper(a32_cpu *c, argreader *R)
+{
+    AInputQueue *q = h2ptr(rd32(R));
+    ALooper *l = h2ptr(rd32(R));
+    int ident = (int)rd32(R);
+    uint32_t fn = rd32(R), data = rd32(R);
+    ALooper_callbackFunc host_fn;
+    void *d = looper_data(fn, data, &host_fn);
+    if (AInputQueue_attachLooper) AInputQueue_attachLooper(q, l, ident, host_fn, d);
+    input_queue_attached(q, l, ident, data, fn != 0); /* the controllers' synthetic events go here (input.c) */
+}
+
+/* outData is a void ** (4 bytes on the guest side); data without a callback is the guest's own pointer */
+static void poll(a32_cpu *c, argreader *R, int all)
+{
+    int timeout = (int)rd32(R);
+    uint32_t out_fd = rd32(R), out_events = rd32(R), out_data = rd32(R);
+    int fd = 0, events = 0;
+    void *data = NULL;
+    /* a synthetic input event waits (input.c): the input queue's ident, like a readable queue fd */
+    int ident;
+    uint32_t gdata;
+    if (input_queue_pending(ALooper_forThread(), &ident, &gdata)) {
+        if (out_fd) st32(out_fd, (uint32_t)-1);
+        if (out_events) st32(out_events, ALOOPER_EVENT_INPUT);
+        if (out_data) st32(out_data, gdata);
+        ret32(c, (uint32_t)ident);
+        return;
+    }
+    /* ALooper_pollAll: removed from the NDK headers (it may miss wakes), still in libandroid for old apps */
+    static int (*poll_all)(int, int *, int *, void **);
+    if (all && !poll_all) poll_all = (int (*)(int, int *, int *, void **))dlsym(RTLD_DEFAULT, "ALooper_pollAll");
+    int (*f)(int, int *, int *, void **) = all ? poll_all : ALooper_pollOnce;
+    int r = f ? f(timeout, &fd, &events, &data) : ALOOPER_POLL_ERROR;
+    if (out_fd) st32(out_fd, (uint32_t)fd);
+    if (out_events) st32(out_events, (uint32_t)events);
+    if (out_data) st32(out_data, (uint32_t)(uintptr_t)data);
+    ret32(c, (uint32_t)r);
+}
+
+void imp_ALooper_pollAll(a32_cpu *c, argreader *R) { poll(c, R, 1); }
+void imp_ALooper_pollOnce(a32_cpu *c, argreader *R) { poll(c, R, 0); }
+
+void imp_AInputQueue_getEvent(a32_cpu *c, argreader *R)
+{
+    AInputQueue *q = h2ptr(rd32(R));
+    uint32_t out = rd32(R);
+    AInputEvent *e = input_queue_pop(q); /* synthetic controller events first */
+    int r = e ? 0 : AInputQueue_getEvent ? AInputQueue_getEvent(q, &e) : -1;
+    if (out) st32(out, r >= 0 ? ptr2h(e) : 0);
+    ret32(c, (uint32_t)r);
+}
+
+/* the name is valid until the next call: one guest buffer, refilled each time */
+void imp_AAssetDir_getNextFileName(a32_cpu *c, argreader *R)
+{
+    AAssetDir *d = h2ptr(rd32(R));
+    const char *name = AAssetDir_getNextFileName ? AAssetDir_getNextFileName(d) : NULL;
+    static uint32_t buf;
+    static size_t size;
+    size_t n = name ? strlen(name) + 1 : 0;
+    if (n > size) {
+        guest_free(buf);
+        size = n < 256 ? 256 : n;
+        buf = guest_malloc((uint32_t)size);
+        if (!buf) size = 0;
+    }
+    if (n && buf) memcpy(g2p(buf), name, n);
+    ret32(c, n && buf ? buf : 0);
+}
+
+/* off_t is 32-bit for the guest (AAsset_openFileDescriptor) and 64-bit in the 64 variant */
+static void open_fd(a32_cpu *c, argreader *R, int wide)
+{
+    AAsset *a = h2ptr(rd32(R));
+    uint32_t out_start = rd32(R), out_len = rd32(R);
+    off64_t start = 0, len = 0;
+    int fd = AAsset_openFileDescriptor64 ? AAsset_openFileDescriptor64(a, &start, &len) : -1;
+    if (wide) {
+        if (out_start) memcpy(g2p(out_start), &start, 8);
+        if (out_len) memcpy(g2p(out_len), &len, 8);
+    } else {
+        if (start > 0x7fffffff || len > 0x7fffffff)
+            bridge_log(ANDROID_LOG_WARN, "AAsset_openFileDescriptor: offset/length past 2 GiB for a 32-bit app");
+        if (out_start) st32(out_start, (uint32_t)start);
+        if (out_len) st32(out_len, (uint32_t)len);
+    }
+    ret32(c, (uint32_t)fd);
+}
+
+void imp_AAsset_openFileDescriptor(a32_cpu *c, argreader *R) { open_fd(c, R, 0); }
+void imp_AAsset_openFileDescriptor64(a32_cpu *c, argreader *R) { open_fd(c, R, 1); }
+
+/* AAsset_getBuffer's memory is the host's (above 4 GiB): the guest gets a copy in its own memory, kept until
+ * AAsset_close like the original (Unreal reads small config/text assets this way) */
+typedef struct asset_buf {
+    struct asset_buf *next;
+    AAsset *asset;
+    uint32_t buf;
+} asset_buf;
+
+static pthread_mutex_t asset_lock = PTHREAD_MUTEX_INITIALIZER;
+static asset_buf *asset_bufs;
+
+void imp_AAsset_getBuffer(a32_cpu *c, argreader *R)
+{
+    AAsset *a = h2ptr(rd32(R));
+    uint32_t g = 0;
+    pthread_mutex_lock(&asset_lock);
+    for (asset_buf *b = asset_bufs; b; b = b->next)
+        if (b->asset == a) g = b->buf;
+    pthread_mutex_unlock(&asset_lock);
+    if (g || !a || !AAsset_getBuffer) {
+        ret32(c, g);
+        return;
+    }
+    const void *p = AAsset_getBuffer(a);
+    off64_t len = p ? AAsset_getLength64(a) : 0;
+    if (!p || len < 0 || len > 0x40000000) {
+        if (p) bridge_log(ANDROID_LOG_WARN, "AAsset_getBuffer: %lld bytes is too big for a 32-bit app", (long long)len);
+        ret32(c, 0);
+        return;
+    }
+    asset_buf *b = malloc(sizeof *b);
+    g = b ? guest_malloc(len ? (uint32_t)len : 1) : 0;
+    if (!g) {
+        free(b);
+        bridge_log(ANDROID_LOG_WARN, "AAsset_getBuffer: no guest memory for %lld bytes", (long long)len);
+        ret32(c, 0);
+        return;
+    }
+    memcpy(g2p(g), p, (size_t)len);
+    b->asset = a, b->buf = g;
+    pthread_mutex_lock(&asset_lock);
+    b->next = asset_bufs, asset_bufs = b;
+    pthread_mutex_unlock(&asset_lock);
+    ret32(c, g);
+}
+
+void imp_AAsset_close(a32_cpu *c, argreader *R)
+{
+    AAsset *a = h2ptr(rd32(R));
+    asset_buf *found = NULL;
+    pthread_mutex_lock(&asset_lock);
+    for (asset_buf **pp = &asset_bufs; *pp; pp = &(*pp)->next)
+        if ((*pp)->asset == a) {
+            found = *pp;
+            *pp = found->next;
+            break;
+        }
+    pthread_mutex_unlock(&asset_lock);
+    if (found) {
+        guest_free(found->buf);
+        free(found);
+    }
+    if (a && AAsset_close) AAsset_close(a);
+}
+
+/* logged: a game that quits by itself shows it here */
+void imp_ANativeActivity_finish(a32_cpu *c, argreader *R)
+{
+    ANativeActivity *a = guest_activity(rd32(R));
+    bridge_log(ANDROID_LOG_INFO, "guest called ANativeActivity_finish");
+    if (a) ANativeActivity_finish(a);
+}
@@ -0,0 +1,553 @@
+/* Host side of the bridge: runs the guest runtime (liba32rt.so) inside this process, dispatches its hypercalls
+ * and calls guest functions on behalf of host threads.
+ *
+ * Threads: the thread that calls a32b_init becomes the guest's main thread. Any other host thread that calls into
+ * the guest first gets a guest thread of its own: the runtime's service thread pthread_creates one (WORK_ATTACH)
+ * and the clone hands it to the waiting host thread (threads.c, thread_adopt), which then owns it for good. Guest
+ * threads (pthread_create in guest code) are host pthreads with their guest context from the start. A host-to-guest
+ * call saves the thread's guest state, runs the function until it returns to A32_RETURN_TRAMPOLINE (hypercall
+ * HC_RETURN), and restores the state: calls nest (Java -> guest -> JNI -> Java -> guest ...). */
+#define _GNU_SOURCE
+#include <errno.h>
+#include <fcntl.h>
+#include <limits.h>
+#include <pthread.h>
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+#include <android/log.h>
+#include "a32bridge.h"
+#include "imports_internal.h"
+#include "../../src/signals.h"
+
+struct grt_info g_info;
+JavaVM *g_vm;
+static pthread_mutex_t init_lock = PTHREAD_MUTEX_INITIALIZER;
+static volatile int ready;
+
+/* ---------------------------------------------------------------- logging */
+
+static void log_write(int prio, const char *tag, const char *msg)
+{
+#ifdef A32B_STDERR_LOG
+    fprintf(stderr, "%c/%s: %s\n", "??VDIWEF"[prio & 7], tag, msg);
+#else
+    __android_log_write(prio, tag, msg);
+#endif
+}
+
+void bridge_log(int prio, const char *fmt, ...)
+{
+    char msg[1024];
+    va_list ap;
+    va_start(ap, fmt);
+    vsnprintf(msg, sizeof msg, fmt, ap);
+    va_end(ap);
+    log_write(prio, "a32bridge", msg);
+}
+
+void a32_report(const char *fmt, ...)
+{
+    char msg[512];
+    va_list ap;
+    va_start(ap, fmt);
+    vsnprintf(msg, sizeof msg, fmt, ap);
+    va_end(ap);
+    log_write(ANDROID_LOG_WARN, "a32", msg);
+}
+
+JNIEnv *host_env(void)
+{
+    JNIEnv *env = NULL;
+    if (!g_vm || (*g_vm)->GetEnv(g_vm, (void **)&env, JNI_VERSION_1_6) != JNI_OK) return NULL;
+    return env;
+}
+
+#ifndef A32B_STDERR_LOG
+/* The translator reports guest crashes and internal errors on stderr, which is /dev/null in an app: forward it to
+ * the system log. */
+static void *stderr_pump(void *arg)
+{
+    FILE *f = fdopen((int)(intptr_t)arg, "r");
+    char line[1024];
+    while (f && fgets(line, sizeof line, f)) {
+        line[strcspn(line, "\n")] = 0;
+        log_write(ANDROID_LOG_WARN, "a32", line);
+    }
+    return NULL;
+}
+
+static void forward_stderr(void)
+{
+    int p[2];
+    if (pipe2(p, O_CLOEXEC)) return;
+    dup2(p[1], 2);
+    close(p[1]);
+    setvbuf(stderr, NULL, _IOLBF, 0);
+    pthread_t t;
+    pthread_attr_t attr;
+    pthread_attr_init(&attr);
+    pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
+    pthread_create(&t, &attr, stderr_pump, (void *)(intptr_t)p[0]);
+    pthread_attr_destroy(&attr);
+}
+#endif
+
+/* A32_WATCH=<seconds>: logs every guest thread's pc/lr periodically, plus the return-address candidates on its
+ * stack (words pointing into executable guest libraries, as lib+offset): where a game hangs or spins. Threads in
+ * translated code are asked to leave it first, so their registers are current. */
+typedef struct {
+    uint32_t lo, hi, off;
+    char name[48];
+} xmap;
+
+static int exec_maps(xmap *m, int max)
+{
+    FILE *f = fopen("/proc/self/maps", "re");
+    int n = 0;
+    char line[512];
+    while (f && n < max && fgets(line, sizeof line, f)) {
+        unsigned long long lo, hi, off;
+        char perms[8], path[400] = "";
+        if (sscanf(line, "%llx-%llx %7s %llx %*s %*s %399s", &lo, &hi, perms, &off, path) < 4) continue;
+        size_t pl = strlen(path);
+        if (hi > 0x100000000ull || pl < 3 || strcmp(path + pl - 3, ".so")) continue; /* guest code isn't host-executable */
+        const char *b = strrchr(path, '/');
+        m[n].lo = (uint32_t)lo, m[n].hi = (uint32_t)hi, m[n].off = (uint32_t)off;
+        snprintf(m[n].name, sizeof m[n].name, "%s", b ? b + 1 : path);
+        n++;
+    }
+    if (f) fclose(f);
+    return n;
+}
+
+static int describe(const xmap *m, int n, uint32_t a, char *out, size_t sz)
+{
+    for (int k = 0; k < n; k++)
+        if (a >= m[k].lo && a < m[k].hi) {
+            snprintf(out, sz, "%s+%x", m[k].name, a - m[k].lo + m[k].off);
+            return 1;
+        }
+    return 0;
+}
+
+/* return addresses found on a guest stack (lib+offset), for logs */
+static size_t stack_scan(const xmap *maps, int nm, uint32_t sp, char *bt, size_t sz)
+{
+    size_t k = 0;
+    int found = 0;
+    for (uint32_t a = sp & ~3u, e = a + 4096; a < e && found < 10 && mem_readable(a, 4); a += 4) {
+        char d[64];
+        uint32_t w = ld32(a);
+        if ((w & 1) || ((w & 3) == 0)) /* Thumb return addresses are odd, ARM ones word-aligned */
+            if (describe(maps, nm, (w & ~1u) - 2, d, sizeof d) && k + 70 < sz) {
+                k += (size_t)snprintf(bt + k, sz - k, " %s", d);
+                found++;
+            }
+    }
+    return k;
+}
+
+/* logs where the current guest call came from: its return address and a scan of the stack */
+void guest_backtrace(a32_cpu *c, const char *what)
+{
+    static xmap maps[256];
+    static pthread_mutex_t m = PTHREAD_MUTEX_INITIALIZER;
+    pthread_mutex_lock(&m);
+    int nm = exec_maps(maps, 256);
+    char lr[64] = "?", bt[600] = "";
+    describe(maps, nm, c->r[14] & ~1u, lr, sizeof lr);
+    stack_scan(maps, nm, c->r[13], bt, sizeof bt);
+    pthread_mutex_unlock(&m);
+    bridge_log(ANDROID_LOG_INFO, "%s: called from %s |%s", what, lr, bt);
+}
+
+static void *watch(void *arg)
+{
+    int secs = (int)(intptr_t)arg;
+    static xmap maps[256];
+    for (;;) {
+        sleep((unsigned)secs);
+        threads_interrupt_all();
+        usleep(2000);
+        int nm = exec_maps(maps, 256);
+        for (a32_thread *t = thread_main(); t; t = t->next) {
+            char pc[64] = "?", lr[64] = "?", bt[600] = "";
+            describe(maps, nm, t->cpu.r[15], pc, sizeof pc);
+            describe(maps, nm, t->cpu.r[14] & ~1u, lr, sizeof lr);
+            stack_scan(maps, nm, t->cpu.r[13], bt, sizeof bt);
+            char comm[32] = "", cp[64];
+            snprintf(cp, sizeof cp, "/proc/self/task/%d/comm", t->tid);
+            FILE *cf = fopen(cp, "re");
+            if (cf) {
+                if (fgets(comm, sizeof comm, cf)) comm[strcspn(comm, "\n")] = 0;
+                fclose(cf);
+            }
+            bridge_log(ANDROID_LOG_INFO, "watch: tid %d %s pc %s lr %s r0 %08x%s |%s", t->tid, comm, pc, lr, t->cpu.r[0],
+                       t->in_guest ? " running" : "", bt);
+        }
+    }
+    return NULL;
+}
+
+/* ---------------------------------------------------------------- guest threads for host threads */
+
+static pthread_mutex_t wq_lock = PTHREAD_MUTEX_INITIALIZER;
+static pthread_cond_t wq_cond = PTHREAD_COND_INITIALIZER;
+static a32_adopt *wq[64];
+static int wq_n;
+
+/* the calling host thread's guest thread (created on first use) */
+static a32_thread *guest_thread(void)
+{
+    if (g_self) return g_self;
+    a32_adopt ad;
+    memset(&ad, 0, sizeof ad);
+    pthread_mutex_lock(&wq_lock);
+    while (wq_n == (int)(sizeof wq / sizeof *wq)) pthread_cond_wait(&wq_cond, &wq_lock);
+    wq[wq_n++] = &ad;
+    pthread_cond_broadcast(&wq_cond);
+    pthread_mutex_unlock(&wq_lock);
+    thread_adopt(&ad);
+    a32_thread *t = g_self;
+    t->cpu.thread = t;
+    /* the new guest thread starts in bionic's thread entry and parks in attached_entry (HC_RETURN) */
+    run_guest(&t->cpu);
+    t->in_host = 1;
+    return t;
+}
+
+/* HC_WAIT_WORK, on the service thread */
+static uint32_t wait_work(void)
+{
+    pthread_mutex_lock(&wq_lock);
+    while (!wq_n) pthread_cond_wait(&wq_cond, &wq_lock);
+    a32_adopt *ad = wq[0];
+    memmove(wq, wq + 1, (size_t)--wq_n * sizeof *wq);
+    pthread_cond_broadcast(&wq_cond);
+    pthread_mutex_unlock(&wq_lock);
+    g_clone_adopt = ad; /* the service thread's next clone (its pthread_create) goes to ad */
+    return WORK_ATTACH;
+}
+
+/* ---------------------------------------------------------------- calls into the guest */
+
+typedef struct {
+    uint32_t r[16], nzcv, q, ge, thumb, itstate, fpscr_nzcv, fpcr, fpsr, excl_valid;
+    uint64_t d[32];
+} saved_regs;
+
+static void save_regs(const a32_cpu *c, saved_regs *s)
+{
+    memcpy(s->r, c->r, sizeof s->r);
+    s->nzcv = c->nzcv, s->q = c->q, s->ge = c->ge, s->thumb = c->thumb, s->itstate = c->itstate;
+    s->fpscr_nzcv = c->fpscr_nzcv, s->fpcr = c->fpcr, s->fpsr = c->fpsr, s->excl_valid = c->excl_valid;
+    memcpy(s->d, c->d, sizeof s->d);
+}
+
+static void restore_regs(a32_cpu *c, const saved_regs *s)
+{
+    memcpy(c->r, s->r, sizeof s->r);
+    c->nzcv = s->nzcv, c->q = s->q, c->ge = s->ge, c->thumb = s->thumb, c->itstate = s->itstate;
+    c->fpscr_nzcv = s->fpscr_nzcv, c->fpcr = s->fpcr, c->fpsr = s->fpsr, c->excl_valid = s->excl_valid;
+    memcpy(c->d, s->d, sizeof s->d);
+}
+
+uint64_t guest_call(uint32_t fn, const uint32_t *words, int n)
+{
+    a32_thread *t = guest_thread();
+    a32_cpu *c = &t->cpu;
+    saved_regs s;
+    save_regs(c, &s);
+    int nstack = n > 4 ? n - 4 : 0;
+    /* below the interrupted code's stack pointer: everything there is free */
+    uint32_t sp = (c->r[13] - 64 - 4u * (uint32_t)nstack) & ~7u;
+    for (int k = 0; k < nstack; k++) st32(sp + 4u * (uint32_t)k, words[4 + k]);
+    for (int k = 0; k < 4; k++) c->r[k] = k < n ? words[k] : 0;
+    c->r[13] = sp;
+    c->r[14] = A32_RETURN_TRAMPOLINE;
+    c->r[15] = fn & ~1u;
+    c->thumb = fn & 1;
+    c->itstate = 0;
+    c->last_exit = 0; /* never chain the interrupted code's last exit to the callee */
+    int in_host = t->in_host;
+    t->in_host = 0;
+    run_guest(c);
+    t->in_host = in_host;
+    uint64_t r = c->r[0] | (uint64_t)c->r[1] << 32;
+    restore_regs(c, &s);
+    c->last_exit = 0;
+    return r;
+}
+
+uint32_t guest_malloc(uint32_t size)
+{
+    return (uint32_t)guest_call(g_info.fn_malloc, &size, 1);
+}
+
+void guest_free(uint32_t p)
+{
+    if (p) guest_call(g_info.fn_free, &p, 1);
+}
+
+uint32_t guest_strdup(const char *s)
+{
+    size_t n = strlen(s) + 1;
+    uint32_t p = guest_malloc((uint32_t)n);
+    if (p) memcpy(g2p(p), s, n);
+    return p;
+}
+
+uint32_t guest_cstr(const char *s)
+{
+    static struct { const char *host; uint32_t guest; } cache[256];
+    static int n;
+    static pthread_mutex_t m = PTHREAD_MUTEX_INITIALIZER;
+    if (!s) return 0;
+    if (in_guest_reach(s, strlen(s) + 1)) return p2g(s);
+    pthread_mutex_lock(&m);
+    for (int k = 0; k < n; k++)
+        if (cache[k].host == s) {
+            uint32_t g = cache[k].guest;
+            pthread_mutex_unlock(&m);
+            return g;
+        }
+    pthread_mutex_unlock(&m);
+    uint32_t g = guest_strdup(s);
+    pthread_mutex_lock(&m);
+    if (n < 256) cache[n].host = s, cache[n++].guest = g;
+    pthread_mutex_unlock(&m);
+    return g;
+}
+
+A32B_API uint64_t a32b_call(uint32_t fn, const uint32_t *words, int n) { return guest_call(fn, words, n); }
+
+/* ---------------------------------------------------------------- hypercalls */
+
+/* gl.c; the PC harness has no GLES */
+__attribute__((weak)) int gl_dispatch(a32_cpu *c, int index, argreader *R)
+{
+    (void)c, (void)index, (void)R;
+    return 0;
+}
+
+static void unresolved(const char *name)
+{
+    /* once per name: games call missing optional functions in loops */
+    static pthread_mutex_t m = PTHREAD_MUTEX_INITIALIZER;
+    static char *seen[256];
+    static int nseen;
+    pthread_mutex_lock(&m);
+    for (int k = 0; k < nseen; k++)
+        if (!strcmp(seen[k], name)) {
+            pthread_mutex_unlock(&m);
+            return;
+        }
+    if (nseen < 256) seen[nseen++] = strdup(name);
+    pthread_mutex_unlock(&m);
+    bridge_log(ANDROID_LOG_ERROR, "guest called %s, which no library defines (returned 0)", name);
+}
+
+static void hypercall(a32_cpu *c, uint32_t n);
+
+/* while a hypercall runs host code, guest signals for this thread are delivered at once (signals.c) */
+void a32_hypercall(a32_cpu *c, uint32_t n)
+{
+    a32_thread *t = c->thread;
+    int in_host = t->in_host;
+    t->in_host = 1;
+    hypercall(c, n);
+    t->in_host = in_host;
+}
+
+static void hypercall(a32_cpu *c, uint32_t n)
+{
+    a32_thread *t = c->thread;
+    switch (n) {
+    case HC_RETURN:
+        t->stop = 1;
+        return;
+    case HC_READY:
+        memcpy(&g_info, g2p(c->r[0]), sizeof g_info);
+        t->stop = 1;
+        return;
+    case HC_WAIT_WORK:
+        c->r[0] = wait_work();
+        return;
+    case HC_LOG:
+        log_write((int)c->r[0], c->r[1] ? (const char *)g2p(c->r[1]) : "", c->r[2] ? (const char *)g2p(c->r[2]) : "");
+        return;
+    case HC_UNRESOLVED:
+        unresolved((const char *)g2p(c->r[0]));
+        c->r[0] = c->r[1] = 0;
+        return;
+    case HC_ABORT:
+        bridge_log(ANDROID_LOG_FATAL, "guest runtime: %s", (const char *)g2p(c->r[0]));
+        abort();
+    }
+    if (n >= HC_JNI && n < HC_JNI + JNI_TABLE_SIZE && jni_dispatch(c, (int)(n - HC_JNI))) return;
+    if (n >= HC_VM && n < HC_VM + VM_TABLE_SIZE && vm_dispatch(c, (int)(n - HC_VM))) return;
+    if (n >= HC_GL && n < HC_GL + 0x1000) {
+        argreader R;
+        ar_init(&R, c, 0, c->r[13] + 8);
+        if (gl_dispatch(c, (int)(n - HC_GL), &R)) return;
+    }
+    if (n >= HC_IMPORT && n < HC_IMPORT + 0x100) {
+        argreader R;
+        ar_init(&R, c, 0, c->r[13] + 8); /* the stub pushed {r7, lr} */
+        if (import_dispatch(c, (int)(n - HC_IMPORT), &R)) return;
+        unresolved(import_names[n - HC_IMPORT]);
+        c->r[0] = c->r[1] = 0;
+        return;
+    }
+    bridge_log(ANDROID_LOG_ERROR, "unknown hypercall 0x%x", n);
+    c->r[0] = (uint32_t)-ENOSYS;
+}
+
+/* ---------------------------------------------------------------- start-up and libraries */
+
+extern char **environ;
+
+A32B_API int a32b_init(JavaVM *vm, const char *libdir)
+{
+    if (ready) return 0;
+    pthread_mutex_lock(&init_lock);
+    if (ready) {
+        pthread_mutex_unlock(&init_lock);
+        return 0;
+    }
+    g_vm = vm;
+    opt_bridge = 1;
+#ifndef A32B_STDERR_LOG
+    forward_stderr();
+#endif
+    if (getenv("A32_INTERP")) opt_interp = 1;
+    if (getenv("A32_STRACE")) opt_strace = 1;
+    if (getenv("A32_BREAK")) {
+        char *p = getenv("A32_BREAK");
+        for (int b = 0; b < 4 && *p; b++) {
+            a32_break_pc[b] = (uint32_t)strtoul(p, &p, 0);
+            if (*p == ',') p++;
+        }
+    }
+    if (getenv("A32_VERBOSE")) opt_verbose = 1;
+    a32_thread *t = thread_main();
+    g_self = t;
+    t->tid = (int)syscall(__NR_gettid);
+    t->cpu.thread = t;
+    int r = -1;
+    if (mem_init()) {
+        bridge_log(ANDROID_LOG_FATAL, "cannot set up the guest address space");
+        goto out;
+    }
+    signals_init();
+    static char rt[PATH_MAX], dir[PATH_MAX];
+    snprintf(dir, sizeof dir, "%s", libdir);
+    snprintf(rt, sizeof rt, "%s/liba32rt.so", libdir);
+    char *argv[] = {rt, dir, NULL};
+    load_args la = {rt, NULL, 2, argv, environ};
+    if (load_program(&la, &t->cpu)) {
+        bridge_log(ANDROID_LOG_FATAL, "cannot load the guest runtime %s", rt);
+        goto out;
+    }
+    t->cpu.thread = t;
+    run_guest(&t->cpu); /* until HC_READY */
+    if (g_info.version != A32B_VERSION) {
+        bridge_log(ANDROID_LOG_FATAL, "guest runtime version %u, bridge %u", g_info.version, A32B_VERSION);
+        goto out;
+    }
+    t->in_host = 1;
+    bridge_log(ANDROID_LOG_INFO, "guest runtime ready (%s, %s)", rt, opt_interp ? "interpreter" : "JIT");
+    if (getenv("A32_WATCH")) {
+        pthread_t w;
+        pthread_create(&w, NULL, watch, (void *)(intptr_t)atoi(getenv("A32_WATCH")));
+    }
+    ready = 1;
+    r = 0;
+out:
+    pthread_mutex_unlock(&init_lock);
+    return r;
+}
+
+static const char *base_name(const char *p)
+{
+    const char *s = strrchr(p, '/');
+    return s ? s + 1 : p;
+}
+
+A32B_API uint32_t a32b_load(const char *stub_path)
+{
+    if (!ready) return 0;
+    uint32_t name = guest_strdup(base_name(stub_path));
+    uint32_t w[2] = {name, 2 /* RTLD_NOW */};
+    uint32_t h = (uint32_t)guest_call(g_info.fn_dlopen, w, 2);
+    if (!h) {
+        uint32_t e = (uint32_t)guest_call(g_info.fn_dlerror, NULL, 0);
+        bridge_log(ANDROID_LOG_ERROR, "cannot load the guest library %s: %s", base_name(stub_path),
+                   e ? (const char *)g2p(e) : "?");
+    }
+    guest_free(name);
+    return h;
+}
+
+A32B_API uint32_t a32b_sym(uint32_t handle, const char *name)
+{
+    uint32_t gn = guest_strdup(name);
+    uint32_t w[2] = {handle, gn};
+    uint32_t a = (uint32_t)guest_call(g_info.fn_dlsym, w, 2);
+    guest_free(gn);
+    return a;
+}
+
+static int dir_of(const char *path, char *out, size_t n)
+{
+    const char *s = strrchr(path, '/');
+    if (!s) return snprintf(out, n, "."), 0;
+    snprintf(out, n, "%.*s", (int)(s - path), path);
+    return 0;
+}
+
+A32B_API jint a32b_jni_onload(JavaVM *vm, const char *stub_path)
+{
+    char dir[PATH_MAX];
+    dir_of(stub_path, dir, sizeof dir);
+    if (a32b_init(vm, dir)) return JNI_ERR;
+    uint32_t h = a32b_load(stub_path);
+    if (!h) return JNI_ERR;
+    jint ver = JNI_VERSION_1_6;
+    uint32_t fn = a32b_sym(h, "JNI_OnLoad");
+    if (fn) {
+        uint32_t w[2] = {g_info.java_vm, 0};
+        ver = (jint)guest_call(fn, w, 2);
+        bridge_log(ANDROID_LOG_INFO, "%s: JNI_OnLoad returned 0x%x", base_name(stub_path), ver);
+    }
+    JNIEnv *env = host_env();
+    if (env) natives_register_java(env, h, base_name(stub_path));
+    return ver;
+}
+
+A32B_API void a32b_native_activity_oncreate(struct ANativeActivity *activity, void *saved, size_t saved_size,
+                                            const char *stub_path)
+{
+    char dir[PATH_MAX];
+    dir_of(stub_path, dir, sizeof dir);
+    if (a32b_init(activity->vm, dir)) abort();
+    uint32_t h = a32b_load(stub_path);
+    uint32_t fn = h ? a32b_sym(h, "ANativeActivity_onCreate") : 0;
+    if (!fn) {
+        bridge_log(ANDROID_LOG_FATAL, "%s has no ANativeActivity_onCreate", base_name(stub_path));
+        abort();
+    }
+    activity_create(activity, saved, saved_size, fn);
+}
+
+/* A32_BREAK: where the guest came from */
+void a32_break_hit(a32_cpu *c)
+{
+    char what[40];
+    snprintf(what, sizeof what, "A32_BREAK %08x", c->r[15]);
+    guest_backtrace(c, what);
+}
@@ -0,0 +1,388 @@
+/* GLES/EGL for guest code: function lookup, GLsync handles, driver strings, buffer mappings, and the functions
+ * gen_gl.py leaves to hand-written code (pointer arrays, host pointers as results, callbacks). Everything else is
+ * generated (gen/gl.c). */
+#include <dlfcn.h>
+#include <stdlib.h>
+#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"
+
+static pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;
+
+/* ---------------------------------------------------------------- function lookup */
+
+#define MISSING ((void *)1)
+static void **fns;
+
+static void *lookup(const char *name)
+{
+    static void *gles, *egl;
+    static void *(*get_proc)(const char *);
+    if (!egl) {
+        egl = dlopen("libEGL.so", RTLD_NOW);
+        gles = dlopen("libGLESv3.so", RTLD_NOW);
+        if (!gles) gles = dlopen("libGLESv2.so", RTLD_NOW);
+        get_proc = egl ? (void *(*)(const char *))dlsym(egl, "eglGetProcAddress") : NULL;
+    }
+    void *f = gles ? dlsym(gles, name) : NULL;
+    if (!f && egl) f = dlsym(egl, name);
+    if (!f && get_proc) f = get_proc(name);
+    return f;
+}
+
+static void *fn_at(int index)
+{
+    void *f = __atomic_load_n(&fns[index], __ATOMIC_ACQUIRE);
+    if (!f) {
+        f = lookup(gl_names[index]);
+        if (!f) f = MISSING;
+        __atomic_store_n(&fns[index], f, __ATOMIC_RELEASE);
+    }
+    return f == MISSING ? NULL : f;
+}
+
+/* a host function by name, for the hand-written code */
+static void *host_fn(const char *name)
+{
+    for (int k = 0; k < gl_count; k++)
+        if (!strcmp(gl_names[k], name)) return fn_at(k);
+    return lookup(name);
+}
+
+static void once_per_name(const char *what, const char *name)
+{
+    static const char *seen[512];
+    static int n;
+    pthread_mutex_lock(&lock);
+    for (int k = 0; k < n; k++)
+        if (seen[k] == name) {
+            pthread_mutex_unlock(&lock);
+            return;
+        }
+    if (n < 512) seen[n++] = name;
+    pthread_mutex_unlock(&lock);
+    bridge_log(ANDROID_LOG_WARN, "%s %s (returned 0)", what, name);
+}
+
+int gl_dispatch(a32_cpu *c, int index, argreader *R)
+{
+    if (index < 0 || index >= gl_count) return 0;
+    if (!fns) {
+        pthread_mutex_lock(&lock);
+        if (!fns) fns = calloc((size_t)gl_count, sizeof *fns);
+        pthread_mutex_unlock(&lock);
+    }
+    void *f = fn_at(index);
+    if (f && gl_dispatch_generated(c, index, R, f)) return 1;
+    once_per_name(f ? "the bridge doesn't support" : "the system has no", gl_names[index]);
+    c->r[0] = c->r[1] = 0;
+    return 1;
+}
+
+/* ---------------------------------------------------------------- GLsync handles */
+
+static void **syncs;
+static uint32_t nsyncs, capsyncs, sync_free_list; /* index + 1 */
+
+uint32_t sync2h(void *s)
+{
+    if (!s) return 0;
+    pthread_mutex_lock(&lock);
+    uint32_t i;
+    if (sync_free_list) {
+        i = sync_free_list - 1;
+        sync_free_list = (uint32_t)(uintptr_t)syncs[i];
+    } else {
+        if (nsyncs == capsyncs) syncs = realloc(syncs, (capsyncs = capsyncs ? capsyncs * 2 : 64) * sizeof *syncs);
+        i = nsyncs++;
+    }
+    syncs[i] = s;
+    pthread_mutex_unlock(&lock);
+    return (i + 1) << 2 | 1; /* odd: never mistaken for another kind of handle in logs */
+}
+
+void *h2sync(uint32_t h)
+{
+    if (!h) return NULL;
+    uint32_t i = (h >> 2) - 1;
+    pthread_mutex_lock(&lock);
+    void *s = i < nsyncs ? syncs[i] : NULL;
+    pthread_mutex_unlock(&lock);
+    return s;
+}
+
+static void sync_release(uint32_t h)
+{
+    uint32_t i = (h >> 2) - 1;
+    pthread_mutex_lock(&lock);
+    if (h && i < nsyncs) {
+        syncs[i] = (void *)(uintptr_t)sync_free_list;
+        sync_free_list = i + 1;
+    }
+    pthread_mutex_unlock(&lock);
+}
+
+void gl_glDeleteSync(a32_cpu *c, argreader *R, void *fn)
+{
+    uint32_t h = rd32(R);
+    ((__typeof__(&glDeleteSync))fn)((GLsync)h2sync(h));
+    sync_release(h);
+}
+
+/* ---------------------------------------------------------------- strings */
+
+uint32_t gl_guest_string(const char *s) { return guest_cstr(s); }
+
+void gl_glGetString(a32_cpu *c, argreader *R, void *fn)
+{
+    GLenum name = (GLenum)rd32(R);
+    ret32(c, gl_guest_string((const char *)((__typeof__(&glGetString))fn)(name)));
+}
+
+void gl_glGetStringi(a32_cpu *c, argreader *R, void *fn)
+{
+    GLenum name = (GLenum)rd32(R);
+    GLuint index = (GLuint)rd32(R);
+    ret32(c, gl_guest_string((const char *)((__typeof__(&glGetStringi))fn)(name, index)));
+}
+
+void gl_eglQueryString(a32_cpu *c, argreader *R, void *fn)
+{
+    EGLDisplay dpy = h2ptr(rd32(R));
+    EGLint name = (EGLint)rd32(R);
+    ret32(c, gl_guest_string(((__typeof__(&eglQueryString))fn)(dpy, name)));
+}
+
+/* ---------------------------------------------------------------- pointer arrays */
+
+static const GLchar **string_array(uint32_t g, GLsizei n)
+{
+    const GLchar **v = calloc(n > 0 ? (size_t)n : 1, sizeof *v);
+    for (GLsizei k = 0; k < n; k++) v[k] = g2p(ld32(g + 4u * (uint32_t)k));
+    return v;
+}
+
+void gl_glShaderSource(a32_cpu *c, argreader *R, void *fn)
+{
+    GLuint shader = rd32(R);
+    GLsizei count = (GLsizei)rd32(R);
+    uint32_t strings = rd32(R);
+    const GLint *length = g2p(rd32(R));
+    const GLchar **v = string_array(strings, count);
+    ((__typeof__(&glShaderSource))fn)(shader, count, v, length);
+    free(v);
+}
+
+void gl_glTransformFeedbackVaryings(a32_cpu *c, argreader *R, void *fn)
+{
+    GLuint program = rd32(R);
+    GLsizei count = (GLsizei)rd32(R);
+    const GLchar **v = string_array(rd32(R), count);
+    GLenum mode = rd32(R);
+    ((__typeof__(&glTransformFeedbackVaryings))fn)(program, count, v, mode);
+    free(v);
+}
+
+void gl_glGetUniformIndices(a32_cpu *c, argreader *R, void *fn)
+{
+    GLuint program = rd32(R);
+    GLsizei count = (GLsizei)rd32(R);
+    const GLchar **v = string_array(rd32(R), count);
+    GLuint *indices = g2p(rd32(R));
+    ((__typeof__(&glGetUniformIndices))fn)(program, count, v, indices);
+    free(v);
+}
+
+static void configs_out(uint32_t gconfigs, EGLConfig *cfg, EGLint n)
+{
+    for (EGLint k = 0; k < n; k++) st32(gconfigs + 4u * (uint32_t)k, ptr2h(cfg[k]));
+}
+
+void gl_eglChooseConfig(a32_cpu *c, argreader *R, void *fn)
+{
+    EGLDisplay dpy = h2ptr(rd32(R));
+    const EGLint *attrib = g2p(rd32(R));
+    uint32_t gconfigs = rd32(R);
+    EGLint size = (EGLint)rd32(R);
+    EGLint *num = g2p(rd32(R));
+    EGLConfig *cfg = gconfigs && size > 0 ? calloc((size_t)size, sizeof *cfg) : NULL;
+    EGLBoolean r = ((__typeof__(&eglChooseConfig))fn)(dpy, attrib, cfg, cfg ? size : 0, num);
+    if (r && cfg) configs_out(gconfigs, cfg, *num < size ? *num : size);
+    free(cfg);
+    ret32(c, r);
+}
+
+void gl_eglGetConfigs(a32_cpu *c, argreader *R, void *fn)
+{
+    EGLDisplay dpy = h2ptr(rd32(R));
+    uint32_t gconfigs = rd32(R);
+    EGLint size = (EGLint)rd32(R);
+    EGLint *num = g2p(rd32(R));
+    EGLConfig *cfg = gconfigs && size > 0 ? calloc((size_t)size, sizeof *cfg) : NULL;
+    EGLBoolean r = ((__typeof__(&eglGetConfigs))fn)(dpy, cfg, cfg ? size : 0, num);
+    if (r && cfg) configs_out(gconfigs, cfg, *num < size ? *num : size);
+    free(cfg);
+    ret32(c, r);
+}
+
+/* ---------------------------------------------------------------- callbacks */
+
+void gl_glDebugMessageCallback(a32_cpu *c, argreader *R, void *fn)
+{
+    (void)c, (void)R, (void)fn;
+    once_per_name("ignored (guest callbacks aren't supported yet):", "glDebugMessageCallback");
+}
+
+void gl_glDebugMessageCallbackKHR(a32_cpu *c, argreader *R, void *fn) { gl_glDebugMessageCallback(c, R, fn); }
+
+/* ---------------------------------------------------------------- buffer mappings */
+
+/* A mapping the guest can't reach (driver memory above 4 GiB) gets a guest copy: filled when mapped for reading,
+ * written back at flush/unmap when mapped for writing. One per (context, buffer object): GL maps buffers, not
+ * targets, and an app may keep several buffers of one target mapped (Unity's dynamic vertex buffers); keyed by the
+ * target, a second map dropped the first one's copy (never freed, never written back: garbage vertices). */
+typedef struct {
+    EGLContext ctx;
+    GLuint buffer;
+    uint8_t *host;
+    uint32_t guest;
+    uint32_t len;
+    GLbitfield access;
+} mapping;
+
+#define MAX_MAPS 256
+static mapping maps[MAX_MAPS];
+
+static mapping *find_map(EGLContext ctx, GLuint buffer)
+{
+    for (int k = 0; k < MAX_MAPS; k++)
+        if (maps[k].host && maps[k].ctx == ctx && maps[k].buffer == buffer) return &maps[k];
+    return NULL;
+}
+
+static EGLContext current_context(void)
+{
+    static __typeof__(&eglGetCurrentContext) f;
+    if (!f) f = (__typeof__(f))host_fn("eglGetCurrentContext");
+    return f ? f() : NULL;
+}
+
+/* the buffer object bound to a buffer target */
+static GLuint bound_buffer(GLenum target)
+{
+    GLenum binding;
+    switch (target) {
+    case 0x8892: binding = 0x8894; break; /* ARRAY_BUFFER */
+    case 0x8893: binding = 0x8895; break; /* ELEMENT_ARRAY_BUFFER */
+    case 0x8A11: binding = 0x8A28; break; /* UNIFORM_BUFFER */
+    case 0x88EB: binding = 0x88ED; break; /* PIXEL_PACK_BUFFER */
+    case 0x88EC: binding = 0x88EF; break; /* PIXEL_UNPACK_BUFFER */
+    case 0x8C8E: binding = 0x8C8F; break; /* TRANSFORM_FEEDBACK_BUFFER */
+    case 0x90D2: binding = 0x90D3; break; /* SHADER_STORAGE_BUFFER */
+    case 0x8F3F: binding = 0x8F43; break; /* DRAW_INDIRECT_BUFFER */
+    case 0x90EE: binding = 0x90EF; break; /* DISPATCH_INDIRECT_BUFFER */
+    case 0x92C0: binding = 0x92C1; break; /* ATOMIC_COUNTER_BUFFER */
+    case 0x8C2A: binding = 0x8C2C; break; /* TEXTURE_BUFFER */
+    default: binding = target; break;     /* COPY_READ/WRITE_BUFFER: the binding has the target's value */
+    }
+    static __typeof__(&glGetIntegerv) gi;
+    if (!gi) gi = (__typeof__(gi))host_fn("glGetIntegerv");
+    GLint name = 0;
+    if (gi) gi(binding, &name);
+    return (GLuint)name;
+}
+
+static uint32_t map_result(GLenum target, void *p, uint32_t len, GLbitfield access)
+{
+    if (!p) return 0;
+    if (in_guest_reach(p, len)) return p2g(p);
+    uint32_t g = guest_malloc(len ? len : 1);
+    if (!g) return 0;
+    if (access & GL_MAP_READ_BIT) memcpy(g2p(g), p, len);
+    GLuint buffer = bound_buffer(target);
+    uint32_t stale = 0;
+    pthread_mutex_lock(&lock);
+    EGLContext ctx = current_context();
+    mapping *m = find_map(ctx, buffer);
+    if (m) stale = m->guest; /* mapped again without an unmap (the GL error case): the old copy goes */
+    if (!m)
+        for (int k = 0; k < MAX_MAPS && !m; k++)
+            if (!maps[k].host) m = &maps[k];
+    if (m) *m = (mapping){ctx, buffer, p, g, len, access};
+    pthread_mutex_unlock(&lock);
+    if (stale) guest_free(stale);
+    if (!m) {
+        static int full;
+        if (!full++) bridge_log(ANDROID_LOG_ERROR, "glMapBuffer: more than %d buffers mapped at once", MAX_MAPS);
+        guest_free(g);
+        return 0;
+    }
+    return g;
+}
+
+void gl_glMapBufferRange(a32_cpu *c, argreader *R, void *fn)
+{
+    GLenum target = rd32(R);
+    GLintptr offset = (int32_t)rd32(R);
+    GLsizeiptr length = (int32_t)rd32(R);
+    GLbitfield access = rd32(R);
+    void *p = ((__typeof__(&glMapBufferRange))fn)(target, offset, length, access);
+    ret32(c, map_result(target, p, (uint32_t)length, access));
+}
+
+void gl_glMapBufferRangeEXT(a32_cpu *c, argreader *R, void *fn) { gl_glMapBufferRange(c, R, fn); }
+
+void gl_glMapBufferOES(a32_cpu *c, argreader *R, void *fn)
+{
+    GLenum target = rd32(R);
+    GLenum access = rd32(R);
+    GLint size = 0;
+    __typeof__(&glGetBufferParameteriv) gp = (__typeof__(gp))host_fn("glGetBufferParameteriv");
+    if (gp) gp(target, GL_BUFFER_SIZE, &size);
+    void *p = ((__typeof__(&glMapBufferOES))fn)(target, access);
+    ret32(c, map_result(target, p, (uint32_t)size, GL_MAP_READ_BIT | GL_MAP_WRITE_BIT));
+}
+
+/* copies a mapping's guest data back (whole range, or [off, off+len) for an explicit flush) */
+static void write_back(GLenum target, uint32_t off, uint32_t len, int unmap)
+{
+    GLuint buffer = bound_buffer(target);
+    pthread_mutex_lock(&lock);
+    mapping *m = find_map(current_context(), buffer);
+    mapping copy;
+    if (m) {
+        copy = *m;
+        if (unmap) m->host = NULL;
+    }
+    pthread_mutex_unlock(&lock);
+    if (!m) return;
+    if (copy.access & GL_MAP_WRITE_BIT) {
+        if (unmap) off = 0, len = copy.len;
+        if (off < copy.len) memcpy(copy.host + off, g2p(copy.guest + off), len > copy.len - off ? copy.len - off : len);
+    }
+    if (unmap) guest_free(copy.guest);
+}
+
+void gl_glFlushMappedBufferRange(a32_cpu *c, argreader *R, void *fn)
+{
+    GLenum target = rd32(R);
+    GLintptr offset = (int32_t)rd32(R);
+    GLsizeiptr length = (int32_t)rd32(R);
+    write_back(target, (uint32_t)offset, (uint32_t)length, 0);
+    ((__typeof__(&glFlushMappedBufferRange))fn)(target, offset, length);
+}
+
+void gl_glFlushMappedBufferRangeEXT(a32_cpu *c, argreader *R, void *fn) { gl_glFlushMappedBufferRange(c, R, fn); }
+
+void gl_glUnmapBuffer(a32_cpu *c, argreader *R, void *fn)
+{
+    GLenum target = rd32(R);
+    write_back(target, 0, 0, 1);
+    ret32(c, ((__typeof__(&glUnmapBuffer))fn)(target));
+}
+
+void gl_glUnmapBufferOES(a32_cpu *c, argreader *R, void *fn) { gl_glUnmapBuffer(c, R, fn); }
@@ -0,0 +1,17 @@
+/* GLES/EGL for guest code (gl.c, gen/gl.c). */
+#ifndef A32B_GL_INTERNAL_H
+#define A32B_GL_INTERNAL_H
+
+#include "imports_internal.h"
+
+/* gen/gl.c */
+extern const int gl_count;
+extern const char *const gl_names[];
+int gl_dispatch_generated(a32_cpu *c, int index, argreader *R, void *fn);
+
+/* gl.c */
+uint32_t sync2h(void *s); /* GLsync handles: freed by glDeleteSync */
+void *h2sync(uint32_t h);
+uint32_t gl_guest_string(const char *s); /* a guest copy of a driver string (kept for good) */
+
+#endif
@@ -0,0 +1,191 @@
+/* Handle tables: 32-bit guest values for 64-bit host references, method/field IDs and other pointers. */
+#include <pthread.h>
+#include <stdlib.h>
+#include "jni_internal.h"
+
+enum { K_FREE, K_LOCAL, K_GLOBAL, K_WEAK, K_KEEP };
+
+typedef struct {
+    void *p;
+    uint32_t serial;
+    uint8_t kind;
+} slot;
+
+static pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;
+static slot *objs;
+static uint32_t nobjs, capobjs, freelist = 0; /* freelist: index + 1 of a free slot (p holds the next) */
+static uint32_t serial_ctr;
+
+/* per thread: the local handles created on it (index, serial), popped with the native frame */
+static __thread struct { uint32_t *v; uint32_t n, cap; } locals;
+
+static uint32_t new_obj(void *p, uint8_t kind)
+{
+    if (!p) return 0;
+    pthread_mutex_lock(&lock);
+    uint32_t i;
+    if (freelist) {
+        i = freelist - 1;
+        freelist = (uint32_t)(uintptr_t)objs[i].p;
+    } else {
+        if (nobjs == capobjs) {
+            capobjs = capobjs ? capobjs * 2 : 1024;
+            objs = realloc(objs, capobjs * sizeof *objs);
+        }
+        i = nobjs++;
+    }
+    objs[i].p = p;
+    objs[i].kind = kind;
+    objs[i].serial = ++serial_ctr;
+    uint32_t serial = objs[i].serial;
+    pthread_mutex_unlock(&lock);
+    if (kind == K_LOCAL) {
+        if (locals.n + 2 > locals.cap) {
+            locals.cap = locals.cap ? locals.cap * 2 : 256;
+            locals.v = realloc(locals.v, locals.cap * sizeof *locals.v);
+        }
+        locals.v[locals.n++] = i;
+        locals.v[locals.n++] = serial;
+    }
+    return (i + 1) << 2;
+}
+
+uint32_t o2h_local(jobject o) { return new_obj(o, K_LOCAL); }
+uint32_t o2h_global(jobject o) { return new_obj(o, K_GLOBAL); }
+uint32_t o2h_weak(jobject o) { return new_obj(o, K_WEAK); }
+uint32_t o2h_keep(jobject o) { return new_obj(o, K_KEEP); }
+
+jobject h2o(uint32_t h)
+{
+    if (!h) return NULL;
+    uint32_t i = (h >> 2) - 1;
+    pthread_mutex_lock(&lock);
+    void *p = i < nobjs && objs[i].kind != K_FREE ? objs[i].p : NULL;
+    pthread_mutex_unlock(&lock);
+    if (!p) bridge_log(6, "invalid object handle 0x%x", h);
+    return p;
+}
+
+static void free_slot(uint32_t i)
+{
+    objs[i].kind = K_FREE;
+    objs[i].p = (void *)(uintptr_t)freelist;
+    freelist = i + 1;
+}
+
+void h_free(uint32_t h)
+{
+    if (!h) return;
+    uint32_t i = (h >> 2) - 1;
+    pthread_mutex_lock(&lock);
+    if (i < nobjs && objs[i].kind != K_FREE) free_slot(i);
+    pthread_mutex_unlock(&lock);
+}
+
+uint32_t frame_mark(void) { return locals.n; }
+
+void frame_pop(uint32_t mark)
+{
+    if (locals.n <= mark) return;
+    pthread_mutex_lock(&lock);
+    for (uint32_t k = mark; k + 1 < locals.n; k += 2) {
+        uint32_t i = locals.v[k], serial = locals.v[k + 1];
+        if (i < nobjs && objs[i].kind == K_LOCAL && objs[i].serial == serial) free_slot(i);
+    }
+    pthread_mutex_unlock(&lock);
+    locals.n = mark;
+}
+
+/* ---------------------------------------------------------------- IDs and pointers: stable, never freed */
+
+typedef struct {
+    void *p;
+    char *shorty;
+} idslot;
+
+typedef struct {
+    idslot *v;
+    uint32_t n, cap;
+    uint32_t *hash; /* open addressing: index + 1 */
+    uint32_t hcap;
+} idtab;
+
+static idtab mids, fids, ptrs;
+
+static uint32_t hashp(void *p) { return (uint32_t)(((uintptr_t)p * 0x9e3779b97f4a7c15ull) >> 32); }
+
+static uint32_t id_get(idtab *t, void *p)
+{
+    if (!p) return 0;
+    pthread_mutex_lock(&lock);
+    if (t->n * 2 >= t->hcap) {
+        uint32_t nc = t->hcap ? t->hcap * 2 : 1024;
+        uint32_t *nh = calloc(nc, 4);
+        for (uint32_t k = 0; k < t->n; k++) {
+            uint32_t j = hashp(t->v[k].p) & (nc - 1);
+            while (nh[j]) j = (j + 1) & (nc - 1);
+            nh[j] = k + 1;
+        }
+        free(t->hash);
+        t->hash = nh;
+        t->hcap = nc;
+    }
+    uint32_t j = hashp(p) & (t->hcap - 1);
+    while (t->hash[j]) {
+        if (t->v[t->hash[j] - 1].p == p) {
+            uint32_t h = t->hash[j] << 2;
+            pthread_mutex_unlock(&lock);
+            return h;
+        }
+        j = (j + 1) & (t->hcap - 1);
+    }
+    if (t->n == t->cap) {
+        t->cap = t->cap ? t->cap * 2 : 512;
+        t->v = realloc(t->v, t->cap * sizeof *t->v);
+    }
+    t->v[t->n].p = p;
+    t->v[t->n].shorty = NULL;
+    t->hash[j] = ++t->n;
+    uint32_t h = t->n << 2;
+    pthread_mutex_unlock(&lock);
+    return h;
+}
+
+static idslot *id_slot(idtab *t, uint32_t h)
+{
+    uint32_t i = (h >> 2) - 1;
+    return h && i < t->n ? &t->v[i] : NULL;
+}
+
+static void *id_ptr(idtab *t, uint32_t h)
+{
+    pthread_mutex_lock(&lock);
+    idslot *s = id_slot(t, h);
+    void *p = s ? s->p : NULL;
+    pthread_mutex_unlock(&lock);
+    return p;
+}
+
+uint32_t mid2h(jmethodID m) { return id_get(&mids, m); }
+jmethodID h2mid(uint32_t h) { return id_ptr(&mids, h); }
+uint32_t fid2h(jfieldID f) { return id_get(&fids, f); }
+jfieldID h2fid(uint32_t h) { return id_ptr(&fids, h); }
+uint32_t ptr2h(void *p) { return id_get(&ptrs, p); }
+void *h2ptr(uint32_t h) { return id_ptr(&ptrs, h); }
+
+void mid_set_shorty(uint32_t h, const char *shorty)
+{
+    pthread_mutex_lock(&lock);
+    idslot *s = id_slot(&mids, h);
+    if (s && !s->shorty) s->shorty = strdup(shorty);
+    pthread_mutex_unlock(&lock);
+}
+
+const char *mid_shorty(uint32_t h)
+{
+    pthread_mutex_lock(&lock);
+    idslot *s = id_slot(&mids, h);
+    const char *r = s ? s->shorty : NULL;
+    pthread_mutex_unlock(&lock);
+    return r;
+}
@@ -0,0 +1,37 @@
+/* Host side of the bridge: libandroid imports, NativeActivity glue and native method registration. */
+#ifndef A32B_IMPORTS_INTERNAL_H
+#define A32B_IMPORTS_INTERNAL_H
+
+#include <android/native_activity.h>
+#include <android/native_window.h>
+#include "jni_internal.h"
+
+/* bridge.c: logs the current guest call's caller (lib+offset) and the return addresses on its stack */
+void guest_backtrace(a32_cpu *c, const char *what);
+
+/* gen/imports.c (from imports.txt) */
+int import_dispatch(a32_cpu *c, int index, argreader *R);
+extern const char *const import_names[];
+
+/* gl.c: GLES/EGL (HC_GL + index); 0 if the function is unknown */
+int gl_dispatch(a32_cpu *c, int index, argreader *R);
+
+/* native_activity.c */
+ANativeActivity *guest_activity(uint32_t g); /* the host activity behind a guest ANativeActivity * */
+void activity_create(ANativeActivity *a, void *saved, size_t saved_size, uint32_t oncreate);
+extern volatile int g_window_w, g_window_h; /* the activity's window size (0 before it exists) */
+
+/* input.c: synthetic input events for NativeActivity guests (Unreal: native_app_glue reads its AInputQueue) */
+void input_queue_attached(void *queue, void *looper, int ident, uint32_t data, int has_callback);
+void input_queue_detached(void *queue);
+/* a synthetic event is waiting for the queue attached to this looper: its ident and guest poll data */
+int input_queue_pending(void *looper, int *ident, uint32_t *data);
+void *input_queue_pop(void *queue); /* the next synthetic AInputEvent of this queue, or NULL */
+
+/* natives.c: registers the exported Java_* functions of a guest library with their classes */
+void natives_register_java(JNIEnv *env, uint32_t handle, const char *libname);
+/* a host function pointer that calls guest function fn with the JNI signature sig ("(IJ)V") */
+void *natives_trampoline(uint32_t fn, const char *sig);
+void *natives_trampoline_named(uint32_t fn, const char *sig, const char *name); /* name: for tracing */
+
+#endif
@@ -0,0 +1,568 @@
+/* Controller input for Gear VR-era games. They read the headset's touchpad and back button and Bluetooth gamepads
+ * as Android input events (Unity: mouse/touch, Escape, joystick buttons and axes). A thread polls the Frame's
+ * controllers through the 64-bit VrApi bridge and turns them into such events, handed to the game the way Android
+ * would: NativeActivity games (Unreal, native_app_glue) get them in their AInputQueue (synthetic AInputEvents the
+ * AInputQueue, AInputEvent, AKeyEvent and AMotionEvent imports know), Unity games through
+ * UnityPlayer.injectEvent, others through the activity's dispatchKeyEvent. Off with A32_NO_INPUT=1.
+ *
+ * Gear VR had a touchpad on the headset (tap, hold, swipe) and a back button; games that took a gamepad read it too:
+ *   right trigger -> touchpad held (Gear VR games: walk), A -> a short tap
+ *   right stick   -> a swipe in that direction (flick it); NativeActivity games: up/down = swipe forward/back
+ *   B, left menu  -> back (Unity: Escape)
+ *   X, Y, sticks  -> gamepad X/Y, joystick axes X/Y (left) and Z/RZ (right), as a real gamepad if there is one */
+#include <android/input.h>
+#include <android/looper.h>
+#include <stdlib.h>
+#include <time.h>
+#include <unistd.h>
+#include "imports_internal.h"
+
+/* weak like the generated imports (the PC test harness has no libandroid) */
+#define W(f) extern __typeof__(f) f __attribute__((weak))
+W(ALooper_wake); W(AInputQueue_detachLooper); W(AInputQueue_hasEvents); W(AInputQueue_preDispatchEvent);
+W(AInputQueue_finishEvent); W(AInputEvent_getType); W(AInputEvent_getDeviceId); W(AInputEvent_getSource);
+W(AKeyEvent_getAction); W(AKeyEvent_getKeyCode); W(AKeyEvent_getMetaState); W(AKeyEvent_getRepeatCount); W(AKeyEvent_getFlags);
+W(AMotionEvent_getAction); W(AMotionEvent_getPointerCount); W(AMotionEvent_getPointerId); W(AMotionEvent_getX);
+W(AMotionEvent_getY); W(AMotionEvent_getRawX); W(AMotionEvent_getRawY); W(AMotionEvent_getAxisValue);
+W(AMotionEvent_getButtonState);
+#undef W
+
+typedef struct { int32_t Type; uint32_t DeviceID; } caps_header;
+typedef struct {
+    caps_header Header;
+    uint32_t ControllerCapabilities, ButtonCapabilities;
+    uint16_t TrackpadMaxX, TrackpadMaxY;
+    float TrackpadSizeX, TrackpadSizeY;
+    uint32_t HapticSamplesMax, HapticSampleDurationMS, TouchCapabilities, Reserved4, Reserved5;
+} remote_caps;
+typedef struct {
+    int32_t ControllerType;
+    double TimeInSeconds;
+    uint32_t Buttons, TrackpadStatus;
+    float TrackpadPosition[2];
+    uint8_t Battery, RecenterCount;
+    uint16_t Reserved;
+    float IndexTrigger, GripTrigger;
+    uint32_t Touches, Reserved5a;
+    float Joystick[2], JoystickNoDeadZone[2];
+} remote_state;
+_Static_assert(sizeof(remote_caps) == 48 && sizeof(remote_state) == 72, "VrApi input ABI");
+
+#define TRACKED_REMOTE 4
+#define LEFT_HAND 4u
+#define B_A 0x1u
+#define B_B 0x2u
+#define B_RTHUMB 0x4u
+#define B_X 0x100u
+#define B_Y 0x200u
+#define B_LTHUMB 0x400u
+#define B_ENTER 0x100000u
+
+/* android.view.KeyEvent / MotionEvent / InputDevice constants */
+#define KEY_DOWN 0
+#define KEY_UP 1
+#define KEYCODE_BACK 4
+#define KEYCODE_BUTTON_A 96
+#define KEYCODE_BUTTON_B 97
+#define KEYCODE_BUTTON_X 99
+#define KEYCODE_BUTTON_Y 100
+#define KEYCODE_BUTTON_THUMBL 106
+#define KEYCODE_BUTTON_THUMBR 107
+#define SOURCE_KEYBOARD 0x101
+#define SOURCE_GAMEPAD 0x401
+#define SOURCE_TOUCHSCREEN 0x1002
+#define SOURCE_JOYSTICK 0x1000010
+#define ACTION_DOWN 0
+#define ACTION_UP 1
+#define ACTION_MOVE 2
+#define AXIS_X 0
+#define AXIS_Y 1
+#define AXIS_Z 11
+#define AXIS_RZ 14
+
+typedef struct {
+    int (*enumerate)(void *, uint32_t, caps_header *);
+    int (*caps)(void *, caps_header *);
+    int (*state)(void *, uint32_t, remote_state *);
+} input_api;
+
+extern int a32_remote_in_use; /* vrapi.c */
+
+static struct {
+    void *mobile;
+    input_api api;
+    jobject activity, target; /* target: the UnityPlayer, else the activity */
+    jmethodID inject;         /* UnityPlayer.injectEvent(InputEvent), else Activity.dispatchKeyEvent */
+    int unity, java;          /* java: the Java delivery is set up */
+    jclass key_class, motion_class, coords_class, props_class, clock_class;
+    jmethodID key_init, motion_obtain, motion_obtain_full, motion_set_source, motion_recycle, coords_init,
+        coords_set_axis, props_init, uptime;
+    jfieldID props_id, props_tool;
+    volatile int running, gen; /* gen: a new input_start ends the previous thread */
+    int gamepad_id; /* an Android input device with gamepad buttons, or 0 */
+} I;
+
+/* ---------------------------------------------------------------- synthetic AInputEvents (NativeActivity) */
+
+/* native_app_glue attaches the activity's AInputQueue to its looper without a callback and polls it; the bridge
+ * puts its own events in front of the queue's: pollAll/pollOnce return the queue's ident while one waits (an
+ * ALooper_wake ends a blocking poll), AInputQueue_getEvent hands it out, finishEvent frees it. */
+#define NFAKE 256
+#define TOUCH_DEVICE 1 /* the Gear VR touchpad's device ID, as the game sees it */
+
+typedef struct {
+    int used, type, source, device, action, code;
+    float x, y;
+} fake_event;
+
+static fake_event pool[NFAKE];
+static int fifo[NFAKE], fifo_head, fifo_count, pool_next;
+static pthread_mutex_t nq_lock = PTHREAD_MUTEX_INITIALIZER;
+static struct {
+    void *queue, *looper;
+    int ident;
+    uint32_t data;
+} NQ;
+
+static int is_fake(const void *p) { return (const char *)p >= (const char *)pool && (const char *)p < (const char *)(pool + NFAKE); }
+static int native_active(void) { return NQ.queue != NULL; }
+
+void input_queue_attached(void *queue, void *looper, int ident, uint32_t data, int has_callback)
+{
+    if (has_callback) {
+        bridge_log(ANDROID_LOG_WARN, "controllers: input queue attached with a callback: synthetic events not supported");
+        return;
+    }
+    pthread_mutex_lock(&nq_lock);
+    NQ.queue = queue, NQ.looper = looper, NQ.ident = ident, NQ.data = data;
+    pthread_mutex_unlock(&nq_lock);
+    bridge_log(ANDROID_LOG_INFO, "controllers: the game reads its AInputQueue (ident %d): Gear VR touchpad events go there", ident);
+}
+
+void input_queue_detached(void *queue)
+{
+    pthread_mutex_lock(&nq_lock);
+    if (NQ.queue == queue) {
+        memset(&NQ, 0, sizeof NQ);
+        for (int k = 0; k < NFAKE; k++) pool[k].used = 0;
+        fifo_count = 0;
+    }
+    pthread_mutex_unlock(&nq_lock);
+}
+
+static void native_push(int type, int source, int device, int action, int code, float x, float y)
+{
+    pthread_mutex_lock(&nq_lock);
+    void *looper = NQ.looper;
+    fake_event *e = NULL;
+    for (int k = 0; k < NFAKE && NQ.queue && fifo_count < NFAKE; k++) {
+        int i = (pool_next + k) % NFAKE;
+        if (pool[i].used) continue;
+        e = &pool[i];
+        pool_next = (i + 1) % NFAKE;
+        fifo[(fifo_head + fifo_count++) % NFAKE] = i;
+        break;
+    }
+    if (e) *e = (fake_event){1, type, source, device, action, code, x, y};
+    pthread_mutex_unlock(&nq_lock);
+    if (e && looper && ALooper_wake) ALooper_wake(looper);
+}
+
+int input_queue_pending(void *looper, int *ident, uint32_t *data)
+{
+    pthread_mutex_lock(&nq_lock);
+    int r = NQ.queue && looper && NQ.looper == looper && fifo_count > 0;
+    if (r) *ident = NQ.ident, *data = NQ.data;
+    pthread_mutex_unlock(&nq_lock);
+    return r;
+}
+
+void *input_queue_pop(void *queue)
+{
+    void *e = NULL;
+    pthread_mutex_lock(&nq_lock);
+    if (queue && queue == NQ.queue && fifo_count > 0) {
+        e = &pool[fifo[fifo_head]];
+        fifo_head = (fifo_head + 1) % NFAKE;
+        fifo_count--;
+    }
+    pthread_mutex_unlock(&nq_lock);
+    return e;
+}
+
+static int queue_has_fake(void *queue)
+{
+    pthread_mutex_lock(&nq_lock);
+    int r = queue && queue == NQ.queue && fifo_count > 0;
+    pthread_mutex_unlock(&nq_lock);
+    return r;
+}
+
+/* the guest's view of the queue and events (imports.txt "!" lines) */
+void imp_AInputQueue_detachLooper(a32_cpu *c, argreader *R)
+{
+    AInputQueue *q = h2ptr(rd32(R));
+    input_queue_detached(q);
+    if (q && AInputQueue_detachLooper) AInputQueue_detachLooper(q);
+}
+
+void imp_AInputQueue_hasEvents(a32_cpu *c, argreader *R)
+{
+    AInputQueue *q = h2ptr(rd32(R));
+    ret32(c, queue_has_fake(q) ? 1u : q && AInputQueue_hasEvents ? (uint32_t)AInputQueue_hasEvents(q) : 0u);
+}
+
+void imp_AInputQueue_preDispatchEvent(a32_cpu *c, argreader *R)
+{
+    AInputQueue *q = h2ptr(rd32(R));
+    AInputEvent *e = h2ptr(rd32(R));
+    ret32(c, is_fake(e) || !q || !e || !AInputQueue_preDispatchEvent ? 0u : (uint32_t)AInputQueue_preDispatchEvent(q, e));
+}
+
+void imp_AInputQueue_finishEvent(a32_cpu *c, argreader *R)
+{
+    AInputQueue *q = h2ptr(rd32(R));
+    AInputEvent *e = h2ptr(rd32(R));
+    int handled = (int)rd32(R);
+    if (is_fake(e)) {
+        pthread_mutex_lock(&nq_lock);
+        ((fake_event *)e)->used = 0;
+        pthread_mutex_unlock(&nq_lock);
+    } else if (q && e && AInputQueue_finishEvent) {
+        AInputQueue_finishEvent(q, e, handled);
+    }
+}
+
+#define EV(fn, member)                                                          \
+    void imp_##fn(a32_cpu *c, argreader *R)                                     \
+    {                                                                           \
+        const AInputEvent *e = h2ptr(rd32(R));                                  \
+        ret32(c, is_fake(e) ? (uint32_t)((const fake_event *)e)->member        \
+                 : e && fn ? (uint32_t)fn(e) : 0u);                             \
+    }
+EV(AInputEvent_getType, type)
+EV(AInputEvent_getDeviceId, device)
+EV(AInputEvent_getSource, source)
+EV(AKeyEvent_getAction, action)
+EV(AKeyEvent_getKeyCode, code)
+EV(AMotionEvent_getAction, action)
+#undef EV
+
+void imp_AKeyEvent_getMetaState(a32_cpu *c, argreader *R)
+{
+    const AInputEvent *e = h2ptr(rd32(R));
+    ret32(c, is_fake(e) || !e || !AKeyEvent_getMetaState ? 0u : (uint32_t)AKeyEvent_getMetaState(e));
+}
+
+void imp_AKeyEvent_getRepeatCount(a32_cpu *c, argreader *R)
+{
+    const AInputEvent *e = h2ptr(rd32(R));
+    ret32(c, is_fake(e) || !e || !AKeyEvent_getRepeatCount ? 0u : (uint32_t)AKeyEvent_getRepeatCount(e));
+}
+
+void imp_AKeyEvent_getFlags(a32_cpu *c, argreader *R)
+{
+    const AInputEvent *e = h2ptr(rd32(R));
+    ret32(c, is_fake(e) || !e || !AKeyEvent_getFlags ? 0u : (uint32_t)AKeyEvent_getFlags(e));
+}
+
+void imp_AMotionEvent_getPointerCount(a32_cpu *c, argreader *R)
+{
+    const AInputEvent *e = h2ptr(rd32(R));
+    ret32(c, is_fake(e) ? 1u : e && AMotionEvent_getPointerCount ? (uint32_t)AMotionEvent_getPointerCount(e) : 0u);
+}
+
+void imp_AMotionEvent_getPointerId(a32_cpu *c, argreader *R)
+{
+    const AInputEvent *e = h2ptr(rd32(R));
+    size_t i = rd32(R);
+    ret32(c, is_fake(e) || !e || !AMotionEvent_getPointerId ? 0u : (uint32_t)AMotionEvent_getPointerId(e, i));
+}
+
+static void motion_xy(a32_cpu *c, argreader *R, int y, float (*real)(const AInputEvent *, size_t))
+{
+    const AInputEvent *e = h2ptr(rd32(R));
+    size_t i = rd32(R);
+    retf(c, is_fake(e) ? (y ? ((const fake_event *)e)->y : ((const fake_event *)e)->x) : e && real ? real(e, i) : 0.0f);
+}
+
+void imp_AMotionEvent_getX(a32_cpu *c, argreader *R) { motion_xy(c, R, 0, AMotionEvent_getX); }
+void imp_AMotionEvent_getY(a32_cpu *c, argreader *R) { motion_xy(c, R, 1, AMotionEvent_getY); }
+void imp_AMotionEvent_getRawX(a32_cpu *c, argreader *R) { motion_xy(c, R, 0, AMotionEvent_getRawX); }
+void imp_AMotionEvent_getRawY(a32_cpu *c, argreader *R) { motion_xy(c, R, 1, AMotionEvent_getRawY); }
+
+void imp_AMotionEvent_getAxisValue(a32_cpu *c, argreader *R)
+{
+    const AInputEvent *e = h2ptr(rd32(R));
+    int32_t axis = (int32_t)rd32(R);
+    size_t i = rd32(R);
+    if (is_fake(e)) {
+        const fake_event *f = (const fake_event *)e;
+        retf(c, axis == AMOTION_EVENT_AXIS_X ? f->x : axis == AMOTION_EVENT_AXIS_Y ? f->y : 0.0f);
+    } else {
+        retf(c, e && AMotionEvent_getAxisValue ? AMotionEvent_getAxisValue(e, axis, i) : 0.0f);
+    }
+}
+
+void imp_AMotionEvent_getButtonState(a32_cpu *c, argreader *R)
+{
+    const AInputEvent *e = h2ptr(rd32(R));
+    ret32(c, is_fake(e) || !e || !AMotionEvent_getButtonState ? 0u : (uint32_t)AMotionEvent_getButtonState(e));
+}
+
+/* ---------------------------------------------------------------- Java delivery */
+
+static jlong now_ms(JNIEnv *env) { return (*env)->CallStaticLongMethod(env, I.clock_class, I.uptime); }
+
+static void deliver(JNIEnv *env, jobject ev)
+{
+    if (!ev || !I.java) return;
+    (*env)->CallBooleanMethod(env, I.target, I.inject, ev);
+    if ((*env)->ExceptionCheck(env)) {
+        (*env)->ExceptionDescribe(env);
+        (*env)->ExceptionClear(env);
+    }
+    (*env)->DeleteLocalRef(env, ev);
+}
+
+static void key(JNIEnv *env, int action, int code, int source)
+{
+    if (native_active()) {
+        /* no gamepad: Unreal assigns gamepads through Java's InputDevice list, which doesn't have ours */
+        if (source != SOURCE_GAMEPAD) native_push(AINPUT_EVENT_TYPE_KEY, source, 0, action, code, 0, 0);
+        return;
+    }
+    if (!I.java) return;
+    jlong t = now_ms(env);
+    int dev = source == SOURCE_GAMEPAD ? I.gamepad_id : 0;
+    jobject ev = (*env)->NewObject(env, I.key_class, I.key_init, t, t, action, code, 0, 0, dev, 0, 0, source);
+    deliver(env, ev);
+}
+
+#define CX 960.0f
+#define CY 540.0f
+
+/* the touchpad, as Unity saw it on a Gear VR: touch events (mouse button 0 and the mouse position); positions are
+ * given on a 1920x1080 screen and scaled to the activity's window for NativeActivity games (Unreal divides them by
+ * its window size) */
+static void touch(JNIEnv *env, int action, float x, float y)
+{
+    if (native_active()) {
+        float w = g_window_w > 0 ? (float)g_window_w : 2 * CX, h = g_window_h > 0 ? (float)g_window_h : 2 * CY;
+        native_push(AINPUT_EVENT_TYPE_MOTION, SOURCE_TOUCHSCREEN, TOUCH_DEVICE, action, 0, x / (2 * CX) * w,
+                    y / (2 * CY) * h);
+        return;
+    }
+    if (!I.java || !I.unity) return; /* dispatchKeyEvent takes key events only */
+    static jlong down;
+    jlong t = now_ms(env);
+    if (action == ACTION_DOWN) down = t;
+    jobject ev = (*env)->CallStaticObjectMethod(env, I.motion_class, I.motion_obtain, down, t, action, x, y, 0);
+    if (!ev) return;
+    (*env)->CallVoidMethod(env, ev, I.motion_set_source, SOURCE_TOUCHSCREEN);
+    deliver(env, ev);
+}
+
+static void tap(JNIEnv *env, int action) { touch(env, action, CX, CY); }
+
+static void sticks(JNIEnv *env, float x, float y, float z, float rz)
+{
+    if (native_active() || !I.java || !I.unity) return;
+    jlong t = now_ms(env);
+    jobjectArray props = (*env)->NewObjectArray(env, 1, I.props_class, NULL);
+    jobjectArray coords = (*env)->NewObjectArray(env, 1, I.coords_class, NULL);
+    jobject p = (*env)->NewObject(env, I.props_class, I.props_init);
+    jobject c = (*env)->NewObject(env, I.coords_class, I.coords_init);
+    (*env)->SetIntField(env, p, I.props_id, 0);
+    (*env)->SetIntField(env, p, I.props_tool, 0);
+    (*env)->CallVoidMethod(env, c, I.coords_set_axis, AXIS_X, x);
+    (*env)->CallVoidMethod(env, c, I.coords_set_axis, AXIS_Y, -y); /* Android: down is positive */
+    (*env)->CallVoidMethod(env, c, I.coords_set_axis, AXIS_Z, z);
+    (*env)->CallVoidMethod(env, c, I.coords_set_axis, AXIS_RZ, -rz);
+    (*env)->SetObjectArrayElement(env, props, 0, p);
+    (*env)->SetObjectArrayElement(env, coords, 0, c);
+    jobject ev = (*env)->CallStaticObjectMethod(env, I.motion_class, I.motion_obtain_full, t, t, ACTION_MOVE, 1, props,
+                                                coords, 0, 0, 1.0f, 1.0f, I.gamepad_id, 0, SOURCE_JOYSTICK, 0);
+    deliver(env, ev);
+    (*env)->DeleteLocalRef(env, p);
+    (*env)->DeleteLocalRef(env, c);
+    (*env)->DeleteLocalRef(env, props);
+    (*env)->DeleteLocalRef(env, coords);
+}
+
+static int setup(JNIEnv *env)
+{
+#define CLS(v, n) if (!(I.v = (*env)->NewGlobalRef(env, (*env)->FindClass(env, n)))) return 0
+    CLS(key_class, "android/view/KeyEvent");
+    CLS(motion_class, "android/view/MotionEvent");
+    CLS(coords_class, "android/view/MotionEvent$PointerCoords");
+    CLS(props_class, "android/view/MotionEvent$PointerProperties");
+    CLS(clock_class, "android/os/SystemClock");
+#undef CLS
+    I.key_init = (*env)->GetMethodID(env, I.key_class, "<init>", "(JJIIIIIIII)V");
+    I.motion_obtain = (*env)->GetStaticMethodID(env, I.motion_class, "obtain", "(JJIFFI)Landroid/view/MotionEvent;");
+    I.motion_obtain_full = (*env)->GetStaticMethodID(env, I.motion_class, "obtain",
+        "(JJII[Landroid/view/MotionEvent$PointerProperties;[Landroid/view/MotionEvent$PointerCoords;IIFFIIII)Landroid/view/MotionEvent;");
+    I.motion_set_source = (*env)->GetMethodID(env, I.motion_class, "setSource", "(I)V");
+    I.coords_init = (*env)->GetMethodID(env, I.coords_class, "<init>", "()V");
+    I.coords_set_axis = (*env)->GetMethodID(env, I.coords_class, "setAxisValue", "(IF)V");
+    I.props_init = (*env)->GetMethodID(env, I.props_class, "<init>", "()V");
+    I.props_id = (*env)->GetFieldID(env, I.props_class, "id", "I");
+    I.props_tool = (*env)->GetFieldID(env, I.props_class, "toolType", "I");
+    I.uptime = (*env)->GetStaticMethodID(env, I.clock_class, "uptimeMillis", "()J");
+    if ((*env)->ExceptionCheck(env)) {
+        (*env)->ExceptionClear(env);
+        return 0;
+    }
+    /* a real gamepad (Unity only takes joystick input from devices Android knows) */
+    jclass dc = (*env)->FindClass(env, "android/view/InputDevice");
+    jmethodID ids = dc ? (*env)->GetStaticMethodID(env, dc, "getDeviceIds", "()[I") : NULL;
+    jmethodID get = dc ? (*env)->GetStaticMethodID(env, dc, "getDevice", "(I)Landroid/view/InputDevice;") : NULL;
+    jmethodID src = dc ? (*env)->GetMethodID(env, dc, "getSources", "()I") : NULL;
+    jmethodID name = dc ? (*env)->GetMethodID(env, dc, "getName", "()Ljava/lang/String;") : NULL;
+    jintArray all = ids ? (*env)->CallStaticObjectMethod(env, dc, ids) : NULL;
+    jint n = all ? (*env)->GetArrayLength(env, all) : 0;
+    for (jint k = 0; k < n && get && src && name; k++) {
+        jint id;
+        (*env)->GetIntArrayRegion(env, all, k, 1, &id);
+        jobject d = (*env)->CallStaticObjectMethod(env, dc, get, id);
+        if (!d) continue;
+        jint sources = (*env)->CallIntMethod(env, d, src);
+        jstring nm = (*env)->CallObjectMethod(env, d, name);
+        const char *u = nm ? (*env)->GetStringUTFChars(env, nm, NULL) : NULL;
+        bridge_log(ANDROID_LOG_INFO, "controllers: Android input device %d \"%s\" sources 0x%x", id, u ? u : "?", sources);
+        if ((sources & SOURCE_GAMEPAD) == SOURCE_GAMEPAD && !I.gamepad_id) I.gamepad_id = id;
+        if (u) (*env)->ReleaseStringUTFChars(env, nm, u);
+        (*env)->DeleteLocalRef(env, d);
+    }
+    if ((*env)->ExceptionCheck(env)) (*env)->ExceptionClear(env);
+    /* Unity: UnityPlayerActivity.mUnityPlayer.injectEvent(InputEvent) */
+    jclass ac = (*env)->GetObjectClass(env, I.activity);
+    jfieldID f = (*env)->GetFieldID(env, ac, "mUnityPlayer", "Lcom/unity3d/player/UnityPlayer;");
+    if ((*env)->ExceptionCheck(env)) (*env)->ExceptionClear(env);
+    jobject player = f ? (*env)->GetObjectField(env, I.activity, f) : NULL;
+    if (player) {
+        jclass pc = (*env)->GetObjectClass(env, player);
+        I.inject = (*env)->GetMethodID(env, pc, "injectEvent", "(Landroid/view/InputEvent;)Z");
+        if ((*env)->ExceptionCheck(env)) (*env)->ExceptionClear(env);
+        if (I.inject) I.target = (*env)->NewGlobalRef(env, player), I.unity = 1;
+    }
+    if (!I.inject) {
+        I.inject = (*env)->GetMethodID(env, ac, "dispatchKeyEvent", "(Landroid/view/KeyEvent;)Z");
+        I.target = I.activity;
+    }
+    return I.inject != NULL && I.key_init && I.motion_obtain && I.motion_obtain_full && I.uptime;
+}
+
+static void *poll_thread(void *arg)
+{
+    int gen = (int)(intptr_t)arg;
+    JNIEnv *env = NULL;
+    JavaVMAttachArgs a = {JNI_VERSION_1_6, "a32 controllers", NULL};
+    if ((*g_vm)->AttachCurrentThread(g_vm, &env, &a) != JNI_OK) return NULL;
+    if (!I.java) I.java = setup(env);
+    if (!I.java && !native_active()) {
+        bridge_log(ANDROID_LOG_ERROR, "controllers: can't set up Android input events");
+        (*g_vm)->DetachCurrentThread(g_vm);
+        return NULL;
+    }
+    bridge_log(ANDROID_LOG_INFO, "controllers -> %s, gamepad device %d (trigger: hold touchpad, A: tap, right stick: "
+               "swipe, B/menu: back), window %dx%d", native_active() ? "AInputQueue" : I.unity ?
+               "UnityPlayer.injectEvent" : "Activity.dispatchKeyEvent", I.gamepad_id, g_window_w, g_window_h);
+    uint32_t prev_buttons = 0, prev_back = 0;
+    int prev_tap = 0, sticks_active = 0, logged = 0;
+    int swipe_step = 0, swipe_armed = 1, tap_frames = 0;
+    float swipe_dx = 0, swipe_dy = 0;
+    while (I.running && I.gen == gen) {
+        uint32_t buttons = 0;
+        float lx = 0, ly = 0, rx = 0, ry = 0, trigger = 0;
+        int devices = 0;
+        for (uint32_t i = 0; i < 4; i++) {
+            caps_header h = {0, 0};
+            if (I.api.enumerate(I.mobile, i, &h) < 0) break;
+            if (h.Type != TRACKED_REMOTE) continue;
+            remote_caps caps;
+            memset(&caps, 0, sizeof caps);
+            caps.Header = h;
+            if (I.api.caps(I.mobile, &caps.Header) < 0) continue;
+            remote_state st;
+            memset(&st, 0, sizeof st);
+            st.ControllerType = TRACKED_REMOTE;
+            if (I.api.state(I.mobile, h.DeviceID, &st) < 0) continue;
+            devices++;
+            int left = (caps.ControllerCapabilities & LEFT_HAND) != 0;
+            buttons |= st.Buttons;
+            if (left) lx = st.Joystick[0], ly = st.Joystick[1];
+            else rx = st.Joystick[0], ry = st.Joystick[1], trigger = st.IndexTrigger;
+        }
+        if (devices && !logged++) bridge_log(ANDROID_LOG_INFO, "controllers: %d found", devices);
+        static const struct { uint32_t bit; int code; } map[] = {
+            {B_X, KEYCODE_BUTTON_X}, {B_Y, KEYCODE_BUTTON_Y},
+            {B_LTHUMB, KEYCODE_BUTTON_THUMBL}, {B_RTHUMB, KEYCODE_BUTTON_THUMBR},
+        };
+        for (size_t k = 0; k < sizeof map / sizeof *map; k++) {
+            uint32_t now = buttons & map[k].bit, was = prev_buttons & map[k].bit;
+            if (now != was) key(env, now ? KEY_DOWN : KEY_UP, map[k].code, SOURCE_GAMEPAD);
+        }
+        if (a32_remote_in_use) {
+            /* the game reads the right controller as its Gear VR Controller: only the left menu button stays (back) */
+            buttons &= B_ENTER | B_X | B_Y | B_LTHUMB;
+            trigger = rx = ry = 0;
+            if (prev_tap && !swipe_step) tap(env, ACTION_UP), prev_tap = 0;
+        }
+        uint32_t back = buttons & (B_ENTER | B_B);
+        if (!!back != !!prev_back) key(env, back ? KEY_DOWN : KEY_UP, KEYCODE_BACK, SOURCE_KEYBOARD);
+        /* touchpad held: the trigger; A gives a short tap (~100 ms) */
+        if ((buttons & B_A) && !(prev_buttons & B_A)) tap_frames = 9;
+        int tapping = trigger > 0.6f || (prev_tap && trigger > 0.4f) || tap_frames > 0;
+        if (tap_frames > 0) tap_frames--;
+        if (tapping != prev_tap && !swipe_step) tap(env, tapping ? ACTION_DOWN : ACTION_UP);
+        else if (tapping != prev_tap) tapping = prev_tap;
+        /* a flick of the right stick: a swipe across the touchpad (down, 6 moves, up) */
+        float mag = rx * rx + ry * ry;
+        if (mag < 0.09f) swipe_armed = 1;
+        if (!swipe_step && swipe_armed && mag > 0.5f && !prev_tap) {
+            swipe_armed = 0;
+            if (rx * rx > ry * ry) swipe_dx = rx > 0 ? 1 : -1, swipe_dy = 0;
+            /* NativeActivity games get the touchpad's own axes: X runs front to back, so stick up = swipe forward,
+             * down = swipe back (Gunjack: back = reload, forward = special weapon) */
+            else if (native_active()) swipe_dx = ry > 0 ? -1 : 1, swipe_dy = 0;
+            else swipe_dx = 0, swipe_dy = ry > 0 ? -1 : 1; /* stick forward: swipe towards the front */
+            touch(env, ACTION_DOWN, CX, CY);
+            swipe_step = 1;
+        } else if (swipe_step) {
+            float d = 50.0f * (float)swipe_step;
+            if (swipe_step <= 6) touch(env, ACTION_MOVE, CX + swipe_dx * d, CY + swipe_dy * d);
+            else {
+                touch(env, ACTION_UP, CX + swipe_dx * 300, CY + swipe_dy * 300);
+                swipe_step = -1;
+            }
+            swipe_step++;
+        }
+        int moving = lx * lx + ly * ly > 0.0025f;
+        if (moving || sticks_active) sticks(env, lx, ly, 0, 0); /* one centred event after movement stops */
+        sticks_active = moving;
+        prev_buttons = buttons, prev_back = back, prev_tap = tapping;
+        usleep(11000);
+    }
+    (*g_vm)->DetachCurrentThread(g_vm);
+    return NULL;
+}
+
+void input_start(void *mobile, void *enumerate, void *caps, void *state, jobject activity)
+{
+    if (getenv("A32_NO_INPUT") || I.running || !enumerate || !caps || !state || !activity) return;
+    I.mobile = mobile;
+    I.api.enumerate = enumerate, I.api.caps = caps, I.api.state = state;
+    I.activity = activity;
+    I.running = 1;
+    int gen = ++I.gen; /* a thread of an earlier VR mode that hasn't seen running == 0 yet ends */
+    pthread_t t;
+    pthread_attr_t attr;
+    pthread_attr_init(&attr);
+    pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
+    if (pthread_create(&t, &attr, poll_thread, (void *)(intptr_t)gen)) I.running = 0;
+    pthread_attr_destroy(&attr);
+}
+
+void input_stop(void) { I.running = 0; }
@@ -0,0 +1,653 @@
+/* JNI for guest code, the parts gen_stubs.py can't generate: the Call*Method / NewObject families (variadic,
+ * va_list and jvalue[] arguments, read with the method's shorty), method IDs (which remember their shorty),
+ * references, strings and primitive arrays (shared when the host's data lies in the guest's 4 GiB, as ART's heap
+ * does, else copied), RegisterNatives (trampolines, natives.c) and the JavaVM functions. */
+#include <stdlib.h>
+#include "imports_internal.h"
+
+/* ---------------------------------------------------------------- original APK signature */
+
+/* UE4's GameActivity.AndroidThunkJava_GetSignature() hashes the APK's signing certificate, which AndroidMain compares
+ * with the original one (a tamper check): with the original value from the conversion (native_activity.c) the
+ * guest's call gets it instead of the re-signed APK's */
+extern char *g_orig_signature;
+static uint32_t signature_mid; /* method handle of AndroidThunkJava_GetSignature()Ljava/lang/String; */
+
+/* ---------------------------------------------------------------- shorties */
+
+/* "(I[Ljava/lang/String;J)V" -> "ILJ)V" */
+void make_shorty(const char *sig, char *out, size_t n)
+{
+    size_t k = 0;
+    const char *p = sig;
+    if (*p == '(') p++;
+    while (*p && *p != ')') {
+        char t = *p;
+        if (t == '[') {
+            while (*p == '[') p++;
+            if (*p == 'L') p = strchr(p, ';');
+            if (!p) break;
+            p++;
+            t = 'L';
+        } else if (t == 'L') {
+            p = strchr(p, ';');
+            if (!p) break;
+            p++;
+        } else {
+            p++;
+        }
+        if (k + 3 < n) out[k++] = t;
+    }
+    char r = 'V';
+    if (p && *p == ')') {
+        p++;
+        r = *p == '[' ? 'L' : *p ? *p : 'V';
+    }
+    out[k++] = ')';
+    out[k++] = r;
+    out[k] = 0;
+}
+
+/* JVM type letter of a class object: "int" -> 'I', anything not primitive -> 'L' */
+static char class_letter(JNIEnv *env, jclass k)
+{
+    static jmethodID get_name;
+    if (!get_name) get_name = (*env)->GetMethodID(env, (*env)->FindClass(env, "java/lang/Class"), "getName",
+                                                  "()Ljava/lang/String;");
+    jstring s = (*env)->CallObjectMethod(env, k, get_name);
+    const char *n = s ? (*env)->GetStringUTFChars(env, s, NULL) : NULL;
+    char r = 'L';
+    if (n) {
+        static const char *const prim[] = {"boolean", "byte", "char", "short", "int", "long", "float", "double",
+                                           "void"};
+        static const char letters[] = "ZBCSIJFDV";
+        for (int i = 0; i < 9; i++)
+            if (!strcmp(n, prim[i])) r = letters[i];
+        (*env)->ReleaseStringUTFChars(env, s, n);
+    }
+    if (s) (*env)->DeleteLocalRef(env, s);
+    return r;
+}
+
+/* the shorty of a java.lang.reflect.Method / Constructor */
+static int reflected_shorty(JNIEnv *env, jobject m, char *out, size_t n)
+{
+    jclass mc = (*env)->GetObjectClass(env, m);
+    jmethodID params = (*env)->GetMethodID(env, mc, "getParameterTypes", "()[Ljava/lang/Class;");
+    jmethodID ret = (*env)->GetMethodID(env, mc, "getReturnType", "()Ljava/lang/Class;");
+    if ((*env)->ExceptionCheck(env)) (*env)->ExceptionClear(env); /* a Constructor has no getReturnType */
+    if (!params) return -1;
+    jobjectArray a = (*env)->CallObjectMethod(env, m, params);
+    jsize np = a ? (*env)->GetArrayLength(env, a) : 0;
+    size_t k = 0;
+    for (jsize i = 0; i < np && k + 3 < n; i++) {
+        jclass pk = (*env)->GetObjectArrayElement(env, a, i);
+        out[k++] = class_letter(env, pk);
+        (*env)->DeleteLocalRef(env, pk);
+    }
+    out[k++] = ')';
+    char r = 'V';
+    if (ret) {
+        jclass rk = (*env)->CallObjectMethod(env, m, ret);
+        r = class_letter(env, rk);
+        (*env)->DeleteLocalRef(env, rk);
+    }
+    out[k++] = r;
+    out[k] = 0;
+    return 0;
+}
+
+/* ---------------------------------------------------------------- function classes */
+
+enum {
+    S_NONE, S_CALL, S_GET_ELEMS, S_REL_ELEMS, S_GET_METHOD, S_FROM_REFLECTED, S_NEW_GLOBAL, S_DELETE_GLOBAL,
+    S_DELETE_LOCAL, S_NEW_WEAK, S_DELETE_WEAK, S_POP_FRAME, S_GET_STRING_CHARS, S_REL_STRING_CHARS,
+    S_GET_STRING_UTF, S_REL_STRING_UTF, S_GET_CRITICAL, S_REL_CRITICAL, S_REGISTER, S_GET_VM, S_DIRECT_ADDR,
+};
+enum { K_VIRTUAL = 1, K_NONVIRTUAL, K_STATIC, K_NEW };
+
+static struct {
+    uint8_t special, kind, var; /* var: 0 "...", 1 va_list, 2 jvalue[] */
+    char type;                  /* result (calls) or element type (arrays) */
+} fn[JNI_TABLE_SIZE];
+static pthread_once_t fn_once = PTHREAD_ONCE_INIT;
+
+static char type_word(const char **p)
+{
+    static const struct { const char *w; char t; } words[] = {
+        {"Object", 'L'}, {"Boolean", 'Z'}, {"Byte", 'B'}, {"Char", 'C'}, {"Short", 'S'},
+        {"Int", 'I'},    {"Long", 'J'},    {"Float", 'F'}, {"Double", 'D'}, {"Void", 'V'},
+    };
+    for (size_t k = 0; k < sizeof words / sizeof *words; k++) {
+        size_t n = strlen(words[k].w);
+        if (!strncmp(*p, words[k].w, n)) {
+            *p += n;
+            return words[k].t;
+        }
+    }
+    return 0;
+}
+
+static void classify(void)
+{
+    static const struct { const char *name; uint8_t s; } named[] = {
+        {"GetMethodID", S_GET_METHOD}, {"GetStaticMethodID", S_GET_METHOD},
+        {"FromReflectedMethod", S_FROM_REFLECTED}, {"NewGlobalRef", S_NEW_GLOBAL},
+        {"DeleteGlobalRef", S_DELETE_GLOBAL}, {"DeleteLocalRef", S_DELETE_LOCAL},
+        {"NewWeakGlobalRef", S_NEW_WEAK}, {"DeleteWeakGlobalRef", S_DELETE_WEAK},
+        {"PopLocalFrame", S_POP_FRAME}, {"GetStringChars", S_GET_STRING_CHARS},
+        {"ReleaseStringChars", S_REL_STRING_CHARS}, {"GetStringCritical", S_GET_STRING_CHARS},
+        {"ReleaseStringCritical", S_REL_STRING_CHARS}, {"GetStringUTFChars", S_GET_STRING_UTF},
+        {"ReleaseStringUTFChars", S_REL_STRING_UTF}, {"GetPrimitiveArrayCritical", S_GET_CRITICAL},
+        {"ReleasePrimitiveArrayCritical", S_REL_CRITICAL}, {"RegisterNatives", S_REGISTER},
+        {"GetJavaVM", S_GET_VM}, {"GetDirectBufferAddress", S_DIRECT_ADDR},
+    };
+    for (int i = 0; i < JNI_TABLE_SIZE; i++) {
+        const char *n = jni_names[i];
+        for (size_t k = 0; k < sizeof named / sizeof *named; k++)
+            if (!strcmp(n, named[k].name)) fn[i].special = named[k].s;
+        if (fn[i].special) continue;
+        const char *p = n;
+        uint8_t kind = 0;
+        char t = 0;
+        if (!strncmp(p, "NewObject", 9) && (!p[9] || !strcmp(p + 9, "V") || !strcmp(p + 9, "A"))) {
+            kind = K_NEW, t = 'L', p += 9;
+        } else if (!strncmp(p, "CallNonvirtual", 14)) {
+            p += 14, kind = K_NONVIRTUAL, t = type_word(&p);
+        } else if (!strncmp(p, "CallStatic", 10)) {
+            p += 10, kind = K_STATIC, t = type_word(&p);
+        } else if (!strncmp(p, "Call", 4)) {
+            p += 4, kind = K_VIRTUAL, t = type_word(&p);
+        }
+        if (kind && t) {
+            if (kind != K_NEW) {
+                if (strncmp(p, "Method", 6)) continue;
+                p += 6;
+            }
+            fn[i].special = S_CALL;
+            fn[i].kind = kind;
+            fn[i].type = t;
+            fn[i].var = *p == 'V' ? 1 : *p == 'A' ? 2 : 0;
+            continue;
+        }
+        int get = !strncmp(n, "Get", 3), rel = !strncmp(n, "Release", 7);
+        if ((get || rel) && strstr(n, "ArrayElements")) {
+            p = n + (get ? 3 : 7);
+            t = type_word(&p);
+            if (t && t != 'L' && !strcmp(p, "ArrayElements")) {
+                fn[i].special = get ? S_GET_ELEMS : S_REL_ELEMS;
+                fn[i].type = t;
+            }
+        }
+    }
+}
+
+/* ---------------------------------------------------------------- method calls */
+
+static jvalue arg_value(char t, argreader *A)
+{
+    jvalue v;
+    v.j = 0;
+    switch (t) {
+    case 'Z': v.z = (jboolean)rd32(A); break;
+    case 'B': v.b = (jbyte)rd32(A); break;
+    case 'C': v.c = (jchar)rd32(A); break;
+    case 'S': v.s = (jshort)rd32(A); break;
+    case 'I': v.i = (jint)rd32(A); break;
+    case 'J': v.j = (jlong)rd64(A); break;
+    case 'F': v.f = (jfloat)rdd(A); break; /* promoted to double */
+    case 'D': v.d = rdd(A); break;
+    default: v.l = h2o(rd32(A)); break;
+    }
+    return v;
+}
+
+static jvalue array_value(char t, uint32_t a)
+{
+    jvalue v;
+    v.j = 0;
+    switch (t) {
+    case 'Z': v.z = ld8(a); break;
+    case 'B': v.b = (jbyte)ld8(a); break;
+    case 'C': v.c = ld16(a); break;
+    case 'S': v.s = (jshort)ld16(a); break;
+    case 'I': v.i = (jint)ld32(a); break;
+    case 'J': v.j = (jlong)ld64(a); break;
+    case 'F': { uint32_t b = ld32(a); memcpy(&v.f, &b, 4); break; }
+    case 'D': { uint64_t b = ld64(a); memcpy(&v.d, &b, 8); break; }
+    default: v.l = h2o(ld32(a)); break;
+    }
+    return v;
+}
+
+#define CALL(T)                                                                                                 \
+    (kind == K_VIRTUAL ? (*env)->Call##T##MethodA(env, obj, m, a)                                               \
+     : kind == K_NONVIRTUAL ? (*env)->CallNonvirtual##T##MethodA(env, obj, cls, m, a)                           \
+                            : (*env)->CallStatic##T##MethodA(env, cls, m, a))
+
+static void call_method(a32_cpu *c, JNIEnv *env, int index, argreader *R)
+{
+    int kind = fn[index].kind;
+    jobject obj = NULL;
+    jclass cls = NULL;
+    if (kind == K_VIRTUAL || kind == K_NONVIRTUAL) obj = h2o(rd32(R));
+    if (kind != K_VIRTUAL) cls = (jclass)h2o(rd32(R));
+    uint32_t mh = rd32(R);
+    jmethodID m = h2mid(mh);
+    const char *shorty = mid_shorty(mh);
+    if (!m || !shorty) {
+        bridge_log(ANDROID_LOG_ERROR, "%s: unknown method ID 0x%x", jni_names[index], mh);
+        c->r[0] = c->r[1] = 0;
+        return;
+    }
+    if (mh == signature_mid && g_orig_signature && fn[index].type == 'L' && kind != K_NEW) {
+        static int logged;
+        if (!logged++) bridge_log(ANDROID_LOG_INFO, "AndroidThunkJava_GetSignature: original signature returned");
+        ret32(c, o2h_local((*env)->NewStringUTF(env, g_orig_signature)));
+        return;
+    }
+    jvalue a[256];
+    int n = 0;
+    if (fn[index].var == 2) {
+        uint32_t arr = rd32(R);
+        for (const char *p = shorty; *p != ')' && n < 256; p++, n++) a[n] = array_value(*p, arr + 8u * (uint32_t)n);
+    } else {
+        argreader V, *A = R;
+        if (fn[index].var == 1) {
+            ar_init(&V, c, 4, rd32(R)); /* va_list: a pointer to the next argument in memory */
+            A = &V;
+        }
+        for (const char *p = shorty; *p != ')' && n < 256; p++, n++) a[n] = arg_value(*p, A);
+    }
+    switch (fn[index].type) {
+    case 'V': CALL(Void); break;
+    case 'Z': ret32(c, CALL(Boolean)); break;
+    case 'B': ret32(c, (uint32_t)(int32_t)CALL(Byte)); break;
+    case 'C': ret32(c, CALL(Char)); break;
+    case 'S': ret32(c, (uint32_t)(int32_t)CALL(Short)); break;
+    case 'I': ret32(c, (uint32_t)CALL(Int)); break;
+    case 'J': ret64(c, (uint64_t)CALL(Long)); break;
+    case 'F': retf(c, CALL(Float)); break;
+    case 'D': retd(c, CALL(Double)); break;
+    default:
+        if (kind == K_NEW) ret32(c, o2h_local((*env)->NewObjectA(env, cls, m, a)));
+        else ret32(c, o2h_local(CALL(Object)));
+        break;
+    }
+}
+
+/* ---------------------------------------------------------------- copies of host data in guest memory */
+
+/* Guest buffers that stand for host data outside the guest's 4 GiB (guest address -> size in bytes). */
+static pthread_mutex_t copies_lock = PTHREAD_MUTEX_INITIALIZER;
+static struct { uint32_t g, size; } *copies;
+static int ncopies, capcopies;
+
+static void copy_add(uint32_t g, uint32_t size)
+{
+    pthread_mutex_lock(&copies_lock);
+    if (ncopies == capcopies) copies = realloc(copies, (size_t)(capcopies = capcopies ? capcopies * 2 : 64) * sizeof *copies);
+    copies[ncopies].g = g;
+    copies[ncopies++].size = size;
+    pthread_mutex_unlock(&copies_lock);
+}
+
+/* -1 if g isn't a copy, else its size (forgotten unless keep) */
+static int64_t copy_find(uint32_t g, int keep)
+{
+    int64_t r = -1;
+    pthread_mutex_lock(&copies_lock);
+    for (int k = ncopies - 1; k >= 0; k--)
+        if (copies[k].g == g) {
+            r = copies[k].size;
+            if (!keep) copies[k] = copies[--ncopies];
+            break;
+        }
+    pthread_mutex_unlock(&copies_lock);
+    return r;
+}
+
+
+static int elem_size(char t)
+{
+    switch (t) {
+    case 'Z': case 'B': return 1;
+    case 'C': case 'S': return 2;
+    case 'J': case 'D': return 8;
+    default: return 4;
+    }
+}
+
+/* element size of a primitive array from its class name ("[I") */
+static int array_elem_size(JNIEnv *env, jarray a)
+{
+    static jmethodID get_name;
+    jclass k = (*env)->GetObjectClass(env, a);
+    if (!get_name) get_name = (*env)->GetMethodID(env, (*env)->FindClass(env, "java/lang/Class"), "getName",
+                                                  "()Ljava/lang/String;");
+    jstring s = (*env)->CallObjectMethod(env, k, get_name);
+    const char *n = (*env)->GetStringUTFChars(env, s, NULL);
+    int r = n && n[0] == '[' ? elem_size(n[1]) : 1;
+    (*env)->ReleaseStringUTFChars(env, s, n);
+    (*env)->DeleteLocalRef(env, s);
+    (*env)->DeleteLocalRef(env, k);
+    return r;
+}
+
+static void set_is_copy(uint32_t is_copy, int v)
+{
+    if (is_copy) st8(is_copy, (uint8_t)v);
+}
+
+/* host data p (bytes) -> what the guest gets: p itself when the guest can reach it, else a copy */
+static uint32_t share_or_copy(void *p, size_t bytes, int *copied)
+{
+    if (in_guest_reach(p, bytes)) {
+        *copied = 0;
+        return p2g(p);
+    }
+    uint32_t g = guest_malloc(bytes ? (uint32_t)bytes : 1);
+    if (g) memcpy(g2p(g), p, bytes);
+    *copied = 1;
+    return g;
+}
+
+static uint32_t get_elems(JNIEnv *env, char t, jarray a, uint32_t is_copy)
+{
+    void *p = NULL;
+    switch (t) {
+    case 'Z': p = (*env)->GetBooleanArrayElements(env, a, NULL); break;
+    case 'B': p = (*env)->GetByteArrayElements(env, a, NULL); break;
+    case 'C': p = (*env)->GetCharArrayElements(env, a, NULL); break;
+    case 'S': p = (*env)->GetShortArrayElements(env, a, NULL); break;
+    case 'I': p = (*env)->GetIntArrayElements(env, a, NULL); break;
+    case 'J': p = (*env)->GetLongArrayElements(env, a, NULL); break;
+    case 'F': p = (*env)->GetFloatArrayElements(env, a, NULL); break;
+    case 'D': p = (*env)->GetDoubleArrayElements(env, a, NULL); break;
+    }
+    if (!p) return 0;
+    size_t bytes = (size_t)(*env)->GetArrayLength(env, a) * (size_t)elem_size(t);
+    int copied;
+    uint32_t g = share_or_copy(p, bytes, &copied);
+    if (copied) {
+        switch (t) {
+        case 'Z': (*env)->ReleaseBooleanArrayElements(env, a, p, JNI_ABORT); break;
+        case 'B': (*env)->ReleaseByteArrayElements(env, a, p, JNI_ABORT); break;
+        case 'C': (*env)->ReleaseCharArrayElements(env, a, p, JNI_ABORT); break;
+        case 'S': (*env)->ReleaseShortArrayElements(env, a, p, JNI_ABORT); break;
+        case 'I': (*env)->ReleaseIntArrayElements(env, a, p, JNI_ABORT); break;
+        case 'J': (*env)->ReleaseLongArrayElements(env, a, p, JNI_ABORT); break;
+        case 'F': (*env)->ReleaseFloatArrayElements(env, a, p, JNI_ABORT); break;
+        case 'D': (*env)->ReleaseDoubleArrayElements(env, a, p, JNI_ABORT); break;
+        }
+        copy_add(g, (uint32_t)bytes);
+    }
+    set_is_copy(is_copy, copied);
+    return g;
+}
+
+/* a guest copy of array data goes back through the critical accessor (any element type) */
+static void write_back(JNIEnv *env, jarray a, uint32_t g, uint32_t size)
+{
+    void *p = (*env)->GetPrimitiveArrayCritical(env, a, NULL);
+    if (!p) return;
+    memcpy(p, g2p(g), size);
+    (*env)->ReleasePrimitiveArrayCritical(env, a, p, 0);
+}
+
+static void release_elems(JNIEnv *env, char t, jarray a, uint32_t g, jint mode)
+{
+    int64_t size = copy_find(g, mode == JNI_COMMIT);
+    if (size >= 0) {
+        if (mode != JNI_ABORT) write_back(env, a, g, (uint32_t)size);
+        if (mode != JNI_COMMIT) guest_free(g);
+        return;
+    }
+    void *p = g2p(g);
+    switch (t) {
+    case 'Z': (*env)->ReleaseBooleanArrayElements(env, a, p, mode); break;
+    case 'B': (*env)->ReleaseByteArrayElements(env, a, p, mode); break;
+    case 'C': (*env)->ReleaseCharArrayElements(env, a, p, mode); break;
+    case 'S': (*env)->ReleaseShortArrayElements(env, a, p, mode); break;
+    case 'I': (*env)->ReleaseIntArrayElements(env, a, p, mode); break;
+    case 'J': (*env)->ReleaseLongArrayElements(env, a, p, mode); break;
+    case 'F': (*env)->ReleaseFloatArrayElements(env, a, p, mode); break;
+    case 'D': (*env)->ReleaseDoubleArrayElements(env, a, p, mode); break;
+    }
+}
+
+/* ---------------------------------------------------------------- dispatch */
+
+static void register_natives(a32_cpu *c, JNIEnv *env, argreader *R)
+{
+    jclass cls = (jclass)h2o(rd32(R));
+    uint32_t methods = rd32(R);
+    jint n = (jint)rd32(R);
+    JNINativeMethod *hm = calloc(n > 0 ? (size_t)n : 1, sizeof *hm);
+    for (jint k = 0; k < n; k++) {
+        uint32_t e = methods + 12u * (uint32_t)k;
+        hm[k].name = g2p(ld32(e));
+        hm[k].signature = g2p(ld32(e + 4));
+        hm[k].fnPtr = natives_trampoline_named(ld32(e + 8), hm[k].signature, hm[k].name);
+        if (!hm[k].fnPtr) {
+            free(hm);
+            ret32(c, (uint32_t)JNI_ERR);
+            return;
+        }
+    }
+    jint r = (*env)->RegisterNatives(env, cls, hm, n);
+    if (r) bridge_log(ANDROID_LOG_ERROR, "RegisterNatives of %d methods failed (%d)", n, r);
+    ret32(c, (uint32_t)r);
+    free(hm);
+}
+
+static pthread_once_t unattached_once = PTHREAD_ONCE_INIT;
+static void unattached_warning(void) { bridge_log(ANDROID_LOG_ERROR, "JNI call on a thread not attached to the VM"); }
+
+int jni_dispatch(a32_cpu *c, int index)
+{
+    pthread_once(&fn_once, classify);
+    JNIEnv *env = host_env();
+    if (!env) {
+        pthread_once(&unattached_once, unattached_warning);
+        c->r[0] = c->r[1] = 0;
+        return 1;
+    }
+    argreader R;
+    ar_init(&R, c, 1, c->r[13] + 8); /* r0 = the guest's JNIEnv; the stub pushed {r7, lr} */
+    switch (fn[index].special) {
+    case S_NONE:
+        if (jni_dispatch_generated(c, env, index, &R)) return 1;
+        bridge_log(ANDROID_LOG_ERROR, "JNI function %d (%s) is not supported", index, jni_names[index]);
+        c->r[0] = c->r[1] = 0;
+        return 1;
+    case S_CALL:
+        call_method(c, env, index, &R);
+        return 1;
+    case S_GET_METHOD: {
+        jclass cls = (jclass)h2o(rd32(&R));
+        const char *name = g2p(rd32(&R)), *sig = g2p(rd32(&R));
+        jmethodID m = !strcmp(jni_names[index], "GetMethodID") ? (*env)->GetMethodID(env, cls, name, sig)
+                                                               : (*env)->GetStaticMethodID(env, cls, name, sig);
+        uint32_t h = mid2h(m);
+        if (h) {
+            char shorty[260];
+            make_shorty(sig, shorty, sizeof shorty);
+            mid_set_shorty(h, shorty);
+            if (!strcmp(name, "AndroidThunkJava_GetSignature") && !strcmp(sig, "()Ljava/lang/String;"))
+                signature_mid = h;
+        }
+        ret32(c, h);
+        return 1;
+    }
+    case S_FROM_REFLECTED: {
+        jobject o = h2o(rd32(&R));
+        uint32_t h = mid2h((*env)->FromReflectedMethod(env, o));
+        char shorty[260];
+        if (h && !mid_shorty(h) && !reflected_shorty(env, o, shorty, sizeof shorty)) mid_set_shorty(h, shorty);
+        ret32(c, h);
+        return 1;
+    }
+    case S_NEW_GLOBAL:
+        ret32(c, o2h_global((*env)->NewGlobalRef(env, h2o(rd32(&R)))));
+        return 1;
+    case S_NEW_WEAK:
+        ret32(c, o2h_weak((*env)->NewWeakGlobalRef(env, h2o(rd32(&R)))));
+        return 1;
+    case S_DELETE_GLOBAL:
+    case S_DELETE_LOCAL:
+    case S_DELETE_WEAK: {
+        uint32_t h = rd32(&R);
+        jobject o = h2o(h);
+        if (o) {
+            if (fn[index].special == S_DELETE_GLOBAL) (*env)->DeleteGlobalRef(env, o);
+            else if (fn[index].special == S_DELETE_WEAK) (*env)->DeleteWeakGlobalRef(env, o);
+            else (*env)->DeleteLocalRef(env, o);
+        }
+        h_free(h);
+        return 1;
+    }
+    case S_POP_FRAME:
+        ret32(c, o2h_local((*env)->PopLocalFrame(env, h2o(rd32(&R)))));
+        return 1;
+    case S_GET_STRING_CHARS: {
+        jstring s = (jstring)h2o(rd32(&R));
+        uint32_t is_copy = rd32(&R);
+        jsize n = (*env)->GetStringLength(env, s);
+        uint32_t g = guest_malloc(2u * (uint32_t)n + 2);
+        if (g) {
+            (*env)->GetStringRegion(env, s, 0, n, g2p(g));
+            st16(g + 2u * (uint32_t)n, 0);
+        }
+        set_is_copy(is_copy, 1);
+        ret32(c, g);
+        return 1;
+    }
+    case S_GET_STRING_UTF: {
+        jstring s = (jstring)h2o(rd32(&R));
+        uint32_t is_copy = rd32(&R);
+        const char *p = (*env)->GetStringUTFChars(env, s, NULL);
+        uint32_t g = p ? guest_strdup(p) : 0;
+        if (p) (*env)->ReleaseStringUTFChars(env, s, p);
+        set_is_copy(is_copy, 1);
+        ret32(c, g);
+        return 1;
+    }
+    case S_REL_STRING_CHARS:
+    case S_REL_STRING_UTF:
+        rd32(&R);
+        guest_free(rd32(&R));
+        return 1;
+    case S_GET_ELEMS: {
+        jarray a = (jarray)h2o(rd32(&R));
+        uint32_t is_copy = rd32(&R);
+        ret32(c, a ? get_elems(env, fn[index].type, a, is_copy) : 0);
+        return 1;
+    }
+    case S_REL_ELEMS: {
+        jarray a = (jarray)h2o(rd32(&R));
+        uint32_t g = rd32(&R);
+        jint mode = (jint)rd32(&R);
+        release_elems(env, fn[index].type, a, g, mode);
+        return 1;
+    }
+    case S_GET_CRITICAL: {
+        jarray a = (jarray)h2o(rd32(&R));
+        uint32_t is_copy = rd32(&R);
+        void *p = a ? (*env)->GetPrimitiveArrayCritical(env, a, NULL) : NULL;
+        if (!p) {
+            ret32(c, 0);
+            return 1;
+        }
+        if (in_guest_reach(p, 1)) {
+            set_is_copy(is_copy, 0);
+            ret32(c, p2g(p));
+            return 1;
+        }
+        /* outside the guest's reach: copy (the size needs the class, which can't be asked for in a critical
+         * region) */
+        (*env)->ReleasePrimitiveArrayCritical(env, a, p, JNI_ABORT);
+        uint32_t size = (uint32_t)(*env)->GetArrayLength(env, a) * (uint32_t)array_elem_size(env, a);
+        uint32_t g = guest_malloc(size ? size : 1);
+        p = (*env)->GetPrimitiveArrayCritical(env, a, NULL);
+        if (g && p) memcpy(g2p(g), p, size);
+        if (p) (*env)->ReleasePrimitiveArrayCritical(env, a, p, JNI_ABORT);
+        copy_add(g, size);
+        set_is_copy(is_copy, 1);
+        ret32(c, g);
+        return 1;
+    }
+    case S_REL_CRITICAL: {
+        jarray a = (jarray)h2o(rd32(&R));
+        uint32_t g = rd32(&R);
+        jint mode = (jint)rd32(&R);
+        int64_t size = copy_find(g, mode == JNI_COMMIT);
+        if (size >= 0) {
+            if (mode != JNI_ABORT) write_back(env, a, g, (uint32_t)size);
+            if (mode != JNI_COMMIT) guest_free(g);
+        } else {
+            (*env)->ReleasePrimitiveArrayCritical(env, a, g2p(g), mode);
+        }
+        return 1;
+    }
+    case S_REGISTER:
+        register_natives(c, env, &R);
+        return 1;
+    case S_GET_VM:
+        st32(rd32(&R), g_info.java_vm);
+        ret32(c, 0);
+        return 1;
+    case S_DIRECT_ADDR: {
+        void *p = (*env)->GetDirectBufferAddress(env, h2o(rd32(&R)));
+        if (p && !in_guest_reach(p, 1)) {
+            bridge_log(ANDROID_LOG_ERROR, "GetDirectBufferAddress: buffer at %p is outside the guest's reach", p);
+            p = NULL;
+        }
+        ret32(c, p2g(p));
+        return 1;
+    }
+    }
+    return 0;
+}
+
+/* JNIInvokeInterface: reserved0-2, DestroyJavaVM, AttachCurrentThread, DetachCurrentThread, GetEnv,
+ * AttachCurrentThreadAsDaemon */
+int vm_dispatch(a32_cpu *c, int index)
+{
+    argreader R;
+    ar_init(&R, c, 1, c->r[13] + 8);
+    switch (index) {
+    case 4:
+    case 7: {
+        uint32_t penv = rd32(&R), args = rd32(&R);
+        JavaVMAttachArgs a = {JNI_VERSION_1_6, NULL, NULL}, *ap = NULL;
+        if (args) {
+            a.version = (jint)ld32(args);
+            a.name = ld32(args + 4) ? g2p(ld32(args + 4)) : NULL;
+            a.group = h2o(ld32(args + 8));
+            ap = &a;
+        }
+        JNIEnv *env = NULL;
+        jint r = index == 4 ? (*g_vm)->AttachCurrentThread(g_vm, &env, ap)
+                            : (*g_vm)->AttachCurrentThreadAsDaemon(g_vm, &env, ap);
+        if (penv) st32(penv, r == JNI_OK ? g_info.jni_env : 0);
+        ret32(c, (uint32_t)r);
+        return 1;
+    }
+    case 5:
+        ret32(c, (uint32_t)(*g_vm)->DetachCurrentThread(g_vm));
+        return 1;
+    case 6: {
+        uint32_t penv = rd32(&R);
+        jint version = (jint)rd32(&R);
+        JNIEnv *env = NULL;
+        jint r = (*g_vm)->GetEnv(g_vm, (void **)&env, version);
+        if (penv) st32(penv, r == JNI_OK ? g_info.jni_env : 0);
+        ret32(c, (uint32_t)r);
+        return 1;
+    }
+    default:
+        ret32(c, (uint32_t)JNI_ERR);
+        return 1;
+    }
+}
@@ -0,0 +1,156 @@
+/* Host side of the bridge: shared declarations. */
+#ifndef A32B_JNI_INTERNAL_H
+#define A32B_JNI_INTERNAL_H
+
+#include <android/log.h>
+#include <jni.h>
+#include <pthread.h>
+#include <stdint.h>
+#include <string.h>
+#include "../../src/interp.h"
+#include "../../src/runtime.h"
+#include "../../src/threads.h"
+#include "../abi.h"
+
+/* ---------------------------------------------------------------- arguments (AAPCS32, softfp) */
+
+/* Reads a guest call's arguments in order: core registers r[ncrn..3], then the stack. Doubleword values take an
+ * even register pair or an 8-byte aligned stack slot; once one spills, every later argument is on the stack.
+ * Also reads a va_list (ncrn = 4, nsaa = the va_list pointer). Variadic floats arrive promoted to double. */
+typedef struct {
+    a32_cpu *c;
+    int ncrn;
+    uint32_t nsaa;
+} argreader;
+
+static inline void ar_init(argreader *R, a32_cpu *c, int first, uint32_t stack)
+{
+    R->c = c;
+    R->ncrn = first;
+    R->nsaa = stack;
+}
+
+static inline uint32_t rd32(argreader *R)
+{
+    if (R->ncrn < 4) return R->c->r[R->ncrn++];
+    uint32_t v = ld32(R->nsaa);
+    R->nsaa += 4;
+    return v;
+}
+
+static inline uint64_t rd64(argreader *R)
+{
+    if (R->ncrn & 1) R->ncrn++;
+    if (R->ncrn <= 2) {
+        uint64_t v = R->c->r[R->ncrn] | (uint64_t)R->c->r[R->ncrn + 1] << 32;
+        R->ncrn += 2;
+        return v;
+    }
+    R->ncrn = 4;
+    R->nsaa = (R->nsaa + 7) & ~7u;
+    uint64_t v = ld64(R->nsaa);
+    R->nsaa += 8;
+    return v;
+}
+
+static inline float rdf(argreader *R)
+{
+    uint32_t b = rd32(R);
+    float f;
+    memcpy(&f, &b, 4);
+    return f;
+}
+
+static inline double rdd(argreader *R)
+{
+    uint64_t b = rd64(R);
+    double d;
+    memcpy(&d, &b, 8);
+    return d;
+}
+
+/* host data the guest can address directly (it lies in the low 4 GiB) */
+static inline int in_guest_reach(const void *p, size_t n) { return (uintptr_t)p + n <= 0x100000000ull; }
+static inline void *g2p(uint32_t a) { return (void *)(uintptr_t)a; }
+static inline uint32_t p2g(const void *p) { return (uint32_t)(uintptr_t)p; }
+
+static inline void ret32(a32_cpu *c, uint32_t v) { c->r[0] = v; }
+static inline void ret64(a32_cpu *c, uint64_t v)
+{
+    c->r[0] = (uint32_t)v;
+    c->r[1] = (uint32_t)(v >> 32);
+}
+static inline void retf(a32_cpu *c, float f)
+{
+    uint32_t b;
+    memcpy(&b, &f, 4);
+    c->r[0] = b;
+}
+static inline void retd(a32_cpu *c, double d)
+{
+    uint64_t b;
+    memcpy(&b, &d, 8);
+    ret64(c, b);
+}
+
+/* Builds a guest call's argument words (AAPCS32): doublewords at an even word index (registers r0-r3 are words
+ * 0-3, the stack follows 8-byte aligned). */
+typedef struct {
+    uint32_t w[64];
+    int n;
+} argbuilder;
+
+static inline void ab_32(argbuilder *B, uint32_t v)
+{
+    if (B->n < 64) B->w[B->n++] = v;
+}
+static inline void ab_64(argbuilder *B, uint64_t v)
+{
+    if (B->n & 1) ab_32(B, 0);
+    ab_32(B, (uint32_t)v);
+    ab_32(B, (uint32_t)(v >> 32));
+}
+
+/* ---------------------------------------------------------------- handles (handles.c) */
+
+/* Guest code holds 32-bit values; host references and IDs are 64-bit pointers. Each gets a handle. */
+uint32_t o2h_local(jobject o);   /* a local reference: freed with the current native frame */
+uint32_t o2h_global(jobject o);
+uint32_t o2h_weak(jobject o);
+uint32_t o2h_keep(jobject o);    /* a host reference the bridge owns (never freed by the guest) */
+jobject h2o(uint32_t h);
+void h_free(uint32_t h);         /* forgets the handle (the host reference is the caller's business) */
+uint32_t mid2h(jmethodID m);
+jmethodID h2mid(uint32_t h);
+uint32_t fid2h(jfieldID f);
+jfieldID h2fid(uint32_t h);
+uint32_t ptr2h(void *p);         /* other host pointers (ANativeWindow *, AAssetManager *, ...) */
+void *h2ptr(uint32_t h);
+/* the method's argument types: 'Z','B','C','S','I','J','F','D','L' per parameter, then the result after ')' */
+void mid_set_shorty(uint32_t h, const char *shorty);
+const char *mid_shorty(uint32_t h);
+/* native frames: local handles created after frame_mark() are forgotten by frame_pop() */
+uint32_t frame_mark(void);
+void frame_pop(uint32_t mark);
+
+/* ---------------------------------------------------------------- bridge (bridge.c) */
+
+extern struct grt_info g_info;
+extern JavaVM *g_vm;
+JNIEnv *host_env(void);          /* NULL if this thread isn't attached to the VM */
+void bridge_log(int prio, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
+/* calls a guest function on this thread's guest context (attaching one first if needed) */
+uint64_t guest_call(uint32_t fn, const uint32_t *words, int n);
+uint32_t guest_malloc(uint32_t size);
+void guest_free(uint32_t p);
+uint32_t guest_strdup(const char *s);
+uint32_t guest_cstr(const char *s); /* a host string the guest can read: itself, or a copy kept for good */
+
+/* jni.c */
+int jni_dispatch(a32_cpu *c, int index);
+int vm_dispatch(a32_cpu *c, int index);
+int jni_dispatch_generated(a32_cpu *c, JNIEnv *env, int index, argreader *R);
+extern const char *const jni_names[JNI_TABLE_SIZE];
+void make_shorty(const char *sig, char *out, size_t n);
+
+#endif
@@ -0,0 +1,230 @@
+/* NativeActivity for guest libraries. The guest gets its own 32-bit ANativeActivity (and callback table) that
+ * mirrors the host's; the host activity's callbacks forward to whatever the guest's ANativeActivity_onCreate put
+ * in its table. Windows, input queues and the asset manager are host pointers: the guest sees handles (ptr2h). */
+#include <android/asset_manager.h>
+#include <android/asset_manager_jni.h>
+#include <stdlib.h>
+#include "imports_internal.h"
+
+/* struct ANativeActivity, 32-bit */
+#define GA_CALLBACKS 0
+#define GA_VM 4
+#define GA_ENV 8
+#define GA_CLAZZ 12
+#define GA_INTERNAL_PATH 16
+#define GA_EXTERNAL_PATH 20
+#define GA_SDK 24
+#define GA_INSTANCE 28
+#define GA_ASSETS 32
+#define GA_OBB_PATH 36
+#define GA_SIZE 40
+#define NCALLBACKS 16 /* ANativeActivityCallbacks: onStart ... onLowMemory */
+
+enum {
+    CB_START, CB_RESUME, CB_SAVE_STATE, CB_PAUSE, CB_STOP, CB_DESTROY, CB_FOCUS, CB_WINDOW_CREATED,
+    CB_WINDOW_RESIZED, CB_WINDOW_REDRAW, CB_WINDOW_DESTROYED, CB_QUEUE_CREATED, CB_QUEUE_DESTROYED, CB_CONTENT_RECT,
+    CB_CONFIG, CB_LOW_MEMORY,
+};
+
+typedef struct {
+    ANativeActivity *host;
+    uint32_t guest;
+} activity;
+
+static activity acts[8];
+static pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;
+
+/* What UE4's GameActivity.AndroidThunkJava_GetSignature() returned for the original APK (Base64 of the SHA-1 of its
+ * signing certificate, with Base64.DEFAULT's newline): the conversion stores it in assets/fp_a32_signature.txt (patch
+ * frame.a32_bridge), jni.c answers the guest's call with it, since the re-signed APK has another certificate. */
+char *g_orig_signature;
+
+/* weak: the PC test harness has no libandroid */
+extern __typeof__(AAssetManager_open) AAssetManager_open __attribute__((weak));
+extern __typeof__(AAsset_getLength) AAsset_getLength __attribute__((weak));
+extern __typeof__(AAsset_read) AAsset_read __attribute__((weak));
+extern __typeof__(AAsset_close) AAsset_close __attribute__((weak));
+
+static void load_orig_signature(AAssetManager *mgr)
+{
+    if (g_orig_signature || !mgr || !AAssetManager_open) return;
+    AAsset *asset = AAssetManager_open(mgr, "fp_a32_signature.txt", AASSET_MODE_BUFFER);
+    if (!asset) return;
+    off_t n = AAsset_getLength(asset);
+    char *s = n > 0 && n < 256 ? malloc((size_t)n + 1) : NULL;
+    if (s && AAsset_read(asset, s, (size_t)n) == n) {
+        s[n] = 0;
+        g_orig_signature = s;
+        bridge_log(ANDROID_LOG_INFO, "original APK signature loaded (%d bytes)", (int)n);
+    } else {
+        free(s);
+    }
+    AAsset_close(asset);
+}
+
+ANativeActivity *guest_activity(uint32_t g)
+{
+    ANativeActivity *r = NULL;
+    pthread_mutex_lock(&lock);
+    for (int k = 0; k < 8; k++)
+        if (acts[k].guest == g && g) r = acts[k].host;
+    pthread_mutex_unlock(&lock);
+    return r;
+}
+
+static uint32_t guest_of(ANativeActivity *a)
+{
+    uint32_t r = 0;
+    pthread_mutex_lock(&lock);
+    for (int k = 0; k < 8; k++)
+        if (acts[k].host == a) r = acts[k].guest;
+    pthread_mutex_unlock(&lock);
+    return r;
+}
+
+/* calls the guest's callback cb (if it set one) with the guest activity and up to two more words */
+static const char *const CB_NAMES[NCALLBACKS] = {
+    "onStart", "onResume", "onSaveInstanceState", "onPause", "onStop", "onDestroy", "onWindowFocusChanged",
+    "onNativeWindowCreated", "onNativeWindowResized", "onNativeWindowRedrawNeeded", "onNativeWindowDestroyed",
+    "onInputQueueCreated", "onInputQueueDestroyed", "onContentRectChanged", "onConfigurationChanged", "onLowMemory",
+};
+
+static uint64_t forward(ANativeActivity *a, int cb, int n, uint32_t w1, uint32_t w2, int *called)
+{
+    uint32_t g = guest_of(a);
+    uint32_t fn = g ? ld32(ld32(g + GA_CALLBACKS) + 4u * (uint32_t)cb) : 0;
+    if (cb != CB_WINDOW_REDRAW && cb != CB_CONTENT_RECT) /* the lifecycle, for logs (rare) */
+        bridge_log(ANDROID_LOG_INFO, "activity %s(0x%x)%s", CB_NAMES[cb], w1, fn ? "" : " (no guest callback)");
+    if (called) *called = fn != 0;
+    if (!fn) return 0;
+    uint32_t w[3] = {g, w1, w2};
+    return guest_call(fn, w, n + 1);
+}
+
+static void on_start(ANativeActivity *a) { forward(a, CB_START, 0, 0, 0, NULL); }
+static void on_resume(ANativeActivity *a) { forward(a, CB_RESUME, 0, 0, 0, NULL); }
+static void on_pause(ANativeActivity *a) { forward(a, CB_PAUSE, 0, 0, 0, NULL); }
+static void on_stop(ANativeActivity *a) { forward(a, CB_STOP, 0, 0, 0, NULL); }
+static void on_low_memory(ANativeActivity *a) { forward(a, CB_LOW_MEMORY, 0, 0, 0, NULL); }
+static void on_config(ANativeActivity *a) { forward(a, CB_CONFIG, 0, 0, 0, NULL); }
+static void on_focus(ANativeActivity *a, int focused) { forward(a, CB_FOCUS, 1, (uint32_t)focused, 0, NULL); }
+volatile int g_window_w, g_window_h;
+extern __typeof__(ANativeWindow_getWidth) ANativeWindow_getWidth __attribute__((weak));
+extern __typeof__(ANativeWindow_getHeight) ANativeWindow_getHeight __attribute__((weak));
+
+static void note_window(ANativeWindow *w)
+{
+    if (!w || !ANativeWindow_getWidth || !ANativeWindow_getHeight) return;
+    int ww = ANativeWindow_getWidth(w), wh = ANativeWindow_getHeight(w);
+    if (ww > 0 && wh > 0) g_window_w = ww, g_window_h = wh;
+}
+
+static void on_window_created(ANativeActivity *a, ANativeWindow *w)
+{
+    note_window(w);
+    forward(a, CB_WINDOW_CREATED, 1, ptr2h(w), 0, NULL);
+}
+static void on_window_resized(ANativeActivity *a, ANativeWindow *w)
+{
+    note_window(w);
+    forward(a, CB_WINDOW_RESIZED, 1, ptr2h(w), 0, NULL);
+}
+static void on_window_redraw(ANativeActivity *a, ANativeWindow *w) { forward(a, CB_WINDOW_REDRAW, 1, ptr2h(w), 0, NULL); }
+static void on_window_destroyed(ANativeActivity *a, ANativeWindow *w) { forward(a, CB_WINDOW_DESTROYED, 1, ptr2h(w), 0, NULL); }
+static void on_queue_created(ANativeActivity *a, AInputQueue *q) { forward(a, CB_QUEUE_CREATED, 1, ptr2h(q), 0, NULL); }
+static void on_queue_destroyed(ANativeActivity *a, AInputQueue *q)
+{
+    forward(a, CB_QUEUE_DESTROYED, 1, ptr2h(q), 0, NULL);
+    input_queue_detached(q);
+}
+
+static void on_content_rect(ANativeActivity *a, const ARect *r)
+{
+    uint32_t g = guest_malloc(sizeof *r);
+    if (!g) return;
+    memcpy(g2p(g), r, sizeof *r);
+    forward(a, CB_CONTENT_RECT, 1, g, 0, NULL);
+    guest_free(g);
+}
+
+static void *on_save_state(ANativeActivity *a, size_t *out_len)
+{
+    *out_len = 0;
+    uint32_t len = guest_malloc(4);
+    if (!len) return NULL;
+    st32(len, 0);
+    int called;
+    uint32_t p = (uint32_t)forward(a, CB_SAVE_STATE, 1, len, 0, &called);
+    void *r = NULL;
+    uint32_t n = ld32(len);
+    if (p && n) {
+        /* the framework frees the result with free() */
+        r = malloc(n);
+        if (r) {
+            memcpy(r, g2p(p), n);
+            *out_len = n;
+        }
+    }
+    guest_free(p);
+    guest_free(len);
+    return r;
+}
+
+static void on_destroy(ANativeActivity *a)
+{
+    forward(a, CB_DESTROY, 0, 0, 0, NULL);
+    pthread_mutex_lock(&lock);
+    for (int k = 0; k < 8; k++)
+        if (acts[k].host == a) acts[k].host = NULL, acts[k].guest = 0;
+    pthread_mutex_unlock(&lock);
+    /* the guest structures stay: the guest may still look at them while it shuts down */
+}
+
+void activity_create(ANativeActivity *a, void *saved, size_t saved_size, uint32_t oncreate)
+{
+    load_orig_signature(a->assetManager);
+    uint32_t g = guest_malloc(GA_SIZE + 4 * NCALLBACKS);
+    memset(g2p(g), 0, GA_SIZE + 4 * NCALLBACKS);
+    st32(g + GA_CALLBACKS, g + GA_SIZE);
+    st32(g + GA_VM, g_info.java_vm);
+    st32(g + GA_ENV, g_info.jni_env);
+    st32(g + GA_CLAZZ, o2h_keep(a->clazz));
+    st32(g + GA_INTERNAL_PATH, a->internalDataPath ? guest_strdup(a->internalDataPath) : 0);
+    st32(g + GA_EXTERNAL_PATH, a->externalDataPath ? guest_strdup(a->externalDataPath) : 0);
+    st32(g + GA_SDK, (uint32_t)a->sdkVersion);
+    st32(g + GA_ASSETS, ptr2h(a->assetManager));
+    st32(g + GA_OBB_PATH, a->obbPath ? guest_strdup(a->obbPath) : 0);
+    pthread_mutex_lock(&lock);
+    int k = 0;
+    while (k < 7 && acts[k].host) k++;
+    acts[k].host = a;
+    acts[k].guest = g;
+    pthread_mutex_unlock(&lock);
+
+    ANativeActivityCallbacks *cb = a->callbacks;
+    cb->onStart = on_start;
+    cb->onResume = on_resume;
+    cb->onSaveInstanceState = on_save_state;
+    cb->onPause = on_pause;
+    cb->onStop = on_stop;
+    cb->onDestroy = on_destroy;
+    cb->onWindowFocusChanged = on_focus;
+    cb->onNativeWindowCreated = on_window_created;
+    cb->onNativeWindowResized = on_window_resized;
+    cb->onNativeWindowRedrawNeeded = on_window_redraw;
+    cb->onNativeWindowDestroyed = on_window_destroyed;
+    cb->onInputQueueCreated = on_queue_created;
+    cb->onInputQueueDestroyed = on_queue_destroyed;
+    cb->onContentRectChanged = on_content_rect;
+    cb->onConfigurationChanged = on_config;
+    cb->onLowMemory = on_low_memory;
+
+    uint32_t gs = 0;
+    if (saved && saved_size) {
+        gs = guest_malloc((uint32_t)saved_size);
+        if (gs) memcpy(g2p(gs), saved, saved_size);
+    }
+    uint32_t w[3] = {g, gs, (uint32_t)saved_size};
+    guest_call(oncreate, w, 3);
+    bridge_log(ANDROID_LOG_INFO, "guest ANativeActivity_onCreate done");
+}
@@ -0,0 +1,272 @@
+/* Java native methods implemented by guest code. RegisterNatives (jni.c) and the exported Java_* functions of a
+ * guest library both end up as a trampoline slot (tramp.S) that ART calls with the host ABI; a32b_native_call
+ * converts the arguments to AAPCS32 (objects become handles, valid until the native method returns) and calls the
+ * guest function. */
+#include <stdlib.h>
+#include "imports_internal.h"
+
+#define NTRAMP 4096 /* tramp.S */
+
+extern const char a32b_tramp_table[];
+
+typedef struct {
+    uint32_t fn;
+    char *shorty;
+    char *name; /* for A32B_TRACE */
+} native;
+
+int a32b_trace = -1; /* A32B_TRACE=1: log native registrations and calls */
+
+static int tracing(void)
+{
+    if (a32b_trace < 0) a32b_trace = getenv("A32B_TRACE") != NULL;
+    return a32b_trace;
+}
+
+static native natives[NTRAMP];
+static int nnatives;
+static pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;
+
+void *natives_trampoline_named(uint32_t fn, const char *sig, const char *name)
+{
+    char shorty[260];
+    make_shorty(sig, shorty, sizeof shorty);
+    pthread_mutex_lock(&lock);
+    int k;
+    for (k = 0; k < nnatives; k++)
+        if (natives[k].fn == fn && !strcmp(natives[k].shorty, shorty)) break;
+    if (k == nnatives) {
+        if (nnatives == NTRAMP) {
+            pthread_mutex_unlock(&lock);
+            bridge_log(ANDROID_LOG_ERROR, "out of native method trampolines (%d)", NTRAMP);
+            return NULL;
+        }
+        natives[k].fn = fn;
+        natives[k].shorty = strdup(shorty);
+        natives[k].name = strdup(name ? name : "?");
+        __atomic_store_n(&nnatives, k + 1, __ATOMIC_RELEASE);
+    }
+    pthread_mutex_unlock(&lock);
+    if (tracing()) bridge_log(ANDROID_LOG_INFO, "native %s%s -> guest 0x%08x (slot %d)", name ? name : "?", sig, fn, k);
+    return (void *)(a32b_tramp_table + 8 * k);
+}
+
+void *natives_trampoline(uint32_t fn, const char *sig) { return natives_trampoline_named(fn, sig, NULL); }
+
+__attribute__((visibility("hidden"))) uint64_t a32b_native_call(uint64_t index, const uint64_t *gpr,
+                                                                 const uint64_t *fpr, const uint64_t *stack)
+{
+    const native *nt = &natives[index];
+    if (tracing()) bridge_log(ANDROID_LOG_INFO, "call %s", nt->name);
+    uint32_t mark = frame_mark();
+    argbuilder B;
+    B.n = 0;
+    ab_32(&B, g_info.jni_env);
+    ab_32(&B, o2h_local((jobject)gpr[1])); /* this or the class */
+    int ng = 2, nf = 0, ns = 0;
+    for (const char *p = nt->shorty; *p != ')'; p++) {
+        uint64_t v = (*p == 'F' || *p == 'D') ? (nf < 8 ? fpr[nf++] : stack[ns++]) : (ng < 8 ? gpr[ng++] : stack[ns++]);
+        switch (*p) {
+        case 'Z': ab_32(&B, (uint8_t)v); break;
+        case 'B': ab_32(&B, (uint32_t)(int32_t)(int8_t)v); break;
+        case 'C': ab_32(&B, (uint16_t)v); break;
+        case 'S': ab_32(&B, (uint32_t)(int32_t)(int16_t)v); break;
+        case 'I':
+        case 'F': ab_32(&B, (uint32_t)v); break; /* a float's bits are the low half of its register / slot */
+        case 'J':
+        case 'D': ab_64(&B, v); break;
+        default: ab_32(&B, o2h_local((jobject)v)); break;
+        }
+    }
+    uint64_t r = guest_call(nt->fn, B.w, B.n);
+    const char *rt = strchr(nt->shorty, ')') + 1;
+    switch (*rt) {
+    case 'V': r = 0; break;
+    case 'Z': r = (uint8_t)r; break;
+    case 'B': r = (uint64_t)(int64_t)(int8_t)r; break;
+    case 'C': r = (uint16_t)r; break;
+    case 'S': r = (uint64_t)(int64_t)(int16_t)r; break;
+    case 'I': r = (uint64_t)(int64_t)(int32_t)r; break;
+    case 'F': r = (uint32_t)r; break;
+    case 'J':
+    case 'D': break;
+    default: r = (uint64_t)(uintptr_t)h2o((uint32_t)r); break; /* still a valid reference: popped below is only the handle */
+    }
+    frame_pop(mark);
+    return r;
+}
+
+/* ---------------------------------------------------------------- Java_* exports */
+
+/* JNI short/long names: Java_<class>_<method>[__<argument types>] with '/' as '_' and the escapes _0xxxx (UTF-16
+ * unit), _1 '_', _2 ';', _3 '['. Returns 0 and fills cls ("a/b/C"), method and args (the long name's argument
+ * types, "" for a short name; *has_args says which). */
+static int demangle(const char *s, char *cls, char *method, char *args, size_t n, int *has_args)
+{
+    char path[512];
+    size_t k = 0;
+    char *out = path;
+    size_t cap = sizeof path;
+    *has_args = 0;
+    args[0] = 0;
+    for (s += 5; *s; s++) {
+        char ch = *s;
+        if (ch == '_') {
+            char e = s[1];
+            if (e == '1') ch = '_', s++;
+            else if (e == '2') ch = ';', s++;
+            else if (e == '3') ch = '[', s++;
+            else if (e == '0') {
+                unsigned u = 0;
+                for (int j = 0; j < 4; j++) {
+                    char h = s[2 + j];
+                    if (!h) return -1;
+                    u = u * 16 + (unsigned)(h <= '9' ? h - '0' : (h | 0x20) - 'a' + 10);
+                }
+                s += 5;
+                if (u >= 0x80) return -1; /* non-ASCII class names: not worth it */
+                ch = (char)u;
+            } else if (e == '_' && out == path) {
+                /* start of the long name's argument types */
+                out[k] = 0;
+                out = args;
+                cap = n;
+                k = 0;
+                *has_args = 1;
+                s++;
+                continue;
+            } else {
+                ch = '/';
+            }
+        }
+        if (k + 1 >= cap) return -1;
+        out[k++] = ch;
+    }
+    out[k] = 0;
+    char *slash = strrchr(path, '/');
+    if (!slash) return -1;
+    *slash = 0;
+    snprintf(cls, n, "%s", path);
+    snprintf(method, n, "%s", slash + 1);
+    return 0;
+}
+
+/* descriptor of a class object: "I", "Ljava/lang/String;", "[I" */
+static void class_descriptor(JNIEnv *env, jclass k, jmethodID get_name, char *out, size_t n)
+{
+    jstring s = (*env)->CallObjectMethod(env, k, get_name);
+    const char *nm = s ? (*env)->GetStringUTFChars(env, s, NULL) : NULL;
+    out[0] = 0;
+    if (nm) {
+        static const char *const prim[] = {"boolean", "byte", "char", "short", "int", "long", "float", "double",
+                                           "void"};
+        static const char letters[] = "ZBCSIJFDV";
+        int found = 0;
+        for (int i = 0; i < 9; i++)
+            if (!strcmp(nm, prim[i])) snprintf(out, n, "%c", letters[i]), found = 1;
+        if (!found) snprintf(out, n, nm[0] == '[' ? "%s" : "L%s;", nm);
+        for (char *p = out; *p; p++)
+            if (*p == '.') *p = '/';
+        (*env)->ReleaseStringUTFChars(env, s, nm);
+    }
+    if (s) (*env)->DeleteLocalRef(env, s);
+}
+
+/* The JNI signature of the native method `name` of cls (with argument types args when has_args). */
+static int native_signature(JNIEnv *env, jclass cls, const char *name, const char *args, int has_args, char *sig,
+                            size_t n)
+{
+    jclass kc = (*env)->FindClass(env, "java/lang/Class");
+    jclass km = (*env)->FindClass(env, "java/lang/reflect/Method");
+    jmethodID get_methods = (*env)->GetMethodID(env, kc, "getDeclaredMethods", "()[Ljava/lang/reflect/Method;");
+    jmethodID get_name = (*env)->GetMethodID(env, kc, "getName", "()Ljava/lang/String;");
+    jmethodID m_name = (*env)->GetMethodID(env, km, "getName", "()Ljava/lang/String;");
+    jmethodID m_mods = (*env)->GetMethodID(env, km, "getModifiers", "()I");
+    jmethodID m_params = (*env)->GetMethodID(env, km, "getParameterTypes", "()[Ljava/lang/Class;");
+    jmethodID m_ret = (*env)->GetMethodID(env, km, "getReturnType", "()Ljava/lang/Class;");
+    if (!get_methods || !get_name || !m_name || !m_mods || !m_params || !m_ret) return -1;
+    jobjectArray ms = (*env)->CallObjectMethod(env, cls, get_methods);
+    if (!ms || (*env)->ExceptionCheck(env)) return -1;
+    int found = -1;
+    jsize nm = (*env)->GetArrayLength(env, ms);
+    for (jsize i = 0; i < nm && found; i++) {
+        jobject m = (*env)->GetObjectArrayElement(env, ms, i);
+        jstring mn = (*env)->CallObjectMethod(env, m, m_name);
+        const char *mname = (*env)->GetStringUTFChars(env, mn, NULL);
+        int match = mname && !strcmp(mname, name) && ((*env)->CallIntMethod(env, m, m_mods) & 0x100 /* native */);
+        if (mname) (*env)->ReleaseStringUTFChars(env, mn, mname);
+        (*env)->DeleteLocalRef(env, mn);
+        if (match) {
+            char buf[1024], d[256];
+            size_t k = 0;
+            buf[k++] = '(';
+            jobjectArray ps = (*env)->CallObjectMethod(env, m, m_params);
+            jsize np = ps ? (*env)->GetArrayLength(env, ps) : 0;
+            for (jsize j = 0; j < np; j++) {
+                jclass pk = (*env)->GetObjectArrayElement(env, ps, j);
+                class_descriptor(env, pk, get_name, d, sizeof d);
+                (*env)->DeleteLocalRef(env, pk);
+                k += (size_t)snprintf(buf + k, sizeof buf - k, "%s", d);
+                if (k >= sizeof buf - 1) break;
+            }
+            if (ps) (*env)->DeleteLocalRef(env, ps);
+            buf[k] = 0;
+            if (!has_args || !strcmp(buf + 1, args)) {
+                jclass rk = (*env)->CallObjectMethod(env, m, m_ret);
+                class_descriptor(env, rk, get_name, d, sizeof d);
+                (*env)->DeleteLocalRef(env, rk);
+                snprintf(sig, n, "%s)%s", buf, d);
+                found = 0;
+            }
+        }
+        (*env)->DeleteLocalRef(env, m);
+    }
+    (*env)->DeleteLocalRef(env, ms);
+    return found;
+}
+
+void natives_register_java(JNIEnv *env, uint32_t handle, const char *libname)
+{
+    uint32_t prefix = guest_strdup("Java_");
+    uint32_t w[2] = {handle, prefix};
+    uint32_t list = (uint32_t)guest_call(g_info.fn_list_symbols, w, 2);
+    guest_free(prefix);
+    if (!list) return;
+    int ok = 0, failed = 0;
+    for (uint32_t e = list; ld32(e); e += 8) {
+        const char *sym = g2p(ld32(e));
+        uint32_t addr = ld32(e + 4);
+        char cls[512], method[512], args[512], sig[1024];
+        int has_args;
+        if (demangle(sym, cls, method, args, sizeof cls, &has_args)) {
+            bridge_log(ANDROID_LOG_WARN, "%s: can't decode %s", libname, sym);
+            failed++;
+            continue;
+        }
+        jclass k = (*env)->FindClass(env, cls);
+        if (!k) {
+            (*env)->ExceptionClear(env);
+            bridge_log(ANDROID_LOG_WARN, "%s: %s: class %s not found", libname, sym, cls);
+            failed++;
+            continue;
+        }
+        if (native_signature(env, k, method, args, has_args, sig, sizeof sig)) {
+            if ((*env)->ExceptionCheck(env)) (*env)->ExceptionClear(env);
+            bridge_log(ANDROID_LOG_WARN, "%s: %s: no native method %s in %s", libname, sym, method, cls);
+            (*env)->DeleteLocalRef(env, k);
+            failed++;
+            continue;
+        }
+        JNINativeMethod m = {method, sig, natives_trampoline_named(addr, sig, method)};
+        if (!m.fnPtr || (*env)->RegisterNatives(env, k, &m, 1)) {
+            if ((*env)->ExceptionCheck(env)) (*env)->ExceptionClear(env);
+            bridge_log(ANDROID_LOG_WARN, "%s: registering %s.%s%s failed", libname, cls, method, sig);
+            failed++;
+        } else {
+            ok++;
+        }
+        (*env)->DeleteLocalRef(env, k);
+    }
+    guest_free(list);
+    if (ok || failed) bridge_log(ANDROID_LOG_INFO, "%s: %d Java_ functions registered, %d not", libname, ok, failed);
+}
@@ -0,0 +1,22 @@
+/* The stub: one copy per 32-bit library, renamed to that library's name (libX.so; the guest code is libX.a32.so).
+ * It only finds its own path and hands JNI_OnLoad / ANativeActivity_onCreate to the bridge. */
+#include <dlfcn.h>
+#include <stddef.h>
+#include "a32bridge.h"
+
+static const char *self_path(void)
+{
+    Dl_info info;
+    return dladdr((void *)self_path, &info) && info.dli_fname ? info.dli_fname : "";
+}
+
+A32B_API jint JNI_OnLoad(JavaVM *vm, void *reserved)
+{
+    (void)reserved;
+    return a32b_jni_onload(vm, self_path());
+}
+
+A32B_API void ANativeActivity_onCreate(struct ANativeActivity *activity, void *saved, size_t saved_size)
+{
+    a32b_native_activity_oncreate(activity, saved, saved_size, self_path());
+}
@@ -0,0 +1,44 @@
+/* Native method trampolines: ART calls a32b_tramp_table + 8 * n with the AAPCS64 JNI arguments; slot n says which
+ * guest function and shorty (natives.c). Every slot is "adr x16, . ; b common": common turns x16 into the slot
+ * number, saves the argument registers and calls a32b_native_call(n, gpr[8], fpr[8], stack args). The result comes
+ * back in x0 and is copied to d0 as well (float and double results use s0/d0). */
+#define NTRAMP 4096
+
+    .text
+    .p2align 3
+    .global a32b_tramp_table
+    .hidden a32b_tramp_table
+    .type a32b_tramp_table, %function
+a32b_tramp_table:
+    .rept NTRAMP
+    adr x16, .
+    b a32b_tramp_common
+    .endr
+    .size a32b_tramp_table, . - a32b_tramp_table
+
+    .type a32b_tramp_common, %function
+a32b_tramp_common:
+    stp x29, x30, [sp, #-160]!
+    mov x29, sp
+    stp x0, x1, [sp, #16]
+    stp x2, x3, [sp, #32]
+    stp x4, x5, [sp, #48]
+    stp x6, x7, [sp, #64]
+    stp d0, d1, [sp, #80]
+    stp d2, d3, [sp, #96]
+    stp d4, d5, [sp, #112]
+    stp d6, d7, [sp, #128]
+    adrp x17, a32b_tramp_table
+    add x17, x17, :lo12:a32b_tramp_table
+    sub x0, x16, x17
+    lsr x0, x0, #3
+    add x1, sp, #16
+    add x2, sp, #80
+    add x3, sp, #160
+    bl a32b_native_call
+    fmov d0, x0
+    ldp x29, x30, [sp], #160
+    ret
+    .size a32b_tramp_common, . - a32b_tramp_common
+
+    .section .note.GNU-stack, "", %progbits
@@ -0,0 +1,183 @@
+# Host functions guest libraries can call (libandroid, ...). One per line: [!] <result> <name>(<arguments>)
+# Types: v void, I 32-bit int, J 64-bit int, f float, P guest pointer (passed through: guest memory is host memory),
+# H host pointer handle (ANativeWindow*, ...: a 32-bit handle on the guest side), A ANativeActivity*, E JNIEnv*
+# (the guest's -> the thread's own), O jobject (handle). Results also: S string (copied into guest memory).
+# "!" = written by hand in host/android.c or host/input.c (input events) as imp_<name>(a32_cpu *c, argreader *R).
+# The host functions are weak references: one the system lacks logs its name and returns 0.
+! v ANativeActivity_finish(A)
+v ANativeActivity_setWindowFormat(AI)
+v ANativeActivity_setWindowFlags(AII)
+v ANativeActivity_showSoftInput(AI)
+v ANativeActivity_hideSoftInput(AI)
+v ANativeWindow_acquire(H)
+v ANativeWindow_release(H)
+I ANativeWindow_getWidth(H)
+I ANativeWindow_getHeight(H)
+I ANativeWindow_getFormat(H)
+I ANativeWindow_setBuffersGeometry(HIII)
+H ANativeWindow_fromSurface(EO)
+H AAssetManager_fromJava(EO)
+! I AInputEvent_getType(H)
+! I AInputEvent_getDeviceId(H)
+! I AInputEvent_getSource(H)
+! I AKeyEvent_getAction(H)
+! I AKeyEvent_getKeyCode(H)
+! I AKeyEvent_getMetaState(H)
+! I AKeyEvent_getRepeatCount(H)
+! I AKeyEvent_getFlags(H)
+H ALooper_forThread()
+H ALooper_prepare(I)
+H ASensorManager_getInstance()
+H ASensorManager_getInstanceForPackage(P)
+H ASensorManager_getDefaultSensor(HI)
+! I ASensorManager_getSensorList(HP)
+! H ASensorManager_createEventQueue(HHIPP)
+I ASensorManager_destroyEventQueue(HH)
+I ASensorEventQueue_enableSensor(HH)
+I ASensorEventQueue_disableSensor(HH)
+I ASensorEventQueue_setEventRate(HHI)
+I ASensorEventQueue_hasEvents(H)
+I ASensorEventQueue_getEvents(HPI)
+I ASensor_getMinDelay(H)
+S ASensor_getName(H)
+S ASensor_getVendor(H)
+I ASensor_getType(H)
+f ASensor_getResolution(H)
+# VrApi 1.x (Gear VR era: vrapi_SubmitFrame/ovrFrameParms), translated to the 64-bit VrApi bridge (host/vrapi.c)
+! I vrapi_Initialize(P)
+! v vrapi_Shutdown()
+! S vrapi_GetVersionString()
+! v vrapi_GetTimeInSeconds()
+! I vrapi_GetSystemPropertyInt(PI)
+! f vrapi_GetSystemPropertyFloat(PI)
+! S vrapi_GetSystemPropertyString(PI)
+! I vrapi_GetSystemStatusInt(PI)
+! f vrapi_GetSystemStatusFloat(PI)
+! H vrapi_EnterVrMode(P)
+! v vrapi_LeaveVrMode(H)
+! v vrapi_GetPredictedDisplayTime(HJ)
+! v vrapi_GetPredictedTracking(PH)
+! v vrapi_RecenterPose(H)
+! H vrapi_CreateTextureSwapChain(IIIIII)
+! H vrapi_CreateTextureSwapChain2(IIIIII)
+! v vrapi_DestroyTextureSwapChain(H)
+! I vrapi_GetTextureSwapChainLength(H)
+! I vrapi_GetTextureSwapChainHandle(HI)
+! v vrapi_SetTextureSwapChainHandle(HII)
+! v vrapi_SubmitFrame(HP)
+! I vrapi_EnumerateInputDevices(HIP)
+! I vrapi_GetInputDeviceCapabilities(HP)
+! I vrapi_GetCurrentInputState(HIP)
+! I vrapi_GetInputTrackingState(HIJP)
+! v vrapi_RecenterInputPose(HI)
+! I vrapi_SetRemoteEmulation(HI)
+! v vrapi_SetPropertyInt(PII)
+! v vrapi_SetPropertyFloat(PIf)
+! I vrapi_GetPropertyInt(PI)
+! I vrapi_ShowSystemUI(PI)
+! I vrapi_ShowSystemUIWithExtra(PIP)
+! v vrapi_ShowFatalError(PPPP)
+! v vrapi_ReturnToHome(P)
+! P ovr_GetLocalPreferenceValueForKey(PP)
+! v ovr_SetLocalPreferenceValueForKey(PP)
+# audio output for guest/opensles.c (AAudio)
+! H a32_audio_open(III)
+! I a32_audio_write(HPI)
+! v a32_audio_start(H)
+! v a32_audio_pause(H)
+! v a32_audio_close(H)
+# VrApi 1.2x-1.4x (Go/Quest era: vrapi_SubmitFrame2, WaitFrame/BeginFrame), same translation (host/vrapi.c)
+! H vrapi_CreateTextureSwapChain3(IJIIII)
+! v vrapi_GetPredictedTracking2(PHD)
+! I vrapi_SubmitFrame2(HP)
+! I vrapi_WaitFrame(HJ)
+! I vrapi_BeginFrame(HJ)
+! I vrapi_SetDisplayRefreshRate(Hf)
+! I vrapi_PollEvent(P)
+! I vrapi_GetSystemPropertyFloatArray(PIPI)
+! I vrapi_SetTrackingSpace(HI)
+! I vrapi_GetTrackingSpace(H)
+! v vrapi_LocateTrackingSpace(PHI)
+! v vrapi_GetTrackingTransform(PHI)
+! v vrapi_SetTrackingTransform(Hfffffff)
+! I vrapi_GetBoundaryGeometry(HIPP)
+! I vrapi_GetBoundaryOrientedBoundingBox(HPP)
+! I vrapi_TestPointIsInBoundary(HPPP)
+! I vrapi_GetBoundaryTriggerState(HIP)
+! I vrapi_RequestBoundaryVisible(HI)
+! I vrapi_GetBoundaryVisible(HP)
+! I vrapi_SetHapticVibrationSimple(HIf)
+! I vrapi_SetHapticVibrationBuffer(HIP)
+! I vrapi_SetClockLevels(HII)
+! I vrapi_SetPerfThread(HII)
+! I vrapi_SetExtraLatencyMode(HI)
+! H vrapi_CreateAndroidSurfaceSwapChain(II)
+! H vrapi_CreateAndroidSurfaceSwapChain2(IIIP)
+! H vrapi_GetTextureSwapChainAndroidSurface(H)
+! I vrapi_CreateSystemVulkan(P)
+! v vrapi_DestroySystemVulkan()
+! I vrapi_GetInstanceExtensionsVulkan(PP)
+! I vrapi_GetDeviceExtensionsVulkan(PP)
+! I vrapi_GetTextureSwapChainBufferVulkan(HI)
+! I vrapi_GetTextureSwapChainBufferFoveationVulkan(HIPP)
+
+# NativeActivity games built on android_native_app_glue (e.g. Unreal 4.10 Gear VR games): looper, input queue,
+# configuration and assets
+H AConfiguration_new()
+v AConfiguration_delete(H)
+v AConfiguration_fromAssetManager(HH)
+v AConfiguration_getLanguage(HP)
+v AConfiguration_getCountry(HP)
+I AConfiguration_getOrientation(H)
+I AConfiguration_getDensity(H)
+I AConfiguration_getSdkVersion(H)
+I AConfiguration_getMcc(H)
+I AConfiguration_getMnc(H)
+I AConfiguration_getTouchscreen(H)
+I AConfiguration_getKeyboard(H)
+I AConfiguration_getNavigation(H)
+I AConfiguration_getKeysHidden(H)
+I AConfiguration_getNavHidden(H)
+I AConfiguration_getScreenSize(H)
+I AConfiguration_getScreenLong(H)
+I AConfiguration_getUiModeType(H)
+I AConfiguration_getUiModeNight(H)
+! I AMotionEvent_getAction(H)
+! I AMotionEvent_getPointerCount(H)
+! I AMotionEvent_getPointerId(HI)
+! f AMotionEvent_getX(HI)
+! f AMotionEvent_getY(HI)
+! f AMotionEvent_getRawX(HI)
+! f AMotionEvent_getRawY(HI)
+! f AMotionEvent_getAxisValue(HII)
+! I AMotionEvent_getButtonState(H)
+! v AInputQueue_attachLooper(HHIPP)
+! v AInputQueue_detachLooper(H)
+! I AInputQueue_hasEvents(H)
+! I AInputQueue_getEvent(HP)
+! I AInputQueue_preDispatchEvent(HH)
+! v AInputQueue_finishEvent(HHI)
+! I ALooper_addFd(HIIIPP)
+I ALooper_removeFd(HI)
+! I ALooper_pollAll(IPPP)
+! I ALooper_pollOnce(IPPP)
+v ALooper_wake(H)
+v ALooper_acquire(H)
+v ALooper_release(H)
+H AAssetManager_open(HPI)
+H AAssetManager_openDir(HP)
+! S AAssetDir_getNextFileName(H)
+v AAssetDir_rewind(H)
+v AAssetDir_close(H)
+! v AAsset_close(H)
+! P AAsset_getBuffer(H)
+I AAsset_read(HPI)
+I AAsset_seek(HII)
+J AAsset_seek64(HJI)
+I AAsset_getLength(H)
+J AAsset_getLength64(H)
+I AAsset_getRemainingLength(H)
+J AAsset_getRemainingLength64(H)
+! I AAsset_openFileDescriptor(HPP)
+! I AAsset_openFileDescriptor64(HPP)
+I AAsset_isAllocated(H)
@@ -0,0 +1,593 @@
+/* Fake JVM (see fakejni.h). Objects are never freed; references are the object pointers. Only what the bridge and
+ * the test libraries use is implemented: everything else aborts with the function's index. */
+#define _GNU_SOURCE
+#include "fakejni.h"
+#include <pthread.h>
+#include <stdarg.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/mman.h>
+
+enum { O_CLASS = 1, O_STRING, O_ARRAY, O_OBJECT, O_METHOD };
+
+struct fclass {
+    char name[256]; /* dotted, as Class.getName() returns it */
+    fmethod *methods;
+    int nmethods;
+};
+
+typedef struct fobj {
+    int kind;
+    fclass *cls;
+    union {
+        fclass *klass;  /* O_CLASS */
+        char *utf;      /* O_STRING */
+        fmethod *m;     /* O_METHOD */
+        int field;      /* O_OBJECT */
+        struct { char type; int len; void *data; } arr;
+    };
+} fobj;
+
+static fclass *classes[256];
+static int nclasses;
+static __thread int attached;
+static __thread char exc[256];
+static __thread int exc_pending;
+static pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;
+
+#define O(x) ((fobj *)(x))
+
+static void dotted(const char *in, char *out, size_t n)
+{
+    snprintf(out, n, "%s", in);
+    for (char *p = out; *p; p++)
+        if (*p == '/') *p = '.';
+}
+
+static fclass *find_class(const char *dname)
+{
+    for (int k = 0; k < nclasses; k++)
+        if (!strcmp(classes[k]->name, dname)) return classes[k];
+    return NULL;
+}
+
+static fclass *get_class(const char *dname)
+{
+    pthread_mutex_lock(&lock);
+    fclass *c = find_class(dname);
+    if (!c) {
+        c = calloc(1, sizeof *c);
+        snprintf(c->name, sizeof c->name, "%s", dname);
+        classes[nclasses++] = c;
+    }
+    pthread_mutex_unlock(&lock);
+    return c;
+}
+
+static fobj *class_obj(fclass *k)
+{
+    fobj *o = calloc(1, sizeof *o);
+    o->kind = O_CLASS;
+    o->cls = get_class("java.lang.Class");
+    o->klass = k;
+    return o;
+}
+
+fclass *fake_class(const char *name, const fmethod *methods)
+{
+    char d[256];
+    dotted(name, d, sizeof d);
+    fclass *c = get_class(d);
+    int n = 0;
+    while (methods && methods[n].name) n++;
+    c->methods = calloc((size_t)n + 1, sizeof *c->methods);
+    memcpy(c->methods, methods, (size_t)n * sizeof *methods);
+    c->nmethods = n;
+    for (int k = 0; k < n; k++) c->methods[k].cls = c;
+    return c;
+}
+
+fmethod *fake_method(fclass *c, const char *name, const char *sig)
+{
+    for (int k = 0; k < c->nmethods; k++)
+        if (!strcmp(c->methods[k].name, name) && (!sig || !strcmp(c->methods[k].sig, sig))) return &c->methods[k];
+    return NULL;
+}
+
+jstring fake_string(const char *utf)
+{
+    fobj *o = calloc(1, sizeof *o);
+    o->kind = O_STRING;
+    o->cls = get_class("java.lang.String");
+    o->utf = strdup(utf);
+    return (jstring)o;
+}
+
+const char *fake_utf(jstring s) { return s ? O(s)->utf : NULL; }
+
+static int esize(char t) { return t == 'Z' || t == 'B' ? 1 : t == 'C' || t == 'S' ? 2 : t == 'J' || t == 'D' ? 8 : 4; }
+
+/* "heap" memory below 4 GiB, as ART's */
+static void *low_alloc(size_t n)
+{
+    static uint8_t *arena;
+    static size_t used;
+    pthread_mutex_lock(&lock);
+    if (!arena) {
+        arena = mmap((void *)0x30000000, 16 << 20, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS | MAP_FIXED_NOREPLACE,
+                     -1, 0);
+        if (arena == MAP_FAILED) abort();
+    }
+    void *p = arena + used;
+    used += (n + 15) & ~(size_t)15;
+    pthread_mutex_unlock(&lock);
+    return p;
+}
+
+static void *high_alloc(size_t n)
+{
+    void *p = mmap((void *)0x7100000000, (n + 4095) & ~(size_t)4095, PROT_READ | PROT_WRITE,
+                   MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
+    if (p == MAP_FAILED || (uintptr_t)p < 0x100000000ull) {
+        fprintf(stderr, "fake JNI: no memory above 4 GiB (%p)\n", p);
+        abort();
+    }
+    return p;
+}
+
+jarray fake_array(char type, int len, int low)
+{
+    fobj *o = calloc(1, sizeof *o);
+    o->kind = O_ARRAY;
+    char cn[256];
+    if (type == 'L') snprintf(cn, sizeof cn, "[Ljava.lang.Object;");
+    else snprintf(cn, sizeof cn, "[%c", type);
+    o->cls = get_class(cn);
+    o->arr.type = type;
+    o->arr.len = len;
+    size_t n = (size_t)len * (type == 'L' ? sizeof(void *) : (size_t)esize(type));
+    o->arr.data = low ? low_alloc(n ? n : 1) : high_alloc(n ? n : 1);
+    memset(o->arr.data, 0, n);
+    return (jarray)o;
+}
+
+void *fake_array_data(jarray a) { return O(a)->arr.data; }
+int fake_get_int_field(jobject o) { return O(o)->field; }
+
+const char *fake_take_exception(void)
+{
+    if (!exc_pending) return NULL;
+    exc_pending = 0;
+    return exc;
+}
+
+static void throw(const char *fmt, ...)
+{
+    va_list ap;
+    va_start(ap, fmt);
+    vsnprintf(exc, sizeof exc, fmt, ap);
+    va_end(ap);
+    exc_pending = 1;
+}
+
+/* ---------------------------------------------------------------- reflection (java.lang.Class / Method) */
+
+static jvalue class_get_name(JNIEnv *env, jobject self, const jvalue *a)
+{
+    (void)env, (void)a;
+    jvalue r;
+    r.l = fake_string(O(self)->klass->name);
+    return r;
+}
+
+/* the class object of one descriptor at *p (advances it) */
+static fobj *descriptor_class(const char **p)
+{
+    static const char *const prim[] = {"boolean", "byte", "char", "short", "int", "long", "float", "double", "void"};
+    static const char letters[] = "ZBCSIJFDV";
+    char name[256];
+    const char *s = *p;
+    if (*s == '[') {
+        const char *e = s;
+        while (*e == '[') e++;
+        e = *e == 'L' ? strchr(e, ';') + 1 : e + 1;
+        snprintf(name, sizeof name, "%.*s", (int)(e - s), s);
+        for (char *q = name; *q; q++)
+            if (*q == '/') *q = '.';
+        *p = e;
+    } else if (*s == 'L') {
+        const char *e = strchr(s, ';');
+        snprintf(name, sizeof name, "%.*s", (int)(e - s - 1), s + 1);
+        for (char *q = name; *q; q++)
+            if (*q == '/') *q = '.';
+        *p = e + 1;
+    } else {
+        snprintf(name, sizeof name, "%s", prim[strchr(letters, *s) - letters]);
+        *p = s + 1;
+    }
+    return class_obj(get_class(name));
+}
+
+static jvalue class_get_declared_methods(JNIEnv *env, jobject self, const jvalue *a)
+{
+    (void)env, (void)a;
+    fclass *k = O(self)->klass;
+    jarray arr = fake_array('L', k->nmethods, 0);
+    O(arr)->cls = get_class("[Ljava.lang.reflect.Method;");
+    for (int i = 0; i < k->nmethods; i++) {
+        fobj *m = calloc(1, sizeof *m);
+        m->kind = O_METHOD;
+        m->cls = get_class("java.lang.reflect.Method");
+        m->m = &k->methods[i];
+        ((fobj **)O(arr)->arr.data)[i] = m;
+    }
+    jvalue r;
+    r.l = arr;
+    return r;
+}
+
+static jvalue method_get_name(JNIEnv *env, jobject self, const jvalue *a)
+{
+    (void)env, (void)a;
+    jvalue r;
+    r.l = fake_string(O(self)->m->name);
+    return r;
+}
+
+static jvalue method_get_modifiers(JNIEnv *env, jobject self, const jvalue *a)
+{
+    (void)env, (void)a;
+    jvalue r;
+    r.i = (O(self)->m->is_native ? 0x100 : 0) | (O(self)->m->is_static ? 0x8 : 0) | 1;
+    return r;
+}
+
+static jvalue method_get_parameter_types(JNIEnv *env, jobject self, const jvalue *a)
+{
+    (void)env, (void)a;
+    const char *p = O(self)->m->sig + 1;
+    fobj *tmp[64];
+    int n = 0;
+    while (*p != ')') tmp[n++] = descriptor_class(&p);
+    jarray arr = fake_array('L', n, 0);
+    O(arr)->cls = get_class("[Ljava.lang.Class;");
+    memcpy(O(arr)->arr.data, tmp, (size_t)n * sizeof *tmp);
+    jvalue r;
+    r.l = arr;
+    return r;
+}
+
+static jvalue method_get_return_type(JNIEnv *env, jobject self, const jvalue *a)
+{
+    (void)env, (void)a;
+    const char *p = strchr(O(self)->m->sig, ')') + 1;
+    jvalue r;
+    r.l = descriptor_class(&p);
+    return r;
+}
+
+/* ---------------------------------------------------------------- JNIEnv */
+
+static jint GetVersion(JNIEnv *env) { (void)env; return JNI_VERSION_1_6; }
+
+static jclass FindClass(JNIEnv *env, const char *name)
+{
+    (void)env;
+    char d[256];
+    dotted(name, d, sizeof d);
+    pthread_mutex_lock(&lock);
+    fclass *c = find_class(d);
+    pthread_mutex_unlock(&lock);
+    if (!c) {
+        throw("java.lang.NoClassDefFoundError: %s", name);
+        return NULL;
+    }
+    return (jclass)class_obj(c);
+}
+
+static jclass GetObjectClass(JNIEnv *env, jobject o) { (void)env; return (jclass)class_obj(O(o)->cls); }
+static jboolean IsInstanceOf(JNIEnv *env, jobject o, jclass k) { (void)env; return o && O(o)->cls == O(k)->klass; }
+static jboolean IsSameObject(JNIEnv *env, jobject a, jobject b) { (void)env; return a == b; }
+static jobject NewRef(JNIEnv *env, jobject o) { (void)env; return o; }
+static void DeleteRef(JNIEnv *env, jobject o) { (void)env, (void)o; }
+static jint PushLocalFrame(JNIEnv *env, jint n) { (void)env, (void)n; return 0; }
+static jobject PopLocalFrame(JNIEnv *env, jobject o) { (void)env; return o; }
+static jint EnsureLocalCapacity(JNIEnv *env, jint n) { (void)env, (void)n; return 0; }
+
+static jboolean ExceptionCheck(JNIEnv *env) { (void)env; return (jboolean)exc_pending; }
+static void ExceptionClear(JNIEnv *env) { (void)env; exc_pending = 0; }
+static jthrowable ExceptionOccurred(JNIEnv *env) { (void)env; return exc_pending ? (jthrowable)fake_string(exc) : NULL; }
+static void ExceptionDescribe(JNIEnv *env) { (void)env; if (exc_pending) fprintf(stderr, "fake JNI exception: %s\n", exc); }
+static jint ThrowNew(JNIEnv *env, jclass k, const char *msg)
+{
+    (void)env;
+    throw("%s: %s", O(k)->klass->name, msg);
+    return 0;
+}
+
+static jmethodID GetMethodID(JNIEnv *env, jclass k, const char *name, const char *sig)
+{
+    (void)env;
+    fmethod *m = fake_method(O(k)->klass, name, sig);
+    if (!m || m->is_static) {
+        throw("java.lang.NoSuchMethodError: %s%s", name, sig);
+        return NULL;
+    }
+    return (jmethodID)m;
+}
+
+static jmethodID GetStaticMethodID(JNIEnv *env, jclass k, const char *name, const char *sig)
+{
+    (void)env;
+    fmethod *m = fake_method(O(k)->klass, name, sig);
+    if (!m || !m->is_static) {
+        throw("java.lang.NoSuchMethodError: %s%s", name, sig);
+        return NULL;
+    }
+    return (jmethodID)m;
+}
+
+static jfieldID GetFieldID(JNIEnv *env, jclass k, const char *name, const char *sig)
+{
+    (void)env, (void)k, (void)sig;
+    return strcmp(name, "value") ? NULL : (jfieldID)1;
+}
+static jint GetIntField(JNIEnv *env, jobject o, jfieldID f) { (void)env, (void)f; return O(o)->field; }
+static void SetIntField(JNIEnv *env, jobject o, jfieldID f, jint v) { (void)env, (void)f; O(o)->field = v; }
+
+/* calls a Java method (impl) or a native one (through its registered pointer, ART style) */
+jvalue fake_invoke(JNIEnv *env, fmethod *m, jobject self, const jvalue *a);
+
+static jvalue call(JNIEnv *env, jobject self, jmethodID mid, const jvalue *a)
+{
+    fmethod *m = (fmethod *)mid;
+    if (!m) {
+        fprintf(stderr, "fake JNI: call with a NULL method ID\n");
+        abort();
+    }
+    return fake_invoke(env, m, self, a);
+}
+
+/* "..." forms: used by the bridge only for methods without arguments */
+static jobject CallObjectMethod(JNIEnv *env, jobject o, jmethodID m, ...)
+{
+    if (((fmethod *)m)->sig[1] != ')') abort();
+    return call(env, o, m, NULL).l;
+}
+static jint CallIntMethod(JNIEnv *env, jobject o, jmethodID m, ...)
+{
+    if (((fmethod *)m)->sig[1] != ')') abort();
+    return call(env, o, m, NULL).i;
+}
+
+static jobject CallObjectMethodA(JNIEnv *env, jobject o, jmethodID m, const jvalue *a) { return call(env, o, m, a).l; }
+static jboolean CallBooleanMethodA(JNIEnv *env, jobject o, jmethodID m, const jvalue *a) { return call(env, o, m, a).z; }
+static jbyte CallByteMethodA(JNIEnv *env, jobject o, jmethodID m, const jvalue *a) { return call(env, o, m, a).b; }
+static jchar CallCharMethodA(JNIEnv *env, jobject o, jmethodID m, const jvalue *a) { return call(env, o, m, a).c; }
+static jshort CallShortMethodA(JNIEnv *env, jobject o, jmethodID m, const jvalue *a) { return call(env, o, m, a).s; }
+static jint CallIntMethodA(JNIEnv *env, jobject o, jmethodID m, const jvalue *a) { return call(env, o, m, a).i; }
+static jlong CallLongMethodA(JNIEnv *env, jobject o, jmethodID m, const jvalue *a) { return call(env, o, m, a).j; }
+static jfloat CallFloatMethodA(JNIEnv *env, jobject o, jmethodID m, const jvalue *a) { return call(env, o, m, a).f; }
+static jdouble CallDoubleMethodA(JNIEnv *env, jobject o, jmethodID m, const jvalue *a) { return call(env, o, m, a).d; }
+static void CallVoidMethodA(JNIEnv *env, jobject o, jmethodID m, const jvalue *a) { call(env, o, m, a); }
+static jobject CallStaticObjectMethodA(JNIEnv *env, jclass k, jmethodID m, const jvalue *a) { (void)k; return call(env, NULL, m, a).l; }
+static jint CallStaticIntMethodA(JNIEnv *env, jclass k, jmethodID m, const jvalue *a) { (void)k; return call(env, NULL, m, a).i; }
+static jlong CallStaticLongMethodA(JNIEnv *env, jclass k, jmethodID m, const jvalue *a) { (void)k; return call(env, NULL, m, a).j; }
+static jfloat CallStaticFloatMethodA(JNIEnv *env, jclass k, jmethodID m, const jvalue *a) { (void)k; return call(env, NULL, m, a).f; }
+static jdouble CallStaticDoubleMethodA(JNIEnv *env, jclass k, jmethodID m, const jvalue *a) { (void)k; return call(env, NULL, m, a).d; }
+static void CallStaticVoidMethodA(JNIEnv *env, jclass k, jmethodID m, const jvalue *a) { (void)k; call(env, NULL, m, a); }
+static jboolean CallStaticBooleanMethodA(JNIEnv *env, jclass k, jmethodID m, const jvalue *a) { (void)k; return call(env, NULL, m, a).z; }
+
+static jobject NewObjectA(JNIEnv *env, jclass k, jmethodID m, const jvalue *a)
+{
+    fobj *o = calloc(1, sizeof *o);
+    o->kind = O_OBJECT;
+    o->cls = O(k)->klass;
+    call(env, (jobject)o, m, a);
+    return (jobject)o;
+}
+
+static jstring NewStringUTF(JNIEnv *env, const char *s) { (void)env; return fake_string(s); }
+static jsize GetStringUTFLength(JNIEnv *env, jstring s) { (void)env; return (jsize)strlen(O(s)->utf); }
+static jsize GetStringLength(JNIEnv *env, jstring s) { (void)env; return (jsize)strlen(O(s)->utf); } /* ASCII only */
+static void GetStringRegion(JNIEnv *env, jstring s, jsize start, jsize len, jchar *buf)
+{
+    (void)env;
+    for (jsize k = 0; k < len; k++) buf[k] = (jchar)O(s)->utf[start + k];
+}
+static const char *GetStringUTFChars(JNIEnv *env, jstring s, jboolean *is_copy)
+{
+    (void)env;
+    if (is_copy) *is_copy = JNI_TRUE;
+    char *p = high_alloc(strlen(O(s)->utf) + 1); /* malloc'd copies live high on Android */
+    strcpy(p, O(s)->utf);
+    return p;
+}
+static void ReleaseStringUTFChars(JNIEnv *env, jstring s, const char *p) { (void)env, (void)s, (void)p; }
+
+static jsize GetArrayLength(JNIEnv *env, jarray a) { (void)env; return O(a)->arr.len; }
+static jobject GetObjectArrayElement(JNIEnv *env, jobjectArray a, jsize i) { (void)env; return ((jobject *)O(a)->arr.data)[i]; }
+static void SetObjectArrayElement(JNIEnv *env, jobjectArray a, jsize i, jobject v) { (void)env; ((jobject *)O(a)->arr.data)[i] = v; }
+static jintArray NewIntArray(JNIEnv *env, jsize n) { (void)env; return (jintArray)fake_array('I', n, 1); }
+static void *GetElements(JNIEnv *env, jarray a, jboolean *is_copy)
+{
+    (void)env;
+    if (is_copy) *is_copy = JNI_FALSE;
+    return O(a)->arr.data;
+}
+static void ReleaseElements(JNIEnv *env, jarray a, void *p, jint mode) { (void)env, (void)a, (void)p, (void)mode; }
+static void GetIntArrayRegion(JNIEnv *env, jintArray a, jsize s, jsize n, jint *buf) { (void)env; memcpy(buf, (jint *)O(a)->arr.data + s, (size_t)n * 4); }
+static void SetIntArrayRegion(JNIEnv *env, jintArray a, jsize s, jsize n, const jint *buf) { (void)env; memcpy((jint *)O(a)->arr.data + s, buf, (size_t)n * 4); }
+
+static jint RegisterNatives(JNIEnv *env, jclass k, const JNINativeMethod *ms, jint n)
+{
+    (void)env;
+    for (jint i = 0; i < n; i++) {
+        fmethod *m = fake_method(O(k)->klass, ms[i].name, ms[i].signature);
+        if (!m || !m->is_native) {
+            throw("java.lang.NoSuchMethodError: no native method %s%s", ms[i].name, ms[i].signature);
+            return JNI_ERR;
+        }
+        m->native_fn = ms[i].fnPtr;
+    }
+    return JNI_OK;
+}
+
+static jint GetJavaVM(JNIEnv *env, JavaVM **vm) { (void)env; *vm = fake_vm(); return 0; }
+static void *GetDirectBufferAddress(JNIEnv *env, jobject b) { (void)env; return O(b)->arr.data; }
+static jlong GetDirectBufferCapacity(JNIEnv *env, jobject b) { (void)env; return O(b)->arr.len; }
+
+static struct JNINativeInterface env_table;
+static JNIEnv env_obj = &env_table;
+
+/* every function not implemented here: "mov w0, #index; b fake_unimplemented" */
+__asm__(".text\n.p2align 3\nfake_unimpl_table:\n.set i, 0\n.rept 233\nmov w0, #i\nb fake_unimplemented\n"
+        ".set i, i + 1\n.endr\n");
+extern const char fake_unimpl_table[];
+
+__attribute__((used)) void fake_unimplemented(int index)
+{
+    fprintf(stderr, "fake JNI: JNIEnv function %d is not implemented\n", index);
+    abort();
+}
+
+static void init_env(void)
+{
+    struct JNINativeInterface *t = &env_table;
+    void **slots = (void **)t;
+    for (int k = 0; k < 233; k++) slots[k] = (void *)(fake_unimpl_table + 8 * k);
+    t->GetVersion = GetVersion;
+    t->FindClass = FindClass;
+    t->GetObjectClass = GetObjectClass;
+    t->IsInstanceOf = IsInstanceOf;
+    t->IsSameObject = IsSameObject;
+    t->NewGlobalRef = NewRef;
+    t->NewLocalRef = NewRef;
+    t->NewWeakGlobalRef = NewRef;
+    t->DeleteGlobalRef = DeleteRef;
+    t->DeleteLocalRef = DeleteRef;
+    t->DeleteWeakGlobalRef = DeleteRef;
+    t->PushLocalFrame = PushLocalFrame;
+    t->PopLocalFrame = PopLocalFrame;
+    t->EnsureLocalCapacity = EnsureLocalCapacity;
+    t->ExceptionCheck = ExceptionCheck;
+    t->ExceptionClear = ExceptionClear;
+    t->ExceptionOccurred = ExceptionOccurred;
+    t->ExceptionDescribe = ExceptionDescribe;
+    t->ThrowNew = ThrowNew;
+    t->GetMethodID = GetMethodID;
+    t->GetStaticMethodID = GetStaticMethodID;
+    t->GetFieldID = GetFieldID;
+    t->GetIntField = GetIntField;
+    t->SetIntField = SetIntField;
+    t->CallObjectMethod = CallObjectMethod;
+    t->CallIntMethod = CallIntMethod;
+    t->CallObjectMethodA = CallObjectMethodA;
+    t->CallBooleanMethodA = CallBooleanMethodA;
+    t->CallByteMethodA = CallByteMethodA;
+    t->CallCharMethodA = CallCharMethodA;
+    t->CallShortMethodA = CallShortMethodA;
+    t->CallIntMethodA = CallIntMethodA;
+    t->CallLongMethodA = CallLongMethodA;
+    t->CallFloatMethodA = CallFloatMethodA;
+    t->CallDoubleMethodA = CallDoubleMethodA;
+    t->CallVoidMethodA = CallVoidMethodA;
+    t->CallStaticObjectMethodA = CallStaticObjectMethodA;
+    t->CallStaticBooleanMethodA = CallStaticBooleanMethodA;
+    t->CallStaticIntMethodA = CallStaticIntMethodA;
+    t->CallStaticLongMethodA = CallStaticLongMethodA;
+    t->CallStaticFloatMethodA = CallStaticFloatMethodA;
+    t->CallStaticDoubleMethodA = CallStaticDoubleMethodA;
+    t->CallStaticVoidMethodA = CallStaticVoidMethodA;
+    t->NewObjectA = NewObjectA;
+    t->NewStringUTF = NewStringUTF;
+    t->GetStringUTFLength = GetStringUTFLength;
+    t->GetStringLength = GetStringLength;
+    t->GetStringRegion = GetStringRegion;
+    t->GetStringUTFChars = GetStringUTFChars;
+    t->ReleaseStringUTFChars = ReleaseStringUTFChars;
+    t->GetArrayLength = GetArrayLength;
+    t->GetObjectArrayElement = GetObjectArrayElement;
+    t->SetObjectArrayElement = SetObjectArrayElement;
+    t->NewIntArray = NewIntArray;
+    t->GetIntArrayElements = (void *)GetElements;
+    t->ReleaseIntArrayElements = (void *)ReleaseElements;
+    t->GetFloatArrayElements = (void *)GetElements;
+    t->ReleaseFloatArrayElements = (void *)ReleaseElements;
+    t->GetByteArrayElements = (void *)GetElements;
+    t->ReleaseByteArrayElements = (void *)ReleaseElements;
+    t->GetPrimitiveArrayCritical = (void *)GetElements;
+    t->ReleasePrimitiveArrayCritical = (void *)ReleaseElements;
+    t->GetIntArrayRegion = GetIntArrayRegion;
+    t->SetIntArrayRegion = SetIntArrayRegion;
+    t->RegisterNatives = RegisterNatives;
+    t->GetJavaVM = GetJavaVM;
+    t->GetDirectBufferAddress = GetDirectBufferAddress;
+    t->GetDirectBufferCapacity = GetDirectBufferCapacity;
+
+    static const fmethod class_methods[] = {
+        {"getName", "()Ljava/lang/String;", 0, 0, class_get_name, NULL, NULL},
+        {"getDeclaredMethods", "()[Ljava/lang/reflect/Method;", 0, 0, class_get_declared_methods, NULL, NULL},
+        {NULL, NULL, 0, 0, NULL, NULL, NULL},
+    };
+    static const fmethod method_methods[] = {
+        {"getName", "()Ljava/lang/String;", 0, 0, method_get_name, NULL, NULL},
+        {"getModifiers", "()I", 0, 0, method_get_modifiers, NULL, NULL},
+        {"getParameterTypes", "()[Ljava/lang/Class;", 0, 0, method_get_parameter_types, NULL, NULL},
+        {"getReturnType", "()Ljava/lang/Class;", 0, 0, method_get_return_type, NULL, NULL},
+        {NULL, NULL, 0, 0, NULL, NULL, NULL},
+    };
+    fake_class("java/lang/Class", class_methods);
+    fake_class("java/lang/reflect/Method", method_methods);
+    fake_class("java/lang/String", NULL);
+    fake_class("java/lang/IllegalStateException", NULL);
+}
+
+JNIEnv *fake_env(void) { return &env_obj; }
+
+/* ---------------------------------------------------------------- JavaVM */
+
+static jint vm_get_env(JavaVM *vm, void **env, jint version)
+{
+    (void)vm, (void)version;
+    if (!attached) {
+        *env = NULL;
+        return JNI_EDETACHED;
+    }
+    *env = &env_obj;
+    return JNI_OK;
+}
+
+static jint vm_attach(JavaVM *vm, JNIEnv **env, void *args)
+{
+    (void)vm, (void)args;
+    attached = 1;
+    *env = &env_obj;
+    return JNI_OK;
+}
+
+static jint vm_detach(JavaVM *vm)
+{
+    (void)vm;
+    attached = 0;
+    return JNI_OK;
+}
+
+static struct JNIInvokeInterface vm_table = {
+    .GetEnv = vm_get_env,
+    .AttachCurrentThread = vm_attach,
+    .AttachCurrentThreadAsDaemon = vm_attach,
+    .DetachCurrentThread = vm_detach,
+};
+static JavaVM vm_obj = &vm_table;
+
+JavaVM *fake_vm(void)
+{
+    static pthread_once_t once = PTHREAD_ONCE_INIT;
+    pthread_once(&once, init_env);
+    return &vm_obj;
+}
+
+void fake_attach(void) { attached = 1; }
@@ -0,0 +1,35 @@
+/* A small fake JVM for testing the bridge without Android: classes and methods are C structs, Java methods are C
+ * functions, native methods are registered function pointers that the harness calls the way ART does. */
+#ifndef FAKEJNI_H
+#define FAKEJNI_H
+
+#include <jni.h>
+
+typedef struct fclass fclass;
+typedef struct fmethod fmethod;
+typedef jvalue (*fimpl)(JNIEnv *env, jobject self, const jvalue *args);
+
+struct fmethod {
+    const char *name, *sig;
+    int is_static, is_native;
+    fimpl impl;      /* Java methods */
+    void *native_fn; /* native methods: set by RegisterNatives */
+    fclass *cls;
+};
+
+JavaVM *fake_vm(void);
+JNIEnv *fake_env(void);
+void fake_attach(void); /* marks the calling thread as attached (ART threads are) */
+/* defines a class with methods (name, sig, static, native, impl); NULL name ends the list */
+fclass *fake_class(const char *name, const fmethod *methods);
+fmethod *fake_method(fclass *c, const char *name, const char *sig);
+jstring fake_string(const char *utf);
+const char *fake_utf(jstring s);
+/* a primitive array whose data lies below 4 GiB (like ART's heap) or above it */
+jarray fake_array(char type, int len, int low);
+void *fake_array_data(jarray a);
+/* the pending exception's message (NULL if none); clears it */
+const char *fake_take_exception(void);
+int fake_get_int_field(jobject o);
+
+#endif
@@ -0,0 +1,300 @@
+/* Bridge test harness: plays ART for the guest test libraries (libbtest*.a32.so) with the fake JVM.
+ *
+ *   harness <dir with liba32rt.so and the test libraries>
+ *
+ * Prints one line per check and "ALL OK" at the end (exit code 0), else the number of failed checks. */
+#define _GNU_SOURCE
+#include <android/native_activity.h>
+#include <pthread.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/mman.h>
+#include "a32bridge.h"
+#include "fakejni.h"
+
+static int failures;
+
+#define CHECK(cond, ...)                                                                                          \
+    do {                                                                                                          \
+        int ok_ = (cond);                                                                                         \
+        printf("%s ", ok_ ? "ok  " : "FAIL");                                                                     \
+        printf(__VA_ARGS__);                                                                                      \
+        printf("\n");                                                                                             \
+        fflush(stdout);                                                                                           \
+        if (!ok_) failures++;                                                                                     \
+    } while (0)
+
+/* ---------------------------------------------------------------- the "Java" class */
+
+static fclass *bridge_cls;
+static jclass bridge_jcls; /* what ART passes static natives */
+
+static jvalue j_add3(JNIEnv *env, jobject self, const jvalue *a)
+{
+    jvalue r;
+    r.i = a[0].i + a[1].i + a[2].i;
+    return r;
+}
+
+static jvalue j_mix(JNIEnv *env, jobject self, const jvalue *a)
+{
+    jvalue r;
+    r.d = a[0].i + (double)a[1].j + a[2].f + a[3].d + (double)strlen(fake_utf((jstring)a[4].l));
+    return r;
+}
+
+/* Java callBack(n) = nativeTwice(n) */
+static jvalue j_callback(JNIEnv *env, jobject self, const jvalue *a)
+{
+    jvalue r;
+    fmethod *m = fake_method(bridge_cls, "nativeTwice", "(I)I");
+    r.i = ((jint (*)(JNIEnv *, jclass, jint))m->native_fn)(env, bridge_jcls, a[0].i);
+    return r;
+}
+
+static jvalue j_ctor(JNIEnv *env, jobject self, const jvalue *a)
+{
+    (*env)->SetIntField(env, self, (*env)->GetFieldID(env, bridge_jcls, "value", "I"), a[0].i);
+    jvalue r;
+    r.j = 0;
+    return r;
+}
+
+static jvalue j_greet(JNIEnv *env, jobject self, const jvalue *a)
+{
+    char buf[128];
+    snprintf(buf, sizeof buf, "hello %s/%d", fake_utf((jstring)a[0].l), fake_get_int_field(self));
+    jvalue r;
+    r.l = fake_string(buf);
+    return r;
+}
+
+#define NATIVE(name, sig) {name, sig, 1, 1, NULL, NULL, NULL}
+static const fmethod bridge_methods[] = {
+    {"add3", "(III)I", 1, 0, j_add3, NULL, NULL},
+    {"mix", "(IJFDLjava/lang/String;)D", 1, 0, j_mix, NULL, NULL},
+    {"callBack", "(I)I", 1, 0, j_callback, NULL, NULL},
+    {"<init>", "(I)V", 0, 0, j_ctor, NULL, NULL},
+    {"greet", "(Ljava/lang/String;)Ljava/lang/String;", 0, 0, j_greet, NULL, NULL},
+    NATIVE("nativeAdd", "(II)I"),
+    NATIVE("nativeMany", "(JDFZBCSIJDFI)J"),
+    NATIVE("nativeFloat", "(FF)F"),
+    NATIVE("nativeDouble", "(DD)D"),
+    NATIVE("nativeByte", "(B)B"),
+    NATIVE("nativeConcat", "(Ljava/lang/String;)Ljava/lang/String;"),
+    NATIVE("nativeSum", "([I)I"),
+    NATIVE("nativeCallJava", "()I"),
+    NATIVE("nativeNested", "(I)I"),
+    NATIVE("nativeTwice", "(I)I"),
+    NATIVE("nativeThread", "()I"),
+    NATIVE("nativeThrow", "()I"),
+    NATIVE("exported", "(I)I"),
+    NATIVE("over", "(I)J"),
+    NATIVE("over", "(J)J"),
+    NATIVE("under_score", "()I"),
+    NATIVE("unregistered", "()V"),
+    {NULL, NULL, 0, 0, NULL, NULL, NULL},
+};
+
+jvalue fake_invoke(JNIEnv *env, fmethod *m, jobject self, const jvalue *a)
+{
+    if (m->impl) return m->impl(env, self, a);
+    fprintf(stderr, "harness: Java calls native %s%s, not supported by the fake\n", m->name, m->sig);
+    abort();
+}
+
+static void *nat(const char *name, const char *sig)
+{
+    fmethod *m = fake_method(bridge_cls, name, sig);
+    return m ? m->native_fn : NULL;
+}
+
+/* ---------------------------------------------------------------- tests */
+
+static void *other_thread(void *arg)
+{
+    fake_attach(); /* an ART thread */
+    JNIEnv *env = fake_env();
+    jint (*add)(JNIEnv *, jclass, jint, jint) = nat("nativeAdd", "(II)I");
+    intptr_t r = 0;
+    for (int k = 0; k < 100; k++) r += add(env, bridge_jcls, k, 1);
+    jint (*nested)(JNIEnv *, jclass, jint) = nat("nativeNested", "(I)I");
+    r += nested(env, bridge_jcls, 1000); /* 2001 */
+    return (void *)r;
+}
+
+static void test_jni(const char *dir)
+{
+    JavaVM *vm = fake_vm();
+    fake_attach();
+    JNIEnv *env = fake_env();
+    bridge_cls = fake_class("com/example/Bridge", bridge_methods);
+    bridge_jcls = (*env)->FindClass(env, "com/example/Bridge");
+    char stub[512];
+    snprintf(stub, sizeof stub, "%s/libbtest.so", dir);
+    jint ver = a32b_jni_onload(vm, stub);
+    CHECK(ver == JNI_VERSION_1_6, "JNI_OnLoad -> 0x%x", ver);
+
+    jint (*add)(JNIEnv *, jclass, jint, jint) = nat("nativeAdd", "(II)I");
+    CHECK(add && add(env, bridge_jcls, 40, 2) == 42, "RegisterNatives: nativeAdd(40, 2)");
+    CHECK(add && add(env, bridge_jcls, -5, 3) == -2, "nativeAdd(-5, 3)");
+
+    jlong (*many)(JNIEnv *, jclass, jlong, jdouble, jfloat, jboolean, jbyte, jchar, jshort, jint, jlong, jdouble,
+                  jfloat, jint) = nat("nativeMany", "(JDFZBCSIJDFI)J");
+    jlong exp = 10000000000LL + 1500 + 25 + 1 + (-3) + 60000 + (-7) + 123456 + (-9000000000LL) + 75 + 25 + 77;
+    jlong got = many ? many(env, bridge_jcls, 10000000000LL, 1.5, 0.25f, 1, -3, 60000, -7, 123456, -9000000000LL, 7.5, 2.5f, 77)
+                     : 0;
+    CHECK(got == exp, "12 mixed arguments (stack on both sides): %lld, expected %lld", (long long)got,
+          (long long)exp);
+
+    jfloat (*mulf)(JNIEnv *, jclass, jfloat, jfloat) = nat("nativeFloat", "(FF)F");
+    CHECK(mulf && mulf(env, bridge_jcls, 1.5f, -4.0f) == -6.0f, "float arguments and result");
+    jdouble (*divd)(JNIEnv *, jclass, jdouble, jdouble) = nat("nativeDouble", "(DD)D");
+    CHECK(divd && divd(env, bridge_jcls, 1.0, 8.0) == 0.125, "double arguments and result");
+    jbyte (*byte1)(JNIEnv *, jclass, jbyte) = nat("nativeByte", "(B)B");
+    CHECK(byte1 && byte1(env, bridge_jcls, -128) == 127 && byte1(env, bridge_jcls, 5) == 4, "byte argument and result");
+
+    jstring (*concat)(JNIEnv *, jclass, jstring) = nat("nativeConcat", "(Ljava/lang/String;)Ljava/lang/String;");
+    jstring s = concat ? concat(env, bridge_jcls, fake_string("frame")) : NULL;
+    CHECK(s && !strcmp(fake_utf(s), "frame-5"), "strings both ways: %s", s ? fake_utf(s) : "(null)");
+
+    jint (*sum)(JNIEnv *, jclass, jintArray) = nat("nativeSum", "([I)I");
+    for (int low = 1; low >= 0; low--) {
+        jintArray arr = fake_array('I', 5, low);
+        jint *d = fake_array_data(arr);
+        for (int k = 0; k < 5; k++) d[k] = k + 1;
+        jint r = sum ? sum(env, bridge_jcls, arr) : -1;
+        CHECK(r == 15 && d[0] == 99, "int[] elements %s 4 GiB (sum %d, written back %d)", low ? "below" : "above",
+              r, d[0]);
+    }
+
+    jint (*calljava)(JNIEnv *, jclass) = nat("nativeCallJava", "()I");
+    jint bits = calljava ? calljava(env, bridge_jcls) : 0;
+    CHECK(bits == 127, "Call*Method: ... / va_list / jvalue[], NewObject, fields, arrays (0x%x of 0x7f)", bits);
+
+    jint (*nested)(JNIEnv *, jclass, jint) = nat("nativeNested", "(I)I");
+    CHECK(nested && nested(env, bridge_jcls, 21) == 43, "nested calls: native -> Java -> native");
+
+    jint (*thr)(JNIEnv *, jclass) = nat("nativeThread", "()I");
+    CHECK(thr && thr(env, bridge_jcls) == 123, "guest thread: AttachCurrentThread + call Java");
+
+    pthread_t t[3];
+    for (int k = 0; k < 3; k++) pthread_create(&t[k], NULL, other_thread, NULL);
+    for (int k = 0; k < 3; k++) {
+        void *r = NULL;
+        pthread_join(t[k], &r);
+        CHECK((intptr_t)r == 4950 + 100 + 2001, "host thread %d gets a guest thread (%ld)", k, (long)(intptr_t)r);
+    }
+
+    jint (*throw_)(JNIEnv *, jclass) = nat("nativeThrow", "()I");
+    jint tr = throw_ ? throw_(env, bridge_jcls) : 0;
+    const char *e = fake_take_exception();
+    CHECK(tr == 7 && e && strstr(e, "boom"), "ThrowNew: %s", e ? e : "(no exception)");
+
+    jint (*exported)(JNIEnv *, jclass, jint) = nat("exported", "(I)I");
+    CHECK(exported && exported(env, bridge_jcls, 14) == 42, "Java_ export, short name");
+    jlong (*over_i)(JNIEnv *, jclass, jint) = nat("over", "(I)J");
+    jlong (*over_j)(JNIEnv *, jclass, jlong) = nat("over", "(J)J");
+    CHECK(over_i && over_j && over_i(env, bridge_jcls, 1) == 2 && over_j(env, bridge_jcls, 1LL << 40) == (1LL << 40) + 2,
+          "Java_ exports, long names (overloads)");
+    jint (*under)(JNIEnv *, jclass) = nat("under_score", "()I");
+    CHECK(under && under(env, bridge_jcls) == 5, "Java_ export with an escaped underscore");
+}
+
+/* ---------------------------------------------------------------- NativeActivity */
+
+static int fake_window_marker;
+#define FAKE_WINDOW ((ANativeWindow *)&fake_window_marker)
+
+/* libandroid, as far as the imports need it */
+void ANativeActivity_finish(ANativeActivity *a) {}
+void ANativeActivity_setWindowFormat(ANativeActivity *a, int32_t f) {}
+void ANativeActivity_setWindowFlags(ANativeActivity *a, uint32_t add, uint32_t rm) {}
+void ANativeActivity_showSoftInput(ANativeActivity *a, uint32_t f) {}
+void ANativeActivity_hideSoftInput(ANativeActivity *a, uint32_t f) {}
+void ANativeWindow_acquire(ANativeWindow *w) {}
+void ANativeWindow_release(ANativeWindow *w) {}
+int32_t ANativeWindow_getWidth(ANativeWindow *w) { return w == FAKE_WINDOW ? 1234 : -1; }
+int32_t ANativeWindow_getHeight(ANativeWindow *w) { return w == FAKE_WINDOW ? 567 : -1; }
+int32_t ANativeWindow_getFormat(ANativeWindow *w) { return 1; }
+int32_t ANativeWindow_setBuffersGeometry(ANativeWindow *w, int32_t x, int32_t y, int32_t f) { return 0; }
+
+static int result2(uint32_t h, int which)
+{
+    uint32_t fn = a32b_sym(h, "btest2_result");
+    uint32_t w = (uint32_t)which;
+    return fn ? (int)a32b_call(fn, &w, 1) : -999;
+}
+
+static void test_native_activity(const char *dir)
+{
+    char stub[512];
+    snprintf(stub, sizeof stub, "%s/libbtest2.so", dir);
+    static ANativeActivityCallbacks cb;
+    static ANativeActivity act;
+    act.callbacks = &cb;
+    act.vm = fake_vm();
+    act.env = fake_env();
+    act.clazz = fake_string("activity");
+    act.internalDataPath = "/data/test/files";
+    act.externalDataPath = "/sdcard/test";
+    act.sdkVersion = 30;
+    a32b_native_activity_oncreate(&act, "abc", 3, stub);
+    uint32_t h = a32b_load(stub);
+    CHECK(h != 0, "NativeActivity library loaded (with its DT_NEEDED libbtest.so)");
+    cb.onStart(&act);
+    cb.onResume(&act);
+    cb.onWindowFocusChanged(&act, 1);
+    cb.onNativeWindowCreated(&act, FAKE_WINDOW);
+    size_t n = 0;
+    char *state = cb.onSaveInstanceState(&act, &n);
+    CHECK(result2(h, 0) == 1 && result2(h, 1) == 1, "onStart, onResume forwarded");
+    CHECK(result2(h, 3) == 1, "onWindowFocusChanged(1)");
+    CHECK(result2(h, 2) == 1234, "onNativeWindowCreated -> ANativeWindow_getWidth import (%d)", result2(h, 2));
+    CHECK(n == 6 && state && !strcmp(state, "state"), "onSaveInstanceState result copied out");
+    CHECK(result2(h, 4) == 1, "saved state passed in");
+    CHECK(result2(h, 5) == 30, "sdkVersion");
+    CHECK(result2(h, 6) == 1, "activity vm/env/paths");
+    CHECK(result2(h, 7) == (1 ^ 0x55), "symbol from the DT_NEEDED library");
+    cb.onDestroy(&act);
+    CHECK(result2(h, 8) == 1, "onDestroy forwarded");
+    free(state);
+}
+
+static void test_cxx(const char *dir, const char *name)
+{
+    char stub[512];
+    snprintf(stub, sizeof stub, "%s/%s.so", dir, name);
+    uint32_t h = a32b_load(stub);
+    uint32_t fn = h ? a32b_sym(h, "cxx_test") : 0;
+    uint32_t w = 6;
+    int r = fn ? (int)a32b_call(fn, &w, 1) : -1;
+    CHECK(r == 303, "%s: C++ exceptions and static constructors in a guest library (%d)", name, r);
+}
+
+int main(int argc, char **argv)
+{
+    if (argc < 2) {
+        fprintf(stderr, "usage: harness <dir>\n");
+        return 2;
+    }
+    /* the host process owns memory in the low 4 GiB, as ART's heap and boot image do: the guest must avoid it */
+    void *taken = mmap((void *)0x400000, 4 << 20, PROT_NONE, MAP_PRIVATE | MAP_ANONYMOUS | MAP_FIXED_NOREPLACE, -1, 0);
+    if (taken == MAP_FAILED) perror("mmap 0x400000");
+    extern int a32_vrapi_selftest(void);
+    CHECK(a32_vrapi_selftest() == 0, "VrApi ABI, render poses, tracking consistency and floor transforms");
+    test_jni(argv[1]);
+    test_native_activity(argv[1]);
+    test_cxx(argv[1], "libbtest3");
+    test_cxx(argv[1], "libbtest3_android");
+    test_cxx(argv[1], "libbtest3_standard");
+    CHECK(mprotect(taken, 4 << 20, PROT_NONE) == 0, "the host's low mapping is still there");
+    if (failures) {
+        printf("%d FAILED\n", failures);
+        return 1;
+    }
+    printf("ALL OK\n");
+    return 0;
+}
@@ -0,0 +1,132 @@
+/* Guest NativeActivity for the on-device test APK (make_apk.py): checks the bridge against the real ART in a
+ * Lepton container and logs "A32TEST ok|FAIL <check>" lines (logcat tag a32test), then "A32TEST done N failed". */
+#include <android/log.h>
+#include <android/native_activity.h>
+#include <android/native_window.h>
+#include <dlfcn.h>
+#include <jni.h>
+#include <pthread.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+#define LOG(...) __android_log_print(ANDROID_LOG_INFO, "a32test", __VA_ARGS__)
+
+static int failed;
+static JavaVM *g_vm;
+
+static void check(int ok, const char *what, const char *detail)
+{
+    if (!ok) failed++;
+    LOG("A32TEST %s %s%s%s", ok ? "ok" : "FAIL", what, detail ? ": " : "", detail ? detail : "");
+}
+
+static jstring static_string(JNIEnv *env, const char *cls, const char *field)
+{
+    jclass c = (*env)->FindClass(env, cls);
+    if (!c) return NULL;
+    jfieldID f = (*env)->GetStaticFieldID(env, c, field, "Ljava/lang/String;");
+    return f ? (jstring)(*env)->GetStaticObjectField(env, c, f) : NULL;
+}
+
+static void *thread_fn(void *arg)
+{
+    JNIEnv *env = NULL;
+    if ((*g_vm)->AttachCurrentThread(g_vm, &env, NULL) != JNI_OK) return (void *)0;
+    jclass c = (*env)->FindClass(env, "android/os/SystemClock");
+    jmethodID m = c ? (*env)->GetStaticMethodID(env, c, "uptimeMillis", "()J") : NULL;
+    jlong t = m ? (*env)->CallStaticLongMethod(env, c, m) : 0;
+    (*g_vm)->DetachCurrentThread(g_vm);
+    return (void *)(intptr_t)(t > 0);
+}
+
+static void run_checks(ANativeActivity *a)
+{
+    JNIEnv *env = NULL;
+    g_vm = a->vm;
+    check((*a->vm)->GetEnv(a->vm, (void **)&env, JNI_VERSION_1_6) == JNI_OK && env == a->env, "GetEnv", NULL);
+
+    jstring model = static_string(env, "android/os/Build", "MODEL");
+    const char *u = model ? (*env)->GetStringUTFChars(env, model, NULL) : NULL;
+    check(u && *u, "Build.MODEL", u);
+    if (u) (*env)->ReleaseStringUTFChars(env, model, u);
+
+    /* String.format("%d-%s", 42, "x") through a varargs Call with an Object[] built in JNI */
+    jclass sc = (*env)->FindClass(env, "java/lang/String");
+    jclass ic = (*env)->FindClass(env, "java/lang/Integer");
+    jmethodID valueof = (*env)->GetStaticMethodID(env, ic, "valueOf", "(I)Ljava/lang/Integer;");
+    jmethodID format = (*env)->GetStaticMethodID(env, sc, "format", "(Ljava/lang/String;[Ljava/lang/Object;)Ljava/lang/String;");
+    jobjectArray args = (*env)->NewObjectArray(env, 2, (*env)->FindClass(env, "java/lang/Object"), NULL);
+    (*env)->SetObjectArrayElement(env, args, 0, (*env)->CallStaticObjectMethod(env, ic, valueof, 42));
+    (*env)->SetObjectArrayElement(env, args, 1, (*env)->NewStringUTF(env, "x"));
+    jstring s = (*env)->CallStaticObjectMethod(env, sc, format, (*env)->NewStringUTF(env, "%d-%s"), args);
+    u = s ? (*env)->GetStringUTFChars(env, s, NULL) : NULL;
+    check(u && !strcmp(u, "42-x"), "String.format via JNI", u);
+    if (u) (*env)->ReleaseStringUTFChars(env, s, u);
+
+    /* Math.hypot(3, 4): double arguments and result */
+    jclass mc = (*env)->FindClass(env, "java/lang/Math");
+    jmethodID hypot = (*env)->GetStaticMethodID(env, mc, "hypot", "(DD)D");
+    check((*env)->CallStaticDoubleMethod(env, mc, hypot, 3.0, 4.0) == 5.0, "Math.hypot", NULL);
+
+    /* int[] through Get/ReleaseIntArrayElements (ART's heap is below 4 GiB: shared, not copied) */
+    jintArray arr = (*env)->NewIntArray(env, 1000);
+    jboolean copy = 2;
+    jint *p = (*env)->GetIntArrayElements(env, arr, &copy);
+    for (int k = 0; k < 1000; k++) p[k] = k;
+    (*env)->ReleaseIntArrayElements(env, arr, p, 0);
+    jint back[2];
+    (*env)->GetIntArrayRegion(env, arr, 998, 2, back);
+    char d[64];
+    snprintf(d, sizeof d, "isCopy %d, at %p", copy, (void *)p);
+    check(back[0] == 998 && back[1] == 999, "int[] elements", d);
+
+    /* an exception thrown in Java, seen and cleared by guest code */
+    jclass ic2 = (*env)->FindClass(env, "java/lang/Integer");
+    jmethodID parse = (*env)->GetStaticMethodID(env, ic2, "parseInt", "(Ljava/lang/String;)I");
+    (*env)->CallStaticIntMethod(env, ic2, parse, (*env)->NewStringUTF(env, "not a number"));
+    int had = (*env)->ExceptionCheck(env);
+    (*env)->ExceptionClear(env);
+    check(had, "Java exception visible to guest code", NULL);
+
+    pthread_t t;
+    void *r = NULL;
+    pthread_create(&t, NULL, thread_fn, NULL);
+    pthread_join(t, &r);
+    check(r != NULL, "guest thread attaches and calls Java", NULL);
+
+    /* the C++ test library: dlopen from guest code, exceptions inside it */
+    void *h = dlopen("libbtest3.so", RTLD_NOW);
+    int (*cxx)(int) = h ? (int (*)(int))dlsym(h, "cxx_test") : NULL;
+    int cr = cxx ? cxx(6) : -1;
+    snprintf(d, sizeof d, "%d", cr);
+    check(cr == 303, "C++ library via dlopen", d);
+
+    check(a->internalDataPath && access(a->internalDataPath, F_OK) == 0, "internalDataPath exists",
+          a->internalDataPath);
+    LOG("A32TEST done %d failed", failed);
+}
+
+static void on_start(ANativeActivity *a) { LOG("onStart"); }
+static void on_resume(ANativeActivity *a) { LOG("onResume"); }
+static void on_pause(ANativeActivity *a) { LOG("onPause"); }
+static void on_focus(ANativeActivity *a, int f) { LOG("onWindowFocusChanged %d", f); }
+static void on_window(ANativeActivity *a, ANativeWindow *w)
+{
+    LOG("onNativeWindowCreated %dx%d format %d", ANativeWindow_getWidth(w), ANativeWindow_getHeight(w),
+        ANativeWindow_getFormat(w));
+}
+static void on_window_destroyed(ANativeActivity *a, ANativeWindow *w) { LOG("onNativeWindowDestroyed"); }
+
+void ANativeActivity_onCreate(ANativeActivity *a, void *saved, size_t n)
+{
+    LOG("onCreate (32-bit guest code, sdk %d)", a->sdkVersion);
+    a->callbacks->onStart = on_start;
+    a->callbacks->onResume = on_resume;
+    a->callbacks->onPause = on_pause;
+    a->callbacks->onWindowFocusChanged = on_focus;
+    a->callbacks->onNativeWindowCreated = on_window;
+    a->callbacks->onNativeWindowDestroyed = on_window_destroyed;
+    run_checks(a);
+}
@@ -0,0 +1,153 @@
+/* Guest test library (armv7, Thumb): what a game's JNI library does. JNI_OnLoad registers natives with
+ * RegisterNatives; Java_* exports are found by name. The natives call back into "Java" with every argument style. */
+#include <android/log.h>
+#include <jni.h>
+#include <pthread.h>
+#include <stdarg.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+#define TAG "btest"
+
+static JavaVM *g_vm;
+static jclass g_cls;
+static jmethodID m_add3, m_mix, m_callback, m_ctor, m_greet;
+
+static jint nativeAdd(JNIEnv *env, jclass c, jint a, jint b) { return a + b; }
+
+/* 12 arguments: host-side some go on the stack (gpr and fpr overflow differ from ARM's) */
+static jlong nativeMany(JNIEnv *env, jclass c, jlong a, jdouble b, jfloat f, jboolean z, jbyte by, jchar ch,
+                        jshort s, jint i, jlong l2, jdouble d2, jfloat f2, jint i2)
+{
+    return a + (jlong)(b * 1000) + (jlong)(f * 100) + z + by + ch + s + i + l2 + (jlong)(d2 * 10) + (jlong)(f2 * 10) +
+           i2;
+}
+
+static jfloat nativeFloat(JNIEnv *env, jclass c, jfloat a, jfloat b) { return a * b; }
+static jdouble nativeDouble(JNIEnv *env, jclass c, jdouble a, jdouble b) { return a / b; }
+static jbyte nativeByte(JNIEnv *env, jclass c, jbyte a) { return (jbyte)(a - 1); }
+
+static jstring nativeConcat(JNIEnv *env, jclass c, jstring s)
+{
+    const char *u = (*env)->GetStringUTFChars(env, s, NULL);
+    char buf[128];
+    snprintf(buf, sizeof buf, "%s-%d", u, (int)(*env)->GetStringUTFLength(env, s));
+    (*env)->ReleaseStringUTFChars(env, s, u);
+    return (*env)->NewStringUTF(env, buf);
+}
+
+/* sums the array and writes element 0 back (shared or copied, both must work) */
+static jint nativeSum(JNIEnv *env, jclass c, jintArray a)
+{
+    jint n = (*env)->GetArrayLength(env, a), sum = 0;
+    jint *p = (*env)->GetIntArrayElements(env, a, NULL);
+    for (jint k = 0; k < n; k++) sum += p[k];
+    p[0] = 99;
+    (*env)->ReleaseIntArrayElements(env, a, p, 0);
+    return sum;
+}
+
+static jint call_v(JNIEnv *env, jclass c, jmethodID m, ...)
+{
+    va_list ap;
+    va_start(ap, m);
+    jint r = (*env)->CallStaticIntMethodV(env, c, m, ap);
+    va_end(ap);
+    return r;
+}
+
+/* calls Java in every style; returns a bit per passed check */
+static jint nativeCallJava(JNIEnv *env, jclass c)
+{
+    jint ok = 0;
+    if ((*env)->CallStaticIntMethod(env, c, m_add3, 1, 2, 3) == 6) ok |= 1;
+    jdouble d = (*env)->CallStaticDoubleMethod(env, c, m_mix, 4, (jlong)5000000000LL, (jfloat)1.5f, 2.25,
+                                               (*env)->NewStringUTF(env, "abc"));
+    if (d == 4 + 5000000000.0 + 1.5 + 2.25 + 3) ok |= 2;
+    jvalue v[3];
+    v[0].i = 10, v[1].i = 20, v[2].i = 30;
+    if ((*env)->CallStaticIntMethodA(env, c, m_add3, v) == 60) ok |= 4;
+    if (call_v(env, c, m_add3, 7, 8, 9) == 24) ok |= 8;
+    jobject o = (*env)->NewObject(env, c, m_ctor, 41);
+    jfieldID f = (*env)->GetFieldID(env, c, "value", "I");
+    if (o && (*env)->GetIntField(env, o, f) == 41) ok |= 16;
+    jstring g = (*env)->CallObjectMethod(env, o, m_greet, (*env)->NewStringUTF(env, "abc"));
+    const char *u = g ? (*env)->GetStringUTFChars(env, g, NULL) : NULL;
+    if (u && !strcmp(u, "hello abc/41")) ok |= 32;
+    if (u) (*env)->ReleaseStringUTFChars(env, g, u);
+    jintArray arr = (*env)->NewIntArray(env, 4);
+    jint in[4] = {1, 2, 3, 4}, out[4];
+    (*env)->SetIntArrayRegion(env, arr, 0, 4, in);
+    (*env)->GetIntArrayRegion(env, arr, 1, 3, out);
+    if (out[0] == 2 && out[2] == 4) ok |= 64;
+    return ok;
+}
+
+/* Java -> native -> Java -> native: nested calls on one thread */
+static jint nativeNested(JNIEnv *env, jclass c, jint n) { return (*env)->CallStaticIntMethod(env, c, m_callback, n) + 1; }
+static jint nativeTwice(JNIEnv *env, jclass c, jint n) { return 2 * n; }
+
+static void *thread_fn(void *arg)
+{
+    JNIEnv *env = NULL;
+    if ((*g_vm)->AttachCurrentThread(g_vm, &env, NULL) != JNI_OK) return (void *)(intptr_t)-1;
+    jint r = (*env)->CallStaticIntMethod(env, g_cls, m_add3, 100, 20, 3);
+    (*g_vm)->DetachCurrentThread(g_vm);
+    return (void *)(intptr_t)r;
+}
+
+/* a guest thread attaches itself and calls Java */
+static jint nativeThread(JNIEnv *env, jclass c)
+{
+    pthread_t t;
+    void *r = NULL;
+    if (pthread_create(&t, NULL, thread_fn, NULL)) return -1;
+    pthread_join(t, &r);
+    return (jint)(intptr_t)r;
+}
+
+static jint nativeThrow(JNIEnv *env, jclass c)
+{
+    (*env)->ThrowNew(env, (*env)->FindClass(env, "java/lang/IllegalStateException"), "boom");
+    return 7;
+}
+
+JNIEXPORT jint JNICALL Java_com_example_Bridge_exported(JNIEnv *env, jclass c, jint x) { return x * 3; }
+JNIEXPORT jlong JNICALL Java_com_example_Bridge_over__I(JNIEnv *env, jclass c, jint x) { return x + 1; }
+JNIEXPORT jlong JNICALL Java_com_example_Bridge_over__J(JNIEnv *env, jclass c, jlong x) { return x + 2; }
+JNIEXPORT jint JNICALL Java_com_example_Bridge_under_1score(JNIEnv *env, jclass c) { return 5; }
+
+int btest_helper(int x) { return x ^ 0x55; }
+
+JNIEXPORT jint JNI_OnLoad(JavaVM *vm, void *reserved)
+{
+    g_vm = vm;
+    JNIEnv *env;
+    if ((*vm)->GetEnv(vm, (void **)&env, JNI_VERSION_1_6) != JNI_OK) return JNI_ERR;
+    jclass c = (*env)->FindClass(env, "com/example/Bridge");
+    if (!c) return JNI_ERR;
+    g_cls = (*env)->NewGlobalRef(env, c);
+    m_add3 = (*env)->GetStaticMethodID(env, c, "add3", "(III)I");
+    m_mix = (*env)->GetStaticMethodID(env, c, "mix", "(IJFDLjava/lang/String;)D");
+    m_callback = (*env)->GetStaticMethodID(env, c, "callBack", "(I)I");
+    m_ctor = (*env)->GetMethodID(env, c, "<init>", "(I)V");
+    m_greet = (*env)->GetMethodID(env, c, "greet", "(Ljava/lang/String;)Ljava/lang/String;");
+    static const JNINativeMethod natives[] = {
+        {"nativeAdd", "(II)I", (void *)nativeAdd},
+        {"nativeMany", "(JDFZBCSIJDFI)J", (void *)nativeMany},
+        {"nativeFloat", "(FF)F", (void *)nativeFloat},
+        {"nativeDouble", "(DD)D", (void *)nativeDouble},
+        {"nativeByte", "(B)B", (void *)nativeByte},
+        {"nativeConcat", "(Ljava/lang/String;)Ljava/lang/String;", (void *)nativeConcat},
+        {"nativeSum", "([I)I", (void *)nativeSum},
+        {"nativeCallJava", "()I", (void *)nativeCallJava},
+        {"nativeNested", "(I)I", (void *)nativeNested},
+        {"nativeTwice", "(I)I", (void *)nativeTwice},
+        {"nativeThread", "()I", (void *)nativeThread},
+        {"nativeThrow", "()I", (void *)nativeThrow},
+    };
+    if ((*env)->RegisterNatives(env, c, natives, sizeof natives / sizeof *natives)) return JNI_ERR;
+    __android_log_print(ANDROID_LOG_INFO, TAG, "JNI_OnLoad done (%s)", m_add3 && m_mix ? "methods found" : "?");
+    return JNI_VERSION_1_6;
+}
@@ -0,0 +1,57 @@
+/* Guest test library (armv7, ARM): a NativeActivity. Needs libbtest.so (DT_NEEDED) and libandroid. */
+#include <android/log.h>
+#include <android/native_activity.h>
+#include <android/native_window.h>
+#include <jni.h>
+#include <stdlib.h>
+#include <string.h>
+
+int btest_helper(int x); /* libbtest.so */
+
+static int started, resumed, width, focus, saved_ok, sdk, env_ok, destroyed;
+
+static void on_start(ANativeActivity *a) { started++; }
+static void on_resume(ANativeActivity *a) { resumed++; }
+static void on_focus(ANativeActivity *a, int f) { focus = f; }
+static void on_window(ANativeActivity *a, ANativeWindow *w) { width = ANativeWindow_getWidth(w); }
+static void on_destroy(ANativeActivity *a) { destroyed++; }
+
+static void *on_save(ANativeActivity *a, size_t *len)
+{
+    char *p = malloc(6);
+    memcpy(p, "state", 6);
+    *len = 6;
+    return p;
+}
+
+void ANativeActivity_onCreate(ANativeActivity *a, void *saved, size_t n)
+{
+    a->callbacks->onStart = on_start;
+    a->callbacks->onResume = on_resume;
+    a->callbacks->onWindowFocusChanged = on_focus;
+    a->callbacks->onNativeWindowCreated = on_window;
+    a->callbacks->onSaveInstanceState = on_save;
+    a->callbacks->onDestroy = on_destroy;
+    saved_ok = n == 3 && !memcmp(saved, "abc", 3);
+    sdk = a->sdkVersion;
+    JNIEnv *env = NULL;
+    env_ok = (*a->vm)->GetEnv(a->vm, (void **)&env, JNI_VERSION_1_6) == JNI_OK && env == a->env &&
+             a->internalDataPath && !strcmp(a->internalDataPath, "/data/test/files");
+    __android_log_print(ANDROID_LOG_INFO, "btest2", "onCreate: sdk %d, saved %d", sdk, saved_ok);
+}
+
+int btest2_result(int which)
+{
+    switch (which) {
+    case 0: return started;
+    case 1: return resumed;
+    case 2: return width;
+    case 3: return focus;
+    case 4: return saved_ok;
+    case 5: return sdk;
+    case 6: return env_ok;
+    case 7: return btest_helper(1);
+    case 8: return destroyed;
+    }
+    return -1;
+}
@@ -0,0 +1,26 @@
+// Guest test library (armv7, C++, static libc++): exceptions thrown and caught inside a guest library unwind
+// through the runtime's dl_unwind_find_exidx; static constructors run at load.
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+static std::vector<int> g_init{1, 2, 3}; // a static constructor
+
+static int thrower(int x)
+{
+    if (x > 2) throw std::runtime_error("too big: " + std::to_string(x));
+    return x;
+}
+
+extern "C" int cxx_test(int n)
+{
+    int caught = 0;
+    for (int k = 0; k < n; k++) {
+        try {
+            thrower(k);
+        } catch (const std::runtime_error &e) {
+            if (std::string(e.what()).find("too big") == 0) caught++;
+        }
+    }
+    return caught * 100 + (int)g_init.size();
+}
@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Builds the on-device test APK org.frameport.a32test: a NativeActivity without Java code whose library is 32-bit
+ARM code (libapktest.a32.so) run by the bridge. Build the bridge first (python bridge/build.py --test).
+
+    uv run python native/a32translator/bridge/test/make_apk.py [--out FILE]
+
+The APK is signed with FramePort's key for the package (created on first use). Install it with
+`frameport install org.frameport.a32test --apk FILE` after `frameport scan` of its folder, or by hand.
+"""
+import argparse
+import struct
+import subprocess
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parents[1]
+OUT = ROOT / "out" / "bridge"
+NDK_BIN = ROOT.parent / ".cache/ndk-27.2.12479018/toolchains/llvm/prebuilt/linux-x86_64/bin"
+PACKAGE = "org.frameport.a32test"
+ANDROID_NS = "http://schemas.android.com/apk/res/android"
+ATTR_IDS = {  # android: attributes used here (framework resource IDs)
+    "label": 0x01010001, "name": 0x01010003, "hasCode": 0x0101000C, "debuggable": 0x0101000F,
+    "exported": 0x01010010, "value": 0x01010024, "minSdkVersion": 0x0101020C, "versionCode": 0x0101021B,
+    "versionName": 0x0101021C, "targetSdkVersion": 0x01010270, "extractNativeLibs": 0x010104EA,
+}
+T_STRING, T_INT, T_BOOL = 0x03, 0x10, 0x12
+
+# (element, [(attribute, value)], children); android attributes are the ATTR_IDS keys, others have no namespace
+MANIFEST = ("manifest", [("package", PACKAGE), ("versionCode", 1), ("versionName", "1.0")], [
+    ("uses-sdk", [("minSdkVersion", 24), ("targetSdkVersion", 30)], []),
+    ("application", [("label", "A32 bridge test"), ("hasCode", False), ("debuggable", True),
+                     ("extractNativeLibs", True)], [
+        ("activity", [("name", "android.app.NativeActivity"), ("label", "A32 bridge test"), ("exported", True)], [
+            ("meta-data", [("name", "android.app.lib_name"), ("value", "apktest")], []),
+            ("intent-filter", [], [
+                ("action", [("name", "android.intent.action.MAIN")], []),
+                ("category", [("name", "android.intent.category.LAUNCHER")], []),
+            ]),
+        ]),
+    ]),
+])
+
+
+def axml(root) -> bytes:
+    """Android binary XML for the tree above (UTF-8 string pool; attribute names with IDs first, as aapt does)."""
+    attr_names = sorted({a for _, attrs, _ in walk(root) for a, _ in attrs if a in ATTR_IDS}, key=ATTR_IDS.get)
+    strings = list(attr_names)
+
+    def idx(s):
+        if s not in strings:
+            strings.append(s)
+        return strings.index(s)
+
+    for s in ("android", ANDROID_NS):
+        idx(s)
+    body = bytearray()
+    ns_chunk = struct.pack("<IIII", 1, 0xFFFFFFFF, idx("android"), idx(ANDROID_NS))
+    body += struct.pack("<HHI", 0x0100, 16, 24) + ns_chunk
+
+    def emit(node):
+        name, attrs, children = node
+        recs = []
+        for a, v in sorted(attrs, key=lambda av: ATTR_IDS.get(av[0], 0)):
+            ns = idx(ANDROID_NS) if a in ATTR_IDS else 0xFFFFFFFF
+            if isinstance(v, bool):
+                raw, typ, data = 0xFFFFFFFF, T_BOOL, 0xFFFFFFFF if v else 0
+            elif isinstance(v, int):
+                raw, typ, data = 0xFFFFFFFF, T_INT, v
+            else:
+                raw, typ, data = idx(v), T_STRING, idx(v)
+            recs.append(struct.pack("<IIIHBBI", ns, idx(a), raw, 8, 0, typ, data))
+        n = idx(name)
+        start = struct.pack("<IIIIHHHHHH", 1, 0xFFFFFFFF, 0xFFFFFFFF, n, 20, 20, len(recs), 0, 0, 0)
+        body.extend(struct.pack("<HHI", 0x0102, 16, 8 + len(start) + 20 * len(recs)) + start + b"".join(recs))
+        for c in children:
+            emit(c)
+        body.extend(struct.pack("<HHI", 0x0103, 16, 24) + struct.pack("<IIII", 1, 0xFFFFFFFF, 0xFFFFFFFF, n))
+
+    emit(root)
+    body += struct.pack("<HHI", 0x0101, 16, 24) + ns_chunk
+
+    data = bytearray()
+    offsets = []
+    for s in strings:
+        offsets.append(len(data))
+        b = s.encode()
+        assert len(s) < 0x80 and len(b) < 0x80
+        data += bytes([len(s), len(b)]) + b + b"\0"
+    while len(data) % 4:
+        data += b"\0"
+    hdr = 28
+    pool = struct.pack("<HHIIIIII", 0x0001, hdr, hdr + 4 * len(strings) + len(data), len(strings), 0, 0x100,
+                       hdr + 4 * len(strings), 0)
+    pool += struct.pack(f"<{len(offsets)}I", *offsets) + data
+    resmap = struct.pack("<HHI", 0x0180, 8, 8 + 4 * len(attr_names)) + b"".join(
+        struct.pack("<I", ATTR_IDS[a]) for a in attr_names)
+    total = 8 + len(pool) + len(resmap) + len(body)
+    return struct.pack("<HHI", 0x0003, 8, total) + pool + resmap + bytes(body)
+
+
+def walk(node):
+    yield node
+    for c in node[2]:
+        yield from walk(c)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out", default=str(OUT / "a32test.apk"))
+    a = ap.parse_args()
+    test = OUT / "test"
+    cc = NDK_BIN / "armv7a-linux-androideabi30-clang"
+    subprocess.run([str(cc), "-O2", "-g", "-mthumb", "-shared", "-fPIC", str(HERE / "libapktest.c"), "-landroid",
+                    "-llog", "-ldl", "-o", str(test / "libapktest.a32.so")], check=True)
+    libs = {
+        "libapktest.so": OUT / "liba32stub.so",  # the stub, under the 32-bit library's name
+        "liba32bridge.so": OUT / "liba32bridge.so",
+        "liba32rt.so": OUT / "liba32rt.so",
+        "libapktest.a32.so": test / "libapktest.a32.so",
+        "libbtest3.a32.so": test / "libbtest3.a32.so",
+    }
+    manifest = axml(MANIFEST)
+    sys.path.insert(0, str(ROOT.parents[1] / "src"))
+    from frameport.apk import axml as fp_axml
+    from frameport.apk import sign
+
+    x = fp_axml.Axml(manifest)  # FramePort's own parser must read it
+    assert fp_axml.MAIN in x.strings() and fp_axml.LAUNCHER in x.strings()
+    assert fp_axml.categories(manifest) == {fp_axml.LAUNCHER}
+    with tempfile.TemporaryDirectory() as td:
+        unsigned = Path(td) / "unsigned.apk"
+        with zipfile.ZipFile(unsigned, "w") as z:
+            z.writestr(zipfile.ZipInfo("AndroidManifest.xml", (2026, 1, 1, 0, 0, 0)), manifest, zipfile.ZIP_DEFLATED)
+            for name, src in libs.items():
+                z.write(src, f"lib/arm64-v8a/{name}", zipfile.ZIP_STORED)
+        sign.sign(unsigned, Path(a.out), PACKAGE)
+    print(a.out)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Runs the bridge test harness (build it first: python bridge/build.py --test).
+
+    python bridge/test/run.py [--runner "qemu-aarch64"] [--interp] [--strace] [--timeout 300]
+
+On x86_64 the harness runs under qemu-aarch64; on an AArch64 Linux machine pass --runner "". Like the program tests,
+it runs in a fresh user+pid namespace (32-bit bionic refuses pids above 65535). Exit code 0 = every check passed.
+"""
+import argparse
+import os
+import resource
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+DIR = Path(__file__).resolve().parents[2] / "out" / "bridge" / "test"
+
+
+def no_core():
+    resource.setrlimit(resource.RLIMIT_CORE, (0, 0))  # qemu-user hangs writing a multi-threaded core
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--runner", default="qemu-aarch64")
+    ap.add_argument("--interp", action="store_true", help="interpreter only (A32_INTERP=1)")
+    ap.add_argument("--strace", action="store_true", help="log guest syscalls (A32_STRACE=1)")
+    ap.add_argument("--timeout", type=int, default=300)
+    a = ap.parse_args()
+    if not (DIR / "harness").exists():
+        sys.exit(f"{DIR / 'harness'} missing: run python bridge/build.py --test")
+    env = dict(os.environ)
+    if a.interp:
+        env["A32_INTERP"] = "1"
+    if a.strace:
+        env["A32_STRACE"] = "1"
+    cmd = ["timeout", "-s", "KILL", str(a.timeout), "unshare", "-Urpf", "--kill-child", *shlex.split(a.runner),
+           "./harness", "."]
+    p = subprocess.run(cmd, cwd=DIR, env=env, preexec_fn=no_core)
+    sys.exit(p.returncode)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,171 @@
+/* Linked only into the qemu host harness. Exercise the real AAPCS readers and thunks with a fake 64-bit API. */
+#include <sys/mman.h>
+static int test_tracking_calls, test_submit_calls;
+static int test_tracked = 1, test_identity, test_current_only;
+static posef64 test_set_pose;
+static tracking2 test_tracking(void *m, double t)
+{
+    tracking2 tr = {0};
+    tr.Status = test_tracked && (!test_current_only || t == 0) ? 143 : 0;
+    tr.HeadPose.Orientation[3] = 1;
+    ++test_tracking_calls;
+    tr.HeadPose.Position[1] = (!tr.Status || test_identity) ? 1.6f : (float)test_tracking_calls;
+    tr.HeadPose.TimeInSeconds = t == 0 ? 42.75 : t;
+    return tr;
+}
+static posef64 test_transform(void *m, int which)
+{
+    posef64 pose = {{0,0,0,1}, {0, which == 3 ? -1.6f : 0, 0}};
+    return pose;
+}
+static void test_set_transform(void *m, posef64 pose) { test_set_pose = pose; }
+static double test_display(void *m, int64_t index) { return 42.25; }
+static pose64 test_submit_pose;
+static uint64_t test_submit_index;
+static unsigned test_submit_layers;
+static double test_submit_time;
+static int test_submit(void *m, const submit2 *d)
+{
+    ++test_submit_calls;
+    test_submit_layers = d->LayerCount;
+    test_submit_index = d->FrameIndex;
+    test_submit_time = d->DisplayTime;
+    if (d->LayerCount == 1) test_submit_pose = ((const projection2 *)d->Layers[0])->HeadPose;
+    return 0;
+}
+int a32_vrapi_selftest(void)
+{
+    int failed = 0;
+#define VT(x) do { if (!(x)) { fprintf(stderr, "FAIL vrapi: %s\n", #x); ++failed; } } while (0)
+    uint8_t *buf = mmap((void *)0x30000000, 8192, PROT_READ|PROT_WRITE,
+                        MAP_PRIVATE|MAP_ANONYMOUS|MAP_FIXED_NOREPLACE, -1, 0);
+    if (buf == MAP_FAILED) return 1;
+    uint32_t g = p2g(buf);
+    a32_cpu cpu = {0};
+    argreader r;
+    cpu.r[0] = 123; cpu.r[1] = 0xdeadbeef; cpu.r[2] = 0x89abcdef; cpu.r[3] = 0x01234567;
+    ar_init(&r, &cpu, 0, g);
+    VT(rd32(&r) == 123); VT(rd64(&r) == UINT64_C(0x0123456789abcdef));
+    bridge(); /* finish pthread_once (the static harness has no real bridge DSO) */
+    __typeof__(B) saved = B;
+    int saved_ok = bridge_ok;
+    B.GetPredictedTracking2 = test_tracking;
+    B.GetTrackingTransform = test_transform; B.SetTrackingTransform = test_set_transform;
+    B.GetPredictedDisplayTime = test_display; B.SubmitFrame2 = test_submit;
+    bridge_ok = 1;
+    void *m = &test_set_pose;
+    uint32_t mh = ptr2h(m);
+    tracking_reset();
+    tracking2 a = tracking_of(m, 42.25), b = tracking_of(m, 42.25);
+    VT(!memcmp(&a, &b, sizeof a)); VT(test_tracking_calls == 1);
+    tracking_of(m, 42.5); VT(test_tracking_calls == 2);
+    cpu.r[0]=g; cpu.r[1]=mh; double requested=42.25; memcpy(&cpu.r[2],&requested,8);
+    ar_init(&r,&cpu,0,g+4096); imp_vrapi_GetPredictedTracking(&cpu,&r);
+    VT(!memcmp(buf,&a,104)); VT(cpu.r[0] == g);
+    cpu.r[0]=g; cpu.r[1]=mh;
+    ar_init(&r,&cpu,0,g+4096); imp_vrapi_GetPredictedTracking2(&cpu,&r);
+    VT(!memcmp(buf,&a,sizeof a)); VT(test_tracking_calls == 2);
+    tracking_reset(); test_tracked = 0;
+    tracking_of(m, 42.25); tracking_of(m, 42.25); VT(test_tracking_calls == 4);
+    test_tracked = 1;
+    cpu.r[0] = g; cpu.r[1] = mh; cpu.r[2] = 3;
+    ar_init(&r, &cpu, 0, g+4096); imp_vrapi_GetTrackingTransform(&cpu, &r);
+    posef64 floor; memcpy(&floor, buf, sizeof floor);
+    VT(floor.Orientation[3] == 1 && floor.Position[1] == -1.6f); VT(cpu.r[0] == g);
+    posef64 wanted = {{0.1f,0.2f,0.3f,0.9f}, {2,-1.6f,4}};
+    cpu.r[0] = mh;
+    memcpy(&cpu.r[1], &wanted, 12); memcpy(buf+4096, (uint8_t *)&wanted+12, 16);
+    ar_init(&r, &cpu, 0, g+4096); imp_vrapi_SetTrackingTransform(&cpu, &r);
+    VT(!memcmp(&wanted, &test_set_pose, sizeof wanted));
+    tracking_of(m, 42.25); VT(test_tracking_calls == 5); /* transform invalidated the cache */
+    /* Projection2: pointer widening and 88 -> 96 byte texture stride; HeadPose is ABI-identical. */
+    memset(buf, 0, 4096);
+    uint32_t layer = g+128, array = g+1024;
+    uint32_t chain_object = 0; uint32_t ch = ptr2h(&chain_object);
+    pose64 render = {0}; render.Orientation[3] = 1; render.Position[1] = 1.75f;
+    render.AngularVelocity[1] = 0.25f; render.LinearAcceleration[2] = 0.75f;
+    render.TimeInSeconds = 42.25; render.PredictionInSeconds = 0.0125;
+    st32(g+32,1); st32(g+36,array); st32(array,layer);
+    st32(layer,1); memcpy(g2p(layer+40), &render, sizeof render);
+    st32(layer+136,ch); st32(layer+224,ch);
+    uint64_t index = UINT64_C(0x123456789);
+    memcpy(buf+8,&index,8); double time=42.25; memcpy(buf+16,&time,8);
+    cpu.r[0] = mh; cpu.r[1] = g;
+    ar_init(&r,&cpu,0,g+4096); imp_vrapi_SubmitFrame2(&cpu,&r);
+    VT(test_submit_calls == 1); VT(test_submit_index == index && test_submit_time == time);
+    VT(!memcmp(&render,&test_submit_pose,sizeof render));
+    /* Legacy VrApi 1.5: 200-byte eye textures and 432-byte layers. */
+    memset(buf,0,4096); st32(g,3); st32(g+1736,1);
+    st32(g+8,ch); st32(g+208,ch); memcpy(buf+8+96,&render,sizeof render);
+    memcpy(buf+1744,&index,8);
+    cpu.r[0]=mh; cpu.r[1]=g;
+    ar_init(&r,&cpu,0,g+4096); imp_vrapi_SubmitFrame(&cpu,&r);
+    VT(test_submit_calls == 2); VT(test_submit_index == index && test_submit_time == time);
+    VT(!memcmp(&render,&test_submit_pose,sizeof render));
+    /* The early loader's 140-byte prefix shifts the otherwise identical legacy layout. */
+    memset(buf,0,4096); st32(g,0x10000001); st32(g+1876,1);
+    st32(g+148,ch); st32(g+348,ch); memcpy(buf+148+96,&render,sizeof render);
+    memcpy(buf+1884,&index,8);
+    cpu.r[0]=mh; cpu.r[1]=g;
+    ar_init(&r,&cpu,0,g+4096); imp_vrapi_SubmitFrame(&cpu,&r);
+    VT(test_submit_calls == 3); VT(test_submit_index == index && test_submit_time == time);
+    VT(!memcmp(&render,&test_submit_pose,sizeof render));
+    /* Runtime tracking loss: hold head and eyes together for <=100 ms, while
+     * keeping repeated answers consistent without renewing the original sample age. */
+    tracking2 good = tracking_of(m, 42.25);
+    test_tracked = 0;
+    int calls = test_tracking_calls;
+    tracking2 held = tracking_of(m, 42.26);
+    VT(held.Status == good.Status && held.HeadPose.Position[1] == good.HeadPose.Position[1]);
+    VT(held.HeadPose.TimeInSeconds == 42.26);
+    VT(!memcmp(held.Eye, good.Eye, sizeof held.Eye));
+    tracking_of(m, 42.26); VT(test_tracking_calls == calls+1);
+    VT(tracking_of(m, 42.36).Status == 0); /* held .26 did not renew .25 */
+    VT(tracking_of(m, 42.5).Status == 0);
+    test_tracked = 1;
+    /* Default submitted without a matching tracking request: repair at display time.
+     * Both conversion paths use this gate; preserve valid arbitrary render poses. */
+    projection2 projection = {0}; projection.Header.Type = 1;
+    projection.HeadPose.Orientation[3] = 1; projection.HeadPose.Position[1] = 1.6f;
+    projection.HeadPose.TimeInSeconds = 42.26;
+    const header2 *headers[] = {&projection.Header};
+    submit2 desc = {0}; desc.DisplayTime = 42.25; desc.LayerCount = 1; desc.Layers = headers;
+    submit_prepare(m, &desc);
+    VT(desc.LayerCount == 1 && projection.HeadPose.Position[1] == good.HeadPose.Position[1]);
+    VT(projection.HeadPose.TimeInSeconds == 42.26); /* exact render-time held answer */
+    /* Genuine tracked identity and head-locked identity must remain unchanged. */
+    tracking_reset(); test_identity = 1;
+    tracking2 identity = tracking_of(m, 42.25);
+    projection.HeadPose = identity.HeadPose; submit_prepare(m, &desc);
+    VT(!memcmp(&projection.HeadPose, &identity.HeadPose, sizeof(pose64)));
+    tracking_reset(); test_tracked = 0;
+    projection.Header.Flags = 4; submit_prepare(m, &desc); VT(desc.LayerCount == 1);
+    projection.Header.Flags = 0; submit_prepare(m, &desc); VT(desc.LayerCount == 0);
+    /* Check the real SubmitFrame2 thunk ends an empty frame with no tracked fallback. */
+    memset(buf, 0, 4096);
+    st32(g+32,1); st32(g+36,array); st32(array,layer); st32(layer,1);
+    st32(layer+136,ch); st32(layer+224,ch);
+    memcpy(g2p(layer+40), &identity.HeadPose, sizeof(pose64)); memcpy(buf+16,&time,8);
+    cpu.r[0]=mh; cpu.r[1]=g;
+    ar_init(&r,&cpu,0,g+4096); imp_vrapi_SubmitFrame2(&cpu,&r);
+    VT(test_submit_calls == 4 && test_submit_layers == 0);
+    test_tracked = 1; test_identity = 0; test_current_only = 1;
+    desc.LayerCount = 1; projection.HeadPose = identity.HeadPose;
+    submit_prepare(m, &desc);
+    VT(desc.LayerCount == 1 && projection.HeadPose.TimeInSeconds == 42.75);
+    VT(desc.DisplayTime == 42.25); /* no extra WaitFrame or display-time advance */
+    test_current_only = 0;
+    /* Keep an update/render pair across more than the old 16 cache entries. */
+    tracking_reset();
+    good = tracking_of(m, 42.25);
+    for (int j = 1; j <= 40; ++j) tracking_of(m, 42.25+j*0.001);
+    calls = test_tracking_calls;
+    held = tracking_of(m, 42.25);
+    VT(test_tracking_calls == calls && !memcmp(&held, &good, sizeof held));
+    test_tracked = 1; test_identity = 0;
+    tracking_reset(); B = saved; bridge_ok = saved_ok;
+    munmap(buf,8192);
+    fprintf(stderr, "vrapi ABI/cache/transform tests: %s\n", failed ? "FAILED" : "OK");
+#undef VT
+    return failed;
+}