FramePort 0.7.1

Notes: language packs verified with Deadpool VR (English dialogue with the patch on)
One job queue per process (Flet builds a new app per window session: an old session's job ran unseen and the same game was built twice at once in one work folder, both failed) and one build per game at a time
2026-10-06 17:00:43 +02:00 · 2026-10-04 19:24:49 -04:00 · 2026-10-04 19:23:33 -04:00 · 2026-10-04 19:23:32 -04:00 · 2026-10-04 19:23:32 -04:00 · 2026-10-04 19:23:32 -04:00
103 changed files with 5753 additions and 217 deletions
@@ -414,9 +414,89 @@ for steamos (Steam Input) → agent v33 `_keyboard` uinput keyboard ("Type on Fr
 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.
@@ -23,6 +23,14 @@ uv run ruff check .          # lint
  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:
@@ -26,7 +26,8 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V
 - **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, a Files tab with drag and drop.
+- **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.

 ## Quick start
@@ -36,11 +37,12 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V
 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 press the **Steam button → Power → Switch to Desktop**.
-   3. Open the app menu (bottom-left corner), search for **Konsole** and open it.
+   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 and the Frame returns to its normal view; that's expected. If
+   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).
@@ -68,6 +70,10 @@ will attempt to guess key patches. If you find a new config that works for an ap

 **[List of tested games](docs/GAMES.md)**

+**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

 [OVRPort](https://github.com/Android-XR-Bridge/OVRPort) (Quest → OpenXR, originally
@@ -35,7 +35,7 @@ import sys
 import time
 import zlib

-AGENT_VERSION = 33
+AGENT_VERSION = 41
 HOME = os.path.expanduser("~")
 STEAM = os.path.join(HOME, ".local/share/Steam")
 ANCHORS = os.path.join(HOME, "Applications/quest-frame")
@@ -537,6 +537,11 @@ def stop_steam():
        time.sleep(1)
    if run(["pgrep", "-x", "steam"]).returncode == 0:
        raise AgentError("Steam did not close")
+    for _ in range(15):  # Steam's helpers can still be writing its config (shortcuts.vdf) for a moment
+        if run(["pgrep", "-f", "steamwebhelper|steam.sh|reaper SteamLaunch"]).returncode:
+            break
+        time.sleep(1)
+    time.sleep(2)
    return service


@@ -564,6 +569,48 @@ def steam_users():
        if os.path.isdir(os.path.join(STEAM, "userdata")) else []


+STEAMID64_BASE = 76561197960265728
+
+
+def active_steam_user():
+    """userdata folder (account id) of the most recent Steam login (config/loginusers.vdf), if it has one."""
+    try:
+        text = open(os.path.join(STEAM, "config/loginusers.vdf"), encoding="utf-8", errors="replace").read()
+    except OSError:
+        return None
+    users = steam_users()
+    for sid, body in re.findall(r'"(\d{17})"\s*\{([^}]*)\}', text):
+        if re.search(r'"MostRecent"\s+"1"', body) and str(int(sid) - STEAMID64_BASE) in users:
+            return str(int(sid) - STEAMID64_BASE)
+    return None
+
+
+def library_users():
+    """Steam accounts whose library gets FramePort's shortcuts: every account on the Frame, the signed-in one first
+    (loginusers.vdf's MostRecent isn't always the account signed in on the Frame: GitHub #4/#21 got shortcuts in the
+    other account; an extra shortcut in an unused account does no harm)."""
+    users = steam_users()
+    if not users:
+        raise AgentError("Steam has no signed-in account on this Frame yet; sign in to Steam on the Frame first")
+    active = active_steam_user()
+    return [active] + [u for u in users if u != active] if active else users
+
+
+def shortcut_appid_for(exe):
+    """appid of the shortcut whose Exe is `exe` in the signed-in account's library (any account if unknown); None
+    when it isn't in the library."""
+    for u in library_users():
+        vdf = os.path.join(STEAM, "userdata", u, "config/shortcuts.vdf")
+        try:
+            root = vdf_decode(open(vdf, "rb").read()) if os.path.exists(vdf) else {}
+        except (OSError, AgentError):
+            continue
+        for v in (root.get("shortcuts") or {}).values():
+            if isinstance(v, dict) and v.get("Exe") == exe and v.get("appid"):
+                return v["appid"] & 0xFFFFFFFF
+    return None
+
+
 def container_running(appid):
    p = run(["podman", "ps", "--format", "{{.Names}}"])
    return f"lepton-steamlaunch-{appid}" in p.stdout.split()
@@ -637,6 +684,58 @@ def battery_state():
    return battery


+BOOT_STATE = os.path.join(HOME, ".cache/frameport-boot.json")
+# what the last lines of a boot's journal say when it was shut down or rebooted on purpose (a crash, a GPU hang that
+# reset the Frame or a pulled battery leaves none of these)
+CLEAN_SHUTDOWN = ("Reached target System Power Off", "Reached target System Reboot", "Reached target Shutdown",
+                  "System is powering down", "System is rebooting", "systemd-shutdown", "Power-Off", "Rebooting.")
+
+
+def boot_state():
+    """This boot and how the previous one ended: {"boot_id", "boot_time", "prev_clean" (True/False/None = unknown),
+    "last_launch" ({"package", "title", "time"}: the FramePort game started last before this boot)}. Worked out once
+    per boot (cached), so the app can say "your Frame restarted while <game> was running"."""
+    try:
+        boot_id = open("/proc/sys/kernel/random/boot_id").read().strip()
+    except OSError:
+        return None
+    try:
+        cached = json.load(open(BOOT_STATE))
+        if cached.get("boot_id") == boot_id:
+            return cached
+    except (OSError, ValueError):
+        pass
+    boot_time = None
+    try:
+        for line in open("/proc/stat"):
+            if line.startswith("btime "):
+                boot_time = int(line.split()[1])
+    except OSError:
+        pass
+    try:
+        tail = run(["journalctl", "-b", "-1", "-n", "120", "-q", "--no-pager", "-o", "cat"]).stdout
+    except OSError:
+        tail = ""
+    prev_clean = any(m in tail for m in CLEAN_SHUTDOWN) if tail.strip() else None
+    last = None
+    for d in cmd_list_installed({})["games"]:
+        log = os.path.join(d["base"], "launch.log")
+        try:
+            t = os.path.getmtime(log)
+        except OSError:
+            continue
+        if (boot_time is None or t < boot_time) and (last is None or t > last["time"]):
+            last = {"package": d["package"], "title": d.get("title") or d["package"], "time": t}
+    state = {"boot_id": boot_id, "boot_time": boot_time, "prev_clean": prev_clean, "last_launch": last}
+    try:
+        os.makedirs(os.path.dirname(BOOT_STATE), exist_ok=True)
+        with open(BOOT_STATE, "w") as f:
+            json.dump(state, f)
+    except OSError:
+        pass
+    return state
+
+
 def cmd_battery(args):
    return {"battery": battery_state()}

@@ -660,6 +759,7 @@ def cmd_info(args):
        "steam_running": run(["pgrep", "-x", "steam"]).returncode == 0,
        "host_fixes": ensure_host_fixes(), "kernel_keys": key_usage(),
        "proton": cmd_proton_status({}) if args.get("proton", True) else None,
+        "boot": boot_state(),
        "battery": battery_state(),
    }

@@ -735,9 +835,11 @@ def vdf_encode(obj):
    return bytes(out) + bytes([TYPE_END])


-def upsert_shortcut(vdf_path, exe, title, start_dir, icon="", tag="Quest on Frame", launch_options="", tags=None):
+def upsert_shortcut(vdf_path, exe, title, start_dir, icon="", tag="Quest on Frame", launch_options="", tags=None,
+                    openvr=True, write=True):
    """Add/update a non-Steam shortcut (matched by Exe, so its appid never changes). `tags` (genres, the user's tags)
-    are merged with tags already on the shortcut, so ones set in Steam are kept."""
+    are merged with tags already on the shortcut, so ones set in Steam are kept. write=False: change nothing, return
+    (appid, whether shortcuts.vdf would change)."""
    data = open(vdf_path, "rb").read() if os.path.exists(vdf_path) else b""
    root = vdf_decode(data) if data else {"shortcuts": {}}
    shortcuts = root.setdefault("shortcuts", {})
@@ -751,8 +853,10 @@ def upsert_shortcut(vdf_path, exe, title, start_dir, icon="", tag="Quest on Fram
        merged = list(dict.fromkeys(have + [t for t in [tag] + list(tags) if t]))
        entry["tags"] = {str(i): t for i, t in enumerate(merged)}
    entry.update(appname=title, Exe=exe, StartDir=start_dir, icon=icon or entry.get("icon", ""), ShortcutPath="",
-                 LaunchOptions=launch_options, IsHidden=0, AllowDesktopConfig=1, AllowOverlay=1, OpenVR=1, Devkit=0,
-                 DevkitGameID="", DevkitOverrideAppID=0, FlatpakAppID="")
+                 LaunchOptions=launch_options, IsHidden=0, AllowDesktopConfig=1, AllowOverlay=1,
+                 OpenVR=1 if openvr else 0, Devkit=0, DevkitGameID="", DevkitOverrideAppID=0, FlatpakAppID="")
+    if not write:
+        return ident, vdf_encode(root) != data
    if data:
        backup_vdf(vdf_path)
    os.makedirs(os.path.dirname(vdf_path), exist_ok=True)
@@ -861,6 +965,11 @@ def cmd_shortcuts(args):
              if isinstance(r, dict) and str(r.get("exe", "")).startswith('"' + ANCHORS)]
    if not packages and not remove:
        return {"started": False}
+    current = cmd_shortcut_status({})
+    alive = time.time() - float(current.get("started") or 0) < 60  # a waiting worker rewrites its status every 10 s
+    if current.get("state") == "waiting" and alive and set(packages) <= set(current.get("packages") or []) \
+            and not remove:
+        return {"started": False, "waiting": True}  # the update for these games already waits (Gaming Mode / game)
    os.makedirs(os.path.dirname(STATUS_FILE), exist_ok=True)
    with open(STATUS_FILE, "w") as f:
        json.dump({"state": "running", "packages": packages, "started": time.time()}, f)
@@ -871,48 +980,121 @@ def cmd_shortcuts(args):
    return {"started": True, "unit": unit}


+def shortcut_args(pkg):
+    """(exe, title, start dir, icon, tag, tags, openvr) of an installed game's shortcut."""
+    anchor = os.path.join(ANCHORS, pkg)
+    dep = json.load(open(os.path.join(anchor, "deployment.json")))
+    icon = next(iter(glob.glob(os.path.join(anchor, "artwork/icon.*"))), "")
+    flat = dep.get("vr") is False
+    tag = ("Windows game on Frame" if flat else "PC VR on Frame") if dep.get("kind") == "pcvr" else "Quest on Frame"
+    return f'"{anchor}/launch.sh"', dep["title"], anchor, icon, tag, dep.get("tags") or [], not flat
+
+
+def library_changes(users, packages):
+    """Whether shortcuts.vdf would change for any of these games (a reinstall usually changes nothing)."""
+    for user in users:
+        vdf = os.path.join(STEAM, "userdata", user, "config/shortcuts.vdf")
+        for pkg in packages:
+            exe, title, start, icon, tag, tags, openvr = shortcut_args(pkg)
+            if upsert_shortcut(vdf, exe, title, start, icon, tag, tags=tags, openvr=openvr, write=False)[1]:
+                return True
+    return False
+
+
+def shortcuts_lost(users, packages, wait=25):
+    """Packages whose shortcut isn't in any account's shortcuts.vdf once Steam has started again (Steam saving its own
+    copy over ours on the way out looked like a successful install with no game in the library, GitHub #27)."""
+    for _ in range(wait):  # until Steam runs again (it rewrites shortcuts.vdf while starting, too)
+        if run(["pgrep", "-x", "steam"]).returncode == 0:
+            break
+        time.sleep(1)
+    time.sleep(8)
+    lost = []
+    for pkg in packages:
+        exe = shortcut_args(pkg)[0]
+        found = False
+        for user in users:
+            vdf = os.path.join(STEAM, "userdata", user, "config/shortcuts.vdf")
+            try:
+                root = vdf_decode(open(vdf, "rb").read()) if os.path.exists(vdf) else {}
+            except (OSError, AgentError):
+                continue
+            entries = (root.get("shortcuts") or {}).values()
+            found = found or any(isinstance(v, dict) and v.get("Exe") == exe for v in entries)
+        if not found:
+            lost.append(pkg)
+    return lost
+
+
+def desktop_mode():
+    """Desktop Mode is open: it runs inside Steam's session, so a Steam restart would end it (and FramePort itself when
+    it runs on the Frame); library changes wait until the user is back in Gaming Mode."""
+    return run(["pgrep", "-x", "plasmashell"]).returncode == 0
+
+
+def game_running():
+    """A game is being played on the Frame (any Lepton game container, or a FramePort PC VR game)."""
+    names = run(["podman", "ps", "--format", "{{.Names}}"]).stdout.split()
+    if any(n.startswith("lepton-steamlaunch-") for n in names):
+        return True
+    return any(pcvr_pids(d["base"]) for d in cmd_list_installed({})["games"] if d.get("kind") == "pcvr")
+
+
 def shortcuts_worker(payload):
+    """One library update at a time: two at once each read shortcuts.vdf, changed it and wrote it back, so the second
+    write brought back a shortcut the first had removed (uninstalling two games quickly left Roblox in Steam)."""
+    import fcntl
+
+    os.makedirs(os.path.dirname(STATUS_FILE), exist_ok=True)
+    with open(STATUS_FILE + ".lock", "w") as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        _shortcuts_worker(payload)
+
+
+def _shortcuts_worker(payload):
    args = json.loads(payload)
    result = {"state": "done", "added": [], "errors": [], "finished": None}
+    os.makedirs(os.path.dirname(STATUS_FILE), exist_ok=True)
    try:
-        users = steam_users()
-        if len(users) != 1:
-            raise AgentError(f"found {len(users)} Steam users; not guessing which library to edit")
-        vdf = os.path.join(STEAM, "userdata", users[0], "config/shortcuts.vdf")
+        users = library_users()
+        if not args.get("remove") and not library_changes(users, args["packages"]):
+            # nothing to change in shortcuts.vdf (e.g. a reinstall): only the artwork, no Steam restart
+            for user in users:
+                update_library(user, args["packages"], result, shortcuts=False)
+            result["unchanged"] = True
+            result["finished"] = time.time()
+            with open(STATUS_FILE, "w") as f:
+                json.dump(result, f)
+            return
+        deadline = time.time() + 12 * 3600
+        while time.time() < deadline:  # restarting Steam would end the game being played, or Desktop Mode
+            reason = "game" if game_running() else "desktop" if desktop_mode() else None
+            if not reason:
+                break
+            with open(STATUS_FILE, "w") as f:
+                json.dump({"state": "waiting", "reason": reason, "packages": args["packages"],
+                           "started": time.time()}, f)
+            time.sleep(10)
        try:
            service = stop_steam()
        except AgentError:
            raise AgentError("Steam did not close; library not modified") from None
-        grid = os.path.join(os.path.dirname(vdf), "grid")
-        os.makedirs(grid, exist_ok=True)
-        for r in args.get("remove", []):  # uninstalled games
-            try:
-                if remove_shortcut(vdf, r["exe"]):
-                    result.setdefault("removed", []).append(r["exe"])
-                for art in grid_files(grid, r.get("appid") or ""):
-                    os.remove(art)
-            except Exception as exc:  # noqa: BLE001
-                result["errors"].append(f"{r.get('exe')}: {exc}")
-        for pkg in args["packages"]:
-            try:
-                anchor = os.path.join(ANCHORS, pkg)
-                dep = json.load(open(os.path.join(anchor, "deployment.json")))
-                icon = next(iter(glob.glob(os.path.join(anchor, "artwork/icon.*"))), "")
-                tag = "PC VR on Frame" if dep.get("kind") == "pcvr" else "Quest on Frame"
-                got = upsert_shortcut(vdf, f'"{anchor}/launch.sh"', dep["title"], anchor, icon, tag,
-                                      tags=dep.get("tags") or [])
-                for kind, suffix in (("portrait", "p"), ("landscape", ""), ("hero", "_hero"), ("logo", "_logo")):
-                    img = next(iter(glob.glob(os.path.join(anchor, f"artwork/{kind}.*"))), None)
-                    if not img:
-                        continue
-                    for old in glob.glob(os.path.join(grid, f"{got}{suffix}.*")):
-                        os.remove(old)
-                    shutil.copy(img, os.path.join(grid, f"{got}{suffix}{os.path.splitext(img)[1]}"))
-                result["added"].append({"package": pkg, "appid": got, "expected": dep["appid"]})
-            except Exception as exc:  # noqa: BLE001
-                result["errors"].append(f"{pkg}: {exc}")
+        for user in steam_users():  # uninstalled games leave every account's library
+            remove_from_library(user, args.get("remove", []), result)
+        for user in users:
+            update_library(user, args["packages"], result)
        if service or args.get("restart", True):
            start_steam(service)
+            lost = shortcuts_lost(users, args["packages"])
+            if lost:  # Steam wrote its old copy back over ours (it was still saving): once more, then report
+                result["retried"] = lost
+                service = stop_steam()
+                for user in users:
+                    update_library(user, lost, {"added": [], "errors": result["errors"]})
+                start_steam(service)
+                for pkg in shortcuts_lost(users, lost):
+                    result["added"] = [a for a in result["added"] if a["package"] != pkg]
+                    result["errors"].append(f"{pkg}: Steam removed the new library entry again after restarting")
    except Exception as exc:  # noqa: BLE001
        result["state"] = "failed"
        result["errors"].append(str(exc))
@@ -922,6 +1104,46 @@ def shortcuts_worker(payload):
        json.dump(result, f)


+def remove_from_library(user, remove, result):
+    """Remove uninstalled games' shortcuts + grid art from one Steam account (Steam is closed)."""
+    vdf = os.path.join(STEAM, "userdata", user, "config/shortcuts.vdf")
+    grid = os.path.join(os.path.dirname(vdf), "grid")
+    for r in remove:
+        try:
+            if remove_shortcut(vdf, r["exe"]):
+                result.setdefault("removed", []).append(r["exe"])
+            for art in grid_files(grid, r.get("appid") or ""):
+                os.remove(art)
+        except Exception as exc:  # noqa: BLE001
+            result["errors"].append(f"{r.get('exe')}: {exc}")
+
+
+def update_library(user, packages, result, shortcuts=True):
+    """Add/update installed games' shortcuts + grid art in one Steam account (Steam is closed; shortcuts=False: only
+    the grid art of shortcuts that are already right, while Steam runs)."""
+    vdf = os.path.join(STEAM, "userdata", user, "config/shortcuts.vdf")
+    grid = os.path.join(os.path.dirname(vdf), "grid")
+    os.makedirs(grid, exist_ok=True)
+    for pkg in packages:
+        try:
+            anchor = os.path.join(ANCHORS, pkg)
+            dep = json.load(open(os.path.join(anchor, "deployment.json")))
+            exe, title, start, icon, tag, tags, openvr = shortcut_args(pkg)
+            got = upsert_shortcut(vdf, exe, title, start, icon, tag, tags=tags, openvr=openvr, write=shortcuts)
+            got = got[0] if not shortcuts else got
+            for kind, suffix in (("portrait", "p"), ("landscape", ""), ("hero", "_hero"), ("logo", "_logo")):
+                img = next(iter(glob.glob(os.path.join(anchor, f"artwork/{kind}.*"))), None)
+                if not img:
+                    continue
+                for old in glob.glob(os.path.join(grid, f"{got}{suffix}.*")):
+                    os.remove(old)
+                shutil.copy(img, os.path.join(grid, f"{got}{suffix}{os.path.splitext(img)[1]}"))
+            if not any(a["package"] == pkg for a in result["added"]):
+                result["added"].append({"package": pkg, "appid": got, "expected": dep["appid"]})
+        except Exception as exc:  # noqa: BLE001
+            result["errors"].append(f"{pkg}: {exc}")
+
+
 def cmd_shortcut_status(args):
    try:
        return json.load(open(STATUS_FILE))
@@ -965,6 +1187,9 @@ def steam_gameid(appid):
    return (int(appid) << 32) | 0x02000000


+NOT_IN_LIBRARY = "not in the Frame's Steam library"
+
+
 def cmd_launch(args):
    """Start an installed game the way the headset's library does: ask the running Steam to launch its shortcut, so
    it gets Steam's VR session, overlay and controller setup (unlike launch_test's direct, headless start)."""
@@ -974,7 +1199,10 @@ def cmd_launch(args):
        raise AgentError(f"{pkg} is not installed")
    if run(["pgrep", "-x", "steam"]).returncode != 0:
        raise AgentError("Steam isn't running on the Frame")
-    gid = steam_gameid(dep["appid"])
+    appid = shortcut_appid_for(f'"{os.path.join(ANCHORS, pkg)}/launch.sh"')
+    if appid is None:  # Steam would only say "Game configuration unavailable"
+        raise AgentError(f"{NOT_IN_LIBRARY}: {dep.get('title') or pkg}")
+    gid = steam_gameid(appid)  # the shortcut's own id (it keeps its first one when the title changes)
    # systemd-run: the launch request must outlive this SSH session
    run(["systemd-run", "--user", "--collect", "--quiet", f"--unit=frameport-launch-{int(time.time())}",
         "steam", "-ifrunning", f"steam://rungameid/{gid}"])
@@ -1164,9 +1392,11 @@ LAUNCH_SH = (r"""#!/usr/bin/env bash
 set -euo pipefail
 app_dir={base_q}
 [[ -d "$app_dir/lepton-app" ]] || {{ echo "Game files missing at $app_dir (storage not mounted?)" >&2; exit 1; }}
-# Some games (Unreal cloud saves) create folders without write/search permission inside Lepton,
-# which silently breaks saving. Repair them before and during every launch.
-fix_perms() {{ find "$app_dir/lepton-data/external" -type d ! -perm -u+rwx -exec chmod u+rwx {{}} + 2>/dev/null ||"""
+# Some games (Unreal cloud saves, SUPERHOT's cloud/data: mode 1700) create folders without write/search permission
+# for the app inside Lepton (it writes through the folder's group), which breaks saving or makes the game quit.
+# Repair them before and during every launch.
+fix_perms() {{ find "$app_dir/lepton-data/external" -type d \( ! -perm -u+rwx -o ! -perm -g+rwx \) """
+r"""-exec chmod u+rwx,g+rwx {{}} + 2>/dev/null ||"""
 r""" true; }}
 # Android can't create an app's external files/cache folders inside Lepton ("Invalid mkdirs path ... not a known app
 # path"): getExternalCacheDir() then returns nothing, which breaks e.g. Whirligig's video player cache. Create them"""
@@ -1665,8 +1895,7 @@ set -euo pipefail
 base={base_q}
 [[ -d "$base/game" ]] || {{ echo "Game files missing at $base (storage not mounted?)" >&2; exit 1; }}
 export SteamAppId={appid}
-export SteamGameId={appid}
-export STEAM_COMPAT_APP_ID={appid}
+{steam_game_id}export STEAM_COMPAT_APP_ID={appid}
 export STEAM_COMPAT_DATA_PATH="$base/compatdata"
 export STEAM_COMPAT_CLIENT_INSTALL_PATH={steam_q}
 export STEAM_COMPAT_INSTALL_PATH="$base/game"
@@ -1733,7 +1962,7 @@ OCULUS_HMD_HELPER = "fp_oculushmd.exe"


 def write_proton_launcher(anchor, base, pkg, title, appid, tool, exe_rel, revive, env, xr_layer=False, game_args=(),
-                          oculus_hmd=False):
+                          oculus_hmd=False, vr=True):
    exe = os.path.join(base, "game", exe_rel)
    prefix = compat_command(tool["dir"])
    injector = os.path.join(base, "revive", "ReviveInjector.exe")
@@ -1754,6 +1983,8 @@ def write_proton_launcher(anchor, base, pkg, title, appid, tool, exe_rel, revive
    text = LAUNCH_PROTON_SH.format(
        title=title.replace("\n", " "), pkg=pkg, base_q=shlex.quote(base), appid=appid, steam_q=shlex.quote(STEAM),
        tool=tool["name"], extra_env=extra, workdir=("/" + shlex.quote(workdir)) if workdir else "",
+        # Proton sets up VR (vrclient, wineopenxr) only when SteamGameId is set: a flat Windows game goes without
+        steam_game_id=f"export SteamGameId={appid}\n" if vr else "",
        xr_layer=XR_LAYER_ENV if xr_layer else "",
        command=" ".join(shlex.quote(a) for a in argv))
    path = os.path.join(anchor, "launch.sh")
@@ -1863,8 +2094,9 @@ def cmd_finalize_pcvr(args):
        raise AgentError(f"{OCULUS_HMD_HELPER} missing")
    set_crash_reporter(base, enabled=not args.get("no_crash_reporter"))
    set_libovr_redirect(base, exe_rel, enabled=bool(args.get("libovr_redirect")), bundled=not revive)
+    vr = args.get("vr", True) is not False  # False: a flat Windows game (no VR at all)
    write_proton_launcher(anchor, base, pkg, title, appid, tool, exe_rel, revive, args.get("env"), xr_layer,
-                          args.get("game_args") or [], oculus_hmd)
+                          args.get("game_args") or [], oculus_hmd, vr=vr)
    art_in = os.path.join(base, "incoming-artwork")
    if os.path.isdir(art_in):
        shutil.rmtree(os.path.join(anchor, "artwork"), ignore_errors=True)
@@ -1872,7 +2104,7 @@ def cmd_finalize_pcvr(args):
    dep = {"package": pkg, "kind": "pcvr", "appid": int(appid), "base": base, "title": title, "exe": exe_rel,
           "tags": args.get("tags") or [],
           "sha256": args.get("exe_sha256"), "revive": revive, "revive_version": args.get("revive_version"),
-           "proton": tool["name"], "xr_layer": xr_layer, "oculus_hmd": oculus_hmd,
+           "proton": tool["name"], "xr_layer": xr_layer, "oculus_hmd": oculus_hmd, "vr": vr,
           "libovr_redirect": bool(args.get("libovr_redirect")),
           "recipe": args.get("recipe"),
           "installed_by": "frameport",
@@ -1956,7 +2188,7 @@ def cmd_uninstall(args):
        remove_tree(base)
    anchor = os.path.join(ANCHORS, pkg)
    removed_sc = False
-    if args.get("remove_shortcut") and len(steam_users()) == 1:
+    if args.get("remove_shortcut") and steam_users():
        # Steam keeps its own copy of shortcuts.vdf and writes it back: change it only with Steam closed (worker)
        removed_sc = cmd_shortcuts({"remove": [{"exe": f'"{anchor}/launch.sh"', "appid": dep.get("appid")}]})["started"]
    if not keep_data or base != anchor:
@@ -2144,6 +2376,18 @@ def cmd_collect_diag(args):
                          "{{.Names}} {{.Status}}"]).stdout[-20000:]
    host["steam_running"] = run(["pgrep", "-x", "steam"]).returncode == 0
    host["uptime"] = _tail("/proc/uptime", 200)
+    host["boot"] = boot_state()
+    # how the previous boot ended: errors and kernel (GPU/msm/kgsl, OOM, panic) warnings before a crash or reset; and
+    # this boot's kernel warnings (a GPU hang the Frame recovered from only ends the game: no reboot, no tombstone)
+    for name, boot, extra in (("previous-boot-errors.txt", "-1", ["-p", "err"]),
+                              ("previous-boot-kernel.txt", "-1", ["-k", "-p", "warning"]),
+                              ("this-boot-kernel.txt", "0", ["-k", "-p", "warning"])):
+        try:
+            text = run(["journalctl", "-b", boot, *extra, "-n", "400", "-q", "--no-pager"]).stdout[-max_bytes:]
+        except OSError:
+            text = ""
+        if text.strip():
+            files[name] = text
    host["installed"] = [{k: g.get(k) for k in ("package", "title", "kind", "appid", "version", "agent_version")}
                         for g in cmd_list_installed({})["games"]]
    out = {"agent_version": AGENT_VERSION, "host": host, "files": files}
