FramePort 0.7.1

Some Quest games ship voice-over languages as <tag>.lang files and ask the Meta Platform SDK for them; overport's
platform loader answers with nothing, so every language but the built-in one stays greyed out. libfp_langpack.so
answers the language-pack and asset-file calls from the packs already on the device (Metadata = the game's
versionName, the /storage/emulated/0 path spelling Unreal uses). Tested in the headset with Deadpool VR (German
dialogue), AC Nexus and Asgard's Wrath 2.

.github/workflows/build.yml

@@ -1,6 +1,7 @@
 name: build
 on:
   push:
+    branches: [main]
     tags: ["v*"]
   pull_request:
   workflow_dispatch:
@@ -12,10 +13,13 @@ jobs:
       - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v10.2.0
       - run: uv sync --extra dev
+      - name: Lint
+        run: uv run ruff check .
       - run: uv run pytest -m "not games and not device"
 
   bundle:
     needs: test
+    if: github.event_name != 'push' || startsWith(github.ref, 'refs/tags/v')  # pushes to main: tests only
     permissions:
       contents: read
       id-token: write      # build provenance attestations (Sigstore)
@@ -31,10 +35,13 @@ jobs:
         include:
           - os: windows-latest
             archive: FramePort-windows-x64.zip
-          - os: macos-latest
+          - os: macos-26  # Apple Silicon + Xcode 26 (macos-15's Xcode 16.4 fails a Flutter plugin; macos-latest
+            # went unassigned on 2026-10-02)
             archive: FramePort-macos-arm64.zip
           - os: ubuntu-22.04  # oldest supported: the bundle needs the build host's GLib/glibc or newer
             archive: FramePort-linux-x64.tar.gz
+          - os: ubuntu-22.04-arm  # Linux ARM64 (same base as x64)
+            archive: FramePort-linux-arm64.tar.gz
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v7
@@ -45,9 +52,9 @@ jobs:
       - run: uv sync --extra dev
       - id: flet
         run: uv run python scripts/package.py
-        continue-on-error: ${{ runner.os == 'macOS' }}
-      - name: macOS fallback (PyInstaller bundle)
-        if: runner.os == 'macOS' && steps.flet.outcome == 'failure'
+        continue-on-error: ${{ runner.os == 'macOS' || runner.arch == 'ARM64' }}
+      - name: macOS / Linux ARM64 fallback (PyInstaller bundle)
+        if: (runner.os == 'macOS' || runner.arch == 'ARM64') && steps.flet.outcome == 'failure'
         run: uv run --with pyinstaller python scripts/package.py --pyinstaller
 
       # ---- signing: self-signed certificate on Windows, ad-hoc on macOS ----
@@ -90,7 +97,9 @@ jobs:
         run: ditto -c -k --keepParent "$(find dist -maxdepth 3 -name '*.app' -type d | head -1)" ${{ matrix.archive }}
       - name: Package (Linux)
         if: runner.os == 'Linux'
-        run: tar czf ${{ matrix.archive }} -C dist --transform 's,^linux,FramePort,' linux
+        run: |  # flet build -> dist/linux; the PyInstaller fallback -> dist/FramePort (one folder)
+          if [ -d dist/linux ]; then tar czf ${{ matrix.archive }} -C dist --transform 's,^linux,FramePort,' linux
+          else tar czf ${{ matrix.archive }} -C dist FramePort; fi
       # self-update with this archive: unpack, verify the layout (+ the signer on Windows), run the real swap script
       - name: Update smoke test
         run: uv run python scripts/update_smoke.py ${{ matrix.archive }}
@@ -132,10 +141,10 @@ jobs:
           git fetch --force origin "refs/tags/${tag}:refs/tags/${tag}"
           whatsnew=$(git tag -l --format='%(contents:body)' "$tag")
           [ -n "$whatsnew" ] || whatsnew=$(git tag -l --format='%(contents:subject)' "$tag")
-          { echo "FramePort ${tag}: Windows (x64), macOS (Apple Silicon) and Linux (x64)."; echo;
+          { echo "FramePort ${tag}: Windows (x64), macOS (Apple Silicon) and Linux (x64, ARM64)."; echo;
             if [ -n "$whatsnew" ] && [ "$(git cat-file -t "$tag")" = tag ]; then
               echo "## What's new"; echo; echo "$whatsnew"; echo; fi
-            echo "Already have FramePort? It offers this update itself (Library → **Update now**, or \`frameport update\`)."
-            echo; sed -n '/^## First launch/,$p' docs/INSTALL.md; } > "$notes"
+            echo "Already have FramePort? It offers this update itself (Library → **Update now**)."
+            echo; cat packaging/release-footer.md; } > "$notes"  # short: the update dialog shows these notes
           gh release delete "$tag" --yes 2>/dev/null || true
           gh release create "$tag" out/* packaging/FramePort-selfsigned.cer --title "FramePort ${tag}" --notes-file "$notes"

.gitignore

@@ -13,3 +13,9 @@ native/.cache/
 native/**/build/
 # per-machine Claude Code settings (contain home paths)
 .claude/settings.local.json
+
+# maintainer-local notes for Claude Code (accounts, credentials)
+CLAUDE.local.md
+# outputs of `frameport report` / `parity` / ruff
+REPORT.md
+.ruff_cache/

CLAUDE.md

@@ -14,7 +14,14 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
     status_row, art_fill, confirm, `update()` = safe update: in Flet 1.0 reading `.page` of an unmounted control
     raises), `jobs.py` (background FIFO job queue, one at a time, cancel via Reporter; no Flet), `views/`
     (library: search/filters/tags/sort as pure tested helpers; game: hero + one-click install, patches under
-    "Customize"; frame: device + readiness + installed, or connect wizard; settings; welcome; activity panel).
+    "Customize"; frame: device + readiness + installed, or connect wizard; files: the Frame's file manager (persistent
+    like the library; locations = Videos/Downloads/Documents from agent `storage_targets`, each installed Quest game's
+    storage, the home folder; SFTP via `install/files.py` list_dir/upload/download/make_dir/rename/delete, all
+    confined to the location by `files.inside`; Lepton's links in a game's storage can't be renamed/deleted; replaced
+    the "Send files" dialog, game menu → "Add videos & files…" = `go("files", pkg)`; multi-select bar (download/
+    delete); drag-and-drop from the OS via the `flet-dropzone` extension (Apache-2.0, Flutter `desktop_drop`), which
+    only a `flet build` bundle contains: `files.dropzone_available()` keeps it out of source runs and the PyInstaller
+    fallback, which would show an unknown control); settings; welcome; activity panel).
     User tags live in library entries (`tags`), filters in library setting `ui.library`.
     **Performance rules** (the app froze before): never put image bytes in controls — artwork is served by URL from the
     GUI assets dir (= user data dir; `ft.run(assets_dir=…)`), as thumbnails (`artwork/thumbs.py`, Pillow); the
@@ -36,8 +43,9 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
   - **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).
-    **Revive is off by default, opt-in** (`pcvr.revive`, and `pcvr.oculus_unreal`): only for an un-cracked Oculus game
-    that fails at "Initializing OVR session". Those (Lone Echo, Robo Recall, Lies Beneath: crack .7z not extracted /
+    **Revive is only suggested for games with Oculus (LibOVR) code** (`pcvr.revive`, and `pcvr.oculus_unreal`; repacks
+    with a bundled Revive and SteamVR/OpenXR games run directly): needed by an un-cracked Oculus game that fails at
+    "Initializing OVR session". Those (Lone Echo, Robo Recall, Lies Beneath: crack .7z not extracted /
     Platform SDK) hit Revive's Oculus-runtime **signature check** under Proton-arm64 — Revive's LoadLibrary/WinVerifyTrust
     hooks don't install (ARM64EC), and the game's Oculus SDK shim rejects the unsigned Revive runtime (wintrust +
     crypt32 signer "Oculus VR") — so they don't run on the Frame without extracting the repack's crack (which FramePort
@@ -74,7 +82,8 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
     package or Rift match) + Steam appdetails (exact title: developer, release date, up to 6 screenshots → artwork
     `shot_N.jpg`). Meta store pages reject scraping, so Oculus exclusives have no screenshots. Genres become automatic
     tags. Steam shortcuts get a complete composed art set (`artwork/steam.py`: 600×900 / 920×430 / 1920×620 / logo /
-    256 icon, blurred-backdrop compositing for square-only covers) and tags: how it runs, the original platform
+    256 icon, blurred-backdrop compositing for square-only covers; no store art (at most the APK icon) → a placeholder
+    set: the name on a colour from the title hash + the APK icon, `steam_set_for`; 2D Android apps get no store lookups) and tags: how it runs, the original platform
     (Meta Quest / Oculus Rift), genres, user tags — merged with tags set in Steam (non-Steam shortcuts can't hold a
     description).
   - Quest/Rift twins stay separate entries, shown and named in Steam "Title (Quest)"/"(Rift)" (`core/titles.py`).
@@ -132,11 +141,14 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
     [--yes]`, once-a-day stderr hint read from the cache only (`refresh_cache()` in a daemon thread writes no
     settings, to avoid read-modify-write races). `scripts/update_smoke.py <archive>` runs the real extract + swap script
     (no relaunch) — CI runs it on all three OS with the archive it just built.
-    Verified: Linux + Windows (native, signer check) smoke with the v0.2.0 bundles; macOS only via the CI smoke.
+    Verified end to end (2026-10-02): real 0.3.3 bundles on Windows and Linux (Ubuntu 22.04/WSLg) found, staged and
+    installed 0.3.4 ("Install updates automatically" path) and relaunched as 0.3.4 with settings kept. Not yet clicked
+    by hand: the "Update now" button path (same apply(), called from the running app). macOS: CI smoke only.
 - `agent/frameport_agent.py` — runs **on the Frame** (python3 stdlib only), JSON over SSH. Owns the install layout,
   launch.sh template, Steam shortcuts (binary VDF), launch tests. Bump `AGENT_VERSION` when changing it.
 - `bootstrap/bootstrap.sh` — one-time Frame setup served by the pairing server (sshd, app key, avahi service, Lepton).
-- `catalog/games/<package>.yaml` — 34 recipes verified 2026-09-28 + Deadpool VR (2026-10-01, owner-confirmed); `catalog/triage.yaml` — log signatures → fixes.
+- `catalog/games/<package>.yaml` — 38 recipes (34 verified 2026-09-28; Deadpool VR, 4XVR, NEX Player and AC Nexus's
+  90 Hz default confirmed later by the owner); `catalog/triage.yaml` — log signatures → fixes.
 - `native/` — sources of the prebuilt binaries in `artifacts/` (adapter, VrApi bridge patches, GL shim, stubs).
   `native/build.py` rebuilds them with NDK r27c (downloaded on demand into `native/.cache`, git-ignored; uses
   `-ffile-prefix-map` so no local paths get embedded; zip symlinks are restored as copies). Users never need the NDK.
@@ -149,9 +161,9 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
 UV_LINK_MODE=copy uv sync --extra dev   # creates/updates ./.venv
 uv run pytest                # unit tests (no device, no game files)
 uv run frameport --help      # CLI;  uv run frameport-gui  for the GUI
-uv run frameport parity --known-good <PATCHED/_known-good-*> --sources "<VR CyberDeck downloads>"
+uv run frameport parity --known-good <PATCHED/_known-good-*> --sources "<folder with the game dumps>"
 ```
-Games/device tests: `pytest -m games` (FRAMEPORT_GAMES=<downloads dir>), `pytest -m device` (FRAMEPORT_FRAME=steamos@host);
+Games tests: `pytest -m games` (FRAMEPORT_GAMES=<downloads dir>); on-device checks are CLI commands (below);
 native layer test: `FRAMEPORT_NATIVE_TESTS=1 pytest -m native` (compiles with the NDK, ~2 min on NTFS).
 Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattributes`).
 - `FRAMEPORT_HOME=<dir>` isolates all app data (tests use it); `FRAMEPORT_JAVA/_OVERPORT_JAR/_APKSIGNER_JAR` override
@@ -159,7 +171,7 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
   artwork, frames.json, the app's SSH key which the dev Frame authorizes).
 - Device checks: `frameport test <pkg>` / `frameport parity-device --results <parity.json> --baseline <launch.txt>
   [--test-only]`; the pre-FramePort baseline is `PATCHED/_known-good-2026-09-28/_frame-state/baseline-launch.txt`.
-- Docs screenshots (`docs/images/`): `python scripts/scrub_library.py ~/.local/share/frameport <dir>` (copies
+- Docs screenshots (`docs/images/`): `python scripts/scrub_library.py ~/.local/share/frameport <dir> --status works,issues` (copies
   library + artwork only; titles replace folder names, local paths → `D:/Games/...`, sort by size) then
   `FRAMEPORT_HOME=<dir> python scripts/ui_smoke.py --out <shots> --docs --fake-frame --game <pkg>` (set
   FRAMEPORT_JAVA/_OVERPORT_JAR/_APKSIGNER_JAR so no tool download toast appears; `--viewport 1280x2600` + crop for the
@@ -178,6 +190,25 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
   an `expand` child in a `wrap=True` Row).
 - Stopping the GUI: `pkill -f` patterns match your own shell — use `pgrep -f "[b]in/frameport-gui|[f]let-desktop-light"`.
 
+## Round-2 polish (2026-10-02)
+- `errors.py`: `explain(exc)` (plain sentence for GUI + CLI), `is_connection_error`. Install/test jobs for the Frame
+  (`Job.needs_frame`) that lose the connection go back to the queue front and the queue pauses (`jobs.paused`);
+  `app._poll` retries every 10 s and resumes (owner-verified on the device 2026-10-02: the queue resumed after the
+  connection was lost). Wake lock: agent v30 `keep_awake` (systemd-inhibit idle:sleep, idle-only
+  fallback because polkit `inhibit-block-sleep` is auth_admin for non-local sessions), held while Frame jobs exist.
+- **Already converted inputs** (`analysis.is_overport_output`, e.g. the owner's library points at `PATCHED/` copies)
+  are not converted again: a second OVRPort run replaced libovrplatformloader.so and dropped its DT_NEEDED on
+  libovrstubs.so (Wallace & Gromit / Espire 2 crashed: cannot locate symbol ovr_…). Alt builds come from the saved
+  `<pkg>.alt-noforcequit.apk`, else one OVRPort run (frame.ovrstubs relinks). `missing_ovr_symbols` only counts
+  linked stub/compat libs. Converted copies in `output/` are removed after a Frame install (`build.keep_copies`).
+- Art: `.picked` marker = user's pick, automatic fetches never overwrite it and only fill missing kinds; a Meta
+  result's picture is the OculusDB image shown in the picker (the ovrp image service served "dogfooding" placeholder
+  covers for some packages, e.g. Asgard's Wrath 2). `steam_art_stale` → game page reminder. No store art → generated
+  `cover.jpg`/`banner.jpg` (APK icon via `fetch.apk_icon`).
+- Game settings dialog (`ui/views/adapter_dialog.py`, metadata `patches/settings.UI`); plain patch summaries
+  (`patches/summaries.py`, `Patch.summary`, "Show technical details" = setting `ui.patch_details`); share nudge
+  (`views/game.should_ask_to_share`); saving a recipe keeps its status (was always "works").
+
 ## 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.
@@ -194,7 +225,28 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
 - **Tracking only works with the headset worn.** SSH/headless launches never reach VISIBLE/FOCUSED and poses have
   flags 0x3. So automated tests prove startup (process alive, instance/session created, frames paced), never visuals.
 
+**Setup / pairing (2026-10-02, verified on the device):** Developer Mode = `"DevModeEnabled"` in
+`~/.local/share/Steam/config/config.vdf` (InstallConfigStore/developer), applied by Valve's
+`/usr/bin/steamos-polkit-helpers/steamos-devkit-mode --enable|--disable` (polkit allow_any: no password; enables/
+disables sshd, xrdp, steamos-devkit-service, debug port forwards; sentinel `/etc/steamos-devkit-enabled`). Steam
+re-asserts the config value at every start and rewrites config.vdf on exit → stop Steam, edit, helper, start.
+**Desktop Mode is a nested Plasma inside steam.service** (own XDG_RUNTIME_DIR `/run/user/1000/nested_plasma` + private
+D-Bus): `systemd-run --user` from Konsole fails ("Failed to connect to user scope bus") unless XDG_RUNTIME_DIR/
+DBUS_SESSION_BUS_ADDRESS point at `/run/user/$UID`, and stopping Steam ends the desktop and everything started in
+it → bootstrap.sh runs the Dev Mode job + Lepton request + `/paired` as a user unit (log `~/.cache/frameport-setup.log`);
+no sudo/password anywhere (verified: naive Frame → connected, password never set). Valve's devkit pairing (fallback,
+PC → Frame only): `POST :32000/register` with an **ssh-rsa** key (`connection.devkit_key`, `frame/devkit.py`) works only
+while Steam is in pairing mode (Settings → Developer → Pair new host), else 403 at once; approve hook waits 30 s.
+The Frame runs firewalld (22 and 32000 open). PC side: the setup server needs inbound TCP 8765–8767 — WSL's Hyper-V
+firewall blocks it silently (`DefaultInboundAction Block`): `pairing.ensure_reachable` adds a temporary rule via one
+UAC prompt, removed when the server stops (flag file in %TEMP%, max 35 min); hints per OS after 45 s without a request
+(`pairing.firewall_hint`). Flet 1.0 patches aren't thread-safe → `app.serialize_flet_updates()` (a dialog shown while a
+scan redraw ran never closed: "dropped a patch for unknown control").
 **Lepton:** needs an activity with category **LAUNCHER** (Quest apps often only have INFO → "APP_ACTIVITY is empty").
+**2D apps:** Lepton runs every app headless (`lepton.headless=true`, only OpenXR output reaches the headset) unless the app folder (`<base>/lepton-app/`) has a `lepton-show-flatscreen` file (liblepton/app_metadata.sh) → Waydroid window on gamescope; agent v28 `set_flatscreen` at finalize for `vr_kind == "none"`. Android 11's navbar covered the
+app's controls → patch `device.hide_navbar` (default on for vr_kind none, migration `flat_hide_navbar`) exports
+`qemu.hw.mainkeys=1` as a second line of `LEPTON_GFXRECON_FP_PROPS` (runtime alternatives failed, see
+docs/FRAME_RUNTIME.md). Verified in the headset 2026-10-02 (2048).
 Lepton = Steam app 3029110 (+ "Lepton Development" 3056000, needs Developer Mode). Per-game env: STEAM_COMPAT_INSTALL_PATH
 /DATA_PATH/SHADER_PATH, SteamAppId. Logs: `<base>/launch.log` and `~/.local/share/Steam/logs/lepton-logcats/steamlaunch-<appid>`.
 Containers are podman `lepton-steamlaunch-<appid>`. Some Unreal games create save dirs without u+rwx → launcher repairs every 2 s.
@@ -276,6 +328,12 @@ the **unpatched** upstream of our `frame.vrapi_bridge` (`native/vrapi` unchanged
 experimental CLI built with `-PwithVrApi=true` (stable jars list it but fail). The owner prefers OVRPort's fixes over
 ours where they work as well (less to maintain): compare in the headset before switching a default.
 `frameport install <pkg> --apk <file>` installs a specific (test) build signed with the game's key.
+Headset results (2026-10-02, `PATCHED/_test-ovrport-1.2.5/TESTING.md`): OVRPort's own VrApi translator fails on the
+Frame (Climb 2: requests VkFormat 37 → crash; POTW: no GLES path, missing `vrapi_GetTextureSwapChainHandle`) → keep
+`frame.vrapi_bridge`; those two changes are upstream candidates. 1.2.5 builds (its platform compat, new permissions)
+work. AC Nexus: `patch_ac_nexus_no_appsw_90` is the catalog default (owner preferred 90 Hz); `STRICT` patches are only
+taken from a catalog recipe where `applies()` holds (the AC Nexus ones need build MAIN.450412.207706.final, else the
+whole overport run fails).
 
 **Patching gotchas:**
 - UnityPy re-serialization breaks scene loading → patch QualitySettings ints in place.
@@ -335,18 +393,121 @@ swapchain was halved (1536/eye) in case memory is the limit (unverified). Frame
 (SteamVR runtimes, Lepton scripts, logs; never commit Valve binaries): `~/frameport-research/frame-data-2026-09-30/`.
 Not yet verified in the headset.
 
-**Lepton storage (2026-09-30):** each app's /sdcard (= /storage/emulated/0 → `<base>/lepton-data/external`) has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (liblepton/mounting.sh, only if they exist at start); agent v24 `storage_targets` reads that mapping. Android's MediaProvider canonicalises paths to /home/steamos/... and rejects every file ("doesn't appear under [/system/media...]"), `sm list-volumes` is empty: the media index never works, apps must browse folders. Lepton installs with `adb install -g` (runtime permissions granted, MANAGE_EXTERNAL_STORAGE too). Send files: `install/files.py`, `frameport frame send|storage`, GUI Frame → Send files.
+**Companion apps / intents (2026-10-03, tested with Stremio + 4XVR):** a second APK can be installed into a running
+Lepton container (`podman exec -i lepton-steamlaunch-<appid> pm install -g -S <size> < apk`) and runs there, VR
+included (4XVR in Stremio's flatscreen container: FrameBridge 72 fps, settings via LEPTON_ENV_FRAMEBRIDGE_CONFIG). But
+Lepton's services.jar (`ActivityStarter.execute`) intercepts **every** `android.intent.action.VIEW` with data (any
+scheme, explicit component or not, no property to disable): it writes `steam://openurl/<uri>` to `/lepton/steam.pipe`
+(= the host Steam client's `~/.steam/steam.pipe`) and starts nothing. So "open in external player" hand-offs (Stremio
+→ 4XVR) can't work inside Lepton; don't retry without Valve changing it. Lepton installs exactly one `*.apk` per app
+folder (two break `get_apk_path`).
+**Text input (2026-10-03, verified in the headset with Stremio VR):** Lepton's Android has no IME (`ime list` empty)
+and runs VR apps headless (`lepton.headless=true`): no Android window has input focus (`dumpsys input` FocusedWindows
+empty), so neither `input text`, a USB keyboard nor Steam's keyboard reach the app. `lepton-show-flatscreen` on a VR
+app keeps VR working (FrameBridge 72 fps) and gives the window focus; Steam's on-screen keyboard then opens for text
+fields. Unity's TMP_InputField on non-Quest Android waits for the system keyboard (`TouchScreenKeyboardShouldBeUsed`)
+and deselects a frame later unless `isKeyboardUsingEvents` (Android: `InPlaceEditing() && m_HideSoftKeyboard`);
+uGUI InputField's LateUpdate keeps the field when `InPlaceEditing()`. Patch `frame.unity_text_input` rewrites them
+(`mov w0,#0|#1; ret`) at Cpp2IL's **Offset** (= file offset; RVA differs by 0x4000 in Stremio's lib), Cpp2IL
+2022.1 pre-release (Unity 6 / metadata v31; Il2CppDumper can't), cached per libil2cpp sha. `/dev/uinput` has an ACL
+for steamos (Steam Input) → agent v33 `_keyboard` uinput keyboard ("Type on Frame") reaches everything with focus.
+Installing a second APK into a container with `pm install` re-runs Lepton's post-install hook on the **main** app
+(`lepton.active_app_id`; moves its files to /data/steam_app) and corrupts it on the next start (fix: touch the APK →
+re-bake); `cmd_real package install` skips the hook.
+**User reports (2026-10-04, issues #4-#10):** Steam shortcuts go to the signed-in account (`loginusers.vdf`
+MostRecent) else every account (agent v35 `library_users`; it used to refuse with >1 account → Play gave Steam's "Game
+configuration unavailable"); `launch` uses the shortcut's own appid and errors `NOT_IN_LIBRARY`, the app then adds it
+and plays. Unity IL2CPP fixes share one Cpp2IL run (`unity_text_input.Il2cppReturnPatch`, `ALL_TARGETS`, cache keyed by
+global-metadata.dat): `frame.unity_runtime_msaa_off` (OVRManager raises MSAA to 4x at runtime: "Switching to the
+recommended level" → Lucky's Tale restarted the headset; `OVRDisplay.get_recommendedMSAALevel` → 0) and
+`frame.unity_multipass` (Oculus XR Plugin multiview → MultiPass via `OculusSettings.GetStereoRenderingMode`; I Am Cat's
+right eye grey). Both checked against Toy Master's Cpp2IL output, not yet in a headset. VR4 quits itself (System.exit
+after the intro movie) → catalog `use_alt`. **Catalog changes reach existing games** without hardcoded migrations:
+recipes store `catalog_rev` (= `CatalogEntry.rev()`), `library._follow_catalog` re-derives non-user recipes whose entry
+changed; a maintained entry beats the user's shared copy when its `updated`/verified date is later (`catalog._newer`).
+**Round 2 of reports (2026-10-04):** VR4's campaign hang = one fragment shader reading an uninitialized loop counter
+(reporter's capture): vkshim `vk_shader_fix` setting (`<size>:<sha256>:<offset>:<words>`, from the recipe's `adapter:`;
+matched by size + SHA-256, words inserted into a copy) — on the device the module is fixed at load ("fixed shader
+module (6488 -> 6512 bytes)"); campaign itself not yet seen in a headset by us. Text settings (kind "str") stay out of
+the Game settings dialog (saving it dropped them). I Am Cat: `GetStereoRenderingMode` is inlined (no call sites) →
+`Il2cppReturnPatch.field_loads` rewrites the field read in `OculusLoader.Initialize` (Cpp2IL gives the field offset,
+`field:<name>`); verified with Toy Master: eye swapchains array=1 ×2 instead of array=2. Builds record `recipe_fp`
+(`patches/base.recipe_fingerprint`, `Patch.revision`): a changed recipe or revised patch shows "Update on Frame".
+Remembered Frames are found again after an address change (`Frame.relocate`: scan, same SSH host key, before
+login). Packaged apps show artwork by file path (`thumbs.use_file_paths`, #16). Diagnostics: this boot's kernel log.
+Device tests of requested games (2026-10-04, headless): I Am Cat, Myst 3.3.0, BattleGlide, Blade & Sorcery: Nomad
+start (RUNNING, frames). Roblox: SIGSEGV in je_free from libroblox.so ~3 s in (likely its anti-tamper vs the re-signed
+APK). BONELAB (Unity 2021.3 Vulkan, OVRPlugin 1.94): SIGSEGV with pc == fault addr in vkCreateInstance, called from
+libSLZQuestNative.so's Vulkan hooks into an unmapped (unloaded) library right after OVRPlugin's pre-init
+xrDestroyInstance; pinning openxr/vrclient libraries (RTLD_NODELETE) did NOT help — find the unloaded library with the
+linker's dlopen/dlclose logging next. Accounting+ (Unity 2017.4 built-in Oculus, libOVRPlugin + libvrapi): Unity
+never starts VR on the Frame (no OVRPlugin/OpenXR lines; runs as a 2D app), which is why its "controller setup"
+screen can't be passed — Unity 2017's Oculus device check, not the controller profiles. Cpp2IL can't read Unity 2017.
+The Frame's Android runtime (vrclient.so) knows oculus/touch_controller but not Meta's Touch Plus/Pro profiles
+(OVRPlugin suggests those too, routinely) → adapter `profile_remap`.
+Headset round 2 (2026-10-04): the Frame drops focus often (ms to 7 s; only some are presence/standby) → games pause
+or recentre (B&S Player.OnVRPresence → Teleport, BattleGlide/Unreal pauses); focus_hold now 1 s focused / 1 s max dip
+(longer must still pause). Myst crash = vrclient xrSyncActions race after FOCUSED → `sync_guard` (confirmed); its
+object glitches: app space warp suspected (FB_space_warp is advertised and used) → recipe `patch_disable_space_warp`.
+I Am Cat multipass: poses/times consistent, but every frame is submitted after the next xrWaitFrame (one period late;
+Zink + doubled draws) and the game clamps its physics step to 10 ms → judder while still; testing scale 0.8. Roblox's
+newest crash is on Fossilize's recording thread → vk_sanitize extended to own-engine libs (engine "Other").
+Accounting+: unity_oculus_check + native/ovrpshim (libfp_ovrp.so waits via ovrp_WaitToBeginFrame before Unity
+2017's ovrp_Update2) → VR in the headset at ~72 fps (2026-10-04), but stuck at "press any button" although input
+reaches its OVRInput cleanly (probe: both Touch connected 0x63, individual buttons, input focus 1) → works with issues.
+"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
+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
+the header checksum/signature; verified with LÖVE for Android 11.5, GitHub #24 Dramatic Shape). 2D apps (vr_kind none)
+keep every suggested patch that isn't about VR (`needs_vr = False`), not a fixed list. FramePort on the Frame:
+`frame/local.py` (127.0.0.1, own key authorized; "This Frame (experimental)"; app data in
+~/.local/share/frameport-app because ~/.local/share/frameport is the agent's) and Steam library changes wait while
+Desktop Mode is open. Verified on the device 2026-10-04 (install + launch test from the Frame). Library updates on the
+Frame run one at a time (agent v40 flock): two quick uninstalls used to bring a removed shortcut back (Roblox).
+Headset round 3 (owner's verdicts, 2026-10-04): Blade & Sorcery works — its freezes were the headset's wear sensor
+flickering off while worn (vrserver.txt "HMD off/on" 0.5-2 s) → per-game `focus_hold_ms=2500` (only this game reacts;
+not a default). BattleGlide works (focus_hold). Myst works with issues (object glitches; space warp ruled out, its
+recipe keeps it on). I Am Cat works with issues (judder; scale 0.8 no help). Roblox unsupported (je_free in
+libroblox, also with the Vulkan shim). Installs skip the Steam restart when the shortcut is unchanged and wait while a
+game runs (agent v37). New default fixes in FramePort's code reach games already in a library: after every app update
+`library._follow_catalog` re-derives each non-user recipe once (setting `recipes.app_version`; tests switch it off via
+`library.REFRESH_ON_UPDATE`); analysis fields added later still need a re-analysis. Troubleshooting techniques: docs/PLAYBOOK.md "Debugging techniques". Unity `boot.config` "vulkan" substring mislabels GLES games as Vulkan
+(I Am Cat ran GLES); OVRPlugin's "Unavailable OpenXR extension: XR_FB_scene" is routine (no longer triaged).
+**Round 4 (2026-10-04):** XR_KHR_android_surface_swapchain is listed by the Frame's runtime but returns
+FUNCTION_UNSUPPORTED → adapter `surface_emul` (default on, `native/adapter/surface_swapchain.c`): an ordinary runtime
+swapchain is returned, the game gets a Surface from a SurfaceTexture on a worker thread (own EGL context, JavaVM from
+XrInstanceCreateInfoAndroidKHR), frames are read back (glReadPixels) and uploaded in xrEndFrame (Vulkan: own command
+buffer + fence per panel, never waits; GLES: glTexSubImage2D). I Am Monkey's intro works (owner-confirmed). SUPERHOT
+(Quest) quit at start: its cloud save folder was mode 1700 and Lepton's app writes through the folder's group →
+launch.sh `fix_perms` adds u+rwx,g+rwx (agent v41). Lucky's Tale: Unity's Loading.PreloadManager thread grows the
+native heap ~1 GB/s until the OOM killer (Frame freezes); no fix. `perf` works as steamos (paranoid 2; ptrace_scope 1
+blocks gdb/eu-stack/debuggerd) — see PLAYBOOK "Debugging techniques". QuestCraft downloads its JRE at first run into
+`files/runtimes/JRE` (Pojlib Installer); on the Frame it was missing (unpacked by hand, unverified). WiiCompiled: its launcher shows
+(lepton-show-flatscreen) but imports .wcgame files through Android's document picker (OPEN_DOCUMENT), which Lepton
+lacks (ActivityNotFoundException) → imported by hand: libmain.so + game.json → internal files/game/<profile>,
+DATA/ → external files/WiiCompiledOpenXRVR/DATA, MOD/ → .../RetroRewind6 (decompiled with jadx). Lepton has no
+picker at all: a FramePort fix would be an injected picker activity. Generated cover/banner art used to suppress the
+Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
+**Lepton storage (2026-09-30):** each app's /sdcard (= /storage/emulated/0 → `<base>/lepton-data/external`) has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (liblepton/mounting.sh, only if they exist at start); agent v24 `storage_targets` reads that mapping. Android's MediaProvider canonicalises paths to /home/steamos/... and rejects every file ("doesn't appear under [/system/media...]"), `sm list-volumes` is empty: the media index never works, apps must browse folders. Lepton installs with `adb install -g` (runtime permissions granted, MANAGE_EXTERNAL_STORAGE too). Files: `install/files.py`, `frameport frame send|storage`, GUI Files tab (formerly Frame → Send files).
 **SteamVR per-app settings (2026-09-30):** editing steamvr.vrsettings while SteamVR runs is lost; the web API (127.0.0.1:27062 /app/setsettings) needs `x-steamvr-secret`. `native/vrsettings` = `fp_vrsettings.exe` (freestanding, OpenVR `FnTable:IVRSettings_003` as a Utility app, loads SteamVR's bin/win64/openvr_api.dll) sets them live and SteamVR persists them: section `steam.app.<shortcut appid>`, keys `preferredRefreshRate` (float) and `motionSmoothingOverride` (0 global, 1 on, 2 off, 3 always). Steam Link (vrlink) lists the Frame's rates 72/80/90/96/108/120/144 in vrserver.txt and follows the per-app preference ("host preferred N Hz"; whether the key is honoured is unverified in-headset yet). Judder metric: vrcompositor.txt session summary dropped + "Timed out. N total" (Stormland: 0 dropped but 313 timeouts in 2 min); fpsVR (`%LOCALAPPDATA%\fpsVR\*.json`, 0.1 ms histograms) gives p99 CPU/GPU ms. `pcvr.steamvr_tuning` (default on, PC only) applies on Play: highest rate whose budget ≥ p99×1.05, at least one step down, smoothing on.
 
+**Language packs (merged from PR #20, 2026-10-04):** overport's `libovrplatformloader.so` is a dispatcher that `dlopen`s Meta's own loader (`libovrplatformloader_meta.so` / `_meta_q1.so`, also `libpxrplatformloader.so`) and keeps its own message queue; `ovr_LanguagePack_GetCurrent/SetCurrent` are 8-byte `return 0` stubs in it, `ovr_AssetFile_GetList` forwards to Meta's loader. `frame.langpacks` (opt-in, `native/langpack`) serves `<tag>.lang` files from the game's data; `elf.hide_exports` marks the loader's exports STB_LOCAL (bionic and glibc only match GLOBAL/WEAK; verified for glibc, bionic's `is_symbol_global_and_defined` is from memory). `libfp_langpack.so` is built here (`python native/build.py --only langpack`) and committed. Owner-verified 2026-10-04: Deadpool VR with only `en.lang` and the patch on plays English dialogue and runs normally (headless launch tests show 2-6 fps while it loads: not a regression sign). A dispatcher answer that arrives after we answered the timed-out GetList is dropped (one answer per request); games already in a library get `lang_packs` filled after an app update (`library._refresh_data_fields`). The library logs to logcat under the tag `fp_langpack` (dirs looked in, packs found, every language-pack call), so it shows up in the game's `launch.log`; an `ovr_AssetFile_GetList` the dispatcher leaves unanswered for 1.5 s is answered with our packs alone. Deadpool VR (Unreal) accepts a pack only when its `Metadata` equals the game's own version string (`ULanguagePacksSubsystem` compares it with `%s.%s.%s.%s.%s` built from the build info, e.g. `1.0.40.356975.Quest` = versionName; found by disassembling `libUE4.so`): the patch writes the APK's versionName into the library (`@FPMETA@` slot, `with_metadata`), `FRAMEPORT_LANGPACK_META` overrides it. Deadpool VR (2026-10-04, headset): German became selectable with that Metadata, but dialogue stayed silent (even English once reported as a pack) while the path was spelled `/sdcard/Android/obb/<pkg>/x.lang`; with the `/storage/emulated/0/Android/obb/<pkg>/x.lang` spelling (Unreal's own, now listed first in `scan_dirs`) German dialogue plays. `FRAMEPORT_LANGPACK_SKIP=<tags>` or a file `fp_langpack_skip` in the obb folder leaves packs out of the list (experiments).
+
 **Unresolved (as of 2026-09-28):** Arcsmith (right-eye distortion) and Time Stall (both eyes) — swap, tracking, Valve
 layers, depth, pacing ruled out. Sniper Elite VR (DEVICE LOST), Espire 1 (Mesa GL upload crash), HITMAN 3 (freedreno
 crash): use PC versions.
 
 ## Releases, CI, GitHub
+Maintainer-only notes (accounts, credentials, key locations) live in the git-ignored `CLAUDE.local.md`.
 Public repo `github.com/spoopyghosty0/frameport` (branch `main`). Push a `v*` tag → CI (`.github/workflows/build.yml`)
 tests, builds Windows x64 / macOS arm64 / Linux x64 bundles, signs, attests and publishes a GitHub Release
 (`FramePort-*.zip/.tar.gz`, the CLI wheel `frameport-<ver>-py3-none-any.whl`, `SHA256SUMS.txt`,
-`FramePort-selfsigned.cer`; notes = "What's new" from the annotated tag message + `docs/INSTALL.md` from "First launch").
+`FramePort-selfsigned.cer`; notes = "What's new" from the annotated tag message + the short `packaging/release-footer.md`; owner: keep release
+notes short — a few "What's new" bullets, nothing long after them).
 Installed apps find the release themselves (self-update), so the notes are what users see in the update dialog.
 - **Release checklist:** bump `src/frameport/_version.py` (the only version; `scripts/package.py` fails a tag build
   whose tag ≠ `v<_version>`), commit, `git tag -a vX.Y.Z -m "FramePort X.Y.Z" -m "<What's new, Markdown bullets>"`,
@@ -355,14 +516,17 @@ Installed apps find the release themselves (self-update), so the notes are what
 - Signing is **free/self-signed by the owner's choice** (no paid certs, no SignPath): Windows binaries are signed with
   a self-signed "FramePort (self-signed)" code-signing cert (RSA 3072, valid to 2031, SHA-256
   `4E:12:98:91:62:C0:E4:50:FB:65:1D:34:BB:73:00:09:7B:78:BE:88:5C:A7:6C:42:23:46:9B:92:A1:59:A7:6E`); secrets
-  `WINDOWS_CODESIGN_PFX` (base64) + `WINDOWS_CODESIGN_PASSWORD`. Private key: `~/.config/frameport-signing/` (WSL) and
-  the backup `PATCHED/_signing-keys/frameport-app-codesign/` — never commit it. macOS is ad-hoc signed only (Gatekeeper
+  `WINDOWS_CODESIGN_PFX` (base64) + `WINDOWS_CODESIGN_PASSWORD`. The private key is never committed (its
+  location is in `CLAUDE.local.md`). macOS is ad-hoc signed only (Gatekeeper
   needs right-click → Open; notarization would need the paid Apple program). Users still see SmartScreen unless they
   import the .cer into Trusted Root.
 - CI gotchas: `flet build` needs `--yes --no-rich-output` (it prompts to install Flutter; rich output crashes the
   Windows console) plus PYTHONUTF8; macOS builds need `--python-version 3.12 --arch arm64` (cryptography has no wheels
   for flet's default Python / x86_64 cross-build), with a PyInstaller fallback step; `astral-sh/setup-uv` has no
   floating major tags after v7 → pin the exact version; force-moving a tag starts duplicate runs (cancel one).
+- macOS runner (2026-10-02): `macos-latest` jobs went unassigned (cancelled after 15 min, no steps); `macos-15`'s Xcode
+  16.4 fails a Flutter plugin (`NWPath has no member`); `macos-26` (Xcode 26) builds with `flet build`. The PyInstaller
+  fallback (`package.py --pyinstaller`) passes `--yes` so a failed `flet build`'s folder doesn't stop it at a prompt.
 - Windows PowerShell calls from Python (`updates._powershell()`): use `%SystemRoot%\System32\WindowsPowerShell\v1.0\
   powershell.exe` with `PSModulePath` removed from the environment — started under PowerShell 7 (CI's default shell,
   or a user's pwsh terminal) it couldn't run Get-AuthenticodeSignature (v0.3.0's Windows update smoke failed on it).
@@ -373,14 +537,6 @@ Installed apps find the release themselves (self-update), so the notes are what
   open). Windows installs of 0.3.1/0.3.2 can't update themselves: they need one manual download.
 - The Linux bundle is built on ubuntu-22.04: a 24.04-built Flutter bundle needs GLib 2.80 (`undefined symbol:
   g_once_init_enter_pointer` on 22.04).
-- **This project's GitHub identity is `spoopyghosty0`** (a dedicated account; the machine's default gh/git login is a
-  different, personal account that must never touch this repo). `gh` (`~/.local/bin/gh`) uses it through
-  `GH_CONFIG_DIR=~/.config/gh-spoopyghosty0` (set for Claude Code in the git-ignored `.claude/settings.local.json`);
-  git pushes from this folder authenticate as it through a repo-local credential helper, and commits use the repo-local
-  identity `spoopyghosty0 <336754034+spoopyghosty0@users.noreply.github.com>`. Check with `gh api user --jq .login`
-  before any GitHub action.
-- **No Claude trailers** (`Co-Authored-By: Claude …`, `Claude-Session: …`) in commits or PR descriptions — the owner's
-  rule; history was rewritten to remove them.
 - **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.
 
@@ -403,11 +559,14 @@ GLAD/GLES); Unreal → alternate no-ForceQuit build. Score changes with
 - Reinstalls keep one rollback copy (`<base>/previous-game.apk`, `settings.conf.previous`); `frameport frame cleanup`
   removes them (and `--path ~/X` extra folders under home).
 
-## Project status (2026-09-29)
+## Project status (2026-10-02)
+Self-update, the Files tab, OVRPort 1.2.5, non-Quest Android apps (vr_kind) and GUI localisation (tr(), 0.3.x) are
+in; see the sections above. Earlier state (2026-09-29):
 34 Quest games ported; the owner confirmed in the headset that all FramePort-rebuilt games work: 23 work, 5 work with
 issues (Arcsmith/Time Stall eye distortion, AC Nexus some flipped launch text, Phantom DLC button, Silhouette hands),
 6 can't run (Sniper Elite VR, Espire 1, HITMAN, and the 32-bit Journey of the Gods / Shadow Point / Sports Scramble).
-Parity: all 34 rebuilt from the dumps match the known-good builds (`docs/parity-report.md`) and were reinstalled +
+Parity: all 34 rebuilt from the dumps match the known-good builds (`docs/parity-report.md`, generated locally and
+git-ignored; 34/34 again with OVRPort 1.2.5 on 2026-10-02) and were reinstalled +
 launch-tested with 0 regressions (`docs/parity-device-report.md`). `PATCHED/` holds exactly the installed builds.
 Owner preferences: manual installs (no third-party installer apps), Python + Flet, dynamic data over hardcoding,
 free tooling only, public repo scrubbed of personal data, keep the known-good backups.

CODE_OF_CONDUCT.md

@@ -0,0 +1,8 @@
+# Code of conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+In short: be respectful and constructive, assume good faith, and keep discussions about the project. Harassment and
+personal attacks aren't tolerated.
+
+Report unacceptable behaviour privately through a GitHub security advisory on this repository (it reaches the
+maintainer only). Reports are handled confidentially.

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+Thanks for helping. The quickest contributions:
+
+- **A game works on the Frame?** In FramePort: the game's menu → **Share working config…** opens a prefilled issue
+  with its recipe. Accepted configs become built-in recipes.
+- **Something doesn't work?** The game's menu → **Report a problem…** saves a diagnostics zip (personal data
+  removed) and opens a prefilled issue to attach it to.
+
+## Development
+```
+uv sync --extra dev          # Python 3.11+, uv (https://docs.astral.sh/uv/)
+uv run frameport-gui         # the app
+uv run frameport --help      # the command line
+uv run pytest                # tests (no headset or game files needed)
+uv run ruff check .          # lint
+```
+- Code and architecture: `CLAUDE.md`, `docs/ARCHITECTURE.md`; per-game symptoms and fixes: `docs/PLAYBOOK.md`.
+- Interface wording: `docs/STYLE.md`. GUI texts go through `tr()`; after changing them run
+  `python scripts/i18n_extract.py`.
+- Translations: see [Translating FramePort](#translating-frameport) below.
+- New fixes are patch modules (`src/frameport/patches/`), with a triage signature (`catalog/triage.yaml`), a PLAYBOOK
+  row and a unit test.
+- Native binaries in `artifacts/` are rebuilt with `python native/build.py` (downloads the NDK).
+
+## Adding a tested game
+
+Tested a game on the Steam Frame? The easiest way is in FramePort: open the game → **…** → **Share working config…**.
+It opens a prefilled GitHub issue with the exact recipe; after review a workflow turns it into
+`catalog/games/<package>.yaml`. Without the app: [working config form](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml). Something doesn't run: the game's
+**Report a problem…** (diagnostics zip, personal data removed) or the [problem report form](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml).
+After catalog changes, regenerate the games list: `python scripts/compat_list.py`.
+
+## Translating FramePort
+The app's texts (screens, help, patch and setting descriptions) can be translated; the command line, logs and
+diagnostics stay English. No programming needed:
+
+1. Copy `src/frameport/locales/template.json` to `src/frameport/locales/<code>.json`, where `<code>` is the language
+   code (`de`, `fr`, `pt`, `ja`, …).
+2. Add `"_language": "<the language's own name>"` (e.g. `"Deutsch"`); it's shown in Settings → Language.
+3. Fill in the values. Each key is the English text; leave a value empty to keep the English text. Plural entries
+   have a list value: `["<one>", "<other>"]`. Keep `{placeholders}` such as `{title}` or `{n}` exactly as they are,
+   and keep `…`, `·` and line breaks where the English has them.
+4. Try it: `uv run frameport-gui`, choose the language in Settings → Language, restart FramePort.
+5. Open a pull request with the file. When the English texts change, `python scripts/i18n_extract.py` refreshes the
+   template; new texts then show in English until they're translated.
+
+Wording rules for English (and a guide for tone) are in `docs/STYLE.md`.
+
+## Ground rules
+- Use only games you own. Contributions that help bypass DRM, licence or entitlement checks, or that add game files,
+  are not accepted.
+- Never commit personal data (IP addresses, user names, home paths, Steam IDs).
+- By contributing you agree to license your work under GPL-3.0-only.

README.md

@@ -1,107 +1,112 @@
 # FramePort
 
-FramePort installs Meta Quest standalone games and Oculus Rift PC VR games on the **Valve Steam Frame**. It patches a
-game so it runs on the Frame's runtimes, copies it to the headset over Wi-Fi and adds it to the Frame's Steam library
-with artwork.
+[![Release](https://img.shields.io/github/v/release/spoopyghosty0/frameport)](https://github.com/spoopyghosty0/frameport/releases/latest)
+[![Build](https://img.shields.io/github/actions/workflow/status/spoopyghosty0/frameport/build.yml?branch=main)](https://github.com/spoopyghosty0/frameport/actions/workflows/build.yml)
+[![Downloads](https://img.shields.io/github/downloads/spoopyghosty0/frameport/total)](https://github.com/spoopyghosty0/frameport/releases)
+[![License](https://img.shields.io/github/license/spoopyghosty0/frameport)](LICENSE)
+![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-blue)
+![Steam Frame](https://img.shields.io/badge/Steam%20Frame-supported-1b2838?logo=steam&logoColor=white)
+
+Install games that target the Meta Quest, Android, or general PCVR onto your **Valve Steam Frame**. FramePort handles everything from uploading game files, setting up your Frame, injecting compatibility patches, and adding shortcuts to your Steam library. FramePort aims to be as simple as possible by taking advantage of the fact that the Steam Frame runs on Linux.
 
 ![Library](docs/images/library.png)
 
-## Purpose
+> **Notice:** FramePort explicitly does NOT download, share, or unlock games. You must provide legally obtained game
+> executables. Core features of FramePort simply download and wrap other published tools (see [Built on](#built-on))
+> with patches provided by FramePort adding a hardware compatibility layer. This enables users to use games/apps legally
+> purchased on sites like [SideQuest](https://sidequestvr.com/). 
 
-FramePort is a **proof of concept**: it shows that VR software built for other platforms (Meta Quest, Oculus Rift) can
-run on the Steam Frame with a translation layer and a few targeted fixes. Most of the work is done by the projects
-FramePort wraps (see [Built on](#built-on)); FramePort selects and applies their fixes per game, adds Steam
-Frame-specific patches, and handles installing, testing and launching.
+## Features
 
-FramePort is **not a piracy tool**. It does not download, share or unlock games, and it does not remove DRM, licence or
-entitlement checks. Use it only with games you own. Games that check their licence through the Oculus Platform SDK are
-marked as not runnable on the Frame.
+- **Painless setup:** one short command on the Frame. No root, no `sudo`, no password.
+  [What it changes](docs/FRAME_SETUP.md).
+- **Type on Frame:** use your computer's keyboard on the Frame: in VR apps, Android apps, Steam and the desktop.
+  [More](#type-on-frame).
+- **One click per game:** convert, patch, sign, upload, add to Steam with artwork, launch test.
+- **Per-game recipes:** a tested catalog plus detection rules; every patch explained in plain words.
+- **FrameBridge:** FramePort's OpenXR adapter emulates what the Frame natively lacks (passthrough, room, controller models,
+  curved and 360° layers); game settings as simple switches.
+- **Beyond Quest:** Android apps as windows, PC VR via Proton or Revive, Windows (non-VR) games via Proton, a Files
+  tab with drag and drop.
+- **Self-updating** releases, redacted diagnostics, one-click problem reports and working-config sharing.
 
-## Getting started
+## Quick start
 
-1. **Download** the archive for your computer from the
-   [latest release](https://github.com/spoopyghosty0/frameport/releases/latest) and extract it anywhere:
+1. [Download](https://github.com/spoopyghosty0/frameport/releases/latest) and unzip the build for Windows, macOS
+   (Apple Silicon) or Linux, then start FramePort.
+2. **Connect the Frame** (once):
+   1. In FramePort click **Steam Frame → Show setup command**. Keep FramePort open; the Frame and your computer must
+      be on the same Wi-Fi.
+   2. On the Frame open the **SteamVR dashboard → Launch a program → Desktop**: the Linux desktop opens on a virtual
+      screen.
+   3. Open the app menu (bottom-left corner of that desktop) → **System → Konsole** (or search for Konsole).
+   4. Type the command FramePort shows exactly as shown (on-screen keyboard or any USB/Bluetooth keyboard) and press
+      **Enter**. This will run the following [bash setup script](bootstrap/bootstrap.sh).
+   5. After a few seconds the desktop closes by itself (Steam restarts once); that's expected. If
+      Steam asks to install **Lepton**, confirm it. FramePort shows the Frame as connected within a minute. No
+      password needed.
+3. **Add games → Scan a folder** with your game backups (APK + OBB, or PC VR game folders).
+4. Open a game → **Install on Frame**, then play it from the Frame's Steam library.
 
-   | Computer | File | Start |
-   |---|---|---|
-   | Windows 10/11 (x64) | `FramePort-windows-x64.zip` | `FramePort.exe` |
-   | macOS (Apple Silicon) | `FramePort-macos-arm64.zip` | `FramePort.app` |
-   | Linux (x64) | `FramePort-linux-x64.tar.gz` | `FramePort/FramePort` |
+Full guide, firewalls and troubleshooting: [docs/INSTALL.md](docs/INSTALL.md).
 
-   The builds are self-signed, so the first start shows a warning: Windows → **More info → Run anyway**;
-   macOS → right-click the app → **Open**. Details: [docs/INSTALL.md](docs/INSTALL.md).
-2. **Get the tools**: on first start FramePort downloads what it needs (Java runtime, OVRPort, apksigner) into its own
-   folder. Nothing is installed system-wide.
-3. **Connect the Frame**: turn on Developer Mode on the Frame (Settings → System → Developer). In FramePort open
-   **Steam Frame**; if the Frame isn't listed, switch it to Desktop mode, open Konsole and paste the one command
-   FramePort shows. This is needed once.
-4. **Add games**: **Add games → Scan a folder** with your Quest game backups (APK + OBB) or Rift game folders.
-   FramePort identifies each game and fetches its artwork and store details.
-5. **Install**: open a game and click **Install on Frame**. FramePort patches, checks, uploads and adds the game to the
-   Frame's Steam library, then runs a short launch test.
-6. **Play**: put the headset on and start the game from the Steam library (or click **Play on Frame**).
+## Type on Frame
 
-![Game page](docs/images/game.png)
+Typing in VR is painful, so FramePort turns your computer's keyboard into a keyboard for the Frame. Open **Type on
+Frame** (keyboard icon on the sidebar's Frame card, the Steam Frame page, or a game's menu), select a text field in
+the headset and type: searches, logins, chat, in any app, in Steam or on the desktop. Paste longer text to type it in
+one go. Nothing to install: FramePort adds a virtual keyboard on the Frame while the window is open, without root.
 
-FramePort updates itself: when a new version is released, the Library shows **Update now**.
+![Type on Frame](docs/images/type-on-frame.png)
 
-## What works
+Unity apps whose text fields close the moment you select them on the Frame (no system keyboard there) get a per-game
+fix, so Steam's on-screen keyboard and Type on Frame work in them too.
+[Details](docs/INSTALL.md#typing-on-the-frame).
 
-The built-in catalog has tested settings for 38 games (27 work, 5 work with known issues, 6 can't run on the Frame).
-Other games get suggested patches from detection rules; each suggestion states its reason, and every patch can be
-switched on or off under **Customize**.
+## Compatibility
 
-![Patches](docs/images/patches.png)
+If a game has already been tested with FramePort, it will automatically use the optimal game config. Otherwise, FramePort
+will attempt to guess key patches. If you find a new config that works for an app you are testing, please consider submitting it to the community!
 
-- Quest games run in Valve's Android runtime (Lepton). 32-bit-only Quest games can't run (the Frame has no 32-bit ARM
-  support).
-- Rift games run through Proton on the Frame (experimental) or on a Windows PC with SteamVR, streamed to the Frame.
-  Games that use the Oculus Platform SDK need the Oculus app and a licence, so they run on the PC only.
-- Automated launch tests confirm a game starts; visuals can only be checked in the headset.
+**[List of tested games](docs/GAMES.md)**
 
-![Steam Frame](docs/images/frame.png)
+**Tested something? Share it.** In FramePort open the game → **…** → **Share working config…** (it fills in the
+recipe for you) or **Report a problem…** (attaches a diagnostics zip with personal data removed). Without the app:
+[share a working config](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml) · [report a problem](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml). Shared configs become built-in recipes for everyone.
 
 ## Built on
 
-FramePort is a front end for other projects; most of the functionality comes from them:
-
-| Project | Used for |
-|---|---|
-| [OVRPort](https://github.com/Android-XR-Bridge/OVRPort) (overport, originally [ovrport/app](https://github.com/ovrport/app)) | Converts Quest games to OpenXR: its CLI applies the game patches and supplies the OpenXR loader; FramePort also includes its VrApi→OpenXR adapter |
-| Valve Lepton, Proton and SteamVR | Run Android games, Windows games and OpenXR on the Frame |
-| [Revive](https://github.com/LibreVR/Revive) (LibreVR) | Runs Oculus Rift games on OpenXR / SteamVR |
-| Mesa (Zink) | OpenGL ES on Vulkan on the Frame |
-| [Khronos OpenXR SDK](https://github.com/KhronosGroup/OpenXR-SDK) | OpenXR headers for the native layers |
-| Eclipse Temurin, Android apksigner, Android NDK | Java runtime, APK signing, building the native layers |
-| [Flet](https://flet.dev) | The desktop app |
-| OculusDB, Steam store | Game descriptions, genres and artwork |
-
-FramePort's own parts: game detection and recipes, the Steam Frame OpenXR adapter (FrameBridge) and the other native
-fixes in `native/`, the installer agent that runs on the Frame, and the desktop/command-line app.
-
-## Command line
-
-The same functions are available as `frameport` (included in the source tree; also released as a Python wheel):
-`frameport scan`, `frameport build`, `frameport install`, `frameport test`, `frameport update`. Run
-`frameport --help` for the full list.
+[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)
+· Eclipse Temurin, Android apksigner and NDK · [Flet](https://flet.dev) · OculusDB and Steam store data.
+What FramePort adds itself: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ## Documentation
 
-- [docs/INSTALL.md](docs/INSTALL.md): installing, first launch, updating, Rift games, sending files, reporting problems.
-- [docs/PLAYBOOK.md](docs/PLAYBOOK.md): symptoms and fixes per game.
-- [docs/FRAME_RUNTIME.md](docs/FRAME_RUNTIME.md): Steam Frame runtime facts.
-- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): how the code is organised.
+| | |
+|---|---|
+| [INSTALL.md](docs/INSTALL.md) | Install, connect, update, PC VR, files, problem reports |
+| [FRAME_SETUP.md](docs/FRAME_SETUP.md) | What setup changes on the Frame, networks and firewalls, undoing it |
+| [COMPATIBILITY.md](docs/COMPATIBILITY.md) | What runs and how well |
+| [GAMES.md](docs/GAMES.md) | Tested games and how well they run |
+| [PLAYBOOK.md](docs/PLAYBOOK.md) | Symptoms and fixes per game |
+| [FRAME_RUNTIME.md](docs/FRAME_RUNTIME.md) | Steam Frame runtime facts |
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | How the code is organised |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Code, recipes, translations |
 
 ## Development
 
 ```
 uv sync --extra dev
 uv run frameport-gui        # the app
+uv run frameport --help     # command line
 uv run pytest               # tests
 ```
 
-See `CLAUDE.md` for project notes and `native/README.md` for the native components.
+## AI Usage Notice
+While I would like to program everything manually, I no longer have much free time for personal projects. As a result I make use of AI tools to make it significantly quicker to debug compatibility issues.
 
 ## License
 
-GPL-3.0-only (it includes GPL-3.0 code from OVRPort). Not affiliated with Valve or Meta.
+GPL-3.0-only (includes GPL-3.0 code from OVRPort). Not affiliated with Valve or Meta.

SECURITY.md

@@ -0,0 +1,8 @@
+# Security
+
+FramePort talks to your Steam Frame over SSH with its own key and runs a small agent there; it also downloads tools
+and its own updates (checked against the release's SHA-256 sums and, on Windows, its signature).
+
+To report a vulnerability, please open a GitHub security advisory for this repository (Security → Report a
+vulnerability) instead of a public issue. Include the FramePort version (`frameport --version`) and how to reproduce
+it. Fixes are released as normal updates; FramePort offers them automatically.

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,27 @@
+# Third-party notices
+
+FramePort is GPL-3.0-only (see `LICENSE`). It includes or downloads the following third-party work.
+
+## Included in this repository / the release bundles
+| Component | Where | License |
+|---|---|---|
+| OVRPort VrApi → OpenXR adapter (`native/vrapi`, github.com/Android-XR-Bridge/OVRPort), with FramePort's changes | `native/vrapi-bridge/`, `artifacts/arm64-v8a/libvrapi.so` | GPL-3.0 (`native/vrapi-bridge/LICENSE.upstream`) |
+| OVRPort platform compatibility library (`native/platform`) | `native/platformcompat/`, `artifacts/arm64-v8a/libovrplatformcompat.so` | GPL-3.0; Meta Platform SDK headers under the Meta Platform Technologies SDK License (`native/platformcompat/licenses/OCULUS-PLATFORM-SDK.txt`) |
+| Khronos OpenXR SDK headers | used to build the native layers | Apache-2.0 / MIT (`native/vrapi-bridge/licenses/OPENXR-SDK.txt`) |
+| Android NDK runtime (statically linked libc++) | native Android libraries | Apache-2.0 with LLVM exception, plus legacy notices (`native/vrapi-bridge/licenses/ANDROID-NDK.txt`) |
+| Flet and Flutter (desktop app runtime) | release bundles | Apache-2.0 / BSD-3-Clause |
+| flet-dropzone / desktop_drop (drag-and-drop) | release bundles | Apache-2.0 / MIT |
+| Python packages (paramiko, zeroconf, psutil, pyelftools, capstone, UnityPy, PyYAML, requests, typer, pyaxmlparser, Pillow, cryptography, …) | release bundles | their own licenses (see each package's metadata) |
+
+FramePort's own native code (the FrameBridge adapter, GL/Vulkan/OpenXR shims, the Windows helpers) is GPL-3.0-only.
+
+## Downloaded at run time (not redistributed)
+| Tool | Source | License |
+|---|---|---|
+| OVRPort / overport CLI | github.com/Android-XR-Bridge/OVRPort releases (fallback github.com/ovrport/app) | GPL-3.0 |
+| 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 |
+
+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.

artifacts/SHA256SUMS

@@ -1,10 +1,12 @@
-0f681f54b59cfad2efc8883aee5a0971c2fba09d9ba2dca15a136b0ac74a59b8  ./arm64-v8a/libfp_vk.so
+48a3ecad77ec0f3215b29070e994590eb9579e04d3c88a47f37f306f9aeb01d9  ./arm64-v8a/libfp_langpack.so
+a5b03bb7ae5d953d7ded2bf117b0a19c57fae604f16f54310847f8e89593dde6  ./arm64-v8a/libfp_ovrp.so
+6d2b9f8cea2f2cf33b8ff30d29a2f3d9c4d55549260a867168a24e44abada021  ./arm64-v8a/libfp_vk.so
 8e00552d1ab90f82749db3caad4f773351fa8a28edcc5ea5cbd1b31c434ff32a  ./arm64-v8a/libframe_xrshim.so
 3dfcb0f2bec47857bcecc7261c58e076d872d4649718c40850f29e10c75477dd  ./arm64-v8a/libglshim.so
-dc62857b4f7a23b194060599339dfe72b38c16cdf4a9eb1b1f3b4d1fb9071a6d  ./arm64-v8a/libopenxr_loader_generic.so
+507bb1c62168da9335a5883ec264aabed2ce09d04b6524e67be504a273473f8d  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
 32525cd0a9ee3d9993d8871cd6905bdcf22cde4f4ba28f5db6434ce7d6554758  ./arm64-v8a/libvrapi.so
-a79c598744b98b9bf581664a80bcee1a0d11a62fdcdb99f05a0f6f381b6498cd  ./armeabi-v7a/libopenxr_loader_generic.so
+11b7019c6a8d3b2f0f89cf23011f84bbbcb8e907f0935978e1df675339abbb6e  ./armeabi-v7a/libopenxr_loader_generic.so
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 1aa733117cf57ccff7cf23f0425dbfd73b0332a3ef1c905ceeca0ccd0449c4e0  ./linux-arm64/XR_APILAYER_FRAMEPORT_timefix.json
 28c2430a02bbd8902c5bfb9562c6fd0e318654f9e05c095bfeb94b0450ab1b07  ./linux-arm64/libxr_frameport_timefix.so

bootstrap/bootstrap.sh

@@ -1,59 +1,134 @@
 #!/usr/bin/env bash
-# FramePort one-time Steam Frame setup. Run in the Frame's Desktop Mode terminal (Konsole):
-#   curl -fsSL http://<pc>:<port>/bootstrap.sh | bash
+# FramePort one-time Steam Frame setup. Run in the Frame's desktop terminal (SteamVR dashboard -> Launch a program
+# -> Desktop, then System -> Konsole):
+#   curl -fsS <pc-ip>:<port>/<code> | bash
 # (the FramePort app shows the exact line and serves this script while its Setup page is open).
 #
-# What it does (asks before anything that needs sudo):
-#   1. sets a password for the 'steamos' user if it has none (sudo needs one)
-#   2. enables the SSH server (sshd)
-#   3. authorizes the FramePort app's SSH key (no password needed afterwards)
-#   4. announces this Frame on the local network (avahi service "_frameport._tcp") so the app finds it
-#   5. checks for Valve's Lepton Android runtime and asks Steam to install it if missing
+# What it does (no password, no sudo):
+#   1. authorizes the FramePort app's SSH key (no password needed afterwards)
+#   2. configures podman for Lepton (avoids a kernel keyring leak after ~200 game starts)
+#   3. turns on Developer Mode if it's off (Valve's own helper; it also enables the SSH server and announces the
+#      Frame on the network as a SteamOS devkit). Steam restarts for that, which closes Desktop Mode: the rest
+#      runs on its own as a user service and the Frame returns to its normal view.
+#   4. asks Steam to install Valve's Lepton Android runtime if it's missing, then tells the app it's done
+# Log of the part that runs on its own: ~/.cache/frameport-setup.log
 set -euo pipefail
 PC_URL="__PC_URL__"          # filled in by the app when serving the script
 PAIR_CODE="__PAIR_CODE__"
 say() { printf '\n\033[1;36m==> %s\033[0m\n' "$*"; }
 
+DEVKIT_HELPER=/usr/bin/steamos-polkit-helpers/steamos-devkit-mode
+STEAM_CONFIG=~/.local/share/Steam/config/config.vdf
+JOB=~/.cache/frameport-setup.sh
+LOG=~/.cache/frameport-setup.log
+
+# Desktop Mode on SteamOS is a nested Plasma session inside steam.service, with its own XDG_RUNTIME_DIR and D-Bus:
+# systemctl/systemd-run --user only reach the user's systemd through the real runtime dir.
+user_systemd() {
+    XDG_RUNTIME_DIR="/run/user/$(id -u)" DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/$(id -u)/bus" "$@"
+}
+
 say "FramePort setup for $(hostname) ($(. /etc/os-release; echo "$NAME $VERSION_ID"))"
 
-if ! passwd -S "$USER" 2>/dev/null | grep -q ' P '; then
-    say "Your user has no password yet. SteamOS needs one for sudo (and as an SSH fallback)."
-    passwd
-fi
-
-say "Enabling the SSH server (sudo)"
-sudo systemctl enable --now sshd
-
 say "Authorizing the FramePort app's key"
-key=$(curl -fsSL "$PC_URL/key?code=$PAIR_CODE")
+key=$(curl -fsS "$PC_URL/key?code=$PAIR_CODE")
 [[ "$key" == ssh-ed25519\ * ]] || { echo "Could not fetch the app's key from $PC_URL (is the app still open?)"; exit 1; }
 mkdir -p ~/.ssh && chmod 700 ~/.ssh && touch ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys
 grep -qxF "$key" ~/.ssh/authorized_keys || echo "$key" >> ~/.ssh/authorized_keys
 
-say "Announcing this Frame on the network (avahi)"
-svc="<?xml version=\"1.0\" standalone='no'?>
-<!DOCTYPE service-group SYSTEM \"avahi-service.dtd\">
-<service-group>
-  <name replace-wildcards=\"yes\">FramePort on %h</name>
-  <service><type>_frameport._tcp</type><port>22</port><txt-record>user=$USER</txt-record><txt-record>pair=$PAIR_CODE</txt-record></service>
-</service-group>"
-echo "$svc" | sudo tee /etc/avahi/services/frameport.service >/dev/null || true
-sudo systemctl enable --now avahi-daemon >/dev/null 2>&1 || true
-sudo systemctl reload avahi-daemon >/dev/null 2>&1 || true
-
 say "Configuring podman for Lepton"
 # rootless podman leaks one kernel keyring per container start; ~200 game launches would exhaust the quota
 mkdir -p ~/.config/containers
 grep -qs '^ *keyring *=' ~/.config/containers/containers.conf || printf '[containers]\nkeyring = false\n' >> ~/.config/containers/containers.conf
 
-say "Checking for Lepton (Valve's Android runtime)"
-if ls ~/.local/share/Steam/steamapps/common/Lepton/lepton >/dev/null 2>&1; then
-    echo "Lepton found."
+# The rest: Developer Mode (if needed), Lepton, telling the app. As a file, so it can run as its own user service:
+# stopping Steam ends Desktop Mode and every program started in it, this terminal included.
+mkdir -p ~/.cache
+cat >"$JOB" <<'JOB'
+set -u
+MODE=$1 PC_URL=$2 PAIR_CODE=$3 CONFIG=$4 HELPER=$5
+log() { echo "$(date +%T) $*"; }
+if [[ $MODE == devmode ]]; then
+    sleep 5  # let the user read the terminal before Desktop Mode closes
+    # Steam re-applies "DevModeEnabled" from config.vdf at every start (calling Valve's helper) and rewrites
+    # config.vdf when it exits: stop Steam, set the value, run the helper (pkexec, allowed without a password), start.
+    log "stopping Steam"
+    systemctl --user stop steam.service
+    for _ in $(seq 40); do pgrep -x steam >/dev/null || break; sleep 1; done
+    if pgrep -x steam >/dev/null; then
+        log "Steam didn't stop"
+        systemctl --user start steam.service
+        exit 1
+    fi
+    cp "$CONFIG" "$CONFIG.before-frameport"
+    python3 - "$CONFIG" <<'PY'
+import re, sys
+path = sys.argv[1]
+text = open(path, encoding="utf-8").read()
+if re.search(r'"DevModeEnabled"\s+"\d+"', text):
+    text = re.sub(r'("DevModeEnabled"\s+)"\d+"', r'\1"1"', text)
+else:  # Steam keeps it in InstallConfigStore/developer
+    lines, keys, key, at = text.splitlines(keepends=True), [], None, None
+    for i, line in enumerate(lines):
+        s = line.strip()
+        if s == "{":
+            keys.append((key or "").lower())
+            if keys == ["installconfigstore", "developer"]:
+                at = ("in", i, line[:len(line) - len(line.lstrip())] + "\t")
+                break
+        elif s == "}":
+            if keys == ["installconfigstore"]:  # end of the top section without a developer block
+                at = ("new", i, line[:len(line) - len(line.lstrip())] + "\t")
+                break
+            keys.pop()
+        elif re.fullmatch(r'"[^"]*"', s):
+            key = s.strip('"')
+    if at is None:
+        sys.exit("unexpected config.vdf layout")
+    kind, i, ind = at
+    if kind == "in":
+        lines.insert(i + 1, f'{ind}"DevModeEnabled"\t\t"1"\n')
+    else:
+        lines[i:i] = [f'{ind}"developer"\n', f"{ind}{{\n", f'{ind}\t"DevModeEnabled"\t\t"1"\n', f"{ind}}}\n"]
+    text = "".join(lines)
+open(path, "w", encoding="utf-8").write(text)
+PY
+    rc=$?
+    [[ $rc == 0 ]] && { "$HELPER" --enable; rc=$?; }
+    log "Developer Mode: $([[ $rc == 0 && -f /etc/steamos-devkit-enabled ]] && echo on || echo "failed ($rc)")"
+    systemctl --user start steam.service
+    [[ $rc == 0 ]] || exit 1
+    for _ in $(seq 90); do pgrep -x steam >/dev/null && break; sleep 1; done
+    sleep 20  # let Steam finish starting before asking it for anything
+fi
+if [[ -e ~/.local/share/Steam/steamapps/common/Lepton/lepton ]]; then
+    log "Lepton found"
 else
-    echo "Lepton is missing. Make sure Developer Mode is on (Settings > System > Developer)."
-    echo "Asking Steam to install it now; confirm in Steam, or launch 'Lepton Development' from your library once."
-    (steam steam://install/3029110 >/dev/null 2>&1 &) || true
+    log "asking Steam to install Lepton (confirm it in Steam)"
+    steam steam://install/3029110 >/dev/null 2>&1 &
+fi
+if curl -fsS "$PC_URL/paired?code=$PAIR_CODE&user=$(id -un)&host=$(hostname)" >/dev/null; then
+    log "told FramePort: done"
+else
+    log "couldn't reach FramePort at $PC_URL"
+fi
+JOB
+
+if [[ -f /etc/steamos-devkit-enabled ]]; then
+    say "Developer Mode is on"
+    bash "$JOB" finish "$PC_URL" "$PAIR_CODE" "$STEAM_CONFIG" "$DEVKIT_HELPER" 2>&1 | tee "$LOG"
+    say "Done. Return to FramePort on your PC: this Frame should now appear as connected."
+    exit 0
 fi
 
-curl -fsS "$PC_URL/paired?code=$PAIR_CODE&user=$USER&host=$(hostname)" >/dev/null 2>&1 || true
-say "Done. Return to FramePort on your PC: this Frame should now appear as connected."
+say "Turning on Developer Mode"
+if [[ ! -x "$DEVKIT_HELPER" || ! -f "$STEAM_CONFIG" ]] || \
+        ! user_systemd systemd-run --user --collect --quiet --unit="frameport-setup-$$" \
+            bash -c 'bash "$0" "$@" >"$HOME/.cache/frameport-setup.log" 2>&1' \
+            "$JOB" devmode "$PC_URL" "$PAIR_CODE" "$STEAM_CONFIG" "$DEVKIT_HELPER"; then
+    echo "Couldn't turn it on automatically. Turn it on in Settings > System > Developer, then run this command again."
+    exit 1
+fi
+echo "Steam restarts to turn it on. That closes the desktop in a few seconds and the Frame returns to its"
+echo "normal view; setup finishes on its own. If Steam asks to install Lepton, confirm it."
+echo "Then return to FramePort on your PC: the Frame appears as connected within a minute."

catalog/games/com.Appnori.AllInOneSports.yaml

@@ -0,0 +1,20 @@
+package: com.Appnori.AllInOneSports
+title: AllInOneSports
+status: works
+tested_version: 1.9.0
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+  known_good_sha256: a1f9535ac569068bba25f137f131db9d4c3e997c072f3e790beac8ffef701fe3
+  app: 0.6.3
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 35
+  issue: 13
+source_hint: All In One Sports

catalog/games/com.Armature.VR4.yaml

@@ -0,0 +1,28 @@
+package: com.Armature.VR4
+title: VR4
+status: works
+notes: Installs the no-ForceQuit build and fixes a campaign shader that hung the GPU after the opening cutscene.
+details: Entering the campaign gave a black screen, slowing audio and a crash (Mercenaries loaded). One fragment shader
+  reads a loop counter before setting it, which hangs the GPU; the Vulkan shim zeroes it (vk_shader_fix). The
+  no-ForceQuit build is kept. Diagnosed and confirmed on a Frame by the reporter of GitHub issue 10.
+tested_version: '2.3'
+engine: Unreal
+xr: VrApi
+alt_overport:
+- patch_remove_unreal_force_quit
+use_alt: true
+adapter:
+  # one campaign shader reads an uninitialized loop counter and hangs the GPU (black screen, slowing audio, crash);
+  # the Vulkan shim inserts two OpStores that zero it and its accumulator (from the reporter's capture, GitHub
+  # issue 10)
+  vk_shader_fix: 6488:5dcd842db8d21e3fdd13ec916d2e34dd0cfdf12a92fffaf8a27115072ef55c59:2624:0x0003003e,138,18,0x0003003e,150,42
+verified:
+  date: '2026-10-02'
+  known_good_sha256: 40ff74e37264b28ae8826923b69d0731d9620094c76462be34159643d6ae91b3
+  app: 0.3.4
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 26
+  issue: 1
+updated: '2026-10-04'
+source_hint: Resident Evil 4

catalog/games/com.CyanWorlds.Myst.yaml

@@ -0,0 +1,19 @@
+package: com.CyanWorlds.Myst
+title: Myst
+status: issues
+notes: Minor graphical glitches on some objects.
+details: The crash is in the Frame's SteamVR runtime (vrclient.so CVRInputLatest::UpdateActionStateInternal via
+  xrSyncActions) on the first input sync after focus, in 2 of 4 headset sessions. sync_guard serialises input syncs
+  with event polling and pauses them for 250 ms after focus returns (confirmed in the headset, no crash). The object
+  glitches are not application space warp (turning it off didn't change them and ran slightly worse).
+tested_version: 3.3.0
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+adapter:
+  sync_guard: 1
+verified:
+  date: '2026-10-04'
+updated: '2026-10-04'
+source_hint: Myst

catalog/games/com.CyanWorlds.Riven.yaml

@@ -0,0 +1,20 @@
+package: com.CyanWorlds.Riven
+title: Riven
+status: works
+notes: Plays as expected.
+tested_version: 1.9.0
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+adapter:
+  equirect_emul: 1
+verified:
+  date: '2026-10-04'
+  known_good_sha256: 7c211588f39c21d67998ac6a6aeb44a8ad66c6551a1b0feb1bcf44e2cef98bdf
+  app: 0.6.3
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 35
+  issue: 26
+source_hint: Riven

catalog/games/com.GhostlyBirdGames.BattleGlide.yaml

@@ -0,0 +1,16 @@
+package: com.GhostlyBirdGames.BattleGlide
+title: BattleGlide
+status: works
+notes: Freezes from the headset's brief focus losses are hidden (focus_hold).
+details: The Frame drops the session out of focus for ~0.5 s every few seconds (11 times in 80 s of play) and Unreal
+  pauses each time; focus_hold hides dips up to 1 s once the game has been focused for 1 s. Longer dips (real
+  interruptions) still pause it.
+tested_version: 0.4.1 (BETA)
+engine: Unreal
+xr: OpenXR
+adapter:
+  focus_hold: 1
+verified:
+  date: '2026-10-04'
+updated: '2026-10-04'
+source_hint: BattleGlide

catalog/games/com.NewFolderGames.IAmCat.yaml

@@ -0,0 +1,23 @@
+package: com.NewFolderGames.IAmCat
+title: I Am Cat
+status: issues
+notes: The view vibrates slightly, even when holding still.
+details: Unity 2022.3 with the Oculus XR Plugin falls back to GLES (Zink) on the Frame, where its single-pass
+  (multiview) rendering drew the right eye wrong (GitHub issue 8); frame.unity_multipass renders each eye in its own
+  pass (OculusSettings.GetStereoRenderingMode + its inlined read in OculusLoader.Initialize). Poses and frame times
+  are consistent, but every frame reaches the runtime one display period late (two passes on Zink) and the game
+  clamps its physics step to 10 ms, so the view judders; scale 0.8 didn't change it. Possible next steps are fixing the
+  multiview path instead or the game's fixed timestep.
+tested_version: 1.4.0.0
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.unity_multipass
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-03'
+  issue: 8
+updated: '2026-10-04'
+source_hint: I Am Cat

catalog/games/com.NewFolderGames.IAmMonkey.yaml

@@ -0,0 +1,21 @@
+package: com.NewFolderGames.IAmMonkey
+title: I Am Monkey
+status: works
+notes: Its intro video plays through FrameBridge's video panels.
+details: The game plays its intro on a panel that an Android media player (ExoPlayer) draws into
+  (XR_KHR_android_surface_swapchain). The Frame's runtime lists that extension but refuses the call, so the panel had
+  no image and the game stayed black waiting for the video (GitHub issue 25). The adapter's surface_emul (on by
+  default) hands the player a real Android Surface and copies each video frame into an ordinary swapchain the panel
+  shows.
+tested_version: 1.0.5
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+  issue: 25
+updated: '2026-10-04'
+source_hint: I Am Monkey

catalog/games/com.StressLevelZero.BONELAB.yaml

@@ -0,0 +1,15 @@
+package: com.StressLevelZero.BONELAB
+title: BONELAB
+status: unsupported
+notes: Crashes while starting its graphics (Vulkan); no fix yet.
+details: SIGSEGV in vkCreateInstance, called from the game's own Vulkan hooks (libSLZQuestNative.so) into code that no
+  longer exists, right after OVRPlugin's pre-initialization creates and destroys an OpenXR instance. Keeping the
+  runtime (vrclient.so) and Steam's Fossilize layer loaded didn't help, so the stale pointer is to memory freed with
+  that first instance.
+tested_version: 1.2974.57485
+engine: Unity
+xr: OpenXR
+verified:
+  date: '2026-10-04'
+updated: '2026-10-04'
+source_hint: BONELAB

catalog/games/com.Ubisoft.ACNexusVR.yaml

@@ -9,8 +9,11 @@ notes: Some launch warning text is still upside down; the rest of the UI is fixe
   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:
+- patch_ac_nexus_no_appsw_90
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   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)'

catalog/games/com.Warpfrog.BladeAndSorcery.yaml

@@ -0,0 +1,22 @@
+package: com.Warpfrog.BladeAndSorcery
+title: 'Blade & Sorcery: Nomad'
+status: works
+notes: The headset's brief focus losses are hidden (focus_hold, up to 2.5 s).
+details: The Frame's runtime drops focus now and then (mostly 1.5-7 s, some only milliseconds); the game pauses
+  ("System menu opened", the world freezes) and re-aligns the player when focus returns (Player.OnVRPresence ->
+  Teleport, the sideways jump). They match the headset's wear sensor flickering off while worn (SteamVR "HMD off" 0.5-2
+  s), which only this game reacts to; focus_hold hides dips up to 2.5 s here. Rendering keeps 72 fps throughout.
+tested_version: 1.3.1
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  focus_hold: 1
+  focus_hold_ms: 2500
+verified:
+  date: '2026-10-04'
+updated: '2026-10-04'
+source_hint: Blade & Sorcery Nomad

catalog/games/com.beatgames.beatpaber.yaml

@@ -0,0 +1,23 @@
+package: com.beatgames.beatpaber
+title: Beat Saber (co-existence build)
+status: works
+notes: A Beat Saber build with its own package name, so a modded and an unmodded Beat Saber can be installed side by
+  side.
+details: The submitted build's app label was very long and the game didn't appear in the Frame's Steam library (GitHub
+  issue 27, a shortcut Steam dropped again; fixed in 0.7.0); the recipe's title names it.
+tested_version: 1.45.1_27839
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 9965b01d5d1a3707bce1762f60d5419ce3e89bc095c63586f6940bb69696e9fd
+  app: 0.6.3
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 35
+  issue: 29
+source_hint: Beat Saber

catalog/games/com.beatgames.beatsaber.yaml

@@ -0,0 +1,19 @@
+package: com.beatgames.beatsaber
+title: Beat Saber
+status: works
+tested_version: 1.40.8_7379
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-03'
+  known_good_sha256: ee720e040931f2547f7611e58ec5ad72d86e800dd4cf3135f576019683f2f359
+  app: 0.6.1
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 33
+  issue: 6
+source_hint: Beat Saber

catalog/games/com.crowscrowscrows.AccountingPlus.yaml

@@ -0,0 +1,17 @@
+package: com.crowscrowscrows.AccountingPlus
+title: Accounting+
+status: issues
+notes: Starts in VR, but doesn't get past its "press any button" screen.
+details: Unity 2017.4 built-in Oculus support. frame.unity_oculus_check gets VR started (Meta's system-app check and
+  the frame wait its legacy loop never makes, libfp_ovrp.so), ~72 fps. Controller input reaches the game's OVRInput
+  cleanly (both Touch controllers connected, individual button bits, input focus 1 while focused) but the screen
+  doesn't continue; Cpp2IL can't read this Unity version to see what it waits for.
+tested_version: 1.24.35
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_oculus_check
+verified:
+  date: '2026-10-04'
+updated: '2026-10-04'
+source_hint: Accounting+

catalog/games/com.iillusions.spacepiratetrainerquest.yaml

@@ -0,0 +1,20 @@
+package: com.iillusions.spacepiratetrainerquest
+title: Space Pirate Trainer Quest
+status: works
+tested_version: '1.97'
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+  known_good_sha256: 711d87e6c1fa14fdcdc8bab5792657523d0281b5d904f7f1abafd98f3189d2c0
+  app: 0.6.3
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 35
+  issue: 14
+source_hint: Space Pirate Trainer

catalog/games/com.lakento.dinosquest.yaml

@@ -0,0 +1,19 @@
+package: com.lakento.dinosquest
+title: Dinosaur Island
+status: works
+tested_version: 1.7.5
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-03'
+  known_good_sha256: 41ecbc728dc533eebcc3980e140fe1764fbd1958735d8a299c63fa9cda13a923
+  app: 0.6.2
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 33
+  issue: 12
+source_hint: DINOSAUR ISLAND

catalog/games/com.owlchemylabs.jobsimulator.yaml

@@ -0,0 +1,19 @@
+package: com.owlchemylabs.jobsimulator
+title: Job Simulator
+status: works
+tested_version: 1.4.0.6515
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-03'
+  known_good_sha256: 64638d7f93bb93cc61f422a43a08bb0d35b9bb4b463e90a42da7002147f03d1b
+  app: 0.6.2
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 33
+  issue: 11
+source_hint: Job Simulator

catalog/games/com.parkline.wander.yaml

@@ -0,0 +1,20 @@
+package: com.parkline.wander
+title: Wander
+status: works
+tested_version: '0.3569'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+  known_good_sha256: c0c9de22b3646f35009a53796757d26f8d4e95259713f26a18fae2be995b23aa
+  app: 0.6.3
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 35
+  issue: 17
+source_hint: Wander

catalog/games/com.playful.LuckysTale.yaml

@@ -0,0 +1,21 @@
+package: com.playful.LuckysTale
+title: Lucky's Tale
+status: issues
+notes: Runs out of memory within a few minutes and freezes the Frame until the game is killed.
+details: Unity's asset loading thread (Loading.PreloadManager) grows the game's native heap by about 1 GB/s
+  shortly after start (10+ GB plus all swap, then the kernel kills it; perf page-fault profile, 2026-10-04). The text
+  window and the MSAA patch aren't the cause (same with the window off); the OBB is byte-identical to the original.
+  The earlier "headset restarted in a menu" reports (GitHub issue 9) were most likely this. No fix yet.
+tested_version: 1.0.55
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-03'
+  issue: 9
+updated: '2026-10-04'
+source_hint: Luckys Tale

catalog/games/com.qcxr.qcxr.yaml

@@ -0,0 +1,21 @@
+package: com.qcxr.qcxr
+title: QuestCraft
+status: issues
+notes: The launcher runs, but Minecraft crashes while starting its graphics (OpenGL error 1282).
+details: QuestCraft downloads its Java runtime (JRE.zip from QuestCraft's GitHub releases) into files/runtimes/JRE
+  on first start; on the Frame that step left nothing behind ("libjvm.so not found"). With the runtime unpacked there
+  by hand, Java, Fabric and the mods load and Minecraft 1.21.5 starts initializing, then its first texture fails with
+  OpenGL error 1282 in QuestCraft's GL-to-GLES layer on Zink. Leads (2026-10-04) - Android's libEGL ran out of
+  eglGetProcAddress slots for desktop GL functions; LWJGL and JNA natives in the APK don't match the newer files
+  QuestCraft downloads.
+tested_version: 6.0.0-RC4
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+updated: '2026-10-04'
+source_hint: QuestCraft

catalog/games/com.resolutiongames.cookinggame.yaml

@@ -0,0 +1,19 @@
+package: com.resolutiongames.cookinggame
+title: Cook-Out
+status: works
+tested_version: 1.20.0.10625-release
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-03'
+  known_good_sha256: 7217649c503adf76f3a959fc72858c446c2a42a9ce9e209286977b1950397915
+  app: 0.6.1
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 33
+  issue: 3
+source_hint: com.resolutiongames.cookinggame

catalog/games/com.roblox.client.yaml

@@ -0,0 +1,14 @@
+package: com.roblox.client
+title: Roblox
+status: unsupported
+notes: Crashes on its first VR frame on the Frame.
+details: SIGSEGV on Roblox's render thread right after it re-creates its eye swapchains (format 37, which the Frame
+  doesn't offer, retried as sRGB 43) — in its own code or inside the runtime's xrBeginFrame. No integrity or login
+  check involved; also needs an online login once it runs.
+tested_version: 2.741.1051
+engine: Other
+xr: OpenXR
+verified:
+  date: '2026-10-04'
+updated: '2026-10-04'
+source_hint: Roblox

catalog/games/com.steelcrategames.keeptalkingandnobodyexplodes.yaml

@@ -0,0 +1,19 @@
+package: com.steelcrategames.keeptalkingandnobodyexplodes
+title: Keep Talking and Nobody Explodes
+status: works
+tested_version: 1.10.15
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+  known_good_sha256: 1a6f18e6d7b077e2662c7e633d473018067f4c871f5c45c4632c58233feaeac5
+  app: 0.6.3
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 35
+  issue: 15
+source_hint: Keep Talking and Nobody Explodes

catalog/games/com.stremio.vrone.yaml

@@ -0,0 +1,21 @@
+package: com.stremio.vrone
+title: Stremio
+status: works
+notes: 'Unity 6 VR media centre (its interface is web pages in Vuplex 3D WebView). Text fields closed at once on the
+  Frame (no system keyboard): frame.unity_text_input keeps them selected and device.text_input_window shows the
+  Android window so Steam''s on-screen keyboard (or Type on Frame from the PC) types into them; confirmed in the
+  headset by the owner (2026-10-03), who confirmed it working. Note: the add-ons page can stay blank in VR (the
+  add-on sync itself succeeds). "Play in an external player" can''t reach another app: Lepton sends every link to
+  Steam''s browser.'
+details: 'Patches: frame.unity_text_input (TMP_InputField.TouchScreenKeyboardShouldBeUsed -> false,
+  isKeyboardUsingEvents -> true; uGUI InputField too), device.text_input_window (lepton-show-flatscreen).'
+tested_version: 0.7.5
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-03'
+source_hint: Stremio

catalog/games/org.wiicompiled.quest.yaml

@@ -0,0 +1,24 @@
+package: org.wiicompiled.quest
+title: WiiCompiled VR
+status: issues
+notes: 'To add a game: in FramePort''s Files tab, upload your .wcgame file to this game''s storage, folder
+  Android/data/org.wiicompiled.quest/files/WiiCompiledOpenXRVR/Import, then open WiiCompiled (it imports the newest
+  file there; one at a time). The right eye jitters during races.'
+details: A native Mario Kart Wii recompilation (needs your own disc as .wcgame files built by the WiiCompiled
+  launcher on a computer). Lepton's Android has no document picker, so the launcher's "Import from computer" and
+  "select disc image" buttons fail (ActivityNotFoundException for OPEN_DOCUMENT); its Import folder is read when the
+  launcher opens instead. The game's libmain.so has its own OpenXR loader and talks to the Frame's runtime directly
+  (FrameBridge isn't in its path); the right-eye jitter in races comes from its stereo replay of the race view, so it
+  needs a fix in WiiCompiled itself. The launcher is a flat Android window (shown with lepton-show-flatscreen).
+tested_version: 0.4.0-quest
+engine: Other
+xr: OpenXR
+frame:
+- frame.sdl_clipboard
+- frame.vk_sanitize
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+updated: '2026-10-04'
+source_hint: WiiCompiled

catalog/games/rift.superhot_vr.yaml

@@ -0,0 +1,20 @@
+package: rift.superhot_vr
+title: SUPERHOT VR
+status: works
+notes: 'Supports SteamVR/OpenXR itself: runs directly, without Revive.'
+engine: Unity
+xr: OpenXR
+kind: rift
+pcvr:
+- pcvr.xr_timefix
+- pcvr.steamvr_tuning
+pcvr_remove:
+- pcvr.revive
+as_is: true
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 143dd3c6a93a45819a98e3cca8fd1535b461cdf860c927d955ca54815faf5d7b
+  app: 0.6.3
+  overport_cli: 1.2.5
+  issue: 28
+source_hint: SUPERHOT VR

catalog/games/unity.SUPERHOT_Team.SUPERHOT_VR_QA.yaml

@@ -0,0 +1,22 @@
+package: unity.SUPERHOT_Team.SUPERHOT_VR_QA
+title: SUPERHOT VR
+status: works
+notes: Quest version. Needs FramePort's launcher from agent 41 (reinstall once) so the game can write its saves.
+details: Unity 2018.4 with built-in Oculus support (GLES). Its eye swapchains (GL_RGBA8, then a 16-bit format) are
+  created as sRGB by the adapter's swapchain_fix. The game creates its cloud save folder with mode 1700 and quits at
+  start when it can't write there ("Something failed to initialize. Quitting!"); the launcher now gives every folder
+  in the game's storage owner and group write permission.
+tested_version: '1.161'
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_no_msaa
+- frame.unity_oculus_check
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+updated: '2026-10-04'
+source_hint: SUPERHOT VR

catalog/games/us.lighthaus.nanocellx.yaml

@@ -5,11 +5,15 @@ source_hint: Nano
 engine: Unity
 xr: OpenXR
 status: works
-notes: Needed Oculus OS telemetry class stubs.
+notes: Needs Oculus OS telemetry class stubs and the no-ForceQuit build (the normal build quits right after
+  starting).
 verified:
-  date: '2026-09-28'
+  date: '2026-10-02'  # owner-confirmed with the no-ForceQuit build
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 31469d50b8ee292597291db7cc3bc3eca8e851f533cd92bba0d64214893580cc
 frame:
 - frame.oculusos
+alt_overport:
+- patch_remove_unreal_force_quit
+use_alt: true

catalog/triage.yaml

@@ -44,7 +44,43 @@ signatures:
     pattern: 'zink.*DEVICE[_ ]LOST|VK_ERROR_DEVICE_LOST'
     severity: fatal
     diagnosis: The GPU hung (Zink/Mesa). For GLES Unity games MSAA render-to-texture is the usual cause.
-    suggest: [frame.unity_no_msaa]
+    suggest: [frame.unity_no_msaa, frame.unity_runtime_msaa_off]
+  - id: unity-runtime-msaa
+    pattern: 'recommended MSAA level is [248]\. Switching to the recommended level'
+    severity: info
+    diagnosis: The game's OVRManager turns MSAA on at runtime (QualitySettings can't keep it off). On GLES this can
+      hang the Frame's GPU or restart the headset; if it does, keep it off in the game's code.
+    suggest: [frame.unity_runtime_msaa_off]
+  - id: runtime-input-crash
+    pattern: 'vrclient\.so[^\n]*(UpdateActionStateInternal|sxr_xrSyncActions)'
+    severity: fatal
+    diagnosis: The Frame's runtime crashed in its controller-input code (xrSyncActions), typically right after the game
+      got focus. sync_guard serialises input syncs and pauses them briefly after focus returns.
+    suggest: [adapter.sync_guard]
+  - id: focus-dip-teleport
+    pattern: 'OnVRPresence[^\n]*Teleport'
+    severity: warning
+    diagnosis: The game moves the player when the headset reports presence again, which the Frame's brief focus dips
+      trigger (the view jumps). focus_hold hides dips under 600 ms.
+    suggest: [adapter.focus_hold]
+  - id: unity-vr-device-none
+    pattern: 'NewtonVR.*(not setup properly|no headset found)|Loaded VR device: None|XR: Oculus could not be loaded'
+    severity: fatal
+    diagnosis: Unity didn't start its Oculus VR device (older Unity checks for Meta's system apps first), so the game
+      runs as a hidden 2D app.
+    suggest: [frame.unity_oculus_check]
+  - id: sdl-no-clipboard
+    pattern: 'ClipboardManager\.addPrimaryClipChangedListener|SDLClipboardHandler\.<init>'
+    severity: fatal
+    diagnosis: An SDL app (SDL2 / LÖVE) crashed at start because Lepton's Android has no clipboard service.
+    suggest: [frame.sdl_clipboard]
+  - id: controller-profile-rejected
+    pattern: 'PATH_UNSUPPORTED.*xrSuggestInteractionProfileBindings|xrSuggestInteractionProfileBindings.*(-48|PATH_UNSUPPORTED)'
+    severity: info
+    diagnosis: The runtime rejected controller bindings for a profile it doesn't know (Meta's Touch Plus/Pro). Usually
+      harmless (Meta's OVRPlugin suggests plain Touch too); a game that suggests only these gets them again as Touch
+      (profile_remap, on by default; log "controller profile ... -> oculus/touch_controller").
+    suggest: []
   - id: gl-shader-failed
     pattern: 'GLShim\s*: SHADER COMPILE FAILED|#extension directive is not allowed in the middle|could not implicitly convert operands'
     severity: error
@@ -79,7 +115,8 @@ signatures:
       agent's controller_models command).
     suggest: []
   - id: scene-missing
-    pattern: 'XR_FB_scene|XR_FB_spatial_entity.*(not supported|UNSUPPORTED)|xrQuerySpacesFB'
+    # not OVRPlugin's routine "Unavailable OpenXR extension: XR_FB_scene" (printed by every OVRPlugin game)
+    pattern: '(?<!Unavailable OpenXR extension: )XR_FB_scene|XR_FB_spatial_entity.*(not supported|UNSUPPORTED)|xrQuerySpacesFB'
     severity: warning
     diagnosis: The game uses the Meta scene (room) API; enable the adapter's guardian-based room emulation.
     suggest: [adapter.scene_emul]
@@ -226,6 +263,25 @@ signatures:
     diagnosis: The game crashed under Wine/Proton (set the Proton debug log and check steam-<appid>.log).
     suggest: [pcvr.proton_log]
 
+  - id: save-folder-permission
+    pattern: "(We don't have write permission to|UnauthorizedAccessException: Access to the path \"/(sdcard|storage/emulated/0)/Android/data/)"
+    severity: error
+    diagnosis: The game can't write to a folder it created in its storage (e.g. SUPERHOT's cloud/data, mode 1700, which
+      makes it quit at start). FramePort's launcher (agent 41 or newer) gives such folders owner and group write
+      permission before and during every launch; update the game on the Frame (reinstall) to get the new launcher.
+    suggest: []
+  - id: surface-swapchain-emulated
+    pattern: 'surface_emul: emulated Android surface swapchain'
+    severity: info
+    diagnosis: The game plays a video on a panel through an Android Surface (XR_KHR_android_surface_swapchain), which the
+      Frame's runtime refuses; FrameBridge emulates it (surface_emul) and copies each video frame into the panel.
+    suggest: []
+  - id: surface-swapchain-failed
+    pattern: 'surface_emul: (setup failed|upload failed|EGL context failed|Vulkan upload path unavailable)'
+    severity: warning
+    diagnosis: FrameBridge couldn't emulate an Android video panel (XR_KHR_android_surface_swapchain); the panel stays
+      empty, and a game waiting for its intro video may stay black (e.g. I Am Monkey's intro).
+    suggest: []
 milestones:  # progress markers, in order; the furthest one reached is reported
   - {id: pcvr-launch, kind: pcvr, pattern: 'FramePort: launching|Launched injector with', label: Launcher started}
   - {id: pcvr-oculus-hmd, kind: pcvr, pattern: 'FramePort oculushmd: OculusHMDConnected event ready', label: Oculus headset event provided}

docs/ARCHITECTURE.md

@@ -84,3 +84,21 @@ update [--check] [--yes]`. CI runs `scripts/update_smoke.py` on every OS with th
 overport CLI release (Android-XR-Bridge/OVRPort, fallback ovrport/app) + patch list + titles, Temurin JRE (Adoptium API), apksigner (Google repository index),
 store artwork/titles (overport image API), catalog (optional remote), Lepton location/appid (Frame appmanifests),
 Steam user (Frame userdata).
+
+## Built on
+
+FramePort is a front end for other projects; most of the functionality comes from them:
+
+| Project | Used for |
+|---|---|
+| [OVRPort](https://github.com/Android-XR-Bridge/OVRPort) (overport, originally [ovrport/app](https://github.com/ovrport/app)) | Converts Quest games to OpenXR: its CLI applies the game patches and supplies the OpenXR loader; FramePort also includes its VrApi→OpenXR adapter |
+| Valve Lepton, Proton and SteamVR | Run Android games, Windows games and OpenXR on the Frame |
+| [Revive](https://github.com/LibreVR/Revive) (LibreVR) | Runs Oculus Rift games on OpenXR / SteamVR |
+| Mesa (Zink) | OpenGL ES on Vulkan on the Frame |
+| [Khronos OpenXR SDK](https://github.com/KhronosGroup/OpenXR-SDK) | OpenXR headers for the native layers |
+| Eclipse Temurin, Android apksigner, Android NDK | Java runtime, APK signing, building the native layers |
+| [Flet](https://flet.dev) | The desktop app |
+| OculusDB, Steam store | Game descriptions, genres and artwork |
+
+FramePort's own parts: game detection and recipes, the Steam Frame OpenXR adapter (FrameBridge) and the other native
+fixes in `native/`, the installer agent that runs on the Frame, and the desktop/command-line app.

docs/COMPATIBILITY.md

@@ -0,0 +1,30 @@
+# Compatibility
+
+The built-in catalog has tested settings for games, each marked as working, working with known issues, or not
+running on the Frame: see the [list of tested games](GAMES.md) (recipes in [catalog/games](../catalog/games)).
+Other games get suggested patches from detection rules; each suggestion states its reason, and every patch can be
+switched on or off under **Customize**: described in plain words, with **Show technical details** for the exact
+effect of each patch.
+
+Tried an untested game? Its page asks how it runs; **Share working config…** opens a prefilled GitHub issue so your
+recipe can join the built-in catalog for everyone.
+
+![Patches](images/patches.png)
+
+| Kind of app | On the Steam Frame |
+|---|---|
+| Meta Quest games (APK) | Translated to OpenXR (OVRPort) and patched for the Frame; run in Valve's Android runtime (Lepton) |
+| Other Android VR apps using OpenXR (e.g. Pico builds) | Translated the same way; the other headset's own extensions and store services aren't available |
+| Ordinary Android apps and games (no VR) | Installed unchanged and shown as a flat window in the headset |
+| PC VR games (Windows; OpenXR, SteamVR or Oculus) | Run through Proton on the Frame (experimental), or on a Windows PC with SteamVR and streamed to the Frame; Oculus-only games use Revive |
+| Can't run | 32-bit-only or x86-only APKs, Pico/HTC Wave SDK apps, Android XR apps, and games that check an Oculus licence (they need the Oculus app on a PC) |
+
+Automated launch tests confirm that a game starts; visuals can only be checked in the headset.
+
+![Steam Frame](images/frame.png)
+
+The **Files** tab manages files on the Frame: upload videos, documents, mods or saves from the computer (buttons or
+drag-and-drop), download, rename and delete (one entry or a selection), in the shared folders every game sees or in
+one game's own storage.
+
+![Files](images/files.png)

docs/FRAME_RUNTIME.md

@@ -14,6 +14,19 @@
   `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).
+- `<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.
+- **2D apps** (verified 2026-10-02 with an open-source 2048 game): Lepton runs every app headless
+  (`lepton.headless=true`; only OpenXR output reaches the headset) unless the app folder (`STEAM_COMPAT_INSTALL_PATH`)
+  contains a file `lepton-show-flatscreen` (`liblepton/app_metadata.sh`): then Android (11, Waydroid) gets a Wayland
+  window shown as a flat panel in the headset. FramePort creates the file for Android apps without VR. Android's
+  back/home/recents bar is drawn over the app's own controls; `qemu.hw.mainkeys=1` removes it, but it's only read at
+  boot and Lepton has no setting for extra properties, so patch `device.hide_navbar` (default on for apps without
+  VR) passes it as a second line of a
+  `LEPTON_GFXRECON_*` value (Lepton copies those into the boot properties unescaped). Runtime alternatives didn't
+  work on Android 11: `policy_control` is gone, `cmd statusbar send-disable-flag home recents` has no `back` and
+  moves the back button onto the app's controls, the `sysui_nav_bar` layout and disabling SystemUI had no effect.
 
 ## OpenXR runtime (as seen by games through overport's loader)
 - Instance extensions present include KHR_android_create_instance (must be enabled; the adapter adds it),
@@ -92,3 +105,14 @@
 - Processes started from Steam (Konsole, SSH sessions?) share steam.service's cgroup: use `systemd-run --user`.
 - SSH: `sshd` must be enabled (`sudo systemctl enable --now sshd`), which needs a user password (`passwd`).
 - mDNS: avahi-daemon runs by default; hostname `frame` → `frame.local`.
+
+## Text input
+
+- Lepton's Android has no on-screen keyboard (IME) and VR apps run headless, so no Android window has keyboard focus
+  and key presses (Steam's keyboard, USB/Bluetooth keyboards, `input text`) don't reach VR apps. The app folder's
+  `lepton-show-flatscreen` marker shows the window (VR keeps working) and gives it focus; Steam's on-screen keyboard
+  then opens for its text fields (FramePort patch `device.text_input_window`).
+- `/dev/uinput` is writable by the steamos user (ACL for Steam Input): a uinput virtual keyboard works like a real
+  one everywhere (FramePort's "Type on Frame", agent `_keyboard`).
+- Unity text fields close without a system keyboard; see `frame.unity_text_input` in PLAYBOOK.md.
+

docs/FRAME_SETUP.md

@@ -0,0 +1,53 @@
+# Frame setup: what changes, networks, undoing it
+
+For the steps themselves see [INSTALL.md](INSTALL.md#connecting-the-steam-frame).
+
+## What the setup changes
+
+The setup command runs [`bootstrap/bootstrap.sh`](../bootstrap/bootstrap.sh), served by the app over your
+local network. Everything it changes:
+
+| Change | Where | How to undo |
+|---|---|---|
+| Turns on **Developer Mode** (only if it's off). Steam restarts once, which closes Desktop Mode; the rest of the setup finishes on its own as a user service (log: `~/.cache/frameport-setup.log`). | `"DevModeEnabled" "1"` in `~/.local/share/Steam/config/config.vdf` (old file kept as `config.vdf.before-frameport`), then Valve's own `steamos-polkit-helpers/steamos-devkit-mode --enable`. That helper enables the SSH server (`sshd`), the devkit service that makes the Frame findable on the network, the remote-desktop and debug services, and system crash dumps. | Settings → System → Developer → Developer Mode off. Valve's helper switches all of those services off again. |
+| Lets the app's SSH key in. | One line ending in `frameport` in `~/.ssh/authorized_keys`. The folder and file are created if missing. | Delete that line. |
+| Configures podman for Lepton. Rootless podman leaks one kernel keyring per container start, and after about 200 game starts every game fails. | `[containers]` / `keyring = false` in `~/.config/containers/containers.conf`. | Remove those lines. |
+| Asks Steam to install **Lepton** (Valve's Android runtime, Steam app 3029110) if it's missing. You confirm it in Steam. | Steam library | Uninstall it in Steam. |
+
+The script runs as your user: no root, no `sudo`, no password. The only system-level change, Developer Mode, is
+made by Valve's own helper, the same one the Settings switch uses. If Developer Mode can't be turned on
+automatically, the script asks you to turn it on in Settings → System → Developer and run the command again.
+
+Nothing else on the system is touched: no packages, no read-only-filesystem changes, no polkit rules. The script
+also leaves two files: `~/.cache/frameport-setup.sh` (the part that runs on its own) and its log.
+
+**Later, the app adds** (all as your user, no root, no `sudo`):
+- FramePort's helper in `~/.local/share/frameport/`;
+- the games, each with a launcher and its data in `~/Applications/quest-frame/<package>/`;
+- their Steam library entries and artwork (`shortcuts.vdf` + `config/grid/`);
+- for PC VR games: an OpenXR layer (`~/.local/share/openxr/1/api_layers/explicit.d/XR_APILAYER_FRAMEPORT_timefix.json`)
+  and, when the first PC VR game is installed, Valve's ARM64 Proton and its Steam Linux Runtime (Steam downloads them;
+  Steam restarts once).
+
+**Settings → Uninstall FramePort → Also remove from the Frame** deletes the games, their Steam entries, the helper
+folder, the OpenXR layer and the setup script's files. Developer Mode, the SSH key line, the podman setting, Lepton
+and Proton stay. Undo them as shown above or in Steam.
+
+## Network and firewalls
+
+The setup command is the only time the Frame connects to your computer: it downloads the script from FramePort on
+TCP port 8765 (8766/8767 if taken), only while the setup command is shown and for at most 30 minutes. Everything
+else goes from the computer to the Frame. If the command just says "timed out", the setup page shows what is likely
+blocking it after about 45 seconds:
+
+- **Windows:** allow FramePort (or Python, when running from source) when Windows asks. On a network Windows treats as
+  **Public** it stays blocked unless you allow public networks; set your home network to Private in Windows'
+  network settings instead.
+- **macOS:** with the firewall on (System Settings → Network → Firewall), allow incoming connections for FramePort
+  when asked.
+- **Linux:** firewalld: `sudo firewall-cmd --add-port=8765/tcp` (until the next restart). ufw:
+  `sudo ufw allow 8765/tcp`, afterwards `sudo ufw delete allow 8765/tcp`.
+- **WSL:** Windows' Hyper-V firewall blocks connections into WSL without asking. FramePort adds a temporary rule for
+  the setup ports (one admin prompt) and removes it again when setup is done or after 35 minutes. WSL must use
+  mirrored networking: `networkingMode=mirrored` under `[wsl2]` in `%UserProfile%\.wslconfig`, then `wsl --shutdown`.
+- Or skip the setup command and use the devkit pairing (see [INSTALL.md](INSTALL.md#connecting-the-steam-frame)): it needs no connection into your computer.

docs/GAMES.md

@@ -0,0 +1,71 @@
+# Tested games
+
+Games tested on the Steam Frame with FramePort's recipes. Games not listed here may work too: FramePort suggests patches for them, and a working config can be shared from the app (**Share working config…**).
+Tested a game? [Share a working config](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml) or [report a problem](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml) (in the app: the game's **…** menu does both and fills in the details).
+Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
+
+| Game | Platform | Status | Notes |
+|---|---|---|---|
+| 4XVR Video Player | Quest | ✅ Works |  |
+| AllInOneSports | Quest | ✅ Works |  |
+| Asgard's Wrath 2 | Quest | ✅ Works |  |
+| BAM | Quest | ✅ Works |  |
+| BARTENDER VR SIMULATOR | Quest | ✅ Works |  |
+| Batman: Arkham Shadow | Quest | ✅ Works |  |
+| BattleGlide | Quest | ✅ Works |  |
+| Beat Saber | Quest | ✅ Works |  |
+| Beat Saber (co-existence build) | Quest | ✅ Works |  |
+| Blade & Sorcery: Nomad | Quest | ✅ Works |  |
+| Carve Snowboarding | Quest | ✅ Works |  |
+| Cook-Out | Quest | ✅ Works |  |
+| Demeter | Quest | ✅ Works |  |
+| Dinosaur Island | Quest | ✅ Works |  |
+| Espire 2 | Quest | ✅ Works |  |
+| Genotype | Quest | ✅ Works |  |
+| H.U.N.T | Quest | ✅ Works |  |
+| I Am Monkey | Quest | ✅ Works |  |
+| In Death: Unchained | Quest | ✅ Works |  |
+| Job Simulator | Quest | ✅ Works |  |
+| Keep Talking and Nobody Explodes | Quest | ✅ Works |  |
+| LEGO® Bricktales | Quest | ✅ Works |  |
+| Marvel's Deadpool VR | Quest | ✅ Works |  |
+| Medieval Dynasty New Settlement | Quest | ✅ Works |  |
+| Mobile Suit Gundam: Silver Phantom | Quest | ✅ Works |  |
+| Nano | Quest | ✅ Works |  |
+| NEX Player | Quest | ✅ Works |  |
+| NOPE CHALLENGE | Quest | ✅ Works |  |
+| Path of the Warrior | Quest | ✅ Works |  |
+| PowerWash Simulator VR | Quest | ✅ Works |  |
+| Rick and Morty: Virtual Rick-ality | PC VR | ✅ Works |  |
+| Riven | Quest | ✅ Works |  |
+| Robo Recall | Quest | ✅ Works |  |
+| Sniper Elite VR: Winter Warrior | Quest | ✅ Works |  |
+| Space Pirate Trainer Quest | Quest | ✅ Works |  |
+| Stremio | Quest | ✅ Works |  |
+| SUPERHOT VR | PC VR | ✅ Works |  |
+| SUPERHOT VR | Quest | ✅ Works |  |
+| The Climb 2 | Quest | ✅ Works |  |
+| Toy Master | Quest | ✅ Works |  |
+| Under Cover | Quest | ✅ Works |  |
+| VR4 | Quest | ✅ Works |  |
+| Wallace & Gromit in The Grand Getaway | Quest | ✅ Works |  |
+| Wander | Quest | ✅ Works |  |
+| Accounting+ | Quest | ⚠️ Works with issues | Starts in VR, but doesn't get past its "press any button" screen. |
+| Arcsmith | Quest | ⚠️ Works with issues | Right eye distorts during movement (unresolved; swap, tracking, Valve layers, depth and pacing ruled out). |
+| Assassin's Creed Nexus | Quest | ⚠️ Works with issues | Some launch warning text is still upside down; the rest of the UI is fixed by flip emulation. |
+| I Am Cat | Quest | ⚠️ Works with issues | The view vibrates slightly, even when holding still. |
+| Lucky's Tale | Quest | ⚠️ Works with issues | Runs out of memory within a few minutes and freezes the Frame until the game is killed. |
+| Myst | Quest | ⚠️ Works with issues | Minor graphical glitches on some objects. |
+| Phantom: Covert Ops | Quest | ⚠️ Works with issues | DLC/store button crashes (no Meta store). |
+| QuestCraft | Quest | ⚠️ Works with issues | The launcher runs, but Minecraft crashes while starting its graphics (OpenGL error 1282). |
+| Silhouette | Quest | ⚠️ Works with issues | Hand-tracking game; the Frame synthesizes hands from controllers, so it is janky. |
+| Time Stall | Quest | ⚠️ Works with issues | Both eyes distort during movement (unresolved). |
+| WiiCompiled VR | Quest | ⚠️ Works with issues | To add a game: in FramePort's Files tab, upload your .wcgame file to this game's storage, folder Android/data/org.wiicompiled.quest/files/WiiCompiledOpenXRVR… |
+| BONELAB | Quest | ❌ Doesn't run | Crashes while starting its graphics (Vulkan); no fix yet. |
+| Espire 1: VR Operative (Quest Edition) | Quest | ❌ Doesn't run | Mesa GL driver crash during texture upload. |
+| HITMAN 3 VR: Reloaded | Quest | ❌ Doesn't run | Vulkan driver crash (freedreno), even without Valve layers. |
+| Journey of the Gods | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |
+| 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. |
+| Sniper Elite VR | Quest | ❌ Doesn't run | GPU hang (zink: DEVICE LOST) even with MSAA off. |
+| Sports Scramble (Santa Cruz) | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |

docs/INSTALL.md

@@ -9,6 +9,7 @@ runtime, the OVRPort CLI and apksigner into its data folder (Settings → Tools
 | Windows 10/11 (x64) | `FramePort-windows-x64.zip` | `FramePort.exe` |
 | macOS (Apple Silicon) | `FramePort-macos-arm64.zip` | `FramePort.app` |
 | Linux (x64, GTK 3; Ubuntu 22.04 or newer) | `FramePort-linux-x64.tar.gz` | `FramePort/FramePort` |
+| Linux (ARM64, GTK 3; Ubuntu 22.04 or newer) | `FramePort-linux-arm64.tar.gz` | `FramePort/FramePort` |
 | Command line only (Python 3.11+) | `frameport-<version>-py3-none-any.whl` | `frameport --help` |
 
 The command-line version installs from the wheel's release link with `uv tool install <link>` (or pipx / pip).
@@ -22,16 +23,81 @@ start shows a warning:
   `FramePort-selfsigned.cer` (attached to each release) into *Trusted Root Certification Authorities* (Current User) to
   show FramePort as the publisher; the certificate can only sign code. Remove it with `certmgr.msc`.
 - **macOS:** right-click `FramePort.app` → **Open** → **Open** (once), or `xattr -dr com.apple.quarantine FramePort.app`.
-- **Linux:** `tar xzf FramePort-linux-x64.tar.gz && ./FramePort/FramePort`.
+- **Linux:** `tar xzf FramePort-linux-x64.tar.gz && ./FramePort/FramePort` (ARM64: `FramePort-linux-arm64.tar.gz`).
 
 ## Connecting the Steam Frame
 
-1. On the Frame: Settings → System → Developer → turn on **Developer Mode**. The Frame and the computer must be on the
-   same network.
-2. In FramePort open **Steam Frame**. A Frame in Developer Mode appears in the list.
-3. First time only: on the Frame switch to Desktop mode (Steam button → Power → Switch to Desktop), open Konsole and
-   run the command FramePort shows. It enables SSH, authorises this computer and installs Valve's Android runtime
-   (Lepton) if needed.
+The Frame and the computer must be on the same network.
+
+1. In FramePort open **Steam Frame** and click **Show setup command**.
+2. First time only, on the Frame:
+   1. Open the **SteamVR dashboard → Launch a program → Desktop**: the Linux desktop opens on a virtual screen.
+   2. Open the app menu (bottom-left corner of that desktop) → **System → Konsole** (or search for Konsole).
+   3. Type the command FramePort shows exactly as shown (on-screen keyboard or any USB/Bluetooth keyboard) and press
+      **Enter**. It looks like `curl -fsS 192.168.1.20:8765/1a2b3c4d | bash`: your computer's address, then a
+      one-time code.
+   4. After a few seconds the desktop closes by itself (Steam restarts once); that's expected. If
+      Steam asks to install **Lepton** (Valve's Android runtime), confirm it.
+
+   FramePort connects by itself within a minute. No password is needed. The command lets FramePort in and turns on
+   **Developer Mode** (which includes SSH); everything it changes is listed in [FRAME_SETUP.md](FRAME_SETUP.md).
+3. Later starts: a Frame in Developer Mode appears in the list and FramePort connects to it automatically. (If you
+   turn Developer Mode off in Settings → System → Developer, turn it on again there.)
+
+**Without Konsole:** turn on Developer Mode yourself (Settings → System → Developer). The Frame then appears under
+**On your network**. On the Frame open Settings → Developer → **Pair new host**, then click **Connect** in FramePort
+and approve it on the Frame (Valve's own devkit pairing; it only sends this computer's key to the Frame). Install
+Lepton from the Steam Frame page afterwards if it's missing.
+
+### Firewalls
+
+If the setup command only says "timed out", a firewall on your computer blocks the Frame; the setup page
+says which after about 45 seconds. Details per system: [FRAME_SETUP.md](FRAME_SETUP.md#network-and-firewalls).
+
+## Running FramePort on the Frame (experimental)
+
+FramePort can run on the Steam Frame itself, without a PC: in **Desktop Mode**, download
+`FramePort-linux-arm64.tar.gz`, unpack it (`tar xzf FramePort-linux-arm64.tar.gz`) and start `FramePort/FramePort`.
+Turn on **Developer Mode** first (Steam → Settings → System); FramePort then manages "This Frame" directly, with
+no pairing. Games are added to the Steam library when you go back to **Gaming Mode** (Steam has to restart for it,
+which would end Desktop Mode). This is new: please report anything odd with **Report a problem**.
+
+## Installing games
+
+- **Install on Frame** on a game's page (or select several in the Library and install them together). Installs run
+  one after another in the background; **Activity** shows the current one at the top.
+- **Update all** reinstalls every game whose build changed (e.g. after a FramePort update). Questions that need an
+  answer (e.g. Oculus games that can't run on the Frame) are asked once, for all games.
+- If the Frame goes to sleep, turns off or leaves the Wi-Fi, the queue **waits** and continues once it's back; uploads
+  pick up where they stopped. While installs run, FramePort keeps the Frame from going to sleep. Before a large batch
+  it checks the Frame has enough free space.
+- Your own game files are never changed. The converted copy is temporary: it's removed once the game is on the Frame
+  (Settings → Installing: keep them, or remove all now).
+- **Game settings…** (game menu or the Steam Frame page): sharpness, refresh rate, controllers, menus, 360° video and
+  mixed-reality options in plain words, only those that matter for the game. Changes are kept with the game and,
+  when it's installed, used the next time it starts.
+- Ordinary Android apps (no VR) are installed unchanged and shown as a flat window in the headset. Android's
+  back/home/recents buttons are hidden by default (patch **Hide Android's navigation bar**).
+
+![Game page](images/game.png)
+
+Each game has **Game settings** in plain words (sharpness, refresh rate, controllers, menus, 360° video, mixed
+reality), showing only what matters for that game. Changes are kept with the game and reach the Frame right away.
+
+![Game settings](images/game-settings.png)
+
+## Typing on the Frame
+
+- **Type on Frame** (Steam Frame page, a game's menu, or the keyboard icon on the sidebar's Frame card): while the
+  window is open, this computer's keyboard works as a keyboard plugged into the Frame. Select a text field in the
+  headset (in an app, Steam or the desktop) and type; Esc and shortcuts go to the Frame too. Paste longer text into
+  the box to type it in one go (US keyboard layout). Click **Done** to disconnect.
+- **Steam's on-screen keyboard** opens for text fields of apps shown as a window (2D apps, and VR apps with
+  **Show the app's Android window**). Steam lists that window as **Gamescope** (the Frame's display compositor);
+  leave it open: it's what receives the typing, the VR view isn't affected.
+- **Unity apps whose text fields close at once** (a caret flashes, nothing can be typed): FramePort suggests
+  **Make Unity text fields work** for them. The first time, it downloads Cpp2IL (a tool that finds the right spot in the
+  game's code, ~17 MB). Games added before this version: open the game's menu → **Analyze again**, then reinstall.
 
 ## Updating
 
@@ -47,11 +113,12 @@ update log is `logs/update.log` in the data folder.
 Command line: `frameport update` (`--check` only checks, exit code 10 = update available; `--yes` doesn't ask).
 `FRAMEPORT_NO_UPDATE_CHECK=1` turns all checks off.
 
-## Oculus Rift (PC VR) games
+## PC VR games
 
-Scan a folder of Rift games (one folder per game) or use **Add games → Add one game folder…**. FramePort finds the
-game's program and asks when there is more than one candidate. **Already patched** on a game page installs a copy
-unchanged. FramePort uses an installed Revive, or downloads a portable copy.
+PC VR games are Windows VR games (OpenXR, SteamVR or Oculus). Scan a folder of them (one folder per game) or use
+**Add games → Add one game folder…**. FramePort finds the game's program and asks when there is more than one
+candidate. **Already patched** on a game page installs a copy unchanged. Oculus-only games need Revive: FramePort uses
+an installed Revive, or downloads a portable copy.
 
 - **Play from this PC:** Windows with Steam and SteamVR. **Install on this PC** adds the game to Steam; stream it to the
   Frame with Steam Link. If a game can't keep up with the refresh rate, FramePort lowers the rate and enables motion
@@ -60,21 +127,57 @@ unchanged. FramePort uses an installed Revive, or downloads a portable copy.
   on the game page.
 - Games that use the Oculus Platform SDK check the licence through the Oculus app, so they run on the PC only.
 
-## Videos, documents and mods
+**Windows games without VR:** **Add games → Add one game folder…** with the game's folder (pick the program that
+starts it if asked). FramePort installs it on the Frame and Proton runs it as a window, like Steam's own Windows games;
+it shows up in the Frame's Steam library tagged "Windows game on Frame". Whether a game runs depends on Proton on ARM
+(x86 games run through emulation).
 
-Steam Frame → **Send files** (or a game's menu → **Add videos & files…**) copies files to the Frame. **Videos**,
-**Downloads** and **Documents** appear inside every Quest game as `/sdcard/Movies`, `/sdcard/Download` and
-`/sdcard/Documents`. Apps find them by browsing folders; Android's media index doesn't work on the Frame. Command
-line: `frameport frame send <files> --to videos`.
+## Files on the Frame (videos, documents, mods, saves)
+
+The **Files** tab manages files on the Frame over the same connection as installs; no other transfer app is needed.
+Pick a location, browse folders, and use **Upload files** / **Upload folder**, **New folder**, or the download, rename
+and delete buttons on each entry. Tick several entries (or the box above the list for all) to download or delete them
+together. In the downloaded app you can also drag files and folders from Explorer / Finder / your file manager onto
+the list to upload them into the open folder. Uploads and downloads run in the Activity panel, resume after an interruption and
+skip files that are already there.
+
+- **Videos**, **Downloads** and **Documents** appear inside every Quest game as `/sdcard/Movies`, `/sdcard/Download`
+  and `/sdcard/Documents`. Apps find files by browsing folders; Android's media index doesn't work on the Frame.
+- Under **Game storage**, each installed game has its own `/sdcard` (mods, saves). A game's menu → **Add videos and
+  files…** opens it. Video players that list only their own folder (e.g. 4XVR's "Internal Storage" = `4XPlayer`) find
+  videos uploaded into that folder.
+- **Home folder** shows everything in the Frame's home folder (hidden files with **Show hidden files**).
+
+Command line: `frameport frame send <files> --dest videos` (`frameport frame storage` lists the destinations).
 
 ## Sharing a working game, reporting a problem
 
 - **Share working config…** (game menu): opens a prefilled GitHub issue with the game's patches and settings. Accepted
-  configs become built-in recipes.
-- **Report a problem…** (game menu, or Settings → Problems & feedback): saves a diagnostics zip to Documents (logs,
+  configs become built-in recipes. Untested games ask on their page once they've been installed or tested: **It
+  works**, **It has issues** or **It doesn't run**.
+- **Report a problem…** (game menu, or Settings → Problems and feedback): saves a diagnostics zip to Documents (logs,
   recipe, device details; IP addresses, user names, home folders and Steam ids replaced) and opens a prefilled GitHub
   issue to attach it to. Command line: `frameport diag report <game>`, `frameport share-recipe <game>`.
 
+## Command line
+
+Everything the app does is also a `frameport` command (in a source checkout: `uv run frameport`); `frameport --help`
+and `frameport <command> --help` describe every option. The main ones:
+
+| Command | What it does |
+|---|---|
+| `scan <folder>` / `list` / `show <game>` | add games, list the library, show a game's analysis and patches |
+| `recipe <game> --enable/--disable <patch>` | change a game's patches (`patches` lists them all) |
+| `build <game>` / `install <game>` / `test <game>` | build, install on the Frame (`--to pc` for PC VR on this PC), launch test |
+| `frame discover` / `frame connect` / `frame info` | find, pair with and describe the Frame |
+| `frame send` / `frame storage` / `frame cleanup` | copy files to the Frame, show where they go, free space |
+| `tools status` / `tools install` | the tools FramePort downloads |
+| `diag report <game>` / `share-recipe <game>` | report a problem / share a working recipe |
+| `update` | update FramePort |
+
+Exit codes: 0 done, 1 something failed, 2 wrong usage, 10 (`update --check`) a newer version exists. Errors are
+one line on stderr; `FRAMEPORT_DEBUG=1` shows the full traceback.
+
 ## Uninstalling
 
 Settings → **Uninstall FramePort…** (or `frameport uninstall-app`) removes its data folder, the Steam shortcuts it

docs/PLAYBOOK.md

@@ -14,6 +14,10 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Symptom | Cause | Fix |
 |---|---|---|
 | Every game suddenly fails to start: `crun: create keyring …: Disk quota exceeded`, `is not a running context` | rootless podman leaked a kernel keyring per launch; 200-key quota exhausted | `keyring = false` in `~/.config/containers/containers.conf` (FramePort agent does it), then reboot the Frame once |
+| A Unity app's text field shows a caret for a moment and loses focus; no keyboard appears (e.g. Stremio VR login) | Unity's TMP_InputField/InputField wait for Android's on-screen keyboard and close themselves without one (Lepton has none); headless VR apps also have no focused Android window, so no key press reaches them | `frame.unity_text_input` (Cpp2IL finds `TouchScreenKeyboardShouldBeUsed`/`isKeyboardUsingEvents`, rewritten to false/true) + `device.text_input_window` (lepton-show-flatscreen: Steam's keyboard and Type on Frame work) |
+| Black screen at start while audio/ExoPlayer runs; log `xrEndFrame: dropped N unusable layer(s)`, a quad layer with swapchain 0x0 (e.g. I Am Monkey's intro video) | The game plays video into an Android-surface swapchain (XR_KHR_android_surface_swapchain); the Frame's runtime lists the extension but returns FUNCTION_UNSUPPORTED | adapter `surface_emul` (default on): FrameBridge gives the player a SurfaceTexture-backed Surface and copies each frame into an ordinary swapchain (log `surface_emul: …`) |
+| The game quits right after start: `Something failed to initialize. Quitting!` / `We don't have write permission to …/files/cloud/data` (e.g. SUPERHOT) | The game created a save folder with mode 1700; inside Lepton the app writes through the folder's group | launch.sh `fix_perms` adds owner + group write to every folder in the game's storage (agent 41); reinstall to get the new launcher |
+| The whole Frame slows to a halt, then the game is killed (`Out of memory: Killed process … anon-rss:10+ GB`), e.g. Lucky's Tale | The game's own memory grows ~1 GB/s on Unity's `Loading.PreloadManager` thread (perf page-fault profile); not the flat window, not the text-input patches | none yet: mark unsupported; profile with `perf record -p <pid> -e page-faults --call-graph fp` (works as steamos, `perf_event_paranoid` 2) |
 | `APP_ACTIVITY is empty`, nothing starts | Manifest has category INFO only; Lepton needs LAUNCHER | `frame.launcher` (automatic) |
 | PC VR game on the Frame shows as a flat window / Revive: `Unable to load LibOVRRT DLL` / `LoaderInstance::CreateInstance chained CreateInstance call failed` | Frame SteamVR runtime rejects OpenXR apiVersion 1.1 (`XR_ERROR_API_VERSION_UNSUPPORTED`), which Proton 11's VR helper requests | `pcvr.xr_timefix` (Frame OpenXR layer, default on): retries xrCreateInstance as 1.0 |
 | Unreal PC VR game on the Frame runs as a flat window although OpenXR works (no `LogHMD` OVRPlugin lines; Unreal logs nothing when it skips the Oculus plugin) / launch.log: `FramePort oculushmd: could not create the OculusHMDConnected event` | UE's OculusHMD (and LibOVR's `ovr_Detect`) only start when the Windows event `OculusHMDConnected` exists and is signalled; on a PC the Oculus service creates it. Revive hooks `OpenEventW` for it, but that relies on Detours patching Wine's (ARM64EC) kernelbase | `pcvr.oculus_unreal` (default for Unreal Rift games; PC VR counterpart of overport's `patch_oculus_unreal`): launch.sh runs the injector through `fp_oculushmd.exe`, which provides the real event until the game exits |
@@ -29,6 +33,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | `INSTALL_FAILED_NO_MATCHING_ABIS` | 32-bit-only APK; Frame has no AArch32 | None. PC/Rift version via Revive |
 | `UnsatisfiedLinkError` / `cannot locate symbol "ovr_…"` | overport's platform loader lacks Meta platform functions | `frame.ovrstubs` (automatic, generated stubs) |
 | missing `ovrMessageType_ToString` | same, but the game needs a real string | `frame.ovrplatformcompat` (automatic) |
+| The game stays in its built-in language or waits at start although its OBB / files hold language packs (`<tag>.lang`, e.g. `de.lang`) | overport's platform loader answers `ovr_LanguagePack_GetCurrent/SetCurrent` with request id 0, so the game never gets the pack's path | `frame.langpacks` (opt-in, experimental, shown for games whose data has `*.lang`; `native/langpack`, build it with `python native/build.py --only langpack`). Default pack: the one the game applies, else env `FRAMEPORT_LANGPACK=<tag>`, else the only pack; search path override `FRAMEPORT_LANGPACK_DIRS`. Unreal games (Deadpool VR) grey out a pack whose asset `Metadata` differs from the game's version string: the patch writes the APK's versionName as Metadata (env `FRAMEPORT_LANGPACK_META` overrides) and reports the pack under the `/storage/emulated/0/Android/obb/<pkg>/` spelling of its path; with `/sdcard/…` the text switched but the dialogue stayed silent (verified in the headset with Deadpool VR) |
 | `ClassNotFoundException com.oculus.os.AnalyticsEvent` → abort | Quest telemetry lookup in Meta XR Audio (Unreal build) or native code | `frame.metaxr_telemetry` + `frame.oculusos` (automatic) |
 | `JNI DETECTED ERROR`, `GetStringUTFChars … NULL` | CheckJNI is on because overport marks the app debuggable | `frame.nodebug` |
 | Unreal game quits a few seconds after start (`System.exit`) | ForceQuit after a failed Quest platform check | alternate build with `patch_remove_unreal_force_quit` (`use_alt`) |
@@ -47,14 +52,24 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Video stutters although fps is steady | video frame rate doesn't divide the refresh rate (30 fps at 72 Hz) | `adapter.refresh_rate` (e.g. 90 for 30 fps, 72 for 24 fps); `layer_debug` logs the offered rates and the app's own requests |
 | PC VR game judders/stutters although the GPU keeps up; vrcompositor.txt "Timed out. N total" high or frames dropped | the game misses the headset's refresh (e.g. 96 Hz = 10.4 ms; Stormland's slow frames take 10.7 ms) | `pcvr.steamvr_tuning` (default on): next Play sets SteamVR per-app `preferredRefreshRate` + `motionSmoothingOverride` via `fp_vrsettings.exe` |
 | Quest app keeps recentering / snapping the view when you turn your head; log shows session state 5→4→3→4→5 within a second | the Frame briefly takes focus; the app recenters on focus changes | unfixed: hiding the dips (debounce) made AC Nexus stay black, so it was removed |
-| Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | send files with Frame → Send files (~/Videos = /sdcard/Movies) and browse folders in the app |
+| 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 |
 | Game (Unity, GLES) freezes, `zink: DEVICE LOST` | multisampled render-to-texture hangs the GPU | `frame.unity_no_msaa`; if it persists: unfixable → PC version |
+| Only the Android home screen shows; the log has Unity's VR device as `None` (e.g. Accounting+, Unity 2017) | Unity 2017–2018 built-in Oculus support starts VR only when `com.oculus.systemactivities` is installed; Lepton has no Meta system apps, so Unity falls back to non-VR | `frame.unity_oculus_check`: that package name in libunity.so → `android`, plus `native/ovrpshim` (libfp_ovrp.so): Unity 2017's legacy frame loop (`ovrp_Update2`/`ovrp_BeginFrame`) never calls `ovrp_WaitToBeginFrame`, so without the shim no `xrWaitFrame` happens, `CompositorOpenXR::Update … outside of frame bounds` floods the log and the dashboard freezes. With it: log `ovrp frame loop shim: waited for frame N`, ~71 fps. Accounting+ then stops at "press any button" although its OVRInput gets clean input (`INPUT_PROBE` in the patch logs connected controllers/buttons/input focus per call) — unresolved |
+| Own-engine game crashes in `libVkLayer_fossilize.so` (Fossilize's recording thread, e.g. Roblox) | same as Deadpool VR: uninitialised pointers in what Fossilize records | `frame.vk_sanitize` now also covers own-engine libraries that load `libvulkan.so` by name |
+| Crash right after the game gets focus, in `vrclient.so … UpdateActionStateInternal` / `sxr_xrSyncActions` (e.g. Myst) | a race in the Frame runtime's input code on the first sync after focus (not every launch) | adapter `sync_guard` (input syncs one at a time with event polling, paused 250 ms after FOCUSED) |
+| View jumps sideways / game pauses or freezes for a moment every few seconds (e.g. Blade & Sorcery, BattleGlide) | the Frame drops focus for ~0.5 s (FOCUSED→VISIBLE→SYNCHRONIZED); games pause or re-align the player (`OnVRPresence … Teleport`) | adapter `focus_hold` |
+| SDL / LÖVE app crashes at start: `NullPointerException … ClipboardManager.addPrimaryClipChangedListener` in `SDLClipboardHandler.<init>` (e.g. Dramatic Shape) | Lepton's Android has no clipboard service (`service check clipboard`: not found) | `frame.sdl_clipboard` (that call → nops in classes.dex, in place, `apk/dex.py`); reproduced and verified with LÖVE for Android 11.5 |
+| Controllers do nothing (e.g. stuck on a setup screen); log: `xrSuggestInteractionProfileBindings … XR_ERROR_PATH_UNSUPPORTED` | the game only suggests bindings for Meta's newer profiles (Touch Plus / Touch Pro); the Frame's Android runtime knows `oculus/touch_controller`, not those | adapter `profile_remap` (default on): the bindings are suggested again for Touch (log: `controller profile … -> oculus/touch_controller`) |
+| Unity game hangs or the whole Frame restarts (e.g. in a menu); log: `The current MSAA level is 0, but the recommended MSAA level is 4. Switching to the recommended level.` (e.g. Lucky's Tale) | Meta's OVRManager (`useRecommendedMSAALevel`) turns 4x MSAA on at runtime, past QualitySettings; multisampled render-to-texture on GLES/Zink hangs the GPU | `frame.unity_runtime_msaa_off` (Cpp2IL: `OVRDisplay.get_recommendedMSAALevel` → 0) |
+| Unity game: one eye shows only effects or grey, the other is fine (e.g. I Am Cat, Oculus XR Plugin on GLES) | the game's single-pass multiview rendering goes wrong for array slice 1 (the adapter submits both slices correctly) | `frame.unity_multipass` (Cpp2IL: `OculusSettings.GetStereoRenderingMode` → MultiPass); `swap_eyes=1` tells whether the game or the adapter is at fault |
 | Setup/intro loops every launch (Espire 2) | save folders created without write permission | launcher repairs permissions every 2 s (built in) |
 | VrApi bridge: never enters VR | Frame reaches FOCUSED later than Quest; tracking only when worn | bridge waits 30 s; test in the headset |
 
 ## Picture problems (headset on)
 | Symptom | Cause | Fix |
 |---|---|---|
+| 2D Android app: Steam says it's running but nothing shows | Lepton runs apps headless unless the app folder has `lepton-show-flatscreen` | FramePort adds it for apps without VR (agent v28+); reinstall apps installed before |
+| 2D Android app: back/home/recents buttons cover the app's own buttons | Android's navigation bar | patch `device.hide_navbar` (on by default for apps without VR) sets `qemu.hw.mainkeys=1`; reinstall to apply |
 | Black screen, audio works, GLES engine with direct VrApi | Mesa rejects Quest-style GLSL | `frame.gl_shim` (logs `GLShim: SHADER COMPILE FAILED` + source lines) |
 | Black screen, audio works, log `Unsupported VrApi layer type N` | bridge drops frames containing that layer | extend the bridge (cylinder=3 is converted to a quad already) |
 | Only some draws visible (e.g. controllers) + `glGetError 0x502` | multiview shaders used on single-view FBOs | GL shim `gl_hide_multiview=1` (default) |
@@ -66,6 +81,12 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | MR game stuck waiting for room data (Demeter) | no Meta scene API | adapter `scene_emul=1` (+ `frame.meta_permissions`) |
 | Hand-tracking game janky (Silhouette) | Frame synthesizes hands from controllers | `controller_fix=0` passes hands through; not really fixable |
 | Eye distortion while moving (Arcsmith, Time Stall) | unknown (not eye swap, tracking, Valve layers, depth or pacing) | unresolved |
+| One eye grey / only effects (I Am Cat, Unity Oculus XR Plugin on GLES) | the game's multiview pass draws array slice 1 wrong on Zink | `frame.unity_multipass` (also rewrites the getter's inlined read in `OculusLoader.Initialize`; check for two `array=1` eye swapchains) |
+| View vibrates even when holding still after `frame.unity_multipass` (I Am Cat) | poses/times are consistent, but two passes on Zink make every frame one period late, and the game clamps its physics step to 10 ms | not fixed (scale 0.8 didn't help); next ideas: fix multiview instead, or the game's fixed timestep |
+| Game freezes / pauses for 1-2 s now and then, no flicker; only some games (Blade & Sorcery) | the headset's wear sensor flickers off while worn (SteamVR vrserver.txt `HMD off, stopping eye tracking` … `HMD on`), the Frame turns it into a focus loss and Quest games that pause on focus loss pause | adapter `focus_hold=1` + `focus_hold_ms=2500` per game; native games don't react, so it's per game |
+| Minor glitches on some objects (Myst, Unreal Vulkan) | unknown; not application space warp (turning it off changed nothing and ran worse) | unresolved |
+| Graphics crash in vkCreateInstance with pc == fault address, from the game's own Vulkan hooks (BONELAB `libSLZQuestNative`) | a pointer into memory freed with OVRPlugin's pre-init OpenXR instance; not the runtime (vrclient.so) or Fossilize being unloaded (keeping both loaded with RTLD_NODELETE didn't help) | unresolved |
+| Own-engine game crashes in `je_free` from its own library on the first frames (Roblox) | the game frees memory it doesn't own; not the Vulkan shim or the format fallback | unsupported |
 
 ## Debugging techniques that worked
 - A user's problem report: `frameport diag inspect <FramePort-diag-*.zip>` re-triages its launch log with the current
@@ -75,6 +96,31 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 - For GLES/GLAD engines, wrap `eglGetProcAddress` to see shader compile errors (build the shim with `-DGLSHIM_TRACE`
   for per-FBO draw counts and draw-call errors; the bridge has `-DOVP_GL_DIAG` for eye-image readback).
 - Anything visual needs one headset session per iteration — batch hypotheses into each build.
+- Headless launch tests never get focus: they prove startup, not play. Crashes right after FOCUSED (Myst), focus
+  dips and judder only show up in a headset session: ask for one, then `frameport diag collect <pkg>` (it contains
+  the headset sessions too, plus this boot's kernel log).
+- Which library a stale pointer belonged to: turn on the Android linker's log for one run by adding
+  `debug.ld.app.<pkg>=dlopen` as an extra line of `LEPTON_GFXRECON_FP_PROPS` (first line `0`) in the game's
+  launch.sh on the Frame (back it up, restore it after) and look for `dlclose: unloading "…"`.
+- Memory runaways / busy loops: `perf` works as steamos (`perf_event_paranoid` 2, user space only; `ptrace_scope` 1
+  blocks eu-stack/gdb/debuggerd). `perf record -p <pid> -e page-faults -c 64 --call-graph fp` names the thread
+  touching new memory (`perf script -F comm,tid,ip,dso`); `-t <tid> -F 499` samples one thread. Map IL2CPP
+  addresses with a full Cpp2IL diffable-cs dump (method `Offset` = address − the r-xp mapping of libil2cpp.so).
+  Sample memory per mapping name from `/proc/<pid>/smaps` (`[anon:libc_malloc]` = native heap).
+- Unity catches native crashes itself: no debuggerd backtrace in Lepton's logcat-crash.log, but a
+  `tombstone_00` in the game's `Android/data/<pkg>/files/` with the memory map (map pc/lr/registers to libraries).
+- Focus losses: the game sees FOCUSED→VISIBLE→SYNCHRONIZED (OVRPlugin `[XR_SESSION]`, FrameBridge `focus_hold:`
+  lines); the cause is on the host: `~/.local/share/Steam/logs/vrserver.txt` (`HMD off/on`, `entering standby`,
+  `SystemButtonDown` in vrclient_vrcompositor.txt) and XRService (`[UserPresence]`, `IMUFallback`). Compare the times
+  (Lepton logs UTC, host logs local time).
+- A Unity getter patch that changes nothing: the compiler may have inlined it (no `BL` to its address in
+  libil2cpp.so) — patch the field read in the caller (`Il2cppReturnPatch.field_loads`).
+- Fixes found by users count: a reporter's shader capture (VR4) became the `vk_shader_fix` recipe data (match by size
+  + SHA-256, insert words); verify on the device that the log shows the module being fixed.
+- Don't install or test on the Frame while the owner is playing: adding a library entry restarts Steam (FramePort
+  now skips the restart when the shortcut is unchanged and waits while a game runs), and a launch test starts a game.
+- Catalog YAML: a `: ` inside an unquoted value breaks the file and the loader skipped it silently (the game vanished
+  from the list); `tests/test_catalog_files.py` now catches it.
 - Keep the known-good APK and roll back if a change regresses (`PATCHED/_known-good-*`).
 
 ## When it can't run on the Frame

docs/STYLE.md

@@ -0,0 +1,28 @@
+# Writing style for FramePort's interface
+
+Short rules so every screen, help text and doc sounds the same. Code style is enforced by `ruff`.
+
+## Words
+- **Steam Frame** on first mention in a screen or document, **the Frame** after that. **Headset** only for the
+  physical device you wear ("put the headset on").
+- **Quest game** for Meta Quest apps, **Android app** for ordinary Android apps, **PC VR game** for Windows VR games.
+  Say Oculus or Rift only for games that use Oculus's own SDK.
+- **Patch** for anything in a game's patch list (never "fix" for the same thing). **Recipe** for a game's chosen
+  patches and settings.
+- Tools by their names: OVRPort, Revive, Proton, Lepton, SteamVR.
+- **Install** (first time), **Update** (a newer build), **Reinstall** (the same build again); **Play** starts a game.
+
+## Form
+- Buttons and headings in sentence case ("Add games", "Report a problem…"); one label per action everywhere.
+- "…" at the end of a label when the action asks for more input (a dialog, a file picker).
+- Sentences end with a period, including tooltips and help texts; labels don't.
+- "and", not "&", in text. An em dash (—) for asides, a middle dot (·) between short facts.
+- Sizes in GiB/MiB (`i18n.fmt_size`), dates as YYYY-MM-DD HH:MM (`i18n.fmt_datetime`).
+- US spelling (customize, analyze, color).
+- Plain, technical wording: say what happens ("Steam restarts once"), no marketing adjectives.
+
+## Translations
+- Every text the GUI shows goes through `tr("…")` or `tr_n("…", "…", n)` (see `src/frameport/i18n.py`); use
+  templates with `.format()`, never f-strings inside `tr()`, and never decide anything from a displayed text.
+- After changing texts run `python scripts/i18n_extract.py` (a test checks the template is current).
+- CLI output, logs, diagnostics, catalog notes and launch-test diagnoses stay English.

native/README.md

@@ -10,6 +10,7 @@ embeds debug paths (`-g`) and the dex depends on the d8 version, so those differ
 | `adapter/` | `{arm64-v8a,armeabi-v7a}/libopenxr_loader_generic.so` | **FrameBridge**: replaces overport's generic loader (which is renamed `libopenxr_loader_original.so`) and fixes Steam Frame runtime gaps. Hooks xrCreateInstance, swapchains, xrEndFrame, spaces, xrPollEvent, … everything else is forwarded by `gen_forwarders.py`-generated tail calls. `scene_emu.c` = Meta scene/spatial-entity emulation; `flip_vk.c` = Vulkan blit for VERTICAL_FLIP quads. `session_fixes.c` = per-game session fixes, all off by default and hooked only when on (`layer_debug` diagnostics, `stable_local`, `focus_hold`, aim correction `aim_pitch/aim_yaw/aim_forward`, `refresh_rate`); `layer_emul_gl.c` = `equirect_emul` (GLES sessions only): 360° equirect/equirect2 layers become one adapter projection layer, drawn by a worker thread with its own EGL context shared with the app's: each 360° image is converted to a cube map only when it changes, and the view is redrawn only after a 4° head turn (GL/EGL resolved with dlopen, so Vulkan games never load them); `layer_math.h` = their pose/face math, tested on the host by `tests/test_layer_emul.py`. `render_model.c` = XR_FB_render_model emulation (setting `controller_models`, off by default): serves `files/framebridge/controller_{left,right}.glb`, which the agent converts on the Frame from SteamVR's own Frame controller render models (never shipped by FramePort); tested on the host by `tests/test_render_model.py`. Settings: `libframe_settings.so` in the APK + `settings.conf`/`framebridge.conf` on the Frame. |
 | `vrapi-bridge/` | `arm64-v8a/libvrapi.so` | VrApi → OpenXR bridge from [Android-XR-Bridge/OVRPort](https://github.com/Android-XR-Bridge/OVRPort) `native/vrapi` at 5e7df52 (GPL-3.0, `LICENSE.upstream`; unchanged upstream as of OVRPort v1.2.5, which ships the unpatched code as its opt-in `patch_vrapi_openxr` in experimental CLI builds), with our changes in `upstream-patches/`: GLES sessions + GL texture swapchains, cylinder→quad layers, GL vertical flip, UNORM↔sRGB format twins, 30 s VR-mode deadline, VALID-only recenter, loading-icon layers skipped, diagnostics behind `-DOVP_GL_DIAG`. |
 | `platformcompat/` | `arm64-v8a/libovrplatformcompat.so` | Real `ovrMessageType_ToString` (same fork, `native/platform`). |
+| `langpack/` | `arm64-v8a/libfp_langpack.so` | Language packs for the Meta Platform SDK (patch `frame.langpacks`, opt-in). overport's platform loader is a dispatcher in front of Meta's own loader and answers `ovr_LanguagePack_GetCurrent/SetCurrent` with `return 0` (no reply ever). This library becomes the loader's first DT_NEEDED; the loader's own exports of the 31 functions it defines are made STB_LOCAL in `.dynsym` (`elf.hide_exports`, nothing moves), so symbol lookups reach the library first. It serves `<tag>.lang` files found in the game's OBB / app files (`$FRAMEPORT_LANGPACK_DIRS` overrides the search path) through `ovr_LanguagePack_*`, `ovr_AssetFile_GetList` (the loader's list + the packs) and `ovr_AssetFile_StatusById`; its own message queue is merged into `ovr_PopMessage`, and every handle that is not ours (an address-range check) goes to the loader's original function, whose address is read at run time from the loader's in-memory `.dynsym`. Host-tested against a stand-in loader (`tests/test_langpack.py`, plain `cc`, no NDK); the bionic/headset side is unverified. |
 | `glshim/` | `arm64-v8a/libglshim.so` | Mesa GLSL compatibility for GLAD engines (hooks eglGetProcAddress): comments out `#pragma` before `#extension`, enables `GL_EXT_shader_implicit_conversions`, hides GL_OVR_multiview (`gl_hide_multiview`, default 1) and logs failed shaders. `-DGLSHIM_TRACE` adds per-FBO draw/error tracing. |
 | `xrlayer/` | `linux-arm64/libxr_frameport_timefix.so` + `XR_APILAYER_FRAMEPORT_timefix.json` | OpenXR API layer for Windows PC VR games under Proton on the Frame (glibc aarch64, built freestanding with the NDK's clang), on by default (patch `pcvr.xr_timefix`). Retries `xrCreateInstance` as an OpenXR 1.0 app when the runtime rejects 1.1 (the Frame's SteamVR runtime does, and Proton 11's VR helper asks for 1.1). Also emulates `xrConvertTimespecTimeToTimeKHR`/`xrConvertTimeToTimespecTimeKHR` if the runtime refuses them (the Frame's Android runtime does; its Linux runtime, used by Proton, supports them as of 2026-09-29 — so this part is only a fallback; Proton's wineopenxr needs them for `XR_KHR_win32_convert_performance_counter_time`, which Revive requires) with the adapter's xrWaitFrame-calibrated offset, and drops the extension from xrCreateInstance if the runtime rejects it. Enabled per game by the Proton launch.sh (`XR_API_LAYER_PATH`, `XR_ENABLE_API_LAYERS`). `tests/test_xrlayer.py` builds it for x86_64 and drives it via ctypes. |
 | `oculushmd/` | `win-x64/fp_oculushmd.exe` | PC VR counterpart of overport's `patch_oculus_unreal` (patch `pcvr.oculus_unreal`, default for Unreal Rift games on the Frame). Unreal's OculusHMD and LibOVR's `ovr_Detect` only start when the Windows named event `OculusHMDConnected` exists and is signalled (the Oculus service creates it). `fp_oculushmd.exe <command line>` creates it (manual reset, signalled), runs the command (Revive's injector) in a job object and keeps the event until every process in the job — the game and its children — has exited (fallback without job support: 3 minutes); returns the command's exit code and logs `FramePort oculushmd: …` to stderr (launch.log). Freestanding Windows x64 console exe (no CRT, no Windows SDK): the NDK's clang + `lld-link /Brepro` with a kernel32 import library generated by `llvm-dlltool`, so it's byte-reproducible. Tested on Windows from WSL with a build whose event name is `-DEVENT_NAME=L"…"` (the Oculus service owns the real event on a PC with the Oculus app). |

native/adapter/eye_debug.c

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Included by frame_adapter.c (after flip_vk.c). Per-game diagnostics for "one eye looks wrong" reports
+// (eye_debug=1; everything also goes to framebridge.log in the app's external files folder):
+//  * every frame's projection layer: each eye's submitted pose vs. a fresh xrLocateViews at the frame's display time
+//    (game-side pose errors), the left/right eye relation (eye distance, relative rotation: must stay constant),
+//    and how long before xrEndFrame each eye's image was released (images handed over too early/late);
+//    summarised every 5 s, the first frames in full.
+//  * release_wait: before an image is released, wait for the app's GPU work on the session's queue (Vulkan) or
+//    glFinish (GLES), for games that release images whose rendering hasn't finished. 2 = only after the first 60 s
+//    of frames, so one headset session compares both (log "release_wait now ON").
+
+#define EYE_TRACKED 16
+
+static struct { XrSwapchain handle; int64_t released_ns; } eye_released[EYE_TRACKED];
+static pthread_mutex_t eye_lock = PTHREAD_MUTEX_INITIALIZER;
+static int64_t eye_first_frame_ns;
+
+static int release_wait_active(void) {
+    if (release_wait == 1) return 1;
+    if (release_wait != 2 || !eye_first_frame_ns) return 0;
+    static int announced;
+    int on = monotonic_ns() - eye_first_frame_ns > 60000000000ll;
+    if (on && !announced++) LOG("eye_debug: release_wait now ON (A/B: the first 60 s ran without it)");
+    return on;
+}
+
+static void eye_wait_for_gpu(void) {
+    if (vk.device) {
+        static PFN_vkQueueWaitIdle wait_idle;
+        if (!wait_idle && vk_ready()) wait_idle = (PFN_vkQueueWaitIdle)vk.GetDeviceProcAddr(vk.device, "vkQueueWaitIdle");
+        if (wait_idle && vk.queue) wait_idle(vk.queue);
+    } else {
+        static void (*finish)(void);
+        if (!finish) finish = (void (*)(void))dlsym(RTLD_DEFAULT, "glFinish");
+        if (finish) finish();
+    }
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL eye_hook_xrReleaseSwapchainImage(XrSwapchain swapchain,
+                                                                       const XrSwapchainImageReleaseInfo *info) {
+    PFN_xrReleaseSwapchainImage fn = (PFN_xrReleaseSwapchainImage)lookup(active_instance, "xrReleaseSwapchainImage");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (release_wait_active()) eye_wait_for_gpu();
+    XrResult result = fn(swapchain, info);
+    if (eye_debug) {
+        int64_t now = monotonic_ns();
+        pthread_mutex_lock(&eye_lock);
+        int slot = -1;
+        for (int i = 0; i < EYE_TRACKED && slot < 0; ++i)
+            if (eye_released[i].handle == swapchain) slot = i;
+        for (int i = 0; i < EYE_TRACKED && slot < 0; ++i)
+            if (!eye_released[i].handle) slot = i;
+        if (slot < 0) slot = (int)(now % EYE_TRACKED);
+        eye_released[slot].handle = swapchain;
+        eye_released[slot].released_ns = now;
+        pthread_mutex_unlock(&eye_lock);
+    }
+    return result;
+}
+
+static int64_t eye_release_age_ns(XrSwapchain swapchain, int64_t now) {
+    int64_t age = -1;
+    pthread_mutex_lock(&eye_lock);
+    for (int i = 0; i < EYE_TRACKED; ++i)
+        if (eye_released[i].handle == swapchain) age = now - eye_released[i].released_ns;
+    pthread_mutex_unlock(&eye_lock);
+    return age;
+}
+
+static float eye_angle_deg(XrQuaternionf a, XrQuaternionf b) {
+    float d = fabsf(a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w);
+    return d >= 1.0f ? 0.0f : 2.0f * acosf(d) * 57.29578f;
+}
+
+static float eye_dist_mm(XrVector3f a, XrVector3f b) {
+    float x = a.x - b.x, y = a.y - b.y, z = a.z - b.z;
+    return sqrtf(x * x + y * y + z * z) * 1000.0f;
+}
+
+static void eye_debug_end_frame(XrSession session, const XrFrameEndInfo *info) {
+    if (!info) return;
+    const XrCompositionLayerProjection *proj = NULL;
+    for (uint32_t i = 0; i < info->layerCount && !proj; ++i)
+        if (info->layers[i] && info->layers[i]->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
+            ((const XrCompositionLayerProjection *)info->layers[i])->viewCount == 2)
+            proj = (const XrCompositionLayerProjection *)info->layers[i];
+    if (!proj) return;
+    int64_t now = monotonic_ns();
+    if (!eye_first_frame_ns) eye_first_frame_ns = now;
+    static struct {
+        int frames, located;
+        float pos_err[2], rot_err[2], pos_err_max[2], rot_err_max[2];  // submitted vs. fresh, per eye
+        float ipd_min, ipd_max, rel_rot_max, step_max[2];               // eye relation; frame-to-frame jump per eye
+        float age_min[2], age_max[2];                                   // ms from release to xrEndFrame
+        int64_t window;
+    } st;
+    static XrPosef last[2];
+    static int have_last;
+    static int detailed;
+    if (!st.window) { st.window = now; st.ipd_min = 1e9f; st.age_min[0] = st.age_min[1] = 1e9f; }
+    // a fresh location of the same views at the frame's display time, in the layer's space
+    XrView fresh[2] = {{XR_TYPE_VIEW, NULL}, {XR_TYPE_VIEW, NULL}};
+    XrViewState vs = {XR_TYPE_VIEW_STATE, NULL};
+    uint32_t n = 0;
+    PFN_xrLocateViews locate = (PFN_xrLocateViews)lookup(active_instance, "xrLocateViews");
+    XrViewLocateInfo li = {XR_TYPE_VIEW_LOCATE_INFO, NULL, XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO, info->displayTime,
+                           proj->space};
+    int located = locate && XR_SUCCEEDED(locate(session, &li, &vs, 2, &n, fresh)) && n == 2 &&
+                  (vs.viewStateFlags & XR_VIEW_STATE_POSITION_VALID_BIT);
+    const XrCompositionLayerProjectionView *v = proj->views;
+    float ipd = eye_dist_mm(v[0].pose.position, v[1].pose.position);
+    float rel = eye_angle_deg(v[0].pose.orientation, v[1].pose.orientation);
+    ++st.frames;
+    if (ipd < st.ipd_min) st.ipd_min = ipd;
+    if (ipd > st.ipd_max) st.ipd_max = ipd;
+    if (rel > st.rel_rot_max) st.rel_rot_max = rel;
+    for (int e = 0; e < 2; ++e) {
+        int64_t age = eye_release_age_ns(v[e].subImage.swapchain, now);
+        float ms = age < 0 ? -1.0f : age / 1e6f;
+        if (ms < st.age_min[e]) st.age_min[e] = ms;
+        if (ms > st.age_max[e]) st.age_max[e] = ms;
+        if (located) {
+            float pe = eye_dist_mm(v[e].pose.position, fresh[e].pose.position);
+            float re = eye_angle_deg(v[e].pose.orientation, fresh[e].pose.orientation);
+            st.pos_err[e] += pe;
+            st.rot_err[e] += re;
+            if (pe > st.pos_err_max[e]) st.pos_err_max[e] = pe;
+            if (re > st.rot_err_max[e]) st.rot_err_max[e] = re;
+        }
+        if (have_last) {
+            float step = eye_angle_deg(last[e].orientation, v[e].pose.orientation);
+            if (step > st.step_max[e]) st.step_max[e] = step;
+        }
+        last[e] = v[e].pose;
+    }
+    have_last = 1;
+    if (located) ++st.located;
+    if (detailed < 4) {
+        ++detailed;
+        for (int e = 0; e < 2; ++e)
+            LOG("eye_debug: eye %d swapchain=%p rect=%d,%d %dx%d array=%u pos=%.4f,%.4f,%.4f rot=%.4f,%.4f,%.4f,%.4f "
+                "fov=%.3f/%.3f/%.3f/%.3f fresh pos=%.4f,%.4f,%.4f", e, (void *)(uintptr_t)v[e].subImage.swapchain,
+                v[e].subImage.imageRect.offset.x, v[e].subImage.imageRect.offset.y, v[e].subImage.imageRect.extent.width,
+                v[e].subImage.imageRect.extent.height, v[e].subImage.imageArrayIndex, v[e].pose.position.x,
+                v[e].pose.position.y, v[e].pose.position.z, v[e].pose.orientation.x, v[e].pose.orientation.y,
+                v[e].pose.orientation.z, v[e].pose.orientation.w, v[e].fov.angleLeft, v[e].fov.angleRight,
+                v[e].fov.angleUp, v[e].fov.angleDown, fresh[e].pose.position.x, fresh[e].pose.position.y,
+                fresh[e].pose.position.z);
+    }
+    if (now - st.window > 5000000000ll) {
+        int l = st.located ? st.located : 1;
+        LOG("eye_debug: %d frames | eye distance %.1f-%.1f mm, eye-to-eye rotation max %.2f deg | vs fresh pose: "
+            "L avg %.1f mm/%.2f deg max %.1f mm/%.2f deg, R avg %.1f mm/%.2f deg max %.1f mm/%.2f deg (%d located) | "
+            "largest frame step L %.2f R %.2f deg | release->end L %.1f-%.1f ms R %.1f-%.1f ms | release_wait %s",
+            st.frames, st.ipd_min, st.ipd_max, st.rel_rot_max, st.pos_err[0] / l, st.rot_err[0] / l, st.pos_err_max[0],
+            st.rot_err_max[0], st.pos_err[1] / l, st.rot_err[1] / l, st.pos_err_max[1], st.rot_err_max[1], st.located,
+            st.step_max[0], st.step_max[1], st.age_min[0], st.age_max[0], st.age_min[1], st.age_max[1],
+            release_wait_active() ? "on" : "off");
+        memset(&st, 0, sizeof(st));
+    }
+}

native/adapter/frame_adapter.c

@@ -45,12 +45,40 @@
 #include <string.h>
 
 #define TAG "FrameBridge"
-#define LOG(...) __android_log_print(ANDROID_LOG_INFO, TAG, __VA_ARGS__)
+#include <stdarg.h>
+#include <time.h>
+// Everything also goes to <app external files>/framebridge.log when eye_debug is on: some games end Lepton's logcat
+// mirror early (WiiCompiled), so a headset session's diagnostics would otherwise be lost.
+static FILE *log_file;
+static void fb_log(const char *fmt, ...) __attribute__((format(printf, 1, 2)));
+static void fb_log(const char *fmt, ...) {
+    va_list args;
+    va_start(args, fmt);
+    __android_log_vprint(ANDROID_LOG_INFO, TAG, fmt, args);
+    va_end(args);
+    if (!log_file) return;
+    struct timespec now;
+    clock_gettime(CLOCK_REALTIME, &now);
+    flockfile(log_file);
+    fprintf(log_file, "%lld.%03ld ", (long long)now.tv_sec, now.tv_nsec / 1000000);
+    va_start(args, fmt);
+    vfprintf(log_file, fmt, args);
+    va_end(args);
+    fputc('\n', log_file);
+    fflush(log_file);
+    funlockfile(log_file);
+}
+#define LOG(...) fb_log(__VA_ARGS__)
 
 static void *loader;
 static PFN_xrGetInstanceProcAddr next_gipa;
 static pthread_once_t init_once = PTHREAD_ONCE_INIT;
 static XrInstance active_instance = XR_NULL_HANDLE;
+static void *android_vm;     // JavaVM from XrInstanceCreateInfoAndroidKHR (surface_swapchain.c)
+static int surface_emul = 1;  // setting: emulate Android surface swapchains
+static int eye_debug;          // setting: per-eye diagnostics + file log (eye_debug.c)
+static int release_wait;       // setting: wait for the app's GPU work before releasing images (2 = after 60 s: A/B)
+static void surf_on_destroy(XrSwapchain handle);
 
 static float scale = 1.0f;
 static int foveation_fix = 1;
@@ -76,9 +104,12 @@ static int no_equirect, no_equirect2, no_cylinder, no_cube;
 static int runtime_has_fb_passthrough, emulate_passthrough, alpha_blend_failed;
 static int controller_models;  // serve Frame controller models via XR_FB_render_model (render_model.c)
 // Per-game settings, all off by default (session_fixes.c, layer_emul_gl.c).
+static int sync_guard;       // xrSyncActions one at a time with xrPollEvent, paused briefly after focus returns
+static int profile_remap = 1; // Meta's newer controller profiles (rejected by the Frame) -> oculus/touch_controller
 static int layer_debug;      // diagnostics: layers, swapchains, session states, spaces, aim/grip, refresh rates
 static int stable_local;     // keep every LOCAL space the app creates on the session-start origin
 static int focus_hold;       // hide brief focus dips once the session has been focused for a while
+static float focus_hold_ms = 1000;  // longest focus dip focus_hold hides
 static float aim_pitch, aim_yaw, aim_forward;  // aim pose correction (degrees, degrees, metres)
 static float refresh_rate;   // requested display refresh rate (Hz), 0 = the app's choice
 static int equirect_emul;    // show 360 layers as cube faces (GLES)
@@ -115,8 +146,14 @@ static void read_settings(const char *path) {
         if (sscanf(line, "scene_depth=%f", &value) == 1 && value > 0.5f && value < 20.0f) scene_depth = value;
         if (sscanf(line, "controller_models=%f", &value) == 1) controller_models = value != 0;
         if (sscanf(line, "layer_debug=%f", &value) == 1) layer_debug = value != 0;
+        if (sscanf(line, "surface_emul=%f", &value) == 1) surface_emul = value != 0;
+        if (sscanf(line, "eye_debug=%f", &value) == 1) eye_debug = value != 0;
+        if (sscanf(line, "release_wait=%f", &value) == 1) release_wait = (int)value;
+        if (sscanf(line, "profile_remap=%f", &value) == 1) profile_remap = value != 0;
+        if (sscanf(line, "sync_guard=%f", &value) == 1) sync_guard = value != 0;
         if (sscanf(line, "stable_local=%f", &value) == 1) stable_local = value != 0;
         if (sscanf(line, "focus_hold=%f", &value) == 1) focus_hold = value != 0;
+        if (sscanf(line, "focus_hold_ms=%f", &value) == 1 && value >= 100 && value <= 5000) focus_hold_ms = value;
         if (sscanf(line, "aim_pitch=%f", &value) == 1 && fabsf(value) <= 90) aim_pitch = value;
         if (sscanf(line, "aim_yaw=%f", &value) == 1 && fabsf(value) <= 90) aim_yaw = value;
         if (sscanf(line, "aim_forward=%f", &value) == 1 && fabsf(value) <= 0.5f) aim_forward = value;
@@ -163,6 +200,12 @@ static void initialize(void) {
     }
     const char *env = getenv("FRAMEBRIDGE_CONFIG");
     if (env && *env) read_settings(env);
+    if (eye_debug && *process && !strchr(process, '/')) {
+        snprintf(path, sizeof(path), "/sdcard/Android/data/%s/files/framebridge.log", process);
+        log_file = fopen(path, "a");
+    }
+    if (eye_debug || release_wait) LOG("per-game: eye_debug=%d release_wait=%d log_file=%s", eye_debug, release_wait,
+                                       log_file ? path : "none");
     if (controller_models && *process && !strchr(process, '/')) render_model_init(process);
 
     LOG("scale=%.2f foveation_fix=%d controller_fix=%d swapchain_fix=%d layer_fix=%d mutable_fix=%d swap_eyes=%d passthrough_emul=%d respace_kick=%d flip_quads=%d controller_models=%d loader=%s",
@@ -193,7 +236,10 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
 
     int chained = 0, enabled = 0;
     for (const XrBaseInStructure *p = (const XrBaseInStructure *)info->next; p; p = p->next)
-        if (p->type == XR_TYPE_INSTANCE_CREATE_INFO_ANDROID_KHR) chained = 1;
+        if (p->type == XR_TYPE_INSTANCE_CREATE_INFO_ANDROID_KHR) {
+            chained = 1;
+            android_vm = ((const struct { XrStructureType type; const void *next; void *vm; void *activity; } *)p)->vm;
+        }
     for (uint32_t i = 0; i < info->enabledExtensionCount; ++i)
         if (!strcmp(info->enabledExtensionNames[i], "XR_KHR_android_create_instance")) enabled = 1;
 
@@ -414,6 +460,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrDestroySwapchain(XrSwapchain swapchain) {
     PFN_xrDestroySwapchain fn = (PFN_xrDestroySwapchain)lookup(active_instance, "xrDestroySwapchain");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
     forget_swapchain(swapchain);
+    surf_on_destroy(swapchain);
     flip_on_destroy(swapchain);
     emul_on_destroy_swapchain(swapchain);
     if (equirect_emul && emul_is_virtual(swapchain)) { emul_virtual_destroy(swapchain); return XR_SUCCESS; }
@@ -667,6 +714,8 @@ XRAPI_ATTR XrResult XRAPI_CALL xrDestroySpace(XrSpace space) {
 
 #include "session_fixes.c"
 #include "layer_emul_gl.c"
+#include "surface_swapchain.c"
+#include "eye_debug.c"
 
 XRAPI_ATTR XrResult XRAPI_CALL xrCreateSession(XrInstance instance, const XrSessionCreateInfo *info, XrSession *session) {
     PFN_xrCreateSession fn = (PFN_xrCreateSession)lookup(instance, "xrCreateSession");
@@ -728,7 +777,13 @@ XRAPI_ATTR XrResult XRAPI_CALL xrPollEvent(XrInstance instance, XrEventDataBuffe
         pthread_mutex_unlock(&scene_lock);
         if (got) return XR_SUCCESS;
     }
+    if (sync_guard) pthread_mutex_lock(&sync_lock);
     XrResult result = focus_hold && event ? focus_hold_poll(fn, instance, event) : fn(instance, event);
+    if (sync_guard) {
+        if (result == XR_SUCCESS && event && session_state_of(event) == XR_SESSION_STATE_FOCUSED)
+            sync_resume_at = monotonic_ns() + SYNC_GUARD_PAUSE_NS;
+        pthread_mutex_unlock(&sync_lock);
+    }
     if (result == XR_SUCCESS && event && (layer_debug || stable_local)) {
         if (event->type == XR_TYPE_EVENT_DATA_SESSION_STATE_CHANGED && layer_debug)
             LOG("layer_debug: session state %d at %.3f", ((const XrEventDataSessionStateChanged *)event)->state,
@@ -852,6 +907,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrLocateViews(XrSession session, const XrViewLoca
 XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInfo *info) {
     PFN_xrEndFrame fn = (PFN_xrEndFrame)lookup(active_instance, "xrEndFrame");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (eye_debug) eye_debug_end_frame(session, info);
     {   // frame pacing statistics every ~5 s: fps and submitted-vs-predicted display time
         static struct timespec start;
         static int frames;
@@ -867,6 +923,12 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
         if (elapsed >= 5.0) {
             LOG("pacing: %.1f fps, displayTime vs predicted: avg %.2f ms, max %.2f ms", frames / elapsed,
                 drift_sum / (double)frames / 1e6, drift_max / 1e6);
+            if (layer_debug)
+                LOG("layer_debug: input: %d xrSyncActions (%d ok, last %d), %d bool reads, %d pressed",
+                    __atomic_exchange_n(&input_syncs, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&input_sync_ok, 0, __ATOMIC_RELAXED), input_last_sync_result,
+                    __atomic_exchange_n(&input_bool_reads, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&input_bool_true, 0, __ATOMIC_RELAXED));
             frames = 0; drift_sum = drift_max = 0;
         }
     }
@@ -951,6 +1013,13 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
                 continue;
             }
         }
+        if (layer && (layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD || layer->type == XR_TYPE_COMPOSITION_LAYER_CYLINDER_KHR) &&
+            !surf_prepare_layer(layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD
+                                    ? ((const XrCompositionLayerQuad *)layer)->subImage.swapchain
+                                    : ((const XrCompositionLayerCylinderKHR *)layer)->subImage.swapchain)) {
+            ++dropped;  // an emulated video surface without a frame yet
+            continue;
+        }
         if (!layer || (layer_fix && !layer_usable(layer))) { ++dropped; continue; }
         if (layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD) {
             const XrCompositionLayerQuad *flipped = flip_quad(session, (const XrCompositionLayerQuad *)layer, &quads[count]);
@@ -1079,6 +1148,18 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetCurrentInteractionProfile(XrSession session,
         (PFN_xrGetCurrentInteractionProfile)lookup(active_instance, "xrGetCurrentInteractionProfile");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
     XrResult result = fn(session, user, state);
+    if (layer_debug && active_instance) {  // which device each hand has, as the runtime reports it
+        PFN_xrPathToString str = (PFN_xrPathToString)lookup(active_instance, "xrPathToString");
+        char who[XR_MAX_PATH_LENGTH] = "?", what[XR_MAX_PATH_LENGTH] = "(none)";
+        uint32_t n = 0;
+        if (str) {
+            str(active_instance, user, sizeof(who), &n, who);
+            if (XR_SUCCEEDED(result) && state && state->interactionProfile)
+                str(active_instance, state->interactionProfile, sizeof(what), &n, what);
+        }
+        static int logged;
+        if (logged++ < 40) LOG("layer_debug: interaction profile of %s: %s (result %d)", who, what, result);
+    }
     if (!controller_fix || XR_FAILED(result) || !state || !state->interactionProfile || !active_instance)
         return result;
     PFN_xrPathToString to_string = (PFN_xrPathToString)lookup(active_instance, "xrPathToString");
@@ -1211,8 +1292,13 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
     if (layer_debug || refresh_rate > 0) {
         HOOK_AS(xrRequestDisplayRefreshRateFB, hook_request_refresh_rate)
     }
-    if (layer_debug || aim_correction_on()) {
+    if (surface_emul) HOOK_AS(xrCreateSwapchainAndroidSurfaceKHR, hook_xrCreateSwapchainAndroidSurfaceKHR)
+    if (eye_debug || release_wait) HOOK_AS(xrReleaseSwapchainImage, eye_hook_xrReleaseSwapchainImage)
+    if (sync_guard || layer_debug) HOOK_AS(xrSyncActions, hook_xrSyncActions)
+    if (layer_debug) HOOK_AS(xrGetActionStateBoolean, hook_xrGetActionStateBoolean)
+    if (layer_debug || aim_correction_on() || profile_remap)
         HOOK_AS(xrSuggestInteractionProfileBindings, hook_xrSuggestInteractionProfileBindings)
+    if (layer_debug || aim_correction_on()) {
         HOOK_AS(xrCreateActionSpace, hook_xrCreateActionSpace)
     }
 #undef HOOK_AS

native/adapter/session_fixes.c

@@ -95,9 +95,55 @@ static void debug_reference_space(XrSession session, const XrReferenceSpaceCreat
         LOG("layer_debug: that LOCAL space can't be located yet (no tracking)");
 }
 
+// ---------------------------------------------------------------- sync_guard
+// The Frame's runtime crashed in xrSyncActions right after focus returned (SIGSEGV in vrclient.so
+// CVRInputLatest::UpdateActionStateInternal, Myst; a race inside the runtime, not every launch). sync_guard runs
+// xrSyncActions one at a time with xrPollEvent and skips it for a moment after FOCUSED arrives (XR_SESSION_NOT_FOCUSED
+// is a success code every app handles: no input for those few frames).
+#define SYNC_GUARD_PAUSE_NS 250000000ll
+static pthread_mutex_t sync_lock = PTHREAD_MUTEX_INITIALIZER;
+static int64_t sync_resume_at;
+
+// layer_debug input counters, logged with the pacing line: were actions synced, did any button read as pressed?
+static int input_syncs, input_sync_ok, input_bool_reads, input_bool_true, input_last_sync_result;
+
+static XRAPI_ATTR XrResult XRAPI_CALL hook_xrSyncActions(XrSession session, const XrActionsSyncInfo *info) {
+    PFN_xrSyncActions fn = (PFN_xrSyncActions)lookup(active_instance, "xrSyncActions");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (!sync_guard) {  // installed for layer_debug only: count
+        XrResult r = fn(session, info);
+        __atomic_add_fetch(&input_syncs, 1, __ATOMIC_RELAXED);
+        if (r == XR_SUCCESS) __atomic_add_fetch(&input_sync_ok, 1, __ATOMIC_RELAXED);
+        input_last_sync_result = r;
+        return r;
+    }
+    pthread_mutex_lock(&sync_lock);
+    int64_t wait = sync_resume_at - monotonic_ns();
+    XrResult r = wait > 0 ? XR_SESSION_NOT_FOCUSED : fn(session, info);
+    pthread_mutex_unlock(&sync_lock);
+    static int logged;
+    if (wait > 0 && logged++ < 5) LOG("sync_guard: input paused for %.0f ms after focus returned", wait / 1e6);
+    return r;
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL hook_xrGetActionStateBoolean(XrSession session, const XrActionStateGetInfo *info,
+        XrActionStateBoolean *state) {
+    PFN_xrGetActionStateBoolean fn = (PFN_xrGetActionStateBoolean)lookup(active_instance, "xrGetActionStateBoolean");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    XrResult r = fn(session, info, state);
+    __atomic_add_fetch(&input_bool_reads, 1, __ATOMIC_RELAXED);
+    if (r == XR_SUCCESS && state && state->isActive && state->currentState)
+        __atomic_add_fetch(&input_bool_true, 1, __ATOMIC_RELAXED);
+    return r;
+}
+
 // ---------------------------------------------------------------- focus_hold
-#define FOCUS_HOLD_MIN_FOCUSED_NS 3000000000ll  // only after this long in FOCUSED (start-up transitions untouched)
-#define FOCUS_HOLD_MAX_DIP_NS 600000000ll       // dips longer than this are delivered (late, in order)
+#define FOCUS_HOLD_MIN_FOCUSED_NS 1000000000ll  // only after this long in FOCUSED (start-up transitions untouched;
+                                                // 3 s let a 27 ms dip through in Blade & Sorcery)
+// dips longer than focus_hold_ms (setting, default 1000) are delivered (late, in order): taking the headset off or the
+// system menu must still pause the game. A longer limit is for headsets whose wear sensor flickers ("HMD off" for
+// 0.5-2 s while worn; Blade & Sorcery pauses on each)
+#define FOCUS_HOLD_MAX_DIP_NS ((int64_t)(focus_hold_ms * 1000000.0f))
 static struct {
     XrEventDataBuffer events[6];
     int count, holding, delivering;
@@ -131,7 +177,7 @@ static XrResult focus_hold_poll(PFN_xrPollEvent fn, XrInstance instance, XrEvent
         if (result != XR_SUCCESS) {
             if (held.holding && now - held.since > FOCUS_HOLD_MAX_DIP_NS) {
                 LOG("focus_hold: focus lost for > %lld ms, delivering %d state change(s)",
-                    FOCUS_HOLD_MAX_DIP_NS / 1000000, held.count);
+                    (long long)(FOCUS_HOLD_MAX_DIP_NS / 1000000), held.count);
                 held.holding = 0; held.delivering = 1;
                 continue;
             }
@@ -195,20 +241,100 @@ static int pose_action_kind(XrAction action) {  // 1 aim, 0 grip, -1 unknown
     return kind;
 }
 
+// Meta's newer controller profiles, which the Frame's runtime doesn't know (it has oculus/touch_controller). An app
+// that suggests bindings only for these gets XR_ERROR_PATH_UNSUPPORTED and no input (e.g. a setup screen that can't be
+// passed); its bindings are suggested again for Touch, keeping the components Touch controllers have.
+static const char *const NEWER_TOUCH[] = {"/interaction_profiles/meta/touch_controller_plus",
+                                          "/interaction_profiles/meta/touch_plus_controller",
+                                          "/interaction_profiles/facebook/touch_controller_pro",
+                                          "/interaction_profiles/meta/touch_pro_controller",
+                                          "/interaction_profiles/meta/touch_controller_rift_cv1",
+                                          "/interaction_profiles/meta/touch_controller_quest_1_rift_s",
+                                          "/interaction_profiles/meta/touch_controller_quest_2"};
+static const char *const TOUCH_PROFILE = "/interaction_profiles/oculus/touch_controller";
+// oculus/touch_controller components (OpenXR spec), after /user/hand/<left|right>/
+static const char *const TOUCH_COMMON[] = {"input/squeeze/value", "input/trigger/value", "input/trigger/touch",
+    "input/thumbstick", "input/thumbstick/x", "input/thumbstick/y", "input/thumbstick/click",
+    "input/thumbstick/touch", "input/thumbrest/touch", "input/grip/pose", "input/aim/pose", "output/haptic"};
+static const char *const TOUCH_LEFT[] = {"input/x/click", "input/x/touch", "input/y/click", "input/y/touch",
+    "input/menu/click"};
+static const char *const TOUCH_RIGHT[] = {"input/a/click", "input/a/touch", "input/b/click", "input/b/touch",
+    "input/system/click"};
+static int app_suggested_touch;
+
+static int in_list(const char *s, const char *const *list, size_t n) {
+    for (size_t i = 0; i < n; ++i)
+        if (!strcmp(s, list[i])) return 1;
+    return 0;
+}
+#define IN(s, list) in_list(s, list, sizeof(list) / sizeof(*list))
+
+// 1 if the binding path exists on oculus/touch_controller
+static int touch_has(const char *path) {
+    const char *left = "/user/hand/left/", *right = "/user/hand/right/";
+    if (!strncmp(path, left, strlen(left))) {
+        path += strlen(left);
+        return IN(path, TOUCH_COMMON) || IN(path, TOUCH_LEFT);
+    }
+    if (!strncmp(path, right, strlen(right))) {
+        path += strlen(right);
+        return IN(path, TOUCH_COMMON) || IN(path, TOUCH_RIGHT);
+    }
+    return 0;
+}
+
+static XrResult remap_to_touch(XrInstance instance, PFN_xrSuggestInteractionProfileBindings fn,
+                               PFN_xrPathToString to_string, const XrInteractionProfileSuggestedBinding *suggested,
+                               const char *profile) {
+    PFN_xrStringToPath to_path = (PFN_xrStringToPath)lookup(instance, "xrStringToPath");
+    XrPath touch;
+    if (!to_path || XR_FAILED(to_path(instance, TOUCH_PROFILE, &touch))) return XR_ERROR_PATH_UNSUPPORTED;
+    uint32_t n = suggested->countSuggestedBindings, kept = 0;
+    XrActionSuggestedBinding *b = calloc(n ? n : 1, sizeof(*b));
+    if (!b) return XR_ERROR_OUT_OF_MEMORY;
+    for (uint32_t i = 0; i < n; ++i) {
+        char path[XR_MAX_PATH_LENGTH];
+        uint32_t size = 0;
+        if (XR_SUCCEEDED(to_string(instance, suggested->suggestedBindings[i].binding, sizeof(path), &size, path))
+                && touch_has(path))
+            b[kept++] = suggested->suggestedBindings[i];
+    }
+    XrInteractionProfileSuggestedBinding copy = *suggested;
+    copy.interactionProfile = touch;
+    copy.countSuggestedBindings = kept;
+    copy.suggestedBindings = b;
+    XrResult r = kept ? fn(instance, &copy) : XR_ERROR_PATH_UNSUPPORTED;
+    free(b);
+    LOG("controller profile %s -> oculus/touch_controller (%u bindings, %u dropped): %d", profile + 22, kept,
+        n - kept, r);
+    return r;
+}
+
 static XRAPI_ATTR XrResult XRAPI_CALL hook_xrSuggestInteractionProfileBindings(XrInstance instance,
         const XrInteractionProfileSuggestedBinding *suggested) {
     PFN_xrSuggestInteractionProfileBindings fn =
         (PFN_xrSuggestInteractionProfileBindings)lookup(instance, "xrSuggestInteractionProfileBindings");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
     PFN_xrPathToString to_string = (PFN_xrPathToString)lookup(instance, "xrPathToString");
-    if (suggested && to_string)
+    if (suggested && to_string && (layer_debug || aim_correction_on()))
         for (uint32_t i = 0; i < suggested->countSuggestedBindings; ++i) {
             char path[XR_MAX_PATH_LENGTH];
             uint32_t size = 0;
             if (XR_SUCCEEDED(to_string(instance, suggested->suggestedBindings[i].binding, sizeof(path), &size, path)))
                 note_pose_binding(suggested->suggestedBindings[i].action, path);
         }
-    return fn(instance, suggested);
+    XrResult r = fn(instance, suggested);
+    if (!profile_remap || !suggested || !to_string) return r;
+    char profile[XR_MAX_PATH_LENGTH] = {0};
+    uint32_t size = 0;
+    if (XR_FAILED(to_string(instance, suggested->interactionProfile, sizeof(profile), &size, profile))) return r;
+    if (!strcmp(profile, TOUCH_PROFILE)) {
+        if (XR_SUCCEEDED(r)) app_suggested_touch = 1;  // the app's own Touch bindings win over a remap
+        return r;
+    }
+    if (r != XR_ERROR_PATH_UNSUPPORTED || app_suggested_touch || !IN(profile, NEWER_TOUCH)) return r;
+    XrResult remapped = remap_to_touch(instance, fn, to_string, suggested, profile);
+    return XR_SUCCEEDED(remapped) ? XR_SUCCESS : r;
 }
 
 static XRAPI_ATTR XrResult XRAPI_CALL hook_xrCreateActionSpace(XrSession session, const XrActionSpaceCreateInfo *info,

native/adapter/surface_swapchain.c

@@ -0,0 +1,510 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Included by frame_adapter.c (after flip_vk.c and layer_emul_gl.c). Emulates XR_KHR_android_surface_swapchain,
+// which the Frame's runtime lists but answers with XR_ERROR_FUNCTION_UNSUPPORTED. Games use it to play a video on a
+// panel (OVROverlay "external surface", Android MediaPlayer/ExoPlayer drawing into a Surface): without it the panel has
+// no image and is dropped, and a game that waits for its intro video shows black forever (I Am Monkey).
+//
+//  * xrCreateSwapchainAndroidSurfaceKHR: the runtime first; if it can't, an ordinary runtime swapchain of the same size
+//    (sRGB RGBA8) is created and returned as the game's swapchain, and the game gets a real android.view.Surface from a
+//    SurfaceTexture owned by a worker thread (own EGL context; JNI through the JavaVM of xrCreateInstance).
+//  * The worker latches each new video frame (any size, YUV: SurfaceTexture samples it), draws it into an RGBA8
+//    texture of the swapchain's size and reads it back (glReadPixels) into a shared buffer.
+//  * xrEndFrame: a layer showing an emulated swapchain gets the newest frame uploaded first (Vulkan: staging buffer +
+//    copy on the session's queue; GLES: glTexSubImage2D in the app's context), then is submitted as usual.
+//  * Any failure: the call returns the runtime's own result (as before), so nothing gets worse.
+#include <jni.h>
+
+#define SURF_MAX 8
+
+typedef void *(*PFN_ASurfaceTexture_fromSurfaceTexture)(JNIEnv *, jobject);
+typedef int (*PFN_ASurfaceTexture_updateTexImage)(void *);
+typedef void (*PFN_ASurfaceTexture_getTransformMatrix)(void *, float[16]);
+typedef int64_t (*PFN_ASurfaceTexture_getTimestamp)(void *);
+typedef void (*PFN_ASurfaceTexture_release)(void *);
+
+#define surf_vm ((JavaVM *)android_vm)  // from XrInstanceCreateInfoAndroidKHR (frame_adapter.c)
+
+typedef struct {
+    int used;
+    XrSwapchain handle;
+    uint32_t width, height;
+    // worker
+    pthread_t thread;
+    int stop, ready, failed;  // ready: surface handed out; failed: worker gave up
+    jobject surface;          // global ref, returned to the game
+    // newest frame (RGBA8, top row first), written by the worker
+    uint8_t *pixels;
+    uint64_t seq;             // bumps with every new frame
+    int64_t frames;
+    // upload side (app render thread)
+    uint64_t uploaded_seq;
+    int uploads, upload_failures, has_content;
+    VkImage vk_images[MAX_IMAGES];
+    uint32_t gl_images[MAX_IMAGES];
+    uint32_t image_count;
+    VkBuffer staging;
+    VkDeviceMemory staging_memory;
+    void *staging_map;
+    VkCommandPool pool;  // own command buffer + fence: uploads never wait for the GPU in xrEndFrame
+    VkCommandBuffer cmd;
+    VkFence fence;
+    int in_flight;      // a copy was submitted and its fence not yet seen signalled
+} surf_swapchain;
+
+static pthread_mutex_t surf_lock = PTHREAD_MUTEX_INITIALIZER;
+static pthread_cond_t surf_cond = PTHREAD_COND_INITIALIZER;
+static surf_swapchain surfs[SURF_MAX];
+static int surf_vulkan;  // the session is Vulkan (else GLES)
+
+static surf_swapchain *surf_find(XrSwapchain handle) {
+    for (int i = 0; i < SURF_MAX; ++i)
+        if (surfs[i].used && surfs[i].handle == handle) return &surfs[i];
+    return NULL;
+}
+
+// ---------------------------------------------------------------- worker: SurfaceTexture -> RGBA pixels
+static const char *surf_vs = "#version 300 es\nout vec2 uv;\nvoid main() {\n"
+    "  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));\n"
+    "  uv = p; gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);\n}\n";
+// window row 0 (glReadPixels' first row) must hold the image's top: sample t = 1 - y (SurfaceTexture t=0 is the bottom)
+static const char *surf_fs = "#version 300 es\n#extension GL_OES_EGL_image_external_essl3 : require\n"
+    "precision mediump float;\nuniform samplerExternalOES tex;\nuniform mat4 st;\nin vec2 uv;\nout vec4 color;\n"
+    "void main() { color = texture(tex, (st * vec4(uv.x, 1.0 - uv.y, 0.0, 1.0)).xy); }\n";
+
+typedef void (*PFN_glReadPixels_)(GLint, GLint, GLsizei, GLsizei, GLenum, GLenum, void *);
+typedef void (*PFN_glTexParameteri_)(GLenum, GLenum, GLint);
+typedef void (*PFN_glUniformMatrix4fv_)(GLint, GLsizei, GLboolean, const GLfloat *);
+typedef void (*PFN_glPixelStorei_)(GLenum, GLint);
+typedef void (*PFN_glTexSubImage2D_)(GLenum, GLint, GLint, GLint, GLsizei, GLsizei, GLenum, GLenum, const void *);
+typedef EGLDisplay (*PFN_eglGetDisplay_)(EGLNativeDisplayType);
+typedef EGLBoolean (*PFN_eglInitialize_)(EGLDisplay, EGLint *, EGLint *);
+static PFN_glReadPixels_ s_glReadPixels;
+static PFN_glTexParameteri_ s_glTexParameteri;
+static PFN_glUniformMatrix4fv_ s_glUniformMatrix4fv;
+static PFN_glPixelStorei_ s_glPixelStorei;
+static PFN_glTexSubImage2D_ s_glTexSubImage2D;
+static PFN_eglGetDisplay_ s_eglGetDisplay;
+static PFN_eglInitialize_ s_eglInitialize;
+static PFN_ASurfaceTexture_fromSurfaceTexture s_ast_from;
+static PFN_ASurfaceTexture_updateTexImage s_ast_update;
+static PFN_ASurfaceTexture_getTransformMatrix s_ast_matrix;
+static PFN_ASurfaceTexture_getTimestamp s_ast_timestamp;
+static PFN_ASurfaceTexture_release s_ast_release;
+
+static int surf_load(void) {
+    static int state;  // 0 untried, 1 ok, -1 failed
+    if (state) return state > 0;
+    state = -1;
+    if (!emul_load_gl()) { LOG("surface_emul: EGL/GLES not available"); return 0; }
+    void *egl = dlopen("libEGL.so", RTLD_NOW | RTLD_LOCAL), *gles = dlopen("libGLESv3.so", RTLD_NOW | RTLD_LOCAL);
+    void *android = dlopen("libandroid.so", RTLD_NOW | RTLD_LOCAL);
+    if (!egl || !gles || !android) { LOG("surface_emul: libEGL/libGLESv3/libandroid missing"); return 0; }
+    s_glReadPixels = (PFN_glReadPixels_)dlsym(gles, "glReadPixels");
+    s_glTexParameteri = (PFN_glTexParameteri_)dlsym(gles, "glTexParameteri");
+    s_glUniformMatrix4fv = (PFN_glUniformMatrix4fv_)dlsym(gles, "glUniformMatrix4fv");
+    s_glPixelStorei = (PFN_glPixelStorei_)dlsym(gles, "glPixelStorei");
+    s_glTexSubImage2D = (PFN_glTexSubImage2D_)dlsym(gles, "glTexSubImage2D");
+    s_eglGetDisplay = (PFN_eglGetDisplay_)dlsym(egl, "eglGetDisplay");
+    s_eglInitialize = (PFN_eglInitialize_)dlsym(egl, "eglInitialize");
+    s_ast_from = (PFN_ASurfaceTexture_fromSurfaceTexture)dlsym(android, "ASurfaceTexture_fromSurfaceTexture");
+    s_ast_update = (PFN_ASurfaceTexture_updateTexImage)dlsym(android, "ASurfaceTexture_updateTexImage");
+    s_ast_matrix = (PFN_ASurfaceTexture_getTransformMatrix)dlsym(android, "ASurfaceTexture_getTransformMatrix");
+    s_ast_timestamp = (PFN_ASurfaceTexture_getTimestamp)dlsym(android, "ASurfaceTexture_getTimestamp");
+    s_ast_release = (PFN_ASurfaceTexture_release)dlsym(android, "ASurfaceTexture_release");
+    if (!s_glReadPixels || !s_glTexParameteri || !s_glUniformMatrix4fv || !s_glPixelStorei || !s_glTexSubImage2D ||
+        !s_eglGetDisplay || !s_eglInitialize || !s_ast_from || !s_ast_update || !s_ast_matrix || !s_ast_timestamp ||
+        !s_ast_release) {
+        LOG("surface_emul: a GL/EGL/ASurfaceTexture function is missing");
+        return 0;
+    }
+    state = 1;
+    return 1;
+}
+
+static void surf_fail(surf_swapchain *s, const char *why) {
+    LOG("surface_emul: %s", why);
+    pthread_mutex_lock(&surf_lock);
+    s->failed = 1;
+    pthread_cond_broadcast(&surf_cond);
+    pthread_mutex_unlock(&surf_lock);
+}
+
+static void *surf_worker(void *arg) {
+    surf_swapchain *s = arg;
+    JNIEnv *env = NULL;
+    if ((*surf_vm)->AttachCurrentThread(surf_vm, &env, NULL) != JNI_OK || !env) { surf_fail(s, "no JNI env"); return NULL; }
+    EGLDisplay dpy = s_eglGetDisplay(EGL_DEFAULT_DISPLAY);
+    EGLint cfg_attribs[] = {EGL_RENDERABLE_TYPE, 0x40 /* EGL_OPENGL_ES3_BIT */, EGL_SURFACE_TYPE, EGL_PBUFFER_BIT,
+                            EGL_RED_SIZE, 8, EGL_GREEN_SIZE, 8, EGL_BLUE_SIZE, 8, EGL_ALPHA_SIZE, 8, EGL_NONE};
+    EGLConfig config = NULL;
+    EGLint n = 0, ctx_attribs[] = {EGL_CONTEXT_CLIENT_VERSION, 3, EGL_NONE}, pb[] = {EGL_WIDTH, 16, EGL_HEIGHT, 16, EGL_NONE};
+    EGLContext ctx = EGL_NO_CONTEXT;
+    EGLSurface pbuf = EGL_NO_SURFACE;
+    void *ast = NULL;
+    jobject st_local = NULL, st_global = NULL;
+    GLuint ext_tex = 0, rgba_tex = 0, fbo = 0, vao = 0, program = 0;
+    if (dpy == EGL_NO_DISPLAY || !s_eglInitialize(dpy, NULL, NULL) || !p_eglChooseConfig(dpy, cfg_attribs, &config, 1, &n) ||
+        n < 1 || (ctx = p_eglCreateContext(dpy, config, EGL_NO_CONTEXT, ctx_attribs)) == EGL_NO_CONTEXT ||
+        (pbuf = p_eglCreatePbufferSurface(dpy, config, pb)) == EGL_NO_SURFACE || !p_eglMakeCurrent(dpy, pbuf, pbuf, ctx)) {
+        surf_fail(s, "EGL context failed");
+        goto out;
+    }
+    // the SurfaceTexture's external texture, and the RGBA target the frames are drawn into
+    p_glGenTextures(1, &ext_tex);
+    p_glBindTexture(0x8D65 /* GL_TEXTURE_EXTERNAL_OES */, ext_tex);
+    s_glTexParameteri(0x8D65, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
+    s_glTexParameteri(0x8D65, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
+    p_glGenTextures(1, &rgba_tex);
+    p_glBindTexture(GL_TEXTURE_2D, rgba_tex);
+    p_glTexStorage2D(GL_TEXTURE_2D, 1, GL_RGBA8, (GLsizei)s->width, (GLsizei)s->height);
+    p_glGenFramebuffers(1, &fbo);
+    p_glBindFramebuffer(GL_FRAMEBUFFER, fbo);
+    p_glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, rgba_tex, 0);
+    if (p_glCheckFramebufferStatus(GL_FRAMEBUFFER) != GL_FRAMEBUFFER_COMPLETE) { surf_fail(s, "framebuffer incomplete"); goto out; }
+    {
+        GLuint v = emul_compile(GL_VERTEX_SHADER, "", surf_vs), f = emul_compile(GL_FRAGMENT_SHADER, "", surf_fs);
+        if (!v || !f) { surf_fail(s, "shader compile failed"); goto out; }
+        program = p_glCreateProgram();
+        p_glAttachShader(program, v);
+        p_glAttachShader(program, f);
+        p_glLinkProgram(program);
+        GLint ok = 0;
+        p_glGetProgramiv(program, GL_LINK_STATUS, &ok);
+        if (!ok) { surf_fail(s, "program link failed"); goto out; }
+    }
+    p_glGenVertexArrays(1, &vao);
+    // android.graphics.SurfaceTexture(texName) + android.view.Surface(SurfaceTexture)
+    {
+        jclass st_class = (*env)->FindClass(env, "android/graphics/SurfaceTexture");
+        jclass surface_class = (*env)->FindClass(env, "android/view/Surface");
+        if (!st_class || !surface_class) { (*env)->ExceptionClear(env); surf_fail(s, "SurfaceTexture/Surface class missing"); goto out; }
+        jmethodID st_init = (*env)->GetMethodID(env, st_class, "<init>", "(I)V");
+        jmethodID st_size = (*env)->GetMethodID(env, st_class, "setDefaultBufferSize", "(II)V");
+        jmethodID surface_init = (*env)->GetMethodID(env, surface_class, "<init>", "(Landroid/graphics/SurfaceTexture;)V");
+        st_local = (*env)->NewObject(env, st_class, st_init, (jint)ext_tex);
+        if (!st_local || (*env)->ExceptionCheck(env)) { (*env)->ExceptionClear(env); surf_fail(s, "new SurfaceTexture failed"); goto out; }
+        (*env)->CallVoidMethod(env, st_local, st_size, (jint)s->width, (jint)s->height);
+        jobject surface_local = (*env)->NewObject(env, surface_class, surface_init, st_local);
+        if (!surface_local || (*env)->ExceptionCheck(env)) { (*env)->ExceptionClear(env); surf_fail(s, "new Surface failed"); goto out; }
+        st_global = (*env)->NewGlobalRef(env, st_local);
+        ast = s_ast_from(env, st_local);
+        if (!ast) { surf_fail(s, "ASurfaceTexture_fromSurfaceTexture failed"); goto out; }
+        pthread_mutex_lock(&surf_lock);
+        s->surface = (*env)->NewGlobalRef(env, surface_local);
+        s->ready = 1;
+        pthread_cond_broadcast(&surf_cond);
+        pthread_mutex_unlock(&surf_lock);
+        (*env)->DeleteLocalRef(env, surface_local);
+    }
+    LOG("surface_emul: Surface ready for %ux%u swapchain %p", s->width, s->height, (void *)(uintptr_t)s->handle);
+    {
+        GLint u_tex = p_glGetUniformLocation(program, "tex"), u_st = p_glGetUniformLocation(program, "st");
+        size_t bytes = (size_t)s->width * s->height * 4;
+        uint8_t *buf = malloc(bytes);
+        int64_t last_ts = -1, window_frames = 0, window_start = 0;
+        while (!s->stop && buf) {
+            struct timespec pause = {0, 8000000};  // ~120 checks a second: well above video frame rates
+            nanosleep(&pause, NULL);
+            if (s_ast_update(ast) != 0) continue;
+            int64_t ts = s_ast_timestamp(ast);
+            if (ts == last_ts) continue;  // no new frame latched
+            last_ts = ts;
+            float m[16];
+            s_ast_matrix(ast, m);
+            p_glBindFramebuffer(GL_FRAMEBUFFER, fbo);
+            p_glViewport(0, 0, (GLsizei)s->width, (GLsizei)s->height);
+            p_glUseProgram(program);
+            p_glActiveTexture(GL_TEXTURE0);
+            p_glBindTexture(0x8D65, ext_tex);
+            p_glUniform1i(u_tex, 0);
+            s_glUniformMatrix4fv(u_st, 1, GL_FALSE, m);
+            p_glBindVertexArray(vao);
+            p_glDrawArrays(GL_TRIANGLES, 0, 3);
+            s_glPixelStorei(GL_PACK_ALIGNMENT, 1);
+            s_glReadPixels(0, 0, (GLsizei)s->width, (GLsizei)s->height, GL_RGBA, GL_UNSIGNED_BYTE, buf);
+            GLenum err = p_glGetError();
+            pthread_mutex_lock(&surf_lock);
+            if (!err && s->pixels) { memcpy(s->pixels, buf, bytes); s->seq++; s->frames++; }
+            pthread_mutex_unlock(&surf_lock);
+            if (err) { static int warned; if (warned++ < 5) LOG("surface_emul: GL error 0x%x drawing a frame", err); }
+            int64_t now = monotonic_ns();
+            if (!window_start) {
+                window_start = now;
+                LOG("surface_emul: first video frame (timestamp %lld)", (long long)ts);
+            }
+            if (++window_frames && now - window_start > 5000000000ll) {
+                LOG("surface_emul: %.1f video frames/s, %d uploaded, %d upload failures", window_frames * 1e9 / (now - window_start),
+                    s->uploads, s->upload_failures);
+                window_frames = 0;
+                window_start = now;
+            }
+        }
+        free(buf);
+    }
+out:
+    if (ast) s_ast_release(ast);
+    if (st_global) (*env)->DeleteGlobalRef(env, st_global);
+    if (ctx != EGL_NO_CONTEXT) { p_eglMakeCurrent(dpy, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT); p_eglDestroyContext(dpy, ctx); }
+    if (pbuf != EGL_NO_SURFACE) p_eglDestroySurface(dpy, pbuf);
+    (*surf_vm)->DetachCurrentThread(surf_vm);
+    return NULL;
+}
+
+// ---------------------------------------------------------------- uploads (app render thread)
+static struct {
+    PFN_vkCreateBuffer CreateBuffer;
+    PFN_vkGetBufferMemoryRequirements GetBufferMemoryRequirements;
+    PFN_vkAllocateMemory AllocateMemory;
+    PFN_vkBindBufferMemory BindBufferMemory;
+    PFN_vkMapMemory MapMemory;
+    PFN_vkCmdCopyBufferToImage CmdCopyBufferToImage;
+    PFN_vkCmdClearColorImage CmdClearColorImage;
+    PFN_vkGetPhysicalDeviceMemoryProperties GetPhysicalDeviceMemoryProperties;
+    PFN_vkGetFenceStatus GetFenceStatus;
+    int state;
+} svk;
+
+static int surf_vk_ready(void) {
+    if (svk.state) return svk.state > 0;
+    svk.state = -1;
+    if (!vk_ready()) return 0;
+#define SDEV(name) svk.name = (PFN_vk##name)vk.GetDeviceProcAddr(vk.device, "vk" #name); if (!svk.name) return 0;
+    SDEV(CreateBuffer) SDEV(GetBufferMemoryRequirements) SDEV(AllocateMemory) SDEV(BindBufferMemory) SDEV(MapMemory)
+    SDEV(CmdCopyBufferToImage) SDEV(CmdClearColorImage) SDEV(GetFenceStatus)
+#undef SDEV
+    void *lib = dlopen("libvulkan.so", RTLD_NOW | RTLD_LOCAL);
+    PFN_vkGetInstanceProcAddr gipa = lib ? (PFN_vkGetInstanceProcAddr)dlsym(lib, "vkGetInstanceProcAddr") : NULL;
+    svk.GetPhysicalDeviceMemoryProperties = gipa ? (PFN_vkGetPhysicalDeviceMemoryProperties)gipa(vk.instance,
+        "vkGetPhysicalDeviceMemoryProperties") : NULL;
+    if (!svk.GetPhysicalDeviceMemoryProperties) return 0;
+    svk.state = 1;
+    return 1;
+}
+
+static void surf_barrier(VkCommandBuffer cmd, VkImage image, VkImageLayout from, VkImageLayout to,
+                         VkAccessFlags src_access, VkAccessFlags dst_access) {
+    VkImageMemoryBarrier b = {VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER, NULL, src_access, dst_access, from, to,
+                              VK_QUEUE_FAMILY_IGNORED, VK_QUEUE_FAMILY_IGNORED, image,
+                              {VK_IMAGE_ASPECT_COLOR_BIT, 0, 1, 0, 1}};
+    vk.CmdPipelineBarrier(cmd, VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, 0, 0, NULL, 0,
+                          NULL, 1, &b);
+}
+
+static int surf_staging(surf_swapchain *s) {
+    if (s->staging_map) return 1;
+    VkCommandPoolCreateInfo pool = {VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO, NULL,
+                                    VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT, vk.family};
+    if (vk.CreateCommandPool(vk.device, &pool, NULL, &s->pool) != VK_SUCCESS) return 0;
+    VkCommandBufferAllocateInfo alloc = {VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO, NULL, s->pool,
+                                         VK_COMMAND_BUFFER_LEVEL_PRIMARY, 1};
+    if (vk.AllocateCommandBuffers(vk.device, &alloc, &s->cmd) != VK_SUCCESS) return 0;
+    VkFenceCreateInfo fence = {VK_STRUCTURE_TYPE_FENCE_CREATE_INFO, NULL, 0};
+    if (vk.CreateFence(vk.device, &fence, NULL, &s->fence) != VK_SUCCESS) return 0;
+    VkBufferCreateInfo bi = {VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO, NULL, 0, (VkDeviceSize)s->width * s->height * 4,
+                             VK_BUFFER_USAGE_TRANSFER_SRC_BIT, VK_SHARING_MODE_EXCLUSIVE, 0, NULL};
+    if (svk.CreateBuffer(vk.device, &bi, NULL, &s->staging) != VK_SUCCESS) return 0;
+    VkMemoryRequirements req;
+    svk.GetBufferMemoryRequirements(vk.device, s->staging, &req);
+    VkPhysicalDeviceMemoryProperties props;
+    svk.GetPhysicalDeviceMemoryProperties(vk.physical, &props);
+    uint32_t want = VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, type = UINT32_MAX;
+    for (uint32_t i = 0; i < props.memoryTypeCount && type == UINT32_MAX; ++i)
+        if ((req.memoryTypeBits & (1u << i)) && (props.memoryTypes[i].propertyFlags & want) == want) type = i;
+    if (type == UINT32_MAX) return 0;
+    VkMemoryAllocateInfo ai = {VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO, NULL, req.size, type};
+    if (svk.AllocateMemory(vk.device, &ai, NULL, &s->staging_memory) != VK_SUCCESS) return 0;
+    if (svk.BindBufferMemory(vk.device, s->staging, s->staging_memory, 0) != VK_SUCCESS) return 0;
+    return svk.MapMemory(vk.device, s->staging_memory, 0, VK_WHOLE_SIZE, 0, &s->staging_map) == VK_SUCCESS;
+}
+
+// Copy the newest frame (or black, the first time) into the next image of the runtime swapchain. Returns 1 if the
+// swapchain now has an image to show, -1 if the previous copy is still running (try next frame), 0 on failure.
+static int surf_upload(surf_swapchain *s, int black) {
+    PFN_xrAcquireSwapchainImage acquire = (PFN_xrAcquireSwapchainImage)lookup(active_instance, "xrAcquireSwapchainImage");
+    PFN_xrWaitSwapchainImage wait = (PFN_xrWaitSwapchainImage)lookup(active_instance, "xrWaitSwapchainImage");
+    PFN_xrReleaseSwapchainImage release = (PFN_xrReleaseSwapchainImage)lookup(active_instance, "xrReleaseSwapchainImage");
+    if (!acquire || !wait || !release || !s->image_count) return 0;
+    uint32_t index = 0;
+    XrSwapchainImageAcquireInfo ai = {XR_TYPE_SWAPCHAIN_IMAGE_ACQUIRE_INFO, NULL};
+    XrSwapchainImageWaitInfo wi = {XR_TYPE_SWAPCHAIN_IMAGE_WAIT_INFO, NULL, 100000000};
+    XrSwapchainImageReleaseInfo ri = {XR_TYPE_SWAPCHAIN_IMAGE_RELEASE_INFO, NULL};
+    if (surf_vulkan && s->in_flight) {  // the previous copy still reads the staging buffer: try again next frame
+        if (svk.GetFenceStatus(vk.device, s->fence) != VK_SUCCESS) return -1;
+        vk.ResetFences(vk.device, 1, &s->fence);
+        s->in_flight = 0;
+    }
+    if (XR_FAILED(acquire(s->handle, &ai, &index)) || index >= s->image_count) return 0;
+    if (XR_FAILED(wait(s->handle, &wi))) { release(s->handle, &ri); return 0; }
+    int ok = 0;
+    size_t bytes = (size_t)s->width * s->height * 4;
+    if (surf_vulkan) {
+        if (!black) {
+            pthread_mutex_lock(&surf_lock);
+            memcpy(s->staging_map, s->pixels, bytes);
+            pthread_mutex_unlock(&surf_lock);
+        }
+        VkImage img = s->vk_images[index];
+        VkCommandBufferBeginInfo begin = {VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO, NULL,
+                                          VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT, NULL};
+        VkCommandBuffer cmd = s->cmd;
+        vk.ResetCommandBuffer(cmd, 0);
+        vk.BeginCommandBuffer(cmd, &begin);
+        surf_barrier(cmd, img, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 0, VK_ACCESS_TRANSFER_WRITE_BIT);
+        if (black) {
+            VkClearColorValue c = {{0, 0, 0, 1}};
+            VkImageSubresourceRange r = {VK_IMAGE_ASPECT_COLOR_BIT, 0, 1, 0, 1};
+            svk.CmdClearColorImage(cmd, img, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, &c, 1, &r);
+        } else {
+            VkBufferImageCopy copy = {0, 0, 0, {VK_IMAGE_ASPECT_COLOR_BIT, 0, 0, 1}, {0, 0, 0}, {s->width, s->height, 1}};
+            svk.CmdCopyBufferToImage(cmd, s->staging, img, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1, &copy);
+        }
+        surf_barrier(cmd, img, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
+                VK_ACCESS_TRANSFER_WRITE_BIT, VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT);
+        vk.EndCommandBuffer(cmd);
+        VkSubmitInfo submit = {VK_STRUCTURE_TYPE_SUBMIT_INFO, NULL, 0, NULL, NULL, 1, &cmd, 0, NULL};
+        // released right after the submit: the runtime's own work on this queue runs after the copy
+        ok = vk.QueueSubmit(vk.queue, 1, &submit, s->fence) == VK_SUCCESS;
+        s->in_flight = ok;
+    } else if (!black) {  // GLES: the app's context is current on its render thread (xrEndFrame)
+        GLint prev_tex = 0, prev_align = 4, prev_unpack = 0;
+        p_glGetIntegerv(GL_TEXTURE_BINDING_2D, &prev_tex);
+        p_glGetIntegerv(GL_UNPACK_ALIGNMENT, &prev_align);
+        p_glGetIntegerv(0x88EF /* GL_PIXEL_UNPACK_BUFFER_BINDING */, &prev_unpack);
+        if (prev_unpack) { typedef void (*bb)(GLenum, GLuint); static bb bind; if (!bind) bind = (bb)dlsym(RTLD_DEFAULT, "glBindBuffer"); if (bind) bind(0x88EC, 0); }
+        p_glBindTexture(GL_TEXTURE_2D, s->gl_images[index]);
+        s_glPixelStorei(GL_UNPACK_ALIGNMENT, 1);
+        pthread_mutex_lock(&surf_lock);
+        s_glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, (GLsizei)s->width, (GLsizei)s->height, GL_RGBA, GL_UNSIGNED_BYTE, s->pixels);
+        pthread_mutex_unlock(&surf_lock);
+        ok = p_glGetError() == GL_NO_ERROR;
+        s_glPixelStorei(GL_UNPACK_ALIGNMENT, prev_align);
+        p_glBindTexture(GL_TEXTURE_2D, (GLuint)prev_tex);
+        if (prev_unpack) { typedef void (*bb)(GLenum, GLuint); static bb bind; if (!bind) bind = (bb)dlsym(RTLD_DEFAULT, "glBindBuffer"); if (bind) bind(0x88EC, (GLuint)prev_unpack); }
+    }
+    release(s->handle, &ri);
+    return ok;
+}
+
+// xrEndFrame: before a layer showing an emulated swapchain is submitted. Returns 0 if it has nothing to show yet.
+static int surf_prepare_layer(XrSwapchain handle) {
+    pthread_mutex_lock(&surf_lock);
+    surf_swapchain *s = surf_find(handle);
+    uint64_t seq = s ? s->seq : 0;
+    pthread_mutex_unlock(&surf_lock);
+    if (!s) return 1;  // not ours
+    if (seq != s->uploaded_seq) {
+        int r = surf_upload(s, 0);
+        if (r > 0) { s->uploaded_seq = seq; s->uploads++; s->has_content = 1; }
+        else if (r == 0 && s->upload_failures++ < 5) LOG("surface_emul: upload failed (swapchain %p)", (void *)(uintptr_t)handle);
+    }
+    return s->has_content;
+}
+
+// ---------------------------------------------------------------- the emulated entry points
+typedef XrResult (XRAPI_PTR *PFN_xrCreateSwapchainAndroidSurfaceKHR_)(XrSession, const XrSwapchainCreateInfo *,
+                                                                      XrSwapchain *, jobject *);
+
+static XRAPI_ATTR XrResult XRAPI_CALL hook_xrCreateSwapchainAndroidSurfaceKHR(XrSession session,
+        const XrSwapchainCreateInfo *info, XrSwapchain *swapchain, jobject *surface) {
+    PFN_xrCreateSwapchainAndroidSurfaceKHR_ fn =
+        (PFN_xrCreateSwapchainAndroidSurfaceKHR_)lookup(active_instance, "xrCreateSwapchainAndroidSurfaceKHR");
+    XrResult result = fn ? fn(session, info, swapchain, surface) : XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (result != XR_ERROR_FUNCTION_UNSUPPORTED || !info || !swapchain || !surface) return result;
+    LOG("surface_emul: runtime has no Android surface swapchains: emulating %ux%u (vm %s, %s session)", info->width,
+        info->height, surf_vm ? "ok" : "MISSING", vk.device ? "Vulkan" : "GLES");
+    if (!surf_vm || !info->width || !info->height || !surf_load()) return result;
+    surf_vulkan = vk.device != VK_NULL_HANDLE;
+    if (surf_vulkan && !surf_vk_ready()) { LOG("surface_emul: Vulkan upload path unavailable"); return result; }
+    pthread_mutex_lock(&surf_lock);
+    surf_swapchain *s = NULL;
+    for (int i = 0; i < SURF_MAX && !s; ++i)
+        if (!surfs[i].used) s = &surfs[i];
+    if (s) { memset(s, 0, sizeof(*s)); s->used = 1; }
+    pthread_mutex_unlock(&surf_lock);
+    if (!s) { LOG("surface_emul: too many surface swapchains"); return result; }
+    // the runtime swapchain the game gets instead (what its layer will show)
+    PFN_xrCreateSwapchain create = (PFN_xrCreateSwapchain)lookup(active_instance, "xrCreateSwapchain");
+    PFN_xrEnumerateSwapchainImages enumerate =
+        (PFN_xrEnumerateSwapchainImages)lookup(active_instance, "xrEnumerateSwapchainImages");
+    PFN_xrDestroySwapchain destroy = (PFN_xrDestroySwapchain)lookup(active_instance, "xrDestroySwapchain");
+    XrSwapchainCreateInfo ci = {XR_TYPE_SWAPCHAIN_CREATE_INFO, NULL, 0,
+                                XR_SWAPCHAIN_USAGE_COLOR_ATTACHMENT_BIT | XR_SWAPCHAIN_USAGE_TRANSFER_DST_BIT |
+                                XR_SWAPCHAIN_USAGE_SAMPLED_BIT,
+                                surf_vulkan ? 43 /* VK_FORMAT_R8G8B8A8_SRGB */ : 0x8C43 /* GL_SRGB8_ALPHA8 */,
+                                1, info->width, info->height, 1, 1, 1};
+    XrSwapchain handle = XR_NULL_HANDLE;
+    XrResult cr = create && enumerate ? create(session, &ci, &handle) : XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (XR_FAILED(cr)) {
+        LOG("surface_emul: xrCreateSwapchain failed %d", cr);
+        pthread_mutex_lock(&surf_lock); s->used = 0; pthread_mutex_unlock(&surf_lock);
+        return result;
+    }
+    s->handle = handle;
+    s->width = info->width;
+    s->height = info->height;
+    s->pixels = calloc((size_t)s->width * s->height, 4);
+    uint32_t n = 0;
+    if (surf_vulkan) {
+        XrSwapchainImageVulkanKHR images[MAX_IMAGES];
+        for (int i = 0; i < MAX_IMAGES; ++i) images[i] = (XrSwapchainImageVulkanKHR){XR_TYPE_SWAPCHAIN_IMAGE_VULKAN_KHR, NULL, VK_NULL_HANDLE};
+        if (XR_SUCCEEDED(enumerate(handle, MAX_IMAGES, &n, (XrSwapchainImageBaseHeader *)images)))
+            for (uint32_t i = 0; i < n && i < MAX_IMAGES; ++i) s->vk_images[i] = images[i].image;
+    } else {
+        emul_gles_image images[MAX_IMAGES];
+        for (int i = 0; i < MAX_IMAGES; ++i) images[i] = (emul_gles_image){XR_TYPE_SWAPCHAIN_IMAGE_OPENGL_ES_KHR, NULL, 0};
+        if (XR_SUCCEEDED(enumerate(handle, MAX_IMAGES, &n, (XrSwapchainImageBaseHeader *)images)))
+            for (uint32_t i = 0; i < n && i < MAX_IMAGES; ++i) s->gl_images[i] = images[i].image;
+    }
+    s->image_count = n < MAX_IMAGES ? n : MAX_IMAGES;
+    int setup_ok = s->pixels && s->image_count && (!surf_vulkan || surf_staging(s));
+    if (setup_ok) {
+        pthread_mutex_lock(&surf_lock);
+        setup_ok = pthread_create(&s->thread, NULL, surf_worker, s) == 0;
+        struct timespec until;
+        clock_gettime(CLOCK_REALTIME, &until);
+        until.tv_sec += 3;
+        while (setup_ok && !s->ready && !s->failed && pthread_cond_timedwait(&surf_cond, &surf_lock, &until) == 0) {}
+        setup_ok = setup_ok && s->ready;
+        pthread_mutex_unlock(&surf_lock);
+    }
+    if (!setup_ok) {
+        LOG("surface_emul: setup failed (images %u, pixels %d): the panel stays empty", s->image_count, s->pixels != NULL);
+        if (s->thread) { s->stop = 1; pthread_join(s->thread, NULL); }
+        if (destroy) destroy(handle);
+        free(s->pixels);
+        pthread_mutex_lock(&surf_lock); s->used = 0; pthread_mutex_unlock(&surf_lock);
+        return result;
+    }
+    // something valid to show from the first frame on (Vulkan: a black image; GLES: the layer waits for a frame)
+    if (surf_vulkan && surf_upload(s, 1) > 0) s->has_content = 1;
+    remember_swapchain(handle);
+    *swapchain = handle;
+    *surface = s->surface;
+    LOG("surface_emul: emulated Android surface swapchain %p (%u images)", (void *)(uintptr_t)handle, s->image_count);
+    return XR_SUCCESS;
+}
+
+// xrDestroySwapchain: an emulated swapchain's worker and surface go with it
+static void surf_on_destroy(XrSwapchain handle) {
+    pthread_mutex_lock(&surf_lock);
+    surf_swapchain *s = surf_find(handle);
+    pthread_mutex_unlock(&surf_lock);
+    if (!s) return;
+    s->stop = 1;
+    if (s->thread) pthread_join(s->thread, NULL);
+    if (surf_vm && s->surface) {
+        JNIEnv *env = NULL;
+        int attached = 0;
+        if ((*surf_vm)->GetEnv(surf_vm, (void **)&env, JNI_VERSION_1_6) != JNI_OK) {
+            attached = (*surf_vm)->AttachCurrentThread(surf_vm, &env, NULL) == JNI_OK;
+        }
+        if (env) (*env)->DeleteGlobalRef(env, s->surface);
+        if (attached) (*surf_vm)->DetachCurrentThread(surf_vm);
+    }
+    pthread_mutex_lock(&surf_lock);
+    free(s->pixels);
+    s->pixels = NULL;
+    s->used = 0;
+    pthread_mutex_unlock(&surf_lock);
+    LOG("surface_emul: destroyed %p", (void *)(uintptr_t)handle);
+}

native/build.py

@@ -5,12 +5,12 @@ Everything is fetched on demand into native/.cache (git-ignored):
   - Android NDK r27c (27.2.12479018) from Google's repository (checksummed via repository2-3.xml)
   - OpenXR headers at the commits each component was written against (KhronosGroup/OpenXR-SDK)
   - Temurin JDK 21 (javac) and Android build-tools (d8) for the Java stub classes
-Then builds: FrameBridge adapter (arm64 + arm32), VrApi bridge, platform compat, GL shim, oculusos stub dex, the
+Then builds: FrameBridge adapter (arm64 + arm32), VrApi bridge, platform compat, language packs, GL shim, oculusos stub dex, the
 timefix OpenXR layer for Proton games (linux-arm64, glibc; the NDK's clang builds it freestanding), the
 OculusHMDConnected helper for Rift games under Proton (win-x64 PE; the NDK's clang + lld-link, no Windows SDK), and
 rewrites artifacts/SHA256SUMS. Run `frameport parity` afterwards to see which games change.
 
-    python native/build.py [--only adapter,bridge,compat,glshim,dex,xrlayer,oculushmd,xrshim,vkshim,vrsettings] [--ndk PATH]
+    python native/build.py [--only adapter,bridge,compat,langpack,glshim,dex,xrlayer,oculushmd,xrshim,vkshim,ovrpshim,vrsettings] [--ndk PATH]
 """
 from __future__ import annotations
 
@@ -223,6 +223,15 @@ def build_compat(tc: Path):
          "-Wl,--version-script=exports.map", "-o", ART / "arm64-v8a/libovrplatformcompat.so"], cwd=src)
 
 
+def build_langpack(tc: Path):
+    """Language packs from the game's files (see langpack/langpack.c): DT_NEEDED-injected into overport's platform loader."""
+    src = HERE / "langpack"
+    run([exe(tc, "aarch64-linux-android29-clang"), "-shared", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror",
+         "-fvisibility=hidden", f"-ffile-prefix-map={src}=native/langpack", "-Wl,--no-undefined",
+         "-Wl,-z,max-page-size=16384", "-Wl,-soname,libfp_langpack.so", "langpack.c", "-ldl", "-llog",
+         "-o", ART / "arm64-v8a/libfp_langpack.so"], cwd=src)
+
+
 def build_glshim(tc: Path):
     src = HERE / "glshim"
     run([exe(tc, "aarch64-linux-android29-clang"), "-shared", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror",
@@ -247,6 +256,14 @@ def build_vkshim(tc: Path):
         cwd=src)
 
 
+def build_ovrpshim(tc: Path):
+    """OVRPlugin frame-loop shim (see ovrpshim/ovrpshim.c) for Unity 2017-2018 built-in Oculus support."""
+    src = HERE / "ovrpshim"
+    run([exe(tc, "aarch64-linux-android29-clang"), "-shared", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror",
+         "-fvisibility=hidden", "-Wl,-soname,libfp_ovrp.so", "-Wl,-z,max-page-size=16384", "ovrpshim.c", "-ldl",
+         "-llog", "-o", ART / "arm64-v8a/libfp_ovrp.so"], cwd=src)
+
+
 def build_dex():
     javac = shutil.which("javac")
     if not javac:
@@ -291,7 +308,7 @@ def write_sums():
 
 def main():
     ap = argparse.ArgumentParser()
-    ap.add_argument("--only", default="adapter,bridge,compat,glshim,dex,xrlayer,oculushmd,xrshim,vkshim,vrsettings")
+    ap.add_argument("--only", default="adapter,bridge,compat,langpack,glshim,dex,xrlayer,oculushmd,xrshim,vkshim,ovrpshim,vrsettings")
     ap.add_argument("--ndk")
     args = ap.parse_args()
     parts = set(args.only.split(","))
@@ -299,10 +316,12 @@ def main():
         (ART / d).mkdir(parents=True, exist_ok=True)
     tc = clang_dir(ndk(args.ndk)) if parts - {"dex"} else None
     steps = {"adapter": lambda: build_adapter(tc), "bridge": lambda: build_bridge(tc), "compat": lambda: build_compat(tc),
+             "langpack": lambda: build_langpack(tc),
              "glshim": lambda: build_glshim(tc), "xrshim": lambda: build_xrshim(tc), "dex": build_dex, "xrlayer": lambda: build_xrlayer(tc),
              "oculushmd": lambda: build_oculushmd(tc), "vkshim": lambda: build_vkshim(tc),
+             "ovrpshim": lambda: build_ovrpshim(tc),
              "vrsettings": lambda: build_vrsettings(tc)}
-    for name in ("adapter", "bridge", "compat", "glshim", "xrshim", "vkshim", "dex", "xrlayer", "oculushmd", "vrsettings"):
+    for name in ("adapter", "bridge", "compat", "langpack", "glshim", "xrshim", "vkshim", "ovrpshim", "dex", "xrlayer", "oculushmd", "vrsettings"):
         if name in parts:
             log(f"build {name}")
             steps[name]()

native/langpack/langpack.c

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

native/ovrpshim/ovrpshim.c

@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// FramePort OVRPlugin frame-loop shim for Unity 2017-2018 built-in Oculus support.
+//
+// That Unity drives OVRPlugin with the legacy frame loop: ovrp_Update2(render step, frame index, ...) on the main
+// thread, then ovrp_BeginFrame / ovrp_EndFrame on the render thread. It never calls ovrp_WaitToBeginFrame, which
+// newer OVRPlugin builds (OVRPort's OpenXR OVRPlugin) need to call xrWaitFrame: no frame ever begins, OVRPlugin logs
+// "CompositorOpenXR::Update called for frame N outside of frame bounds" thousands of times a second and the Frame's
+// dashboard freezes (Accounting+, Unity 2017.4).
+//
+// FramePort renames the "ovrp_Update2" lookup in libunity.so to "fpov_Update2" (same length) and adds this library to
+// libOVRPlugin.so's DT_NEEDED, so Unity's dlsym on the plugin finds this function: it waits for the frame first (once
+// per frame index, render step only), then calls the real ovrp_Update2.
+#include <android/log.h>
+#include <dlfcn.h>
+#include <pthread.h>
+
+#define TAG "FrameBridge"
+#define EXPORT __attribute__((visibility("default")))
+#define LOG(...) __android_log_print(ANDROID_LOG_INFO, TAG, __VA_ARGS__)
+
+typedef int (*PFN_Update2)(int step, int frame_index, double prediction_seconds);
+typedef int (*PFN_WaitToBeginFrame)(int frame_index);
+
+static PFN_Update2 real_update2;
+static PFN_WaitToBeginFrame real_wait;
+static pthread_once_t once = PTHREAD_ONCE_INIT;
+
+static void init(void) {
+    void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
+    if (!ovrp) ovrp = dlopen("libOVRPlugin.so", RTLD_NOW);
+    if (ovrp) {
+        real_update2 = (PFN_Update2)dlsym(ovrp, "ovrp_Update2");
+        real_wait = (PFN_WaitToBeginFrame)dlsym(ovrp, "ovrp_WaitToBeginFrame");
+    }
+    LOG("ovrp frame loop shim: ovrp_Update2 %s, ovrp_WaitToBeginFrame %s", real_update2 ? "OK" : "MISSING",
+        real_wait ? "OK" : "MISSING");
+}
+
+#define STEP_RENDER (-1)  // ovrpStep_Render
+
+EXPORT int fpov_Update2(int step, int frame_index, double prediction_seconds) {
+    pthread_once(&once, init);
+    static int last_waited = -1, logged;
+    if (step == STEP_RENDER && real_wait && frame_index != last_waited) {
+        last_waited = frame_index;
+        int r = real_wait(frame_index);
+        if (logged++ < 3) LOG("ovrp frame loop shim: waited for frame %d: %d", frame_index, r);
+    }
+    return real_update2 ? real_update2(step, frame_index, prediction_seconds) : -1000;  // ovrpFailure
+}
+
+// ---------------------------------------------------------------- input diagnostics (pass-through)
+// The game's C# input (OVRInput) asks OVRPlugin which controllers are connected and for their button state. These
+// wrappers return exactly what OVRPlugin returns and log the connected mask and every change of the button bits, to
+// see whether presses reach the game (Accounting+ stuck at "press any button" while the runtime reports presses).
+typedef struct { unsigned int words[3]; } State;  // the common start: ConnectedControllers, Buttons, Touches
+// ovrpControllerState2 is returned by value (through x8): the type must have its exact size, 64 bytes (4 uint32,
+// IndexTrigger[2], HandTrigger[2], Thumbstick[2] and Touchpad[2] as float pairs)
+typedef struct { unsigned int words[16]; } State2;
+_Static_assert(sizeof(State2) == 64, "ovrpControllerState2 is 64 bytes");
+typedef unsigned int (*PFN_GetConnected)(void);
+typedef int (*PFN_GetState4)(unsigned int mask, State *state);  // (written by OVRPlugin; only the start is read)
+typedef State2 (*PFN_GetState2)(unsigned int mask);
+static PFN_GetConnected real_connected;
+static PFN_GetState4 real_state4;
+static PFN_GetState2 real_state2;
+static pthread_once_t input_once = PTHREAD_ONCE_INIT;
+
+static void input_init(void) {
+    void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
+    if (!ovrp) return;
+    real_connected = (PFN_GetConnected)dlsym(ovrp, "ovrp_GetConnectedControllers");
+    real_state4 = (PFN_GetState4)dlsym(ovrp, "ovrp_GetControllerState4");
+    real_state2 = (PFN_GetState2)dlsym(ovrp, "ovrp_GetControllerState2");
+}
+
+// per requested controller mask (the game may ask for Touch, Remote, Gamepad... separately)
+static struct { unsigned int mask, connected, buttons; int seen; } masks[8];
+static int changes;
+
+// Face buttons on the Frame's controllers can read as clicked while only touched (Accounting+: buttons == touches ==
+// A|B|X|Y held for seconds). A button held for more than STUCK_NS is reported released until it really lets go, so
+// real presses (short) still register as a change.
+#include <time.h>
+#define STUCK_NS 2000000000ll
+static long long held_since[32];
+static unsigned int suppressed;
+
+static long long now_ns(void) {
+    struct timespec t;
+    clock_gettime(CLOCK_MONOTONIC, &t);
+    return t.tv_sec * 1000000000ll + t.tv_nsec;
+}
+
+static unsigned int unstick(unsigned int buttons) {
+    long long now = now_ns();
+    for (int b = 0; b < 32; b++) {
+        unsigned int bit = 1u << b;
+        if (!(buttons & bit)) {
+            held_since[b] = 0;
+            suppressed &= ~bit;
+            continue;
+        }
+        if (!held_since[b]) held_since[b] = now;
+        if (now - held_since[b] > STUCK_NS && !(suppressed & bit)) {
+            suppressed |= bit;
+            static int logged;
+            if (logged++ < 20) LOG("ovrp input: button 0x%x held for > 2 s: reported released until let go", bit);
+        }
+    }
+    return buttons & ~suppressed;
+}
+
+static void note_state(const char *which, unsigned int mask, const State *s) {
+    int i = 0;
+    while (i < 8 && masks[i].seen && masks[i].mask != mask) i++;
+    if (i == 8) return;
+    if (!masks[i].seen || masks[i].buttons != s->words[1] || masks[i].connected != s->words[0]) {
+        if (changes++ < 120)
+            LOG("ovrp input: %s(mask 0x%x): connected 0x%x buttons 0x%x touches 0x%x%s", which, mask, s->words[0],
+                s->words[1], s->words[2], masks[i].seen ? "" : " (first call with this mask)");
+        masks[i].seen = 1;
+        masks[i].mask = mask;
+        masks[i].connected = s->words[0];
+        masks[i].buttons = s->words[1];
+    }
+}
+
+EXPORT unsigned int fpov_GetConnectedControllers(void) {
+    pthread_once(&input_once, input_init);
+    unsigned int c = real_connected ? real_connected() : 0;
+    static unsigned int last = 0xffffffffu;
+    static int logged;
+    if (c != last && logged++ < 20) LOG("ovrp input: connected controllers 0x%x", c);
+    last = c;
+    return c;
+}
+
+EXPORT int fpov_GetControllerState4(unsigned int mask, State *state) {
+    pthread_once(&input_once, input_init);
+    int r = real_state4 ? real_state4(mask, state) : -1000;
+    if (state) {
+        note_state("State4", mask, state);
+        state->words[1] = unstick(state->words[1]);
+    }
+    return r;
+}
+
+EXPORT State2 fpov_GetControllerState2(unsigned int mask) {
+    pthread_once(&input_once, input_init);
+    State2 s = {{0}};
+    if (real_state2) s = real_state2(mask);
+    note_state("State2", mask, (const State *)&s);
+    s.words[1] = unstick(s.words[1]);
+    return s;
+}
+
+// Unity's own input (libunity.so: Input.GetKey/anyKey on the Oculus device) reads ovrp_GetControllerState (v1,
+// returned by value, 48 bytes: 4 uint32, IndexTrigger[2], HandTrigger[2], Thumbstick[2]) and ovrp_GetControllerState2
+typedef struct { unsigned int words[12]; } State1;
+_Static_assert(sizeof(State1) == 48, "ovrpControllerState is 48 bytes");
+typedef State1 (*PFN_GetState1)(unsigned int mask);
+static PFN_GetState1 real_state1;
+
+EXPORT State1 fpov_GetControllerState(unsigned int mask) {
+    pthread_once(&input_once, input_init);
+    if (!real_state1) {
+        void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
+        if (ovrp) real_state1 = (PFN_GetState1)dlsym(ovrp, "ovrp_GetControllerState");
+    }
+    State1 s = {{0}};
+    if (real_state1) s = real_state1(mask);
+    note_state("State1(unity)", mask, (const State *)&s);
+    return s;
+}
+
+// Oculus Utilities (1.3x) ignores every button unless OVRPlugin reports input focus; with Unity 2017's legacy frame
+// loop on OVRPort's OVRPlugin that may never be true. Report it as true (the session's own focus still pauses the game)
+// and log what OVRPlugin said.
+typedef int (*PFN_GetInputFocus)(int *has_focus);
+static PFN_GetInputFocus real_input_focus;
+
+EXPORT int fpov_GetAppHasInputFocus(int *has_focus) {
+    pthread_once(&input_once, input_init);
+    if (!real_input_focus) {
+        void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
+        if (ovrp) real_input_focus = (PFN_GetInputFocus)dlsym(ovrp, "ovrp_GetAppHasInputFocus");
+    }
+    int value = 0, r = real_input_focus ? real_input_focus(&value) : -1000;
+    static int last = -2, logged;
+    if ((r < 0 ? -1 : value) != last && logged++ < 20) LOG("ovrp input: OVRPlugin input focus %d (result %d)", value, r);
+    last = r < 0 ? -1 : value;
+    if (has_focus) *has_focus = 1;
+    return 0;  // ovrpSuccess
+}

native/vkshim/vkshim.c

@@ -8,6 +8,11 @@
 // at this shim (patches/frame/vk_sanitize.py). dlsym on the shim finds the functions below first and every other
 // symbol in its dependency, the real libvulkan.so. Valid pointers are kept; a pointer is dropped only when it isn't
 // readable memory or doesn't point at a structure type the parent may chain.
+//
+// Shader fixes (adapter setting vk_shader_fix, from a game's recipe): a SPIR-V module whose size and SHA-256 match is
+// copied with extra words inserted at a byte offset, e.g. stores that initialize locals a shader reads before writing
+// (an undefined loop counter hung the GPU in VR4's campaign). Every other module passes through unchanged.
+// Format: vk_shader_fix=<size>:<sha256 hex>:<byte offset>:<word>,<word>,...[;<next fix>]
 #define _GNU_SOURCE
 #include <vulkan/vulkan.h>
 #include <android/log.h>
@@ -27,14 +32,162 @@ static void *real_vk;
 static PFN_vkGetInstanceProcAddr real_gipa;
 static PFN_vkGetDeviceProcAddr real_gdpa;
 static PFN_vkCreateRenderPass2 real_rp2_trampoline;
+static PFN_vkCreateShaderModule real_csm_trampoline;
 static pthread_once_t once = PTHREAD_ONCE_INIT;
 
+// ---------------------------------------------------------------- shader fixes (settings)
+
+#define MAX_FIXES 16
+#define MAX_WORDS 64
+static struct {
+    size_t size, offset;
+    uint8_t sha[32];
+    uint32_t words[MAX_WORDS];
+    int nwords;
+} fixes[MAX_FIXES];
+static int nfixes;
+
+static int hexval(char c) {
+    return c >= '0' && c <= '9' ? c - '0' : c >= 'a' && c <= 'f' ? c - 'a' + 10 : c >= 'A' && c <= 'F' ? c - 'A' + 10 : -1;
+}
+
+static void parse_fixes(char *v) {
+    for (char *save = NULL, *item = strtok_r(v, ";", &save); item && nfixes < MAX_FIXES; item = strtok_r(NULL, ";", &save)) {
+        char *f[4] = {0}, *save2 = NULL;
+        int n = 0;
+        for (char *t = strtok_r(item, ":", &save2); t && n < 4; t = strtok_r(NULL, ":", &save2)) f[n++] = t;
+        if (n != 4 || strlen(f[1]) != 64) continue;
+        int ok = 1;
+        for (int i = 0; i < 32 && ok; i++) {
+            int hi = hexval(f[1][2 * i]), lo = hexval(f[1][2 * i + 1]);
+            if (hi < 0 || lo < 0) ok = 0; else fixes[nfixes].sha[i] = (uint8_t)(hi << 4 | lo);
+        }
+        fixes[nfixes].size = strtoul(f[0], NULL, 0);
+        fixes[nfixes].offset = strtoul(f[2], NULL, 0);
+        int nw = 0;
+        for (char *save3 = NULL, *w = strtok_r(f[3], ",", &save3); w && nw < MAX_WORDS; w = strtok_r(NULL, ",", &save3))
+            fixes[nfixes].words[nw++] = (uint32_t)strtoul(w, NULL, 0);
+        fixes[nfixes].nwords = nw;
+        if (ok && nw && fixes[nfixes].size % 4 == 0 && fixes[nfixes].offset % 4 == 0 &&
+            fixes[nfixes].offset >= 20 && fixes[nfixes].offset <= fixes[nfixes].size)
+            nfixes++;
+    }
+}
+
+static void read_settings(const char *path) {
+    FILE *f = fopen(path, "r");
+    if (!f) return;
+    char line[4096];
+    while (fgets(line, sizeof line, f)) {
+        line[strcspn(line, "\r\n")] = 0;
+        if (!strncmp(line, "vk_shader_fix=", 14)) {
+            nfixes = 0;  // later sources override earlier ones (as for the adapter's settings)
+            parse_fixes(line + 14);
+        }
+    }
+    fclose(f);
+}
+
+static void read_all_settings(void) {
+    char path[600];
+    Dl_info info;
+    if (dladdr((void *)read_all_settings, &info) && info.dli_fname) {
+        const char *slash = strrchr(info.dli_fname, '/');
+        if (slash && slash - info.dli_fname < 500) {
+            snprintf(path, sizeof path, "%.*s/libframe_settings.so", (int)(slash - info.dli_fname), info.dli_fname);
+            read_settings(path);
+        }
+    }
+    char pkg[256] = {0};
+    FILE *f = fopen("/proc/self/cmdline", "r");
+    if (f) {
+        size_t n = fread(pkg, 1, sizeof pkg - 1, f);
+        pkg[n] = 0;
+        fclose(f);
+    }
+    char *colon = strchr(pkg, ':');
+    if (colon) *colon = 0;
+    if (*pkg && !strchr(pkg, '/')) {
+        snprintf(path, sizeof path, "/sdcard/Android/data/%s/files/framebridge.conf", pkg);
+        read_settings(path);
+    }
+    const char *env = getenv("FRAMEBRIDGE_CONFIG");
+    if (env && *env) read_settings(env);
+}
+
+// SHA-256 (FIPS 180-4), only run for modules whose size matches a fix
+static const uint32_t K[64] = {
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01,
+    0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc,
+    0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
+    0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08,
+    0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+    0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2};
+#define ROR(x, n) (((x) >> (n)) | ((x) << (32 - (n))))
+
+static void sha256_block(uint32_t h[8], const uint8_t *p) {
+    uint32_t w[64];
+    for (int i = 0; i < 16; i++) w[i] = (uint32_t)p[4 * i] << 24 | (uint32_t)p[4 * i + 1] << 16 | (uint32_t)p[4 * i + 2] << 8 | p[4 * i + 3];
+    for (int i = 16; i < 64; i++) {
+        uint32_t s0 = ROR(w[i - 15], 7) ^ ROR(w[i - 15], 18) ^ (w[i - 15] >> 3);
+        uint32_t s1 = ROR(w[i - 2], 17) ^ ROR(w[i - 2], 19) ^ (w[i - 2] >> 10);
+        w[i] = w[i - 16] + s0 + w[i - 7] + s1;
+    }
+    uint32_t a = h[0], b = h[1], c = h[2], d = h[3], e = h[4], f = h[5], g = h[6], hh = h[7];
+    for (int i = 0; i < 64; i++) {
+        uint32_t t1 = hh + (ROR(e, 6) ^ ROR(e, 11) ^ ROR(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + w[i];
+        uint32_t t2 = (ROR(a, 2) ^ ROR(a, 13) ^ ROR(a, 22)) + ((a & b) ^ (a & c) ^ (b & c));
+        hh = g; g = f; f = e; e = d + t1; d = c; c = b; b = a; a = t1 + t2;
+    }
+    h[0] += a; h[1] += b; h[2] += c; h[3] += d; h[4] += e; h[5] += f; h[6] += g; h[7] += hh;
+}
+
+static void sha256(const uint8_t *data, size_t len, uint8_t out[32]) {
+    uint32_t h[8] = {0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19};
+    size_t i = 0;
+    for (; i + 64 <= len; i += 64) sha256_block(h, data + i);
+    uint8_t tail[128] = {0};
+    size_t rest = len - i;
+    memcpy(tail, data + i, rest);
+    tail[rest] = 0x80;
+    size_t blocks = rest + 9 > 64 ? 2 : 1;
+    uint64_t bits = (uint64_t)len * 8;
+    for (int b = 0; b < 8; b++) tail[blocks * 64 - 1 - b] = (uint8_t)(bits >> (8 * b));
+    for (size_t b = 0; b < blocks; b++) sha256_block(h, tail + 64 * b);
+    for (int b = 0; b < 8; b++) {
+        out[4 * b] = h[b] >> 24; out[4 * b + 1] = h[b] >> 16; out[4 * b + 2] = h[b] >> 8; out[4 * b + 3] = h[b];
+    }
+}
+
+// The fixed copy of `code` (caller frees) and its size, or NULL when no fix matches.
+static uint32_t *fixed_shader(const uint32_t *code, size_t size, size_t *out_size) {
+    for (int i = 0; i < nfixes; i++) {
+        if (fixes[i].size != size) continue;
+        uint8_t digest[32];
+        sha256((const uint8_t *)code, size, digest);
+        if (memcmp(digest, fixes[i].sha, 32)) continue;
+        size_t extra = (size_t)fixes[i].nwords * 4;
+        uint32_t *copy = malloc(size + extra);
+        if (!copy) return NULL;
+        memcpy(copy, code, fixes[i].offset);
+        memcpy((uint8_t *)copy + fixes[i].offset, fixes[i].words, extra);
+        memcpy((uint8_t *)copy + fixes[i].offset + extra, (const uint8_t *)code + fixes[i].offset, size - fixes[i].offset);
+        *out_size = size + extra;
+        return copy;
+    }
+    return NULL;
+}
+
 static void init(void) {
+    read_all_settings();
+    if (nfixes) LOG("vk shim: %d shader fix(es) configured", nfixes);
     real_vk = dlopen("libvulkan.so", RTLD_NOW | RTLD_LOCAL);
     if (real_vk) {
         real_gipa = (PFN_vkGetInstanceProcAddr)dlsym(real_vk, "vkGetInstanceProcAddr");
         real_gdpa = (PFN_vkGetDeviceProcAddr)dlsym(real_vk, "vkGetDeviceProcAddr");
         real_rp2_trampoline = (PFN_vkCreateRenderPass2)dlsym(real_vk, "vkCreateRenderPass2");
+        real_csm_trampoline = (PFN_vkCreateShaderModule)dlsym(real_vk, "vkCreateShaderModule");
     }
     LOG("vk shim: libvulkan.so %s", real_gipa && real_gdpa ? "OK" : "MISSING");
 }
@@ -203,17 +356,26 @@ static VkRenderPassCreateInfo2 clean_create_info(Arena *a, const VkRenderPassCre
 // ---------------------------------------------------------------- entry points
 
 #define MAX_DEVICES 8
-static struct { VkDevice device; PFN_vkCreateRenderPass2 rp2, rp2khr; } devices[MAX_DEVICES];
+enum { FN_RP2, FN_RP2KHR, FN_CSM, FN_COUNT };
+static const char *const FN_NAMES[FN_COUNT] = {"vkCreateRenderPass2", "vkCreateRenderPass2KHR", "vkCreateShaderModule"};
+static struct { VkDevice device; PFN_vkVoidFunction fn[FN_COUNT]; } devices[MAX_DEVICES];
 static PFN_vkCreateRenderPass2 fallback_rp2khr;  // from vkGetInstanceProcAddr
 static pthread_mutex_t dev_lock = PTHREAD_MUTEX_INITIALIZER;
 
-static PFN_vkCreateRenderPass2 real_for(VkDevice device, int khr) {
-    PFN_vkCreateRenderPass2 fn = NULL;
+// The next implementation of a wrapped device function: the one vkGetDeviceProcAddr returned for this device, else
+// a fresh lookup, else the loader's trampoline.
+static PFN_vkVoidFunction device_fn(VkDevice device, int which) {
+    PFN_vkVoidFunction fn = NULL;
     pthread_mutex_lock(&dev_lock);
     for (int i = 0; i < MAX_DEVICES; i++)
-        if (devices[i].device == device) { fn = khr ? devices[i].rp2khr : devices[i].rp2; break; }
+        if (devices[i].device == device) { fn = devices[i].fn[which]; break; }
     pthread_mutex_unlock(&dev_lock);
-    if (!fn && real_gdpa) fn = (PFN_vkCreateRenderPass2)real_gdpa(device, khr ? "vkCreateRenderPass2KHR" : "vkCreateRenderPass2");
+    if (!fn && real_gdpa) fn = real_gdpa(device, FN_NAMES[which]);
+    return fn;
+}
+
+static PFN_vkCreateRenderPass2 real_for(VkDevice device, int khr) {
+    PFN_vkCreateRenderPass2 fn = (PFN_vkCreateRenderPass2)device_fn(device, khr ? FN_RP2KHR : FN_RP2);
     if (!fn) fn = khr ? fallback_rp2khr : real_rp2_trampoline;
     return fn;
 }
@@ -246,10 +408,39 @@ static VKAPI_ATTR VkResult VKAPI_CALL create_render_pass2_khr(VkDevice device, c
     return create_render_pass2(device, ci, alloc, rp, 1);
 }
 
+static int fixes_applied;
+
+EXPORT VKAPI_ATTR VkResult VKAPI_CALL vkCreateShaderModule(VkDevice device, const VkShaderModuleCreateInfo *ci,
+                                                           const VkAllocationCallbacks *alloc, VkShaderModule *module) {
+    pthread_once(&once, init);
+    PFN_vkCreateShaderModule real = (PFN_vkCreateShaderModule)device_fn(device, FN_CSM);
+    if (!real) real = real_csm_trampoline;
+    if (!real) return VK_ERROR_INITIALIZATION_FAILED;
+    size_t size = 0;
+    uint32_t *code = nfixes && ci && ci->pCode ? fixed_shader(ci->pCode, ci->codeSize, &size) : NULL;
+    if (!code) return real(device, ci, alloc, module);
+    VkShaderModuleCreateInfo copy = *ci;  // the caller's create info and code stay untouched
+    copy.codeSize = size;
+    copy.pCode = code;
+    VkResult r = real(device, &copy, alloc, module);
+    free(code);
+    if (fixes_applied++ < 20) LOG("vk shim: fixed shader module (%zu -> %zu bytes): %d", ci->codeSize, size, r);
+    return r;
+}
+
+static int wrapped_index(const char *name) {
+    for (int i = 0; i < FN_COUNT; i++)
+        if (!strcmp(name, FN_NAMES[i])) return i;
+    return -1;
+}
+
 static PFN_vkVoidFunction wrap(const char *name) {
-    if (!strcmp(name, "vkCreateRenderPass2")) return (PFN_vkVoidFunction)vkCreateRenderPass2;
-    if (!strcmp(name, "vkCreateRenderPass2KHR")) return (PFN_vkVoidFunction)create_render_pass2_khr;
-    return NULL;
+    switch (wrapped_index(name)) {
+    case FN_RP2: return (PFN_vkVoidFunction)vkCreateRenderPass2;
+    case FN_RP2KHR: return (PFN_vkVoidFunction)create_render_pass2_khr;
+    case FN_CSM: return nfixes ? (PFN_vkVoidFunction)vkCreateShaderModule : NULL;  // nothing to fix: no detour
+    default: return NULL;
+    }
 }
 
 EXPORT VKAPI_ATTR PFN_vkVoidFunction VKAPI_CALL vkGetDeviceProcAddr(VkDevice device, const char *name) {
@@ -258,7 +449,7 @@ EXPORT VKAPI_ATTR PFN_vkVoidFunction VKAPI_CALL vkGetDeviceProcAddr(VkDevice dev
     PFN_vkVoidFunction fn = real_gdpa(device, name);
     PFN_vkVoidFunction w = fn ? wrap(name) : NULL;
     if (!w) return fn;
-    int khr = name[strlen(name) - 1] == 'R';
+    int which = wrapped_index(name);
     pthread_mutex_lock(&dev_lock);
     int slot = -1;
     for (int i = 0; i < MAX_DEVICES; i++) {
@@ -267,7 +458,7 @@ EXPORT VKAPI_ATTR PFN_vkVoidFunction VKAPI_CALL vkGetDeviceProcAddr(VkDevice dev
     }
     if (slot >= 0) {
         devices[slot].device = device;
-        if (khr) devices[slot].rp2khr = (PFN_vkCreateRenderPass2)fn; else devices[slot].rp2 = (PFN_vkCreateRenderPass2)fn;
+        devices[slot].fn[which] = fn;
     }
     pthread_mutex_unlock(&dev_lock);
     return w;

packaging/release-footer.md

@@ -0,0 +1,8 @@
+## Install
+
+- **Windows:** unzip `FramePort-windows-x64.zip`, run `FramePort.exe` (warning → **More info → Run anyway**).
+- **macOS:** unzip `FramePort-macos-arm64.zip`, right-click `FramePort.app` → **Open**.
+- **Linux:** `tar xzf FramePort-linux-x64.tar.gz && ./FramePort/FramePort` (ARM64: `FramePort-linux-arm64.tar.gz`).
+
+Full guide: [docs/INSTALL.md](https://github.com/spoopyghosty0/frameport/blob/main/docs/INSTALL.md) · checksums in
+`SHA256SUMS.txt`.

pyproject.toml

@@ -1,13 +1,27 @@
 [project]
 name = "frameport"
 dynamic = ["version"]
-description = "Port Meta Quest standalone games to the Valve Steam Frame (Lepton): suggested patches, automated validation, one-click install."
+description = "Run Meta Quest, Android and PC VR games on the Valve Steam Frame: per-game patches, validation and one-click install."
 readme = "README.md"
-license = { text = "GPL-3.0-only" }
+license = "GPL-3.0-only"
+license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]
+authors = [{ name = "spoopyghosty0" }]
+keywords = ["steam-frame", "vr", "openxr", "meta-quest", "android", "lepton", "proton", "revive"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: X11 Applications",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Games/Entertainment",
+]
 requires-python = ">=3.11"
 dependencies = [
     "flet>=1.0",
     "flet-desktop>=1.0",
+    "flet-dropzone>=0.4.0",  # drag-and-drop uploads in the Files tab (packaged app only; Apache-2.0)
     "paramiko>=3.4",
     "zeroconf>=0.132",
     "psutil>=5.9",
@@ -20,11 +34,16 @@ dependencies = [
     "pyaxmlparser>=0.3.31",
 ]
 
+[project.urls]
+Homepage = "https://github.com/spoopyghosty0/frameport"
+Issues = "https://github.com/spoopyghosty0/frameport/issues"
+Releases = "https://github.com/spoopyghosty0/frameport/releases"
+
 [project.optional-dependencies]
-dev = ["pytest>=8", "flet-web>=1.0", "flet-cli>=1.0", "playwright>=1.40"]
+dev = ["pytest>=8", "pytest-timeout>=2.3", "ruff>=0.6", "flet-web>=1.0", "flet-cli>=1.0", "playwright>=1.40"]
 
 [project.scripts]
-frameport = "frameport.cli:app"
+frameport = "frameport.cli:main"
 frameport-gui = "frameport.ui.app:main"
 
 [build-system]
@@ -45,8 +64,8 @@ packages = ["src/frameport"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+timeout = 120
 markers = [
-    "device: needs a reachable Steam Frame (FRAMEPORT_FRAME=user@host)",
     "games: needs the local game dumps (FRAMEPORT_GAMES=<downloads dir>)",
     "native: compiles native code with the NDK from native/build.py (FRAMEPORT_NATIVE_TESTS=1; slow)",
 ]
@@ -59,3 +78,19 @@ company = "FramePort"
 [tool.flet.app]
 path = "src"
 module = "main"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+extend-exclude = ["native", "src/frameport/_data"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+ignore = [
+    "E731",  # lambdas assigned to names: used for small Flet callbacks
+    "B008",  # function calls in defaults: Typer options
+    "UP007", "UP045",  # Optional[...] in Typer signatures (Typer reads the annotations)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["frameport"]

scripts/catalog_from_issue.py

@@ -21,7 +21,10 @@ from frameport.recommend.catalog import CatalogEntry, to_yaml  # noqa: E402
 
 PKG_RE = re.compile(r"^(rift\.[a-z0-9_]{1,80}|[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z0-9_]+){1,8})$")
 STATUSES = {"works", "issues", "unsupported", "unknown"}
-LIST_FIELDS = {"overport_extra", "overport_remove", "alt_overport", "frame", "frame_remove", "pcvr", "pcvr_remove"}
+LIST_FIELDS = {"overport_extra", "overport_remove", "alt_overport", "frame", "frame_remove", "pcvr", "pcvr_remove",
+               "device"}
+# FramePort's own patch ids must exist (OVRPort's are listed by its CLI at runtime, so not checked here)
+OWN_PATCH_FIELDS = ("frame", "frame_remove", "pcvr", "pcvr_remove", "device")
 DICT_FIELDS = {"adapter", "device_files", "lepton_env", "proton_env", "verified"}
 ID_RE = re.compile(r"^[A-Za-z0-9_.\-]{1,80}$")
 
@@ -64,6 +67,13 @@ def validate(d: dict) -> CatalogEntry:
     for k in LIST_FIELDS & set(d):
         if not isinstance(d[k], list) or not all(isinstance(x, str) and ID_RE.match(x) for x in d[k]):
             raise Invalid(f"{k} must be a list of patch ids")
+    from frameport.patches import base
+
+    base.load_all()
+    for k in OWN_PATCH_FIELDS:
+        unknown_ids = [x for x in d.get(k) or [] if x not in base.REGISTRY]
+        if unknown_ids:
+            raise Invalid(f"{k}: unknown patch id(s) {', '.join(unknown_ids)}")
     for k in DICT_FIELDS & set(d):
         if not isinstance(d[k], dict):
             raise Invalid(f"{k} must be a mapping")

scripts/compat_list.py

@@ -0,0 +1,48 @@
+"""Write docs/GAMES.md: the tested games from the bundled catalog as a simple table to share.
+Run after catalog changes: python scripts/compat_list.py"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+from frameport.recommend import catalog  # noqa: E402
+
+STATUS = {"works": "✅ Works", "issues": "⚠️ Works with issues", "unsupported": "❌ Doesn't run"}
+ORDER = {"works": 0, "issues": 1, "unsupported": 2}
+ISSUES = "https://github.com/spoopyghosty0/frameport/issues/new?template="
+SHARE, REPORT = ISSUES + "working-config.yml", ISSUES + "bug-report.yml"
+
+
+def short(note: str) -> str:
+    """The note's first sentence, without technical asides."""
+    first = re.split(r"(?<=[.!?])\s", " ".join((note or "").split()), maxsplit=1)[0]
+    return first if len(first) <= 160 else first[:157].rstrip() + "…"
+
+
+def render() -> str:
+    # the repo's own recipes only (a local user catalog would replace or hide entries)
+    bundled = catalog._load_dir(catalog.catalog_dir() / "games", "bundled")
+    entries = [e for e in bundled.values() if e.status in STATUS]
+    entries.sort(key=lambda e: (ORDER[e.status], e.title.lower()))
+    rows = ["| Game | Platform | Status | Notes |", "|---|---|---|---|"]
+    for e in entries:
+        platform = "PC VR" if e.kind == "rift" else "Quest"
+        note = "" if e.status == "works" else short(e.notes).replace("|", "/")
+        rows.append(f"| {e.title} | {platform} | {STATUS[e.status]} | {note} |")
+    return ("# Tested games\n\n"
+            "Games tested on the Steam Frame with FramePort's recipes. Games not listed here may work too: FramePort "
+            "suggests patches for them, and a working config can be shared from the app (**Share working config…**).\n"
+            f"Tested a game? [Share a working config]({SHARE}) or [report a problem]({REPORT}) (in the app: the game's "
+            "**…** menu does both and fills in the details).\n"
+            "Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.\n\n"
+            + "\n".join(rows) + "\n")
+
+
+if __name__ == "__main__":
+    out = ROOT / "docs" / "GAMES.md"
+    out.write_text(render(), encoding="utf-8")
+    print(f"wrote {out}")

scripts/eval_heuristics.py

@@ -23,7 +23,8 @@ def signature(recipe) -> dict:
     pats = recipe.patches
     return {
         "overport": sorted(p for p in pats if base.get(p).category == "overport" and not base.get(p).default_on),
-        "overport_removed": sorted(p for p in (x.id for x in base.all_patches() if x.category == "overport" and x.default_on)
+        "overport_removed": sorted(p for p in (x.id for x in base.all_patches()
+                                               if x.category == "overport" and x.default_on)
                                    if p not in pats),
         "frame": sorted(p for p in pats if base.get(p).category == "frame" and not base.get(p).default_on),
         "adapter": {p.split(".", 1)[1]: v.get("value") for p, v in sorted(pats.items()) if p.startswith("adapter.")},
@@ -47,7 +48,8 @@ def main() -> int:
         if not catalog.lookup(a.package):
             continue
         want = signature(engine.suggest(a, use_catalog=True))
-        want["status_unsupported"] = catalog.lookup(a.package).status == "unsupported" and "32-bit" in catalog.lookup(a.package).notes
+        want["status_unsupported"] = (catalog.lookup(a.package).status == "unsupported"
+                                      and "32-bit" in catalog.lookup(a.package).notes)
         got = signature(engine.suggest(a, use_catalog=False))
         diffs = {k: (want[k], got[k]) for k in want if want[k] != got[k]}
         total += len(want)

scripts/i18n_extract.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Collect every translatable text into src/frameport/locales/template.json (see src/frameport/i18n.py).
+
+    python scripts/i18n_extract.py          # rewrite the template
+    python scripts/i18n_extract.py --check  # exit 1 if the template is out of date (CI / tests)
+
+Sources: tr("…") and tr_n("…", "…", n) calls in src/frameport (literal arguments), the GUI help texts, and every
+patch's title and description. A translation file (locales/<language>.json) copies the template and fills in the
+values: a string for tr() texts, a list [one, other] for tr_n() texts.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src" / "frameport"
+TEMPLATE = SRC / "locales" / "template.json"
+sys.path.insert(0, str(ROOT / "src"))
+
+
+def from_code() -> tuple[dict, list[str]]:
+    """(texts, problems): tr()/tr_n() literals, and calls whose text isn't a literal (can't be extracted)."""
+    texts: dict = {}
+    problems = []
+    for path in sorted(SRC.rglob("*.py")):
+        if path.name == "i18n.py" and path.parent == SRC:
+            continue
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+        for node in ast.walk(tree):
+            if not (isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id in ("tr", "tr_n")):
+                continue
+            args = node.args[:1] if node.func.id == "tr" else node.args[:2]
+            if all(isinstance(a, ast.Constant) and isinstance(a.value, str) for a in args) and args:
+                if node.func.id == "tr":
+                    texts.setdefault(args[0].value, "")
+                else:
+                    texts[args[0].value] = ["", ""]
+            elif any(isinstance(a, ast.JoinedStr) for a in args):
+                problems.append(f"{path.relative_to(ROOT)}:{node.lineno}: f-string inside {node.func.id}() "
+                                "(use a template and .format())")
+    return texts, problems
+
+
+def from_data() -> dict:
+    """Help texts and patch titles/descriptions (defined as data, translated where they're shown)."""
+    from frameport.patches import base
+    from frameport.patches.settings import GROUPS, UI
+    from frameport.ui.help import HELP
+
+    texts = {dict.__getitem__(HELP, k): "" for k in HELP}
+    for p in base.all_patches():
+        for t in (p.title, p.description, p.summary):
+            if t:
+                texts[t] = ""
+    for _, title in GROUPS:  # the Game settings dialog
+        texts[title] = ""
+    for ui in UI.values():
+        for t in (ui.get("label"), ui.get("help")):
+            if t:
+                texts[t] = ""
+        if ui["control"][0] == "choice":
+            for _, label in ui["control"][1]:
+                if any(c.isalpha() for c in label):
+                    texts[label] = ""
+    return texts
+
+
+def build() -> tuple[dict, list[str]]:
+    code, problems = from_code()
+    texts = {**from_data(), **code}
+    return dict(sorted(texts.items(), key=lambda kv: kv[0].lower())), problems
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--check", action="store_true", help="only check that the template is up to date")
+    args = ap.parse_args()
+    texts, problems = build()
+    for p in problems:
+        print(p, file=sys.stderr)
+    text = json.dumps(texts, ensure_ascii=False, indent=1) + "\n"
+    if args.check:
+        current = TEMPLATE.read_text(encoding="utf-8") if TEMPLATE.exists() else ""
+        if current != text:
+            print("locales/template.json is out of date: run python scripts/i18n_extract.py", file=sys.stderr)
+            return 1
+        return 1 if problems else 0
+    TEMPLATE.parent.mkdir(parents=True, exist_ok=True)
+    TEMPLATE.write_text(text, encoding="utf-8")
+    print(f"{len(texts)} texts -> {TEMPLATE.relative_to(ROOT)}")
+    return 1 if problems else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/package.py

@@ -40,9 +40,19 @@ def stage_data():
     shutil.rmtree(DATA, ignore_errors=True)
     for name in ("catalog", "artifacts", "agent", "bootstrap"):
         shutil.copytree(ROOT / name, DATA / name)
+    # the Frame agent is uploaded as source; `flet build` turns every .py into .pyc (issue #2): keep a non-.py copy
+    shutil.copy2(ROOT / "agent/frameport_agent.py", DATA / "agent/frameport_agent.py.txt")
     print(f"staged data in {DATA}")
 
 
+def check_bundle(out: Path) -> None:
+    """The finished bundle must contain the agent's source (the app uploads it to the Frame)."""
+    found = [p for p in out.rglob("frameport_agent.py*") if p.suffix != ".pyc"]
+    if not found:
+        raise SystemExit(f"{out}: the Frame agent's source is missing from the bundle (only compiled?)")
+    print("agent source in bundle:", ", ".join(str(p.relative_to(out)) for p in found))
+
+
 def main() -> int:
     ap = argparse.ArgumentParser()
     ap.add_argument("--pyinstaller", action="store_true")
@@ -53,8 +63,15 @@ def main() -> int:
     stage_data()
     try:
         if args.pyinstaller:
+            sep = ";" if TARGET == "windows" else ":"
+            # --yes: a failed flet build's folder doesn't stop it
             cmd = ["flet", "pack", str(ROOT / "src/main.py"), "--name", "FramePort", "--product-name", "FramePort",
-                   "--add-data", f"{DATA}{';' if TARGET == 'windows' else ':'}frameport/_data", "--distpath", str(ROOT / "dist")]
+                   "--add-data", f"{DATA}{sep}frameport/_data",
+                   # translations (data files PyInstaller doesn't pick up from the imports)
+                   "--add-data", f"{ROOT / 'src/frameport/locales'}{sep}frameport/locales",
+                   "--distpath", str(ROOT / "dist"), "--yes"]
+            if TARGET == "linux":
+                cmd.append("--onedir")  # a folder: the bundle check sees the agent source, the archive the app
         else:
             # --yes: install the Flutter SDK etc. without prompting; --no-rich-output: plain logs (CI, Windows consoles)
             cmd = ["flet", "build", TARGET, str(ROOT), "--project", "FramePort", "--product", "FramePort",
@@ -62,7 +79,10 @@ def main() -> int:
             if TARGET == "macos":  # flet's default bundled Python lacks prebuilt cryptography wheels for both Mac archs
                 cmd += ["--python-version", "3.12", "--arch", "arm64"]  # Apple Silicon; x86_64 cross-build fails
         print(" ".join(cmd))
-        return subprocess.call(cmd, cwd=ROOT)
+        rc = subprocess.call(cmd, cwd=ROOT)
+        if rc == 0:
+            check_bundle(ROOT / "dist" if args.pyinstaller else ROOT / "dist" / TARGET)
+        return rc
     finally:
         if not args.keep_data:
             shutil.rmtree(DATA, ignore_errors=True)

scripts/scrub_library.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Make a screenshot-safe copy of a FramePort data folder (for docs/images):
 
-    python scripts/scrub_library.py <data dir> <new dir> [--sort size]
+    python scripts/scrub_library.py <data dir> <new dir> [--sort size] [--status works,issues]
 
 Copies library.json + artwork/ only (no Frame pairing, SSH key, tools, logs or builds). In the copy every game's
 folder name becomes its store title, every local path becomes D:/Games/<Quest|PC VR>/<title>/..., settings other than
@@ -66,14 +66,19 @@ def main() -> int:
     ap.add_argument("src", type=Path)
     ap.add_argument("dest", type=Path)
     ap.add_argument("--sort", default="size", choices=["name", "recent", "played", "size", "status"])
+    ap.add_argument("--status", default="", help="keep only games with these recipe statuses, e.g. works,issues")
     args = ap.parse_args()
     lib = json.loads((args.src / "library.json").read_text())
-    games = {pkg: scrub_game(g) for pkg, g in lib.get("games", {}).items()}
+    keep = {x for x in args.status.split(",") if x}
+    games = {pkg: scrub_game(g) for pkg, g in lib.get("games", {}).items()
+             if not keep or (g.get("recipe") or {}).get("status", "unknown") in keep}
     view = {**(lib.get("settings", {}).get("ui.library") or {}), "sort": args.sort, "platform": "all",
             "where": "all", "status": "all", "tags": []}
-    out = {"games": games, "settings": {"ui.library": view, "migrations": lib.get("settings", {}).get("migrations", [])}}
+    migrations = lib.get("settings", {}).get("migrations", [])
+    out = {"games": games, "settings": {"ui.library": view, "migrations": migrations}}
     text = json.dumps(out, indent=1)
-    leftovers = [o for o in re.findall(r'"((?:/|[A-Za-z]:\\\\)[^"]*)"', text) if not o.startswith(("D:/Games/",) + DEVICE)]
+    leftovers = [o for o in re.findall(r'"((?:/|[A-Za-z]:\\\\)[^"]*)"', text)
+                 if not o.startswith(("D:/Games/",) + DEVICE)]
     if leftovers:
         print("not scrubbed:", leftovers[:10], file=sys.stderr)
         return 1

scripts/ui_smoke.py

@@ -25,6 +25,51 @@ PORT = 8557
 ERRORS: list[str] = []
 
 
+class FakeFS:
+    """--fake-frame's file system for the Files tab: a temp folder with sample files, served like SFTP."""
+
+    def __init__(self):
+        import tempfile
+
+        self.home = tempfile.mkdtemp(prefix="fp-fake-frame-")
+        samples = {"Videos": ["Earth from orbit (360).mp4", "Mars landing (VR180).mkv", "Concert 8K 3D.mp4"],
+                   "Downloads": ["Mods/", "readme.txt"], "Documents": ["Saves/", "Notes.pdf"]}
+        sizes = {".mp4": 2_400_000_000, ".mkv": 1_100_000_000}
+        for folder, names in samples.items():
+            base = os.path.join(self.home, folder)
+            os.makedirs(os.path.join(base, "Trips"), exist_ok=True)
+            for n in names:
+                if n.endswith("/"):
+                    os.makedirs(os.path.join(base, n), exist_ok=True)
+                else:
+                    with open(os.path.join(base, n), "wb") as f:
+                        f.truncate(sizes.get(os.path.splitext(n)[1], 48_000))  # sparse: no real disk use
+
+    def agent(self, command, **args):
+        if command == "storage_targets":
+            return {"targets": [{"id": n.lower(), "path": os.path.join(self.home, n), "android": a, "shared": True}
+                                for n, a in (("Videos", "/sdcard/Movies"), ("Downloads", "/sdcard/Download"),
+                                             ("Documents", "/sdcard/Documents"))]}
+        raise RuntimeError(f"fake Frame: {command} not available")
+
+    @property
+    def sftp(self):
+        import paramiko
+
+        class SFTP:
+            def listdir_attr(self, path):
+                out = []
+                for name in sorted(os.listdir(path)):
+                    a = paramiko.SFTPAttributes.from_stat(os.lstat(os.path.join(path, name)))
+                    a.filename = name
+                    out.append(a)
+                return out
+
+            def stat(self, path):
+                return paramiko.SFTPAttributes.from_stat(os.stat(path))
+        return SFTP()
+
+
 class FakeTarget:
     """--fake-frame: a pretend Steam Frame with the library's working Quest builds installed (no network, no device),
     for documentation screenshots."""
@@ -33,6 +78,7 @@ class FakeTarget:
         from frameport.frame.connection import parse_target
 
         self.label = "steamframe"
+        self.frame = FakeFS()
         self.target = parse_target("steamos@steamframe.local")
         works = [g for g in library.games() if g.get("kind") != "rift" and (g.get("build") or {}).get("sha256")
                  and (g.get("recipe") or {}).get("status") in ("works", "issues")]
@@ -54,6 +100,38 @@ class FakeTarget:
         pass
 
 
+class FakeKeyboardSession:
+    """--fake-frame: Type on Frame connects at once (nothing is sent anywhere)."""
+
+    def __init__(self, frame):
+        self.closed = False
+
+    def key(self, name, action="down"):
+        return True
+
+    def text(self, text):
+        return ""
+
+    def close(self):
+        self.closed = True
+
+
+def open_type_dialog(app: FramePortApp) -> None:
+    """Type on Frame over the Steam Frame page, with one key 'pressed' so the screenshot shows it working."""
+    from types import SimpleNamespace
+
+    app.navigate(1)
+    time.sleep(1.5)
+    app.type_on_frame()
+    time.sleep(1.5)
+    dialog = [d for d in app.page._dialogs.controls if d.open][-1]
+    listener = dialog.content.controls[1]
+    listener.on_key_down(SimpleNamespace(key="Enter"))
+
+
+STEP_SECONDS = 4  # per screen (the screenshot is taken ~3 s in)
+
+
 def driver(app: FramePortApp, steps: list[tuple[str, callable]], ready: threading.Event, done_step: list):
     for name, action in steps:
         try:
@@ -62,7 +140,7 @@ def driver(app: FramePortApp, steps: list[tuple[str, callable]], ready: threadin
             ERRORS.append(f"{name}: {traceback.format_exc()}")
         done_step.append(name)
         ready.set()
-        time.sleep(4)
+        time.sleep(STEP_SECONDS)
 
 
 def main() -> int:
@@ -75,15 +153,23 @@ def main() -> int:
     ap.add_argument("--viewport", default="1280x820", help="browser size, e.g. 2560x1440")
     ap.add_argument("--update", action="store_true", help="pretend a new FramePort release exists (update UI)")
     ap.add_argument("--fake-frame", action="store_true", help="pretend a Steam Frame is connected (no device needed)")
+    ap.add_argument("--hover", default=None, help="x,y: move the mouse there before the Library screenshot")
+    ap.add_argument("--install-questions", nargs="+", metavar="PKG", default=None,
+                    help="open the install questions for these games, then click each dialog's main button twice "
+                         "(a double click must not duplicate dialogs); nothing is installed")
     ap.add_argument("--docs", action="store_true", help="only the screens used in the docs (Library, --game, Frame)")
     args = ap.parse_args()
+    global STEP_SECONDS
+    if args.hover:
+        STEP_SECONDS = 7
     from frameport.ui import theme
 
     theme.set_scale(args.scale)
     vw, vh = (int(x) for x in args.viewport.split("x"))
     args.out.mkdir(parents=True, exist_ok=True)
     game = args.game or (library.games()[0]["package"] if library.games() else None)
-    steps = [("library", lambda a: a.navigate(0)), ("frame", lambda a: a.navigate(1)), ("tools", lambda a: a.navigate(2))]
+    steps = [("library", lambda a: a.navigate(0)), ("frame", lambda a: a.navigate(1)),
+             ("files", lambda a: a.go("files")), ("tools", lambda a: a.go("settings"))]
     if game:
         steps.insert(1, ("game", lambda a: a.open_game(game)))
         steps.insert(2, ("game-customize", lambda a: a.open_game(game, advanced=True)))
@@ -95,8 +181,31 @@ def main() -> int:
     if args.docs:
         steps = [("library", lambda a: a.navigate(0))]
         if game:
-            steps += [("game", lambda a: a.open_game(game)), ("game-customize", lambda a: a.open_game(game, advanced=True))]
+            steps += [("game", lambda a: a.open_game(game)),
+                      ("game-customize", lambda a: a.open_game(game, advanced=True))]
         steps.append(("frame", lambda a: a.navigate(1)))
+        steps.append(("files", lambda a: a.go("files")))
+        steps.append(("files-select", lambda a: [a.files_view._toggle(e.path, True)
+                                                 for e in a.files_view.entries[1:3]]))
+        steps.append(("type-on-frame", open_type_dialog))
+    if args.install_questions:
+        queued: list[str] = []
+
+        def open_questions(a):
+            a._submit_install = lambda p, to: queued.append(p)
+            a.install_many(args.install_questions, "frame")
+
+        def double_click(a):
+            dialogs = [d for d in a.page._dialogs.controls if d.open]
+            print(f"open dialogs: {len(dialogs)}", flush=True)
+            button = dialogs[-1].actions[-1]
+            button.on_click(None)
+            button.on_click(None)
+
+        def report(a):
+            print(f"open dialogs: {len([d for d in a.page._dialogs.controls if d.open])}, queued: {queued}", flush=True)
+        steps = [("library", lambda a: a.navigate(0)), ("questions", open_questions),
+                 ("after-1st-double", double_click), ("after-2nd-double", double_click), ("end", report)]
     if args.update:
         from frameport import updates
 
@@ -105,7 +214,7 @@ def main() -> int:
                               notes="## What's new\n- Self-update test release\n- **Bold** and `code` in notes")
         steps += [("update-banner", lambda a: (a.updater._set(fake), a.navigate(0))),
                   ("update-dialog", lambda a: a.updater.show_dialog()),
-                  ("update-settings", lambda a: (a.page.pop_dialog(), a.navigate(2)))]
+                  ("update-settings", lambda a: (a.page.pop_dialog(), a.go("settings")))]
     if args.frame:
         from frameport.frame.connection import parse_target
 
@@ -130,6 +239,13 @@ def main() -> int:
             steps.append(("launch-test-job", job))
     ready, done = threading.Event(), []
 
+    if args.fake_frame:  # never reach a real Frame (start-up auto-connect, discovery, the 30 s poll)
+        from frameport.frame import keyboard
+
+        keyboard.KeyboardSession = FakeKeyboardSession
+        FramePortApp.connect = lambda self, *a, **k: None
+        FramePortApp.refresh_frame = lambda self, *a, **k: None
+
     def app_main(page: ft.Page):
         try:
             app = FramePortApp(page)
@@ -155,8 +271,13 @@ def main() -> int:
                 while len(done) < len(steps) and time.time() < deadline:
                     if ready.wait(1):
                         ready.clear()
+                        name = done[-1]
                         time.sleep(3)  # let Flutter paint
-                        page.screenshot(path=str(args.out / f"{shot:02d}-{done[-1]}.png"))
+                        if args.hover and name == "library":
+                            hx, hy = (float(v) for v in args.hover.split(","))
+                            page.mouse.move(hx, hy)
+                            time.sleep(1.5)
+                        page.screenshot(path=str(args.out / f"{shot:02d}-{name}.png"))
                         shot += 1
                 browser.close()
         except Exception:  # noqa: BLE001

scripts/update_smoke.py

@@ -44,7 +44,8 @@ def main() -> int:
     nested = sub / "new-version.txt"  # files in existing subfolders must be replaced too (Windows merges folders)
     nested.write_text("new")
     if platform == "win32" and os.environ.get("HAS_CERT") == "true":
-        a, b = updates._signer_thumbprint(installed / "FramePort.exe"), updates._signer_thumbprint(new / "FramePort.exe")
+        a = updates._signer_thumbprint(installed / "FramePort.exe")
+        b = updates._signer_thumbprint(new / "FramePort.exe")
         print(f"signer thumbprints: installed {a} new {b}")
         assert a and a == b, "signature check failed"
     # the same launch as the app (detached; apply() checks the script started), then wait for it to finish

src/frameport/_version.py

@@ -1,2 +1,2 @@
 # The FramePort version: the single source (pyproject reads it via hatch; CI checks a release tag matches it).
-__version__ = "0.3.3"
+__version__ = "0.7.1"

src/frameport/analysis/detect.py

@@ -13,6 +13,7 @@ from . import elf
 logging.getLogger("pyaxmlparser").setLevel(logging.ERROR)
 
 UNITY_GGM = "assets/bin/Data/globalgamemanagers"
+IL2CPP_METADATA = "assets/bin/Data/Managed/Metadata/global-metadata.dat"
 
 
 def _read_manifest_info(path: Path) -> tuple[str, str, str, str | None]:
@@ -56,6 +57,29 @@ def _features(manifest: bytes) -> dict[str, bool]:
     return out
 
 
+def vr_kind(libs: set[str], manifest_strings: list[str]) -> str:
+    """What kind of Android app this is, for choosing how to port it:
+    quest       Meta Quest app (VrApi / OVRPlugin / Meta's OpenXR loader + Oculus manifest entries): OVRPort
+    openxr      another headset's OpenXR app (Pico, Khronos loader): OVRPort's loader + the Frame adapter
+    android_xr  Android XR (Jetpack XR / spatial) app: needs system services Lepton doesn't have
+    pico_sdk    Pico's pre-OpenXR SDK, wave: HTC Vive Wave SDK: no OpenXR path, can't run
+    none        an ordinary (2D) Android app or game: installed without the VR translation"""
+    text = " ".join(manifest_strings)
+    meta = (libs & {"libvrapi.so", "libOVRPlugin.so", "libovrplatformloader.so"}
+            or "com.oculus." in text or "oculus.software." in text or "horizonos." in text)
+    if meta:
+        return "quest"
+    if any(lib.startswith("libwvr") for lib in libs) or "com.htc.vr" in text:
+        return "wave"
+    if "libopenxr_loader.so" in libs or "org.khronos.openxr" in text:
+        return "openxr"
+    if libs & {"libPvr_UnitySDK.so", "libpxr_api.so", "libPxr_api.so", "libPvrSDK.so"} or "pvr.app.type" in text:
+        return "pico_sdk"
+    if "android.software.xr" in text or "androidx.xr" in text or "com.google.android.xr" in text:
+        return "android_xr"
+    return "none"
+
+
 # OpenXR composition-layer extensions the Frame runtime lacks (see docs/FRAME_RUNTIME.md).
 LAYER_EXTENSIONS = ("XR_KHR_composition_layer_cylinder", "XR_KHR_composition_layer_equirect",
                     "XR_KHR_composition_layer_equirect2", "XR_KHR_composition_layer_cube")
@@ -69,6 +93,9 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
         abi = next((a for a in ("arm64-v8a", "armeabi-v7a") if a in abis), None)
         prefix = f"lib/{abi}/" if abi else None
         libs = sorted(n[len(prefix):] for n in names if prefix and n.startswith(prefix) and n.endswith(".so"))
+        # SDL's Java side (SDL2 / LÖVE apps): crashes in Lepton without a clipboard service (frame.sdl_clipboard)
+        sdl_java = any(b"Lorg/libsdl/app/SDLClipboardHandler;" in z.read(n) for n in names
+                       if n.startswith("classes") and n.endswith(".dex"))
         manifest = z.read("AndroidManifest.xml")
         lib_bytes = {}
         if deep and prefix:
@@ -80,8 +107,10 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
                         lib_bytes[lib] = z.read(info)
         engine_lib = next((prefix + n for n in ("libUE4.so", "libUnreal.so") if prefix and prefix + n in names), None)
         unreal_version = _unreal_version(z, engine_lib) if deep and engine_lib else None
-        boot = z.read("assets/bin/Data/boot.config").decode("utf-8", "replace") if "assets/bin/Data/boot.config" in names else ""
+        boot = (z.read("assets/bin/Data/boot.config").decode("utf-8", "replace")
+                if "assets/bin/Data/boot.config" in names else "")
         ggm = z.read(UNITY_GGM) if deep and UNITY_GGM in names else None
+        il2cpp_meta = z.read(IL2CPP_METADATA) if deep and IL2CPP_METADATA in names and "libil2cpp.so" in libs else None
 
     package, version, label, activity = _read_manifest_info(path)
     libset = set(libs)
@@ -113,7 +142,8 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
             oculus_os_refs.append(name)
         if name != "libOVRPlugin.so":  # OVRPlugin lists every layer extension; only the game's own requests count
             layer_exts |= {ext for ext in LAYER_EXTENSIONS if ext.encode() + b"\0" in data}
-        if name not in ("libvrapi.so", "libOVRPlugin.so") and b"GLAD_GL_" in data and "eglGetProcAddress" in elf.dyn_symbols(data, False):
+        if (name not in ("libvrapi.so", "libOVRPlugin.so") and b"GLAD_GL_" in data
+                and "eglGetProcAddress" in elf.dyn_symbols(data, False)):
             uses_glad = True
 
     msaa_levels = 0
@@ -126,6 +156,7 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
             msaa_levels = 0
 
     cats = axml.categories(manifest)
+    manifest_strings = axml.Axml(manifest).strings()
     features = _features(manifest)
     used_perms, _ = axml.used_and_declared_permissions(manifest)
     return Analysis(
@@ -151,17 +182,59 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
             "missing_ovr_symbols": sorted(missing_ovr_symbols(lib_bytes)), "size": path.stat().st_size,
             "data_bytes": data_bytes or 0,
             "features": features,
-            "meta_permissions_used": sorted(p for p in used_perms if p.startswith(("com.oculus.permission.", "horizonos."))),
+            "meta_permissions_used": sorted(p for p in used_perms
+                                            if p.startswith(("com.oculus.permission.", "horizonos."))),
             # mixed-reality-only: passthrough required and no guardian (Meta's BOUNDARYLESS_APP)
-            "mr_only": features.get("com.oculus.feature.PASSTHROUGH", False) and "com.oculus.feature.BOUNDARYLESS_APP" in features,
+            "mr_only": (features.get("com.oculus.feature.PASSTHROUGH", False)
+                        and "com.oculus.feature.BOUNDARYLESS_APP" in features),
             "hand_tracking_only": features.get("oculus.software.handtracking", False),
             "unreal_version": unreal_version,
             "oculus_os_refs": sorted(oculus_os_refs),
             "xr_layer_exts": sorted(layer_exts),  # composition-layer extensions the game's own libraries request
+            "vr_kind": vr_kind(libset, manifest_strings),
+            # the base of a split APK set (Play "app bundle" installs): the code/libraries live in split APKs
+            "split_apk": bool({"isSplitRequired", "requiredSplitTypes"} & set(manifest_strings)),
+            # Unity (IL2CPP) text fields: they close at once on the Frame (frame.unity_text_input)
+            "text_fields": unity_text_fields(il2cpp_meta) if il2cpp_meta else [],
+            # Meta's OVRManager raises MSAA at runtime (frame.unity_runtime_msaa_off); Oculus XR Plugin (multiview)
+            "ovr_runtime_msaa": bool(il2cpp_meta) and b"\0useRecommendedMSAALevel\0" in il2cpp_meta,
+            "sdl_java": sdl_java,
+            "oculus_xr_plugin": bool(il2cpp_meta) and b"\0m_StereoRenderingModeAndroid\0" in il2cpp_meta,
+            # Unity's built-in Oculus support checks for Meta's system apps before VR (frame.unity_oculus_check)
+            "unity_oculus_check": b"\0com.oculus.systemactivities\0" in lib_bytes.get("libunity.so", b""),
+            "unity_version": unity_version(ggm, lib_bytes.get("libunity.so")) if engine == "Unity" else None,
         },
     )
 
 
+def unity_text_fields(metadata: bytes) -> list[str]:
+    """The Unity text field classes an IL2CPP game contains (names from its global-metadata.dat string table)."""
+    out = []
+    if b"\0TMP_InputField\0" in metadata:
+        out.append("TMP_InputField")
+    if b"\0InputField\0" in metadata and b"\0UnityEngine.UI\0" in metadata:  # not the tail of TMP_InputField
+        out.append("InputField")
+    return out
+
+
+UNITY_VERSION = re.compile(rb"(?<![\d.])(\d{4}\.\d+\.\d+[abfpx]\d+)")
+
+
+def unity_version(ggm: bytes | None = None, libunity: bytes | None = None) -> str | None:
+    """Unity version (e.g. 6000.2.7f2): from the header of globalgamemanagers, else the version string libunity.so
+    repeats most (games packed into data.unity3d have no loose globalgamemanagers)."""
+    m = UNITY_VERSION.search(ggm[:512]) if ggm else None
+    if m:
+        return m.group(1).decode()
+    if libunity:
+        from collections import Counter
+
+        found = Counter(x.group(1) for x in UNITY_VERSION.finditer(libunity))
+        if found:
+            return found.most_common(1)[0][0].decode()
+    return None
+
+
 def _uses_feature(manifest: bytes, feature: str) -> bool:
     x = axml.Axml(manifest)
     return any(el.name == "uses-feature" and (x.attr_str(el, "name") or "").startswith(feature) for el in x.elements())
@@ -173,12 +246,14 @@ def missing_ovr_symbols(lib_bytes: dict[str, bytes]) -> set[str]:
     if not loader or not elf.is_elf(loader):
         return set()
     exported = set(elf.dyn_symbols(loader, True))
-    for extra in ("libovrplatformcompat.so", "libovrstubs.so"):
-        if extra in lib_bytes:
+    linked = set(elf.needed(loader))
+    for extra in ("libovrplatformcompat.so", "libovrstubs.so", "libfp_langpack.so"):
+        if extra in lib_bytes and extra in linked:  # only counts when the loader loads it (a lone file doesn't help)
             exported |= elf.dyn_symbols(lib_bytes[extra], True)
     wanted = set()
     for name, data in lib_bytes.items():
-        if name.startswith(("libovrplatformloader", "libopenxr_loader", "libframe_settings", "libfrda")) or not elf.is_elf(data):
+        if (name.startswith(("libovrplatformloader", "libopenxr_loader", "libframe_settings", "libfrda"))
+                or not elf.is_elf(data)):
             continue
         wanted |= {s for s in elf.dyn_symbols(data, False) if s.startswith(("ovr_", "ovrMessageType_"))}
     return wanted - exported

src/frameport/analysis/elf.py

@@ -106,6 +106,29 @@ def replace_rodata_string(data: bytes, old: str, new: str) -> tuple[bytes, int]:
     return bytes(buf), count
 
 
+def hide_exports(data: bytes, names) -> tuple[bytes, list[str]]:
+    """Make the exported functions `names` invisible to symbol lookup without removing them: their .dynsym entries
+    become STB_LOCAL (name, value and section stay, nothing moves, the hash tables are untouched). Both bionic's and
+    glibc's lookups only match GLOBAL/WEAK entries, so a lookup for such a name (a game's import, or dlsym on this
+    library's handle) goes on to the next library in the dependency list; code that reads the library's own .dynsym
+    (native/langpack) still finds the original address. Returns (data, names actually hidden); ELF64 only."""
+    if not is_elf(data) or not is_64bit(data) or data[5] != 1:
+        return data, []
+    sec = _elf(data).get_section_by_name(".dynsym")
+    if not isinstance(sec, SymbolTableSection):
+        return data, []
+    wanted = set(names)
+    entsize, start = sec["sh_entsize"] or 24, sec["sh_offset"]
+    buf, hidden = bytearray(data), []
+    for i, sym in enumerate(sec.iter_symbols()):
+        if (sym.name in wanted and sym["st_shndx"] != "SHN_UNDEF"
+                and sym["st_info"]["bind"] in ("STB_GLOBAL", "STB_WEAK")):
+            at = start + i * entsize + 4  # Elf64_Sym.st_info: binding in the high nibble, type in the low one
+            buf[at] &= 0x0F
+            hidden.append(sym.name)
+    return bytes(buf), sorted(hidden)
+
+
 def add_needed(data: bytes, library: str) -> bytes:
     """Add a DT_NEEDED entry in front of the existing ones (same effect as `patchelf --add-needed`; being first matters
     for symbol interposition, e.g. the GL shim must precede libEGL).
@@ -219,7 +242,7 @@ def add_needed(data: bytes, library: str) -> bytes:
         table[note_i] = new_load
     # PT_LOAD entries must stay sorted by vaddr (bionic); the new one has the highest vaddr.
     load_slots = [i for i, p in enumerate(table) if p["type"] == PT_LOAD]
-    for i, p in zip(load_slots, sorted((table[i] for i in load_slots), key=lambda p: p["vaddr"])):
+    for i, p in zip(load_slots, sorted((table[i] for i in load_slots), key=lambda p: p["vaddr"]), strict=True):
         table[i] = p
 
     buf += b"\0" * (file_end - len(buf))

src/frameport/analysis/il2cpp.py

@@ -0,0 +1,107 @@
+"""Find methods in an IL2CPP Unity game: Cpp2IL lists every method with its address ([Address(... Offset = "0x...")]
+in its "diffable C#" output with the attribute injector). Offset is the method's position in the libil2cpp.so FILE
+(not the virtual address: those differ, e.g. by 0x4000 in Stremio VR's library), which is what a byte patch needs.
+
+Results are cached per game build (its global-metadata.dat), so a rebuild of the same game doesn't run Cpp2IL again,
+and neither does the next patch of the same build (an earlier one has already changed libil2cpp.so's bytes, never its
+layout)."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import subprocess
+import tempfile
+from pathlib import Path
+
+from ..core.cache import cache_dir
+
+_ADDRESS = re.compile(r'Offset = "0x([0-9A-Fa-f]+)", Length = "0x([0-9A-Fa-f]+)"')
+
+
+def parse_methods(cs_text: str, names: list[str]) -> dict[str, tuple[int, int]]:
+    """{method name: (file offset, length)} for the named methods of one Cpp2IL diffable-C# class file. A name
+    "field:<f>" gives the instance field's offset instead: (offset, 0)."""
+    lines = cs_text.splitlines()
+    found: dict[str, tuple[int, int]] = {}
+    for name in [n for n in names if n.startswith("field:")]:
+        m = re.search(rf"\s{re.escape(name[6:])};\s*//Field offset: 0x([0-9A-Fa-f]+)", cs_text)
+        if m:
+            found[name] = (int(m.group(1), 16), 0)
+    names = [n for n in names if not n.startswith("field:")]
+    for i, line in enumerate(lines):
+        for name in names:
+            if name in found or not re.search(rf"\s{re.escape(name)}\s*\(", line) or "Token" in line:
+                continue
+            for back in range(i - 1, max(i - 4, -1), -1):
+                m = _ADDRESS.search(lines[back])
+                if m:
+                    found[name] = (int(m.group(1), 16), int(m.group(2), 16))
+                    break
+    return found
+
+
+def _last_error(output: str) -> str:
+    """The exception line of Cpp2IL's output (its stack trace isn't useful to a user)."""
+    lines = [ln.strip() for ln in output.splitlines() if ln.strip()]
+    msg = next((ln for ln in reversed(lines) if "Exception" in ln and not ln.startswith("at ")), None)
+    return (msg or (lines[-1] if lines else "no output"))[:300]
+
+
+def _plain_version(version: str) -> str:
+    """6000.2.7f2 -> 6000.2.7 (what Cpp2IL's --force-unity-version takes)."""
+    m = re.match(r"\d+\.\d+\.\d+", version)
+    return m.group(0) if m else version
+
+
+def _cache_file(lib: bytes, metadata: bytes) -> Path:
+    key = hashlib.sha256(metadata + len(lib).to_bytes(8, "little")).hexdigest()[:32]
+    return cache_dir() / "il2cpp" / (key + ".json")
+
+
+def find_methods(lib: bytes, metadata: bytes, unity_version: str, wanted: dict[str, list[str]],
+                 cpp2il: Path | None = None, timeout: float = 900) -> dict[str, dict[str, tuple[int, int]]]:
+    """wanted: {class file (relative to Cpp2IL's DiffableCs folder, e.g. "Unity.TextMeshPro/TMPro/TMP_InputField.cs"):
+    [method names]} -> {class file: {method: (file offset, length)}}; classes or methods not in the game are left
+    out."""
+    cache_file = _cache_file(lib, metadata)
+    try:
+        cached = json.loads(cache_file.read_text())
+        if cached.get("error"):  # Cpp2IL can't read this build (e.g. an old Unity): don't run it again per patch
+            raise RuntimeError(cached["error"])
+        if all(cls in cached.get("classes", {}) or cls in cached.get("missing", []) for cls in wanted):
+            return {cls: {m: tuple(v) for m, v in cached["classes"][cls].items() if m in names}
+                    for cls, names in wanted.items() if cls in cached.get("classes", {})}
+    except (OSError, ValueError, KeyError):
+        pass
+    if cpp2il is None:
+        from ..tools import cpp2il as tool
+
+        cpp2il = tool.ensure()
+    with tempfile.TemporaryDirectory(prefix="frameport-il2cpp-") as tmp:
+        t = Path(tmp)
+        (t / "libil2cpp.so").write_bytes(lib)
+        (t / "global-metadata.dat").write_bytes(metadata)
+        proc = subprocess.run([str(cpp2il), "--force-binary-path", str(t / "libil2cpp.so"),
+                               "--force-metadata-path", str(t / "global-metadata.dat"),
+                               "--force-unity-version", _plain_version(unity_version),
+                               "--use-processor", "attributeinjector", "--output-as", "diffable-cs",
+                               "--output-to", str(t / "out")], capture_output=True, text=True, errors="replace",
+                              timeout=timeout, cwd=tmp)
+        root = t / "out" / "DiffableCs"
+        if not root.is_dir():
+            error = "Cpp2IL couldn't read this game's code: " + _last_error(proc.stdout + proc.stderr)
+            cache_file.parent.mkdir(parents=True, exist_ok=True)
+            cache_file.write_text(json.dumps({"unity_version": unity_version, "error": error}))
+            raise RuntimeError(error)
+        out, missing = {}, []
+        for cls, names in wanted.items():
+            f = root / cls
+            if f.exists():
+                out[cls] = parse_methods(f.read_text(encoding="utf-8", errors="replace"), names)
+            else:
+                missing.append(cls)
+    cache_file.parent.mkdir(parents=True, exist_ok=True)
+    cache_file.write_text(json.dumps({"unity_version": unity_version, "missing": missing,
+                                      "classes": {c: {m: list(v) for m, v in ms.items()} for c, ms in out.items()}}))
+    return out

src/frameport/analysis/langpacks.py

@@ -0,0 +1,28 @@
+"""Language packs (`<BCP47 tag>.lang`) in a game's data folder (OBB / app files); see native/langpack."""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+MAX_DEPTH = 3  # same depth as the runtime scan in native/langpack/langpack.c
+TAG = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def find_tags(data_dir: Path | str | None) -> list[str]:
+    """Tags of the language packs below `data_dir` (de.lang -> "de"), sorted, first file per tag."""
+    if not data_dir:
+        return []
+    root = Path(data_dir)
+    if not root.is_dir():
+        return []
+    seen: dict[str, str] = {}
+    base_depth = len(root.parts)
+    for folder, dirs, files in os.walk(root):
+        if len(Path(folder).parts) - base_depth >= MAX_DEPTH:
+            dirs[:] = []
+        for name in files:
+            stem, dot, ext = name.rpartition(".")
+            if dot and ext.lower() == "lang" and TAG.match(stem):
+                seen.setdefault(stem.lower(), stem)
+    return sorted(seen.values(), key=str.lower)

src/frameport/analysis/rift.py

@@ -40,7 +40,8 @@ PLATFORM_DLLS = ("libovrplatform64_1.dll", "libovrplatform32_1.dll")
 PLATFORM_WRAPPERS = ("pnsovr.dll",)
 GRAPHICS = (("d3d12.dll", "D3D12"), ("d3d11.dll", "D3D11"), ("vulkan-1.dll", "Vulkan"), ("opengl32.dll", "OpenGL"))
 AMBIGUITY = 15  # a runner-up within this many points means "ask the user"
-# repacks start their bundled Revive through a proxy DLL next to the exe (Windows loads DLLs from the exe's folder first)
+# repacks start their bundled Revive through a proxy DLL next to the exe (Windows loads DLLs from the exe's folder
+# first)
 LOADER_DLLS = ("xinput1_3.dll", "xinput1_4.dll", "xinput9_1_0.dll", "dinput8.dll", "version.dll", "winmm.dll")
 REVIVE_DLLS = ("librevive64.dll", "librevive32.dll", "librevivexr64.dll", "librevivexr32.dll")
 
@@ -267,18 +268,22 @@ def candidates(tree: Tree) -> list[Path]:
 
 
 # ------------------------------------------------------------------------------------------ naming
-_TAG_WORDS = r"(?:ARMGDDN|VRP|JF|FFA|Repacks?|Shipping|GOG|CODEX|PLAZA|FitGirl|DODI|ElAmigos|Oculus|Rift|PCVR)"
+# words that describe a build rather than the game (neutral; release tags are removed by their form, not by name)
+_BUILD_WORDS = r"(?:Shipping|GOG|Oculus|Rift|PCVR|Repacks?|Release)"
+# a release tag at the end: " -TAG", " -TAG v76", " -[TAG Repacks]" (a space before the dash and none after it, so
+# subtitles like " - Episode II" and hyphenated words like "Rick-ality" stay)
+_TRAILING_TAG = r"\s-(?=[\[A-Za-z0-9])(?:\[[^\]]*\]|[A-Za-z0-9]{2,12}\b)(?:\s+v\d+)?.*$"
 
 
 def clean_title(name: str) -> str:
-    """'Asgards Wrath v1.6.0 -ARMGDDN' -> 'Asgards Wrath'; 'Arktika 1 (v1.0.0.7) -VRP' -> 'Arktika 1';
+    """'Asgards Wrath v1.6.0 -TAG' -> 'Asgards Wrath'; 'Arktika 1 (v1.0.0.7) -TAG' -> 'Arktika 1';
     'Vader Immortal - Episode II v2.0.2+236948 Shipping' -> 'Vader Immortal - Episode II'."""
-    t = re.sub(r"\[[^\]]*\]", " ", name)  # [FFA Repacks]
-    t = re.sub(r"\((?:[^)]*\d[^)]*|[^)]*" + _TAG_WORDS + r"[^)]*)\)", " ", t, flags=re.I)  # (v1.0.0.7)
-    t = re.sub(r"\s-\s*" + _TAG_WORDS + r"\b.*$", " ", t, flags=re.I)  # -ARMGDDN, -VRP v76
+    t = re.sub(_TRAILING_TAG, " ", name)
+    t = re.sub(r"\[[^\]]*\]", " ", t)  # [TAG Repacks]
+    t = re.sub(r"\((?:[^)]*\d[^)]*|[^)]*\b" + _BUILD_WORDS + r"\b[^)]*)\)", " ", t, flags=re.I)  # (v1.0.0.7)
     t = re.sub(r"\bv\d[\w.+\-]*", " ", t, flags=re.I)  # v1.6.0, v008, v2.0.2+236948
     t = re.sub(r"(?<![\w.])\d+(?:\.\d+){2,}[\w+\-]*", " ", t)  # 4.15.20, 21.11.08.358012
-    t = re.sub(r"\b" + _TAG_WORDS + r"\b", " ", t, flags=re.I)
+    t = re.sub(r"\b" + _BUILD_WORDS + r"\b", " ", t, flags=re.I)
     t = re.sub(r"[_]+", " ", t)
     t = re.sub(r"\s+", " ", t).strip(" -_.")
     return t or name.strip()
@@ -356,13 +361,6 @@ def is_ambiguous(ranked: list[dict]) -> bool:
     return len(ranked) > 1 and ranked[0]["score"] < 1000 and ranked[1]["score"] >= ranked[0]["score"] - AMBIGUITY
 
 
-def find_exe(folder: Path) -> Path | None:
-    """The best program to start the game (used by callers that only need one)."""
-    tree = walk(folder)
-    ranked = rank_exes(folder, candidates(tree), tree.manifest)
-    return Path(folder) / ranked[0]["path"] if ranked else None
-
-
 # ------------------------------------------------------------------------------------------ analysis
 def fingerprint(folder: Path, exe_rel: str) -> str:
     p = Path(folder) / exe_rel
@@ -432,8 +430,9 @@ def analyze(folder: Path, exe: str | None = None, tree: Tree | None = None) -> A
                 platform_imports |= set(sub.imports + sub.delay_imports)
             except (PEError, OSError, struct.error):
                 pass
-    platform_sdk = any(n in names for n in PLATFORM_DLLS + PLATFORM_WRAPPERS) or bool(platform_imports & set(PLATFORM_DLLS)) or \
-        b"ovr_PlatformInitializeWindows" in blob or b"ovr_Entitlement_GetIsViewerEntitled" in blob
+    platform_sdk = (any(n in names for n in PLATFORM_DLLS + PLATFORM_WRAPPERS)
+                    or bool(platform_imports & set(PLATFORM_DLLS))
+                    or b"ovr_PlatformInitializeWindows" in blob or b"ovr_Entitlement_GetIsViewerEntitled" in blob)
     # how to start it with VR on SteamVR / the Frame (see launch_mode())
     try:
         exe_dir = {p.name.lower() for p in exe_path.parent.iterdir()}

src/frameport/analysis/stubgen.py

@@ -1,6 +1,6 @@
 """Generate a tiny Android shared library whose exported functions all `return 0` (no compiler needed).
 
-Used for Meta platform functions (ovr_*) that overport's platform loader lacks: without them the game fails with
+Used for Meta platform functions (ovr_*) that OVRPort's platform loader lacks: without them the game fails with
 UnsatisfiedLinkError / dlopen errors. The layout follows what bionic requires: section headers present (.dynsym,
 .dynstr, .hash, .text, .dynamic, .shstrtab), PT_LOAD segments 16 KiB aligned, PT_DYNAMIC matching the .dynamic
 section, DT_HASH, DT_SONAME and PT_GNU_STACK non-executable.

src/frameport/apk/axml.py

@@ -6,8 +6,8 @@ file stays byte-identical, which keeps diffs against known-good builds meaningfu
 from __future__ import annotations
 
 import struct
+from collections.abc import Iterator
 from dataclasses import dataclass
-from typing import Iterator
 
 RES_XML = 0x0003
 RES_STRING_POOL = 0x0001
@@ -252,7 +252,8 @@ def define_meta_permissions(manifest: bytes) -> tuple[bytes, list[str]] | None:
         start = struct.pack("<HHIII", RES_XML_START_ELEMENT, 16, 56, 0, 0xFFFFFFFF)
         start += struct.pack("<IIHHHHHH", 0xFFFFFFFF, perm_el, 20, 20, 1, 0, 0, 0)
         start += struct.pack("<IIIHBBI", android_ns, name_attr, value, 8, 0, TYPE_STRING, value)
-        end = struct.pack("<HHIII", RES_XML_END_ELEMENT, 16, 24, 0, 0xFFFFFFFF) + struct.pack("<II", 0xFFFFFFFF, perm_el)
+        end = (struct.pack("<HHIII", RES_XML_END_ELEMENT, 16, 24, 0, 0xFFFFFFFF)
+               + struct.pack("<II", 0xFFFFFFFF, perm_el))
         chunks += start + end
     manifest_el = next(el for el in x.elements() if el.name == "manifest")
     insert_at = manifest_el.offset + manifest_el.size

src/frameport/apk/dex.py

@@ -0,0 +1,93 @@
+"""Minimal in-place dex edits: find one method's bytecode and turn a call in it into no-ops (same length), then fix the
+header's SHA-1 signature and Adler-32 checksum. Nothing moves, so the rest of classes.dex stays byte-identical (no
+smali round trip)."""
+from __future__ import annotations
+
+import hashlib
+import struct
+import zlib
+
+INVOKE_VIRTUAL, INVOKE_VIRTUAL_RANGE = 0x6E, 0x74  # 35c / 3rc: 3 code units, method index in the second
+
+
+def _uleb(data: bytes, pos: int) -> tuple[int, int]:
+    value = shift = 0
+    while True:
+        b = data[pos]
+        pos += 1
+        value |= (b & 0x7F) << shift
+        if not b & 0x80:
+            return value, pos
+        shift += 7
+
+
+class Dex:
+    def __init__(self, data: bytes):
+        if data[:4] != b"dex\n":
+            raise ValueError("not a dex file")
+        self.data = bytearray(data)
+        h = struct.unpack_from("<8I", data, 56)  # string_ids size/off, type_ids, proto_ids, field_ids
+        self.strings_n, self.strings_off, self.types_n, self.types_off = h[0], h[1], h[2], h[3]
+        self.methods_n, self.methods_off, self.classes_n, self.classes_off = struct.unpack_from("<4I", data, 88)
+
+    def string(self, idx: int) -> str:
+        off = struct.unpack_from("<I", self.data, self.strings_off + 4 * idx)[0]
+        _n, pos = _uleb(self.data, off)
+        end = self.data.index(0, pos)
+        return bytes(self.data[pos:end]).decode("utf-8", "replace")
+
+    def type_name(self, idx: int) -> str:
+        return self.string(struct.unpack_from("<I", self.data, self.types_off + 4 * idx)[0])
+
+    def method(self, idx: int) -> tuple[str, str]:
+        cls, _proto, name = struct.unpack_from("<HHI", self.data, self.methods_off + 8 * idx)
+        return self.type_name(cls), self.string(name)
+
+    def method_index(self, cls: str, name: str) -> list[int]:
+        return [i for i in range(self.methods_n) if self.method(i) == (cls, name)]
+
+    def code_items(self, cls: str, name: str) -> list[int]:
+        """Offsets of the code items of the methods `name` in class `cls` (direct and virtual)."""
+        out = []
+        for c in range(self.classes_n):
+            base = self.classes_off + 32 * c
+            if self.type_name(struct.unpack_from("<I", self.data, base)[0]) != cls:
+                continue
+            class_data = struct.unpack_from("<I", self.data, base + 24)[0]
+            if not class_data:
+                continue
+            pos = class_data
+            sf, pos = _uleb(self.data, pos)
+            inf, pos = _uleb(self.data, pos)
+            dm, pos = _uleb(self.data, pos)
+            vm, pos = _uleb(self.data, pos)
+            for _ in range(sf + inf):
+                _, pos = _uleb(self.data, pos)
+                _, pos = _uleb(self.data, pos)
+            for count in (dm, vm):
+                idx = 0
+                for _ in range(count):
+                    diff, pos = _uleb(self.data, pos)
+                    _, pos = _uleb(self.data, pos)
+                    code, pos = _uleb(self.data, pos)
+                    idx += diff
+                    if code and self.method(idx)[1] == name:
+                        out.append(code)
+        return out
+
+    def nop_calls(self, code_off: int, targets: set[int]) -> int:
+        """Replace invoke-virtual(/range) calls of any method index in `targets` inside one code item with nops."""
+        insns_n = struct.unpack_from("<I", self.data, code_off + 12)[0]
+        start = code_off + 16
+        units = struct.unpack_from(f"<{insns_n}H", self.data, start)
+        done = 0
+        for i in range(insns_n - 2):
+            if units[i] & 0xFF in (INVOKE_VIRTUAL, INVOKE_VIRTUAL_RANGE) and units[i + 1] in targets:
+                struct.pack_into("<3H", self.data, start + 2 * i, 0, 0, 0)
+                done += 1
+        return done
+
+    def finish(self) -> bytes:
+        self.data[12:32] = hashlib.sha1(bytes(self.data[32:])).digest()
+        struct.pack_into("<I", self.data, 8, zlib.adler32(bytes(self.data[12:])) & 0xFFFFFFFF)
+        return bytes(self.data)

src/frameport/apk/sign.py

@@ -1,6 +1,6 @@
 """Signing (apksigner via the managed JRE) and alignment checks.
 
-overport creates one keystore per package (password "password", alias "key"). The same key must sign every later
+OVRPort creates one keystore per package (password "password", alias "key"). The same key must sign every later
 build of that package, or Android refuses the update and saves are lost on reinstall.
 """
 from __future__ import annotations
@@ -24,11 +24,30 @@ def _apksigner() -> str:
     return str(jar)
 
 
+def ensure_keystore(package: str) -> Path:
+    """The package's signing key. OVRPort creates it on its first patch; apps built without OVRPort (ordinary
+    Android apps) get one made here with the same layout (password "password", alias "key")."""
+    ks = overport_tool.keystore(package)
+    if ks.exists():
+        return ks
+    java = toolchain.java_path()
+    keytool = java.with_name("keytool.exe" if java and java.name.endswith(".exe") else "keytool") if java else None
+    if not keytool or not keytool.exists():
+        raise RuntimeError(f"no signing key for {package} and no keytool to create one (run `frameport tools install`)")
+    import subprocess
+
+    p = subprocess.run([str(keytool), "-genkeypair", "-keystore", str(ks), "-storetype", "JKS", "-storepass", KS_PASS,
+                        "-keypass", KS_PASS, "-alias", KS_ALIAS, "-keyalg", "RSA", "-keysize", "2048",
+                        "-validity", "10000", "-dname", f"CN={package}, O=FramePort"],
+                       capture_output=True, text=True, timeout=120)
+    if p.returncode or not ks.exists():
+        raise RuntimeError("couldn't create a signing key: " + (p.stdout + p.stderr)[-500:])
+    return ks
+
+
 def sign(unsigned: Path, final: Path, package: str) -> None:
     """Align (4 bytes; .so to 16 KiB pages) and sign v1+v2+v3. apksigner performs the alignment itself."""
-    ks = overport_tool.keystore(package)
-    if not ks.exists():
-        raise RuntimeError(f"no signing key for {package} at {ks} (overport creates it on first patch)")
+    ks = ensure_keystore(package)
     final.unlink(missing_ok=True)
     p = toolchain.run_java([
         "-jar", _apksigner(), "sign", "--ks", str(ks), "--ks-pass", f"pass:{KS_PASS}", "--ks-key-alias", KS_ALIAS,
@@ -55,7 +74,8 @@ def cert_digest(apk: Path) -> str | None:
 
 
 def alignment_problems(apk: Path) -> list[str]:
-    """Stored entries must be 4-byte aligned; stored .so files page (16 KiB) aligned (what zipalign -c -P 16 4 checks)."""
+    """Stored entries must be 4-byte aligned; stored .so files page (16 KiB) aligned (what zipalign -c -P 16 4
+    checks)."""
     bad = []
     with open(apk, "rb") as f, zipfile.ZipFile(apk) as z:
         for info in z.infolist():

src/frameport/apk/workspace.py

@@ -18,7 +18,8 @@ class ApkWorkspace:
         self.add: dict[str, bytes] = {}
         self.rename: dict[str, str] = {}  # old name -> new name (content unchanged unless replaced)
         self.remove: set[str] = set()
-        abi = next((a for a in ("arm64-v8a", "armeabi-v7a") if any(n.startswith(f"lib/{a}/") for n in self.infos)), None)
+        abi = next((a for a in ("arm64-v8a", "armeabi-v7a")
+                    if any(n.startswith(f"lib/{a}/") for n in self.infos)), None)
         self.abi = abi
         self.libdir = f"lib/{abi}/" if abi else ""
 
@@ -89,7 +90,8 @@ class ApkWorkspace:
                 if name in self.replace:
                     dst.writestr(zi, self.replace[name])
                 else:
-                    with self._zip.open(info) as fin, dst.open(zi, "w", force_zip64=info.file_size > 0x7FFFFFFF) as fout:
+                    with (self._zip.open(info) as fin,
+                          dst.open(zi, "w", force_zip64=info.file_size > 0x7FFFFFFF) as fout):
                         shutil.copyfileobj(fin, fout, 1 << 22)
             for name, data in self.add.items():
                 zi = zipfile.ZipInfo(name, date_time=(2020, 1, 1, 0, 0, 0))

src/frameport/artwork/details.py

@@ -61,6 +61,8 @@ def fetch_details(entry: dict, screenshots: bool = True) -> dict:
     """Collect details for a library entry (doesn't store them; see pipeline.fetch_details)."""
     title = entry.get("title") or entry["package"]
     out: dict = {"sources": [], "fetched": time.time()}
+    if ((entry.get("analysis") or {}).get("extra") or {}).get("vr_kind") == "none":
+        return out  # an Android app without VR isn't on a VR store; a title match would be another product
     try:
         app = oculusdb_app(entry)
     except Exception:  # noqa: BLE001 - offline

src/frameport/artwork/fetch.py

@@ -1,6 +1,6 @@
 """Store artwork for the Steam library (portrait/landscape/hero/logo/icon).
 
-Fetched live from overport's image service (Meta store art by package name), cached per package. Falls back to
+Fetched live from OVRPort's image service (Meta store art by package name), cached per package. Falls back to
 the APK's launcher icon when the store has nothing (e.g. sideload-only titles).
 """
 from __future__ import annotations
@@ -20,7 +20,9 @@ KINDS = {
     "APP_IMG_LOGO_TRANSPARENT": "logo",
     "APP_IMG_ICON": "icon",
 }
-EXTRA_KINDS = ("square",)  # OculusDB's square cover (Rift games)
+# OculusDB's square cover (Rift games); FramePort's own cover/banner (no store art)
+EXTRA_KINDS = ("square", "cover", "banner")
+PICKED = ".picked"  # marker: the art in this folder was chosen by the user (Find artwork); automatic fetches skip it
 
 
 def artwork_dir(package: str) -> Path:
@@ -36,12 +38,18 @@ def _ext(data: bytes) -> str:
 def fetch(package: str, apk: Path | None = None, refresh: bool = False,
           lookup: str | None = None) -> tuple[Path, str | None]:
     """Returns (folder with <kind>.<ext> files, store display name or None). `lookup` is the package whose store art
-    to use (a Rift game borrows its Quest version's art); Rift ids without one have no store art."""
+    to use (a Rift game borrows its Quest version's art); Rift ids without one have no store art.
+    Without `refresh` it only fills in missing kinds and never touches art the user picked (PICKED marker): a pick
+    often lacks a kind (Steam has no icon, OculusDB only a square cover), and re-fetching the store art for that
+    replaced the pick at the next install."""
     out = artwork_dir(package)
+    if refresh:
+        (out / PICKED).unlink(missing_ok=True)
     have = {p.stem for p in out.iterdir()}
     title = None
     lookup = lookup or (None if package.startswith("rift.") else package)
-    if lookup and (refresh or not {"portrait", "landscape", "hero", "icon"} <= have):
+    picked = (out / PICKED).exists()
+    if lookup and not picked and (refresh or not {"portrait", "landscape", "hero", "icon"} <= have):
         try:
             data = cache.http_get(API.format(package=lookup), timeout=30).json()
         except Exception:
@@ -52,6 +60,8 @@ def fetch(package: str, apk: Path | None = None, refresh: bool = False,
                 kind = KINDS.get(img.get("image_type"))
                 if not kind:
                     continue
+                if not refresh and kind in have:
+                    continue  # keep what's there; only fill gaps
                 raw = base64.b64decode(img["uri"])
                 for old in out.glob(f"{kind}.*"):
                     old.unlink()
@@ -67,21 +77,43 @@ def fetch(package: str, apk: Path | None = None, refresh: bool = False,
     return out, title
 
 
-def apk_icon(apk: Path) -> bytes | None:
-    """Largest PNG launcher icon inside the APK (mipmap/drawable)."""
+def apk_icon(apk: Path | str | None) -> bytes | None:
+    """The app's launcher icon from the APK as PNG bytes: the icon the manifest names (pyaxmlparser), else the
+    largest ic_launcher bitmap. None for vector/adaptive-only icons (no bitmap to use)."""
+    if not apk or not Path(apk).is_file():
+        return None
+    import io
+
+    from PIL import Image
+
+    dens = ("xxxhdpi", "xxhdpi", "xhdpi", "hdpi", "mdpi")
     try:
         with zipfile.ZipFile(apk) as z:
-            cands = [i for i in z.infolist() if i.filename.startswith("res/") and "ic_launcher" in i.filename
-                     and i.filename.endswith((".png", ".webp"))]
-            if not cands:
-                cands = [i for i in z.infolist() if i.filename.startswith("res/mipmap") and i.filename.endswith(".png")]
-            if not cands:
-                return None
-            best = max(cands, key=lambda i: i.file_size)
-            data = z.read(best)
-            return data if data[:4] == b"\x89PNG" else None
-    except (zipfile.BadZipFile, OSError):
+            listed = set(z.namelist())
+            names = []
+            try:
+                from pyaxmlparser import APK
+
+                named = APK(str(apk)).get_app_icon()
+                if named:
+                    names.append(named)
+            except Exception:  # noqa: BLE001 - unreadable resources: fall back to the usual file names
+                pass
+            names += sorted((n for n in listed if n.startswith("res/") and "ic_launcher" in n
+                             and n.endswith((".png", ".webp")) and "foreground" not in n and "background" not in n),
+                            key=lambda n: next((i for i, d in enumerate(dens) if d in n), len(dens)))
+            for n in names:
+                if n not in listed or not n.endswith((".png", ".webp")):
+                    continue
+                with Image.open(io.BytesIO(z.read(n))) as im:
+                    if im.width < 48:
+                        continue
+                    out = io.BytesIO()
+                    im.convert("RGBA").save(out, "PNG")
+                    return out.getvalue()
+    except (zipfile.BadZipFile, OSError, ValueError):
         return None
+    return None
 
 
 def files(package: str) -> list[Path]:

src/frameport/artwork/sources.py

@@ -139,10 +139,18 @@ def has_art(package: str) -> bool:
 
 
 def fetch_rift(package: str, title: str, canonical: str | None = None, quest_package: str | None = None,
-               exe: Path | None = None) -> dict:
-    """Find and store artwork for a Rift game. Returns what was found: {source, quest_package, oculus_app_id,
-    canonical_name, steam_appid} (only the keys that apply)."""
+               exe: Path | None = None, oculus: bool = True) -> dict:
+    """Find and store artwork for a PC VR game. Returns what was found: {source, quest_package, oculus_app_id,
+    canonical_name, steam_appid} (only the keys that apply). oculus=False (no Oculus code: a SteamVR/OpenXR game):
+    Steam is asked first, the Oculus store only if Steam has nothing."""
     found: dict = {}
+    if not oculus:
+        try:
+            st = match_steam(title)
+        except Exception:  # noqa: BLE001 - offline
+            st = None
+        if st and apply_steam(package, st["id"]):
+            return {"steam_appid": st["id"], "source": "steam"}
     app = None
     try:
         app = match_rift(title, canonical)
@@ -219,9 +227,15 @@ def apply_choice(package: str, choice: dict) -> bool:
         if choice["source"] == "Steam":
             apply_steam(tmp, choice["id"])
         elif choice.get("package"):
+            # the picture the picker showed (OculusDB) is the cover; the store service by package adds the logo
+            # and icon. Its covers can differ from the picked picture (e.g. a "dogfooding" placeholder), so they're
+            # dropped when the picked picture arrived: the Steam shapes are composed from it instead.
+            picked = apply_oculusdb(tmp, choice["app"]) if choice.get("app") else False
             fetch.fetch(tmp, lookup=choice["package"], refresh=True)
-            if not has_art(tmp):
-                apply_oculusdb(tmp, choice["app"])
+            if picked:
+                for f in stage.iterdir():
+                    if f.stem in ("portrait", "landscape", "hero"):
+                        f.unlink()
         else:
             apply_oculusdb(tmp, choice["app"])
         if not has_art(tmp):
@@ -233,6 +247,7 @@ def apply_choice(package: str, choice: dict) -> bool:
         for f in stage.iterdir():
             if f.is_file() and f.stem in ART_STEMS:
                 f.replace(d / f.name)
+        (d / fetch.PICKED).write_text(choice.get("source", ""), encoding="utf-8")  # keep it through installs
         return True
     finally:
         shutil.rmtree(stage, ignore_errors=True)

src/frameport/artwork/steam.py

@@ -4,6 +4,8 @@ Steam wants: portrait 600×900 (library grid), landscape 920×430 (recent/horizo
 logo (transparent, drawn on the hero) and an icon. Store art rarely covers all of them — Rift games from OculusDB only
 have a square cover — so missing shapes are composed: the best source image, fitted and centred over a blurred,
 darkened copy of itself (or a screenshot, for the hero). Results are cached in artwork/<pkg>/steam/.
+A game without any artwork (e.g. an Android app that isn't on a VR store) gets a placeholder set: its name on a
+coloured background, with the APK's own launcher icon when it has a bitmap one.
 """
 from __future__ import annotations
 
@@ -65,15 +67,21 @@ def _ratio_ok(src: Path, size) -> bool:
     return abs(r - target) / target < 0.18
 
 
-def steam_set(package: str) -> dict[str, Path]:
-    """{portrait, landscape, hero, logo?, icon?} files ready for Steam (created once per source change)."""
+def steam_set(package: str, title: str = "", apk: str | Path | None = None) -> dict[str, Path]:
+    """{portrait, landscape, hero, logo?, icon?} files ready for Steam (created once per source change). Without any
+    artwork: a placeholder set showing `title` (+ the launcher icon from `apk`), or {} without a title."""
     src = _sources(package)
-    if not src:
+    if not src and not title:
         return {}
+    title = title or package
     out_dir = fetch.artwork_dir(package) / "steam"
-    out_dir.mkdir(exist_ok=True)
-    key = hashlib.sha1("|".join(f"{k}:{p.stat().st_size}:{p.stat().st_mtime_ns}" for k, p in sorted(src.items()))
-                       .encode()).hexdigest()[:8]
+    out_dir.mkdir(parents=True, exist_ok=True)
+    # no store art (at most the APK's icon; the GUI's generated cover/banner don't count): the name on a coloured tile
+    placeholder = not (set(src) & (STORE_KINDS | {"shot"}))
+    parts = [f"{k}:{p.stat().st_size}:{p.stat().st_mtime_ns}" for k, p in sorted(src.items())]
+    if placeholder:
+        parts.append(f"placeholder:{PLACEHOLDER_VERSION}:{title}:{apk or ''}")
+    key = hashlib.sha1("|".join(parts).encode()).hexdigest()[:8]
     stamp = out_dir / f".{key}"
     result: dict[str, Path] = {}
     if stamp.exists():
@@ -83,6 +91,10 @@ def steam_set(package: str) -> dict[str, Path]:
         return result
     for p in out_dir.iterdir():
         p.unlink()
+    if placeholder:
+        result = _placeholder(out_dir, title, src.get("icon"), apk)
+        stamp.write_text("")
+        return result
     for kind, size in SIZES.items():
         choice = next((k for k in PREFER[kind] if k in src), None)
         if not choice:
@@ -115,15 +127,196 @@ def steam_set(package: str) -> dict[str, Path]:
     return result
 
 
+PLACEHOLDER_VERSION = 2
+
+
+STORE_KINDS = {"portrait", "square", "landscape", "hero"}
+
+
+def ensure_cover(package: str) -> Path | None:
+    """A cover for FramePort's own library when a game has no store art (e.g. a 2D Android app): the same name +
+    APK icon design as the Steam placeholder, saved as artwork/<pkg>/cover.jpg. None when store art exists."""
+    from ..core import library
+
+    d = fetch.artwork_dir(package)
+    if {p.stem for p in fetch.files(package)} & STORE_KINDS:
+        return None
+    g = library.game(package) or {}
+    if not any(d.glob("icon.*")):  # the icon also shows in lists (Frame page)
+        icon = fetch.apk_icon(g.get("apk"))
+        if icon:
+            (d / "icon.png").write_bytes(icon)
+    # icon-only (the card and the game page show the name anyway): a tall cover for cards, a wide banner for the page
+    title = g.get("title") or package
+    cover, banner = d / "cover.jpg", d / "banner.jpg"
+    stamp = d / ".cover"
+    key = f"{PLACEHOLDER_VERSION}:{title}:{next((p.stat().st_size for p in d.glob('icon.*')), 0)}"
+    if cover.exists() and banner.exists() and stamp.exists() and stamp.read_text(encoding="utf-8") == key:
+        return cover
+    icon = _load_icon(next(iter(sorted(d.glob("icon.*"))), None), g.get("apk"))
+    background = _background_for(title)
+    # cover: icon a bit above the middle (the card's title sits at the bottom); banner: icon on the right (the game
+    # page draws the title on the left)
+    for path, size, side, centre in ((cover, (600, 900), 300, (0.5, 0.4)), (banner, (1600, 600), 320, (0.75, 0.5))):
+        im = background(size)
+        if icon is not None:
+            ic = icon.resize((side, side))
+            im.paste(ic, (round(size[0] * centre[0] - side / 2), round(size[1] * centre[1] - side / 2)), ic)
+        im.save(path, "JPEG", quality=90, optimize=True)
+    stamp.write_text(key, encoding="utf-8")
+    return cover
+
+
+def steam_set_for(package: str) -> dict[str, Path]:
+    """steam_set() with the library entry's title and APK, so a game without artwork gets a placeholder."""
+    from ..core import library
+
+    g = library.game(package) or {}
+    return steam_set(package, title=g.get("title") or package, apk=g.get("apk"))
+
+
+def _apk_icon(apk: str | Path | None):
+    """The APK's launcher icon as a PIL image, or None (see fetch.apk_icon)."""
+    import io
+
+    from PIL import Image
+
+    data = fetch.apk_icon(apk)
+    if not data:
+        return None
+    with Image.open(io.BytesIO(data)) as im:
+        return im.convert("RGBA")
+
+
+def _font(size: int):
+    from PIL import ImageFont
+
+    try:
+        return ImageFont.load_default(size=size)  # Pillow's bundled scalable font (needs FreeType)
+    except Exception:  # noqa: BLE001
+        return ImageFont.load_default()
+
+
+def _wrap(draw, text: str, font, width: int) -> list[str]:
+    lines: list[str] = []
+    for word in text.split():
+        if lines and draw.textlength(f"{lines[-1]} {word}", font=font) <= width:
+            lines[-1] += f" {word}"
+        else:
+            lines.append(word)
+    return lines or [text]
+
+
+def _title_block(draw, text: str, box: tuple[int, int, int, int], max_size: int, fill) -> None:
+    """Draw `text` centred in box (x0, y0, x1, y1), as large as fits (wrapped, at most 3 lines)."""
+    x0, y0, x1, y1 = box
+    size = max_size
+    while True:
+        font = _font(size)
+        lines = _wrap(draw, text, font, x1 - x0)
+        line_h = round(size * 1.2)
+        too_wide = any(draw.textlength(line, font=font) > x1 - x0 for line in lines)
+        if size <= 14 or (len(lines) <= 3 and not too_wide and line_h * len(lines) <= y1 - y0):
+            break
+        size = round(size * 0.9)
+    top = y0 + (y1 - y0 - line_h * len(lines)) // 2
+    for i, line in enumerate(lines):
+        w = draw.textlength(line, font=font)
+        draw.text((x0 + (x1 - x0 - w) / 2, top + i * line_h), line, font=font, fill=fill)
+
+
+def _background_for(title: str):
+    """A vertical gradient in a colour picked from the title: background(size) -> PIL image."""
+    import colorsys
+
+    from PIL import Image
+
+    hue = int(hashlib.sha1(title.encode()).hexdigest()[:4], 16) / 0xFFFF
+    top = tuple(round(c * 255) for c in colorsys.hls_to_rgb(hue, 0.30, 0.45))
+    bottom = tuple(round(c * 255) for c in colorsys.hls_to_rgb(hue, 0.10, 0.40))
+
+    def background(size):
+        mask = Image.linear_gradient("L").resize(size)  # 0 at the top → 255 at the bottom
+        return Image.composite(Image.new("RGB", size, bottom), Image.new("RGB", size, top), mask)
+    return background
+
+
+def _load_icon(icon_file: Path | None, apk):
+    from PIL import Image
+
+    if icon_file:
+        try:
+            with Image.open(icon_file) as im:
+                return im.convert("RGBA")
+        except Exception:  # noqa: BLE001
+            pass
+    return _apk_icon(apk)
+
+
+def _placeholder(out_dir: Path, title: str, icon_file: Path | None, apk) -> dict[str, Path]:
+    """Name-on-colour art (portrait, landscape, hero, logo, icon), the hue picked from the title."""
+    from PIL import Image, ImageDraw
+
+    icon = _load_icon(icon_file, apk)
+    background = _background_for(title)
+
+    result: dict[str, Path] = {}
+    for kind, (w, h) in SIZES.items():
+        im = background((w, h))
+        draw = ImageDraw.Draw(im)
+        if kind != "hero":  # Steam draws the logo (the name) over the hero
+            text_box = (w // 10, h // 10, w - w // 10, h - h // 10)
+            if icon is not None:
+                side = min(w, h) // 3
+                ic = icon.resize((side, side), Image.LANCZOS)
+                if kind == "portrait":
+                    im.paste(ic, ((w - side) // 2, h // 4 - side // 4), ic)
+                    text_box = (w // 10, h // 4 + side, w - w // 10, h - h // 10)
+                else:
+                    im.paste(ic, (w // 10, (h - side) // 2), ic)
+                    text_box = (w // 10 + side + w // 20, h // 10, w - w // 12, h - h // 10)
+            _title_block(draw, title, text_box, h // 7 if kind == "portrait" else h // 5, (255, 255, 255))
+        path = out_dir / f"{kind}.jpg"
+        im.save(path, "JPEG", quality=90, optimize=True)
+        result[kind] = path
+    logo = Image.new("RGBA", (1200, 400), (0, 0, 0, 0))
+    _title_block(ImageDraw.Draw(logo), title, (20, 20, 1180, 380), 150, (255, 255, 255, 255))
+    logo = logo.crop(logo.getbbox() or (0, 0, 1200, 400))
+    result["logo"] = out_dir / "logo.png"
+    logo.save(result["logo"], "PNG")
+    ic = background((256, 256))
+    if icon is not None:
+        inner = icon.resize((216, 216), Image.LANCZOS)
+        ic.paste(inner, (20, 20), inner)
+    else:
+        _title_block(ImageDraw.Draw(ic), title[:2].upper() if len(title) > 3 else title, (24, 24, 232, 232), 140,
+                     (255, 255, 255))
+    result["icon"] = out_dir / "icon.png"
+    ic.save(result["icon"], "PNG")
+    return result
+
+
 def original_platform(entry: dict) -> str:
-    return "Oculus Rift" if entry.get("kind") == "rift" else "Meta Quest"
+    """What the game was made for (a Steam tag)."""
+    extra = (entry.get("analysis") or {}).get("extra") or {}
+    if entry.get("kind") == "rift":
+        if extra.get("flat"):
+            return "Windows"
+        return "Oculus Rift" if extra.get("needs_revive") else "PC VR"
+    kind = extra.get("vr_kind") or "quest"
+    return {"quest": "Meta Quest", "none": "Android"}.get(kind, "Android VR")
 
 
 def steam_tags(entry: dict, where: str = "frame") -> list[str]:
     """Tags for the Steam shortcut (Steam can group them into collections): how it runs, the game's original platform,
     genres and the user's own tags."""
-    runs = ("PC VR on Frame" if entry.get("kind") == "rift" else "Quest on Frame") if where == "frame" else \
-        "Rift via Revive"
+    from ..targets.pc_revive import TAG
+
+    kind = ((entry.get("analysis") or {}).get("extra") or {}).get("vr_kind") or "quest"
+    flat = bool(((entry.get("analysis") or {}).get("extra") or {}).get("flat"))
+    runs = TAG if where != "frame" else ("Windows game on Frame" if flat else "PC VR on Frame") \
+        if entry.get("kind") == "rift" else \
+        "Quest on Frame" if kind == "quest" else "Android on Frame"
     base = [runs, original_platform(entry)]
     genres = ((entry.get("details") or {}).get("genres") or [])[:4]
     return list(dict.fromkeys(base + genres + list(entry.get("tags") or [])))

src/frameport/artwork/thumbs.py

@@ -12,7 +12,8 @@ from pathlib import Path
 from ..core.paths import user_data_dir
 from . import fetch
 
-WIDTHS = {"portrait": 400, "square": 400, "landscape": 1280, "hero": 1280, "icon": 96, "logo": 600}
+WIDTHS = {"portrait": 400, "square": 400, "cover": 400, "banner": 1280, "landscape": 1280, "hero": 1280, "icon": 96,
+          "logo": 600}
 _locks: dict[str, threading.Lock] = {}
 _guard = threading.Lock()
 
@@ -62,16 +63,43 @@ def pick(package: str, kinds: tuple[str, ...]) -> Path | None:
     return next((files[k] for k in kinds if k in files), None)
 
 
-def url(package: str, kinds: tuple[str, ...], width: int | None = None) -> str | None:
-    """Asset URL (for ft.Image / DecorationImage src) of the first available kind, as a thumbnail."""
+def url(package: str, kinds: tuple[str, ...], width: int | None = None, wait: bool = True) -> str | None:
+    """Asset URL (for ft.Image / DecorationImage src) of the first available kind, as a thumbnail. wait=False (render
+    paths): if the thumbnail doesn't exist yet it is made in the background and the original is used meanwhile."""
     src = pick(package, kinds)
     if not src:
         return None
-    t = thumb(src, width or WIDTHS.get(src.stem, 600), src.stem)
-    return asset_url(t)
+    width = width or WIDTHS.get(src.stem, 600)
+    if not wait:
+        ready = ready_thumb(src, width, src.stem)
+        if ready is None:
+            threading.Thread(target=thumb, args=(src, width, src.stem), daemon=True).start()
+            return asset_url(src)
+        return asset_url(ready)
+    return asset_url(thumb(src, width, src.stem))
+
+
+def ready_thumb(path: Path, width: int, kind: str | None = None) -> Path | None:
+    """The thumbnail if it already exists (no image work)."""
+    kind = kind or path.stem
+    out = path.parent / f"t_{kind}_{width}_{_digest(path)}{'.png' if kind == 'logo' else '.jpg'}"
+    return out if out.exists() else None
+
+
+_FILE_PATHS = False
+
+
+def use_file_paths(on: bool = True) -> None:
+    """Images by absolute file path: a packaged app (flet build) serves relative image paths from its own bundled
+    assets, not from assets_dir, so artwork by URL stayed blank there (GitHub issue 16; the reporter confirmed file
+    paths work in the Windows app). Source runs and the web view (ui_smoke) keep URLs."""
+    global _FILE_PATHS
+    _FILE_PATHS = on
 
 
 def asset_url(path: Path) -> str:
+    if _FILE_PATHS:
+        return str(path.resolve())
     return "/" + path.relative_to(user_data_dir()).as_posix()
 
 

src/frameport/build.py

@@ -1,4 +1,4 @@
-"""Build stage: overport → Frame fixes (apk-stage patches) → sign → static validation."""
+"""Build stage: OVRPort → Frame fixes (apk-stage patches) → sign → static validation."""
 from __future__ import annotations
 
 import hashlib
@@ -25,7 +25,7 @@ def sha256(path: Path) -> str:
 
 
 def overport_ids(recipe: Recipe, alt: bool = False) -> list[str]:
-    """overport defaults (overport's order) first, then extras in recipe order, then the alt-build extras."""
+    """OVRPort defaults (OVRPort's order) first, then extras in recipe order, then the alt-build extras."""
     chosen = [pid for pid in recipe.patches if base.get(pid).category == "overport"]
     order = [pid for pid, *_ in OVERPORT_PATCHES]
     defaults = [pid for pid in order if pid in chosen and base.get(pid).default_on]
@@ -64,14 +64,28 @@ def build(source: SourceGame, analysis: Analysis, recipe: Recipe, outdir: Path,
     shutil.rmtree(work, ignore_errors=True)
     work.mkdir(parents=True)
     outdir.mkdir(parents=True, exist_ok=True)
-    variants = [("primary", False)] + ([("alt", True)] if recipe.alt_patches else [])
+    # an APK that is already an OVRPort/FramePort build (e.g. a copy from an earlier FramePort) isn't converted again
+    # for the normal build: a second conversion replaces OVRPort's platform loader and drops what the first build
+    # linked to it (Wallace & Gromit / Espire 2 then crashed with "cannot locate symbol ovr_..."). Only the Steam
+    # Frame patches are applied on top. Its alternate build is the copy saved next to it, or (no copy) one more
+    # OVRPort run for the alternate patches; the stand-ins patch relinks what that drops.
+    converted = recipe.overport and analysis.is_overport_output
+    variants = [("primary", False)] + ([("alt", True)] if recipe.alt_patches and recipe.overport else [])
+    alt_copy = Path(source.apk).with_name(f"{pkg}.alt-noforcequit.apk")
     results = {}
     all_checks, applied = [], []
     try:
         for variant, alt in variants:
-            reporter.stage(f"overport ({variant})")
-            ids = overport_ids(recipe, alt)
-            patched = overport_tool.patch(source.apk, work, f"{pkg}.{variant}.overport.apk", ids, reporter)
+            input_apk = alt_copy if converted and alt and alt_copy.exists() else Path(source.apk)
+            if recipe.overport and (not converted or alt and input_apk == Path(source.apk)):
+                reporter.stage(f"OVRPort ({variant})")
+                ids = overport_ids(recipe, alt)
+                patched = overport_tool.patch(source.apk, work, f"{pkg}.{variant}.overport.apk", ids, reporter)
+            else:  # an ordinary Android app, or an already converted build: only the Frame patches it needs
+                if recipe.overport:
+                    reporter.log(f"{input_apk.name} is already converted: applying only the Steam Frame patches")
+                patched = work / f"{pkg}.{variant}.original.apk"
+                shutil.copyfile(input_apk, patched)
             reporter.stage(f"Frame fixes ({variant})")
             unsigned = work / f"{pkg}.{variant}.unsigned.apk"
             applied, checks = apply_frame_fixes(patched, unsigned, analysis, recipe, reporter)
@@ -81,7 +95,7 @@ def build(source: SourceGame, analysis: Analysis, recipe: Recipe, outdir: Path,
             sign.sign(unsigned, final, pkg)
             unsigned.unlink(missing_ok=True)
             reporter.stage(f"validate ({variant})")
-            checks += check_apk(final, pkg)
+            checks += check_apk(final, pkg, expect_adapter=recipe.overport)
             for c in checks:
                 reporter.check(c["name"], c["ok"], c["detail"])
             results[variant] = final

src/frameport/cli.py

@@ -1,6 +1,8 @@
 """FramePort command line. Same operations as the GUI (for automation and headless use).
+Exit codes: 0 done, 1 something failed, 2 wrong usage, 10 (`update --check`) a newer version exists.
+Errors are one line on stderr; FRAMEPORT_DEBUG=1 shows the traceback.
 
-    frameport tools install                      # portable Java + overport + apksigner
+    frameport tools install                      # portable Java + OVRPort + apksigner
     frameport scan "<folder with game dumps>"    # analyze + suggest recipes
     frameport list | show <pkg> | patches
     frameport recipe <pkg> --enable frame.nodebug --set scale=1.2
@@ -8,8 +10,9 @@
     frameport frame discover | pair | info --frame steamos@frame.local
     frameport install <pkg> --frame steamos@frame.local [--apk-only]
     frameport test <pkg> --frame ...             # headless launch + triage
-    frameport frame proton [--install]           # Proton on the Frame, for Oculus Rift (PC VR) games
-    frameport install rift.<game> --to pc|frame  # Rift games: this PC (Revive + Steam) or the Frame (Proton)
+    frameport frame send <files> --dest videos   # copy files to the Frame (where every game sees them)
+    frameport frame proton [--install]           # Proton on the Frame, for PC VR games
+    frameport install rift.<game> --to pc|frame  # PC VR games: this PC (Steam) or the Frame (Proton)
     frameport pc info                            # Windows Steam / SteamVR / Revive on this PC
     frameport parity --known-good <PATCHED dir>  # rebuild everything and diff against known-good APKs
     frameport diag collect <pkg>|--all [--no-frame]  # redacted diagnostics zip (attach it to a GitHub issue)
@@ -31,10 +34,17 @@ from .core import library
 from .core.events import printing_reporter
 from .patches import base
 
-app = typer.Typer(add_completion=False, no_args_is_help=True, help="Port Meta Quest games to the Steam Frame.")
+FRAME_HELP = "the Frame as user@host (default: the paired Frame)"
+ALL_HELP = "every game in the library"
+JSON_HELP = "print JSON"
+
+app = typer.Typer(add_completion=False, no_args_is_help=True,
+                  help="Run Meta Quest, Android and PC VR games on the Steam Frame.",
+                  epilog="Exit codes: 0 done, 1 something failed, 2 wrong usage, 10 (update --check) a newer version "
+                         "exists. The GUI is frameport-gui.")
 tools_app = typer.Typer(help="Manage the portable toolchain.")
 frame_app = typer.Typer(help="Find and connect to a Steam Frame.")
-pc_app = typer.Typer(help="This PC as a target for Oculus Rift (PC VR) games via Revive.")
+pc_app = typer.Typer(help="This PC as a target for PC VR games (Steam and SteamVR; Revive for Oculus games).")
 diag_app = typer.Typer(help="Diagnostics bundles and problem reports.")
 app.add_typer(tools_app, name="tools")
 app.add_typer(frame_app, name="frame")
@@ -126,7 +136,7 @@ def update_cmd(check: bool = typer.Option(False, "--check", help="Only say wheth
         return
     for cmd in cmds:
         typer.echo("$ " + " ".join(cmd))
-        if subprocess.call(cmd):
+        if subprocess.call(cmd, timeout=updates.UPGRADE_TIMEOUT, env=updates.upgrade_env()):
             typer.echo("Update failed.", err=True)
             raise typer.Exit(1)
     typer.echo(f"Updated to FramePort {up.version}.")
@@ -157,27 +167,34 @@ def _pkgs(package: Optional[str], all_: bool) -> list[str]:
         return [g["package"] for g in library.games()]
     if not package:
         raise typer.BadParameter("give a package or --all")
-    matches = [g["package"] for g in library.games() if package.lower() in (g["package"] + " " + (g.get("title") or "")).lower()]
+    matches = [g["package"] for g in library.games()
+               if package.lower() in (g["package"] + " " + (g.get("title") or "")).lower()]
     if package in [g["package"] for g in library.games()]:
         return [package]
     if len(matches) != 1:
-        raise typer.BadParameter(f"{package!r} matches {len(matches)} games: {matches[:5]}")
+        if not matches:
+            raise typer.BadParameter(f"no game in the library matches {package!r} (see frameport list)")
+        raise typer.BadParameter(f"{package!r} matches {len(matches)} games: {', '.join(matches[:5])}"
+                                 + (" …" if len(matches) > 5 else ""))
     return matches
 
 
 # ------------------------------------------------------------------------------------------ tools
 @tools_app.command("status")
 def tools_status(check_latest: bool = typer.Option(False, "--latest", help="also look up the newest versions")):
+    """Which tools FramePort has (Java runtime, OVRPort, apksigner, Revive)."""
     from .tools import toolchain
 
     for s in toolchain.status(check_latest):
         latest = f" (latest {s.latest})" if s.latest else ""
-        typer.echo(f"{s.name:10} {'installed' if s.installed else 'missing':9} {s.version or '-'}{latest}  {s.path or ''}")
+        state = "installed" if s.installed else "missing"
+        typer.echo(f"{s.name:10} {state:9} {s.version or '-'}{latest}  {s.path or ''}")
 
 
 @tools_app.command("install")
 def tools_install(update: bool = typer.Option(False, help="update to the newest versions"),
-                  revive: bool = typer.Option(False, help="also install Revive (for Oculus Rift games)")):
+                  revive: bool = typer.Option(False, help="also install Revive (for Oculus PC games)")):
+    """Download the tools FramePort needs into its own folder (nothing is installed system-wide)."""
     from .tools import overport as ov
     from .tools import toolchain
 
@@ -189,11 +206,11 @@ def tools_install(update: bool = typer.Option(False, help="update to the newest
 
     added = op.refresh(ov.list_patches)
     if added:
-        typer.echo("new overport patches: " + ", ".join(added))
+        typer.echo("new OVRPort patches: " + ", ".join(added))
 
 
 @tools_app.command("import-keys")
-def tools_import_keys(dirs: list[Path]):
+def tools_import_keys(dirs: list[Path] = typer.Argument(..., help="folders with <package>.keystore files")):
     """Import existing per-package signing keystores (keeps updates installable over existing installs)."""
     from .tools import overport as ov
 
@@ -202,7 +219,7 @@ def tools_import_keys(dirs: list[Path]):
 
 # ------------------------------------------------------------------------------------------ library
 @app.command()
-def scan(path: Path):
+def scan(path: Path = typer.Argument(..., help="a folder with game backups (APKs or PC VR game folders), or an APK")):
     """Find games under PATH, analyze them and suggest patches."""
     rep = printing_reporter(verbose=False)
     for g in pipeline.add_path(path, rep):
@@ -212,6 +229,7 @@ def scan(path: Path):
 
 @app.command("list")
 def list_games():
+    """The games in the library."""
     for g in library.games():
         a = g["analysis"]
         built = "built" if g.get("build", {}).get("ok") else ("build-failed" if g.get("build") else "")
@@ -220,8 +238,9 @@ def list_games():
 
 
 @app.command()
-def show(package: str, as_json: bool = typer.Option(False, "--json"),
+def show(package: str, as_json: bool = typer.Option(False, "--json", help=JSON_HELP),
          all_: bool = typer.Option(False, "--all", help="also list patches that don't apply to this game")):
+    """A game's analysis and recipe (its patches, with the reason for each)."""
     [pkg] = _pkgs(package, False)
     g = library.game(pkg)
     if as_json:
@@ -242,7 +261,8 @@ def show(package: str, as_json: bool = typer.Option(False, "--json"),
     if hidden and not all_:
         typer.echo(f"  ({len(hidden)} patches hidden as not relevant for this game; --all to list them)")
     if r.get("alt_patches"):
-        typer.echo(f"  alternate build adds: {', '.join(r['alt_patches'])}  (installed: {'alt' if r['use_alt'] else 'primary'})")
+        which = "alt" if r["use_alt"] else "primary"
+        typer.echo(f"  alternate build adds: {', '.join(r['alt_patches'])}  (installed: {which})")
 
 
 @app.command()
@@ -254,11 +274,13 @@ def patches():
 
 
 @app.command()
-def recipe(package: str, enable: list[str] = typer.Option([], "--enable"), disable: list[str] = typer.Option([], "--disable"),
+def recipe(package: str, enable: list[str] = typer.Option([], "--enable", help="patch id to turn on (repeatable)"),
+           disable: list[str] = typer.Option([], "--disable", help="patch id to turn off (repeatable)"),
            set_: list[str] = typer.Option([], "--set", help="adapter setting key=value"),
-           use_alt: Optional[bool] = typer.Option(None, "--use-alt/--no-alt"), reset: bool = False,
+           use_alt: Optional[bool] = typer.Option(None, "--use-alt/--no-alt", help="install the alternate build"),
+           reset: bool = typer.Option(False, help="start again from the suggested recipe"),
            as_is: Optional[bool] = typer.Option(None, "--as-is/--patch", help="install unchanged (already patched)"),
-           exe: Optional[str] = typer.Option(None, help="Rift games: the program that starts the game (relative)")):
+           exe: Optional[str] = typer.Option(None, help="PC VR games: the program that starts the game (relative)")):
     """Change a game's patch selection."""
     [pkg] = _pkgs(package, False)
     r = pipeline.reset_recipe(pkg) if reset else library.recipe_from_dict(library.game(pkg)["recipe"])
@@ -287,8 +309,9 @@ def recipe(package: str, enable: list[str] = typer.Option([], "--enable"), disab
 
 # ------------------------------------------------------------------------------------------ build / install / test
 @app.command()
-def build(package: Optional[str] = typer.Argument(None), all_: bool = typer.Option(False, "--all"),
-          outdir: Optional[Path] = None, verbose: bool = False):
+def build(package: Optional[str] = typer.Argument(None), all_: bool = typer.Option(False, "--all", help=ALL_HELP),
+          outdir: Optional[Path] = typer.Option(None, help="where to write the APKs (default: FramePort's data)"),
+          verbose: bool = typer.Option(False, help="print every step")):
     """Patch and sign (primary + alternate build when the recipe has one)."""
     failed = []
     for pkg in _pkgs(package, all_):
@@ -299,19 +322,21 @@ def build(package: Optional[str] = typer.Argument(None), all_: bool = typer.Opti
             if not info["ok"]:
                 failed.append(pkg)
         except Exception as exc:  # noqa: BLE001
-            typer.echo(f"{pkg}: FAILED {exc}")
+            typer.echo(f"{pkg}: FAILED {exc}", err=True)
             failed.append(pkg)
     raise typer.Exit(1 if failed else 0)
 
 
 @app.command()
-def install(package: Optional[str] = typer.Argument(None), all_: bool = typer.Option(False, "--all"),
-            frame: Optional[str] = typer.Option(None, help="steamos@host"), password: Optional[str] = None,
+def install(package: Optional[str] = typer.Argument(None), all_: bool = typer.Option(False, "--all", help=ALL_HELP),
+            frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
+            password: Optional[str] = typer.Option(None, help="the Frame's password (first connection only)"),
             apk_only: bool = typer.Option(False, help="reuse game data already on the Frame"),
             no_library: bool = typer.Option(False, help="don't add to the Steam library now"),
-            to: str = typer.Option("frame", help="frame, or pc (Oculus Rift games only: run on this PC via Revive)"),
+            to: str = typer.Option("frame", help="frame, or pc (PC VR games only: install on this PC)"),
             apk: Optional[Path] = typer.Option(None, help="install this APK instead of the last build (one game; e.g. "
                                                           "a test build signed with the game's key)")):
+    """Install games on the Frame (or PC VR games on this PC) and add them to the Steam library."""
     target = _target(frame, password, to)
     pkgs = _pkgs(package, all_)
     if apk and len(pkgs) != 1:
@@ -323,15 +348,16 @@ def install(package: Optional[str] = typer.Argument(None), all_: bool = typer.Op
 
 
 @app.command()
-def test(package: Optional[str] = typer.Argument(None), all_: bool = typer.Option(False, "--all"),
-         frame: Optional[str] = None, seconds: int = 45,
-         to: str = typer.Option("frame", help="frame, or pc (Rift games installed on this PC)")):
+def test(package: Optional[str] = typer.Argument(None), all_: bool = typer.Option(False, "--all", help=ALL_HELP),
+         frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
+         seconds: int = typer.Option(45, help="how long the game runs before it's stopped"),
+         to: str = typer.Option("frame", help="frame, or pc (PC VR games installed on this PC)")):
     """Headless launch on the Frame (or this PC) + log triage."""
     target = _target(frame, to=to)
     installed = {g["package"] for g in target.installed()}
     for pkg in _pkgs(package, all_):
         if pkg not in installed:
-            typer.echo(f"{pkg}: not installed on {target.label}")
+            typer.echo(f"{pkg}: not installed on {target.label}", err=True)
             continue
         s = pipeline.test_game(pkg, target, printing_reporter(False), seconds)
         typer.echo(f"{pkg}: {s['state']} ({s['verdict']}) furthest: {s['milestone']}"
@@ -339,18 +365,21 @@ def test(package: Optional[str] = typer.Argument(None), all_: bool = typer.Optio
 
 
 @app.command()
-def triage(logfile: Path, package: Optional[str] = None):
+def triage(logfile: Path = typer.Argument(..., help="a launch.log"),
+           package: Optional[str] = typer.Option(None, help="the game's package (keeps only its log lines)")):
     """Classify a launch.log offline."""
     from .validate.triage import triage as run_triage
 
     r = run_triage(logfile.read_text(errors="replace"), "UNKNOWN", package)
     typer.echo(f"furthest milestone: {r.milestone}; fps {r.fps}")
     for f in r.findings:
-        typer.echo(f"  {f.severity:7} {f.id}: {f.diagnosis}\n          {f.evidence[:200]}\n          suggest: {f.suggest}")
+        typer.echo(f"  {f.severity:7} {f.id}: {f.diagnosis}\n          {f.evidence[:200]}\n"
+                   f"          suggest: {f.suggest}")
 
 
 @app.command()
-def settings(package: str, values: list[str], frame: Optional[str] = None):
+def settings(package: str, values: list[str] = typer.Argument(..., help="key=value pairs"),
+             frame: Optional[str] = typer.Option(None, help=FRAME_HELP)):
     """Change FrameBridge settings of an installed game (no re-patching), e.g. scale=1.2."""
     target = _target(frame)
     kv = dict(v.split("=", 1) for v in values)
@@ -359,7 +388,8 @@ def settings(package: str, values: list[str], frame: Optional[str] = None):
 
 # ------------------------------------------------------------------------------------------ frame
 @frame_app.command("discover")
-def frame_discover(seconds: float = 4.0):
+def frame_discover(seconds: float = typer.Option(4.0, help="how long to listen")):
+    """Find Steam Frames (in Developer Mode) on the local network."""
     from .frame.discovery import browse
 
     for f in browse(seconds):
@@ -367,7 +397,7 @@ def frame_discover(seconds: float = 4.0):
 
 
 @frame_app.command("pair")
-def frame_pair(timeout: float = 600):
+def frame_pair(timeout: float = typer.Option(600, help="seconds to wait for the Frame")):
     """Serve the one-line bootstrap for the Frame and wait until it reports back."""
     import time
 
@@ -375,7 +405,8 @@ def frame_pair(timeout: float = 600):
     from .frame.pairing import PairingServer
 
     srv = PairingServer().start()
-    typer.echo("On the Frame, open Desktop Mode → Konsole and run:\n\n    " + srv.one_liner + "\n")
+    typer.echo("On the Frame, open the SteamVR dashboard → Launch a program → Desktop, then System → Konsole, and "
+               "run:\n\n    " + srv.one_liner + "\n")
     end = time.time() + timeout
     while time.time() < end and not srv.paired:
         time.sleep(1)
@@ -389,7 +420,8 @@ def frame_pair(timeout: float = 600):
 
 
 @frame_app.command("connect")
-def frame_connect(address: str, password: Optional[str] = typer.Option(None, prompt=False)):
+def frame_connect(address: str = typer.Argument(..., help="steamos@<host or IP>"),
+                  password: Optional[str] = typer.Option(None, prompt=False, help="the Frame's password (once)")):
     """Connect with SSH (password once), install FramePort's key and remember the Frame."""
     from .frame.connection import Frame, parse_target, save_target
 
@@ -399,12 +431,15 @@ def frame_connect(address: str, password: Optional[str] = typer.Option(None, pro
     info = f.agent("info")
     t.name = info["hostname"]
     save_target(t)
-    typer.echo(json.dumps({k: info[k] for k in ("hostname", "os", "os_version", "lepton", "steam_users", "free_bytes")}, indent=1))
+    keys = ("hostname", "os", "os_version", "lepton", "steam_users", "free_bytes")
+    typer.echo(json.dumps({k: info[k] for k in keys}, indent=1))
 
 
 @frame_app.command("cleanup")
-def frame_cleanup(frame: Optional[str] = None, keep_rollback: bool = typer.Option(False, help="keep previous-game.apk copies"),
-                  path: list[str] = typer.Option([], help="extra folder under the Frame's home to delete, e.g. ~/PATCHED")):
+def frame_cleanup(frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
+                  keep_rollback: bool = typer.Option(False, help="keep previous-game.apk copies"),
+                  path: list[str] = typer.Option([], help="extra folder under the Frame's home to delete, "
+                                                         "e.g. ~/PATCHED")):
     """Free space on the Frame: rollback APKs from reinstalls, leftover uploads, optional extra folders."""
     r = _target(frame).frame.agent("cleanup", rollback=not keep_rollback, paths=path)
     typer.echo(f"removed {len(r['removed'])} item(s), freed {r['freed_bytes'] / 2**30:.1f} GiB")
@@ -412,12 +447,13 @@ def frame_cleanup(frame: Optional[str] = None, keep_rollback: bool = typer.Optio
 
 @frame_app.command("send")
 def frame_send(paths: list[Path] = typer.Argument(..., help="files or folders to send"),
-               to: str = typer.Option("videos", help="destination: videos, downloads, documents, app, app-files"),
-               game: Optional[str] = typer.Option(None, help="package of the game, for --to app / app-files"),
+               to: str = typer.Option("videos", "--dest", "--to",
+                                      help="destination: videos, downloads, documents, app, app-files"),
+               game: Optional[str] = typer.Option(None, help="package of the game, for --dest app / app-files"),
                folder: str = typer.Option("", help="sub-folder inside the destination"),
                app: Optional[str] = typer.Option(None, help="package of a player: also add the files to its own folder "
                                                             "(e.g. 4XVR lists /sdcard/4XPlayer, not Movies)"),
-               frame: Optional[str] = None):
+               frame: Optional[str] = typer.Option(None, help=FRAME_HELP)):
     """Send files to apps on the Frame. videos/downloads/documents are shared by every Quest game (they appear as
     /sdcard/Movies, /sdcard/Download, /sdcard/Documents); app/app-files are one game's own storage. Apps find the
     files by browsing folders (Android's media index doesn't work in Lepton)."""
@@ -429,7 +465,8 @@ def frame_send(paths: list[Path] = typer.Argument(..., help="files or folders to
 
 
 @frame_app.command("storage")
-def frame_storage(game: Optional[str] = None, frame: Optional[str] = None):
+def frame_storage(game: Optional[str] = typer.Option(None, help="also show this game's own storage"),
+                  frame: Optional[str] = typer.Option(None, help=FRAME_HELP)):
     """Where files for Lepton apps go on the Frame (and where the apps see them)."""
     from .install import files
 
@@ -438,19 +475,20 @@ def frame_storage(game: Optional[str] = None, frame: Optional[str] = None):
 
 
 @frame_app.command("info")
-def frame_info(frame: Optional[str] = None):
+def frame_info(frame: Optional[str] = typer.Option(None, help=FRAME_HELP)):
+    """The Frame's SteamOS build, runtimes, storage and installed games (JSON)."""
     typer.echo(json.dumps(_target(frame).describe(), indent=1, default=str))
 
 
 @frame_app.command("controller-models")
-def frame_controller_models(frame: Optional[str] = None,
+def frame_controller_models(frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
                             convert: bool = typer.Option(False, help="also convert them (cached on the Frame)")):
     """SteamVR render models on the Frame and which ones serve as Steam Frame controller models (controller_models)."""
     typer.echo(json.dumps(_target(frame).frame.agent("controller_models", convert=convert), indent=1))
 
 
 @frame_app.command("proton")
-def frame_proton(frame: Optional[str] = None,
+def frame_proton(frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
                  install_: bool = typer.Option(False, "--install", help="install it (Steam on the Frame restarts once "
                                                "and downloads it; waits until done)"),
                  in_headset: bool = typer.Option(False, help="with --install: only ask Steam (confirm in the headset)"),
@@ -484,6 +522,7 @@ def frame_proton(frame: Optional[str] = None,
 # ------------------------------------------------------------------------------------------ pc (Revive)
 @pc_app.command("info")
 def pc_info():
+    """Steam, SteamVR and Revive on this PC (JSON)."""
     typer.echo(json.dumps(_target(None, to="pc").describe(), indent=1, default=str))
 
 
@@ -500,8 +539,10 @@ def pc_install_revive():
 @app.command()
 def parity(known_good: Path = typer.Option(..., help="folder of known-good game folders (PATCHED layout)"),
            sources: Path = typer.Option(..., help="folder with the original game dumps"),
-           outdir: Path = typer.Option(Path("parity-out")), only: list[str] = typer.Option([]),
-           report: Path = typer.Option(Path("parity-report.md")), keep: bool = False):
+           outdir: Path = typer.Option(Path("parity-out"), help="where the rebuilt APKs go"),
+           only: list[str] = typer.Option([], help="only games whose folder contains this (repeatable)"),
+           report: Path = typer.Option(Path("parity-report.md"), help="the report to write"),
+           keep: bool = typer.Option(False, help="keep work files")):
     """Rebuild every catalog game from its source dump and compare with the known-good APKs."""
     from .parity import run_parity
 
@@ -510,7 +551,7 @@ def parity(known_good: Path = typer.Option(..., help="folder of known-good game
 
 
 @app.command()
-def report(out: Path = typer.Option(Path("REPORT.md"))):
+def report(out: Path = typer.Option(Path("REPORT.md"), help="the file to write")):
     """Write a status report of every catalog game (markdown)."""
     from .report import write
 
@@ -518,10 +559,13 @@ def report(out: Path = typer.Option(Path("REPORT.md"))):
 
 
 @app.command("parity-device")
-def parity_device(results: Path = typer.Option(Path("parity-out/parity.json")), frame: Optional[str] = None,
+def parity_device(results: Path = typer.Option(Path("parity-out/parity.json"), help="parity.json from `parity`"),
+                  frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
                   baseline: Optional[Path] = typer.Option(None, help="baseline launch.txt from before the change"),
-                  report: Path = typer.Option(Path("parity-device-report.md")), only: list[str] = typer.Option([]),
-                  seconds: int = 45, test_only: bool = typer.Option(False, help="only re-run the launch tests")):
+                  report: Path = typer.Option(Path("parity-device-report.md"), help="the report to write"),
+                  only: list[str] = typer.Option([], help="only these games (repeatable)"),
+                  seconds: int = typer.Option(45, help="launch test length"),
+                  test_only: bool = typer.Option(False, help="only re-run the launch tests")):
     """Install the APKs rebuilt by `parity` on the Frame (APK only) and compare headless launches with a baseline."""
     from .parity import install_and_test
 
@@ -562,7 +606,7 @@ def _diag_target(no_frame: bool, frame: Optional[str], to: str):
     try:
         return _target(frame, to=to)
     except Exception as exc:  # noqa: BLE001  (offline Frame: PC-side data only)
-        typer.echo(f"({to} not reachable: {exc}; collecting the PC side only)")
+        typer.echo(f"({to} not reachable: {exc}; collecting the PC side only)", err=True)
         return None
 
 
@@ -571,12 +615,13 @@ def _open(url: str, browser: bool) -> None:
 
     typer.echo(url)
     if browser and not winhost.open_url(url):
-        typer.echo("(couldn't open a browser: open the link above)")
+        typer.echo("(couldn't open a browser: open the link above)", err=True)
 
 
 @diag_app.command("collect")
 def diag_collect(package: Optional[str] = typer.Argument(None, help="a game (omit for app-wide logs only)"),
-                 all_: bool = typer.Option(False, "--all"), frame: Optional[str] = None,
+                 all_: bool = typer.Option(False, "--all", help=ALL_HELP),
+                 frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
                  no_frame: bool = typer.Option(False, "--no-frame", help="don't contact the Frame"),
                  to: str = typer.Option("frame", help="where the game is installed: frame or pc"),
                  out: Optional[Path] = typer.Option(None, help="folder or .zip path (default: Documents)")):
@@ -587,7 +632,8 @@ def diag_collect(package: Optional[str] = typer.Argument(None, help="a game (omi
 
 
 @diag_app.command("inspect")
-def diag_inspect(bundle: Path, as_json: bool = typer.Option(False, "--json")):
+def diag_inspect(bundle: Path = typer.Argument(..., help="a diagnostics zip"),
+                 as_json: bool = typer.Option(False, "--json", help=JSON_HELP)):
     """Summarize a diagnostics zip and re-triage its launch logs with this version's signatures."""
     from .diag import bundle as b
 
@@ -616,10 +662,13 @@ def diag_inspect(bundle: Path, as_json: bool = typer.Option(False, "--json")):
 
 
 @diag_app.command("report")
-def diag_report(package: Optional[str] = typer.Argument(None), description: str = typer.Option("", "--text"),
-                frame: Optional[str] = None, no_frame: bool = typer.Option(False, "--no-frame"),
-                to: str = typer.Option("frame"), out: Optional[Path] = None,
-                browser: bool = typer.Option(True, "--browser/--no-browser")):
+def diag_report(package: Optional[str] = typer.Argument(None, help="the game (omit for an app problem)"),
+                description: str = typer.Option("", "--message", "--text", help="what went wrong"),
+                frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
+                no_frame: bool = typer.Option(False, "--no-frame", help="don't contact the Frame"),
+                to: str = typer.Option("frame", help="where the game is installed: frame or pc"),
+                out: Optional[Path] = typer.Option(None, help="folder or .zip path (default: Documents)"),
+                browser: bool = typer.Option(True, "--browser/--no-browser", help="open the issue in a browser")):
     """Collect a diagnostics zip and open a prefilled GitHub problem report (attach the zip there)."""
     from .core import winhost
 
@@ -642,7 +691,7 @@ def diag_report(package: Optional[str] = typer.Argument(None), description: str
 def share_recipe(package: str, status: str = typer.Option("works", help="works or issues"),
                  notes: str = typer.Option("", help="what you checked in the headset, known issues"),
                  frame: Optional[str] = typer.Option(None, help="include the Frame's SteamOS build"),
-                 browser: bool = typer.Option(True, "--browser/--no-browser")):
+                 browser: bool = typer.Option(True, "--browser/--no-browser", help="open the issue in a browser")):
     """Submit a working configuration: saves it as a known-good recipe and opens a prefilled GitHub issue."""
     if status not in ("works", "issues"):
         raise typer.BadParameter("--status must be works or issues")
@@ -653,9 +702,29 @@ def share_recipe(package: str, status: str = typer.Option("works", help="works o
     _open(pipeline.share_working_config(pkg, status, notes, info), browser)
 
 
-def main():  # pragma: no cover
-    app()
+def main() -> None:
+    """Entry point: errors end in one line on stderr and exit code 1 (FRAMEPORT_DEBUG=1 shows the traceback)."""
+    import os
+
+    try:
+        app()
+    except KeyboardInterrupt:
+        typer.echo("Cancelled.", err=True)
+        sys.exit(130)
+    except Exception as exc:  # noqa: BLE001
+        if os.environ.get("FRAMEPORT_DEBUG"):
+            raise
+        typer.echo(f"Error: {_describe(exc)}", err=True)
+        typer.echo("(set FRAMEPORT_DEBUG=1 to see the traceback)", err=True)
+        sys.exit(1)
+
+
+def _describe(exc: BaseException) -> str:
+    """A readable one-line reason (shared with the GUI: frameport.errors)."""
+    from .errors import explain
+
+    return explain(exc)
 
 
 if __name__ == "__main__":  # pragma: no cover
-    sys.exit(app())
+    main()

src/frameport/core/applog.py

@@ -32,7 +32,9 @@ def app_log_path() -> Path:
 
 def setup(component: str = "app") -> None:
     """Log to <data>/logs/app.log (2 MB × 3). Safe to call more than once; also records uncaught exceptions."""
-    if any(getattr(h, "_frameport", False) for h in log.handlers):
+    from .paths import removed
+
+    if removed() or any(getattr(h, "_frameport", False) for h in log.handlers):
         return
     try:
         handler = logging.handlers.RotatingFileHandler(app_log_path(), maxBytes=2 << 20, backupCount=3,
@@ -58,8 +60,19 @@ def _version() -> str:
     return __version__
 
 
+def shutdown() -> None:
+    """Close the log file (uninstall: an open file can't be deleted on Windows)."""
+    for h in [h for h in log.handlers if getattr(h, "_frameport", False)]:
+        log.removeHandler(h)
+        h.close()
+
+
 def save_job_log(kind: str, package: str | None, state: str, text: str) -> Path | None:
     """Keep a finished job's log (the GUI only holds it in memory); the last KEEP_JOB_LOGS are kept."""
+    from .paths import removed
+
+    if removed():
+        return None
     try:
         d = jobs_dir()
         name = re.sub(r"[^A-Za-z0-9._-]+", "_", f"{kind}-{package or 'app'}-{state}")[:120]

src/frameport/core/cache.py

@@ -11,9 +11,8 @@ from pathlib import Path
 
 import requests
 
-from .paths import user_data_dir
-
 from .. import REPO_URL, __version__
+from .paths import user_data_dir, write_atomic
 
 USER_AGENT = f"FramePort/{__version__} (+{REPO_URL})"
 _session = requests.Session()
@@ -38,7 +37,7 @@ def cached_text(name: str, url: str, max_age: float = 86400, fallback: str | Non
     if not fresh:
         try:
             text = http_get(url).text
-            path.write_text(text, encoding="utf-8")
+            write_atomic(path, text)
             return text
         except Exception:
             pass
@@ -57,7 +56,8 @@ def cached_json(name: str, url: str, max_age: float = 86400, fallback=None):
         return fallback
 
 
-def download(url: str, dest: Path, progress=None, expected_sha256: str | None = None, expected_sha1: str | None = None) -> Path:
+def download(url: str, dest: Path, progress=None, expected_sha256: str | None = None,
+             expected_sha1: str | None = None) -> Path:
     """Stream url to dest (atomic), verifying a checksum when given."""
     import hashlib
 

src/frameport/core/events.py

@@ -6,8 +6,8 @@ from __future__ import annotations
 
 import threading
 import time
+from collections.abc import Callable
 from dataclasses import dataclass, field
-from typing import Callable
 
 
 @dataclass

src/frameport/core/library.py

@@ -4,13 +4,18 @@ from __future__ import annotations
 import json
 import threading
 import time
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
 from dataclasses import asdict
 from pathlib import Path
 
 from .models import Analysis, Recipe
-from .paths import user_data_dir
+from .paths import user_data_dir, write_atomic
 
-_lock = threading.Lock()
+# One lock for every read-modify-write of library.json: jobs, the poll thread and the UI all change it, and a change
+# made between another thread's load() and save() would be lost. Re-entrant so edit() can call load()/save().
+_lock = threading.RLock()
+_last_retry = 0.0  # when migrations waiting for a game folder were last retried
 
 
 def _path() -> Path:
@@ -18,13 +23,69 @@ def _path() -> Path:
 
 
 def load() -> dict:
-    try:
-        data = json.loads(_path().read_text(encoding="utf-8"))
-    except (OSError, ValueError):
-        return {"games": {}, "settings": {}}
-    if _migrate(data):
+    with _lock:
+        try:
+            data = json.loads(_path().read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return {"games": {}, "settings": {}}
+        if _migrate(data) | _follow_catalog(data):
+            save(data)
+        return data
+
+
+@contextmanager
+def edit() -> Iterator[dict]:
+    """A read-modify-write of the whole library as one step: `with edit() as data: ...` (saved on exit)."""
+    with _lock:
+        data = load()
+        yield data
         save(data)
-    return data
+
+
+REFRESH_ON_UPDATE = True  # (tests switch it off: their hand-made libraries have no version marker)
+
+
+def _follow_catalog(data: dict) -> bool:
+    """Recipes FramePort derived (not ones the user edited) stay current: when their catalog entry is new or changed,
+    and once after every app update (new automatic fixes and suggestions in FramePort's code), the game's recipe is
+    derived again; a changed recipe shows Update on Frame."""
+    from .. import __version__
+    from ..recommend import catalog, engine
+
+    settings = data.setdefault("settings", {})
+    app_updated = REFRESH_ON_UPDATE and settings.get("recipes.app_version") != __version__
+    changed = app_updated
+    settings["recipes.app_version"] = __version__
+    for pkg, g in (data.get("games") or {}).items():
+        r, a = g.get("recipe"), g.get("analysis")
+        if app_updated and isinstance(a, dict):
+            changed |= _refresh_data_fields(g, a)
+        if not isinstance(r, dict) or not isinstance(a, dict) or r.get("source") == "user":
+            continue
+        entry = catalog.lookup(pkg)
+        if not app_updated and (entry is None or r.get("catalog_rev") == entry.rev()):
+            continue
+        try:
+            g["recipe"] = recipe_to_dict(engine.suggest(analysis_from_dict(a)))
+        except Exception:  # noqa: BLE001 - a malformed entry keeps its recipe
+            continue
+        changed = True
+    return changed
+
+
+def _refresh_data_fields(g: dict, a: dict) -> bool:
+    """Analysis fields read from the game's data folder (cheap, no APK analysis) that newer FramePort versions added:
+    filled in for games already in the library, so their patches are offered without a re-analysis."""
+    extra = a.setdefault("extra", {})
+    if "lang_packs" in extra or a.get("package", "").startswith("rift."):
+        return False
+    from ..analysis import langpacks
+
+    try:
+        extra["lang_packs"] = langpacks.find_tags(g.get("data_dir"))
+    except OSError:
+        return False
+    return True
 
 
 def _migrate(data: dict) -> bool:
@@ -60,7 +121,8 @@ def _migrate(data: dict) -> bool:
                     and not extra.get("openxr_native")):
                 r.setdefault("patches", {}).setdefault("pcvr.oculus_unreal", {})
                 r.setdefault("reasons", {}).setdefault(
-                    "pcvr.oculus_unreal", "Unreal game: its Oculus plugin checks for the Oculus service before it starts VR.")
+                    "pcvr.oculus_unreal",
+                    "Unreal game: its Oculus plugin checks for the Oculus service before it starts VR.")
         done.append("oculus_unreal")
         changed = True
     if "rift_revive_correct" not in done:
@@ -68,7 +130,7 @@ def _migrate(data: dict) -> bool:
         # VR; OpenXR/SteamVR-native and catalog games keep their own settings). The dump is never modified (as_is).
         from ..recommend import engine
 
-        for pkg, g in (data.get("games") or {}).items():
+        for g in (data.get("games") or {}).values():
             a = g.get("analysis") or {}
             if not (isinstance(g.get("recipe"), dict) and (a.get("extra") or {}).get("kind") == "rift"):
                 continue
@@ -85,7 +147,7 @@ def _migrate(data: dict) -> bool:
         from ..analysis import rift
         from ..recommend import engine
 
-        for pkg, g in (data.get("games") or {}).items():
+        for g in (data.get("games") or {}).values():
             a = g.get("analysis") or {}
             if not (isinstance(g.get("recipe"), dict) and (a.get("extra") or {}).get("kind") == "rift"):
                 continue
@@ -118,24 +180,25 @@ def _migrate(data: dict) -> bool:
         # Rift games get a launch mode from their files (repack with bundled Revive → run directly; SteamVR/OpenXR-
         # capable → run directly with arguments; Oculus-only → FramePort's Revive). Re-analyze (keeping the chosen
         # exe) and re-derive the recipe; a repack launched through a second Revive failed (e.g. its entitlement check).
-        from ..analysis import rift
-        from ..recommend import engine
-
+        waiting = []
         for pkg, g in (data.get("games") or {}).items():
             a = g.get("analysis") or {}
             if not (isinstance(g.get("recipe"), dict) and (a.get("extra") or {}).get("kind") == "rift"):
                 continue
-            gd = g.get("game_dir") or (a.get("extra") or {}).get("folder")
-            try:
-                if not (gd and Path(gd).is_dir()):
-                    continue
-                an = rift.analyze(Path(gd), exe=g.get("exe") or (a.get("extra") or {}).get("exe"))
-                g["analysis"] = asdict(an)
-                g["recipe"] = recipe_to_dict(engine.suggest(an))
-            except Exception:  # noqa: BLE001
-                continue
+            if not _rift_launch_mode(g):
+                waiting.append(pkg)  # game folder not reachable now (e.g. a drive not connected): retried later
+        if waiting:
+            data["settings"].setdefault("migrations_waiting", {})["rift_launch_modes"] = waiting
         done.append("rift_launch_modes")
         changed = True
+    global _last_retry
+    waiting = (data["settings"].get("migrations_waiting") or {}).get("rift_launch_modes") or []
+    if waiting and time.time() - _last_retry > 600:  # games skipped because their folder wasn't there (checked
+        _last_retry = time.time()                     # every 10 min: load() runs often, a missing drive is slow)
+        still = [p for p in waiting if p in data.get("games", {}) and not _rift_launch_mode(data["games"][p])]
+        if still != waiting:
+            data["settings"]["migrations_waiting"]["rift_launch_modes"] = still
+            changed = True
     if "quest_binary_fixes_v2" not in done:
         # Quest recipes gain the default-on binary fixes: the swapchain size guard (every overport build) and the
         # Vulkan shim (Unreal)
@@ -156,6 +219,16 @@ def _migrate(data: dict) -> bool:
                     r.setdefault("reasons", {}).setdefault(pid, s.reason)
         done.append("quest_binary_fixes_v2")
         changed = True
+    if "flat_hide_navbar" not in done:
+        # Android apps without VR gain the default-on "Hide Android's navigation bar" patch
+        for g in (data.get("games") or {}).values():
+            a, r = g.get("analysis") or {}, g.get("recipe")
+            if isinstance(r, dict) and (a.get("extra") or {}).get("vr_kind") == "none":
+                r.setdefault("patches", {}).setdefault("device.hide_navbar", {})
+                r.setdefault("reasons", {}).setdefault(
+                    "device.hide_navbar", "2D app: Android's navigation buttons would cover the app's own controls.")
+        done.append("flat_hide_navbar")
+        changed = True
     if "rift_steamvr_tuning" not in done:
         # PC VR recipes gain automatic SteamVR performance settings (refresh rate / motion smoothing on frame drops)
         for g in (data.get("games") or {}).values():
@@ -169,18 +242,42 @@ def _migrate(data: dict) -> bool:
     return changed
 
 
+def _rift_launch_mode(g: dict) -> bool:
+    """Re-analyze a Rift game (keeping the chosen exe) and re-derive its recipe. False if its folder isn't there."""
+    from ..analysis import rift
+    from ..recommend import engine
+
+    a = g.get("analysis") or {}
+    gd = g.get("game_dir") or (a.get("extra") or {}).get("folder")
+    if not (gd and Path(gd).is_dir()):
+        return False
+    try:
+        an = rift.analyze(Path(gd), exe=g.get("exe") or (a.get("extra") or {}).get("exe"))
+        g["analysis"] = asdict(an)
+        g["recipe"] = recipe_to_dict(engine.suggest(an))
+    except Exception:  # noqa: BLE001 - an unreadable game keeps its recipe
+        pass
+    return True
+
+
 def save(data: dict) -> None:
     with _lock:
-        tmp = _path().with_suffix(".tmp")
-        tmp.write_text(json.dumps(data, indent=1, default=str), encoding="utf-8")
-        tmp.replace(_path())
+        write_atomic(_path(), json.dumps(data, indent=1, default=str))
 
 
 def upsert_game(package: str, **fields) -> dict:
-    data = load()
-    entry = data["games"].setdefault(package, {"package": package, "added": time.time()})
-    entry.update(fields)
-    save(data)
+    with edit() as data:
+        entry = data["games"].setdefault(package, {"package": package, "added": time.time()})
+        entry.update(fields)
+    return entry
+
+
+def update_game(package: str, fn: Callable[[dict], None]) -> dict | None:
+    """Change one game's entry in place, atomically (fn mutates the entry). None if the game isn't there."""
+    with edit() as data:
+        entry = data["games"].get(package)
+        if entry is not None:
+            fn(entry)
     return entry
 
 
@@ -193,9 +290,8 @@ def games() -> list[dict]:
 
 
 def remove_game(package: str) -> None:
-    data = load()
-    data["games"].pop(package, None)
-    save(data)
+    with edit() as data:
+        data["games"].pop(package, None)
 
 
 def setting(key: str, default=None):
@@ -203,9 +299,16 @@ def setting(key: str, default=None):
 
 
 def set_setting(key: str, value) -> None:
-    data = load()
-    data.setdefault("settings", {})[key] = value
-    save(data)
+    with edit() as data:
+        data.setdefault("settings", {})[key] = value
+
+
+def update_setting(key: str, fn: Callable, default=None):
+    """Set a setting from its current value, atomically: value = fn(current or default). Returns the new value."""
+    with edit() as data:
+        settings = data.setdefault("settings", {})
+        settings[key] = value = fn(settings.get(key, default))
+    return value
 
 
 def recipe_to_dict(r: Recipe) -> dict:
@@ -228,5 +331,6 @@ def analysis_from_dict(d: dict) -> Analysis:
         elif f.default is not dataclasses.MISSING or f.default_factory is not dataclasses.MISSING:  # type: ignore[misc]
             continue  # let the dataclass default apply
         else:
-            kwargs[f.name] = "" if f.type == "str" else [] if "list" in str(f.type) else                 0 if f.type == "int" else False if f.type == "bool" else None
+            kwargs[f.name] = ("" if f.type == "str" else [] if "list" in str(f.type) else
+                              0 if f.type == "int" else False if f.type == "bool" else None)
     return Analysis(**kwargs)