@@ -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
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
-# FramePort one-time Steam Frame setup. Run in the Frame's Desktop Mode terminal (Konsole):
+# 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).
 #
@@ -128,6 +129,6 @@ if [[ ! -x "$DEVKIT_HELPER" || ! -f "$STEAM_CONFIG" ]] || \
    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 Desktop Mode in a few seconds and the Frame returns to its"
+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."
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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+
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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}
@@ -1,21 +1,32 @@
 # 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 |  |
@@ -26,21 +37,35 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | 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. |
@@ -31,12 +31,12 @@ 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. Press the **Steam button → Power → Switch to Desktop**.
-   2. Open the app menu (bottom-left corner), search for **Konsole** and open it.
+   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 and the Frame returns to its normal view; that's expected. If
+   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
@@ -54,6 +54,14 @@ Lepton from the Steam Frame page afterwards if it's missing.
 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
@@ -119,6 +127,11 @@ 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.

+**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).
+
 ## 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.
@@ -15,6 +15,9 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 |---|---|---|
 | 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 |
@@ -30,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`) |
@@ -50,6 +54,14 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Quest app keeps recentering / snapping the view when you turn your head; log shows session state 5→4→3→4→5 within a second | the Frame briefly takes focus; the app recenters on focus changes | unfixed: hiding the dips (debounce) made AC Nexus stay black, so it was removed |
 | Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | upload in the Files tab (Videos = /sdcard/Movies) and browse folders in the app |
 | 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 |

@@ -69,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
@@ -78,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
@@ -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). |
@@ -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));
+    }
+}
@@ -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
@@ -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,
@@ -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);
+}
@@ -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]()
@@ -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);
+}
@@ -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
+}
@@ -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;
@@ -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")
@@ -13,6 +13,8 @@ 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:
@@ -22,7 +24,9 @@ def short(note: str) -> str:


 def render() -> str:
-    entries = [e for e in catalog.load().values() if e.origin == "bundled" and e.status in STATUS]
+    # 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:
@@ -32,6 +36,8 @@ def render() -> str:
    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")

@@ -1,2 +1,2 @@
 # The FramePort version: the single source (pyproject reads it via hatch; CI checks a release tag matches it).
-__version__ = "0.6.1"
+__version__ = "0.7.1"
@@ -93,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:
@@ -193,6 +196,12 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
            "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,
        },
    )
@@ -238,7 +247,7 @@ def missing_ovr_symbols(lib_bytes: dict[str, bytes]) -> set[str]:
        return set()
    exported = set(elf.dyn_symbols(loader, True))
    linked = set(elf.needed(loader))
-    for extra in ("libovrplatformcompat.so", "libovrstubs.so"):
+    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()
@@ -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).
@@ -2,7 +2,9 @@
 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 libil2cpp.so (sha256), so a rebuild of the same game doesn't run Cpp2IL again."""
+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
@@ -18,9 +20,15 @@ _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."""
+    """{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:
@@ -33,14 +41,22 @@ def parse_methods(cs_text: str, names: list[str]) -> dict[str, tuple[int, int]]:
    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) -> Path:
-    return cache_dir() / "il2cpp" / (hashlib.sha256(lib).hexdigest()[:32] + ".json")
+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]],
@@ -48,9 +64,11 @@ def find_methods(lib: bytes, metadata: bytes, unity_version: str, wanted: dict[s
    """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)
+    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", {})}
@@ -72,7 +90,10 @@ def find_methods(lib: bytes, metadata: bytes, unity_version: str, wanted: dict[s
                              timeout=timeout, cwd=tmp)
        root = t / "out" / "DiffableCs"
        if not root.is_dir():
-            raise RuntimeError("Cpp2IL couldn't read this game's code: " + (proc.stdout + proc.stderr)[-400:].strip())
+            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
@@ -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)
@@ -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)
@@ -76,7 +76,8 @@ def steam_set(package: str, title: str = "", apk: str | Path | None = None) -> d
    title = title or package
    out_dir = fetch.artwork_dir(package) / "steam"
    out_dir.mkdir(parents=True, exist_ok=True)
-    placeholder = not (set(src) - {"icon"})  # no store art (at most the APK's icon): the name on a coloured tile
+    # 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 ''}")
@@ -299,6 +300,8 @@ def original_platform(entry: dict) -> str:
    """What the game was made for (a Steam tag)."""
    extra = (entry.get("analysis") or {}).get("extra") or {}
    if entry.get("kind") == "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")
@@ -310,7 +313,9 @@ def steam_tags(entry: dict, where: str = "frame") -> list[str]:
    from ..targets.pc_revive import TAG

    kind = ((entry.get("analysis") or {}).get("extra") or {}).get("vr_kind") or "quest"
-    runs = TAG if where != "frame" else "PC VR on Frame" if entry.get("kind") == "rift" else \
+    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]
@@ -86,7 +86,20 @@ def ready_thumb(path: Path, width: int, kind: str | None = None) -> Path | None:
    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()


@@ -405,7 +405,8 @@ def frame_pair(timeout: float = typer.Option(600, help="seconds to wait for the
    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)
@@ -28,7 +28,7 @@ def load() -> dict:
            data = json.loads(_path().read_text(encoding="utf-8"))
        except (OSError, ValueError):
            return {"games": {}, "settings": {}}
-        if _migrate(data):
+        if _migrate(data) | _follow_catalog(data):
            save(data)
        return data

@@ -42,6 +42,52 @@ def edit() -> Iterator[dict]:
        save(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:
    """One-time updates of stored recipes when a new default is introduced (each runs once per library)."""
    done = data.setdefault("settings", {}).setdefault("migrations", [])
@@ -82,6 +82,7 @@ class Recipe:
    as_is: bool = False  # install the game unchanged (already patched): no overport / Frame fixes / Revive
    overport: bool = True  # False: an ordinary Android app: no VR translation (overport) and no FrameBridge adapter
    reasons: dict[str, str] = field(default_factory=dict)  # patch id -> why it was suggested
+    catalog_rev: str = ""  # CatalogEntry.rev() it was derived from: a changed catalog entry re-derives the recipe

    def enabled(self, patch_id: str) -> bool:
        return patch_id in self.patches
@@ -39,6 +39,12 @@ def bootstrap_dir() -> Path:
    return DATA_ROOT / "bootstrap"


+def _on_frame() -> bool:
+    from ..frame.local import on_frame
+
+    return on_frame()
+
+
 def user_data_dir() -> Path:
    """Tools, keystores, work dirs and settings. Override with FRAMEPORT_HOME."""
    if os.environ.get("FRAMEPORT_HOME"):
@@ -48,7 +54,10 @@ def user_data_dir() -> Path:
    elif sys.platform == "darwin":
        base = Path.home() / "Library/Application Support/FramePort"
    else:
-        base = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local/share")) / "frameport"
+        # on the Frame itself ~/.local/share/frameport is the agent's folder (and its purge removes it): the app's own
+        # data (library, tools, game signing keys) lives next to it
+        name = "frameport-app" if _on_frame() else "frameport"
+        base = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local/share")) / name
    if not _removed.is_set():
        base.mkdir(parents=True, exist_ok=True)
    return base
@@ -46,8 +46,12 @@ def explain(exc: BaseException) -> str:
    low = msg.lower()
    if paramiko and isinstance(exc, paramiko.ChannelException):
        return tr("The connection to the Frame is busy. Try again in a moment.")
-    if "authentication failed" in low:
-        return msg  # already says what to do (run the bootstrap / enter the password)
+    if "authentication failed" in low or "no authentication methods available" in low:
+        if "password was refused" in low:
+            return tr("The Frame refused that password. Check it, or run the first-time setup instead: Steam Frame → "
+                      "Show setup command.")
+        return tr("This Frame isn't set up for FramePort yet. Run the first-time setup: Steam Frame → Show setup "
+                  "command.")
    if is_connection_error(exc):
        return tr("Can't reach your Frame. Make sure it's on, awake and on the same network, then try again.")
    if isinstance(exc, OSError) and exc.errno == errno.ENOSPC:
@@ -9,11 +9,13 @@ from __future__ import annotations
 import contextlib
 import hashlib
 import json
+import logging
 import os
 import posixpath
 import re
 import stat
 import threading
+import time
 from dataclasses import dataclass, field
 from pathlib import Path

@@ -21,9 +23,30 @@ import paramiko

 from ..core.paths import agent_file, ssh_dir, user_data_dir, write_atomic

+log = logging.getLogger(__name__)
+
 REMOTE_AGENT_DIR = ".local/share/frameport/agent"


+class FrameNotPaired(ConnectionError):
+    """SSH works but none of FramePort's ways in was accepted: the Frame hasn't run the first-time setup (or the
+    password was wrong). The message keeps "authentication failed" for older callers."""
+
+    def __init__(self, tried_password: bool, details: list[str]):
+        self.tried_password = tried_password
+        self.details = details
+        reason = ("the password was refused" if tried_password
+                  else "this Frame doesn't know FramePort yet")
+        super().__init__(f"SSH authentication failed: {reason}. Run the first-time setup on the Frame (Steam Frame → "
+                         "Show setup command)." + (f" ({'; '.join(details)})" if details else ""))
+
+
+def _no_auth_methods(exc: BaseException) -> bool:
+    """paramiko ends a key/agent attempt that had nothing to offer (no SSH keys on this PC, no agent) with a plain
+    SSHException, not an AuthenticationException: it's a failed login all the same, not a network problem."""
+    return isinstance(exc, paramiko.SSHException) and "no authentication methods available" in str(exc).lower()
+
+
 def app_key() -> paramiko.Ed25519Key:
    path = ssh_dir() / "id_ed25519"
    if not path.exists():
@@ -93,7 +116,14 @@ _saved_cache: tuple[float, list] = (-1.0, [])


 def saved_targets() -> list[FrameTarget]:
-    """The remembered Frames (read again only when frames.json changed: the sidebar asks several times a second)."""
+    """The remembered Frames (read again only when frames.json changed: the sidebar asks several times a second).
+    FramePort running on a Frame remembers that Frame itself (127.0.0.1) the first time."""
+    if not (user_data_dir() / "frames.json").exists():
+        return _local_frame()
+    return _read_saved()
+
+
+def _read_saved() -> list[FrameTarget]:
    global _saved_cache
    path = user_data_dir() / "frames.json"
    try:
@@ -111,8 +141,62 @@ def saved_targets() -> list[FrameTarget]:
        return []


+def is_unreachable(exc: BaseException) -> bool:
+    """The Frame isn't there at all (asleep, off the network): retrying an upload at once won't help."""
+    return isinstance(exc, (ConnectionRefusedError, TimeoutError, paramiko.ssh_exception.NoValidConnectionsError))
+
+
+def _local_frame() -> list[FrameTarget]:
+    """On a Frame with nothing remembered yet: this Frame, with FramePort's key authorized for the local user."""
+    from . import local
+
+    if not local.on_frame():
+        return []
+    try:
+        local.authorize_self(app_public_key())
+    except OSError:
+        pass
+    target = FrameTarget("127.0.0.1", local.local_user(), 22, local.LOCAL_NAME)
+    save_target(target)
+    return [target]
+
+
+def replace_target(old_host: str, target: FrameTarget) -> None:
+    """The remembered Frame at old_host is now at target.host (same device: its SSH host key matched)."""
+    items = [FrameTarget(target.host, t.user, t.port, t.name) if t.host == old_host else t for t in _read_saved()]
+    if target.host not in [t.host for t in items]:
+        items.insert(0, target)
+    seen, out = set(), []
+    for t in items:
+        if t.host not in seen:
+            seen.add(t.host)
+            out.append(t)
+    write_atomic(user_data_dir() / "frames.json", json.dumps([t.__dict__ for t in out], indent=2))
+
+
+def server_key(host: str, port: int = 22, timeout: float = 5) -> paramiko.PKey | None:
+    """The SSH host key a device presents (no login)."""
+    import socket
+
+    try:
+        sock = socket.create_connection((host, port), timeout=timeout)
+    except OSError:
+        return None
+    transport = paramiko.Transport(sock)
+    try:
+        transport.start_client(timeout=timeout)
+        return transport.get_remote_server_key()
+    except (OSError, paramiko.SSHException, EOFError):
+        return None
+    finally:
+        transport.close()
+
+
+_last_relocate = -1e9
+
+
 def save_target(target: FrameTarget) -> None:
-    items = [t for t in saved_targets() if t.host != target.host]
+    items = [t for t in _read_saved() if t.host != target.host]
    items.insert(0, target)
    write_atomic(user_data_dir() / "frames.json", json.dumps([t.__dict__ for t in items], indent=2))

@@ -133,6 +217,9 @@ def bundled_agent_version() -> int | None:
 RUN_TIMEOUT = 120  # seconds: default bound for one remote command's output


+NOT_IN_LIBRARY = "not in the Frame's Steam library"  # agent cmd_launch's error when the shortcut is missing
+
+
 class AgentFailed(RuntimeError):
    pass

@@ -260,6 +347,48 @@ class Frame:

    # ------------------------------------------------------------------ connect
    def connect(self, timeout: float = 10) -> Frame:
+        try:
+            return self._connect(timeout)
+        except OSError:
+            if self.target.host in ("127.0.0.1", "localhost"):  # FramePort on the Frame itself: sshd isn't running
+                raise ConnectionError("FramePort runs on this Frame but can't reach it over SSH: turn on Developer "
+                                      "Mode (Steam → Settings → System → Developer Mode), then try again") from None
+            moved = self.relocate()  # the router gave the Frame a new address (it's remembered by address)
+            if not moved:
+                raise
+            log.info("Frame moved from %s to %s", self.target.host, moved)
+            old, self.target.host = self.target.host, moved
+            self._connect(timeout)
+            replace_target(old, self.target)
+            return self
+
+    def relocate(self) -> str | None:
+        """The Frame's new address when it no longer answers at the remembered one: a device on the network whose
+        SSH host key is the one this PC saw at the old address (checked before logging in). At most once a minute (the
+        GUI retries every few seconds while a Frame sleeps)."""
+        global _last_relocate
+        if time.monotonic() - _last_relocate < 60 or self.target.host not in [t.host for t in saved_targets()]:
+            return None
+        _last_relocate = time.monotonic()
+        hk = paramiko.HostKeys()
+        try:
+            hk.load(str(ssh_dir() / "known_hosts"))
+        except OSError:
+            return None
+        known = hk.lookup(self.target.host if self.target.port == 22 else f"[{self.target.host}]:{self.target.port}")
+        if not known:
+            return None
+        from .discovery import browse
+
+        for f in browse(seconds=3.0):
+            if f.host == self.target.host or f.port != self.target.port:
+                continue
+            key = server_key(f.host, f.port)
+            if key is not None and known.get(key.get_name()) == key:
+                return f.host
+        return None
+
+    def _connect(self, timeout: float) -> Frame:
        known = ssh_dir() / "known_hosts"
        known.touch(exist_ok=True)
        kwargs = dict(hostname=self.target.host, port=self.target.port, username=self.target.user, timeout=timeout,
@@ -283,12 +412,17 @@ class Frame:
            except paramiko.AuthenticationException as exc:
                client.close()
                errors.append(f"{attempt}: {exc}")
+            except paramiko.SSHException as exc:
+                client.close()
+                if not _no_auth_methods(exc):
+                    raise
+                # (Reddit, 2026-10-03: this ended the loop before the password was tried)
+                errors.append(f"{attempt}: {exc}")
            except BaseException:
                client.close()
                raise
        else:
-            raise ConnectionError("SSH authentication failed (" + "; ".join(errors) + "). Run the FramePort "
-                                  "bootstrap on the Frame or enter the steamos password.")
+            raise FrameNotPaired(bool(self.password), errors)
        client.save_host_keys(str(known))
        transport = client.get_transport()
        transport.set_keepalive(15)
@@ -308,6 +442,8 @@ class Frame:
        presents the same SSH host key as this connection. Returns (frame, link name); (self, "") if none."""
        import socket

+        if self.target.host in ("127.0.0.1", "localhost"):  # FramePort on the Frame itself: nothing is faster
+            return self, ""
        key = self.client.get_transport().get_remote_server_key()
        for iface in FAST_LINKS:
            for name, ip in self.addresses():
@@ -408,10 +544,24 @@ class Frame:
        if dirs:
            self.run("xargs -0 mkdir -p", stdin="\0".join(dirs))

-    def put(self, local: Path, remote: str, progress=None, resume: bool = True, mkdir: bool = True) -> None:
+    def put(self, local: Path, remote: str, progress=None, resume: bool = True, mkdir: bool = True,
+            attempts: int = 3) -> None:
        """Upload with resume: data goes to <remote>.part, appended from the existing size, then renamed. progress may
-        raise (e.g. Cancelled): the .part stays and the next put continues from there."""
-        local = Path(local)
+        raise (e.g. Cancelled): the .part stays and the next put continues from there. A failed transfer is resumed
+        up to `attempts` times (Windows: an occasional OSError [Errno 22] mid-upload that the next try got past)."""
+        for attempt in range(attempts):
+            try:
+                return self._put(Path(local), remote, progress, resume, mkdir)
+            except OSError as exc:
+                if attempt == attempts - 1 or is_unreachable(exc):
+                    raise
+                log.warning("upload of %s failed (%s), resuming", Path(local).name, exc)
+                time.sleep(2)
+                if not self.alive():
+                    self.close()
+                    self.connect()
+
+    def _put(self, local: Path, remote: str, progress, resume: bool, mkdir: bool) -> None:
        size = local.stat().st_size
        part = remote + ".part"
        if mkdir:
@@ -0,0 +1,45 @@
+"""FramePort running on the Steam Frame itself (Desktop Mode, the Linux ARM64 bundle): it manages the same device over
+SSH to 127.0.0.1, so everything else (agent, installs, launch tests) works unchanged. Developer Mode has to be on for
+sshd; FramePort authorizes its own key for the local user, no pairing needed."""
+from __future__ import annotations
+
+import functools
+import getpass
+import os
+import platform
+from pathlib import Path
+
+LOCAL_NAME = "This Frame (experimental)"  # FramePort running on the Frame itself
+
+
+@functools.lru_cache(maxsize=1)
+def on_frame() -> bool:
+    """SteamOS on ARM64 (the Steam Frame)."""
+    if platform.machine().lower() not in ("aarch64", "arm64"):
+        return False
+    try:
+        text = Path("/etc/os-release").read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return False
+    return any(line.strip().lower() in ("id=steamos", 'id="steamos"') for line in text.splitlines())
+
+
+def authorize_self(public_key: str) -> bool:
+    """Add FramePort's public key to this user's ~/.ssh/authorized_keys (once). True if it was added."""
+    ssh = Path.home() / ".ssh"
+    keys = ssh / "authorized_keys"
+    ssh.mkdir(mode=0o700, exist_ok=True)
+    have = keys.read_text(encoding="utf-8", errors="replace") if keys.exists() else ""
+    if public_key.strip() in have:
+        return False
+    with open(keys, "a", encoding="utf-8") as f:
+        f.write(("" if not have or have.endswith("\n") else "\n") + public_key.strip() + " frameport-local\n")
+    os.chmod(keys, 0o600)
+    return True
+
+
+def local_user() -> str:
+    try:
+        return getpass.getuser()
+    except Exception:  # noqa: BLE001
+        return "steamos"
@@ -210,7 +210,7 @@ def install_pcvr(frame: Frame, plan: PcvrPlan, reporter: Reporter) -> dict:
        env=launch_env(plan.recipe),
        game_args=game_args(plan.recipe), no_crash_reporter="pcvr.no_crash_reporter" in plan.recipe.patches,
        libovr_redirect="pcvr.libovr_redirect" in plan.recipe.patches,
-        exe_sha256=plan.exe_sha256, revive_version=plan.revive_version,
+        exe_sha256=plan.exe_sha256, revive_version=plan.revive_version, vr=not is_flat_windows(plan.package),
        recipe={"patches": sorted(plan.recipe.patches), "source": plan.recipe.source},
    )
    reporter.log(f"installed at {result['base']} (Proton {result['proton']}, Steam shortcut id {result['appid']})")
@@ -325,6 +325,14 @@ def _tags(package: str) -> list[str]:
    return steam_tags(entry) if entry else []


+def is_flat_windows(package: str) -> bool:
+    """A Windows game without VR (added with "Add one game folder…"): Proton runs it as a window, no VR setup."""
+    from ..core import library
+
+    g = library.game(package) or {}
+    return bool(((g.get("analysis") or {}).get("extra") or {}).get("flat"))
+
+
 def _flatscreen(package: str) -> bool:
    """An Android app without VR: Lepton must show it as a flat window (it never draws through OpenXR)."""
    from ..core import library
@@ -384,8 +392,19 @@ def add_to_steam(frame: Frame, packages: list[str], reporter: Reporter, wait: fl
            continue
        if status.get("state") in ("done", "failed"):
            break
+        if status.get("state") == "waiting":  # Steam restarts later: after the game, or back in Gaming Mode
+            reporter.check("Steam library", None,
+                           "added when you're back in Gaming Mode (Steam has to restart for it)"
+                           if status.get("reason") == "desktop" else
+                           "added when the game that's running now is closed (Steam has to restart for it)")
+            return status
+    added = {a["package"] for a in status.get("added", [])}
    for a in status.get("added", []):
        reporter.check(f"Steam library: {a['package']}", True, f"shortcut {a['appid']}")
    for e in status.get("errors", []):
        reporter.check("Steam library", False, e)
+    if not status.get("errors"):
+        for pkg in packages:
+            if pkg not in added:  # no answer in time: say so (Play adds a missing shortcut itself)
+                reporter.check(f"Steam library: {pkg}", False, "the Frame didn't confirm the library entry in time")
    return status
@@ -56,6 +56,7 @@
 "A new FramePort version is ready to install": "",
 "A recipe is the list of patches FramePort applies to a game before installing it. Known-good recipes were tested on a Frame; the others are suggested from the game's engine and VR API. Hover a patch for why it's there.": "",
 "A VR app made for another Android headset. OpenXR apps are translated like Quest games; apps built on a headset maker's own SDK (Pico, HTC Wave) can't run on the Frame.": "",
+ "A Windows game without VR, added with \"Add one game folder…\". On the Frame, Proton runs it as a window (like Steam's own Windows games); it's in the Frame's Steam library.": "",
 "A Windows PC VR game (OpenXR, SteamVR or Oculus). It runs on this PC with SteamVR, or on the Frame with Proton. Oculus-only games also need Revive (Oculus → OpenXR).": "",
 "A zip with FramePort's logs, the game's recipe and analysis, launch-test logs and the Frame's runtime details — enough to debug without the game files. IP addresses, host and user names, home folders and Steam ids are replaced by placeholders. Attach it to a GitHub issue.": "",
 "ABIs": "",
@@ -70,6 +71,7 @@
 "Add games": "",
 "Add one game folder…": "",
 "Add this tag": "",
+ "Add to Steam library: {title}": "",
 "Add videos": "",
 "Add videos and files…": "",
 "Add your games": "",
@@ -97,6 +99,8 @@
 "Allows very large pictures (8K video, theatres) instead of quitting.": "",
 "Already patched: don't change the game's files": "",
 "Already patched: install as is (skip patching)": "",
+ "Already set up: on your network": "",
+ "Also delete this game's files on this PC ({size})": "",
 "Also in your library: {value} version": "",
 "Also remove FramePort's games and files from the Frame": "",
 "An ordinary Android app or game (no VR). It's installed unchanged and runs in Lepton, Valve's Android container.": "",
@@ -111,6 +115,7 @@
 "APK": "",
 "Appearance": "",
 "Apply the suggested patches and reinstall": "",
+ "Apps that suggest controller bindings only for Meta's newer profiles (Touch Plus, Touch Pro), which the Frame's runtime rejects (XR_ERROR_PATH_UNSUPPORTED), get the same bindings as oculus/touch_controller instead (components Touch lacks are dropped). Without it such apps get no controller input.": "",
 "Artwork for {get}": "",
 "Artwork updated ({src}). The Frame's Steam library still shows the old art.": "",
 "Artwork updated for {get}": "",
@@ -127,6 +132,7 @@
 "Automatic SteamVR performance settings (this PC)": "",
 "Back to library": "",
 "Back up the signing keys ({len}) to {shown_dir} first": "",
+ "Before a swapchain image is handed to the Frame, wait until the game's GPU work on it has finished, for games that hand over images early (an eye flickers or jitters). Costs some frame time. 2 = only after the first 60 s (compare both in one session).": "",
 "Before each Play on this PC, FramePort reads SteamVR's record of the game's last session (frames dropped; frame times from fpsVR if installed). If it dropped frames, it lowers the game's refresh rate to one whose frame budget fits (e.g. 96 → 90 Hz) and turns motion smoothing on, through SteamVR's per-application settings; each later session can step down again. Set a refresh rate or smoothing mode here to choose yourself. Ignored on the Frame.": "",
 "Best guess": "",
 "Blit quads flagged XrCompositionLayerImageLayoutFB VERTICAL_FLIP upside down (Vulkan). Fixes UI panels and text that show upside down (e.g. Assassin's Creed Nexus).": "",
@@ -235,6 +241,7 @@
 ],
 "Downloading…": "",
 "Downloads": "",
+ "Draws each eye separately; try it when one eye shows a grey or broken picture.": "",
 "Drop invalid layers": "",
 "Drop layers whose swapchain failed or whose extension isn't enabled.": "",
 "Drop to upload": "",
@@ -280,16 +287,20 @@
 "Fix upside-down menus": "",
 "Fixes graphics code that the Frame's drivers reject (black screen with sound).": "",
 "Flat": "",
+ "focus_hold hides focus dips up to this long (100-5000). Longer for a headset whose wear sensor flickers (\"HMD off\" for 0.5-2 s while worn, e.g. Blade & Sorcery pausing); taking the headset off or the system menu pauses the game only after this long.": "",
 "Folder": "",
 "folder and everything in it": "",
 "Folder name": "",
 "Folder to upload to the Frame": "",
 "Folder with VR games (Android APKs or PC VR games)": "",
+ "For apps that only know Quest 3/Pro controllers: without it they get no buttons.": "",
+ "For games that crash right after you return to them (e.g. after the Steam menu).": "",
 "For games that pause or recenter when the headset briefly loses focus.": "",
 "For games that show the headset's own controllers. Takes effect after a reinstall.": "",
 "For games whose menus or screens jump to wherever you look.": "",
 "For heavy games that use application space warp: it causes artifacts or hangs on non-Quest runtimes (e.g. Asgard's Wrath 2, Batman: Arkham Shadow).": "",
 "For mixed-reality-only games. On the Frame, passthrough is emulated by the FrameBridge adapter (greyscale cameras).": "",
+ "For one eye looking wrong (e.g. a jittering right eye): logs each eye's submitted pose against a fresh one, the eye-to-eye relation and when each eye's image was released, also into framebridge.log in the game's storage (some games stop Android's log early). No effect on the game.": "",
 "For Unreal games that close themselves right after starting (e.g. Phantom: Covert Ops). Also disables the in-game Quit.": "",
 "Force enable passthrough": "",
 "Found": "",
@@ -359,7 +370,7 @@
 "Hide Quest foveation": "",
 "Hides Android's back/home/recents buttons, which cover the app's own buttons.": "",
 "Hides Quest foveation extensions the Frame runtime lacks.": "",
- "Hides the Frame's brief focus dips (well under a second) once the game has been focused for a few seconds. For games that recentre or pause every time focus returns.": "",
+ "Hides the Frame's brief focus dips (up to a second) once the game has been focused for a second. For games that recentre or pause every time focus returns.": "",
 "High": "",
 "Higher is sharper but needs more power.": "",
 "Higher keeps more detail but uses more memory.": "",
@@ -372,6 +383,7 @@
 "If the pointer doesn't hit what you aim at, tilt it up or down.": "",
 "If Windows asked whether FramePort may use the network, allow it (Private networks).": "",
 "If you know the Frame's address.": "",
+ "Ignore focus dips up to": "",
 "In your Steam library": "",
 "In your Steam library · launch settings changed — update it": "",
 "Install": "",
@@ -403,7 +415,7 @@
 "It has a known blocker on the Steam Frame.": "",
 "It has issues: share…": "",
 "it stopped at '{value}'": "",
- "It trusts this app, turns on Developer Mode and installs Lepton if needed. Turning on Developer Mode closes Desktop Mode; the setup finishes on its own and FramePort connects by itself. You only do this once.": "",
+ "It trusts this app, turns on Developer Mode and installs Lepton if needed. Turning on Developer Mode closes the desktop; the setup finishes on its own and FramePort connects by itself. You only do this once.": "",
 "It was removed from the library.": "",
 "It works: share…": "",
 "Java runtime": "",
@@ -412,12 +424,14 @@
 "Keep converted copies on this PC after installing (FramePort converts again for every install, so they're only needed for inspecting a build)": "",
 "Keep game saves on the Frame": "",
 "Keep menus in place": "",
+ "Keeps a smoothing setting off that the game turns on itself and that can freeze the Frame.": "",
 "Keeps one label so the title is stable.": "",
 "Keeps one name for the game, so it shows the same everywhere.": "",
 "Keyboard connected to {label}.": "",
 "Keyboard disconnected: {error}": "",
 "KiB": "",
 "Language": "",
+ "Language packs from the game's files": "",
 "Last build": "",
 "Last launch test: {get} · furthest: {value}": "",
 "Later": "",
@@ -436,9 +450,13 @@
 "Lepton is Valve's Android container on the Frame. Quest games run inside it, one container per game. It needs Developer Mode.": "",
 "Lepton only launches an activity with category LAUNCHER (Quest apps often use INFO). Symptom when missing: launch.log says 'APP_ACTIVITY is empty' and nothing starts.": "",
 "Lepton runs VR apps headless: their Android window is never shown, so it never gets keyboard focus and no key press (Steam's on-screen keyboard, a USB/Bluetooth keyboard, Type on Frame) reaches the app's text fields. With Lepton's lepton-show-flatscreen marker the window is shown (behind the VR view, which keeps working) and Steam's keyboard opens for a selected text field. Steam lists the shown window as \"Gamescope\" (the Frame's compositor). Pairs with \"Make Unity text fields work without a system keyboard\".": "",
+ "Lepton's Android has no clipboard service, and SDL's Java code (SDL2 and LÖVE games, e.g. Dramatic Shape) registers a clipboard listener at start without checking, so the app crashes with a NullPointerException in SDLClipboardHandler. That call is skipped (an in-place edit of classes.dex).": "",
 "Lets games made for Oculus PCs run on SteamVR.": "",
 "Lets games written for newer OpenXR versions run on the Frame.": "",
 "Lets mixed-reality games start even though they insist on a camera view of your room.": "",
+ "Lets older Unity games start VR without Meta's system apps (they'd stay on a 2D screen).": "",
+ "Lets SDL and LÖVE games start on the Frame (they'd crash looking for a clipboard).": "",
+ "Lets the game find language files (like de.lang) that are already in its data, instead of waiting for a download that never comes.": "",
 "Lets typing reach this app: Steam's on-screen keyboard or your computer's keyboard (VR is unaffected).": "",
 "Lets Unity games accept a headset that isn't a Quest.": "",
 "Lets Unreal games accept a headset that isn't a Quest.": "",
@@ -451,6 +469,7 @@
 "Loads libglshim.so ahead of libEGL in every engine library that fetches GL through eglGetProcAddress. Fixes Quest-only leniency that Mesa/Zink rejects: #pragma before #extension, implicit int/float conversions (enables GL_EXT_shader_implicit_conversions), and multiview shaders used on single-view framebuffers (hides GL_OVR_multiview; gl_hide_multiview=0 turns that off). Logs every failed shader with its source lines (logcat tag GLShim). Symptom: black screen with working audio in a GLES game.": "",
 "Locations": "",
 "Logs details for debugging: composition layers and swapchains, focus changes, play-space creation, pointer vs grip poses, refresh rates. No effect on the game.": "",
+ "Longer for headsets that briefly think they're off your head.": "",
 "Looking for Frames on your network…": "",
 "Looking for your Frame…": "",
 "Looking up the store description and screenshots…": "",
@@ -471,6 +490,7 @@
 "Menus and screens": "",
 "Meta Quest": "",
 "Meta XR Audio: skip Quest telemetry class": "",
+ "Meta's OVRManager switches Unity to the headset's recommended MSAA level (4x) while the game runs, whatever its quality settings say (log: \"Switching to the recommended level\"). Multisampled render-to-texture on GLES can hang the Frame's GPU, up to a restart of the whole headset (e.g. Lucky's Tale in a menu). Rewrites OVRDisplay.recommendedMSAALevel -> 0 in libil2cpp.so (found with Cpp2IL), so MSAA stays off.": "",
 "MiB": "",
 "Mirrored": "",
 "Mixed reality": "",
@@ -487,13 +507,14 @@
 "Needs Windows (or WSL on Windows)": "",
 "Neutralises Meta XR Audio's Quest-only calls (Unity/Wwise).": "",
 "New folder": "",
- "New Frame? Run one command on it and FramePort does the rest.": "",
+ "New Frame? Run one command on it and FramePort does the rest. Did this once already? Your Frame appears under step 2.": "",
 "New name": "",
 "Next": "",
 "No activity": "",
+ "no answer from the Frame": "",
 "No artwork could be downloaded from that {source} result; the current artwork stays. Try another one.": "",
 "No folders to rescan yet: add games with Scan a folder": "",
- "No Frames found. New Frame? Use first-time setup below. Otherwise make sure Developer Mode is on (Settings → System → Developer) and the Frame is on the same network.": "",
+ "No Frames found. New Frame? Use first-time setup (step 1). Otherwise make sure Developer Mode is on (Settings → System → Developer) and the Frame is on the same network.": "",
 "No games found in that folder": "",
 "No limit": "",
 "No matching files": "",
@@ -523,19 +544,18 @@
 "Now {scale:.0%}; {new:.0%} after restarting FramePort.": "",
 "Oculus game — needs Revive, which doesn't run on the Frame. Play it on this PC (SteamVR).": "",
 "Oculus OS telemetry class stubs": "",
+ "Oculus XR Plugin games render both eyes in one pass (multiview) on Android. If one eye shows only effects or grey (e.g. I Am Cat), rendering each eye in its own pass can fix it, at some GPU cost. Rewrites OculusSettings.GetStereoRenderingMode and its inlined read in OculusLoader.Initialize -> MultiPass in libil2cpp.so (found with Cpp2IL). Try it when one eye is wrong.": "",
 "off: {names}": "",
 "Offline": "",
 "Older workaround for upside-down quads: rotates them 180° (quads are single-sided; prefer flip_emul).": "",
 "On Frame": "",
 "On the Frame, place Revive's runtime (FramePort's Revive, or the repack's bundled LibRevive) where the game's Oculus SDK looks for LibOVRRT so it can load a VR runtime (pure runtime substitution — what Revive's LoadLibrary hook does on Windows; that hook doesn't work under Proton on the Frame). It does NOT bypass the Oculus runtime signature check: a game that verifies the runtime's signature will still refuse it. Ignored on this PC (Revive's hook handles it there).": "",
- "On the Frame: Steam button → Power → Switch to Desktop, open Konsole and run:": "",
+ "On the Frame: SteamVR dashboard → Launch a program → Desktop, then app menu → System → Konsole, and run:": "",
 "On this PC": "",
 "On this PC, launch the game through Revive's OpenVR backend, which talks straight to SteamVR — the original, most reliable Revive path. On by default for PC installs. Turn it off to use Revive's newer OpenXR backend instead. Ignored on the Frame (which always uses OpenXR).": "",
 "On this PC, runs Revive through SteamVR (works with more headsets).": "",
- "On your network": "",
 "on: {names}": "",
 "One PC VR game folder": "",
- "Only FramePort's entry is removed. Your game files and anything installed stay.": "",
 "Only if 360° pictures show wrongly.": "",
 "Only if 360° pictures show wrongly: 1 = upside down, 2 = mirrored, 4 = turned around (add values to combine).": "",
 "Open": "",
@@ -546,7 +566,7 @@
 "Opens this player's storage on the Frame (Files tab): upload videos into the folder it lists": "",
 "OpenXR runtime": "",
 "Or paste text to type it in one go": "",
- "Or turn on Developer Mode on the Frame (Settings → System → Developer): it then shows up above. Open Settings → Developer → Pair new host on the Frame, click Connect here and approve FramePort. That way needs no connection into this computer.": "",
+ "Or turn on Developer Mode on the Frame (Settings → System → Developer): it then shows up under step 2. Open Settings → Developer → Pair new host on the Frame, click Connect there and approve FramePort. That way needs no connection into this computer.": "",
 "Override the guardian depth (0 = use guardian, min 1.5 m).": "",
 "Override the guardian width (0 = use guardian, min 1.5 m).": "",
 "OVRPort converts Quest games from Meta's own VR APIs to standard OpenXR. These are its optional patches.": "",
@@ -555,6 +575,7 @@
 "OVRPort's OpenXR dispatcher aborts the app ('Wrong createInfo size', SIGABRT in libopenxr_loader.so xrCreateSwapchain) when a swapchain is wider or taller than 4096 px, which video players do for 8K video or big theatre textures (e.g. 4XVR). Raises the guard to 16384 px so the Frame's runtime (8192 px max) decides instead.": "",
 "OVRPort's own converter for games that use Meta's oldest VR interface (experimental).": "",
 "OVRPort's own VrApi→OpenXR adapter for engines that call libvrapi.so directly: the same upstream code as FramePort's 'VrApi → OpenXR bridge' without its Frame-specific changes. Only in OVRPort's experimental CLI builds (the stable CLI lists it but can't apply it).": "",
+ "OVRPort's platform loader answers the Meta Platform SDK's language-pack calls (ovr_LanguagePack_GetCurrent/SetCurrent) with 'no request', so a game that asks for its language pack never gets an answer. Adds a small library that serves language packs (<tag>.lang, e.g. de.lang) found in the game's own data folders (OBB and app files) through the same calls, the asset-file list and the status call, without any download. The game then finds the file path itself. The pack it applies with SetCurrent wins; otherwise the environment variable FRAMEPORT_LANGPACK (a tag), otherwise the only pack there is. Everything else goes to the loader unchanged. Off by default: turn it on for a game whose data has such files (the game page lists the patch only then).": "",
 "Package": "",
 "Pairing: on the Frame open Settings → Developer → Pair new host, then approve FramePort.": "",
 "Password (first time only)": "",
@@ -578,6 +599,7 @@
 "PC VR · Proton": "",
 "PC VR —": "",
 "PC VR ✓": "",
+ "Per-eye diagnostics (log)": "",
 "Pick several games and install them in one go. FramePort asks every question first, then works through the queue in the background.": "",
 "Picks a refresh rate and motion smoothing that suit the game on this PC.": "",
 "Pico/YVR/Quest metadata": "",
@@ -648,10 +670,12 @@
 "Remove {title} from the library?": "",
 "Removed the converted copies ({size})": "",
 "Removed {title}": "",
+ "Removed {title} and deleted its files on this PC ({size})": "",
 "Removes a controller position adjustment, for games whose hands look misplaced.": "",
 "Removes Android's back/home/recents buttons from a 2D app's window, where they cover the app's own controls. Turn it off for an app that needs the on-screen back button.": "",
 "Removes debugging leftovers some game files contain.": "",
 "Removes everything FramePort created: its data and tools on this PC, the Steam entries it added, and (optionally) its games and files on the Frame. Your game dumps aren't touched.": "",
+ "Removes FramePort's entry. Anything installed on the Frame stays.": "",
 "Removes leftovers from dumped/modded APKs.": "",
 "Removes Meta's old VR library when the game doesn't need it.": "",
 "Removes OVRPort's controller pose offset if controllers look misplaced.": "",
@@ -692,6 +716,7 @@
 "Runs Oculus PC games on OpenXR": "",
 "Runs OVRPort and apksigner": "",
 "Runs the game directly": "",
+ "Runs xrSyncActions one at a time with xrPollEvent and skips it for 250 ms after focus returns. For games that crash in the runtime's input code right after focus comes back (SIGSEGV in vrclient.so UpdateActionStateInternal / xrSyncActions, e.g. Myst).": "",
 "Save": "",
 "Save as known-good recipe": "",
 "Saved as a known-good recipe": "",
@@ -705,6 +730,7 @@
 "Scan a folder…": "",
 "Scan {name}": "",
 "Scans the folders you added games from again and adds games that appeared since. Games already in the library keep their recipe, tags and art; unchanged ones aren't analyzed again.": "",
+ "SDL apps: start without a clipboard service": "",
 "Search": "",
 "Search again": "",
 "Search games and tags": "",
@@ -740,9 +766,11 @@
 "Show Steam Frame controllers": "",
 "Show technical details (patch ids, exact effects, parameters)": "",
 "Show the app's Android window (for typing)": "",
+ "Show video panels": "",
 "Showing {len} of {n}": "",
 "Shows 3D 360° pictures flat if they look doubled.": "",
 "Shows the Frame's cameras where the game expects passthrough.": "",
+ "Shows videos that games play on a flat panel (e.g. an intro video).": "",
 "Signing keys matter: game updates must be signed with the same key or their saves are lost on reinstall.": "",
 "Signs rebuilt games": "",
 "Size": "",
@@ -770,6 +798,7 @@
 "Starts the game with options, e.g. to choose SteamVR or OpenXR.": "",
 "Starts the game with the launcher that came with your copy.": "",
 "Status": "",
+ "Steady controller input after focus": "",
 "Steam": "",
 "Steam for Windows not found": "",
 "Steam Frame": "",
@@ -813,6 +842,7 @@
 "The Frame is charging: continuing the installs.": "",
 "the Frame isn't connected": "",
 "The Frame isn't connected": "",
+ "The Frame refused that password. Check it, or run the first-time setup instead: Steam Frame → Show setup command.": "",
 "The Frame went offline: {exc}": "",
 "The Frame's battery is at {pct} % and not charging. Plug it in (a strong charger, not a PC port): long installs can drain it, and FramePort pauses them at {pause} %.": "",
 "The Frame's battery is at {pct} %: installs paused so it doesn't switch off mid-upload. Plug it in; the queue continues by itself.": "",
@@ -837,6 +867,7 @@
 "This computer's keyboard works as a keyboard on your Frame while this window is open. In the headset, select a text field (in a game or app, in Steam or on the desktop), then type here.": "",
 "This deletes the {what} on the Frame. It can't be undone.": "",
 "This folder is empty. Upload files with the buttons above.": "",
+ "This Frame isn't set up for FramePort yet. Run the first-time setup: Steam Frame → Show setup command.": "",
 "This game can't run on the Steam Frame.": "",
 "This game is marked \"Can't run\" on the Steam Frame:": "",
 "This game's folder has several programs and FramePort isn't sure which one starts the game. Open the game (or right-click → Change executable) to pick it.": "",
@@ -851,6 +882,7 @@
 "Tools": "",
 "Tools are up to date": "",
 "Translator for games built on Meta's oldest VR interface.": "",
+ "Treat newer Quest controllers as Touch": "",
 "Tried it in the headset? Tell us how it runs: with your recipe it can join FramePort's built-in list, so it works out of the box for everyone.": "",
 "Troubleshooting": "",
 "Try again": "",
@@ -881,8 +913,13 @@
 "Uninstall {title}?": "",
 "Uninstall. ": "",
 "Uninstalled {title}": "",
+ "Uninstalled {title} and deleted its files on this PC ({size})": "",
+ "Unity 2017: start VR without Meta's system apps": "",
+ "Unity's older built-in Oculus support (Unity 2017–2018) only starts VR when Android has Meta's com.oculus.systemactivities package; without it the game runs as a hidden 2D app (you see the Android home screen, e.g. Accounting+). Points that package name in libunity.so at \"android\", which always exists, and adds the frame wait its legacy frame loop never makes (libfp_ovrp.so calls ovrp_WaitToBeginFrame before ovrp_Update2; without it no frame starts and the dashboard freezes).": "",
 "Unity's TMP_InputField / InputField wait for Android's on-screen keyboard and close themselves a frame later when there is none (Lepton has no on-screen keyboard; Meta's system keyboard does this on a Quest), so a selected text field only flashes a caret. Rewrites TouchScreenKeyboardShouldBeUsed -> false and isKeyboardUsingEvents (TMP) / InPlaceEditing (uGUI) -> true in libil2cpp.so, found per game with Cpp2IL (downloaded on first use), so fields stay selected and take key presses: Steam's keyboard (with \"Show the app window\") or Type on Frame from the PC.": "",
 "Unity: disable MSAA": "",
+ "Unity: keep MSAA off at runtime (OVRManager)": "",
+ "Unity: render each eye separately (no multiview)": "",
 "Unreal builds of Meta XR Audio abort ('ClassNotFoundException com.oculus.os.AnalyticsEvent') on non-Quest devices. Patches that one JNI FindClass call so the library continues (e.g. NOPE Challenge).": "",
 "Unreal games start CrashReportClient when they crash, which leaves a crash dialog instead of simply closing. This passes -nocrashreports to the game and, on the Frame, renames the game's copy of CrashReportClient.exe so it can't start (your game files on this PC aren't changed).": "",
 "Untested": "",
@@ -925,14 +962,18 @@
 "Valve's Android runtime isn't installed (needs Developer Mode)": "",
 "Version": "",
 "Very high": "",
+ "Video panels that an Android media player draws into (XR_KHR_android_surface_swapchain, e.g. I Am Monkey's intro video), which the Frame's runtime refuses, get an Android Surface from FrameBridge: each video frame is copied into an ordinary swapchain the panel shows. Without it these panels are missing and a game waiting for its video stays black. 0 = leave them to the runtime.": "",
 "Video players' virtual theatres and 360° videos would otherwise stay black.": "",
 "Videos": "",
 "Videos, documents, mods and saves on your Steam Frame": "",
 "View screenshot": "",
 "VrApi → OpenXR adapter (OVRPort)": "",
 "VrApi → OpenXR bridge": "",
+ "Vulkan shader fixes": "",
+ "Vulkan shim (frame.vk_sanitize): SPIR-V modules matching size + SHA-256 get words inserted at a byte offset, e.g. stores that initialize locals a shader reads before writing (an undefined loop counter hung the GPU in VR4's campaign). Format: <size>:<sha256>:<byte offset>:<word>,<word>,...; several separated by ';'. Comes from a game's recipe.": "",
 "Vulkan: drop invalid render-pass pointers": "",
 "v{remote} (updates on the next action)": "",
+ "Wait for the game's GPU before showing an image": "",
 "Waiting": "",
 "Waiting ({n})": "",
 "Waiting for the Frame": "",
@@ -946,6 +987,8 @@
 "Where this game's recipe came from: catalog (tested on a Frame), heuristics (suggested by FramePort) or user (changed by you).": "",
 "Which program starts {get}?": "",
 "Which Proton build runs the game on the Frame (a Steam compat tool name from the Frame's ARM64 compat list, e.g. proton_11-arm64 or proton-experimental-arm64). Empty = newest installed.": "",
+ "Windows": "",
+ "Windows game (Proton)": "",
 "Windows not detected": "",
 "Windows treats this network as public and its firewall blocks the Frame. In Windows' network settings set this network to Private (or allow FramePort on public networks when Windows asks).": "",
 "Windows' firewall for WSL blocks the Frame from reaching FramePort. Open the setup command again and allow the change when Windows asks (admin).": "",
@@ -969,6 +1012,8 @@
 "Your custom recipe": "",
 "your Frame": "",
 "Your Frame is back: continuing": "",
+ "Your Frame isn't set up for FramePort yet. Run the first-time setup once (step 1).": "",
+ "Your Frame restarted unexpectedly while {title} was running (or soon after). If that game crashed it, please report it.": "",
 "Your headset, what it's ready for and what's installed": "",
 "Your own game files aren't touched.": "",
 "Your own tags (filled) can be anything you like. Outlined tags are added automatically from the engine, VR API and store genres. Filter the library by either.": "",
@@ -1031,7 +1076,11 @@
 ],
 "{on} on your Frame": "",
 "{remaining} more after this": "",
+ "{title} couldn't be added to the Frame's Steam library: {why}": "",
 "{title} failed: {error}": "",
+ "{title} isn't in the Frame's Steam library yet: adding it (Steam restarts once)": "",
+ "{title} will be in the Frame's Steam library when the game that's running is closed": "",
+ "{title} will be in the Frame's Steam library when you're back in Gaming Mode: start it from there": "",
 "{title}: analyzed again": "",
 "{title}: details from {value}": "",
 "{title}: done": "",
@@ -73,6 +73,7 @@ class Patch:
    default_on: bool = False  # part of the always-recommended baseline
    experimental: bool = False
    needs_vr: bool = True  # only matters for VR apps (hidden for Android apps without VR)
+    revision: int = 1  # bump when apply() writes something different: installed builds then show "Update on Frame"

    @property
    def summary(self) -> str:
@@ -168,3 +169,24 @@ def _import_modules() -> None:

    for mod in pkgutil.iter_modules(frame.__path__):
        importlib.import_module(f"{frame.__name__}.{mod.name}")
+
+
+def recipe_fingerprint(recipe: dict) -> str:
+    """What a build of this recipe contains: the patch selection with parameters, the build choices and each enabled
+    patch's revision. A build whose fingerprint differs from the recipe's now is outdated (a catalog fix, a revised
+    patch or a changed option), even when nothing was rebuilt yet."""
+    import hashlib
+    import json
+
+    load_all()
+    patches = recipe.get("patches") or {}
+    d = {"patches": patches, "use_alt": bool(recipe.get("use_alt")), "alt": sorted(recipe.get("alt_patches") or []),
+         "as_is": bool(recipe.get("as_is")), "overport": recipe.get("overport", True),
+         "rev": {p: REGISTRY[p].revision for p in sorted(patches) if p in REGISTRY and REGISTRY[p].revision != 1}}
+    return hashlib.sha256(json.dumps(d, sort_keys=True, default=str).encode()).hexdigest()[:16]
+
+
+def revised_since_unrecorded(recipe: dict) -> bool:
+    """For builds made before fingerprints were recorded: an enabled patch has been revised since (revision > 1)."""
+    load_all()
+    return any(p in REGISTRY and REGISTRY[p].revision > 1 for p in recipe.get("patches") or {})
@@ -0,0 +1,90 @@
+"""Language packs (`<tag>.lang` files in the game's data) for the Meta Platform SDK (native/langpack)."""
+from __future__ import annotations
+
+from ...analysis import elf
+from ..base import ApkContext, Patch, register
+from . import artifact
+
+LOADER = "libovrplatformloader.so"
+LIB = "libfp_langpack.so"
+META_MARK = b"@FPMETA@\0"  # native/langpack: g_meta_slot = marker + META_LEN bytes the Metadata is written into
+META_LEN = 96
+
+
+def with_metadata(lib: bytes, text: str) -> bytes:
+    """The library with `text` (the game's versionName) as the Metadata of the packs it serves.
+
+    Unreal games such as Deadpool VR only treat a pack as installed when its Metadata equals their own version string,
+    which Meta's store sets when the pack is uploaded."""
+    raw = text.encode("utf-8")
+    at = lib.find(META_MARK)
+    if not raw or len(raw) >= META_LEN or at < 0:
+        return lib
+    at += len(META_MARK)
+    return lib[:at] + raw + b"\0" * (META_LEN - len(raw)) + lib[at + META_LEN:]
+
+# Every function native/langpack/langpack.c defines. The loader's own exports of these are hidden (see
+# elf.hide_exports) so lookups reach LIB first; tests/test_langpack.py keeps this list equal to the C source.
+EXPORTS = (
+    "ovr_AssetDetailsArray_GetElement", "ovr_AssetDetailsArray_GetSize", "ovr_AssetDetails_GetAssetId",
+    "ovr_AssetDetails_GetAssetType", "ovr_AssetDetails_GetDownloadStatus", "ovr_AssetDetails_GetFilepath",
+    "ovr_AssetDetails_GetIapStatus", "ovr_AssetDetails_GetLanguage", "ovr_AssetDetails_GetMetadata",
+    "ovr_AssetFileDownloadResult_GetAssetId", "ovr_AssetFileDownloadResult_GetFilepath", "ovr_AssetFile_GetList",
+    "ovr_AssetFile_StatusById", "ovr_Error_GetCode", "ovr_Error_GetDisplayableMessage", "ovr_Error_GetHttpCode",
+    "ovr_Error_GetMessage", "ovr_FreeMessage", "ovr_LanguagePackInfo_GetEnglishName",
+    "ovr_LanguagePackInfo_GetNativeName", "ovr_LanguagePackInfo_GetTag", "ovr_LanguagePack_GetCurrent",
+    "ovr_LanguagePack_SetCurrent", "ovr_Message_GetAssetDetails", "ovr_Message_GetAssetDetailsArray",
+    "ovr_Message_GetAssetFileDownloadResult", "ovr_Message_GetError", "ovr_Message_GetRequestID",
+    "ovr_Message_GetType", "ovr_Message_IsError", "ovr_PopMessage",
+)
+
+
+class LanguagePacks(Patch):
+    id = "frame.langpacks"
+    title = "Language packs from the game's files"
+    description = ("OVRPort's platform loader answers the Meta Platform SDK's language-pack calls "
+                   "(ovr_LanguagePack_GetCurrent/SetCurrent) with 'no request', so a game that asks for its language "
+                   "pack never gets an answer. Adds a small library that serves language packs (<tag>.lang, e.g. "
+                   "de.lang) found in the game's own data folders (OBB and app files) through the same calls, the "
+                   "asset-file list and the status call, without any download. The game then finds the file path "
+                   "itself. The pack it applies with SetCurrent wins; otherwise the environment variable "
+                   "FRAMEPORT_LANGPACK (a tag), otherwise the only pack there is. Everything else goes to the "
+                   "loader unchanged. Off by default: turn it on for a game whose data has such files (the game "
+                   "page lists the patch only then).")
+    order = 32
+    experimental = True  # opt-in: checked in a headset with Deadpool VR, AC Nexus and Asgard's Wrath 2 only
+
+    # never part of a default recipe (few games tested): shown under Customize for games whose data has
+    # language packs, off until the user turns it on
+
+    def applies(self, a):
+        return LOADER in a.libs and "arm64-v8a" in a.abis and bool((a.extra or {}).get("lang_packs"))
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a" or not ws.has(ws.lib(LOADER)):
+            return False
+        loader = ws.read_lib(LOADER)
+        patched, hidden = elf.hide_exports(loader, EXPORTS)
+        if not hidden and LIB in elf.needed(loader):
+            return False  # applied by an earlier build
+        if not hidden:
+            ctx.notes.append("the platform loader has none of the language-pack functions: nothing to replace")
+            return False
+        patched = elf.add_needed(patched, LIB)
+        ws.put(ws.lib(LOADER), patched)
+        version = (ctx.analysis.version or "").strip()
+        ws.put(ws.lib(LIB), with_metadata(artifact(ws.abi, LIB), version))
+        ctx.notes.append(f"language packs served by {LIB} ({len(hidden)} loader functions replaced, "
+                         f"Metadata \"{version}\")")
+        return True
+
+    def validate(self, ctx: ApkContext):
+        ws = ctx.ws
+        if not ws.has(ws.lib(LOADER)):
+            return []
+        linked = LIB in elf.needed(ws.read_lib(LOADER))
+        return [("Language-pack library linked to the platform loader", linked and ws.has(ws.lib(LIB)), LIB)]
+
+
+register(LanguagePacks)
@@ -0,0 +1,48 @@
+"""SDL apps (SDL2 / LÖVE games, e.g. Dramatic Shape) crash at start in Lepton: its Android has no clipboard service
+(`service check clipboard`: not found), getSystemService(CLIPBOARD_SERVICE) returns null and SDLClipboardHandler's
+constructor calls addPrimaryClipChangedListener on it (NullPointerException in SDLActivity.onCreate). That one call is
+turned into no-ops in classes.dex (in place; other clipboard calls only happen when the app uses the clipboard)."""
+from __future__ import annotations
+
+from ...apk.dex import Dex
+from ..base import ApkContext, Patch, Suggestion, register
+
+HANDLER = "Lorg/libsdl/app/SDLClipboardHandler;"
+LISTENER = ("Landroid/content/ClipboardManager;", "addPrimaryClipChangedListener")
+
+
+class SdlClipboard(Patch):
+    id = "frame.sdl_clipboard"
+    title = "SDL apps: start without a clipboard service"
+    description = ("Lepton's Android has no clipboard service, and SDL's Java code (SDL2 and LÖVE games, e.g. "
+                   "Dramatic Shape) registers a clipboard listener at start without checking, so the app crashes "
+                   "with a NullPointerException in SDLClipboardHandler. That call is skipped (an in-place edit of "
+                   "classes.dex).")
+    order = 44
+    needs_vr = False
+
+    def applies(self, a):
+        return bool((a.extra or {}).get("sdl_java"))
+
+    def detect(self, a):
+        if self.applies(a):
+            return Suggestion(True, "SDL app: it crashes at start in Lepton, which has no clipboard service.")
+        return None
+
+    def apply(self, ctx: ApkContext) -> bool:
+        changed = False
+        for name in sorted(n for n in ctx.ws.names() if n.startswith("classes") and n.endswith(".dex")):
+            data = ctx.ws.read(name)
+            if HANDLER.encode() not in data:
+                continue
+            dex = Dex(data)
+            targets = set(dex.method_index(*LISTENER))
+            done = sum(dex.nop_calls(code, targets) for code in dex.code_items(HANDLER, "<init>")) if targets else 0
+            if done:
+                ctx.ws.put(name, dex.finish())
+                ctx.notes.append(f"{name}: SDLClipboardHandler no longer needs a clipboard service ({done} call)")
+                changed = True
+        return changed
+
+
+register(SdlClipboard)
@@ -26,8 +26,8 @@ def count_msaa_levels(ggm_bytes: bytes) -> int:

 def disable_msaa(ggm_bytes: bytes) -> bytes | None:
    """Set every quality level's antiAliasing to 0 by patching the int in place (re-serializing with UnityPy breaks
-    scene loading). The field is found through the 4-int run skinWeights, textureQuality, anisotropicTextures,
-    antiAliasing."""
+    scene loading). The field is found through the 4-int run skinWeights (blendWeights before Unity 2019),
+    textureQuality, anisotropicTextures, antiAliasing."""
    data = bytearray(ggm_bytes)
    patched = 0
    for obj, raw, level in _levels(ggm_bytes):
@@ -35,9 +35,12 @@ def disable_msaa(ggm_bytes: bytes) -> bytes | None:
        if aa <= 1:
            continue
        base = obj.byte_start
-        if bytes(data[base:base + len(raw)]) != raw:
+        if ggm_bytes[base:base + len(raw)] != raw:  # (not `data`: an earlier level of the same object changed it)
            raise RuntimeError("QualitySettings object bytes not found in place")
-        key = struct.pack("<4i", level["skinWeights"], level["textureQuality"], level["anisotropicTextures"], aa)
+        weights = level.get("skinWeights", level.get("blendWeights"))
+        if weights is None:
+            raise RuntimeError(f"quality level {level.get('name')}: unknown QualitySettings layout")
+        key = struct.pack("<4i", weights, level["textureQuality"], level["anisotropicTextures"], aa)
        at = raw.find(key)
        if at < 0:
            raise RuntimeError(f"antiAliasing field not found for quality level {level['name']}")
@@ -0,0 +1,86 @@
+"""Unity 2017-era built-in Oculus support starts its VR device only on a Quest/Go: libunity.so asks Android's package
+manager for com.oculus.systemactivities (Meta's system UI) and, when the lookup fails, quietly falls back to its "None"
+VR device. Lepton's Android has no such package, so the game ran as a plain 2D app that Lepton never shows (only the
+Android home screen, e.g. Accounting+, Unity 2017.4). The package name in libunity.so is pointed at "android" (always
+installed): a same-length, in-place string edit; everything else about the check stays as it is."""
+from __future__ import annotations
+
+from ...analysis import elf
+from ..base import ApkContext, Patch, Suggestion, register
+from . import artifact
+
+PACKAGE = "com.oculus.systemactivities"
+ALWAYS_THERE = "android"
+# Unity's legacy frame loop never calls ovrp_WaitToBeginFrame: its ovrp_Update2 lookup goes to native/ovrpshim
+SHIM = "libfp_ovrp.so"
+UPDATE, SHIM_UPDATE = "ovrp_Update2", "fpov_Update2"
+# input diagnostics (off): the C# P/Invoke names in libil2cpp.so pointed at the shim's wrappers, which log what they
+# return, report input focus as true and release buttons held > 2 s. Accounting+ still didn't pass "press any button"
+# with them (input reached the game cleanly), so they stay off; switch on to investigate another game.
+INPUT_PROBE = False
+INPUT_CALLS = ("ovrp_GetConnectedControllers", "ovrp_GetControllerState4", "ovrp_GetControllerState2",
+               "ovrp_GetAppHasInputFocus")
+UNITY_INPUT_CALLS = ("ovrp_GetControllerState", "ovrp_GetControllerState2")
+
+
+class UnityOculusCheck(Patch):
+    id = "frame.unity_oculus_check"
+    title = "Unity 2017: start VR without Meta's system apps"
+    description = ("Unity's older built-in Oculus support (Unity 2017–2018) only starts VR when Android has Meta's "
+                   "com.oculus.systemactivities package; without it the game runs as a hidden 2D app (you see the "
+                   "Android home screen, e.g. Accounting+). Points that package name in libunity.so at \"android\", "
+                   "which always exists, and adds the frame wait its legacy frame loop never makes (libfp_ovrp.so "
+                   "calls ovrp_WaitToBeginFrame before ovrp_Update2; without it no frame starts and the dashboard "
+                   "freezes).")
+    order = 45
+
+    def applies(self, a):
+        x = a.extra or {}
+        major = int(str(x.get("unity_version") or "0").split(".")[0] or 0)
+        # Unity 2019+ games run without it (e.g. Lucky's Tale 2019.4): their builds stay as they are
+        return a.engine == "Unity" and "libOVRPlugin.so" in a.libs and bool(x.get("unity_oculus_check")) \
+            and 0 < major < 2019
+
+    def detect(self, a):
+        if self.applies(a):
+            return Suggestion(True, "Older Unity with built-in Oculus support: it checks for Meta's system apps "
+                                    "before starting VR, and its frame loop never waits for the next frame "
+                                    "(e.g. Accounting+).")
+        return None
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        name = ws.lib("libunity.so")
+        if not ws.has(name):
+            return False
+        data, count = elf.replace_rodata_string(ws.read(name), PACKAGE, ALWAYS_THERE)
+        if not count:
+            return False
+        data, loops = elf.replace_rodata_string(data, UPDATE, SHIM_UPDATE)
+        plugin = ws.lib("libOVRPlugin.so")
+        if loops and ws.abi == "arm64-v8a" and ws.has(plugin):
+            ovrp = ws.read(plugin)
+            if SHIM.encode() not in ovrp:
+                ws.put(plugin, elf.add_needed(ovrp, SHIM))
+            ws.put(ws.lib(SHIM), artifact(ws.abi, SHIM))
+            ctx.notes.append(f"libunity.so: {UPDATE} -> {SHIM_UPDATE} ({SHIM} waits for each frame)")
+        il2cpp = ws.lib("libil2cpp.so")
+        if loops and INPUT_PROBE and ws.has(il2cpp):  # diagnostics: the game's C# input calls go through the shim
+            code, probes = ws.read(il2cpp), 0
+            for real in INPUT_CALLS:
+                code, n = elf.replace_rodata_string(code, real, "fpov_" + real[5:])
+                probes += n
+            if probes:
+                ws.put(il2cpp, code)
+                ctx.notes.append(f"libil2cpp.so: {probes} input calls logged by {SHIM}")
+        if loops and INPUT_PROBE:  # Unity's own input reads too
+            for real in UNITY_INPUT_CALLS:
+                data, n = elf.replace_rodata_string(data, real, "fpov_" + real[5:])
+                if n:
+                    ctx.notes.append(f"libunity.so: {real} logged by {SHIM}")
+        ws.put(name, data)
+        ctx.notes.append(f"libunity.so: {PACKAGE} -> {ALWAYS_THERE} ({count}x)")
+        return True
+
+
+register(UnityOculusCheck)
@@ -0,0 +1,69 @@
+"""Unity XR settings the game's code chooses at runtime, fixed in libil2cpp.so (found per game with Cpp2IL, like
+frame.unity_text_input).
+
+- MSAA: Meta's OVRManager (useRecommendedMSAALevel) raises Unity's antiAliasing to the headset's recommended level
+  (4x) at runtime ("The current MSAA level is 0, but the recommended MSAA level is 4. Switching to the recommended
+  level."), whatever QualitySettings say, so frame.unity_no_msaa can't keep it off. Multisampled render-to-texture on
+  GLES through Zink hangs the Frame's GPU (Lucky's Tale: the whole headset restarted in a menu, 2026-10-03).
+  OVRDisplay.recommendedMSAALevel -> 0 keeps it off.
+- Multiview: Oculus XR Plugin games render both eyes in one pass (Multiview) on Android. I Am Cat (Unity 2022.3, GLES
+  through Zink) drew only effects into the right eye's array slice; OculusSettings.GetStereoRenderingMode -> 0
+  (MultiPass) renders each eye in its own pass."""
+from __future__ import annotations
+
+from ..base import Suggestion, register
+from .unity_text_input import RET_FALSE, Il2cppReturnPatch
+
+RET_ZERO = RET_FALSE  # mov w0, #0 ; ret
+
+
+class UnityRuntimeMsaa(Il2cppReturnPatch):
+    id = "frame.unity_runtime_msaa_off"
+    title = "Unity: keep MSAA off at runtime (OVRManager)"
+    description = ("Meta's OVRManager switches Unity to the headset's recommended MSAA level (4x) while the game runs, "
+                   "whatever its quality settings say (log: \"Switching to the recommended level\"). Multisampled "
+                   "render-to-texture on GLES can hang the Frame's GPU, up to a restart of the whole headset (e.g. "
+                   "Lucky's Tale in a menu). Rewrites OVRDisplay.recommendedMSAALevel -> 0 in libil2cpp.so (found with "
+                   "Cpp2IL), so MSAA stays off.")
+    order = 47
+    targets = {"Oculus.VR/OVRDisplay.cs": {"get_recommendedMSAALevel": RET_ZERO},
+               "Assembly-CSharp/OVRDisplay.cs": {"get_recommendedMSAALevel": RET_ZERO}}  # older Oculus Integration
+    check_name = "Unity MSAA"
+
+    def applies(self, a):
+        return a.engine == "Unity" and "libil2cpp.so" in a.libs and not a.only_32bit
+
+    def detect(self, a):
+        if self.applies(a) and (a.extra or {}).get("ovr_runtime_msaa") and "GLES" in a.graphics:
+            return Suggestion(True, "GLES Unity game whose OVRManager turns 4x MSAA on at runtime: multisampled "
+                                    "render-to-texture can hang the Frame's GPU.")
+        return None
+
+
+class UnityMultiPass(Il2cppReturnPatch):
+    id = "frame.unity_multipass"
+    title = "Unity: render each eye separately (no multiview)"
+    description = ("Oculus XR Plugin games render both eyes in one pass (multiview) on Android. If one eye shows only "
+                   "effects or grey (e.g. I Am Cat), rendering each eye in its own pass can fix it, at some GPU cost. "
+                   "Rewrites OculusSettings.GetStereoRenderingMode and its inlined read in OculusLoader.Initialize -> "
+                   "MultiPass in libil2cpp.so (found with Cpp2IL). Try it when one eye is wrong.")
+    order = 48
+    revision = 2  # 0.6.3 only patched the getter, which is inlined: also the field read in OculusLoader.Initialize
+    SETTINGS = "Unity.XR.Oculus/Unity/XR/Oculus/OculusSettings.cs"
+    targets = {SETTINGS: {"GetStereoRenderingMode": RET_ZERO}}
+    # the one-line getter is inlined into OculusLoader.Initialize (no call sites in I Am Cat / Toy Master): the field
+    # read there is what reaches the native plugin
+    field_loads = {"Unity.XR.Oculus/Unity/XR/Oculus/OculusLoader.cs":
+                   {"Initialize": (SETTINGS, "m_StereoRenderingModeAndroid", 0)}}
+    check_name = "Unity stereo mode"
+
+    def applies(self, a):
+        return a.engine == "Unity" and "libil2cpp.so" in a.libs and not a.only_32bit \
+            and (a.extra or {}).get("oculus_xr_plugin", True) is not False
+
+    def detect(self, a):
+        return None  # only for a game that shows the symptom (catalog recipe or the user's choice)
+
+
+register(UnityRuntimeMsaa)
+register(UnityMultiPass)
@@ -29,12 +29,14 @@ def _executable(data: bytes) -> list[tuple[int, int]]:
            if s["p_type"] == "PT_LOAD" and s["p_flags"] & 1]


-def patch_methods(lib: bytes, found: dict[str, dict[str, tuple[int, int]]]) -> tuple[bytes | None, list[str]]:
-    """Write the return values over the methods' first two instructions. found = il2cpp.find_methods' result.
+def patch_methods(lib: bytes, found: dict[str, dict[str, tuple[int, int]]],
+                  targets: dict[str, dict[str, bytes]] | None = None) -> tuple[bytes | None, list[str]]:
+    """Write the return values over the methods' first two instructions. found = il2cpp.find_methods' result,
+    targets = {class file: {method: RET_*}} (default: the text field methods).
    Returns (patched library or None when nothing changed, notes)."""
    out, notes, changed = bytearray(lib), [], False
    code = _executable(lib)
-    for cls, methods in TARGETS.items():
+    for cls, methods in (targets or TARGETS).items():
        for method, new in methods.items():
            off, length = found.get(cls, {}).get(method, (None, 0))
            if off is None:
@@ -47,11 +49,103 @@ def patch_methods(lib: bytes, found: dict[str, dict[str, tuple[int, int]]]) -> t
                continue
            out[off:off + len(new)] = new
            changed = True
-            notes.append(f"{name} -> {'true' if new == RET_TRUE else 'false'} (at {off:#x})")
+            notes.append(f"{name} -> {'true/1' if new == RET_TRUE else 'false/0'} (at {off:#x})")
    return (bytes(out) if changed else None), notes


-class UnityTextInput(Patch):
+def patch_field_loads(lib: bytes, method: tuple[int, int], field_offset: int, value: int, name: str
+                      ) -> tuple[bytes | None, list[str]]:
+    """Inside one method (file offset, length), turn every load of the instance field at field_offset (ldr/ldrh/ldrb
+    w<t>, [x<n>, #field_offset]) into mov w<t>, #value: for a getter the compiler inlined into its caller, patching the
+    getter alone changes nothing. Refuses when there's no such load (unless already patched) or more than 2."""
+    start, length = method
+    if start % 4 or not any(a <= start and start + length <= b for a, b in _executable(lib)):
+        raise RuntimeError(f"{name}: offset {start:#x} isn't code in libil2cpp.so (Cpp2IL mismatch)")
+    kinds = [(0xB9400000, 4), (0x79400000, 2), (0x39400000, 1)]  # ldr w (32-bit), ldrh, ldrb (unsigned offset)
+    mov = 0x52800000 | (value & 0xFFFF) << 5  # movz w<t>, #value
+    out, hits, already = bytearray(lib), [], 0
+    for off in range(start, start + length, 4):
+        w = int.from_bytes(lib[off:off + 4], "little")
+        if w & 0xFFFFFFE0 == mov:
+            already += 1
+        for base, size in kinds:
+            if field_offset % size == 0 and field_offset // size < 4096 \
+                    and w & 0xFFFFFC00 == base | (field_offset // size) << 10:
+                hits.append(off)
+                out[off:off + 4] = (mov | w & 31).to_bytes(4, "little")
+    if not hits:
+        if already:
+            return None, [f"{name} already patched"]
+        raise RuntimeError(f"{name}: no load of the field at {field_offset:#x} in this method")
+    if len(hits) > 2:
+        raise RuntimeError(f"{name}: {len(hits)} loads of offset {field_offset:#x}; not guessing which one")
+    return bytes(out), [f"{name} -> {value} (at {', '.join(hex(h) for h in hits)})"]
+
+
+ALL_TARGETS: dict[str, list[str]] = {}  # every IL2CPP patch's methods: one Cpp2IL run (and cache entry) serves all
+
+
+class Il2cppReturnPatch(Patch):
+    """Make IL2CPP methods return a constant (targets), found per game with Cpp2IL (analysis/il2cpp.py)."""
+    targets: dict[str, dict[str, bytes]] = {}
+    # loads of a field inlined into a method: {method's class file: {method: (field's class file, field, value)}}
+    field_loads: dict[str, dict[str, tuple[str, str, int]]] = {}
+    check_name = ""
+
+    def __init_subclass__(cls, **kw):
+        super().__init_subclass__(**kw)
+        wanted = [(c, m) for c, methods in cls.targets.items() for m in methods]
+        for c, methods in cls.field_loads.items():
+            for m, (fc, field, _v) in methods.items():
+                wanted += [(c, m), (fc, f"field:{field}")]
+        for c, m in wanted:
+            ALL_TARGETS.setdefault(c, [])
+            if m not in ALL_TARGETS[c]:
+                ALL_TARGETS[c].append(m)
+
+    @staticmethod
+    def _unity_version(ws) -> str | None:
+        """For library entries analyzed before the version was recorded: read it from the APK itself."""
+        from ...analysis.detect import UNITY_GGM, unity_version
+
+        ggm = ws.read(UNITY_GGM) if ws.has(UNITY_GGM) else None
+        libunity = ws.read_lib("libunity.so") if ws.has(ws.lib("libunity.so")) else None
+        return unity_version(ggm, libunity) if ggm or libunity else None
+
+    def apply(self, ctx: ApkContext) -> bool:
+        from ...analysis.il2cpp import find_methods
+
+        ws = ctx.ws
+        lib_name = ws.lib("libil2cpp.so")
+        if ws.abi != "arm64-v8a" or not ws.has(lib_name) or not ws.has(METADATA):
+            return False
+        version = (ctx.analysis.extra or {}).get("unity_version") or self._unity_version(ws)
+        if not version:
+            ctx.reporter.check(self.check_name, False, "not fixed: unknown Unity version (rescan the game)")
+            return False
+        lib = ws.read(lib_name)
+        ctx.reporter.log(f"{self.check_name}: finding the code (Cpp2IL; the first time can take a minute)")
+        try:
+            found = find_methods(lib, ws.read(METADATA), version, ALL_TARGETS)
+            patched, notes = patch_methods(lib, found, self.targets)
+            for c, methods in self.field_loads.items():
+                for m, (fc, field, value) in methods.items():
+                    method, offset = found.get(c, {}).get(m), found.get(fc, {}).get(f"field:{field}")
+                    if not method or not offset:
+                        continue
+                    name = f"{c.rsplit('/', 1)[-1][:-3]}.{m}: {field}"
+                    again, more = patch_field_loads(patched or lib, method, offset[0], value, name)
+                    patched, notes = again or patched, notes + more
+        except Exception as exc:  # noqa: BLE001 - optional fix: the game still builds, unchanged
+            ctx.reporter.check(self.check_name, False, f"not fixed: {exc}")
+            return False
+        ctx.notes.extend(notes or [f"{self.check_name}: code not found in this game"])
+        if patched is not None:
+            ws.put(lib_name, patched)
+        return patched is not None
+
+
+class UnityTextInput(Il2cppReturnPatch):
    id = "frame.unity_text_input"
    title = "Make Unity text fields work without a system keyboard"
    description = ("Unity's TMP_InputField / InputField wait for Android's on-screen keyboard and close themselves a "
@@ -63,6 +157,8 @@ class UnityTextInput(Patch):
                   "Frame from the PC.")
    order = 46
    needs_vr = False
+    targets = TARGETS
+    check_name = "Unity text fields"

    def applies(self, a):
        return a.engine == "Unity" and "libil2cpp.so" in a.libs and bool((a.extra or {}).get("text_fields"))
@@ -74,29 +170,5 @@ class UnityTextInput(Patch):
                                    "it has no system keyboard.")
        return None

-    def apply(self, ctx: ApkContext) -> bool:
-        from ...analysis.il2cpp import find_methods
-
-        ws = ctx.ws
-        lib_name = ws.lib("libil2cpp.so")
-        if ws.abi != "arm64-v8a" or not ws.has(lib_name) or not ws.has(METADATA):
-            return False
-        version = (ctx.analysis.extra or {}).get("unity_version")
-        if not version:
-            ctx.reporter.check("Unity text fields", False, "not fixed: unknown Unity version (rescan the game)")
-            return False
-        lib = ws.read(lib_name)
-        ctx.reporter.log("finding the text field code (Cpp2IL; the first time can take a minute)")
-        try:
-            found = find_methods(lib, ws.read(METADATA), version, {c: list(m) for c, m in TARGETS.items()})
-            patched, notes = patch_methods(lib, found)
-        except Exception as exc:  # noqa: BLE001 - optional fix: the game still builds, its text fields as before
-            ctx.reporter.check("Unity text fields", False, f"not fixed: {exc}")
-            return False
-        ctx.notes.extend(notes or ["no Unity text field code found"])
-        if patched is not None:
-            ws.put(lib_name, patched)
-        return patched is not None
-

 register(UnityTextInput)
@@ -8,6 +8,24 @@ from . import artifact
 SHIM = "libfp_vk.so"  # not longer than "libvulkan.so": the engine's dlopen string is rewritten in place
 VULKAN = "libvulkan.so"
 ENGINE_LIBS = ("libUE4.so", "libUnreal.so")
+# not the engine: XR/Meta/FramePort libraries that may name libvulkan.so too
+NOT_ENGINE = ("libopenxr", "libOVR", "libovr", "libvrapi", "libfp_", "libframe", "libVkLayer", "libc++", "libunity")
+
+
+def engine_libs(ws, analysis) -> list[str]:
+    """The game's libraries that load Vulkan by name: Unreal's engine library, or for other engines (own engines,
+    e.g. Roblox) every library of the game naming libvulkan.so. Unity loads Vulkan differently and isn't touched."""
+    if analysis.engine == "Unreal":
+        return [lib for lib in ENGINE_LIBS if ws.has(ws.lib(lib))]
+    if analysis.engine != "Other":
+        return []
+    out = []
+    for lib in analysis.libs:
+        if lib.startswith(NOT_ENGINE) or not ws.has(ws.lib(lib)):
+            continue
+        if b"\0" + VULKAN.encode() + b"\0" in ws.read_lib(lib):
+            out.append(lib)
+    return out


 class VulkanSanitize(Patch):
@@ -22,6 +40,9 @@ class VulkanSanitize(Patch):
    default_on = True

    def detect(self, a):
+        if a.engine == "Other":  # changes nothing unless one of its libraries loads Vulkan by name
+            return Suggestion(True, "Own-engine game: applied when one of its libraries loads Vulkan by name (e.g. "
+                                    "Roblox); keeps Lepton's Fossilize layer from crashing on uninitialized pointers.")
        if a.engine == "Unreal":
            return Suggestion(True, "Unreal game: applied automatically when the engine loads Vulkan by name; keeps "
                                    "Lepton's Fossilize layer from crashing on uninitialized pointers "
@@ -29,16 +50,14 @@ class VulkanSanitize(Patch):
        return None

    def applies(self, a):
-        return a.engine == "Unreal"
+        return a.engine in ("Unreal", "Other")

    def apply(self, ctx: ApkContext) -> bool:
        ws = ctx.ws
        if ws.abi != "arm64-v8a":
            return False
        changed = False
-        for lib in ENGINE_LIBS:
-            if not ws.has(ws.lib(lib)):
-                continue
+        for lib in engine_libs(ws, ctx.analysis):
            data, count = elf.replace_rodata_string(ws.read_lib(lib), VULKAN, SHIM)
            if count:
                ws.put(ws.lib(lib), data)
@@ -52,7 +71,9 @@ class VulkanSanitize(Patch):

    def validate(self, ctx: ApkContext):
        ws = ctx.ws
-        return [("Vulkan shim present", ws.has(ws.lib(SHIM)), SHIM)]
+        uses = [lib for lib in ctx.analysis.libs if not lib.startswith(NOT_ENGINE) and ws.has(ws.lib(lib))
+                and b"\0" + SHIM.encode() + b"\0" in ws.read_lib(lib)] if ctx.analysis.engine == "Other" else [1]
+        return [("Vulkan shim present", ws.has(ws.lib(SHIM)), SHIM)] if uses else []


 register(VulkanSanitize)
@@ -31,6 +31,11 @@ SETTINGS = [
    ("cylinder_strips", "int", 1, "Show curved panels",
     "Cylinder layers (curved menus and movie screens, e.g. 4XVR), which the Frame's runtime lacks, are shown as a "
     "few flat strips along the curve. 0 = drop them. 360° (equirect) layers can't be shown on the Frame."),
+    ("surface_emul", "int", 1, "Show video panels",
+     "Video panels that an Android media player draws into (XR_KHR_android_surface_swapchain, e.g. I Am Monkey's "
+     "intro video), which the Frame's runtime refuses, get an Android Surface from FrameBridge: each video frame is "
+     "copied into an ordinary swapchain the panel shows. Without it these panels are missing and a game waiting for "
+     "its video stays black. 0 = leave them to the runtime."),
    ("equirect_emul", "int", 0, "Show 360° layers",
     "360° (equirect) layers, e.g. a video player's virtual theatre or 360° videos (e.g. 4XVR), which the Frame's "
     "runtime lacks, are drawn by a background thread into a layer behind the game's own picture: the 360° image is "
@@ -53,8 +58,20 @@ SETTINGS = [
     "Every 'local' play space the game creates lines up with the one at the start. For games whose menus or screens "
     "jump to where you look on the Frame."),
    ("focus_hold", "int", 0, "Ignore brief focus dips",
-     "Hides the Frame's brief focus dips (well under a second) once the game has been focused for a few seconds. For "
+     "Hides the Frame's brief focus dips (up to a second) once the game has been focused for a second. For "
     "games that recentre or pause every time focus returns."),
+    ("focus_hold_ms", "float", 1000.0, "Longest focus dip to ignore (ms)",
+     "focus_hold hides focus dips up to this long (100-5000). Longer for a headset whose wear sensor flickers "
+     "(\"HMD off\" for 0.5-2 s while worn, e.g. Blade & Sorcery pausing); taking the headset off or the system menu "
+     "pauses the game only after this long."),
+    ("sync_guard", "int", 0, "Guard controller input after focus",
+     "Runs xrSyncActions one at a time with xrPollEvent and skips it for 250 ms after focus returns. For games that "
+     "crash in the runtime's input code right after focus comes back (SIGSEGV in vrclient.so UpdateActionStateInternal "
+     "/ xrSyncActions, e.g. Myst)."),
+    ("profile_remap", "int", 1, "Newer Touch profiles as Touch",
+     "Apps that suggest controller bindings only for Meta's newer profiles (Touch Plus, Touch Pro), which the Frame's "
+     "runtime rejects (XR_ERROR_PATH_UNSUPPORTED), get the same bindings as oculus/touch_controller instead "
+     "(components Touch lacks are dropped). Without it such apps get no controller input."),
    ("aim_pitch", "float", 0.0, "Pointer tilt (degrees)",
     "Tilts the controllers' pointing ray up (+) or down (−), for games whose pointer doesn't hit what you aim at."),
    ("aim_yaw", "float", 0.0, "Pointer turn (degrees)", "Turns the controllers' pointing ray left (+) or right (−)."),
@@ -66,6 +83,14 @@ SETTINGS = [
    ("layer_debug", "int", 0, "Extra diagnostics (log)",
     "Logs details for debugging: composition layers and swapchains, focus changes, play-space creation, pointer vs "
     "grip poses, refresh rates. No effect on the game."),
+    ("eye_debug", "int", 0, "Per-eye diagnostics (log)",
+     "For one eye looking wrong (e.g. a jittering right eye): logs each eye's submitted pose against a fresh one, the "
+     "eye-to-eye relation and when each eye's image was released, also into framebridge.log in the game's storage "
+     "(some games stop Android's log early). No effect on the game."),
+    ("release_wait", "int", 0, "Wait for the game's GPU before showing an image",
+     "Before a swapchain image is handed to the Frame, wait until the game's GPU work on it has finished, for games "
+     "that hand over images early (an eye flickers or jitters). Costs some frame time. 2 = only after the first 60 s "
+     "(compare both in one session)."),
    ("scene_emul", "int", 0, "Emulate Meta scene (room)",
     "Fake XR_FB_scene/spatial entities: a guardian-sized room with floor, ceiling and four walls, for mixed-reality "
     "games that build their level from the room (e.g. Demeter)."),
@@ -85,12 +110,20 @@ SETTINGS = [
    ("respace_kick", "int", 0, "Re-create reference space", "Recreate spaces after the first frames (diagnostic)."),
    ("flip_quads", "int", 0, "Rotate quads 180°",
     "Older workaround for upside-down quads: rotates them 180° (quads are single-sided; prefer flip_emul)."),
+    ("vk_shader_fix", "str", "", "Vulkan shader fixes",
+     "Vulkan shim (frame.vk_sanitize): SPIR-V modules matching size + SHA-256 get words inserted at a byte offset, "
+     "e.g. stores that initialize locals a shader reads before writing (an undefined loop counter hung the GPU in "
+     "VR4's campaign). Format: <size>:<sha256>:<byte offset>:<word>,<word>,...; several separated by ';'. Comes from "
+     "a game's recipe."),
    ("gl_hide_multiview", "int", 1, "GL shim: hide multiview",
     "GL shim only: hide GL_OVR_multiview so all passes use single-view shaders. For GLES games whose multiview "
     "shaders fail on single-view render targets (e.g. Path of the Warrior)."),
 ]


+# settings that need a new build, not only new settings files: the Vulkan shim learned vk_shader_fix in 0.6.4
+REVISIONS = {"vk_shader_fix": 2}
+
 # How the "Game settings" dialog shows each setting to non-technical users: group, level (common settings are always
 # shown; advanced ones only under "Show advanced settings"), a plain label and one-line help, the control, and the
 # setting it depends on (only shown while that one is on). The technical title/description above stay for the CLI.
@@ -107,6 +140,15 @@ UI: dict[str, dict] = {
    "controller_fix": dict(group="controllers", level="common", label="Use controllers",
                           help="Turn off only for games you play with your hands instead of controllers.",
                           control=("switch",)),
+    "focus_hold_ms": dict(group="screens", level="advanced", label="Ignore focus dips up to", depends="focus_hold",
+                          help="Longer for headsets that briefly think they're off your head.",
+                          control=("slider", 500.0, 3000.0, 100.0, "{:.0f} ms")),
+    "sync_guard": dict(group="troubleshooting", level="advanced", label="Steady controller input after focus",
+                       help="For games that crash right after you return to them (e.g. after the Steam menu).",
+                       control=("switch",)),
+    "profile_remap": dict(group="controllers", level="advanced", label="Treat newer Quest controllers as Touch",
+                          help="For apps that only know Quest 3/Pro controllers: without it they get no buttons.",
+                          control=("switch",)),
    "aim_pitch": dict(group="controllers", level="common", label="Pointer angle",
                      help="If the pointer doesn't hit what you aim at, tilt it up or down.",
                      control=("slider", -30.0, 30.0, 1.0, "{:+.0f}°")),
@@ -121,6 +163,9 @@ UI: dict[str, dict] = {
    "cylinder_strips": dict(group="screens", level="common", label="Show curved menus and screens",
                            help="The Frame can't show curved panels; this shows them as gently bent strips.",
                            control=("switch",)),
+    "surface_emul": dict(group="screens", level="common", label="Show video panels",
+                         help="Shows videos that games play on a flat panel (e.g. an intro video).",
+                         control=("switch",)),
    "flip_emul": dict(group="screens", level="common", label="Fix upside-down menus",
                      help="Turns menus and text the right way up.", control=("switch",)),
    "stable_local": dict(group="screens", level="common", label="Keep menus in place",
@@ -162,7 +207,7 @@ UI: dict[str, dict] = {
                            control=("choice", [(0, "As the game sends it"), (2, "Flat")])),
    **{key: dict(group="troubleshooting", level="advanced", control=("switch",)) for key in (
        "foveation_fix", "swapchain_fix", "layer_fix", "gl_hide_multiview", "mutable_fix", "flip_quads", "swap_eyes",
-        "strip_depth", "respace_kick", "layer_debug")},
+        "strip_depth", "respace_kick", "layer_debug", "eye_debug", "release_wait")},
 }


@@ -177,6 +222,7 @@ class AdapterSetting(Patch):
        self.description = description
        self.params = [Param("value", kind, default, description)]
        self.default = default
+        self.revision = REVISIONS.get(key, 1)

    def detect(self, a):
        from .applicability import needs_scene, uses_equirect_layers, uses_render_models
@@ -210,6 +256,7 @@ class AdapterSetting(Patch):
            "mutable_fix": ap.is_vulkan,
            "swapchain_fix": ap.is_gles,
            "gl_hide_multiview": lambda a: a.direct_vrapi and ap.is_gles(a),
+            "vk_shader_fix": lambda a: a.engine == "Unreal",  # read by the Vulkan shim, which only Unreal games get
            "controller_models": ap.may_use_render_models,
            **{k: ap.is_gles for k in ("equirect_emul", "equirect_face", "equirect_res", "equirect_flip",
                                       "equirect_fps", "equirect_stereo")},
@@ -42,7 +42,15 @@ SUMMARIES = {
    "frame.meta_permissions": "Declares Meta's permissions some mixed-reality games ask for, so they don't stop.",
    "frame.ovrplatformcompat": "Adds a small piece of Meta's platform library that some games need to start.",
    "frame.ovrstubs": "Provides stand-ins for Meta store functions the game expects, so it doesn't crash at start.",
+    "frame.langpacks": "Lets the game find language files (like de.lang) that are already in its data, instead of "
+                       "waiting for a download that never comes.",
    "frame.unity_no_msaa": "Turns off a smoothing setting that crashes some older Unity games on the Frame.",
+    "frame.unity_runtime_msaa_off": "Keeps a smoothing setting off that the game turns on itself and that can freeze "
+                                    "the Frame.",
+    "frame.sdl_clipboard": "Lets SDL and LÖVE games start on the Frame (they'd crash looking for a clipboard).",
+    "frame.unity_oculus_check": "Lets older Unity games start VR without Meta's system apps (they'd stay on a 2D "
+                                "screen).",
+    "frame.unity_multipass": "Draws each eye separately; try it when one eye shows a grey or broken picture.",
    "frame.swapchain_limit": "Allows very large pictures (8K video, theatres) instead of quitting.",
    "frame.vrapi_bridge": "Translator for games built on Meta's oldest VR interface.",
    "frame.gl_shim": "Fixes graphics code that the Frame's drivers reject (black screen with sound).",
@@ -9,10 +9,12 @@ PC (Revive + local Steam) or on the Frame (Proton + Revive).
 """
 from __future__ import annotations

+import threading
 import time
 from pathlib import Path

 from . import build as builder
+from .analysis import langpacks
 from .analysis.detect import analyze
 from .artwork import fetch as artwork
 from .core import library
@@ -153,7 +155,9 @@ def add_rift_game(folder: Path, reporter: Reporter | None = None, tree=None, exe
    if reporter:
        reporter.log(f"analyzing {folder.name}")
    a = rift.analyze(folder, exe=exe, tree=tree)
-    if not a.extra.get("vr_found") and not force and not old:
+    # no VR runtime in it: added on purpose ("Add one game folder…") = a flat Windows game run by Proton
+    a.extra["flat"] = not a.extra.get("vr_found")
+    if a.extra["flat"] and not force and not old:
        if reporter:
            reporter.log(f"skipped {folder.name}: no VR support (OpenXR, SteamVR or Oculus) found in {a.extra['exe']}")
        return None
@@ -273,6 +277,7 @@ def add_game(src: SourceGame, reporter: Reporter | None = None) -> dict:
    if reporter:
        reporter.log(f"analyzing {src.apk.name}")
    a = analyze(src.apk, data_bytes=src.data_bytes())
+    a.extra["lang_packs"] = langpacks.find_tags(src.data_dir)
    recipe = engine.suggest(a)
    return library.upsert_game(
        a.package, title=recipe.title or a.label, name=src.name, apk=str(src.apk),
@@ -292,6 +297,7 @@ def reanalyze(package: str, reporter: Reporter | None = None) -> dict:
    if reporter:
        reporter.log(f"analyzing {src.apk.name}")
    a = analyze(src.apk, data_bytes=src.data_bytes())
+    a.extra["lang_packs"] = langpacks.find_tags(src.data_dir)
    suggested = engine.suggest(a)
    keep = library.recipe_from_dict(entry["recipe"]).source == "user"
    return library.upsert_game(package, analysis=a.to_dict(), suggested=library.recipe_to_dict(suggested),
@@ -349,7 +355,8 @@ def prepare_rift(package: str, reporter: Reporter) -> dict:
        check("Revive", True, f"{revive.installed_version()} ({rdir})")
    art, store_title = artwork.fetch(package, lookup=entry.get("quest_package"))
    info = {"sha256": sha256(exe) if exe.is_file() else None, "checks": checks,
-            "ok": all(c["ok"] is not False for c in checks), "revive": revive.installed_version(), "kind": "rift"}
+            "ok": all(c["ok"] is not False for c in checks), "revive": revive.installed_version(), "kind": "rift",
+            "recipe_fp": recipe_fingerprint(entry["recipe"])}
    library.upsert_game(package, build=info)
    return info

@@ -384,11 +391,27 @@ def prepare_as_is(package: str, reporter: Reporter) -> dict:
        check("Manifest", None, str(exc))
    art, store_title = artwork.fetch(package, apk)
    info = {"apk": str(apk), "alt_apk": None, "sha256": sha256(apk), "alt_sha256": None, "applied": [],
-            "checks": checks, "ok": all(c["ok"] is not False for c in checks), "as_is": True}
+            "checks": checks, "ok": all(c["ok"] is not False for c in checks), "as_is": True,
+            "recipe_fp": recipe_fingerprint(entry["recipe"])}
    library.upsert_game(package, build=info, title=entry.get("title") or store_title)
    return info


+def recipe_fingerprint(recipe: dict) -> str:
+    from .patches.base import recipe_fingerprint as fp
+
+    return fp(recipe)
+
+
+_build_locks: dict[str, threading.Lock] = {}
+_build_locks_guard = threading.Lock()
+
+
+def _build_lock(package: str) -> threading.Lock:
+    with _build_locks_guard:
+        return _build_locks.setdefault(package, threading.Lock())
+
+
 def build_game(package: str, reporter: Reporter, outdir: Path | None = None) -> dict:
    entry = library.game(package)
    if is_rift(entry):
@@ -399,11 +422,12 @@ def build_game(package: str, reporter: Reporter, outdir: Path | None = None) ->
    a = library.analysis_from_dict(entry["analysis"])
    recipe = library.recipe_from_dict(entry["recipe"])
    out = outdir or (output_dir() / quest_dump.display_name(entry.get("name") or package))
-    res = builder.build(src, a, recipe, out, reporter)
+    with _build_lock(package):  # one build per game at a time: builds share the game's work folder
+        res = builder.build(src, a, recipe, out, reporter)
    art, store_title = artwork.fetch(package, res.apk)
    build_info = {"apk": str(res.apk), "alt_apk": str(res.alt_apk) if res.alt_apk else None, "sha256": res.sha256,
                  "alt_sha256": res.alt_sha256, "applied": res.applied, "checks": res.checks, "ok": res.ok,
-                  "overport": res.meta.get("overport")}
+                  "overport": res.meta.get("overport"), "recipe_fp": recipe_fingerprint(entry["recipe"])}
    library.upsert_game(package, build=build_info, title=entry.get("title") or store_title)
    return build_info

@@ -446,6 +470,52 @@ def remove_all_converted_copies() -> int:
    return freed


+def local_game_files(package: str) -> list[Path]:
+    """The game's own files on this PC that "Uninstall → also delete the files on this PC" removes: a Quest game's
+    APK and data (OBB) folder, a PC VR game's folder, and FramePort's converted copies of it. Never the signing keys,
+    and never a path another library entry still uses (e.g. a shared folder)."""
+    g = library.game(package) or {}
+    paths: list[Path] = []
+    if g.get("kind") == "rift":
+        paths += [Path(g["game_dir"])] if g.get("game_dir") else []
+    else:
+        paths += [Path(p) for p in (g.get("apk"), g.get("data_dir")) if p]
+    b = g.get("build") or {}
+    out = output_dir().resolve()
+    paths += [Path(b[k]) for k in ("apk", "alt_apk") if b.get(k) and out in Path(b[k]).resolve().parents]
+    others = [o for o in library.games() if o.get("package") != package]
+    used = [Path(p).resolve() for o in others for p in (o.get("apk"), o.get("data_dir"), o.get("game_dir")) if p]
+
+    def shared(p: Path) -> bool:  # the same path, a path inside it, or a folder around it belongs to another game
+        rp = p.resolve()
+        return any(u == rp or rp in u.parents or u in rp.parents for u in used)
+    return [p for p in dict.fromkeys(paths) if p.exists() and not shared(p)]
+
+
+def delete_local_files(package: str) -> tuple[list[str], int]:
+    """Delete local_game_files(package), then the game's folder if that left it empty, and drop the library entry (the
+    game can't be rebuilt without its files). Returns (deleted paths, bytes freed)."""
+    import shutil
+
+    files = local_game_files(package)
+    freed, done = 0, []
+    parents = {p.parent for p in files}
+    for p in files:
+        size = sum(f.stat().st_size for f in p.rglob("*") if f.is_file()) if p.is_dir() else p.stat().st_size
+        shutil.rmtree(p) if p.is_dir() else p.unlink()
+        freed += size
+        done.append(str(p))
+    for d in parents:  # e.g. "Game v1.2/" that held only the APK and its OBB folder
+        try:
+            if d.is_dir() and not any(d.iterdir()) and d != output_dir():
+                d.rmdir()
+                done.append(str(d))
+        except OSError:
+            pass
+    library.remove_game(package)
+    return done, freed
+
+
 def remove_converted_copies(package: str) -> int:
    """The converted APKs are only needed until they're on the Frame (every install converts again): remove them
    unless the user keeps them (setting build.keep_copies). Only files in FramePort's own output folder, never the
@@ -49,6 +49,7 @@ class CatalogEntry:
    proton_tool: str = ""
    as_is: bool = False  # Rift: the dump runs unchanged (e.g. a SteamVR build: no Revive)
    verified: dict = field(default_factory=dict)
+    updated: str = ""  # date of the last maintainer change without a new headset test (e.g. a fix from a report)
    source_hint: str = ""
    origin: str = "bundled"

@@ -57,6 +58,14 @@ class CatalogEntry:
        known = {k: v for k, v in d.items() if k in cls.__dataclass_fields__}
        return cls(**known, origin=origin)

+    def rev(self) -> str:
+        """Fingerprint of the recipe content: library recipes derived from this entry follow it when it changes."""
+        import hashlib
+        import json
+
+        d = {k: v for k, v in self.to_dict().items() if k != "origin"}
+        return hashlib.sha256(json.dumps(d, sort_keys=True, default=str).encode()).hexdigest()[:16]
+
    def to_dict(self) -> dict:
        out = {}
        for k in self.__dataclass_fields__:
@@ -114,11 +123,21 @@ def load(refresh: bool = False) -> dict[str, CatalogEntry]:
    if _cache is None or refresh:
        entries = _load_dir(catalog_dir() / "games", "bundled")
        entries.update(_load_remote())
-        entries.update(_load_dir(user_catalog_dir(), "user"))
+        for pkg, e in _load_dir(user_catalog_dir(), "user").items():
+            if not _newer(entries.get(pkg), e):  # the user's own recipe, unless a maintained one was verified later
+                entries[pkg] = e
        _cache = entries
    return _cache


+def _newer(maintained: CatalogEntry | None, user: CatalogEntry) -> bool:
+    """True when the bundled/remote entry was verified after the user's (e.g. a fix for a config the user shared)."""
+    if maintained is None:
+        return False
+    when = max(str(maintained.updated or ""), str(maintained.verified.get("date") or ""))
+    return when > str(user.verified.get("date") or "")
+
+
 def lookup(package: str) -> CatalogEntry | None:
    return load().get(package)

@@ -9,10 +9,13 @@ from ..patches import base
 from . import catalog
 from .catalog import TOGGLED_DEVICE

+# what a flat (non-VR) Windows game keeps of the PC VR patches
+FLAT_WINDOWS_PATCHES = ("pcvr.proton_tool", "pcvr.proton_env", "pcvr.proton_log", "pcvr.no_crash_reporter")
+

 def suggest(analysis: Analysis, use_catalog: bool = True) -> Recipe:
    entry = catalog.lookup(analysis.package) if use_catalog else None
-    recipe = Recipe(analysis.package, title=analysis.label)
+    recipe = Recipe(analysis.package, title=analysis.label, catalog_rev=entry.rev() if entry else "")
    # 1. heuristics / defaults from every patch module
    rift = (analysis.extra or {}).get("kind") == "rift"
    for patch in base.all_patches():
@@ -27,6 +30,10 @@ def suggest(analysis: Analysis, use_catalog: bool = True) -> Recipe:
    # 2. known-good catalog recipe overrides heuristics
    if rift:
        _rift_recipe(analysis, recipe, entry)
+        if (analysis.extra or {}).get("flat"):  # a Windows game without VR: Proton only, no VR parts
+            for pid in [p for p in recipe.patches if p not in FLAT_WINDOWS_PATCHES]:
+                recipe.patches.pop(pid)
+                recipe.reasons.pop(pid, None)
    elif entry:
        recipe.source = f"catalog ({entry.origin})"
        recipe.status, recipe.notes, recipe.title = entry.status, entry.notes, entry.title or recipe.title
@@ -176,7 +183,10 @@ def _non_quest(analysis: Analysis, recipe: Recipe) -> None:
    if kind == "none":
        # an ordinary (2D) Android app: no OpenXR to translate. Install it unchanged, or with only the launcher fix
        recipe.overport = False
-        needed = {"device.hide_navbar"} | ({"frame.launcher"} if analysis.has_info_category else set())  # LAUNCHER
+        # fixes that aren't about VR stay (navigation bar, SDL's clipboard, Unity text fields...), and the launcher
+        # entry when the app only has an INFO activity
+        needed = {pid for pid in recipe.patches if not base.get(pid).needs_vr and pid != "frame.launcher"}
+        needed |= {"frame.launcher"} if analysis.has_info_category else set()
        recipe.patches = {pid: v for pid, v in recipe.patches.items() if pid in needed}
        recipe.reasons = {pid: v for pid, v in recipe.reasons.items() if pid in recipe.patches}
        recipe.alt_patches = []
@@ -61,28 +61,55 @@ def from_path(path: Path) -> SourceGame | None:
    return SourceGame(display_name(path.name), apk, data, path, [a for a in apks if a != apk])


-def scan(root: Path, depth: int = 2) -> list[SourceGame]:
-    """Find games under root (the root itself, or folders up to `depth` levels down)."""
-    root = Path(root)
-    found = []
-    game = from_path(root)
-    if game:
-        return [game]
-    frontier = [root]
-    for _ in range(depth):
-        nxt = []
-        for d in frontier:
-            try:
-                children = sorted(p for p in d.iterdir() if p.is_dir() and not p.name.startswith(("_", ".")))
-            except OSError:
+def _no_quest_games_below(d: Path) -> bool:
+    """Folders not worth searching for APKs: a PC program (exe/dll files), a git checkout, a Python environment."""
+    try:
+        names = [p.name.lower() for p in d.iterdir()]
+    except OSError:
+        return True
+    return any(n.endswith((".exe", ".dll")) for n in names) or ".git" in names or "pyvenv.cfg" in names
+
+
+def _other_folders(d: Path, game: SourceGame) -> list[Path]:
+    """Subfolders of a folder with an APK that aren't that game's own data (OBB) folder."""
+    try:
+        subs = [p for p in d.iterdir() if p.is_dir() and not p.name.startswith(("_", "."))]
+    except OSError:
+        return []
+    own = {game.data_dir.resolve()} if game.data_dir else set()
+    return [p for p in subs if p.resolve() not in own and p.name.lower() not in ("obb", "android")]
+
+
+def scan(root: Path, depth: int = 5) -> list[SourceGame]:
+    """Find games under root, up to `depth` folder levels down (e.g. a download manager's
+    "<library>/data/downloads/<game>/game.apk"). A folder with an APK and nothing but that game's data folder is one
+    game; a folder that also has other folders is a collection: its loose APKs are games and its folders are searched
+    (a "VR" folder with a stray APK next to the game folders used to count as one game). PC program folders and code
+    checkouts aren't searched."""
+    found: list[SourceGame] = []
+
+    def walk(d: Path, level: int) -> None:
+        game = from_path(d)
+        if game and (level >= depth or not _other_folders(d, game)):
+            found.append(game)
+            return
+        if game:  # a collection with loose APKs: each is a game of its own
+            found.extend(g for g in (from_path(p) for p in sorted(d.glob("*.apk")) if _is_apk(p)) if g)
+        if level >= depth:
+            return
+        try:
+            children = sorted(p for p in d.iterdir() if p.is_dir() and not p.name.startswith(("_", ".")))
+        except OSError:
+            return
+        for child in children:
+            if game and game.data_dir and child.resolve() == game.data_dir.resolve():
                continue
-            for child in children:
-                g = from_path(child)
-                if g:
-                    found.append(g)
-                else:
-                    nxt.append(child)
-        frontier = nxt
-    loose = [p for p in root.glob("*.apk") if _is_apk(p)]
-    found += [g for g in (from_path(p) for p in loose) if g]
+            if from_path(child) or not _no_quest_games_below(child):
+                walk(child, level + 1)
+
+    root = Path(root)
+    if root.is_file():
+        g = from_path(root)
+        return [g] if g else []
+    walk(root, 0)
    return found
@@ -19,12 +19,14 @@ import flet as ft
 from .. import pipeline
 from ..core import applog, library
 from ..errors import explain
+from ..frame.connection import NOT_IN_LIBRARY, AgentFailed
 from ..i18n import fmt_size, tr, tr_n
 from ..recommend import catalog
 from . import components as C
+from . import jobs as jobs_module
 from . import theme as T
 from .components import install_state  # noqa: F401  (re-exported: tests and older callers import it from here)
-from .jobs import Job, JobManager
+from .jobs import Job

 NAV = [("library", tr("Library"), ft.Icons.GRID_VIEW_ROUNDED),
       ("frame", tr("Steam Frame"), ft.Icons.VIEW_IN_AR_ROUNDED),
@@ -51,7 +53,10 @@ class FramePortApp:
        self.files_view = None  # likewise (views/files.FilesView): keeps the location/folder between visits
        self.exe_queue: list[str] = []  # games whose executable the user should confirm (after a scan)
        self._failures: list[Job] = []  # failed installs/tests, shown together when the queue is done
-        self.jobs = JobManager(self._on_job)
+        self.jobs = jobs_module.shared()  # one queue per process, shared by every window session
+        self.jobs.subscribe(self._on_job)
+        self._handled_jobs: set[int] = set()  # finished jobs this session has reacted to (pop-ups, refreshes)
+        page.on_close = lambda e: self.jobs.unsubscribe(self._on_job)  # session gone: stop drawing into it
        from .updater import Updater

        self.updater = Updater(self)  # new FramePort releases (sidebar card, Library bar, one-click update)
@@ -365,8 +370,8 @@ class FramePortApp:
        self._refresh_sidebar()
        self.activity.refresh()
        self._keep_frame_awake()
-        if job and job.state in ("done", "failed", "cancelled") and job.finished and not getattr(job, "_handled", 0):
-            job._handled = 1
+        if job and job.state in ("done", "failed", "cancelled") and job.finished and id(job) not in self._handled_jobs:
+            self._handled_jobs.add(id(job))
            if job.kind == "app-update" and job.state != "done":
                self.updater.restart = None  # the update didn't get ready: don't quit
            self.updater.on_jobs_changed()  # an update waiting for the queue to empty installs now
@@ -393,8 +398,13 @@ class FramePortApp:
                           else (lambda e: self.show_activity(True)))
            elif job.state == "failed":
                msg = tr("{title} failed: {error}").format(title=job.title, error=job.error)
-                self.toast(msg, error=True, action=tr("Details"),
-                           on_action=lambda e: self.show_activity(True))
+                pkg = job.package
+                if job.kind in ("install", "test") and pkg:  # one click to the diagnostics + prefilled issue
+                    self.toast(msg, error=True, action=tr("Report a problem"),
+                               on_action=lambda e: self.report_problem_dialog(pkg))
+                else:
+                    self.toast(msg, error=True, action=tr("Details"),
+                               on_action=lambda e: self.show_activity(True))
            self.refresh_view()
            if job.kind == "scan" and self.exe_queue:
                self.page.run_thread(self.next_exe_choice)
@@ -494,7 +504,8 @@ class FramePortApp:
        if self.frame_state == "connected" and C.install_state(g, self.frame_info) in ("installed", "outdated"):
            out.append((tr("Play on Frame"), ft.Icons.PLAY_ARROW_ROUNDED, lambda e: self.play(pkg, "frame"), False,
                        tr("Starts the game through the Frame's Steam — put the headset on")))
-        if g.get("kind") == "rift" and pkg in self.pc_installs():
+        if g.get("kind") == "rift" and pkg in self.pc_installs() and \
+                not ((g.get("analysis") or {}).get("extra") or {}).get("flat"):
            out.append((tr("Play on this PC"), ft.Icons.PLAY_ARROW_ROUNDED, lambda e: self.play(pkg, "pc"), False,
                        tr("Starts the game through Steam on this PC (SteamVR + Revive)")))
        return out
@@ -503,7 +514,13 @@ class FramePortApp:
        title = self._title(pkg)

        def work():
-            res = self._target_for(to).launch(pkg) or {}
+            try:
+                res = self._target_for(to).launch(pkg) or {}
+            except AgentFailed as exc:
+                if to != "frame" or NOT_IN_LIBRARY not in str(exc):
+                    raise
+                self._add_then_play(pkg, title)  # e.g. the shortcut step failed during the install
+                return
            library.upsert_game(pkg, last_played=time.time())
            if to == "frame":
                self.toast(tr("Starting {title} on the Frame — put the headset on").format(title=title))
@@ -515,6 +532,26 @@ class FramePortApp:
                self.toast(tr("Starting SteamVR and {title} — put your headset on").format(title=title))
        self.run_bg(work)

+    def _add_then_play(self, pkg: str, title: str) -> None:
+        def run(job: Job):  # (jobs get the Job, not a reporter: this raised TypeError in 0.6.3)
+            target = self._target_for("frame")
+            status = target.add_to_library([pkg], job.reporter)
+            if status.get("state") == "waiting":  # Desktop Mode is open (FramePort on the Frame) or a game runs
+                return (tr("{title} will be in the Frame's Steam library when you're back in Gaming Mode: start it "
+                           "from there").format(title=title) if status.get("reason") == "desktop" else
+                        tr("{title} will be in the Frame's Steam library when the game that's running is closed")
+                        .format(title=title))
+            if not any(a.get("package") == pkg for a in status.get("added", [])):
+                raise RuntimeError(tr("{title} couldn't be added to the Frame's Steam library: {why}").format(
+                    title=title, why="; ".join(status.get("errors") or []) or tr("no answer from the Frame")))
+            time.sleep(15)  # Steam restarted: give it time to load the library before asking it to launch
+            target.launch(pkg)
+            library.upsert_game(pkg, last_played=time.time())
+            return tr("Starting {title} on the Frame — put the headset on").format(title=title)
+        self.toast(tr("{title} isn't in the Frame's Steam library yet: adding it (Steam restarts once)").format(
+            title=title))
+        self.submit(tr("Add to Steam library: {title}").format(title=title), run, pkg, "tool-frame")
+
    def quick_action(self, g: dict) -> tuple[str | None, str | None]:
        """(tooltip, kind) for a library card's round button; kind: play | install | update | reinstall (None: no
        button, e.g. while a job runs for the game or before a Frame is connected)."""
@@ -1015,19 +1052,53 @@ class FramePortApp:
            tr("Removes {title} from this PC's Steam library (Steam restarts once). "
               "The game folder isn't touched.").format(title=title)

+        delete_local, extra = self._delete_local_option(pkg)
+
        def run(job: Job):
            self._target_for(to).uninstall(pkg, keep_data=True)
            self._pc_cache = None
+            if delete_local and delete_local.value:
+                done, freed = pipeline.delete_local_files(pkg)
+                job.reporter.log(f"deleted {len(done)} item(s) on this PC, {fmt_size(freed)}")
+                self.go("library")
+                return tr("Uninstalled {title} and deleted its files on this PC ({size})").format(
+                    title=title, size=fmt_size(freed))
            return tr("Uninstalled {title}").format(title=title)
        C.confirm(self.page, tr("Uninstall {title}?").format(title=title), text, tr("Uninstall"),
-                  lambda: self.submit(tr("Uninstall {title}").format(title=title), run, pkg, "uninstall"), danger=True)
+                  lambda: self.submit(tr("Uninstall {title}").format(title=title), run, pkg, "uninstall"), danger=True,
+                  extra=extra)
+
+    def _delete_local_option(self, pkg: str) -> tuple[ft.Checkbox | None, ft.Control | None]:
+        """The 'Also delete this game's files on this PC' checkbox (off by default) with the paths it would delete."""
+        files = pipeline.local_game_files(pkg)
+        if not files:
+            return None, None
+        size = sum((sum(f.stat().st_size for f in p.rglob("*") if f.is_file()) if p.is_dir() else p.stat().st_size)
+                   for p in files)
+        box = ft.Checkbox(label=tr("Also delete this game's files on this PC ({size})").format(size=fmt_size(size)),
+                          value=False, active_color=T.ERROR)
+        from ..core import winhost
+
+        shown = [winhost.to_windows(p) if winhost.is_wsl() else str(p) for p in files]
+        return box, ft.Column([box, *[C.body("• " + s, T.TEXT_3) for s in shown[:4]]], spacing=T.px(4), tight=True)

    def remove_from_library(self, pkg: str) -> None:
        title = self._title(pkg)
+        delete_local, extra = self._delete_local_option(pkg)
+
+        def remove():
+            if delete_local and delete_local.value:
+                _done, freed = pipeline.delete_local_files(pkg)  # (removes the library entry too)
+                message = tr("Removed {title} and deleted its files on this PC ({size})").format(
+                    title=title, size=fmt_size(freed))
+            else:
+                library.remove_game(pkg)
+                message = tr("Removed {title}").format(title=title)
+            self.go("library")
+            self.toast(message)
        C.confirm(self.page, tr("Remove {title} from the library?").format(title=title),
-                  tr("Only FramePort's entry is removed. Your game files and anything installed stay."), tr("Remove"),
-                  lambda: (library.remove_game(pkg), self.go("library"),
-                           self.toast(tr("Removed {title}").format(title=title))), danger=True)
+                  tr("Removes FramePort's entry. Anything installed on the Frame stays."), tr("Remove"), remove,
+                  danger=True, extra=extra)

    def _target_for(self, to: str):
        if to == "pc":
@@ -1335,6 +1406,30 @@ class FramePortApp:
            except Exception:  # noqa: BLE001
                traceback.print_exc()

+    def _check_frame_restart(self, info: dict | None) -> None:
+        """The Frame restarted without shutting down (a crash, a GPU reset) soon after a FramePort game started: say
+        so, with Report a problem (Reddit 2026-10-03: "Resident Evil 4 crashes the Frame after the opening cutscene").
+        Uses the last boot seen (kept in settings, so a crash while FramePort was closed counts too)."""
+        from . import restart
+
+        boot = (info or {}).get("boot") or {}
+        if not boot.get("boot_id"):
+            return
+        seen = library.setting("frame.boot_id")
+        if seen == boot["boot_id"]:
+            return
+        library.set_setting("frame.boot_id", boot["boot_id"])
+        game = restart.crashed_game(boot, seen)
+        if game is None:
+            return
+        applog.log.info("Frame restarted unexpectedly after %s was started: %s", game["package"], boot)
+        library.upsert_game(game["package"], frame_restart=boot.get("boot_time")) if library.game(game["package"]) \
+            else None
+        pkg = game["package"]
+        self.toast(tr("Your Frame restarted unexpectedly while {title} was running (or soon after). If that game "
+                      "crashed it, please report it.").format(title=game.get("title") or pkg), error=True,
+                   action=tr("Report a problem"), on_action=lambda e: self.report_problem_dialog(pkg))
+
    def _battery_check(self, fetch: bool) -> None:
        """Battery level for the sidebar, and the queue on battery power: warn once, pause before the Frame would
        switch itself off mid-upload, continue when it charges (ui/battery.py)."""
@@ -1384,6 +1479,7 @@ class FramePortApp:
                self.toast(explain(exc), error=True)
            return False
        self.frame_info, self.frame_state = info, "connected"
+        self._check_frame_restart(info)
        self._awake_at = 0.0  # the lock went away with the old connection's Frame session: take it again
        self.jobs.resume()
        self.toast(tr("Your Frame is back: continuing"))
@@ -1459,6 +1555,7 @@ class FramePortApp:
                t.label = target.label
                save_target(target)
                old, self.target, self.frame_info, self.frame_state = self.target, t, info, "connected"
+                self._check_frame_restart(info)
                if old is not None and old is not t and not self.jobs.current():
                    try:  # the connection it replaces (a running job keeps using its own until it ends)
                        old.close()
@@ -1466,9 +1563,14 @@ class FramePortApp:
                        pass
                if not quiet:
                    self.toast(tr("Connected to {label}").format(label=target.label))
+                self._not_paired = False
            except Exception as exc:  # noqa: BLE001
+                from ..frame.connection import FrameNotPaired
+
                self.frame_state = "offline"
                self.frame_info = None
+                # reachable, but it doesn't let FramePort in: the Frame page points at the first-time setup
+                self._not_paired = isinstance(exc, FrameNotPaired)
                if not quiet:
                    self.toast(tr("Couldn't connect: {exc}").format(exc=explain(exc)), error=True)
            if self.route[0] in ("frame", "library", "game", "welcome"):
@@ -1502,6 +1604,7 @@ class FramePortApp:
                changed = info.get("installed") != (self.frame_info or {}).get("installed") or \
                    self.frame_state != "connected"
                self.frame_info, self.frame_state = info, "connected"
+                self._check_frame_restart(info)
            except Exception as exc:  # noqa: BLE001
                frame = getattr(target, "frame", None)
                if frame is not None and frame.alive():
@@ -1736,6 +1839,11 @@ def main(argv=None):
        return
    T.set_scale(T.scale_from_setting(library.setting("ui.scale", "auto")))  # before any view is built
    applog.log.info("ui scale %.2f", T.SCALE)
+    from .. import updates
+    from ..artwork import thumbs
+
+    if updates.install_kind() == "bundle":  # a packaged app finds artwork by file path, not by URL (GitHub #16)
+        thumbs.use_file_paths(True)
    ft.run(lambda page: FramePortApp(page), assets_dir=assets_dir())


@@ -45,6 +45,8 @@ def platform(g: dict) -> tuple[str, str, str]:
    """(short label, long label, help key) for a game's platform: what it was made for, not how it runs here."""
    if g.get("kind") == "rift":
        extra = ((g.get("analysis") or {}).get("extra") or {})
+        if extra.get("flat"):
+            return tr("Windows"), tr("Windows game (Proton)"), "platform_windows"
        oculus = extra.get("needs_revive") or extra.get("libovr")
        return tr("PC VR"), tr("PC VR · Oculus") if oculus else tr("PC VR"), "platform_pcvr"
    kind = (((g.get("analysis") or {}).get("extra") or {}).get("vr_kind")) or "quest"
@@ -68,9 +70,22 @@ def install_state(game: dict, frame_info: dict | None) -> str | None:
    built = {b.get("sha256"), b.get("alt_sha256")} - {None}
    if built and dep.get("sha256") and dep["sha256"] not in built:
        return "outdated"
+    if built and dep.get("sha256") in built and recipe_changed(game):
+        return "outdated"  # the recipe changed since this build (e.g. a catalog fix): it needs a new build
    return "outdated" if settings_diff(game, frame_info) else "installed"


+def recipe_changed(game: dict) -> bool:
+    from ..patches.base import recipe_fingerprint, revised_since_unrecorded
+
+    recipe, b = game.get("recipe") or {}, game.get("build") or {}
+    if not recipe:
+        return False
+    if b.get("recipe_fp"):
+        return b["recipe_fp"] != recipe_fingerprint(recipe)
+    return revised_since_unrecorded(recipe)
+
+
 def pc_outdated(g: dict, dep: dict) -> bool:
    """A PC install whose launch settings (pcvr patches + their parameters) differ from the game's recipe now."""
    installed = set((dep.get("recipe") or {}).get("patches") or [])
@@ -328,12 +343,14 @@ def bottom_fade(height: int | None = None, strength: float = 0.85) -> ft.Contain


 def confirm(page: ft.Page, heading: str, text: str, ok_label: str, on_ok: Callable[[], None],
-            danger: bool = False) -> None:
+            danger: bool = False, extra: ft.Control | None = None) -> None:
+    """A yes/no dialog; `extra` (e.g. an option checkbox) goes below the text and is read by on_ok."""
    def go(e):
        page.pop_dialog()
        on_ok()
+    content = body(text) if extra is None else ft.Column([body(text), extra], spacing=T.px(12), tight=True)
    page.show_dialog(ft.AlertDialog(
-        title=ft.Text(heading, weight=ft.FontWeight.W_600), content=ft.Container(body(text), width=T.px(420)),
+        title=ft.Text(heading, weight=ft.FontWeight.W_600), content=ft.Container(content, width=T.px(420)),
        bgcolor=T.SURFACE_2, shape=ft.RoundedRectangleBorder(radius=T.RADIUS),
        actions=[ghost(tr("Cancel"), on_click=lambda e: page.pop_dialog()),
                 ft.FilledButton(ok_label, on_click=go, style=ft.ButtonStyle(
@@ -28,6 +28,8 @@ HELP: dict[str, str] = _Translated({
                 "game (or right-click → Change executable) to pick it.",
    "platform_quest": "A Meta Quest game (APK). It's rebuilt for the Frame and runs in Lepton, Valve's Android "
                      "container.",
+    "platform_windows": "A Windows game without VR, added with \"Add one game folder…\". On the Frame, Proton runs it "
+                        "as a window (like Steam's own Windows games); it's in the Frame's Steam library.",
    "platform_pcvr": "A Windows PC VR game (OpenXR, SteamVR or Oculus). It runs on this PC with SteamVR, or on the "
                     "Frame with Proton. Oculus-only games also need Revive (Oculus → OpenXR).",
    "platform_android": "An ordinary Android app or game (no VR). It's installed unchanged and runs in Lepton, Valve's "
@@ -100,6 +100,10 @@ class JobManager:
    def subscribe(self, fn: Callable[[Job | None], None]) -> None:
        self._listeners.append(fn)

+    def unsubscribe(self, fn: Callable[[Job | None], None]) -> None:
+        if fn in self._listeners:
+            self._listeners.remove(fn)
+
    def submit(self, job: Job) -> Job:
        job.reporter.subscribe(lambda ev, j=job: self._event(j, ev))
        with self._cv:
@@ -225,3 +229,18 @@ class JobManager:
            if self.save_logs:
                applog.save_job_log(job.kind, job.package, job.state, job.text())
            self._notify(job, force=True)
+
+
+_shared: JobManager | None = None
+_shared_lock = threading.Lock()
+
+
+def shared() -> JobManager:
+    """The process's one job queue. Flet builds a new app object for every window session (a reconnect after sleep
+    or a reload): with a queue per session, the old session's job kept running unseen and the same game could be
+    built twice at once in the same work folder (both builds then failed)."""
+    global _shared
+    with _shared_lock:
+        if _shared is None:
+            _shared = JobManager()
+        return _shared
@@ -0,0 +1,16 @@
+"""Did the Frame crash because of a game? (no Flet) From the agent's boot state: a new boot whose predecessor didn't
+shut down cleanly, with a FramePort game started shortly before it."""
+from __future__ import annotations
+
+SOON = 3 * 3600  # a game started up to 3 h before the restart may have caused it
+
+
+def crashed_game(boot: dict, previous_boot_id: str | None) -> dict | None:
+    """The game to blame ({"package", "title", "time"}) or None. Only for a boot FramePort hasn't seen before whose
+    previous boot ended without a clean shutdown (a battery shutdown or a normal power-off is clean)."""
+    if not previous_boot_id or boot.get("boot_id") == previous_boot_id or boot.get("prev_clean") is not False:
+        return None
+    last, boot_time = boot.get("last_launch"), boot.get("boot_time")
+    if not last or not boot_time or not 0 <= boot_time - last.get("time", 0) <= SOON:
+        return None
+    return last
@@ -18,7 +18,9 @@ from .. import theme as T
 if TYPE_CHECKING:
    from ..app import FramePortApp

-SPECS = {key: (kind, default) for key, kind, default, _, _ in SETTINGS}
+# the dialog's settings: numbers and switches (text settings such as vk_shader_fix are recipe data: saving the dialog
+# keeps them as they are)
+SPECS = {key: (kind, default) for key, kind, default, _, _ in SETTINGS if kind in ("int", "float")}


 def default(key: str):
@@ -173,7 +173,7 @@ class FrameView:
                                                                                   devkit=f.source == "devkit")),
                ], spacing=T.S3), padding=ft.Padding(T.S3, T.px(8), T.S2, T.px(8)), bgcolor=T.SURFACE_2,
                    border_radius=T.RADIUS_SM))
-            found.controls = items or [C.body(tr("No Frames found. New Frame? Use first-time setup below. Otherwise "
+            found.controls = items or [C.body(tr("No Frames found. New Frame? Use first-time setup (step 1). Otherwise "
                                              "make sure Developer Mode is on (Settings → System → Developer) and "
                                              "the Frame is on the same network."))]
            found.controls.append(C.ghost(tr("Search again"), ft.Icons.REFRESH_ROUNDED, lambda e: app.run_bg(discover)))
@@ -215,7 +215,8 @@ class FrameView:
            discovery), which used to close it."""
            line = app.pairing.one_liner
            pair_box.controls = [
-                C.body(tr("On the Frame: Steam button → Power → Switch to Desktop, open Konsole and run:"), T.TEXT),
+                C.body(tr("On the Frame: SteamVR dashboard → Launch a program → Desktop, then app menu → System → "
+                          "Konsole, and run:"), T.TEXT),
                ft.Container(ft.Row([ft.Text(line, font_family="monospace", selectable=True, size=T.px(12),
                                             color=T.TEXT, expand=True),
                                     C.icon_btn(ft.Icons.CONTENT_COPY_ROUNDED, tr("Copy"), lambda e: app.copy(line))]),
@@ -225,7 +226,7 @@ class FrameView:
                        C.meta(tr("Waiting for your Frame… (code {code})").format(code=app.pairing.code))],
                       spacing=T.S2),
                C.meta(tr("It trusts this app, turns on Developer Mode and installs Lepton if needed. Turning on "
-                       "Developer Mode closes Desktop Mode; the setup finishes on its own and FramePort connects "
+                       "Developer Mode closes the desktop; the setup finishes on its own and FramePort connects "
                       "by itself. You only do this once.")),
            ]
            hint = getattr(app.pairing, "hint", "")
@@ -235,8 +236,8 @@ class FrameView:
                           weight=ft.FontWeight.W_600),
                    C.body(hint, T.TEXT),
                    C.meta(tr("Or turn on Developer Mode on the Frame (Settings → System → Developer): it then shows "
-                              "up above. Open Settings → Developer → Pair new host on the Frame, click Connect here "
-                              "and approve FramePort. That way needs no connection into this computer.")),
+                              "up under step 2. Open Settings → Developer → Pair new host on the Frame, click Connect "
+                              "there and approve FramePort. That way needs no connection into this computer.")),
                ], spacing=T.S2), "warn"))
            if update:
                pair_box.update()
@@ -252,7 +253,12 @@ class FrameView:
                          width=T.px(240), tooltip=C.tip(HELP["password"]), **style)
        saved = saved_targets()
        offline = None
-        if saved and app.frame_state == "offline":
+        if getattr(app, "_not_paired", False):  # it answered, but doesn't know FramePort yet
+            offline = C.callout(ft.Row([
+                C.body(tr("Your Frame isn't set up for FramePort yet. Run the first-time setup once (step 1)."), T.TEXT,
+                       expand=True),
+                C.primary(tr("Show setup command"), ft.Icons.TERMINAL_ROUNDED, pair)]), "warn")
+        elif saved and app.frame_state == "offline":
            unreachable = tr("{label} ({host}) isn't reachable. Make sure it's switched on and on the same "
                             "network.").format(label=saved[0].label, host=saved[0].host)
            offline = C.callout(ft.Row([C.body(unreachable, T.TEXT, expand=True),
@@ -280,10 +286,12 @@ class FrameView:
        return ft.Column([
            app.top_bar(tr("Connect your Steam Frame"), tr("FramePort installs games on the Frame over your network")),
            *([offline] if offline else []),
-            step(1, tr("On your network"), tr("Frames in Developer Mode show up here."), found, help="developer_mode"),
-            step(2, tr("First-time setup"), tr("New Frame? Run one command on it and FramePort does the rest."),
-                 C.secondary(tr("Show setup command"), ft.Icons.TERMINAL_ROUNDED, pair), pair_box,
+            step(1, tr("First-time setup"), tr("New Frame? Run one command on it and FramePort does the rest. Did this "
+                                               "once already? Your Frame appears under step 2."),
+                 C.primary(tr("Show setup command"), ft.Icons.TERMINAL_ROUNDED, pair), pair_box,
                 help="first_time_setup"),
+            step(2, tr("Already set up: on your network"), tr("Frames in Developer Mode show up here."), found,
+                 help="developer_mode"),
            step(3, tr("Enter the address"), tr("If you know the Frame's address."),
                 ft.Row([addr, pw, C.primary(tr("Connect"),
                                             on_click=lambda e: app.connect_manual(addr.value, pw.value))],
@@ -14,9 +14,10 @@ os.environ["FRAMEPORT_HOME"] = tempfile.mkdtemp(prefix="frameport-tests-")
@pytest.fixture(autouse=True)
 def isolated_home(tmp_path, monkeypatch):
    """Never touch the real user data dir (tools, keystores, library) from tests."""
-    from frameport.core import paths
+    from frameport.core import library, paths

    monkeypatch.setenv("FRAMEPORT_HOME", str(tmp_path / "home"))
+    monkeypatch.setattr(library, "REFRESH_ON_UPDATE", False)  # hand-made test libraries have no version marker
    yield
    paths._removed.clear()  # an uninstall test marks the data folder as removed for the rest of the process

@@ -0,0 +1,66 @@
+// Test fixture for tests/test_langpack.py: a stand-in for OVRPort's platform loader (libovrplatformloader.so).
+// Like the real one it answers ovr_LanguagePack_GetCurrent/SetCurrent with `return 0` and keeps its own message queue;
+// AssetFile_GetList/StatusById queue one message that carries one "store" asset (id 7).
+// Build: cc -shared -fPIC -O1 fakeloader.c -o libovrplatformloader.so
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+typedef uint64_t u64;
+typedef struct { uint32_t type; u64 req; int err; } fmsg;
+typedef struct { u64 id; char type[16]; char path[32]; } fdet;
+
+static fmsg *q[16];
+static int qn, freed;
+static u64 next_req = 100;
+static fdet store = {7, "store", "/store/a"};
+static int arr_handle;
+
+static u64 post(uint32_t type, int err) {
+    fmsg *m = calloc(1, sizeof *m);
+    m->type = type;
+    m->req = next_req++;
+    m->err = err;
+    q[qn++] = m;
+    return m->req;
+}
+
+u64 ovr_AssetFile_GetList(void) {
+    if (getenv("FAKE_SILENT_LIST")) return next_req++;  // asks, never answers (the case the timeout fallback is for)
+    return post(0x4AFC6F74u, 0);
+}
+u64 ovr_AssetFile_StatusById(u64 id) { return post(0x5D955D38u, id != 7); }
+u64 ovr_LanguagePack_GetCurrent(void) { return 0; }
+u64 ovr_LanguagePack_SetCurrent(const char *tag) { (void)tag; return 0; }
+
+void *ovr_PopMessage(void) {
+    if (!qn) return NULL;
+    fmsg *m = q[0];
+    memmove(q, q + 1, sizeof(q[0]) * (size_t)--qn);
+    return m;
+}
+void ovr_FreeMessage(void *m) { freed++; free(m); }
+uint32_t ovr_Message_GetType(const void *m) { return ((const fmsg *)m)->type; }
+u64 ovr_Message_GetRequestID(const void *m) { return ((const fmsg *)m)->req; }
+_Bool ovr_Message_IsError(const void *m) { return ((const fmsg *)m)->err != 0; }
+void *ovr_Message_GetError(const void *m) { (void)m; return NULL; }
+void *ovr_Message_GetAssetDetails(const void *m) { return ((const fmsg *)m)->err ? NULL : &store; }
+void *ovr_Message_GetAssetDetailsArray(const void *m) { (void)m; return &arr_handle; }
+size_t ovr_AssetDetailsArray_GetSize(const void *a) { (void)a; return 1; }
+void *ovr_AssetDetailsArray_GetElement(const void *a, size_t i) { (void)a; return i == 0 ? &store : NULL; }
+u64 ovr_AssetDetails_GetAssetId(const void *d) { return ((const fdet *)d)->id; }
+const char *ovr_AssetDetails_GetAssetType(const void *d) { return ((const fdet *)d)->type; }
+const char *ovr_AssetDetails_GetDownloadStatus(const void *d) { (void)d; return "available"; }
+const char *ovr_AssetDetails_GetFilepath(const void *d) { return ((const fdet *)d)->path; }
+const char *ovr_AssetDetails_GetIapStatus(const void *d) { (void)d; return "free"; }
+void *ovr_AssetDetails_GetLanguage(const void *d) { (void)d; return NULL; }
+const char *ovr_AssetDetails_GetMetadata(const void *d) { (void)d; return ""; }
+
+// not part of the SDK: lets the test see that our wrapper frees the dispatcher's own message
+int fake_freed(void) { return freed; }
+void fake_late_list(u64 req) {  // the dispatcher answers a GetList after all (late)
+    fmsg *m = calloc(1, sizeof *m);
+    m->type = 0x4AFC6F74u;
+    m->req = req;
+    q[qn++] = m;
+}
@@ -49,6 +49,23 @@ def test_launcher_template(monkeypatch, tmp_path):
    assert subprocess.run(["bash", "-n", str(anchor / "launch.sh")]).returncode == 0


+def test_launcher_repairs_save_folder_permissions(monkeypatch, tmp_path):
+    """SUPERHOT creates its cloud save folder with mode 1700 and quits when it can't write there (Lepton's app
+    writes through the folder's group): the launcher gives every storage folder owner and group write permission."""
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "anchor"
+    anchor.mkdir()
+    a.write_launcher(str(anchor), str(tmp_path / "game"), "com.x.y", "T", 1, "/lepton/lepton", {})
+    fix = next(line for line in (anchor / "launch.sh").read_text().splitlines() if line.startswith("fix_perms()"))
+    saves = tmp_path / "game" / "lepton-data" / "external" / "Android" / "data" / "com.x.y" / "files" / "cloud"
+    saves.mkdir(parents=True)
+    os.chmod(saves, 0o1700)
+    if os.stat(saves).st_mode & 0o777 != 0o700:
+        pytest.skip("filesystem doesn't keep modes")
+    subprocess.run(["bash", "-c", f"app_dir={tmp_path / 'game'}\n{fix}\nfix_perms"], check=True)
+    assert os.stat(saves).st_mode & 0o770 == 0o770
+
+
 def test_cli_protocol(tmp_path):
    p = subprocess.run([sys.executable, str(AGENT), "nope"], capture_output=True, text=True)
    assert p.returncode == 2 and json.loads(p.stdout)["ok"] is False
@@ -369,11 +386,32 @@ def test_launch_uses_steam_shortcut(monkeypatch, tmp_path):
    (anchor / "deployment.json").write_text(json.dumps(deployment))
    calls = []
    monkeypatch.setattr(a, "run", lambda cmd, **k: (calls.append(cmd), SimpleNamespace(returncode=0, stdout=""))[1])
+    cfg = tmp_path / ".local/share/Steam/userdata/42/config"
+    cfg.mkdir(parents=True)
+    with pytest.raises(a.AgentError, match="not in the Frame's Steam library"):
+        a.cmd_launch({"package": "com.x.y"})
+    exe = f'"{anchor}/launch.sh"'
+    a.upsert_shortcut(str(cfg / "shortcuts.vdf"), exe, "Old title", str(anchor))  # keeps its first id
    r = a.cmd_launch({"package": "com.x.y"})
-    assert r["gameid"] == (2546384938 << 32) | 0x02000000
+    assert r["gameid"] == (a.shortcut_appid(exe, "Old title") << 32) | 0x02000000
    assert calls[-1][-1] == f"steam://rungameid/{r['gameid']}" and calls[-1][0] == "systemd-run"


+def test_library_users_prefers_the_signed_in_account(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    steam = tmp_path / ".local/share/Steam"
+    with pytest.raises(a.AgentError, match="signed-in"):
+        a.library_users()
+    for u in ("12345", "999"):
+        (steam / "userdata" / u / "config").mkdir(parents=True)
+    assert a.library_users() == ["12345", "999"]  # unknown: every account (used to fail with 2 accounts)
+    (steam / "config").mkdir()
+    (steam / "config/loginusers.vdf").write_text(
+        '"users"\n{\n\t"76561197960278073"\n\t{\n\t\t"MostRecent"\t\t"1"\n\t}\n'
+        '\t"76561197960266727"\n\t{\n\t\t"MostRecent"\t\t"0"\n\t}\n}\n')
+    assert a.library_users() == ["12345", "999"]  # every account, the signed-in one first
+
+
 def test_uninstall_quest_keeping_saves_drops_the_install_record(monkeypatch, tmp_path):
    a = load_agent(monkeypatch, tmp_path)
    anchor = tmp_path / "Applications/quest-frame/com.x.y"
@@ -793,3 +831,85 @@ def test_keyboard_session_reports_a_refused_device(monkeypatch, tmp_path):
    out = io.StringIO()
    assert a.keyboard_session(io.StringIO(""), out) == 1
    assert json.loads(out.getvalue())["ready"] is False
+
+
+def test_boot_state_finds_unclean_previous_boot_and_last_launch(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    base = tmp_path / "game"
+    base.mkdir()
+    (base / "launch.log").write_text("x")
+    os.utime(base / "launch.log", (1000, 1000))
+    monkeypatch.setattr(a, "cmd_list_installed", lambda args: {"games": [{"package": "com.x", "title": "X",
+                                                                           "base": str(base)}]})
+    real_open = open
+
+    def fake_open(path, *args, **kw):
+        if path == "/proc/sys/kernel/random/boot_id":
+            from io import StringIO
+            return StringIO("abc\n")
+        if path == "/proc/stat":
+            from io import StringIO
+            return StringIO("cpu 1 2 3\nbtime 2000\n")
+        return real_open(path, *args, **kw)
+    monkeypatch.setattr(a, "open", fake_open, raising=False)
+    monkeypatch.setattr(a, "run", lambda cmd, **kw: SimpleNamespace(stdout="kernel: msm_dpu ... fault\n"))
+    st = a.boot_state()
+    assert st == {"boot_id": "abc", "boot_time": 2000, "prev_clean": False,
+                  "last_launch": {"package": "com.x", "title": "X", "time": 1000.0}}
+    monkeypatch.setattr(a, "run", lambda cmd, **kw: SimpleNamespace(stdout="Reached target System Power Off\n"))
+    assert a.boot_state()["prev_clean"] is False  # cached for this boot: worked out once
+
+
+def test_flat_windows_game_launcher_and_shortcut(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    monkeypatch.setattr(a, "compat_command", lambda d: ["/proton", "waitforexitandrun"])
+    anchor, base = tmp_path / "anchor", tmp_path / "base"
+    anchor.mkdir()
+    tool = {"dir": "/tools/proton", "name": "Proton 11"}
+    a.write_proton_launcher(str(anchor), str(base), "rift.game", "Game", 123, tool, "Game.exe", False, {}, vr=False)
+    flat = (anchor / "launch.sh").read_text()
+    a.write_proton_launcher(str(anchor), str(base), "rift.game", "Game", 123, tool, "Game.exe", False, {})
+    vr = (anchor / "launch.sh").read_text()
+    assert "SteamGameId" not in flat and "export SteamGameId=123" in vr  # Proton sets up VR only with it
+    assert "STEAM_COMPAT_APP_ID=123" in flat
+    vdf = str(tmp_path / "shortcuts.vdf")
+    a.upsert_shortcut(vdf, '"/x/launch.sh"', "Game", "/x", tag="Windows game on Frame", openvr=False)
+    entry = a.vdf_decode(open(vdf, "rb").read())["shortcuts"]["0"]
+    assert entry["OpenVR"] == 0 and entry["tags"]["0"] == "Windows game on Frame"
+
+
+def test_reinstall_with_unchanged_shortcut_does_not_restart_steam(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "Applications/quest-frame/com.x.y"
+    (anchor / "artwork").mkdir(parents=True)
+    (anchor / "artwork/portrait.jpg").write_bytes(b"art")
+    (anchor / "deployment.json").write_text(json.dumps({"package": "com.x.y", "appid": 1, "title": "X", "base": "b"}))
+    cfg = tmp_path / ".local/share/Steam/userdata/42/config"
+    cfg.mkdir(parents=True)
+    exe, title, start, icon, tag, tags, openvr = a.shortcut_args("com.x.y")
+    assert a.library_changes(["42"], ["com.x.y"])  # not in the library yet
+    a.upsert_shortcut(str(cfg / "shortcuts.vdf"), exe, title, start, icon, tag, tags=tags, openvr=openvr)
+    assert not a.library_changes(["42"], ["com.x.y"])  # a reinstall: nothing to change
+    stops = []
+    monkeypatch.setattr(a, "stop_steam", lambda: stops.append(1) or True)
+    monkeypatch.setattr(a, "start_steam", lambda s: stops.append(2))
+    a.shortcuts_worker(json.dumps({"packages": ["com.x.y"], "remove": []}))
+    status = json.load(open(a.STATUS_FILE))
+    assert not stops and status["state"] == "done" and status["unchanged"]
+    assert status["added"][0]["package"] == "com.x.y"
+    assert (cfg / "grid").is_dir() and any(p.name.endswith("p.jpg") for p in (cfg / "grid").iterdir())
+
+
+def test_shortcuts_lost_after_steam_restart(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "Applications/quest-frame/com.x.y"
+    anchor.mkdir(parents=True)
+    (anchor / "deployment.json").write_text(json.dumps({"package": "com.x.y", "appid": 1, "title": "X", "base": "b"}))
+    cfg = tmp_path / ".local/share/Steam/userdata/42/config"
+    cfg.mkdir(parents=True)
+    monkeypatch.setattr(a, "run", lambda cmd, **k: SimpleNamespace(returncode=0, stdout=""))
+    monkeypatch.setattr(a.time, "sleep", lambda s: None)
+    assert a.shortcuts_lost(["42"], ["com.x.y"]) == ["com.x.y"]  # Steam put its old shortcuts.vdf back
+    exe, title, start, icon, tag, tags, openvr = a.shortcut_args("com.x.y")
+    a.upsert_shortcut(str(cfg / "shortcuts.vdf"), exe, title, start, icon, tag, tags=tags, openvr=openvr)
+    assert a.shortcuts_lost(["42"], ["com.x.y"]) == []
@@ -312,6 +312,22 @@ def test_picked_art_survives_installs(monkeypatch):
    assert (d / "portrait.png").read_bytes() == png("red")


+
+def test_generated_cover_still_gets_a_steam_placeholder():
+    """The library's generated cover/banner (apps without store art, e.g. WiiCompiled) aren't store art: Steam still
+    gets the placeholder set (it used to get nothing at all, a blank tile in the Frame's library)."""
+    from PIL import Image
+
+    from frameport.artwork import fetch, steam
+
+    pkg = "org.example.generated"
+    d = fetch.artwork_dir(pkg)
+    d.mkdir(parents=True, exist_ok=True)
+    Image.new("RGB", (600, 900)).save(d / "cover.jpg")
+    Image.new("RGB", (920, 430)).save(d / "banner.jpg")
+    art = steam.steam_set(pkg, title="Generated Cover App")
+    assert {"portrait", "landscape", "hero"} <= set(art)
+
 def test_apps_without_store_art_get_a_cover(tmp_path):
    """FramePort's library shows a cover (name + APK icon) for apps no store knows; store art always wins."""
    import zipfile
@@ -0,0 +1,15 @@
+"""Every bundled catalog file parses (the loader skips broken files silently, so a typo would hide a game)."""
+from pathlib import Path
+
+import yaml
+
+from frameport.recommend.catalog import CatalogEntry, catalog_dir
+
+
+def test_every_catalog_file_parses():
+    files = sorted((catalog_dir() / "games").glob("*.yaml"))
+    assert files
+    for f in files:
+        d = yaml.safe_load(f.read_text(encoding="utf-8"))
+        e = CatalogEntry.from_dict(d, "bundled")
+        assert e.package == Path(f).stem, f
@@ -0,0 +1,114 @@
+"""Logging in to the Frame (Reddit 2026-10-03: "Couldn't connect: no authentication methods available" even with the
+right password). paramiko ends the key/agent attempt with a plain SSHException when this PC has no SSH keys; that must
+not stop the password attempt, and the final error must say what to do."""
+import paramiko
+import pytest
+
+from frameport.errors import explain
+from frameport.frame import connection as C
+
+
+class _Client:
+    """Stands in for paramiko.SSHClient: `script` maps attempt kind -> exception (or None = success)."""
+    script: dict = {}
+    tried: list = []
+
+    def load_host_keys(self, path):
+        pass
+
+    def set_missing_host_key_policy(self, policy):
+        pass
+
+    def close(self):
+        pass
+
+    def save_host_keys(self, path):
+        pass
+
+    def connect(self, pkey=None, password=None, allow_agent=False, look_for_keys=False, **kw):
+        kind = "password" if password else "agent" if allow_agent else "app_key"
+        _Client.tried.append(kind)
+        exc = _Client.script.get(kind)
+        if exc is not None:
+            raise exc
+
+
+@pytest.fixture
+def fake_ssh(monkeypatch):
+    monkeypatch.setattr(C.paramiko, "SSHClient", _Client)
+    monkeypatch.setattr(C, "app_keys", lambda: ["key"])
+    _Client.tried = []
+    return _Client
+
+
+NO_METHODS = paramiko.SSHException("No authentication methods available")
+
+
+def test_no_ssh_keys_on_the_pc_still_tries_the_password(fake_ssh, monkeypatch):
+    fake_ssh.script = {"app_key": paramiko.AuthenticationException("Authentication failed."), "agent": NO_METHODS,
+                       "password": paramiko.AuthenticationException("Authentication failed.")}
+    frame = C.Frame(C.FrameTarget("10.0.0.2"), password="secret")
+    with pytest.raises(C.FrameNotPaired) as err:
+        frame.connect()
+    assert fake_ssh.tried == ["app_key", "agent", "password"]
+    assert err.value.tried_password and "password was refused" in str(err.value)
+    assert "refused that password" in explain(err.value)
+
+
+def test_unpaired_frame_without_password_explains_the_setup(fake_ssh):
+    fake_ssh.script = {"app_key": paramiko.AuthenticationException("Authentication failed."), "agent": NO_METHODS}
+    with pytest.raises(C.FrameNotPaired) as err:
+        C.Frame(C.FrameTarget("10.0.0.2")).connect()
+    assert "authentication failed" in str(err.value).lower()  # app.connect's devkit fallback looks for this
+    assert "first-time setup" in explain(err.value) and "isn't set up" in explain(err.value)
+    assert explain(NO_METHODS).startswith("This Frame isn't set up")
+
+
+def test_network_errors_still_end_the_attempts(fake_ssh):
+    fake_ssh.script = {"app_key": paramiko.SSHException("Error reading SSH protocol banner")}
+    with pytest.raises(paramiko.SSHException, match="banner"):
+        C.Frame(C.FrameTarget("10.0.0.2"), password="x").connect()
+    assert fake_ssh.tried == ["app_key"]
+
+
+def test_upload_resumes_after_a_transient_error(tmp_path, monkeypatch):
+    from frameport.frame.connection import Frame, FrameTarget
+
+    f = Frame(FrameTarget("h"))
+    calls = []
+
+    def flaky(local, remote, progress, resume, mkdir):
+        calls.append(1)
+        if len(calls) == 1:
+            raise OSError(22, "Invalid argument")
+    monkeypatch.setattr(f, "_put", flaky)
+    monkeypatch.setattr(f, "alive", lambda: True)
+    monkeypatch.setattr("frameport.frame.connection.time.sleep", lambda s: None)
+    f.put(tmp_path / "x.bin", "/r/x.bin")
+    assert len(calls) == 2
+
+
+def test_framport_on_the_frame_targets_itself(tmp_path, monkeypatch):
+    from frameport.frame import connection, local
+
+    monkeypatch.setattr(local, "on_frame", lambda: True)
+    monkeypatch.setattr(local.Path, "home", lambda: tmp_path)
+    targets = connection.saved_targets()
+    assert targets and targets[0].host == "127.0.0.1" and targets[0].name == local.LOCAL_NAME
+    keys = (tmp_path / ".ssh/authorized_keys").read_text()
+    assert connection.app_public_key().split()[1] in keys
+    assert not local.authorize_self(connection.app_public_key())  # once
+    monkeypatch.setattr(local, "on_frame", lambda: False)
+    assert connection.saved_targets()[0].host == "127.0.0.1"  # remembered like any Frame
+
+
+def test_app_data_on_the_frame_stays_out_of_the_agents_folder(monkeypatch, tmp_path):
+    from frameport.core import paths
+    from frameport.frame import local
+
+    monkeypatch.delenv("FRAMEPORT_HOME", raising=False)
+    monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path))
+    monkeypatch.setattr(local, "on_frame", lambda: True)
+    assert paths.user_data_dir() == tmp_path / "frameport-app"  # the agent owns (and purges) .../frameport
+    monkeypatch.setattr(local, "on_frame", lambda: False)
+    assert paths.user_data_dir() == tmp_path / "frameport"
@@ -216,12 +216,17 @@ def test_catalog_from_issue(tmp_path):
    assert s.main([str(_write(tmp_path, BODY)), "--issue", "7", "--out", str(tmp_path)]) == 0
    d = yaml.safe_load((tmp_path / "com.example.game.yaml").read_text())
    assert d["frame"] == ["frame.ovrstubs"] and d["verified"]["issue"] == 7
+    with_device = BODY.replace("- frame.ovrstubs", "- frame.ovrstubs\ndevice:\n- device.text_input_window")
+    assert s.main([str(_write(tmp_path, with_device)), "--out", str(tmp_path)]) == 0
+    assert yaml.safe_load((tmp_path / "com.example.game.yaml").read_text())["device"] == ["device.text_input_window"]


@pytest.mark.parametrize("bad", ["package: ../../etc/passwd\ntitle: x", "package: com.a.b\ntitle: x\nevil: 1",
                                 "package: com.a.b\ntitle: x\nstatus: great",
                                 "package: com.a.b\ntitle: x\nframe: [\"$(rm)\"]",
-                                 "package: com.a.b\ntitle: x\ndevice_files: {'../x': 1}", "- a list"])
+                                 "package: com.a.b\ntitle: x\ndevice_files: {'../x': 1}", "- a list",
+                                 "package: com.a.b\ntitle: x\nframe: [frame.no_such_patch]",
+                                 "package: com.a.b\ntitle: x\ndevice: device.text_input_window"])
 def test_catalog_from_issue_rejects(tmp_path, bad):
    s = _script()
    body = BODY.split("```yaml")[0] + "```yaml\n" + bad + "\n```\n"
@@ -260,7 +265,9 @@ def test_agent_collect_diag(monkeypatch, tmp_path):
    (xr / "XRService-12-31-50.log").write_text("xr")
    host = a.cmd_collect_diag({})
    assert host["agent_version"] == a.AGENT_VERSION and "openxr_layers" in host["host"]
-    assert host["files"] == {"XRService-12-31-50.log": "xr"}
+    # (plus the previous boot's journal excerpts when this machine has a journal)
+    assert {k: v for k, v in host["files"].items() if not k.startswith("previous-boot")} == \
+        {"XRService-12-31-50.log": "xr"}
    res = a.cmd_collect_diag({"package": "com.x.y", "max_bytes": 1000})
    f = res["files"]
    assert res["installed"] and {"deployment.json", "launch.sh", "settings.conf", "launch.log", "logcat-main.log",
@@ -37,6 +37,7 @@ def test_known_failures(exc, start):

 def test_other_errors_keep_their_message():
    auth = ConnectionError("SSH authentication failed (bad key). Run the FramePort bootstrap on the Frame.")
-    assert explain(auth) == str(auth) and not is_connection_error(auth)  # already says what to do
+    # login refused: points at the first-time setup, and isn't a "Frame went away" (the queue mustn't wait for it)
+    assert explain(auth).startswith("This Frame isn't set up") and not is_connection_error(auth)
    assert explain(AgentFailed("Lepton is not installed (Developer Mode → …)")).startswith("Lepton is not installed")
    assert explain(RuntimeError()) == "RuntimeError"
@@ -0,0 +1,416 @@
+"""Language packs (native/langpack + patch frame.langpacks).
+
+The C library is compiled for this host and driven through ctypes against a stand-in for OVRPort's platform loader
+(tests/fixtures/src/fakeloader.c) that went through the real ELF patch (elf.hide_exports): lookups for the hidden
+names no longer find the loader's functions, and the library still reaches them by reading the loader's .dynsym.
+Needs a C compiler on Linux; the device side (bionic) is not covered here."""
+import ctypes as C
+import platform
+import re
+import shutil
+import subprocess
+import time
+import zipfile
+from pathlib import Path
+
+import pytest
+
+from frameport.analysis import elf, langpacks
+from frameport.apk.workspace import ApkWorkspace
+from frameport.core.events import Reporter
+from frameport.core.models import Analysis
+from frameport.patches import base
+from frameport.patches.frame import langpack as patch_mod
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "native/langpack/langpack.c"
+FAKE = Path(__file__).with_name("fixtures") / "src" / "fakeloader.c"
+CC = shutil.which("cc") or shutil.which("gcc") or shutil.which("clang")
+pytestmark = pytest.mark.skipif(not CC or platform.system() != "Linux", reason="needs a C compiler on Linux")
+
+GETLIST, STATUSBYID, GETCURRENT, SETCURRENT = 0x4AFC6F74, 0x5D955D38, 0x1F90F0D5, 0x5B4FBBE0
+VOIDP = C.c_void_p
+
+
+def _analysis(**kw):
+    d = dict(package="com.example.questgame", version="1.0", label="Quest Game", abis=["arm64-v8a"], engine="Unity",
+             xr="OpenXR", graphics="Vulkan (declared in manifest)", direct_vrapi=False, libs=[], launcher_activity=None,
+             has_info_category=True, meta_permissions=[], uses_glad_gl=False, unity_msaa_levels=0,
+             oculus_os_classes=False, is_overport_output=True, debuggable=True, extra={"size": 1})
+    d.update(kw)
+    return Analysis(**d)
+
+
+def _compile(src, out, *extra):
+    subprocess.run([CC, "-shared", "-fPIC", "-O1", "-Wall", "-Wextra", "-Werror", *extra, str(src), "-o", str(out),
+                    "-ldl", "-lpthread"], check=True, capture_output=True)
+
+
+@pytest.fixture(scope="module")
+def built(tmp_path_factory):
+    d = tmp_path_factory.mktemp("langpack-build")
+    _compile(FAKE, d / "fakeloader.so")
+    _compile(SRC, d / "langpack.so", "-fvisibility=hidden")
+    _compile(SRC, d / "langpack_fast.so", "-fvisibility=hidden", "-DFP_LIST_TIMEOUT_MS=100")
+    original = (d / "fakeloader.so").read_bytes()
+    patched, hidden = elf.hide_exports(original, patch_mod.EXPORTS)
+    return {"lib": d / "langpack.so", "fast": d / "langpack_fast.so", "original": original, "patched": patched,
+            "hidden": hidden}
+
+
+def _dlclose(lib):
+    libdl = C.CDLL(None)
+    libdl.dlclose.argtypes = [VOIDP]
+    libdl.dlclose(lib._handle)
+
+
+class Api:
+    """The library under test (`lp`) and the stand-in loader behind it (`loader`)."""
+
+    def __init__(self, lp, loader):
+        self.lp, self.loader = lp, loader
+
+    def f(self, name, res, *args, lib=None):
+        fn = getattr(lib or self.lp, name)
+        fn.restype, fn.argtypes = res, list(args)
+        return fn
+
+    def pop(self):
+        return self.f("ovr_PopMessage", VOIDP)()
+
+    def msg_type(self, m):
+        return self.f("ovr_Message_GetType", C.c_uint32, VOIDP)(m)
+
+    def req_id(self, m):
+        return self.f("ovr_Message_GetRequestID", C.c_uint64, VOIDP)(m)
+
+    def is_error(self, m):
+        return bool(self.f("ovr_Message_IsError", C.c_bool, VOIDP)(m))
+
+    def free(self, m):
+        self.f("ovr_FreeMessage", None, VOIDP)(m)
+
+    def details(self, d):
+        s = lambda name: self.f(name, C.c_char_p, VOIDP)(d)  # noqa: E731
+        lang = self.f("ovr_AssetDetails_GetLanguage", VOIDP, VOIDP)(d)
+        out = {"id": self.f("ovr_AssetDetails_GetAssetId", C.c_uint64, VOIDP)(d),
+               "type": s("ovr_AssetDetails_GetAssetType"), "status": s("ovr_AssetDetails_GetDownloadStatus"),
+               "path": s("ovr_AssetDetails_GetFilepath")}
+        if lang:
+            ls = lambda name: self.f(name, C.c_char_p, VOIDP)(lang)  # noqa: E731
+            out.update(tag=ls("ovr_LanguagePackInfo_GetTag"), en=ls("ovr_LanguagePackInfo_GetEnglishName"),
+                       native=ls("ovr_LanguagePackInfo_GetNativeName"))
+        return out
+
+    def ask(self, name, *args):
+        """Send a request, pop the answer, return (message type, error?, payload getter result)."""
+        argtypes = [C.c_char_p] if args and isinstance(args[0], bytes) else ([C.c_uint64] if args else [])
+        req = self.f(name, C.c_uint64, *argtypes)(*args)
+        m = self.pop()
+        assert m and self.req_id(m) == req
+        return m
+
+
+def _api(built, tmp_path, monkeypatch, which):
+    monkeypatch.delenv("FRAMEPORT_LANGPACK", raising=False)
+    lib = tmp_path / "lib"
+    lib.mkdir()
+    (lib / "libovrplatformloader.so").write_bytes(built["patched"])  # the name the library looks for
+    shutil.copy(built[which], lib / "libfp_langpack.so")
+    loader = C.CDLL(str(lib / "libovrplatformloader.so"))
+    lp = C.CDLL(str(lib / "libfp_langpack.so"))
+    yield Api(lp, loader)
+    _dlclose(lp)
+    _dlclose(loader)
+
+
+@pytest.fixture
+def api(built, tmp_path, monkeypatch):
+    yield from _api(built, tmp_path, monkeypatch, "lib")
+
+
+@pytest.fixture
+def api_fast(built, tmp_path, monkeypatch):  # same library with a 100 ms GetList timeout
+    yield from _api(built, tmp_path, monkeypatch, "fast")
+
+
+@pytest.fixture
+def packs(tmp_path, monkeypatch):
+    root = tmp_path / "obb"
+    (root / "sub").mkdir(parents=True)
+    for rel in ("de.lang", "en-us.lang", "sub/fr.lang", "notes.txt", "x y.lang"):
+        (root / rel).write_bytes(b"data")
+    monkeypatch.setenv("FRAMEPORT_LANGPACK_DIRS", str(root))
+    return root
+
+
+def test_exports_match_the_c_source():
+    text = SRC.read_text()
+    defined = set(re.findall(r"^EXPORT\s+[^;{(]*?\b(ovr_\w+)\s*\(", text, re.M))
+    assert defined == set(patch_mod.EXPORTS)
+    assert len(patch_mod.EXPORTS) == len(defined)
+
+
+def test_hide_exports_keeps_symbols_but_hides_them_from_lookup(built, tmp_path):
+    assert set(built["hidden"]) >= {"ovr_PopMessage", "ovr_LanguagePack_GetCurrent", "ovr_AssetFile_GetList"}
+    assert "fake_freed" not in built["hidden"]
+    d = tmp_path / "orig"
+    d.mkdir()
+    (d / "a.so").write_bytes(built["original"])
+    (d / "b.so").write_bytes(built["patched"])
+    orig, patched = C.CDLL(str(d / "a.so")), C.CDLL(str(d / "b.so"))
+    try:
+        assert orig.ovr_PopMessage and patched.fake_freed  # visible before, others untouched
+        with pytest.raises(AttributeError):
+            patched.ovr_PopMessage  # noqa: B018  hidden: a lookup goes on to the next library
+        # the entries are still defined (the library reads their addresses from .dynsym)
+        assert "ovr_PopMessage" in elf.dyn_symbols(built["patched"], True)
+        assert elf.hide_exports(built["patched"], patch_mod.EXPORTS)[1] == []  # idempotent
+    finally:
+        _dlclose(orig)
+        _dlclose(patched)
+
+
+def test_get_current_without_a_choice_is_an_error_when_several_packs(api, packs):
+    m = api.ask("ovr_LanguagePack_GetCurrent")
+    assert api.msg_type(m) == GETCURRENT and api.is_error(m)
+    err = api.f("ovr_Message_GetError", VOIDP, VOIDP)(m)
+    assert api.f("ovr_Error_GetCode", C.c_int, VOIDP)(err) == 404
+    assert b"no language pack" in api.f("ovr_Error_GetMessage", C.c_char_p, VOIDP)(err)
+    assert not api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m)
+    api.free(m)
+
+
+def test_get_current_by_environment_and_single_pack(api, packs, monkeypatch, tmp_path):
+    monkeypatch.setenv("FRAMEPORT_LANGPACK", "DE")
+    m = api.ask("ovr_LanguagePack_GetCurrent")
+    assert not api.is_error(m)
+    d = api.details(api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m))
+    assert d["type"] == b"language_pack" and d["status"] == b"installed"
+    assert d["path"] == str(packs / "de.lang").encode()
+    assert (d["tag"], d["en"], d["native"]) == (b"de", b"German", b"Deutsch")
+    assert d["id"] >> 48 == 0x4650
+    api.free(m)
+    # exactly one pack and nothing chosen: that one
+    monkeypatch.delenv("FRAMEPORT_LANGPACK")
+    only = tmp_path / "only"
+    only.mkdir()
+    (only / "de.lang").write_bytes(b"x")
+    monkeypatch.setenv("FRAMEPORT_LANGPACK_DIRS", str(only))
+    m = api.ask("ovr_LanguagePack_GetCurrent")
+    assert api.details(api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m))["tag"] == b"de"
+    api.free(m)
+
+
+def test_set_current_then_status_then_get_current(api, packs):
+    m = api.ask("ovr_LanguagePack_SetCurrent", b"de-DE")  # the base language matches
+    assert api.msg_type(m) == SETCURRENT and not api.is_error(m)
+    res = api.f("ovr_Message_GetAssetFileDownloadResult", VOIDP, VOIDP)(m)
+    asset = api.f("ovr_AssetFileDownloadResult_GetAssetId", C.c_uint64, VOIDP)(res)
+    path = api.f("ovr_AssetFileDownloadResult_GetFilepath", C.c_char_p, VOIDP)(res)
+    assert asset and path == str(packs / "de.lang").encode()
+    api.free(m)
+
+    m = api.ask("ovr_AssetFile_StatusById", asset)  # the confirm step of the documented flow
+    assert api.msg_type(m) == STATUSBYID and not api.is_error(m)
+    d = api.details(api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m))
+    assert (d["status"], d["path"], d["id"]) == (b"installed", path, asset)
+    api.free(m)
+
+    m = api.ask("ovr_LanguagePack_GetCurrent")  # the choice sticks
+    assert api.details(api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m))["tag"] == b"de"
+    api.free(m)
+
+    m = api.ask("ovr_AssetFile_StatusById", asset + 1)  # ours by prefix, but unknown
+    assert api.is_error(m)
+    api.free(m)
+
+
+def test_set_current_unknown_pack_is_an_error(api, packs):
+    for tag in (b"xx", b""):
+        m = api.ask("ovr_LanguagePack_SetCurrent", tag)
+        assert api.is_error(m) and not api.f("ovr_Message_GetAssetFileDownloadResult", VOIDP, VOIDP)(m)
+        api.free(m)
+
+
+def test_asset_list_adds_our_packs_to_the_loaders_list(api, packs):
+    req = api.f("ovr_AssetFile_GetList", C.c_uint64)()
+    assert req == 100  # the loader's own request id
+    m = api.pop()
+    assert api.msg_type(m) == GETLIST and api.req_id(m) == req and not api.is_error(m)
+    arr = api.f("ovr_Message_GetAssetDetailsArray", VOIDP, VOIDP)(m)
+    size = api.f("ovr_AssetDetailsArray_GetSize", C.c_size_t, VOIDP)(arr)
+    items = [api.details(api.f("ovr_AssetDetailsArray_GetElement", VOIDP, VOIDP, C.c_size_t)(arr, i))
+             for i in range(size)]
+    assert size == 4
+    ours = [i for i in items if i["type"] == b"language_pack"]
+    assert {i["tag"] for i in ours} == {b"de", b"en-us", b"fr"} and {i["status"] for i in ours} == {b"installed"}
+    store = [i for i in items if i["type"] == b"store"]  # the loader's own entry, served by the loader's accessors
+    assert store == [{"id": 7, "type": b"store", "status": b"available", "path": b"/store/a"}]
+    assert api.f("ovr_AssetDetailsArray_GetElement", VOIDP, VOIDP, C.c_size_t)(arr, 4) is None
+    before = api.loader.fake_freed()
+    api.free(m)  # frees the loader's message behind ours too
+    assert api.loader.fake_freed() == before + 1
+
+
+def _our_metadata(api):
+    api.f("ovr_AssetFile_GetList", C.c_uint64)()
+    m = api.pop()
+    arr = api.f("ovr_Message_GetAssetDetailsArray", VOIDP, VOIDP)(m)
+    get = api.f("ovr_AssetDetailsArray_GetElement", VOIDP, VOIDP, C.c_size_t)
+    out = {api.f("ovr_AssetDetails_GetMetadata", C.c_char_p, VOIDP)(get(arr, i))
+           for i in range(api.f("ovr_AssetDetailsArray_GetSize", C.c_size_t, VOIDP)(arr))
+           if api.f("ovr_AssetDetails_GetAssetType", C.c_char_p, VOIDP)(get(arr, i)) == b"language_pack"}
+    api.free(m)
+    return out
+
+
+def test_metadata_is_empty_without_the_games_version(api, packs, monkeypatch):
+    monkeypatch.delenv("FRAMEPORT_LANGPACK_META", raising=False)
+    assert _our_metadata(api) == {b""}
+
+
+def test_metadata_from_the_environment(api, packs, monkeypatch):
+    monkeypatch.setenv("FRAMEPORT_LANGPACK_META", "2.0.1.77.Quest")
+    assert _our_metadata(api) == {b"2.0.1.77.Quest"}
+
+
+def test_patch_writes_the_games_version_as_the_metadata(built, tmp_path, monkeypatch):
+    monkeypatch.delenv("FRAMEPORT_LANGPACK_META", raising=False)
+    lib = patch_mod.with_metadata(built["lib"].read_bytes(), "1.0.40.356975.Quest")
+    assert len(lib) == built["lib"].stat().st_size and b"1.0.40.356975.Quest" in lib
+    assert patch_mod.with_metadata(lib, "") == lib and patch_mod.with_metadata(b"no marker", "1") == b"no marker"
+    assert patch_mod.with_metadata(lib, "x" * 200) == lib  # too long for the slot: left as it was
+    d = tmp_path / "meta"
+    d.mkdir()
+    (d / "libovrplatformloader.so").write_bytes(built["patched"])
+    (d / "libfp_langpack.so").write_bytes(lib)
+    root = tmp_path / "obb"
+    root.mkdir()
+    (root / "de.lang").write_bytes(b"1")
+    monkeypatch.setenv("FRAMEPORT_LANGPACK_DIRS", str(root))
+    loader, lp = C.CDLL(str(d / "libovrplatformloader.so")), C.CDLL(str(d / "libfp_langpack.so"))
+    try:
+        assert _our_metadata(Api(lp, loader)) == {b"1.0.40.356975.Quest"}
+    finally:
+        _dlclose(lp)
+        _dlclose(loader)
+
+
+def _tags(api):
+    api.f("ovr_AssetFile_GetList", C.c_uint64)()
+    m = api.pop()
+    arr = api.f("ovr_Message_GetAssetDetailsArray", VOIDP, VOIDP)(m)
+    get = api.f("ovr_AssetDetailsArray_GetElement", VOIDP, VOIDP, C.c_size_t)
+    size = api.f("ovr_AssetDetailsArray_GetSize", C.c_size_t, VOIDP)(arr)
+    out = {api.details(get(arr, i)).get("tag") for i in range(size)}
+    api.free(m)
+    out.discard(None)
+    return out
+
+
+def test_packs_can_be_left_out_by_environment_or_file(api, packs, monkeypatch):
+    assert _tags(api) == {b"de", b"en-us", b"fr"}
+    monkeypatch.setenv("FRAMEPORT_LANGPACK_SKIP", "EN-US, x")
+    assert _tags(api) == {b"de", b"fr"}
+    monkeypatch.delenv("FRAMEPORT_LANGPACK_SKIP")
+    (packs / "fp_langpack_skip").write_text("de\nfr\n")
+    assert _tags(api) == {b"en-us"}
+    (packs / "fp_langpack_skip").unlink()
+    assert _tags(api) == {b"de", b"en-us", b"fr"}  # nothing remembered between lists
+
+
+def test_everything_else_reaches_the_loader_unchanged(api, packs):
+    # a status request for the loader's own asset: its message comes back as it is
+    req = api.f("ovr_AssetFile_StatusById", C.c_uint64, C.c_uint64)(7)
+    assert req == 100
+    m = api.pop()
+    assert api.msg_type(m) == STATUSBYID and not api.is_error(m)
+    d = api.details(api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m))
+    assert d["path"] == b"/store/a"
+    api.free(m)
+    assert api.loader.fake_freed() == 1
+    assert api.pop() is None
+
+
+def test_asset_list_without_packs_is_the_loaders_message(api, tmp_path, monkeypatch):
+    monkeypatch.setenv("FRAMEPORT_LANGPACK_DIRS", str(tmp_path / "nothing-here"))
+    api.f("ovr_AssetFile_GetList", C.c_uint64)()
+    m = api.pop()
+    arr = api.f("ovr_Message_GetAssetDetailsArray", VOIDP, VOIDP)(m)
+    assert api.f("ovr_AssetDetailsArray_GetSize", C.c_size_t, VOIDP)(arr) == 1
+    api.free(m)
+    assert api.loader.fake_freed() == 1
+
+
+def test_asset_list_the_loader_never_answers_gets_our_packs_after_the_timeout(api_fast, packs, monkeypatch):
+    monkeypatch.setenv("FAKE_SILENT_LIST", "1")
+    req = api_fast.f("ovr_AssetFile_GetList", C.c_uint64)()
+    assert req == 100
+    assert api_fast.pop() is None  # not overdue yet
+    time.sleep(0.2)
+    m = api_fast.pop()
+    assert m and api_fast.msg_type(m) == GETLIST and api_fast.req_id(m) == req and not api_fast.is_error(m)
+    arr = api_fast.f("ovr_Message_GetAssetDetailsArray", VOIDP, VOIDP)(m)
+    size = api_fast.f("ovr_AssetDetailsArray_GetSize", C.c_size_t, VOIDP)(arr)
+    tags = {api_fast.details(api_fast.f("ovr_AssetDetailsArray_GetElement", VOIDP, VOIDP, C.c_size_t)(arr, i))["tag"]
+            for i in range(size)}
+    assert tags == {b"de", b"en-us", b"fr"}
+    api_fast.free(m)
+    assert api_fast.pop() is None  # answered once
+    before = api_fast.loader.fake_freed()
+    # the dispatcher's answer arrives after all: dropped, not a second answer
+    api_fast.loader.fake_late_list(C.c_uint64(req))
+    assert api_fast.pop() is None
+    assert api_fast.loader.fake_freed() == before + 1
+
+
+def test_find_tags_in_the_data_folder(tmp_path):
+    root = tmp_path / "game"
+    (root / "a" / "b" / "c" / "d").mkdir(parents=True)
+    for rel in ("de.lang", "a/EN-us.LANG", "a/b/c/fr.lang", "a/b/c/d/too-deep.lang", "bad name.lang", "x.txt"):
+        (root / rel).write_bytes(b"1")
+    assert langpacks.find_tags(root) == ["de", "EN-us", "fr"]
+    assert langpacks.find_tags(None) == [] and langpacks.find_tags(tmp_path / "missing") == []
+
+
+def _apk(tmp_path, built):
+    p = tmp_path / "in.apk"
+    with zipfile.ZipFile(p, "w") as z:
+        z.writestr("AndroidManifest.xml", b"manifest")
+        z.writestr("classes.dex", b"dex\n035\0")
+        z.writestr("lib/arm64-v8a/libovrplatformloader.so", built["original"])
+    return p
+
+
+def test_patch_links_the_library_and_hides_the_loaders_functions(built, tmp_path, monkeypatch):
+    monkeypatch.setattr(patch_mod, "artifact", lambda abi, name: b"\x7fELF-langpack")
+    patch = base.get("frame.langpacks")
+    a = _analysis(libs=["libovrplatformloader.so"], extra={"size": 1, "lang_packs": ["de", "en-us"]})
+    assert patch.applies(a)  # the game's data has language packs
+    assert patch.detect(a) is None  # opt-in: never part of a suggested recipe
+    assert not patch.applies(_analysis(libs=["libovrplatformloader.so"]))  # no language packs: nothing to serve
+    assert not patch.applies(_analysis(libs=[], extra={"size": 1, "lang_packs": ["de"]}))  # no platform loader
+    with ApkWorkspace(_apk(tmp_path, built)) as ws:
+        ctx = base.ApkContext(ws, a, {}, Reporter(), {})
+        assert patch.apply(ctx)
+        loader = ws.read_lib("libovrplatformloader.so")
+        assert elf.needed(loader)[0] == "libfp_langpack.so"
+        assert "ovr_PopMessage" in elf.dyn_symbols(loader, True)  # still defined, only no longer global
+        assert ws.read_lib("libfp_langpack.so") == b"\x7fELF-langpack"
+        assert all(ok for _, ok, _ in patch.validate(ctx))
+        assert not patch.apply(base.ApkContext(ws, a, {}, Reporter(), {}))  # applied once is enough
+        assert any("language packs" in n for n in ctx.notes)
+
+
+def test_games_already_in_the_library_get_their_language_packs_after_an_app_update(tmp_path):
+    """lang_packs is read from the data folder (no APK analysis): filled in once for existing entries."""
+    from frameport.core import library
+
+    data = tmp_path / "data"
+    (data / "obb").mkdir(parents=True)
+    (data / "obb" / "de.lang").write_bytes(b"x")
+    g = {"data_dir": str(data), "analysis": {"package": "com.x.y", "extra": {}}}
+    assert library._refresh_data_fields(g, g["analysis"])
+    assert g["analysis"]["extra"]["lang_packs"] == ["de"]
+    assert not library._refresh_data_fields(g, g["analysis"])  # once
@@ -370,7 +370,7 @@ def test_game_settings_dialog_shows_relevant_settings_and_saves_only_changes():
    from frameport.patches.settings import SETTINGS, UI
    from frameport.ui.views import adapter_dialog as ad

-    assert set(UI) == {k for k, *_ in SETTINGS}  # every setting has a plain label/control
+    assert set(UI) == {k for k, kind, *_ in SETTINGS if kind != "str"}  # every number/switch has a label/control
    vulkan = _analysis()
    gles = _analysis(graphics="GLES (declared in manifest)")
    assert ad.relevant(vulkan, "flip_emul", 1) and not ad.relevant(gles, "flip_emul", 1)  # Vulkan-only
@@ -386,6 +386,11 @@ def test_game_settings_dialog_shows_relevant_settings_and_saves_only_changes():
    adapter = {k: v for k, v in saved["patches"].items() if k.startswith("adapter.")}
    assert adapter == {"adapter.refresh_rate": {"value": 90.0}, "adapter.aim_pitch": {"value": -5.0}}  # no defaults
    assert "frame.launcher" in saved["patches"]  # other patches untouched
+    r = library.recipe_from_dict(saved)
+    r.patches["adapter.vk_shader_fix"] = {"value": "8:" + "0" * 64 + ":4:1"}
+    library.upsert_game("com.x", recipe=asdict(r))
+    ad.save_to_recipe("com.x", ad.recipe_values(library.game("com.x")))
+    assert library.game("com.x")["recipe"]["patches"]["adapter.vk_shader_fix"]["value"].startswith("8:")  # kept
    assert saved["source"] == "user" and saved["reasons"]["adapter.aim_pitch"] == "Set by you."


@@ -0,0 +1,20 @@
+from frameport.ui.restart import crashed_game
+
+LAUNCH = {"package": "com.x", "title": "X", "time": 1000.0}
+
+
+def boot(**kw):
+    return {"boot_id": "b2", "boot_time": 2000, "prev_clean": False, "last_launch": LAUNCH, **kw}
+
+
+def test_unclean_restart_soon_after_a_launch_blames_the_game():
+    assert crashed_game(boot(), "b1") == LAUNCH
+
+
+def test_no_blame_for_clean_shutdowns_first_sight_old_launches_or_same_boot():
+    assert crashed_game(boot(prev_clean=True), "b1") is None  # powered off / battery shutdown
+    assert crashed_game(boot(prev_clean=None), "b1") is None  # journal unknown
+    assert crashed_game(boot(), None) is None  # never seen this Frame boot before: nothing to compare
+    assert crashed_game(boot(), "b2") is None  # same boot
+    assert crashed_game(boot(boot_time=1000 + 4 * 3600), "b1") is None  # the game ran hours before
+    assert crashed_game(boot(last_launch=None), "b1") is None
@@ -60,3 +60,18 @@ def test_crash_logcat_signatures():
             "(xrCreateSwapchain+424)\n")
    r = triage(log.replace("11 (SIGSEGV)", "6 (SIGABRT)"), "EXITED", "com.example.game", crash=abort)
    assert [(f.id, f.suggest) for f in r.findings] == [("swapchain-size-abort", ["frame.swapchain_limit"])]
+
+
+def test_ovrplugin_extension_probe_is_not_a_scene_game():
+    probe = LOG_OK + "09-28 17:39:02.200  1147  1174 I OVRPlugin: Unavailable OpenXR extension: XR_FB_scene\n"
+    assert "scene-missing" not in {f.id for f in triage(probe, "RUNNING", "com.example.game").findings}
+    used = LOG_OK + "09-28 17:39:04.000  1147  1174 E Unity   : xrQuerySpacesFB failed: -12\n"
+    assert "scene-missing" in {f.id for f in triage(used, "RUNNING", "com.example.game").findings}
+
+
+def test_rejected_controller_profile_is_information_only():
+    log = LOG_OK + ("09-28 17:39:02.300  1147  1174 E OVRPlugin: OpenXR error: XR_ERROR_PATH_UNSUPPORTED, cmd "
+                    "xrSuggestInteractionProfileBindings(m_xrInstance, &plusSuggestedBindings)\n")
+    f = {x.id: x for x in triage(log, "RUNNING", "com.example.game").findings}
+    assert f["controller-profile-rejected"].severity == "info"
+    assert triage(log, "RUNNING", "com.example.game").verdict == "pass"
Author	SHA1	Message	Date
spoopyghosty0	4e00c88949	FramePort 0.7.1	2026-10-04 19:24:49 -04:00
spoopyghosty0	1b62d643f3	Notes: language packs verified with Deadpool VR (English dialogue with the patch on)	2026-10-04 19:23:33 -04:00
spoopyghosty0	6bd4eb523f	One job queue per process (Flet builds a new app per window session: an old session's job ran unseen and the same game was built twice at once in one work folder, both failed) and one build per game at a time	2026-10-04 19:23:32 -04:00
spoopyghosty0	d22123c657	Language packs: lint (line length, imports)	2026-10-04 19:23:32 -04:00
spoopyghosty0	0137cd993b	Language packs: ship libfp_langpack.so (built here), drop the dispatcher's late asset-list answer once we answered after the timeout (one answer per request), per-thread skip list, and games already in a library get their packs listed after an app update	2026-10-04 19:23:32 -04:00
yzfsoldier	7b8e7c2c5d	Opt-in frame.langpacks: serve <tag>.lang language packs from the game's files (PR #20 ) 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.	2026-10-04 19:23:29 -04:00
spoopyghosty0	990331e5b6	WiiCompiled VR recipe: how to add a game (upload the .wcgame to its Import folder with the Files tab)	2026-10-04 18:32:29 -04:00
spoopyghosty0	56b370f582	WiiCompiled VR recipe: works with issues (no document picker in Lepton: manual .wcgame import; right eye jitters in races, inside the game's own OpenXR path)	2026-10-04 18:29:53 -04:00
spoopyghosty0	ac628cd284	FrameBridge: per-eye diagnostics (eye_debug: submitted vs fresh eye poses, eye-to-eye relation, release timing; also logged to framebridge.log because some games end Lepton's logcat early) and release_wait (wait for the game's GPU work before an image is released; 2 = A/B after 60 s)	2026-10-04 18:24:15 -04:00
spoopyghosty0	c12b2f6992	Steam art: games whose only art is the library's generated cover/banner get the placeholder set again (they got no Steam art at all, e.g. WiiCompiled)	2026-10-04 18:19:03 -04:00
spoopyghosty0	a110e8573f	QuestCraft recipe: works with issues (Java runtime missing on first start; Minecraft's graphics then fail with OpenGL error 1282)	2026-10-04 18:11:37 -04:00
spoopyghosty0	4fdeeaf829	FrameBridge emulates Android video panels (XR_KHR_android_surface_swapchain: I Am Monkey's intro, surface_emul); the launcher repairs save folders without group write (SUPERHOT quit at start, agent v41); SUPERHOT (Quest) and I Am Monkey recipes; Lucky's Tale's out-of-memory diagnosis	2026-10-04 18:07:22 -04:00
spoopyghosty0	dbabb37343	FramePort 0.7.0	2026-10-04 17:08:34 -04:00
spoopyghosty0	7afee4bf59	FramePort on the Frame: Play in Desktop Mode says the game will be in the Steam library back in Gaming Mode (was an error: the waiting library update read as 'no answer'); a second request for a game whose library update already waits doesn't start another (agent v39)	2026-10-04 16:53:47 -04:00
spoopyghosty0	7367a35176	Library rescans find new downloads: a folder with a stray APK next to game folders counted as one game (the scan stopped there), and games more than two folders down (a download manager's <library>/data/downloads/<game>/) weren't searched; now 5 levels, collections vs game folders told apart, PC program folders and code checkouts skipped	2026-10-04 16:50:33 -04:00
spoopyghosty0	9948f946c5	Remove from library offers the same 'also delete this game's files on this PC' option (off by default)	2026-10-04 16:39:35 -04:00
spoopyghosty0	3870500972	Uninstall asks whether to also delete the game's files on this PC (off by default): the APK and data folder (or a PC VR game's folder) and FramePort's converted copies, listed with their size; never signing keys or files another library entry uses; the game then leaves the library	2026-10-04 16:36:17 -04:00
spoopyghosty0	a7b02c00ee	On the Frame itself the app keeps its data in ~/.local/share/frameport-app: ~/.local/share/frameport is the agent's folder, which its purge removes (with the game signing keys)	2026-10-04 16:31:54 -04:00
spoopyghosty0	09c7bb6ea7	SDL / LÖVE apps start on the Frame (GitHub #24 ): Lepton's Android has no clipboard service and SDLClipboardHandler's constructor crashed on it; frame.sdl_clipboard skips that one call with an in-place classes.dex edit (apk/dex.py), verified with LÖVE for Android 11.5 (crash without, runs with). Android apps without VR keep every suggested non-VR patch	2026-10-04 16:29:45 -04:00
spoopyghosty0	3761dfd62d	FramePort on the Frame itself: on SteamOS ARM64 it remembers 'This Frame' (127.0.0.1) and authorizes its own key (no pairing; Developer Mode for sshd, explained if off). Steam library changes wait while Desktop Mode is open (a Steam restart would end it, and FramePort with it; agent v38). Recipe: Beat Saber co-existence build (#29 , without the repack's branding)	2026-10-04 16:17:24 -04:00
spoopyghosty0	f86d9021f9	Steam library fixes (GitHub #4 , #21 , #27 ): shortcuts go to every Steam account, the agent waits for Steam's helpers before writing and checks the entries survived Steam's restart (writes once more, else reports it; agent v38); Play's add-to-library repair no longer crashes (TypeError since 0.6.3). Uploads resume after a transient OSError (Windows Errno 22). Recipes: Riven (#26 ), SUPERHOT VR Rift version (#28 )	2026-10-04 16:03:38 -04:00
spoopyghosty0	83e901a682	Accounting+: works with issues (VR starts with frame.unity_oculus_check + the frame-wait shim; stuck at 'press any button' although its OVRInput gets clean input). The shim's input wrappers (logging, input focus, stuck-button release) stay behind INPUT_PROBE (off); per-hand interaction profiles and input counters in layer_debug	2026-10-04 15:50:00 -04:00
spoopyghosty0	246e5fc5ee	Accounting+ runs: with the frame-loop shim Unity 2017's built-in Oculus support submits frames (~71 fps in the launch test, was a frozen dashboard); frame.unity_oculus_check is suggested again	2026-10-04 15:03:49 -04:00
spoopyghosty0	17403779cb	Accounting+ / Unity 2017 built-in Oculus: native/ovrpshim (libfp_ovrp.so) adds the frame wait Unity's legacy loop never makes (fpov_Update2 = ovrp_WaitToBeginFrame once per frame, then ovrp_Update2); frame.unity_oculus_check renames the lookup in libunity.so and links the shim into libOVRPlugin.so. Still opt-in until a launch test shows frames	2026-10-04 14:58:01 -04:00
spoopyghosty0	0e03e061a4	Recipes FramePort derived (not the user's own) are derived again once after every app update, so new automatic fixes reach games already in a library (e.g. the Vulkan shim for own-engine games); a changed recipe shows Update on Frame	2026-10-04 14:52:26 -04:00
spoopyghosty0	d8cf19fb20	Owner's verdicts: Blade & Sorcery works, BattleGlide works, Myst and I Am Cat work with issues, Roblox unsupported; Myst keeps application space warp (turning it off didn't help). PLAYBOOK: symptom rows and debugging techniques from these sessions (headset-only failures, linker log via LEPTON_GFXRECON_FP_PROPS, Unity's own tombstone, wear-sensor focus losses in vrserver.txt, inlined getters, catalog YAML)	2026-10-04 14:43:49 -04:00
spoopyghosty0	7cd9a38eaf	Headset round 3: Blade & Sorcery's freezes are the headset's wear sensor flickering off while worn (SteamVR 'HMD off' 0.5-2 s), which only this game pauses on: new adapter setting focus_hold_ms (default 1000; 2500 in its recipe). Installs no longer restart Steam when the game's shortcut is unchanged (a reinstall ended a game being played), and wait while a game runs when Steam has to restart (agent v37). frame.vk_sanitize also covers own-engine libraries that load libvulkan.so by name (Roblox's crash is on Fossilize's recording thread). Myst: app space warp off (object glitches). frame.unity_oculus_check is opt-in (Unity 2017's frame loop never waits: dashboard freeze). focus_hold: 1 s focused / 1 s dips by default	2026-10-04 14:15:50 -04:00
spoopyghosty0	4f3593192f	Recipes from the second headset round: BattleGlide works (focus_hold), Myst works with minor glitches (sync_guard confirmed), Blade & Sorcery still jumps/freezes now and then. GAMES.md is generated from the repo's recipes only (a local user catalog hid Myst), and a test parses every catalog file (a broken one was skipped silently)	2026-10-04 12:03:53 -04:00
spoopyghosty0	974426d1d0	Headset round (2026-10-04): frame.unity_oculus_check (Unity 2017-2018 built-in Oculus starts VR only with Meta's com.oculus.systemactivities; Accounting+ now creates its OpenXR instance instead of running as a hidden 2D app); adapter sync_guard (the Frame runtime's xrSyncActions race right after focus, Myst); recipes: Myst, BattleGlide and Blade & Sorcery: Nomad (focus_hold for the Frame's brief focus dips) as works with issues, Roblox and BONELAB unsupported with what was found; triage + PLAYBOOK rows	2026-10-04 11:45:52 -04:00
spoopyghosty0	b7a0e0cb5b	Notes: device results for the requested games (BONELAB, Roblox, Accounting+ findings)	2026-10-04 11:14:57 -04:00
spoopyghosty0	38edc26092	Cpp2IL: a build it can't read (e.g. Unity 2017) is cached as such, so each Unity patch doesn't run it again, and the error names Cpp2IL's exception instead of a stack trace; the controller-profile triage line no longer suggests profile_remap (it's on by default)	2026-10-04 11:14:43 -04:00
spoopyghosty0	e96e25bade	Controller profiles (0.7.0 D): the adapter suggests bindings for Meta's newer Touch profiles (Touch Plus/Pro), which the Frame's runtime rejects, again as oculus/touch_controller (setting profile_remap, default on; triage info signature). unity_no_msaa: games with several MSAA quality levels failed ('bytes not found in place'), and pre-2019 Unity names the field blendWeights	2026-10-04 10:27:53 -04:00
spoopyghosty0	67c991ca4f	Fixes from user reports, round 2: VR4 campaign hang (one shader reads an uninitialized loop counter; the Vulkan shim's new vk_shader_fix setting inserts the zeroing stores, matched by size + SHA-256, from #10 's capture); I Am Cat multipass (the getter is inlined: the field read in OculusLoader.Initialize is rewritten, verified on a Frame); builds remember their recipe (recipe_fp, Patch.revision) so changed recipes show Update on Frame; a Frame that got a new address is found again by its SSH host key; packaged apps show library artwork (#16 ); diagnostics include this boot's kernel log; the Game settings dialog keeps text settings; recipes from #13 , #14 , #15 , #17	2026-10-04 10:21:30 -04:00
spoopyghosty0	d2017194f3	Catalog recipes reach games already in the library: recipes remember the catalog entry they came from (catalog_rev) and are derived again when it changes (never the user's own edits); a maintained entry updated after the user's shared copy wins. Recipes: I Am Cat (issues: frame.unity_multipass), Lucky's Tale (issues: frame.unity_runtime_msaa_off), VR4 works with the no-ForceQuit build	2026-10-04 01:31:16 -04:00
spoopyghosty0	7a11706b3a	FramePort 0.6.3: Unity patches frame.unity_runtime_msaa_off (OVRManager turns 4x MSAA on at runtime: Lucky's Tale restarted the headset, #9 ) and frame.unity_multipass (Oculus XR Plugin multiview: I Am Cat's grey right eye, #8 ), sharing one Cpp2IL run per build; triage signature for runtime MSAA; VR4 installs the no-ForceQuit build (#10 )	2026-10-04 01:22:47 -04:00
spoopyghosty0	76d4390b19	Steam library entries (issues #4 , #5 : 'Game configuration unavailable', no shortcuts): agent v35 adds shortcuts for the signed-in Steam account (loginusers.vdf), else every account, instead of failing when the Frame has several; Play launches the shortcut's own id and says when a game isn't in the library, and the app then adds it and starts the game; an install whose library entry isn't confirmed says so. Triage: OVRPlugin's routine 'Unavailable OpenXR extension: XR_FB_scene' no longer suggests scene emulation	2026-10-04 01:10:52 -04:00
spoopyghosty0	2022d9986a	Catalog: VR4 keeps its package title (com.Armature.VR4; the store name stays in source_hint for matching dump folders)	2026-10-04 00:54:16 -04:00
spoopyghosty0	9ff7edf93b	Catalog: working configs from issues #1 (Resident Evil 4, package com.Armature.VR4: works with issues), #3 (Cook-Out), #6 (Beat Saber), #11 (Job Simulator), #12 (Dinosaur Island); games list regenerated. catalog_from_issue: 'device' is a checked list field, and FramePort patch ids must exist	2026-10-04 00:52:39 -04:00
spoopyghosty0	a5722b50a0	Windows games without VR (Reddit request): a game folder added with 'Add one game folder…' that has no VR runtime becomes a flat Windows game: only the Proton patches, a launcher without SteamGameId (Proton sets up no VR), a non-VR Steam shortcut (OpenVR=0, tag 'Windows game on Frame'), labels 'Windows game (Proton)'; no 'Play on this PC'	2026-10-03 19:38:23 -04:00
spoopyghosty0	0a13ca72a2	Frame crash detection: agent v34 reports the boot id, whether the previous boot shut down cleanly (journal) and the FramePort game launched last before it; the app compares with the last boot it saw and, after an unclean restart soon after a game started, says so with Report a problem. Diagnostics include the previous boot's errors and kernel warnings (GPU resets, OOM)	2026-10-03 19:33:37 -04:00
spoopyghosty0	c53d754007	FramePort 0.6.2	2026-10-03 19:29:24 -04:00
spoopyghosty0	a1662da17d	Connecting a new Frame (Reddit feedback): a PC without SSH keys made paramiko end the key attempt with 'No authentication methods available' (SSHException), which stopped the loop before the password was tried and showed that raw message; now it's a failed login like any other, and the final error (FrameNotPaired) says to run the first-time setup or that the password was refused. Wizard: first-time setup is step 1, a 'not set up yet' callout with the setup button after such a failure. Failed installs/tests offer Report a problem. README/GAMES/CONTRIBUTING: share-a-config and report-a-problem links	2026-10-03 19:02:31 -04:00
spoopyghosty0	0141bad259	Desktop on the Steam Frame: SteamVR dashboard → Launch a program → Desktop, then System → Konsole (the Steam Deck's Power → Switch to Desktop doesn't apply) — README, INSTALL, setup wizard, CLI, bootstrap	2026-10-03 18:12:12 -04:00