FramePort 1.4.0

Tests: the refresh-rate request hook is always installed too (#336 )
Site: release and contributor data refreshed (1.4.0)
2026-10-25 20:02:00 +01:00 · 2026-10-25 13:48:50 -04:00 · 2026-10-25 13:44:31 -04:00 · 2026-10-25 13:41:15 -04:00 · 2026-10-25 13:40:39 -04:00 · 2026-10-25 13:39:25 -04:00
387 changed files with 36005 additions and 2252 deletions
@@ -59,8 +59,22 @@ Detailed device findings per game/issue: docs/DEVICE_NOTES.md (read before debug
    agent ends at EOF); sources and costs in docs/FRAME_RUNTIME.md "Monitoring sources"; game card (fps from
    FrameBridge pacing; End game = Steam's Exit game, then cmd_stop), tiles with `C.Sparkline` (Flet canvas, no charts
    extension), details, a pooled process table (Game / Steam & SteamVR / All; right-click: end / force kill / end
-    game; MON_CRITICAL needs force, MON_NEVER is refused)); settings; welcome; activity panel). Files, Screenshots and the Library share right-click menus
-    (one `ft.ContextMenu` per view, filled on right-click; on one of several selected items they act on the whole
+    game; MON_CRITICAL needs force, MON_NEVER is refused)); room (`views/room.py`, persistent, "experimental" pill:
+    scan with progress + Cancel = agent v109 `room_capture_stop`, play area, delete; cache `ui/room_state.py` shared
+    with the Frame page's short card, mesh cached in `<data>/rooms-cache/<frame>/`; in-window 3D `ui/room3d.py`
+    RoomCanvas over `mr/view3d.py` (pure-Python projection, mesh reduced to ≤4k/≤1.5k edges at rest/moving, ≤18 fps
+    worker; each redraw sends NEW shape controls: changing a Points list made Flet diff it item by item, 0.3-1 s);
+    "Open full 3D view" = `mr/room_viewer.py` token server on 127.0.0.1 + hand-written WebGL `mr/viewer_page.py`,
+    stopped on disconnect/close; Test Quest MR tip = `mr.TESTER_*`; editing cards `views/room_edit.py` (agent v109):
+    Clean-up = fp_roomscan's refinement settings, `install/rooms.REFINE_DEFAULTS` = the owner's defaults + slider
+    metadata (agent `ROOM_REFINE_DEFAULTS` must match, a test checks), saved non-defaults in the Frame's
+    `rooms/refine.json`, used by every build; Apply = job → agent `room_refine` (`--refine-only` on a copy of the room
+    folder from `room-raw.txt`/`room-mesh-raw.bin`, scan.json → status `report`/`labels`/`suggestions`); Labels =
+    the label rules' decisions + Add as door / Add as closet; Furniture & screens = box editor (click a box in the
+    canvas: `view3d.pick`) + doors/windows on a wall (`mr.room.plane_on_wall`), Save = `rooms.put_room` → `room_put
+    edited` (keeps raw files, `edits.txt` survives a new clean-up; "Back to the scan's boxes" = keep_edits false); no
+    eraser in the GUI (`rooms.refine(erase=)` only)); settings; welcome; activity panel). Files, Screenshots and the Library share right-click menus
+    (`app.popmenu`, filled on right-click; on one of several selected items they act on the whole
    selection, `C.menu_targets`) and click-and-drag multi-select (`C.DragSelect`: pan start/end on the area + item
    hover events, which Flutter also sends with the button held; Flet can't report item positions, so no rubber band).
    Selection bars sit below the list: above it, their appearing shifted the items mid-drag. Async handlers (they
@@ -130,10 +144,19 @@ Detailed device findings per game/issue: docs/DEVICE_NOTES.md (read before debug
    in Containers with `ft.ScrollKey`), the header stays; `app.settings_view.show_section(key)` (ui_smoke
    `settings-index`).
    Help hints: wording for non-obvious terms lives in `ui/help.py` (`HELP`); show it with `C.help_icon(key)` or the
-    `help=` argument of `section`/`kv` (`C.Check` help key), tooltips via `C.tip()` (wraps). Game actions for the Library
-    right-click menu (one `ft.ContextMenu` around the grid, filled on right-click; short: `menus.quick_menu`, key actions
-    + "More actions…" = the game page with its full "…" menu opened from code, `app.open_game_menu`) and the game
-    page's "…" menu (`menus.menu_sections` quick=False, sectioned) come from `app.game_actions()`. Picking art (`sources.apply_choice`) downloads into a staging dir and keeps the old
+    `help=` argument of `section`/`kv` (`C.Check` help key), tooltips via `C.tip()` (wraps). Context menus
+    (Library, Files, Screenshots, Monitor) and the game page's "…" are FramePort's own (GitHub #414):
+    `ui/popmenu.PopMenu` = `app.popmenu.show(entries, at=(x, y) | below=box)`, drawn in page.overlay (outside-click
+    barrier + panels; hover submenus with open/close intent delays, ↑ ↓ → ← Enter Esc via `app._on_key` first, closes
+    on outside click/Esc/choice/`app.go`; panels size to the estimated label width between MIN_W and MAX_W, longer
+    labels wrap, flip/clamp into the window, submenus on the side with room; a solid grey left edge (owner: no portal gradient) and a solid soft-accent highlight; fade off with
+    Reduce motion; hovering only repaints rows). Flet's stock ContextMenu/PopupMenu can't nest and cap at 280 px, so
+    they're only used for button menus (`C.menu_button`, width scaled; `C.menu_label` wraps). Game menus come from
+    `app.game_actions()` = `menus.menu_sections`: right-click = Play, Install/Update, Game settings | Open game page,
+    Select | Update ▸ On the Frame ▸ Saves ▸ Name and artwork ▸ Recipe ▸ Troubleshoot ▸ | Uninstall…, Remove from
+    library… (`menus.group`: a one-item group stays inline); the page's "…" (quick=False) is the same without what
+    its hero has; on one of several selected games `menus.selection_menu` (`library.menu_actions`); the recipe card's
+    buttons = `game_actions(recipe=True)`. Picking art (`sources.apply_choice`) downloads into a staging dir and keeps the old
    art if nothing came back; "Update Steam art on Frame" re-sends the art set to the game's anchor (agent ≥ 12).
    Patch descriptions/reasons describe the general case, naming games only as "e.g. …".
  - Installs: queued/cancelled/failed ones are remembered (library setting `ui.installs`) → Library "Resume" bar;
@@ -218,6 +241,11 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
    `FRAMEPORT_DESKTOP=1` skips the Steam-parent watchdog and Steam's display; ensure_host_fixes refreshes entries
    (older installs, stale ones removed), uninstall/purge remove them. Per app: library entry field `desktop_entry`
    (default on; patches don't apply to Linux apps) → game page switch → agent `desktop_entry`. Untested on device.
+  - App bundles (discussion #482, `sources/bundles.py`, docs/DEVICE_NOTES.md#app-bundles-xapk--apks--apkm--apkx-discussion-482):
+    .xapk/.apks/.apkm/.apkx files and folders of split APKs are unpacked + merged into ONE APK (Lepton: one APK per app;
+    OVRPort: one APK) in `<data>/bundles/<pkg>/<key>/` (lib/assets splits in Python, resource/feature splits via
+    APKEditor `tools/apkeditor.py`); arm64-v8a split only; library field `bundle`; merged APKs are unsigned (builds sign).
+    FrameDrop itself takes no bundles; `.apkx` is no defined format (read as a zip of APKs); old encrypted .apkm: refused.
  - Scanning: SideQuest backups (`<package>/<time>/apk|obb|data`) and AXRB downloads (`AXRB/<app id>/<binary id>/base.apk`
    + OBBs/assets; its `patched/`/`*-axrb.apk` PC builds are skipped) are recognised (`sources/quest_dump.py`, FAQ).
  - Quest/Rift twins stay separate entries, shown and named in Steam "Title (Quest)"/"(Rift)" (`core/titles.py`).
@@ -308,7 +336,11 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
    reinstall of the release's `.whl`); `prepare()` → `<data>/updates/<ver>/` (SHA256SUMS.txt required + checked,
    layout checked, Windows: the new FramePort.exe must have the running exe's Authenticode signer when that one is
    signed, `ready.json`); `apply()` writes + starts detached `apply.ps1`/`apply.sh` (wait for pid → Windows: copy over,
-    replaced files kept in `updates/<ver>/previous` because the zip has no top folder; macOS/Linux: mv to `.old` + swap,
+    replaced files kept in `updates/<ver>/previous` because the zip has no top folder; nothing touched while a program file
+    is in use, old-only files of app/Lib/DLLs/site-packages/data moved to `previous`, a failed copy deletes what it
+    added (#476: the old rollback kept new modules → old version crashed at start); bundles carry
+    `frameport/_bundle_files.txt` (package.py) → `core/bundle_files.check` at GUI start removes/ignores leftovers and
+    reports a mixed install; macOS/Linux: mv to `.old` + swap,
    rollback, `xattr -dr` quarantine → relaunch; `<data>/logs/update.log`). `ui/updater.py`: background check (10 s,
    then 6 h), sidebar card (hidden control, toggled), Library bar (`library_bar`), changelog dialog, job
    `app-update` that restarts only when no other job is active, `apply_pending_at_start()` in `main()` for
@@ -455,7 +487,9 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
 - No XR_FB_display_refresh_rate (`xrGetDisplayRefreshRateFB` -7), yet OVRPort's dispatcher offers it and answered 0 Hz
  → FrameBridge always answers with the measured rate (1/predictedDisplayPeriod, else 72). PreyVR (#306, idTech 4:
  `USERCMD_MSEC = 1000 / GetRefresh()`) had 0 ms tics: async thread spinning, `com_frameTime` stuck at 0, menu black.
- Guardian STAGE bounds report 1×1 m (scene emulation uses ≥1.5 m).
+- Guardian STAGE bounds report 1×1 m (scene emulation uses ≥1.5 m). OVRPlugin treats that rect as a configured
+  boundary but can't outline it ("ovrpBoundary_Outer is not supported"): Demeter's guardian check indexed an empty
+  array → with `scene_emul` the app's STAGE `xrGetReferenceSpaceBoundsRect` returns XR_SPACE_BOUNDS_UNAVAILABLE.
 - GL goes through **Zink** (Mesa GL on Vulkan). Mesa GLSL is strict: `#pragma` before `#extension` fails, implicit
  int/float conversions fail (enable `GL_EXT_shader_implicit_conversions`), num_views=2 shaders on single-view FBOs
  give GL_INVALID_OPERATION. Some GLES games hit `zink: DEVICE LOST` (Unity MSAA RTT; Sniper Elite VR even without).
@@ -568,20 +602,21 @@ Toy Master doesn't request a model after that (it uses its own), so the glb load
 **Crash backtraces:** Lepton writes tombstones only to `lepton-logcats/steamlaunch-<appid>/logcat-crash.log` (launch tests return `crash_log`). Fossilize loads into every app (userdebug guest) → `frame.vk_sanitize` (`native/vkshim`); overport's dispatcher aborts on swapchains > 4096 px → `frame.swapchain_limit`; cylinder layers → quad strips (`cylinder_strips`). Drawing equirect layers ourselves and a focus debounce were tried and removed: don't retry without a new approach. → docs/DEVICE_NOTES.md#crash-backtraces-fossilize-swapchain-limit-cylinder-and-equirect-layers
 **360° layers / 4XVR:** the Frame's Android runtime composites only quad + projection layers (quads always above projection layers). Per-game adapter settings (off by default): `equirect_emul` (GLES), `equirect_flip/face/res/fps/stereo`, `stable_local`, `focus_hold` (default on), `aim_pitch/aim_yaw/aim_forward`, `refresh_rate`, `layer_debug`; agent `link_media` / `app_media_dirs` put sent files into a player's own folder. → docs/DEVICE_NOTES.md#360-layers--4xvr
 **Companion apps / intents:** a second APK can run inside a game's Lepton container, but Lepton turns every `android.intent.action.VIEW` with data into `steam://openurl` → "open in external player" hand-offs can't work; Lepton installs exactly one `*.apk` per app folder. → docs/DEVICE_NOTES.md#companion-apps--intents-stremio--4xvr
-**Text input:** Lepton's Android has no IME and VR apps run headless (no focused window); `lepton-show-flatscreen` keeps VR and gives focus + Steam's keyboard (`device.text_input_window`); `frame.unity_text_input` patches Unity's TMP_InputField/InputField at Cpp2IL offsets; agent `_keyboard` = uinput "Type on Frame". `pm install` of a second APK corrupts the main app (`cmd_real package install` skips the hook). → docs/DEVICE_NOTES.md#text-input-stremio-vr
+**Browser stand-in (#466):** Lepton's `ActivityStarter.execute` takes every VIEW intent before resolution → `steam://openurl` into `/lepton/steam.pipe`; apps that first query for a browser (Plex) find none → opt-in `frame.browser_handoff` (activity + `dex/browser-handoff.dex` in the app's own APK, analysis `browser_query`); a 2D app with an APK patch on is built, not as_is (`engine.flat_as_is`). → docs/DEVICE_NOTES.md#browser-stand-in-for-sign-ins-plex-github-466
+**Text input:** Lepton's Android has no IME and VR apps run headless (no focused window); `lepton-show-flatscreen` keeps VR and gives focus + Steam's keyboard (`device.text_input_window`); `frame.unity_text_input` patches Unity's TMP_InputField/InputField at Cpp2IL offsets; agent `_keyboard` = uinput "Type on Frame". `pm install` of a second APK corrupts the main app (`cmd_real package install` skips the hook). Its window is a gamescope "desktop game" overlay: SteamVR auto-theaters it before the OpenXR session and opens the dashboard on it at session start (controllers = mouse on the Android screen, AC Nexus/#476/#477) → the launcher (`_theater_hold`, first thing) and dashboard worker keep `dashboard.autoShowGameTheater` off while such a game runs (agent v119, holds per launcher pid in `theater-holds/`); SteamOS 0.5.6 logs the dashboard button as `open_dashboard_action`. → docs/DEVICE_NOTES.md#text-input-stremio-vr, #typing-window-takes-the-controllers-steamvr-theater-mode-476-477-ac-nexus
 **User reports #4-#10:** shortcuts go to the signed-in account (agent `library_users`), `launch` errors `NOT_IN_LIBRARY`; shared Cpp2IL run (`unity_text_input.Il2cppReturnPatch`) for `frame.unity_runtime_msaa_off` and `frame.unity_multipass`; VR4 → catalog `use_alt`. **Catalog changes reach existing games**: recipes store `catalog_rev`, `library._follow_catalog` re-derives non-user recipes. → docs/DEVICE_NOTES.md#user-reports-2026-10-04-issues-4-10
 **Round 2 of reports / headset rounds 2-3 (2026-10-04):** vkshim `vk_shader_fix` (VR4); `Il2cppReturnPatch.field_loads` (I Am Cat); builds record `recipe_fp` (changed recipe/revised patch → "Update on Frame"); `Frame.relocate`; adapter `profile_remap` (Touch Plus/Pro); `sync_guard` (Myst); `focus_hold` tuning; ovrpshim for Unity 2017 (Accounting+); Steam library to every account, `shortcuts_lost` / `add_devkit_entry`; no clipboard service → `frame.sdl_clipboard`, `frame.godot_clipboard`; 2D apps keep non-VR patches (`needs_vr = False`); `frame/local.py` (FramePort on the Frame); after every app update `library._follow_catalog` re-derives non-user recipes once (`recipes.app_version`, `library.REFRESH_ON_UPDATE`). Analysis fields added later: **bump `analysis/detect.ANALYSIS_VERSION`** (re-analysis at GUI start + `pipeline.refresh_analyses`; `analysis_failed`). Roblox and BONELAB crash (unsupported). → docs/DEVICE_NOTES.md#round-2-of-reports-headset-rounds-2-3-2026-10-04
 **Round 4:** XR_KHR_android_surface_swapchain is listed but unsupported → adapter `surface_emul` (default on, `native/adapter/surface_swapchain.c`); save folders without u/g+rwx → launch.sh `fix_perms`; Lucky's Tale OOM (no fix); `perf` works as steamos (gdb blocked); QuestCraft JRE, WiiCompiled import by hand (Lepton has no document picker). → docs/DEVICE_NOTES.md#round-4-2026-10-04-surface-swapchains-save-folder-permissions
 **Steam library failures (GitHub #21/#30/#41/#42):** on some Frames Steam never loads FramePort's shortcuts.vdf entries (Play → AppError_9) → fallback: register through Steam's devkit interface (`devkit-1 … create-shortcut`, `~/devkit-game/<id>/`; `devkit_appid`, `devkit_appid_from_log`, `devkit_unregister`, `copy_grid_art`; ids: letter first, letters/digits/_ only); `collect_diag` adds `steam_library`. Cause still unknown. → docs/DEVICE_NOTES.md#steam-library-failures-and-the-devkit-fallback-github-21304142
 **Exit game (GitHub #36):** `Apps.TerminateApp` (Steam CEF devtools on 127.0.0.1:8080) closes games; launch.sh ends the game when its parent reaper is gone (`upgrade_launchers` adds it). → docs/DEVICE_NOTES.md#exit-game-github-36
 **SteamVR dashboard at game start:** launch.sh's `_dashboard_worker` hides the dashboard via `SteamClient.OpenVR.VROverlay` (agent `steam_js`) from the first FrameBridge `new layer:` line (120 s, ≤10 times, stops after `toggle_dashboard_action`); log `<base>/dashboard.log`, opt out `FRAMEPORT_KEEP_DASHBOARD=1`. → docs/DEVICE_NOTES.md#steamvr-dashboard-at-game-start
-**Space warp / ITR2:** OVRPort's dispatcher offers XR_FB_space_warp itself (`patch_disable_space_warp` doesn't reach UE5) → FrameBridge `hide_space_warp` (per game, off; suggested for UE5 + OVRPlugin). `equirect_emul` switches itself off on Vulkan. → docs/DEVICE_NOTES.md#space-warp--itr2
+**Space warp / ITR2:** OVRPort's dispatcher offers XR_FB_space_warp itself (`patch_disable_space_warp` doesn't reach UE5) → FrameBridge `hide_space_warp` (per game, off; suggested for UE5 + OVRPlugin). Games that *require* space warp (OutRun, #336: "AppSW recommended buffers unavailable") → `space_warp_emul` (`native/adapter/space_warp.c`: MV size, FrameBridge-owned MV/depth images, info stripped; overrides hide_space_warp). `equirect_emul` switches itself off on Vulkan. → docs/DEVICE_NOTES.md#space-warp--itr2
 **PR #34 (Lucas-Mathieu):** `native/adapter/audio_metadata.h` keeps Meta XR Audio Wwise metadata alive (Batman: Arkham Shadow 1.4.1 smoke-bomb crash). Outside PRs: review source, rebuild `artifacts/` ourselves, merge locally. → docs/DEVICE_NOTES.md#pr-34-meta-xr-audio-metadata-batman
 **Heuristics eval (2026-10-04):** 19/44 recipes exact (superseded by the 2026-10-15 numbers under Heuristics). → docs/DEVICE_NOTES.md#heuristics-eval-2026-10-04
 **Power (0.9, agent v47):** sidebar bar below the Frame card: Sleep / Restart / Shut down, each confirmed (`app.frame_power`, a running game asks again). logind answers CanSuspend/CanReboot/CanPowerOff = "challenge" for an SSH session but "yes" inside a user unit, so agent `power` runs `systemctl suspend|reboot|poweroff` from a transient `systemd-run --user --on-active=3` timer (the command answers first). Restart verified on the device (back in ~84 s, new boot id).
 **Proton default:** the newest **stable** ARM64 Proton (`pick_proton`; owner's headset A/B); `pcvr.proton_tool` dropdown (Experimental = alias `proton-experimental`), `ensure_proton`, `proton_alternative_worth_trying`. → docs/DEVICE_NOTES.md#proton-default-stable-vs-experimental
 **USB cable link:** `usb0` is a USB NCM gadget (Developer Mode only); Frame 10.86.200.233, PC **10.86.200.234** (`frame/usb.py`); ~37 MB/s; `scripts/usb_autotest.py`, `frameport frame usb-check`; discovery prefers USB > hotspot > network (`discovery.dedupe`). → docs/DEVICE_NOTES.md#usb-cable-link
-**Catalog updates without a release (2026-10-05):** apps fetch `catalog/games/*.yaml` from GitHub `main` (`recommend/catalog.refresh_remote`: one API call `git/trees/main?recursive=1` + raw.githubusercontent downloads of changed blobs, cached as `catalog-gh-<sha>.yaml`, every 6 h; GUI at start + Settings → Data "Check now"; CLI background thread + `frameport catalog-update`). `catalog.load()` only reads the cache. A remote entry is skipped (`unusable_reason`) when it names a patch/adapter key this app doesn't register, has a field `CatalogEntry` doesn't know, or `min_app` > this version: add `min_app` (or rely on new patch ids) when a config needs an unreleased FramePort. Remote beats bundled unless the bundled entry has a later updated/verified date; the user's own entries still win as before. Off: setting `catalog.auto_update`, env FRAMEPORT_NO_CATALOG_UPDATE; FRAMEPORT_CATALOG_URL still overrides the source. So: **pushing a catalog change to main reaches users within 6 h** (their recipes follow via catalog_rev → Update on Frame).
+**Catalog updates without a release (2026-10-05):** apps fetch `catalog/games/*.yaml` from GitHub `main` (`recommend/catalog.refresh_remote`: one API call `git/trees/main?recursive=1` + raw.githubusercontent downloads of changed blobs, cached as `catalog-gh-<sha>.yaml`, every 6 h; GUI at start + Settings → Data "Check now"; CLI background thread + `frameport catalog-update`). `catalog.load()` only reads the cache. A remote entry is skipped (`unusable_reason`) when it names a patch/adapter key this app doesn't register, has a field `CatalogEntry` doesn't know, or `min_app` > this version: add `min_app` (or rely on new patch ids) when a config needs an unreleased FramePort. Remote beats bundled unless the bundled entry has a later updated/verified date; the user's own entries still win as before. Off: setting `catalog.auto_update`, env FRAMEPORT_NO_CATALOG_UPDATE; FRAMEPORT_CATALOG_URL still overrides the source. So: **pushing a catalog change to main reaches users within 6 h** (their recipes follow via catalog_rev → Update on Frame). `catalog/triage.yaml` comes from the same tree listing (cached `triage-gh-<sha>.yaml`, index key `triage`; a new copy → `triage.reset()`; with FRAMEPORT_CATALOG_URL: that folder's optional `triage.yaml`): `validate/triage.database()` = bundled merged with remote per signature id (remote wins unless the bundled one has a later `updated:`; bundled-only ids stay), each remote signature dropped (bundled one kept) when malformed, it has an unknown field, suggests a patch/adapter key this app lacks, or `min_app` (per signature or top-level = whole file) > this version; `triage.skipped()`, `frameport catalog-update` lists them.
 **Start activity / QuestCraft / ITR2 pop-in:** `frame.start_activity` (analysis `extra.vr_activity`, `axml.set_start_activity`; OVRPort gives every MAIN activity LAUNCHER, so take the VR activity from the original APK); Unreal reads user config from **internal** storage; Lepton passes `LEPTON_ENV_<NAME>` to the app as `<NAME>` (QuestCraft `LIBGL_NOERROR`); vkshim `vk_query_slots` left off. → docs/DEVICE_NOTES.md#start-activity--questcraft--itr2-pop-in
 **Vulkan validation / ITR2 solved:** bundle Khronos' `libVkLayer_khronos_validation.so` into a test APK + vkshim `vk_validation=1` (logcat tag VALIDATION); `vk_spec_fixes=1` drops ITR2's invalid depth resolve; VALVE_rpo removed its fog (catalog `lepton_env: VK_INSTANCE_LAYERS`). Agent `not_started` waits 30 s for "Boot complete!". → docs/DEVICE_NOTES.md#vulkan-validation--itr2-solved
 **GitHub #38/#39:** SteamVR rejects image rects past their swapchain (-25) → FrameBridge `rect_clamp` (default on), triage `swapchain-rect-invalid`; The Room VR MSAA crash in libgallium. → docs/DEVICE_NOTES.md#github-3839-powerwash-simulator-the-room-vr
@@ -590,9 +625,11 @@ Toy Master doesn't request a model after that (it uses its own), so the glb load
 **Vader Immortal (GitHub #49):** stuck on its loading card and leaked GPU mappings (solved below: `gl_error_clear`); diagnostics FrameBridge `layer_debug`, `strip_color_bias`, `frame_balance`, `snapshot=N` (`snapshot_gl.c`: saves the submitted left-eye image as `files/fb_snap_*.ppm`). → docs/DEVICE_NOTES.md#vader-immortal-headless-investigation
 **SteamVR overlay apps:** host OpenVR overlays composite over Lepton games; detection `analysis/vroverlay.py`, patch `pcvr.vr_overlay`, Linux fields `vr_overlay`/`vr_overlay_autostart`, agent `register_vr_overlay`/`unregister_vr_overlay`/`launch_vr_overlay`; SteamVR on the Frame reads only `binary_path_linux_arm`; FramePort's own autostart (`ensure_overlay_service`, `frameport-vr-overlays.service`). See also docs/FRAME_RUNTIME.md "Overlay apps". → docs/DEVICE_NOTES.md#steamvr-overlay-apps
 **Vader's leak solved / AC Nexus flips:** stale GL errors broke SteamVR's GL interop → adapter `gl_error_clear` (GLES, catalog for Vader ep1-3); read `xrclient_<pkg>.txt` in Steam's logs for runtime errors; the runtime caps swapchains per session (~15) → flip emulation in place; adapter `flip_dump`. → docs/DEVICE_NOTES.md#vaders-leak-solved--ac-nexus-flips
+**Mixed reality: scanned rooms (branch mr-scene):** agent `room_capture` records Valve's RoomView 3D depth mesh -> `fp_roomscan` -> `room.txt` + `room-mesh.bin` (docs/mr/ROOM_FORMAT.md; refined by default: the owner's cleanup passes + label rules in `native/roomscan/refine.c`/`rules.c`, unrefined output kept as `room-raw.txt` + `room-mesh-raw.bin`, head path/settings/report/labels/door suggestions in `scan.json`, `--refine-only <dir>` re-runs it, `--refine 0` = old output; docs/mr/scan.md "Refinement") in `~/.local/share/frameport/rooms/<universe>/`, copied next to settings.conf (`_room_sync`); FrameBridge (`scene_room.c/scene_meta.c/scene_anchors.c`, all through xrshim) serves walls, volumes, planes, the room mesh, META discovery/persistence, saved anchors and `XR_META_boundary_visibility`; `scene_emul` + `frame.meta_permissions` for every USE_SCENE/USE_ANCHOR_API game (migrations `scene_emul_all`, `scene_permissions`); per-game `scene_hide_bounds` (Demeter). → docs/DEVICE_NOTES.md#mixed-reality-scanned-rooms
 **Unreal's self-restart:** UE 4.21+ restarts itself after the first shader precompile and Lepton ends the container → launch.sh RESTART_BLOCK starts Lepton once more (`upgrade_launchers`; `FRAMEPORT_NO_RESTART=1` off). → docs/DEVICE_NOTES.md#unreals-self-restart
 **xrWaitFrame runs ahead:** the runtime sometimes returns a display time <1 refresh after the last submit and rejects the second submission (`VRCompositorError_AlreadySubmitted`) → the VrApi bridge re-waits (`pacing 2s:` counters). → docs/DEVICE_NOTES.md#xrwaitframe-runs-ahead-journey-of-the-gods
 **Lepton's logcat mirror dies** (EOF, read failure, or silent) → launch.sh `_logcat_keeper` reads `podman exec <container> logcat` itself into launch.log (log `<base>/logcat-keeper.log`). → docs/DEVICE_NOTES.md#leptons-logcat-mirror-dies
+**Graceful stop (#480, agent v120):** killing the container never paused the app (saves in `OnApplicationPause` lost: Just Dance VR) → launch.sh `pause_game` / agent `stop` / End game first `am start` the HOME intent in the container (`input keyevent` does nothing headless) and wait ≤3 s for STOPPED (`PAUSE_SCRIPT`, `<base>/stop-pause.log`). Steam's own Exit game signals the whole process tree (conmon is re-parented to the reaper) at once → agent v121: launch.sh's `_exit_hook` worker (`exit_hook_worker`, `EXIT_HOOK_JS`) wraps `SteamClient.Apps.TerminateApp` in SharedJSContext with a CDP binding of its own: Exit game for that game's ids waits for the worker's pause (cap 3 s, 0.8 s without an answer, lease 10 s), other ids pass straight through; End game calls `terminate_app_js` (past the hook). → docs/DEVICE_NOTES.md#graceful-stop-the-game-is-paused-before-it-ends-github-480-agent-v120
 **Double launch:** launch.sh takes `flock` on `<base>/.launch.lock` (fd 9); a second launch exits 0 and logs to `<base>/launch-dup.log` (`upgrade_launchers` adds it). → docs/DEVICE_NOTES.md#double-launch
 **Issue triage round 2026-10-06:** FrameBridge turns haptic amplitude 0 into xrStopHapticFeedback, per-game `haptic_scale`; Lambda1VR → `frame.tbxr_vendor`; Jurassic World → `frame.vrapi_stub`; Metro Awakening / Pinball FX → `hide_space_warp`; `frame.ovr_trace` can't trace Unity games; the VrApi bridge's 30 s head-pose deadline ends headless VR mode. → docs/DEVICE_NOTES.md#issue-triage-round-2026-10-06
 **Lepton storage:** each app's /sdcard has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (agent `storage_targets`); the media index never works; Lepton grants all runtime permissions. → docs/DEVICE_NOTES.md#lepton-storage
@@ -601,6 +638,8 @@ Toy Master doesn't request a model after that (it uses its own), so the glb load
 **Cube swapchains:** the runtime refuses `faceCount=6` → FrameBridge `cube_standin` (default on, GLES only, `native/adapter/cube_standin.c`). → docs/DEVICE_NOTES.md#cube-swapchains
 **Hardware video decoding:** `native/hevc` OMX plugin (`OMX.frameport.{avc,hevc,vp9}.decoder`), installed once per Frame (`ensure_video_codec`, agent `video_codec_status`/`install_video_codec`/`video_codec_switch`); **bump `revision` in native/hevc/build.py with every artifact change**; per game `frame.hw_video_decode` (analysis `media_codec`), Settings `video.hw_decode`, `FRAMEPORT_NO_HW_VIDEO=1`; Batman migration `batman_video_patches` + `surface_native`. → docs/DEVICE_NOTES.md#hardware-video-decoding
 **Vulkan shader dump:** adapter `vk_shader_dump=1` (`native/vkshim/shader_dump.h`) writes SPIR-V modules + `index.txt` to `files/fp_vk_shaders/`; `collect_diag` returns the newest session's modules (`shader_dumps`); triage `gpu-hang`, `triage.graphics_api`. → docs/DEVICE_NOTES.md#vulkan-shader-dump
+**Foveation centre (#394):** Valve's FDM layer centres its density map on the whole swapchain (not the eye's rect or optical axis) and Turnip picks density per GMEM bin (the sharp area snaps to bins, so its size shifts with render resolution: driver design); `VK_LAYER_FRAMEPORT_fdm_centre` (native/foveation/centre.h, below Valve's layer, views from FrameBridge `fdm_views.c`) rewrites the per-eye density-map offsets; FrameBridge `snapshot=N` reads Vulkan eyes back. → docs/DEVICE_NOTES.md#foveation-sharp-area-centre-and-size-394
+**Expansion file names (#450/#481):** OBBs with a download's copy suffix (`main.203.com.Armature.VR4-003.obb`) or another case are installed under the game's name (`quest_dump.obb_names`/`frame_manifest`, PC files untouched), other kinds too (#415: Crisis Brigade 2's `office.222.<pkg>.obb`, kind spelling kept, never an "another app" warning); another app's name (#129), duplicates and unclear cases stay warnings. → docs/DEVICE_NOTES.md#expansion-file-names-450-481
 **Unreal OBB check (#159):** `frame.unreal_skip_obb_check` (analysis `unreal_verify_obb`) turns off Epic's OBB CRC pass; triage `unreal-obb-check-stuck`. → docs/DEVICE_NOTES.md#unreal-obb-check
 **Issue round 2026-10-12:** Lepton breaks on unquoted paths with spaces → launchers give Lepton a `~/.local/share/frameport/lepton-paths/<pkg>` link (`app_dir_lines`/`set_app_dir`/`launcher_base`); `frame.eos_keychain_loop`, `frame.unity_tls_key_pool` (`libfp_tkeys.so`, `elf.rename_imports`), `frame.vermillion_scene_canvas`; `tools/cpp2il.py` falls back to Cpp2IL's dev build for metadata v107; Linux `desktop_icon`; `scripts/upload_bench.py`. → docs/DEVICE_NOTES.md#issue-round-2026-10-12
 **OpenSSH uploads (#324/#242):** `native_upload.quote` escapes only backslash and `"`, Win32 local paths go as `C:/…`; `Frame.auth` records the login that worked (app_key / user_key from `ssh.extra_keys`, `frame ssh-keys`, agent, password); strict IdentitiesOnly first, relaxed retry. → docs/DEVICE_NOTES.md#openssh-uploads
@@ -704,7 +743,8 @@ short recap of the thread so far; read **all** comments on a thread first (a lat
 - **How a change reaches users** (decide this before promising a fix):
  - *Catalog / recipe / triage* changes reach **installed** apps within ~6 h with no build — apps fetch
    `catalog/games/*.yaml` + `triage.yaml` from `main` (`catalog.refresh_remote`), recipes follow via `catalog_rev` →
-    "Update on Frame". So accepting a recipe or adding a triage signature is "live" once pushed.
+    "Update on Frame". So accepting a recipe or adding a triage signature is "live" once pushed (a signature that
+    suggests a patch/setting the installed app doesn't have yet is skipped there: needs a release; `min_app` gates it).
  - *Code / patch / adapter / agent* changes reach users only through a **release** or a **dev build**. For a per-game
    fix a reporter should try now: push to `main`, cut a dev build (Actions → build → `dev` ticked, with `notes`), tell
    them to install it via **Settings → Updates → "Install the latest dev build…"** and then rebuild the game on the
@@ -778,3 +818,9 @@ asks before ending a running game, and closes local FramePort/Desktop Mode. Purg
 Hook hardening: both lines `-` + `/usr/bin/timeout -k 5 20`; ExecStartPost only `systemd-run --no-block`s the
 verify (unit frameport-library-verify) so Steam's start never waits; drop-in removed once mode != later and nothing
 pending (`drop_library_hooks_if_idle`). Steam = static user unit steam.service (Type=simple, Restart=always, 90 s).
+Agent v124: a waiting `now` worker holds the shortcut lock (`shortcut_lock`) for up to 12 h, so nothing an SSH command
+reaches blocks on it (an install's `library_mode` hung until the 600 s agent timeout): `library_mode` tries once and
+skips the hook cleanup; `cmd_shortcuts` journals into the waiting worker (`pending_lock`, a short separate lock;
+the worker writes "running" under it before merging the journal after stop_steam, one restart for all; the PC
+shows the same "waiting" reason); `queue_library` waits ≤30 s, else journal only; runs drop what they applied
+(`consume_pending`), never later entries.
@@ -2,12 +2,17 @@

 Thanks for helping. The quickest contributions:

- **A game works on the Frame?** In FramePort: the game's menu → **Share working config…** opens a prefilled issue
-  with its recipe. Accepted configs become built-in recipes.
- **Something doesn't work?** The game's menu → **Report a problem…** saves a diagnostics zip (personal data
-  removed) and opens a prefilled issue to attach it to.
+- **A game works on the Frame?** Game menu → **Recipe → Share working recipe…** opens a prefilled issue. After
+  review the recipe becomes a built-in recipe (`catalog/games/<package>.yaml`), and installed copies of FramePort get
+  the recipe within 6 hours.
+- **Something doesn't work?** Game menu → **Troubleshoot → Report a problem…** saves a diagnostics zip (personal data
+  removed) and opens a prefilled issue to attach the zip to.
+
+Without the app: [working recipe form](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml)
+· [problem report form](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml).

 ## Development
+
 ```
 uv sync --extra dev          # Python 3.11+, uv (https://docs.astral.sh/uv/)
 uv run frameport-gui         # the app
@@ -15,39 +20,32 @@ uv run frameport --help      # the command line
 uv run pytest                # tests (no headset or game files needed)
 uv run ruff check .          # lint
 ```
- Code and architecture: `CLAUDE.md`, `docs/ARCHITECTURE.md`; per-game symptoms and fixes: `docs/PLAYBOOK.md`.
- Interface wording: `docs/STYLE.md`. GUI texts go through `tr()`; after changing them run
-  `python scripts/i18n_extract.py`.
- Translations: see [Translating FramePort](#translating-frameport) below.
- New fixes are patch modules (`src/frameport/patches/`), with a triage signature (`catalog/triage.yaml`), a PLAYBOOK
-  row and a unit test.
- Native binaries in `artifacts/` are rebuilt with `python native/build.py` (downloads the NDK).

-## Adding a tested game
-
-Tested a game on the Steam Frame? The easiest way is in FramePort: open the game → **…** → **Share working config…**.
-It opens a prefilled GitHub issue with the exact recipe; after review a workflow turns it into
-`catalog/games/<package>.yaml`. Without the app: [working config form](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml). Something doesn't run: the game's
-**Report a problem…** (diagnostics zip, personal data removed) or the [problem report form](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml).
-After catalog changes, regenerate the games list: `python scripts/compat_list.py`.
+- Where things are: `docs/ARCHITECTURE.md` (module notes in `CLAUDE.md`), `docs/PLAYBOOK.md` (symptoms and fixes),
+  `docs/FRAME_RUNTIME.md` (runtime facts).
+- A new fix = a patch module (`src/frameport/patches/`) + a triage signature (`catalog/triage.yaml`) + a PLAYBOOK row
+  + a unit test.
+- After changing a patch, game setting, recipe or triage signature: `python scripts/patch_docs.py`. After catalog
+  changes also `python scripts/compat_list.py`.
+- GUI texts go through `tr()`; after changing them run `python scripts/i18n_extract.py`. Wording rules:
+  `docs/STYLE.md`.
+- Docs screenshots and videos are rendered, never taken by hand: `docs/SHOWCASE.md`.
+- Native binaries in `artifacts/`: `python native/build.py` (downloads the NDK).

 ## Translating FramePort
-The app's texts (screens, help, patch and setting descriptions) can be translated; the command line, logs and
-diagnostics stay English. No programming needed:

-1. Copy `src/frameport/locales/template.json` to `src/frameport/locales/<code>.json`, where `<code>` is the language
-   code (`de`, `fr`, `pt`, `ja`, …).
-2. Add `"_language": "<the language's own name>"` (e.g. `"Deutsch"`); it's shown in Settings → Language.
-3. Fill in the values. Each key is the English text; leave a value empty to keep the English text. Plural entries
-   have a list value: `["<one>", "<other>"]`. Keep `{placeholders}` such as `{title}` or `{n}` exactly as they are,
-   and keep `…`, `·` and line breaks where the English has them.
-4. Try it: `uv run frameport-gui`, choose the language in Settings → Language, restart FramePort.
-5. Open a pull request with the file. When the English texts change, `python scripts/i18n_extract.py` refreshes the
-   template; new texts then show in English until they're translated.
+The app's texts can be translated, no programming needed. The command line, logs and diagnostics stay English.

-Wording rules for English (and a guide for tone) are in `docs/STYLE.md`.
+1. Copy `src/frameport/locales/template.json` to `src/frameport/locales/<code>.json` (`de`, `fr`, `pt`, `ja`, …).
+2. Add `"_language": "<the language's own name>"`, for example `"Deutsch"`.
+3. Fill in the values. Each key is the English text; an empty value keeps the English. Plural entries take a list:
+   `["<one>", "<other>"]`. Keep `{placeholders}` such as `{title}` exactly, and `…`, `·` and line breaks where the
+   English has them.
+4. Try the translation: `uv run frameport-gui`, pick the language in Settings → Appearance → Language, restart FramePort.
+5. Open a pull request with the file. New English texts show in English until they're translated.

 ## Ground rules
+
 - Use only games you own. Contributions that help bypass DRM, licence or entitlement checks, or that add game files,
  are not accepted.
 - Never commit personal data (IP addresses, user names, home paths, Steam IDs).
@@ -8,78 +8,73 @@
 ![Steam Frame](https://img.shields.io/badge/Steam%20Frame-supported-1b2838?logo=steam&logoColor=white)

 Install Quest games, Android apps, Linux apps and PC VR games on the **Valve Steam Frame**. FramePort sets up the
-Frame, patches each game so it runs there, uploads it and adds it to your Steam library with artwork.
+Frame, patches each game to run there, uploads the game and adds the game to your Steam library with artwork.

 [![FramePort: library, one-click install, play, monitor](docs/images/tour-teaser.webp)](docs/media/frameport-tour.mp4)

-▶ [Watch the full tour](docs/media/frameport-tour.mp4) · New to FramePort? [Watch the install tutorial](docs/media/frameport-install.mp4)
+▶ [Watch the tour](docs/media/frameport-tour.mp4) · [Watch the install tutorial](docs/media/frameport-install.mp4)
 (about 90 seconds each)

 > **Notice:** FramePort doesn't download, share or unlock games. Use games you got legally, for example from
-> [SideQuest](https://sidequestvr.com/). FramePort downloads published open-source tools (see [Built on](#built-on))
-> and adds its own patches so games run on the Frame.
+> [SideQuest](https://sidequestvr.com/). FramePort downloads published open-source tools ([Built on](#built-on))
+> and adds its own patches.
 >
-> Not every game runs on the Frame: recipes are tested by the community, and some games need Meta's services or
-> hardware the Frame lacks.
+> Not every game runs on the Frame. Some need Meta's services or hardware the Frame lacks.

 ## Features

 ![Library](docs/images/library.png)

 - **Easy setup:** one line in the Frame's terminal. No root, no password. [What it changes](docs/FRAME_SETUP.md).
- **One click per game:** patch, upload, add to Steam with artwork and test that it starts.
- **Recipes:** tested patches and settings for 120+ games; other games get suggested patches, each explained in
-  plain words.
+- **One click per game:** patch, upload, add to Steam with artwork, test that the game starts.
+- **Recipes:** tested patches and settings for hundreds of games. Other games get suggested patches, each explained.
 - **Game settings:** sharpness, refresh rate, controllers, 360° video and mixed reality as simple switches.
 - **More than Quest games:** Android apps in a window, Linux apps, PC VR games and Windows programs.
- **Install links:** "Install with FramePort" buttons on websites ([frameport.app](https://frameport.app) links) open
-  in FramePort.
- **Your Frame from your PC:** Type on Frame (your keyboard on the Frame), Files, Screenshots, Live view (what the
-  headset shows, in your browser) and Monitor (frame rate, temperatures, battery, processes).
+- **Install links:** "Install with FramePort" buttons on websites open in FramePort.
+- **Your Frame from your PC:** Type on Frame, Files, Screenshots, Live view (what the headset shows) and Monitor
+  (frame rate, temperatures, battery, processes).
+- **Your room for mixed reality (experimental):** scan your room in the headset and fix the scan up in 3D. Try the room with
+  [Test Quest MR](https://github.com/spoopyghosty0/TestQuestMR).
 - **Updates itself**, and reports problems without personal data.

-Details for each: [Install and first steps](docs/INSTALL.md).
-
 ![Monitor](docs/images/monitor.png)

 ![Screenshots](docs/images/screenshots.png)

+![Room (experimental): the scanned room in 3D, clean-up and labels](docs/images/room.png)
+
 ## Quick start

-1. [Download](https://github.com/spoopyghosty0/frameport/releases/latest) the build for Windows, macOS (Apple
-   Silicon) or Linux, unpack it and start FramePort.
-2. In FramePort click **Steam Frame → Start setup**. The Frame and your PC must be on the same Wi-Fi (or use a USB
-   cable).
-3. On the Frame open the **SteamVR dashboard → Launch a program → Desktop**, then the app menu → **System →
-   Konsole**, and run:
+1. [Download](https://github.com/spoopyghosty0/frameport/releases/latest) FramePort for Windows, macOS (Apple
+   Silicon) or Linux, unpack the download and start FramePort.
+2. Click **Steam Frame → Start setup**. The Frame and your PC must be on the same Wi-Fi (or use a USB cable).
+3. On the Frame open **SteamVR dashboard → Launch a program → Desktop**, then **app menu → System → Konsole**, and
+   run:

   ```
   curl -fsSL https://frameport.app/s | bash
   ```

-4. Click **Allow** in FramePort when it shows the same 4-digit code as the Frame. Steam restarts once; if it asks to
-   install **Lepton** (Valve's Android runtime), confirm it.
-5. **Add games → Scan a folder…** with your games, open one and click **Install on Frame**. Play it from the Frame's
-   Steam library.
+4. Click **Allow** when FramePort shows the same 4-digit code as the Frame. Steam restarts once. If Steam asks to install
+   **Lepton** (Valve's Android runtime), confirm.
+5. **Add games → Scan a folder…**, open a game and click **Install on Frame**. Play the game from the Frame's Steam library.

-Full guide, firewalls and troubleshooting: [Install and first steps](docs/INSTALL.md). How to lay out game folders:
-[FAQ](docs/FAQ.md).
+Full guide: [Install and first steps](docs/INSTALL.md). Game folders: [FAQ](docs/FAQ.md).

 ## Compatibility

-Tested games use their recipe (the patches and settings that work for them) automatically; for other games FramePort
-suggests patches. See the [list of tested games](docs/GAMES.md). Got a game working? Share its recipe from the game's
-**…** menu: [how](docs/INSTALL.md#share-a-recipe-or-report-a-problem).
+Tested games get their recipe (the patches and settings that work) automatically. Other games get suggested
+patches. See the [tested games](docs/GAMES.md). Got a game working?
+[Share its recipe](docs/INSTALL.md#share-a-recipe-or-report-a-problem).

 ## Compared with other tools

-FrameDrop and Valve's own tools install an app as it is. FramePort differs in four ways:
+FrameDrop and Valve's own tools install an app as it is. FramePort also:

- **Free and open source** (GPL-3.0). FrameDrop is free (donationware) without published source.
- **Quest games that don't run on the Frame as they are** get converted and patched, with a tested recipe for 120+
-  games. The others install the game unchanged.
- **Windows, macOS and Linux.** FrameDrop is for Windows.
- **Wi-Fi or a USB cable**, and no **Pair new host** step.
+- is **free and open source** (GPL-3.0). FrameDrop is free (donationware), without published source.
+- **converts and patches Quest games** that don't run as they are, with tested recipes for hundreds of games.
+- runs on **Windows, macOS and Linux**. FrameDrop is for Windows.
+- connects over **Wi-Fi or a USB cable**, without a **Pair new host** step.

 <details>
 <summary>All differences</summary>
@@ -88,12 +83,12 @@ FrameDrop and Valve's own tools install an app as it is. FramePort differs in fo
 |---|---|---|---|
 | Cost and source code | Free, open source (GPL-3.0) | Free (donationware), source not published | Free, from Valve |
 | Runs on | Windows, macOS, Linux | Windows | Depends on the tool |
-| First connection | One line in the Frame's terminal; it turns on Developer Mode itself. No password | Turn on Developer Mode, then **Pair new host** | Turn on Developer Mode and pair, or use Android's debug tool (adb) |
+| First connection | One line in the Frame's terminal; turns on Developer Mode itself. No password | Turn on Developer Mode, then **Pair new host** | Turn on Developer Mode and pair, or use Android's debug tool (adb) |
 | Wireless or cable | Wi-Fi, the Frame's hotspot or a USB cable | Same Wi-Fi network | Wi-Fi, or adb |
 | Quest games that don't run as they are | Converted and patched for the Frame | Installed as they are | Installed as they are |
-| Knows which patches a game needs | Tested recipes for 120+ games, updated without an app update | Not stated | No |
+| Knows which patches a game needs | Tested recipes for hundreds of games, updated without an app update | Not stated | No |
 | In the Steam library | Yes, with artwork and tags | As a "Devkit Game" shortcut | As "Devkit Game: &lt;title&gt;"; not with adb |
-| Android apps, Linux apps, Windows programs | All three; Proton (runs Windows programs) is installed for you | All three; install Proton first | Yes; 2D Android apps need an extra file |
+| Android apps, Linux apps, Windows programs | All three; Proton is installed for you | All three; install Proton first | Yes; 2D Android apps need an extra file |
 | PC VR games | On your PC; some also on the Frame | Not supported | Not supported |
 | "Install with …" buttons on websites | Yes ([frameport.app](https://frameport.app) links) | Its own | No |
 | A game doesn't start | A launch test reads the logs and suggests a patch | A log viewer | No help |
@@ -101,10 +96,10 @@ FrameDrop and Valve's own tools install an app as it is. FramePort differs in fo

 </details>

-Other tools as described on their own pages, checked 2026-10-09:
+Based on each tool's own pages, checked 2026-10-09:
 [FrameDrop about](https://framedropvr.com/about) · [how-to](https://framedropvr.com/how-to) ·
 [Valve: loading games on Steam Frame](https://partner.steamgames.com/doc/steamhardware/steamframe/loadgames).
-Out of date? [Report a problem](https://github.com/spoopyghosty0/frameport/issues/new).
+Out of date? [Report the problem](https://github.com/spoopyghosty0/frameport/issues/new).

 ## Built on

@@ -119,15 +114,17 @@ What FramePort adds: [Architecture](docs/ARCHITECTURE.md).

 | | |
 |---|---|
-| [Install and first steps](docs/INSTALL.md) | Install, connect, update, PC VR games, files, problem reports |
-| [What the setup changes](docs/FRAME_SETUP.md) | What setup changes on the Frame, networks and firewalls, undoing it |
-| [Compatibility](docs/COMPATIBILITY.md) | What runs and how well |
-| [Tested games](docs/GAMES.md) | Tested games and how well they run |
-| [FAQ](docs/FAQ.md) | Game folders and common questions |
-| [Controller buttons](docs/CONTROLLERS.md) | Quest Touch buttons on the Frame: SteamVR default, Mirror and Quest pair |
-| [Porting playbook](docs/PLAYBOOK.md) | Symptoms and fixes per game |
-| [Steam Frame runtime reference](docs/FRAME_RUNTIME.md) | Facts about the Frame's runtime |
-| [Architecture](docs/ARCHITECTURE.md) | How the code is organized |
+| [Install and first steps](docs/INSTALL.md) | Install, connect, install games, update |
+| [What the setup changes](docs/FRAME_SETUP.md) | Changes on the Frame, firewalls, undoing it |
+| [FAQ](docs/FAQ.md) | Game folders and fixing problems |
+| [Compatibility](docs/COMPATIBILITY.md) · [Tested games](docs/GAMES.md) | What runs, and how well |
+| [Controller buttons](docs/CONTROLLERS.md) | Quest buttons on the Frame's controllers |
+| [Themes](docs/THEMES.md) | Color themes and making your own |
+| [Install button](docs/INSTALL_BUTTON.md) | An "Install with FramePort" button for your download page |
+| [Diagnostics](docs/DIAGNOSTICS.md) | What a problem report contains |
+| [Patch reference](docs/PATCHES.md) | Every patch and game setting |
+| [Porting playbook](docs/PLAYBOOK.md) · [Runtime reference](docs/FRAME_RUNTIME.md) | Symptoms and fixes; facts about the Frame |
+| [Architecture](docs/ARCHITECTURE.md) · [Screenshots and videos](docs/SHOWCASE.md) | How the code and the docs' pictures are made |
 | [Contributing](CONTRIBUTING.md) | Code, recipes, translations |

 ## Development
@@ -1,6 +1,6 @@
 # Third-party notices

-FramePort is GPL-3.0-only (see `LICENSE`). It includes or downloads the following third-party work.
+FramePort is GPL-3.0-only (see `LICENSE`). FramePort includes or downloads the following third-party work.

 ## Included in this repository / the release bundles
 | Component | Where | License |
@@ -25,6 +25,8 @@ FramePort's own native code (the FrameBridge adapter, GL/Vulkan/OpenXR shims, th
 | Eclipse Temurin JRE | api.adoptium.net | GPL-2.0 with Classpath Exception |
 | apksigner (Android build-tools) | dl.google.com Android repository | Apache-2.0 |
 | Revive (portable copy, only if Revive isn't installed) | github.com/LibreVR/Revive releases | GPL-3.0 |
+| Cpp2IL (only for Unity IL2CPP patches) | github.com/SamboyCoding/Cpp2IL releases | MIT |
+| APKEditor (only for app bundles with resource splits) | github.com/REAndroid/APKEditor releases | Apache-2.0 |

 Valve's Lepton, Proton and SteamVR, and Meta's software, are used on your devices as installed by Steam / Meta;
 FramePort doesn't distribute them.
@@ -1,16 +1,18 @@
 # Announcements

-`current.md` is the one announcement FramePort shows as a pop-up in the app. Edit it on `main`: the app reads it
-from GitHub `main` (raw.githubusercontent.com) at most every 6 hours, so a push reaches everyone without a release.
+`current.md` is the one announcement FramePort shows as a pop-up in the app. Edit `current.md` on `main`: the app
+reads the file from GitHub `main` (raw.githubusercontent.com) at most every 6 hours, so a push reaches everyone
+without a release.

 ## Who sees it

- **Only people who already used FramePort before the announcement's `date`.** A new install never shows one, and
-  nor does an announcement published before FramePort was installed.
- **Once.** Closing it in any way (the X, a click outside it, Escape, or its button) dismisses it for good. The app
-  remembers dismissals in its settings (`announce.dismissed`).
- **A new announcement = a new `id`.** Fixing a typo with the same `id` doesn't show it again to anyone who closed it.
-  A new `id` shows to everyone who used FramePort before its `date`, whether they closed the earlier one or not.
+- **Only people who used FramePort before the announcement's `date`.** A new install never shows an announcement,
+  and neither does an announcement published before FramePort was installed.
+- **Once.** Closing the pop-up in any way (the X, a click outside, Escape, or the pop-up's button) dismisses the
+  announcement for good. The app remembers dismissals in its settings (`announce.dismissed`).
+- **A new announcement = a new `id`.** A typo fix with the same `id` doesn't show the announcement again to anyone
+  who closed it. A new `id` shows to everyone who used FramePort before its `date`, whether they closed the earlier
+  announcement or not.

 ## The file

@@ -31,7 +33,7 @@ The body, in Markdown: **bold**, *italic*, `code`, [links](https://frameport.app

 The body is Markdown (no HTML). A `date` in the future works as a schedule: nobody sees it before then.

-Images look best at about 2:1 (e.g. 1200×600). The pop-up is 600 px wide and shows between 140 and 320 px of the
+Images look best at about 2:1 (for example 1200×600). The pop-up is 600 px wide and shows between 140 and 320 px of the
 picture's height.

 `pytest tests/test_announcements.py` checks this file, so a broken announcement fails CI instead of silently showing
@@ -1,32 +1,66 @@
-1a4dce5c4a6d0dfc5f20e55ac29e70c73cc2cc124c21ca6a7e1b316e6afb1c79  ./arm64-v8a/libVkLayer_fdm_darken.so
-5becb96ee86fbda0ce98c0e0fd064f8ba092314aceaa400e3dcc785705dc3c23  ./arm64-v8a/libVkLayer_fp_shaderfix.so
-222727ddabf7eaee08c92e86c64f02edc6639667e9041ab2629032b885c9ae3a  ./arm64-v8a/liba32bridge.so
-c9c3da5cac224c38e2210b781bd12b7f97e02bd6b0ebb0ef85543e4ea4b76671  ./arm64-v8a/liba32rt.so
+dfeee15b52a530aef0fc90f79140249522adf888d1c88fd57935dd8ce5257fa5  ./arm64-v8a/libVkLayer_fdm_darken.so
+86974202436e9209e260a690ae3eb0082d7d0f88e17c621dd77c0788ea66bc6d  ./arm64-v8a/libVkLayer_fp_shaderfix.so
+e63d93e086df3b7b29501188b80fb113879e2fd325d7659f68a31ac5bc87b561  ./arm64-v8a/liba32bridge.so
+81b073b0cdf11fdb09d22dff682884c5046fe13801f18db9aed232e86f3bf173  ./arm64-v8a/liba32rt.so
 18d8d917e83a6d87008f41908eb478dff635e798844e125abd1e8a5cf31805e2  ./arm64-v8a/liba32stub.so
-d6337034fb0bdcca7ef9b7063d85b7586b8508b63b435959e8fffaba0691091c  ./arm64-v8a/libfp_langpack.so
+845905e8c2da617dddcb9625f4ed38e06f1d85f9c729b55dacb2c59488074c3e  ./arm64-v8a/libfp_langpack.so
 69102b128e00fa1809489a7308e09c1505f563bf7091bbdd3fe5a58e4cc96c2c  ./arm64-v8a/libfp_luajit.so
 321da502e0f8f46f0880aad39fe6b84bdef88f925164568814cf704a1b31a577  ./arm64-v8a/libfp_ovrp.so
 40defdaddcda53bd2649eb48076fae1622bfc2bfc88e9e03c94fc8b45af2a4f2  ./arm64-v8a/libfp_ovrtrace.so
 0167c2fde5dfde62897f9d85afc4fc8e97784e988b5b8df6cea8c407240b3424  ./arm64-v8a/libfp_tkeys.so
-e32f9b3222bfe2e58c193db809ac2cf54086df36fd2ec6651aa2e58308f6b39d  ./arm64-v8a/libfp_vk.so
+0055308856070aa7e09d80bcf66ea52dc0a495829b9da64383e38f4350706226  ./arm64-v8a/libfp_vk.so
+3c548b567c6984c91bf3f4a2b0bae1336f569f3e9fa9c3204872fd9876f88284  ./arm64-v8a/libfp_xrruntime.so
 383054f8b3b41dde76d062c71856cd3163655e50009c08454bc1793f393ead65  ./arm64-v8a/libfpg.so
 4a13a33e112c9e4e3c5ff4337ed6e988a9e5b3602f48d654df148ef5fafbf426  ./arm64-v8a/libfpglmv.so
 36400eae4ba3807bcfcd54463daa217347032b07218792faa448d8cbbd086a0e  ./arm64-v8a/libframe_xrshim.so
 19ba5ed3c4b780f5ae46251f6958f552acfc5f13c8bb39f995579593fa8990c6  ./arm64-v8a/libglshim.so
-f0894d9cc08aed4c0f6468134e76909d583a208c3f5e528bc3ee795f51b19fcb  ./arm64-v8a/libopenxr_loader_generic.so
+be863bb0001bc60e9bbd691753f5c5968664ae7917b29258dd15b7a9dd1c3ade  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
-a4ed80ae45ca90758239f152ea5a2e8c127d491e1e697ea5680db6fd7f72db07  ./arm64-v8a/libvrapi.so
-a4ed80ae45ca90758239f152ea5a2e8c127d491e1e697ea5680db6fd7f72db07  ./arm64-v8a/libvrapi_foveation.so
-4e03a8389981ed5a27b4c159cc83168c4f93d0d75479a445b02e5669aa26a71b  ./armeabi-v7a/libopenxr_loader_generic.so
+c7a14d34e4ddf20ec943641f6431525867d6f030cd01160df1b24afd441af39f  ./arm64-v8a/libvrapi.so
+c7a14d34e4ddf20ec943641f6431525867d6f030cd01160df1b24afd441af39f  ./arm64-v8a/libvrapi_foveation.so
+2f978a24bc78a33a4162f5d35ec13d722a5a965a67772bd6128cbd6f8b0b4b17  ./armeabi-v7a/libopenxr_loader_generic.so
+6fd59e6c6e533c0a17204e4f12adaf992ffa6cf58d6280aa9b37ca7ba20299d4  ./dex/browser-handoff.dex
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 b634ab5640e258563c536e658cad87080553df6f34f62269a21d554844e58bfe  ./hevc/COPYING.FFmpeg
-141de01f0d40b97d4f9a720db5ab8ea442f6aa35db5272048899292884994a1c  ./hevc/libstagefrighthw.so
-4516971bbb2b635e19b14d2d37b9353962876f7de02043e7457327052c1fcbc0  ./hevc/manifest.json
+55aae57d292e9536701f2f8a9dbaf1edcfdd766c5748d07a34da2f5ef197f212  ./hevc/libstagefrighthw.so
+389352bf10c03ab54e784a43c9b217451dd814cacec1d7178777e337c9d6f7de  ./hevc/manifest.json
 46c3dcad2c43cc30bea3b3680b362ed84a99c15d60714bbbbb422c80ecf90405  ./hevc/media_codecs_frameport.xml
 529ea35d5d82474afe9e09ad1216d269317f56dd24a05fb100fced52b7b4dbca  ./hevc/podman.py.txt
 6cda3076a8c09b31bb1f90da614ea89e7ee194589626eeac613e522849604e47  ./licenses/LuaJIT.txt
 1aa733117cf57ccff7cf23f0425dbfd73b0332a3ef1c905ceeca0ccd0449c4e0  ./linux-arm64/XR_APILAYER_FRAMEPORT_timefix.json
 28c2430a02bbd8902c5bfb9562c6fd0e318654f9e05c095bfeb94b0450ab1b07  ./linux-arm64/libxr_frameport_timefix.so
+2cc16b90abcd3d359f1658c581172bd650017bf2725e24268915f50904c000ec  ./linux-arm64-bin/fp_roomscan
 b10b3a5c10c3339fc63fd9f6cb4d01ea29be11a863d0ebad1389ea69fd471940  ./linux-arm64-bin/fp_venc
+00c2dead0fd7497929833467f0e55699d57d26be1b85dce35402993852f7b111  ./roomscan/ceiling.png
+c1962de31ed2810d31c760cf9ee63316ac2b8c9528ccbcd9299ebf5ba39b2995  ./roomscan/done.png
+0dfaea4c68979b0a45a9fef06fdf1a92468ffc8f46f80a3a014fce1d805972d5  ./roomscan/failed.png
+f2bae84f1d1512f87b25e688acdddb29b3f360f3f0d0cd4fdeeb741a79e7b19a  ./roomscan/finish_00.png
+9be7720c45f162e99813cb9a7a03e026fed53b41f06637b30ded309eeac91759  ./roomscan/finish_01.png
+220d699f879b3a8669cfaf4dc714496e8c1db7e7878e7cd12b1a41aec9b62faa  ./roomscan/finish_02.png
+42871b440b77449d4fe41be1c809a930148a874caa8bc92b13b5d25bb6effa83  ./roomscan/finish_03.png
+a470f62624c94ed6791cc7ee03066e1ffb0a676d520658a0a8b02a6af1605b3b  ./roomscan/finish_04.png
+195ff1c649fd9b42bfa6eea29c43a8b67116fd6ffe9b0fe53dcbdb1074bd34fa  ./roomscan/finish_05.png
+a45accab86b02d7b78327a17b84a6fea543ecc549282055dd3182c686fc2b1b8  ./roomscan/finish_06.png
+b88d6c590ea839a9d11b3a4de8c3effb39752f7114318966fddae09995e0fd37  ./roomscan/finish_07.png
+4a3615db26cf765b855a997be3e067aed58464894dab4a6700fdec5c2b854501  ./roomscan/finish_08.png
+f532a83044e707c66dbc74787ce7b844890bc05829d3e9c8f7e33dae9db246a5  ./roomscan/finish_09.png
+ffce61a9f13bbb250fad3582396a5bec82a1bad1d585b7ef9b8f65d343806b26  ./roomscan/finish_10.png
+4a63772adacb31004749ab04b592076bd36cda61eef52f59037d5abdc9e527db  ./roomscan/finish_11.png
+f373e7021cfce0d1078227f473425a10035ee426102b78f13e0fea4833b736d5  ./roomscan/finish_12.png
+1147391822be3f1aa5351374b8fd9ec85f8b5ce40e3cb9f3146d778e6fbc652a  ./roomscan/floor.png
+eb3c8b55a9dbafa030797ca9f06a22c3ee3bbef96cb7adea26d433ebad43d43f  ./roomscan/look_00.png
+6ba965ff6d22a469c558f2a68229bd2ff48fc28badb95889ca245310d1dd3e96  ./roomscan/look_01.png
+0a11cec25ebc76fe11d505d1f2ec162c9b4a6754393065800e73b1f81e2d94c8  ./roomscan/look_02.png
+fa5a4c94d20af56797b9fcc111148767847a6633ade9217cab373de232efad90  ./roomscan/look_03.png
+e80fa493e380fba39084be2ee62859adcff4e39aa66566abee10a4d6339c52e9  ./roomscan/look_04.png
+133617f0d8d1e69c37408aac80033f71856b592b62e3b780cc12b446bd974680  ./roomscan/look_05.png
+d5dd296ff23641c6973c57ac139147e99c7b783316ab60537adb2155dd196880  ./roomscan/look_06.png
+c08570aa78f966ae937b2e21d0bad887c5352fbca56aa579a2a7ef8541fb96ad  ./roomscan/look_07.png
+3767e7db5fb6babc872fa62c42604f749c65936717d332101745b201cd450cd5  ./roomscan/look_08.png
+2924dc65e5c497545340209edc16060e12e1834d11af6871d1c1baa50b7b2562  ./roomscan/look_09.png
+cd0150dfc10b2aea39403c74eff72fd05fb0111178ef39b4c98657a6d16d105e  ./roomscan/look_10.png
+011355e412f73ade3896e9037490e607c4365d0cf8ceb807d236bf68b414d3ed  ./roomscan/look_11.png
+1b8b47ffb47568d540921f065b5958eeb44a6489498d58e0f33f5d1f535154e2  ./roomscan/look_12.png
+926c7bc6a103adee5b9bf938f5d4e39095ab77fd6270b5301be3b0428edd9ae6  ./roomscan/start.png
 c2c70f4af1a5c3e6089dff1130161dd417f8044f99ec639eeecf1083930aab16  ./win-x64/fp_oculushmd.exe
 60ebc5fea05b8945082e2ca8b9f2eb74616012a26eb50133af273dff0fcddc42  ./win-x64/fp_vrsettings.exe
@@ -1,8 +1,8 @@
 {
-  "revision": 8,
+  "revision": 11,
  "runtime_sha256": "456e912c75cd389abcf6a63bc80e2a53bdc334371d00b200c93680388ae955e2",
  "files": {
-    "libstagefrighthw.so": "141de01f0d40b97d4f9a720db5ab8ea442f6aa35db5272048899292884994a1c",
+    "libstagefrighthw.so": "55aae57d292e9536701f2f8a9dbaf1edcfdd766c5748d07a34da2f5ef197f212",
    "podman.py": "529ea35d5d82474afe9e09ad1216d269317f56dd24a05fb100fced52b7b4dbca",
    "media_codecs_frameport.xml": "46c3dcad2c43cc30bea3b3680b362ed84a99c15d60714bbbbb422c80ecf90405",
    "COPYING.FFmpeg": "b634ab5640e258563c536e658cad87080553df6f34f62269a21d554844e58bfe"
@@ -8,19 +8,21 @@ notes: 'Native OpenXR GLES video player. 360 theatres/videos (equirect2 layers,
 details: 'Settings: equirect_emul (GLES worker draws 360 layers into a projection layer), stable_local, focus_hold,
  scale 0.75; frame.swapchain_limit for its 7680x3840 theatre swapchains. Its hardware decoding mode (Java MediaCodec,
  Vr4pMediaPlayer; its own FFmpeg is the software path) gets the Frame''s video hardware with frame.hw_video_decode
-  (added 2026-10-09, not yet checked in the headset).'
+  (added 2026-10-09, not yet checked in the headset). swapchain_pool shares extra GLES panel images to avoid the
+  runtime swapchain count cap (#387); host-tested only, menu interaction needs a headset check.'
 tested_version: 2.0.22
 engine: Other
 xr: OpenXR
 frame:
 - frame.hw_video_decode
 adapter:
+  swapchain_pool: 1
  equirect_emul: 1
  stable_local: 1
  focus_hold: 1
  scale: 0.75
 verified:
  date: '2026-10-01'
-updated: '2026-10-10'
+updated: '2026-10-18'
 min_app: 0.12.1
 source_hint: 4XVR Video Player
@@ -0,0 +1,16 @@
+package: com.And7Limited.Hitstream
+title: Hitstream
+status: works
+tested_version: 2.06bQuest
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+adapter:
+  controller_models: 1
+  haptic_fix: 1
+notes: Fitness rhythm game; uses controller models and haptics fix.
+verified:
+  date: '2026-10-12'
+  known_good_sha256: ecc9e2eee79073ae97ad5d3f70c21e8f049f899f21b51dfd541430bb7dd04cac
+source_hint: Hitstream
@@ -0,0 +1,29 @@
+package: com.BaggyG.JKXR_Companion_App
+title: JKXR_Companion_App
+status: unknown
+notes: 'JKXR''s companion app: it manages JKXR''s mods and start options in /sdcard/JKXR. On the Frame each game
+  has its own /sdcard, so this recipe shares JKXR''s folder with it (device.shared_folder). Install JKXR first.
+  Starting JKXR from the companion app can''t work (each game runs in its own container): start JKXR from Steam.
+  Shared folder not yet confirmed by a player (GitHub 440).'
+tested_version: '1.0'
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-20'
+  known_good_sha256: 75ee0487ed6253a682b388df7ff06c6f7f35b2ce1b5a71341aed815bf6d60b34
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 109
+  issue: 440
+source_hint: jkxrcompanion_115meta
+shared_folder:
+  game: com.drbeef.jkxr
+  folder: JKXR
+min_app: 1.3.1
@@ -0,0 +1,23 @@
+package: com.BanzaiStudios.GAZZLERS
+title: GAZZLERS
+status: unknown
+notes: Stopped at start with "Current Platform is not supported" (GitHub issue 404); the recipe makes the game take
+  its Meta Quest path. The fix builds and applies offline; not yet checked on the Frame.
+details: The game chooses between its Meta Quest and PICO code from SystemInfo.deviceModel and throws for any other
+  device; Lepton's Android reports Valve Lepton (write-once ro.product properties). frame.gazzlers_quest_platform
+  makes PlatformDeterminer.GetAndroidPlatform return Platform.Meta.
+tested_version: 1.4.1.7857
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.gazzlers_quest_platform
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-23'
+  issue: 404
+updated: '2026-10-23'
+source_hint: Gazzlers
@@ -0,0 +1,26 @@
+package: com.EgerterSoftware.MovieDeckforPlex
+title: Movie Deck for Plex
+status: works
+notes: Works out of the box and absolutely fantastically so.
+tested_version: '6.4'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.meta_permissions
+- frame.unity_text_input
+- frame.hw_video_decode
+device:
+- device.text_input_window
+adapter:
+  controller_models: 1
+  haptic_fix: 1
+  scene_emul: 1
+verified:
+  date: '2026-10-20'
+  known_good_sha256: 397912f98ded90df0dabeb51d097c56de9b70ef99674303fa0efba84d43c4df0
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261015.6141207'
+  agent: 109
+  issue: 435
+source_hint: Movie Deck For Plex
@@ -0,0 +1,20 @@
+package: com.Iconik.LittleNightmaresVR
+title: Little Nightmares VR
+status: works
+tested_version: 1.0.31
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.hw_video_decode
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-18'
+  known_good_sha256: 171e586bf35ee4494874c6f2c37fb734f718e5b81744b2df9095919398d70839
+  app: 1.2.1
+  overport_cli: 1.2.5
+  frame_build: '20261015.6141207'
+  agent: 96
+  issue: 421
+source_hint: Little Nightmares VR- Altered Echoes
@@ -0,0 +1,19 @@
+package: com.MoonMonsterStudios.SpaceControl
+title: SpaceControl
+status: works
+tested_version: 1.1.2
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-20'
+  known_good_sha256: 60b900a0a73a693426b85d81a489c63fab6cc959939f80efd29632945e0ce559
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261015.6141207'
+  agent: 109
+  issue: 447
+source_hint: Space Control
@@ -0,0 +1,23 @@
+package: com.MyronSoftware.Deisim
+title: Deisim
+status: works
+tested_version: 1.58.543
+engine: Unity
+xr: OpenXR
+frame:
+- frame.bhaptics_permission
+- frame.photon_voice_audio_route
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-21'
+  known_good_sha256: 91bc0a28ff7ca22a877f4f920984c3a6a2c91828a2bccff0c5eb4affb4dc13ae
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261015.6141207'
+  agent: 109
+  issue: 462
+source_hint: Deisim
@@ -12,6 +12,7 @@ overport_extra:
 - patch_force_passthrough
 adapter:
  scene_emul: 1
+  scene_hide_bounds: 1
 device:
 - device.text_input_window
 verified:
@@ -22,4 +23,4 @@ verified:
 frame:
 - frame.meta_permissions
 - frame.unity_text_input
-updated: '2026-10-15'
+updated: '2026-10-17'
@@ -0,0 +1,20 @@
+package: com.ORIGAMEDIGITAL.UmurangiGenerationVR
+title: Umurangi Generation VR
+status: issues
+notes: The game freezes after taking a photo, while it saves it, which makes it hard to play.
+tested_version: '1.163'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-22'
+  known_good_sha256: c4dfe227c3e33e611f9a4b8ee542912c0891fe600a7d32e56cbe84b0524ec8d9
+  app: 1.3.0
+  overport_cli: 1.2.5
+  issue: 472
+source_hint: com.ORIGAMEDIGITAL.UmurangiGenerationVR.output
@@ -0,0 +1,19 @@
+package: com.Oculus.FirstContact
+title: First Contact
+status: works
+notes: '32-bit only, runs through FramePort''s 32-bit bridge (experimental). Played in the headset
+  (GitHub #489); the headless launch test ends early, which is expected for the bridge.'
+tested_version: '1.12'
+engine: Unreal
+xr: VrApi
+frame:
+- frame.a32_bridge
+verified:
+  date: '2026-10-25'
+  known_good_sha256: 7b971d70af24ec554994e59f65b2568c5b86a94df04e962699051f267d6358b7
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261022.6153909'
+  agent: 109
+  issue: 489
+source_hint: com.Oculus.FirstContact
@@ -6,7 +6,10 @@ engine: Unreal
 xr: OpenXR
 status: works
 notes: Very large data set (~31 GiB). Built with disable_space_warp.
-details: Reported working on Pico 4 with overport runtime 3.0.x. 83 OBB/pakchunk files (~32 GB).
+details: 'Reported working on Pico 4 with overport runtime 3.0.x. 83 OBB/pakchunk files (~32 GB): besides main and
+  patch.0, 81 patch.pakchunk<N>-Android_ASTC.com.Sanzaru.Wrath2.obb files (~27 GB). Without them the game hangs at
+  engine start-up (GitHub #471); up to FramePort 1.3.0 they are only sent from a com.Sanzaru.Wrath2 folder next to
+  the APK, not loose next to it.'
 overport_extra:
 - patch_disable_space_warp
 alt_overport:
@@ -0,0 +1,24 @@
+package: com.TeravisionGames.OrcsMustDie
+title: 'Orcs Must Die: By The Blade'
+status: works
+notes: Perfect at v151
+tested_version: 1.0.164237
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+frame:
+- frame.unreal_ovrp_entrypoints
+- frame.hw_video_decode
+adapter:
+  equirect_emul: 1
+  haptic_fix: 1
+verified:
+  date: '2026-10-21'
+  known_good_sha256: 11e5d45587277a5edea8be4862c7af19aa5c38445676607c541bc1e471f473ff
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261015.6141207'
+  agent: 109
+  issue: 453
+source_hint: OrcsMustDie
@@ -5,16 +5,20 @@ source_hint: Assassins Creed Nexus VR
 engine: Unity
 xr: OpenXR
 status: works
-notes: FrameBridge turns its upside-down UI panels upright (flip emulation, in place since FramePort 1.2.0). Ubisoft
-  login may not work.
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
+notes: 'FrameBridge turns its upside-down UI panels upright (flip emulation, in place since FramePort 1.2.0). Ubisoft
+  login may not work. frame.unity_text_input added from detection (not headset-verified); no device.text_input_window:
+  its Android window took the controllers'' input (owner, 2026-10-23).
+
+  Runs as a Quest 3 with the Vulkan panel pool (swapchain_pool): as a Quest 3 it switches to larger eye images after
+  the intro, which the Frame''s swapchain limit refused before the pool (GitHub #424; checked headless 2026-10-23,
+  FramePort 1.4.0).'
 details: Ubisoft online login may not work. Data folder holds raw assets (start0..2, .climb, bundles), not .obb
  files; install to obb as-is.
 overport_extra:
 - patch_ac_nexus_no_appsw_90
 frame:
 - frame.unity_text_input
-device:
+frame_remove:
 - device.text_input_window
 verified:
  date: '2026-09-28'
@@ -23,5 +27,7 @@ verified:
  known_good_sha256: 89644a12bf8df956fa3d3a9a40540ba9e1fb62f63494714a05c9f05984383ac8
  no_appsw_90: '2026-10-02, OVRPort 1.2.5 (owner: 90 Hz felt better than 72 Hz; same known issues)'
  flip_in_place: '2026-10-14, owner in the headset: launch warnings and tutorial pop-ups upright (GitHub #138)'
-updated: '2026-10-15'
-min_app: 1.2.0
+updated: '2026-10-25'
+min_app: 1.4.0
+adapter:
+  swapchain_pool: 1
@@ -0,0 +1,23 @@
+package: com.XrealGames.Zc15
+title: Zero Caliber 2
+status: works
+tested_version: 2.0.1173-S-80237
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+frame:
+- frame.hw_video_decode
+- frame.unreal_noreserve
+adapter:
+  haptic_fix: 1
+  fixed_resolution: 1
+verified:
+  date: '2026-10-25'
+  known_good_sha256: 48a6fc11f64aba9a9ee95863cb601d64ad8b54eba9034d5b05097f5d3ee00b57
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261022.6153909'
+  agent: 109
+  issue: 492
+source_hint: Zero Caliber 2
@@ -0,0 +1,11 @@
+package: com.ZarApps.PianoVision
+title: PianoVision
+status: unsupported
+notes: Starts, but needs camera hand tracking (Android games on the Frame only get hands built from the controllers)
+  and USB MIDI from a piano, which the Frame's Android container doesn't pass through.
+tested_version: 3.0.8
+engine: Unity
+xr: OpenXR
+verified:
+  date: '2026-10-20'
+  issue: 297
@@ -0,0 +1,22 @@
+package: com.astrobotquest.vrhost
+title: Astro VR Host
+status: works
+notes: Runs your own Astro Bot Rescue Mission files (the unpacked CUSA12392 folder, not the .pkg). With the Files
+  tab, copy the folder to Android/data/com.astrobotquest.vrhost/files/games/ in the game's storage and add Android/data/com.astrobotquest.vrhost/files/vrhost.txt
+  with the lines language=<your language, e.g. en-US> and refresh_rate=80. Set FoV to 100% in the game.
+details: 'Tested with AstroQuest v0.23 (https://github.com/bigmak94/AstroQuest). The port caps the resolution at
+  1440 px per eye; vrhost.txt can''t change that. Other vrhost.txt options: https://github.com/bigmak94/AstroQuest/blob/main/README-QUEST-VR.md#installing-and-running'
+tested_version: '0.23'
+engine: Other
+xr: OpenXR
+adapter:
+  refresh_rate: 80.0
+verified:
+  date: '2026-10-22'
+  known_good_sha256: c2e13ab155b947c0037362635bd34112c16b69b804af82b347021f2261ef5bfb
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261015.6141207'
+  agent: 109
+  issue: 464
+source_hint: AstroQuest
@@ -0,0 +1,24 @@
+package: com.baobab.invasion
+title: Invasion
+status: works
+tested_version: 1.0.250
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_oculus_check
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-25'
+  known_good_sha256: 06c8f94556eb8d8d6679e089d2429e70b45148aba7ad0d47c42bd1de932cbdc1
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261022.6153909'
+  agent: 109
+  issue: 490
+source_hint: com.baobab.invasion
@@ -16,6 +16,7 @@ frame:
 - frame.hw_video_decode
 - frame.unity_text_input
 adapter:
+  fixed_resolution: 1
  sync_guard: 1
  surface_native: 1
  fade_quad: 1
@@ -26,6 +27,6 @@ verified:
  overport_cli: 1.2.3
  overport_runtime: 3.4.3-23204ea
  known_good_sha256: 796d1cab08f614d72c50d9702974c719c0908f5de91183cfe02d1fd5eb09551a
-updated: '2026-10-15'
-min_app: 1.1.0
+updated: '2026-10-18'
+min_app: 1.2.2
 source_hint: Batman- Arkham Shadow
@@ -0,0 +1,26 @@
+package: com.com2usroca.Darksword
+title: Darksword
+status: works
+tested_version: 1.6.2.11
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+frame:
+- frame.unreal_skip_obb_check
+- frame.bhaptics_permission
+- frame.unreal_ovrp_entrypoints
+- frame.hw_video_decode
+adapter:
+  haptic_fix: 1
+  scale: 1.5
+foveation: tracked
+verified:
+  date: '2026-10-18'
+  known_good_sha256: 47f9968e5fac70a5873b996a4d7b9c01d42d2f0cc1d9dc24013eb2e3b08a8a8e
+  app: 1.2.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 96
+  issue: 410
+source_hint: darksword
@@ -0,0 +1,19 @@
+package: com.drbeef.jkxr
+title: JKXR
+status: issues
+notes: Tested in the early part of Jedi Outcast. Two players report stutters and freezes after 3-15 minutes of play
+  (under investigation in issue 441).
+tested_version: 1.1.28
+engine: Other
+xr: OpenXR
+frame:
+- frame.tbxr_vendor
+verified:
+  date: '2026-10-20'
+  known_good_sha256: 771e48b22d3a558ea11869aa1e9070b11908b17ab47a9e8866769bb67efc30a5
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 109
+  issue: 441
+source_hint: QuestAPKs
@@ -0,0 +1,23 @@
+package: com.drbeef.questzdoom
+title: QuestZDoom
+status: works
+notes: 'Needs a WAD: put it into QuestZDoom/wads in the game''s storage (Files tab) and create QuestZDoom/qzdoom.ini
+  with the lines "[IWADSearch.Directories]" and "Path=/sdcard/QuestZDoom/wads" (commandline.txt alone is not
+  enough). Smooth past 15 minutes in the headset with gl_error_clear (issue 237).'
+details: GZDoom on OpenGL ES with Team Beef's OpenXR code. The game leaves GL_INVALID_ENUM pending every frame; the
+  runtime's GL check failed on it at the first swapchain and its GL interop then created about 100 GPU objects a
+  second that were never freed (8,000 after 75 s headless). Frames slowed down over the minutes, and in a player's
+  session the GPU driver crashed after 6 minutes and the Frame restarted. gl_error_clear clears the errors before
+  FrameBridge calls the runtime; GPU objects then stay flat (headless, 2026-10-24).
+tested_version: 1.6.2
+engine: Other
+xr: OpenXR
+frame:
+- frame.tbxr_vendor
+adapter:
+  gl_error_clear: 1
+verified:
+  date: '2026-10-25'
+  issue: 237
+updated: '2026-10-25'
+source_hint: questzdoom-1.6.2
@@ -0,0 +1,24 @@
+package: com.fasttravelgames.solero
+title: Solero
+status: works
+tested_version: 1.00.109160
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+frame:
+- frame.gms_platform_version
+- frame.unreal_ovrp_entrypoints
+- frame.hw_video_decode
+adapter:
+  equirect_emul: 1
+  haptic_fix: 1
+verified:
+  date: '2026-10-20'
+  known_good_sha256: 2d19ac1ed61cc12d0976155fbb6697fb87ec5d60c6601fe1598c965bc3e48377
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261015.6141207'
+  agent: 109
+  issue: 448
+source_hint: Action Hero
@@ -0,0 +1,36 @@
+package: com.fgol.HungrySharkEvolution
+title: Hungry Shark Evolution
+status: works
+notes: Phone game (2D). Tested with 14.6.0 installed from an .xapk bundle; cloud sync and Google services don't work.
+tested_version: 14.6.0
+engine: Unity
+xr: '?'
+overport_remove:
+- patch_copy_libraries
+- patch_copy_ovrplugin_vrapi
+- patch_replace_icon_label
+- patch_fix_min_android_sdk
+- patch_generate_config
+- patch_remove_localized_names
+- patch_clean_up_frida
+- patch_oculus_unity
+- patch_oculus_unreal
+- patch_vr_metadata
+- patch_launcher_entry
+- patch_remove_uses_library
+- patch_fix_unreal_crash
+- patch_meta_xr_audio
+- patch_mark_as_debuggable
+- patch_mark_allow_backup
+frame:
+- frame.unity_text_input
+- frame.hw_video_decode
+verified:
+  date: '2026-10-25'
+  known_good_sha256: d912bc914ea396f19e51d1b35777232cb0a4225a5f288870916744fcaacba9b1
+  app: 1.3.1.dev675
+  overport_cli: 1.2.5
+  frame_build: '20261022.6153909'
+  agent: 123
+  issue: 486
+source_hint: Hungry+Shark+Evolution_14.6.0_APKPure
@@ -0,0 +1,24 @@
+package: com.garage.drumsrock
+title: Drums Rock
+status: works
+notes: Let's Rock!
+tested_version: '1.401'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+  scale: 2.0
+verified:
+  date: '2026-10-18'
+  known_good_sha256: 61d724ce51cc5bc17c7f942803922e8606fc5d60bc4ec5134f06754c5172c7eb
+  app: 1.2.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 96
+  issue: 409
+source_hint: drums rock
@@ -0,0 +1,16 @@
+package: com.gevr.port
+title: GoldenEye VR
+status: issues
+notes: No sound; otherwise works great.
+tested_version: 0.5.8
+engine: Other
+xr: OpenXR
+frame:
+- frame.sdl_clipboard
+verified:
+  date: '2026-10-18'
+  known_good_sha256: 5bd0d5ad71368178f8478193c215459a670d22ca6828bb155d76c5255908759b
+  app: 1.2.1
+  overport_cli: 1.2.5
+  issue: 412
+source_hint: GoldenEye-VR-v0.5.8
@@ -5,8 +5,10 @@ source_hint: NOPE CHALLENGE
 engine: Unreal
 xr: OpenXR
 status: works
-notes: Meta XR Audio telemetry patch + nodebug. MR "Reality Breach" mode unavailable.
-details: The MR 'Reality Breach' mode needs passthrough; standard VR mode used.
+notes: "Meta XR Audio telemetry patch + nodebug. MR mode: needs a scanned room."
+details: The MR 'Reality Breach' mode needs passthrough and a room; standard VR mode was verified.
+adapter:
+  scene_emul: 1
 alt_overport:
 - patch_remove_unreal_force_quit
 frame:
@@ -0,0 +1,26 @@
+package: com.mrf.kluge.SynthRiders
+title: SynthRiders
+status: works
+tested_version: 3.6.7a2
+engine: Unity
+xr: OpenXR
+frame:
+- frame.meta_permissions
+- frame.bhaptics_permission
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  controller_models: 1
+  haptic_fix: 1
+  scene_emul: 1
+verified:
+  date: '2026-10-25'
+  known_good_sha256: ef1792f577697c5fa355a61adfc02e9d8a50fe4ddfec0357398bd5867df42f17
+  app: 1.3.1.dev703
+  overport_cli: 1.2.5
+  frame_build: '20261022.6153909'
+  agent: 125
+  issue: 494
+source_hint: com.mrf.kluge.SynthRiders
@@ -0,0 +1,19 @@
+package: com.mrf.tvb.laser_dance
+title: Laser Dance
+engine: Unity
+xr: OpenXR
+status: works
+notes: Mixed reality laser obstacle course; requires spatial data and room layout emulation (scene_emul=1). frame.meta_depth_occlusion keeps close lasers visible (its asset fixes only for the build they were made for); tested version not recorded (PR #246).
+details: Mixed reality game that projects lasers across your room; needs Meta scene emulation and spatial data permission.
+adapter:
+  controller_fix: 1
+  haptic_fix: 1
+  scene_emul: 1
+  passthrough_emul: 1
+frame:
+- frame.meta_permissions
+- frame.meta_depth_occlusion
+- frame.unity_scene_active_rooms
+- frame.unity_text_input
+min_app: 1.2.2
+updated: '2026-10-18'
@@ -0,0 +1,25 @@
+package: com.onehamsa.underdogs
+title: UNDERDOGS
+status: works
+tested_version: 1.5.4.12573
+engine: Unity
+xr: OpenXR
+frame:
+- frame.bhaptics_permission
+- frame.photon_voice_audio_route
+- frame.unity_text_input
+- frame.hw_video_decode
+device:
+- device.text_input_window
+adapter:
+  controller_models: 1
+  haptic_fix: 1
+verified:
+  date: '2026-10-23'
+  known_good_sha256: 0b98b5c71855341abc2ad942dbbdd920a6d362f7fee25a598b1a6ca1248fb27a
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261022.6150929'
+  agent: 109
+  issue: 474
+source_hint: com.onehamsa.underdogs
@@ -18,11 +18,12 @@ engine: Unity
 xr: OpenXR
 frame:
 - frame.unity_text_input
+- frame.pojlib_connection
 device:
 - device.text_input_window
 lepton_env:
  LEPTON_ENV_LIBGL_NOERROR: '1'
 verified:
  date: '2026-10-05'
-updated: '2026-10-05'
+updated: '2026-10-23'
 source_hint: QuestCraft
@@ -0,0 +1,27 @@
+package: com.simpsonsHitAndRun.vr
+title: Simpsons Hit and Run VR
+status: works
+notes: 'Needs the port''s game data: after installing, copy the "SimpsonsHitRun" folder (see the port''s GitHub
+  instructions) into the game''s storage with FramePort''s Files tab. In-game settings: Vehicle lights off, Enhanced
+  materials off, CSM shadows off (otherwise it crashes when starting a new game), Render scale 150% at 120 Hz.'
+details: 'Tested with v1.2 of https://github.com/kote2345/The-Simpsons-Hit-and-Run-VR. Vehicle lights break entities
+  and Enhanced materials break textures. Render scale above 150% can''t keep up at 120 Hz (200% runs at about 100
+  fps). Optional: set the in-game VR tab''s mode to VR to make the menus more comfortable. While paused, a long
+  black texture can appear from the head when looking up; it goes away when the pause menu closes. Contributed in
+  issues 443 and 461.'
+tested_version: '0.93'
+engine: Other
+xr: OpenXR
+frame:
+- frame.sdl_clipboard
+adapter:
+  refresh_rate: 120.0
+verified:
+  date: '2026-10-22'
+  known_good_sha256: e406a5da1b2f99fc3a9f95af44f458598ad52d1296a8c577bf1f8e2343738ff2
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261015.6141207'
+  agent: 109
+  issue: 461
+source_hint: SimpsonsHitRun_1.2
@@ -0,0 +1,22 @@
+package: com.stalwart.barbaria
+title: Barbaria
+status: works
+tested_version: 1.10.1.22383.158.OBERON.Quest.release
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+  scale: 2.0
+verified:
+  date: '2026-10-18'
+  known_good_sha256: e0cd063fc14a2bea5503bf63cf83246527b286915f05186ca5a2c42ce6e7d75a
+  app: 1.2.1
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 96
+  issue: 418
+source_hint: barbaria
@@ -0,0 +1,23 @@
+package: com.wnas.eternalstarlight
+title: Eternal Starlight
+status: issues
+notes: Voice commands do not appear to work.
+tested_version: 1.7.404
+engine: Unity
+xr: OpenXR
+frame:
+- frame.bhaptics_permission
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-24'
+  known_good_sha256: 37a79332a89c974971df30a38adbeafdc2466c3163348ab4215ff93014d5be12
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261022.6153909'
+  agent: 109
+  issue: 479
+source_hint: Eternal Starlight
@@ -1,13 +1,14 @@
 package: com.zenstudios.PFXVRQuest
 title: Pinball FX VR
 status: issues
-notes: Plays; mixed reality mode not working yet. Space warp off (fewer stutters).
+notes: "Plays; space warp off (fewer stutters). MR mode: needs a scanned room."
 tested_version: '1.9'
 engine: Unreal
 xr: OpenXR
 alt_overport:
 - patch_remove_unreal_force_quit
 adapter:
+  scene_emul: 1
  equirect_emul: 1
  hide_space_warp: 1
 verified:
@@ -0,0 +1,24 @@
+package: dev.melee.game
+title: Xelee
+status: unknown
+notes: 'The app opens a flat launcher (MeleeActivity) that starts the VR part (MeleeXrActivity): "Show the app''s
+  Android window" is on so that launcher can be seen in the headset; without it Lepton runs the app headless, the
+  launcher waits invisibly and OpenXR never starts. Keep the Vulkan library rename disabled: the engine (Aurora/Dawn
+  WebGPU) builds the name libvulkan.so from two pieces, so the rename made it ask for "libfp_vkn.so" (GitHub #475).
+  The VR part is not yet checked on the Frame.'
+details: 'Vulkan (Dawn) loads and precompiles all 6080 pipelines in about 34 s with the rename off; the launch then
+  stays in the 2D launcher, so no OpenXR call is made (GitHub #475).'
+tested_version: 0.1.0-beta
+engine: Other
+xr: OpenXR
+frame:
+- frame.meta_permissions
+- frame.sdl_clipboard
+frame_remove:
+- frame.vk_sanitize
+device:
+- device.text_input_window
+adapter:
+  scene_emul: 1
+updated: '2026-10-24'
+source_hint: Xelee-Quest-arm64
@@ -0,0 +1,26 @@
+package: games.b4t.epicrollercoasters.oculus
+title: Epic Roller Coasters
+status: works
+notes: You may need to restart the game for the camera to be placed in front of the menu.
+tested_version: 8.36.04
+engine: Unity
+xr: OpenXR
+overport_extra:
+- patch_disable_space_warp
+frame:
+- frame.bhaptics_permission
+- frame.vivox_audio_route
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-21'
+  known_good_sha256: 5760a135be2e2df634c78eae4f9d177b2a95a9da26a4739fdd6e1f5159ed9320
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261015.6141207'
+  agent: 109
+  issue: 456
+source_hint: Epic Roller Coasters
@@ -0,0 +1,16 @@
+package: io.port0r.houseofthedead
+title: 'Port0r: House of the Dead VR'
+status: works
+tested_version: 0.1.1
+engine: Other
+xr: OpenXR
+as_is: true
+verified:
+  date: '2026-10-25'
+  known_good_sha256: 699a25d696df8af8669feee11037a2c1c56f15a8f9359b1f8d17897aa841b197
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261020.6124238'
+  agent: 109
+  issue: 496
+source_hint: Port0r-HouseOfTheDeadVR-v0.1.1-quest3
@@ -0,0 +1,16 @@
+package: io.port0r.segarally
+title: 'Port0r: Rally VR'
+status: works
+tested_version: 0.2.6
+engine: Other
+xr: OpenXR
+as_is: true
+verified:
+  date: '2026-10-25'
+  known_good_sha256: 186018b96550c3881e4659293d07a2fbe6bb7a962798de1dbf6bcba3a99b9025
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261020.6124238'
+  agent: 109
+  issue: 498
+source_hint: Port0r-RallyVR-v0.2.6-quest3
@@ -0,0 +1,20 @@
+package: io.port0r.timecrisis
+title: 'Port0r: Time Crisis VR'
+status: issues
+notes: Immersive mode shows a black screen (only the arm and gun); the flat and 3D screen modes work
+  (game menu, setup button).
+tested_version: 0.2.2
+engine: Other
+xr: OpenXR
+adapter:
+  refresh_rate: 90.0
+as_is: true
+verified:
+  date: '2026-10-25'
+  known_good_sha256: 4208f5bf16ecc2cfcf3fbb6cb5abf2d632eeffdc3a74115c0b03e861c1bdee43
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261020.6124238'
+  agent: 109
+  issue: 497
+source_hint: Port0r-TimeCrisisVR-v0.2.2-quest3
@@ -0,0 +1,18 @@
+package: io.port0r.timecrisis2
+title: 'Port0r: Time Crisis II VR'
+status: issues
+notes: Gameplay runs well; cut scenes and the title and game-selection screens after inserting coins
+  don't display properly.
+tested_version: 0.1.0
+engine: Other
+xr: OpenXR
+as_is: true
+verified:
+  date: '2026-10-25'
+  known_good_sha256: 3277d77f81fc6ec7e686d2bd74050234dbfb4c90bf3009a1feb027147372aecb
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261020.6124238'
+  agent: 109
+  issue: 495
+source_hint: Port0r-TimeCrisisIIVR-v0.1.0-quest3
@@ -0,0 +1,16 @@
+package: io.port0r.virtuacop
+title: 'Port0r: Cop VR'
+status: works
+tested_version: 0.2.2
+engine: Other
+xr: OpenXR
+as_is: true
+verified:
+  date: '2026-10-25'
+  known_good_sha256: 67e0e5676054b8c7a05d9e835d312d29716437e2166c2ce558b6b9b1782286bf
+  app: 1.3.0
+  overport_cli: 1.2.5
+  frame_build: '20261020.6124238'
+  agent: 109
+  issue: 493
+source_hint: Port0r-CopVR-v0.2.1-quest3
@@ -0,0 +1,21 @@
+package: jp.strippers.punchfit
+title: Punch Fit
+status: works
+tested_version: 1.7.2
+engine: Unity
+xr: OpenXR
+frame:
+- frame.meta_permissions
+- frame.unity_text_input
+adapter:
+  haptic_fix: 1
+  pose_time_fix: 1
+  scene_emul: 1
+  passthrough_emul: 1
+notes: Mixed reality workout arena; composition layer trimming prevents 21+ layer overflow.
+verified:
+  date: '2026-10-12'
+  known_good_sha256: 1a0050272526360542d62e7e6d1fc2daecb765c34378a6fe4ad51568ec550c0d
+source_hint: Punch Fit
+min_app: 1.2.2
+updated: '2026-10-18'
@@ -0,0 +1,20 @@
+package: org.outrun.quest.vr
+title: OutRun Quest VR
+status: unknown
+notes: Needs colour-space support and FrameBridge's space warp (it quits at start without them). Not yet checked on
+  the Frame with both (GitHub #336).
+details: Own engine with OpenGL ES and its own OpenXR loader. It requires XR_FB_color_space (Rec.709; quit with "Rec.709
+  color space unavailable") and Meta's Application SpaceWarp (quit with "AppSW recommended buffers unavailable"); the
+  Frame's runtime offers neither in a usable form. fb_color_space offers the colour-space extension; space_warp_emul
+  offers XR_FB_space_warp with a motion-vector size, serves the motion-vector and depth images as GL textures and
+  removes the space warp info from every frame. Turning space warp off can't help, the game refuses to start without it.
+tested_version: 0.4.25-music-indicators
+engine: Other
+xr: OpenXR
+adapter:
+  fb_color_space: 1
+  space_warp_emul: 1
+verified:
+  issue: 336
+updated: '2026-10-24'
+source_hint: OutRunQuest-VR-v0.4.25-music-indicators-arm64
@@ -1,9 +1,10 @@
 package: org.primedgun.v2
 title: PrimedGun v2
-status: unknown
-notes: 'Without the Vulkan library rename: the game builds the library name from two pieces, so the renamed name didn''t
-  exist ("libfp_vkn.so"), its renderer fell back to OpenGL and VR couldn''t start (GitHub #254). Not yet confirmed in
-  the headset.'
+status: issues
+notes: 'Vulkan via a statically linked Khronos OpenXR loader, which bypasses FrameBridge (the picture jumps).
+  The embedded-loader patch is off for now: with it, the game''s loader and the one FramePort adds call each other
+  until the game crashes at Play (GitHub #254). Keep the Vulkan library rename disabled: this game assembles its
+  library name from two pieces, so renaming it prevented Vulkan from loading and VR could not start.'
 tested_version: 2.0.0-alpha.4
 engine: Other
 xr: OpenXR
@@ -11,5 +12,6 @@ frame:
 - frame.sdl_clipboard
 frame_remove:
 - frame.vk_sanitize
-updated: '2026-10-18'
+- frame.static_openxr_loader
+updated: '2026-10-23'
 source_hint: PrimedGun v2 Quest APK (github.com/iChris4/MetroidPrimePortVR)
@@ -3,9 +3,67 @@
 # "apply and rebuild"; an entry `adapter.<key>=<value>` sets that value (else 1). `severity`: fatal (the game can't
 # run) | error | warning | info. `question`: a symptom only the player sees (play sessions, GUI "Last session"): its
 # fix is offered as that question, never applied on its own. `report: true` = the useful next step is a problem report
-# with diagnostics. Launch tests and real play sessions (agent session_log, `frameport session`) are both matched.
+# with diagnostics. `unless_patch: <patch id>` = not when that patch is in the game's build (a log line that stays
+# the same with the fix in place). Launch tests and real play sessions (agent session_log, `frameport session`) are both matched.
 # Sources: every failure we hit porting 34 games to the Steam Frame (see docs/PLAYBOOK.md).
+# Installed apps fetch this file from GitHub main (every 6 h, like catalog/games) and use each remote signature in
+# place of their bundled one with the same id, unless it names a patch/adapter setting or a field the app doesn't know,
+# or `min_app` (per signature, or top-level for the whole file) is above its version. Optional `updated: 'YYYY-MM-DD'`
+# lets a bundled copy that was changed later win over an older remote one.
 signatures:
+  - id: mr-no-room
+    pattern: 'FrameBridge[^\r\n]*scene: (?:capture requested -> (?:guardian box|using guardian room)|room from guardian|room [^\r\n]*(?:from guardian|configured/default size|box))'
+    severity: info
+    diagnosis: 'The game is using a simple fallback room. Scan your room for mixed reality, or use Frame > Room > Use my play area for walls without furniture. A recorded scan can be imported until headset capture is available.'
+    suggest: []
+  - id: mr-discovery-unsupported
+    pattern: '(?:Unknown proc addr:\s*xrDiscoverSpacesMETA|(?:MRUK[^\r\n]*)?NoRoomsFound)'
+    # discovery reached FrameBridge and found the room (OVRPort's "Unknown proc addr" comes before the shim takes over)
+    unless: 'FrameBridge[^\r\n]*scene: discovery request=\d+ results=[1-9]'
+    severity: warning
+    diagnosis: 'The game cannot discover a Meta room. Enable room layout (adapter.scene_emul), rebuild and reinstall for the updated extension shim, then save a room under Frame > Room.'
+    suggest: [adapter.scene_emul]
+  - id: dynamic-resolution-foveation
+    pattern: 'projection view [01](?: rect change)?:[^\r\n]*rect=(?:[1-9]\d*,\d+|0,[1-9]\d*) '
+    # a rebuilt APK's foveation centring layer re-centres Valve's density map on the submitted rect (#394)
+    unless: 'fixed_resolution: recommended|fdm_centre: pass'
+    severity: info
+    diagnosis: The game submits an offset projection viewport. With Valve foveation, dynamic resolution can move the sharp centre or expose a white edge. A rebuilt APK (Update on Frame) puts the sharp area back on each eye; keeping full resolution may also help for the white edge, increases GPU load and needs the updated adapter and OVRPlugin shim in a rebuilt APK.
+    question: With foveated rendering enabled, was the sharp centre misplaced or was there a white line at the picture edge?
+    suggest: [adapter.fixed_resolution]
+  - id: static-openxr-loader-bypass
+    pattern: 'RuntimeManifestFile::FindManifestFiles - using global runtime file /[^\r\n]*etc/openxr/1/active_runtime(?:\.[A-Za-z0-9_-]+)?\.json'
+    unless: 'FrameBridge[: ]|fp_xrruntime[: ]'
+    severity: warning
+    diagnosis: A Khronos loader loaded the system runtime without FrameBridge. A statically linked loader may bypass the bundled loader chain; analyze again, enable the embedded OpenXR loader patch when detected, then rebuild and reinstall to write its per-game manifest.
+    suggest: [frame.static_openxr_loader]
+  - id: cryengine-init-failed
+    pattern: 'Cry\s*:[^\r\n]*Engine initialization failed![^\r\n]*CrySystem initialization failed'
+    severity: fatal
+    diagnosis: CryEngine's start-up failed (CrySystem initialization), and the crash that follows comes from its shutdown. FramePort 1.3.0 builds of The Climb 1/2 failed like this because a dormant diagnostic layer was linked into CryEngine's renderer; a newer FramePort leaves it out, so update FramePort and press Update on Frame. Otherwise attach the diagnostics zip to a report.
+    report: true
+    suggest: []
+  - id: vrapi-bridge-no-loader
+    pattern: 'OVRPortVrApi: xrInitializeLoaderKHR failed: OpenXR result -7'
+    severity: fatal
+    diagnosis: The VrApi bridge found no OpenXR loader because FrameBridge didn't load (a library it needs is missing from the APK). Dev builds of FramePort before this was fixed left that library out of The Climb 1; update FramePort and press Update on Frame. Otherwise attach the diagnostics zip to a report.
+    report: true
+    suggest: []
+  - id: questcraft-no-java-runtime
+    pattern: 'libjvm\.so[^\r\n]*(?:not found|No such file)'
+    severity: fatal
+    diagnosis: QuestCraft's Java runtime isn't there. QuestCraft downloads it only on Wi-Fi, and the Frame's Android reports its network as Ethernet, so the download was skipped. Rebuild with the pojlib connection fix (frame.pojlib_connection), or unpack QuestCraft's JRE.zip into the game's files/runtimes/JRE with the Files tab.
+    suggest: [frame.pojlib_connection]
+  - id: video-decoder-held-by-steam
+    pattern: 'FramePort: hardware video decoder \S+ in use by:[^\r\n]*steamwebhelper'
+    severity: warning
+    diagnosis: Steam's own interface had the Frame's hardware video decoder open when the game started. Large videos (8K cutscenes, e.g. Batman) then decode in software and play choppy. Restarting Steam, or the Frame, before playing frees it.
+    suggest: []
+  - id: swapchain-limit-reached
+    pattern: 'FrameBridge:\s+xrCreateSwapchain [^\r\n]*\bresult=-10\b'
+    severity: error
+    diagnosis: The Frame runtime reached its swapchain count limit (about 15 live swapchains per session), not necessarily a memory limit. Extra menus or video panels may close or stay gray. A game may also stop drawing when a new set of eye images is refused (e.g. AC Nexus with the Quest 3 identity). Updated FramePort builds provide Share panel images (swapchain limit), for GLES and Vulkan apps (panels share one or two runtime images, leaving room for the rest).
+    suggest: []
  - id: quest2-headset-identity
    pattern: 'venderId[^\r\n]*systemName Oculus Quest2'
    severity: info
@@ -75,7 +133,7 @@ signatures:
  - id: no-launcher
    pattern: 'APP_ACTIVITY is empty'
    severity: fatal
-    diagnosis: 'Nothing starts: Lepton found no entry point in the app (an activity with category LAUNCHER).'
+    diagnosis: 'Nothing starts: Lepton found no entry point in the app (an activity with category LAUNCHER; one on an activity-alias alone does not count). Rebuild with the launcher fix (frame.launcher) and reinstall.'
    suggest: [frame.launcher]
  - id: linux-x86-no-fex
    pattern: '(cannot execute binary file: Exec format error|exec format error)'
@@ -87,6 +145,13 @@ signatures:
    severity: fatal
    diagnosis: 32-bit-only APK (e.g. a Gear VR or Oculus Go game). The Steam Frame has no 32-bit ARM support; FramePort's 32-bit bridge translates the game (experimental).
    suggest: [frame.a32_bridge]
+  - id: missing-split
+    pattern: 'INSTALL_FAILED_MISSING_SPLIT'
+    severity: fatal
+    diagnosis: Only the base APK of a split app was installed (the base requires its split APKs). Add the whole app
+      bundle (.xapk, .apks, .apkm or .apkx) or the folder with all its split APKs instead; FramePort merges them into
+      one APK. Then install the game again.
+    suggest: []
  - id: a32-jit-overflow
    pattern: 'a32: block at 0x[0-9a-f]+ overflowed the code buffer'
    severity: fatal
@@ -94,11 +159,40 @@ signatures:
      interpreter, for example OpenSSL's ARMv8 SHA-1 code in Pinball FX2 VR. Fixed in newer FramePort versions;
      update FramePort and rebuild the game ("Update on Frame").
    suggest: [frame.a32_bridge]
+  - id: a32-video-ndk
+    pattern: 'AndroidMediaNDK could not load symbol AMedia\w+|GetDirectBufferAddress: buffer at 0x[0-9a-f]+ is outside the guest''s reach'
+    severity: error
+    diagnosis: A 32-bit game on the bridge can't play its videos through Unity's video player (Ghost Giant's intro
+      stays black). Older bridges lacked the NDK media functions (libmediandk), and Unity's Java fallback hands the 32-bit
+      code decoder buffers it can't reach. Fixed in newer FramePort versions; update FramePort and rebuild the game
+      ("Update on Frame").
+    suggest: [frame.a32_bridge]
  - id: android-too-new
    pattern: '(NoClassDefFoundError|ClassNotFoundException|NoSuchMethodError)\b.*(Landroid/window/|android\.window\.|(storeStoreFence|loadLoadFence)\(\)V in class Ljava/lang/invoke/VarHandle)'
    severity: fatal
    diagnosis: The game needs a newer Android than the Frame has, so it can't run yet. It calls Android 12/13+ classes (android.window.*, VarHandle fences) that the Frame's Android 11 (API 30) container lacks (for example minSdk 34 apps); nothing to patch until Valve updates Lepton's Android.
    suggest: []
+  - id: system-library-missing
+    # GitHub #484 (YouTube VR): OVRPort's patch_remove_uses_library also drops <uses-library> entries for libraries
+    # Lepton has; the classes of patches/frame/system_libraries.LEPTON_LIBRARIES then can't be found
+    pattern: '(ClassNotFoundException|NoClassDefFoundError)\b.*\bL?(org[./]apache[./]http[./]|android[./]test[./]|javax[./]obex[./]|com[./]android[./](location[./]provider|mediadrm[./]signer|media[./]remotedisplay|future[./]usb)[./]|android[./]net[./]ipsec[./]ike[./])'
+    severity: fatal
+    diagnosis: The app closed at start because it can't find classes from one of Android's optional libraries (for example org.apache.http.legacy in YouTube VR). The Frame's Android has the library, but OVRPort removed the app's request for it from the manifest; "Keep Android's shared libraries the app uses" puts it back. Turn it on and rebuild the game ("Update on Frame").
+    suggest: [frame.keep_system_libraries]
+  - id: refresh-rate-refused
+    # GitHub #336 (OutRun): the game quits when its xrRequestDisplayRefreshRateFB is refused; FrameBridge now answers
+    # success, so the game's own error line only shows in older builds
+    pattern: 'request display Hz: -1000101000'
+    severity: error
+    diagnosis: The game asked for a refresh rate the Frame's runtime refuses and may quit on that error. A newer FramePort keeps the current rate instead; press Update on Frame. Setting Game settings → Refresh rate to 90 Hz also avoids the error.
+    suggest: [adapter.refresh_rate=90]
+  - id: hybrid-feature-missing
+    # GitHub #484 (YouTube VR): a Horizon OS hybrid app checks for the system feature oculus.software.vr.app.hybrid
+    # before it leaves its 2D panel for VR
+    pattern: 'Missing hybrid app system feature'
+    severity: warning
+    diagnosis: 'The app stays in its 2D panel because it can''t find a Quest system feature it checks before switching into VR (360° videos, full screen). "Hybrid app: allow the switch into VR" declares that feature for the app. Turn it on and press Update on Frame; whether the VR part then works depends on the app.'
+    suggest: [device.hybrid_app]
  - id: web-wrapper
    pattern: '(Creating TwaLauncher for com\.oculus\.browser|NameNotFoundException:? com\.oculus\.browser)'
    severity: fatal
@@ -202,6 +296,16 @@ signatures:
      GraphicsEnv functions it uses were not found or behaved differently, for example after a Lepton update), so the game's
      OpenGL ES shader fixes (zink_shader_fix) don't apply.
    suggest: []
+  - id: shader-fix-unmatched
+    # vkshim (vk_shader_fix) / the shader-fix layer (zink_shader_fix), once per session, 5 minutes after the first shader
+    pattern: '(?:vk shim|shader fix layer): \d+ shader fix\(es\) configured, none matched'
+    severity: info
+    diagnosis: This game's recipe has a shader fix (for a GPU hang at one effect or scene), but none of the shaders it
+      fixes showed up in the first minutes of play. If you haven't reached that part of the game yet, that's expected.
+      Otherwise a game update may have changed the shader, so the fix no longer applies and the old hang can come back.
+      If the game freezes or closes there, please send a problem report with diagnostics so the fix can be updated.
+    suggest: []
+    report: true
  - id: zink-device-lost
    pattern: 'zink.*DEVICE[_ ]LOST|VK_ERROR_DEVICE_LOST'
    severity: fatal
@@ -313,6 +417,16 @@ signatures:
    diagnosis: The game needs Meta's colour-space extension, which the Frame's runtime doesn't offer, and quits before
      it starts VR (for example OutRun Quest VR). FrameBridge can offer it.
    suggest: [adapter.fb_color_space]
+  - id: appsw-required
+    # GitHub #336: OutRun Quest VR requires Application SpaceWarp: without a motion-vector size (the Frame's runtime
+    # reports none) or without XR_FB_space_warp it logs this line and quits before its first frame
+    pattern: 'AppSW recommended buffers unavailable'
+    unless: 'per-game: space_warp_emul=1'
+    severity: fatal
+    diagnosis: The game requires Meta's space warp (Application SpaceWarp) and quits because the Frame reports no
+      buffer size for it (for example OutRun Quest VR). Turning space warp off can't help; FrameBridge can provide
+      space warp itself (the game renders every frame normally, its motion vectors are not used).
+    suggest: [adapter.space_warp_emul]
  - id: vulkan-pipeline-refused
    # GitHub #349: with Lepton's Fossilize layer loaded every Transformers pipeline failed with -1; without it a few
    # multiview vertex shaders still fail in Turnip. Unreal ends at the first one.
@@ -387,6 +501,8 @@ signatures:
    # "Name=XR_FB_scene SpecVersion=1", OVRPort's "overportOXR: - XR_FB_scene 1", Unity's 'Meta XR Feature: ...
    # Extensions="..."' (GitHub #404); XR_FB_scene_capture alone doesn't count either
    pattern: '(?m)^(?!.*(?:Unavailable OpenXR extension: |Name=|overportOXR: - |Extensions=")).*XR_FB_scene\b|XR_FB_spatial_entity.*(not supported|UNSUPPORTED)|xrQuerySpacesFB'
+    # FrameBridge serves the room (OVRPort still lists XR_FB_scene and the shim names xrQuerySpacesFB): no finding
+    unless: 'FrameBridge[^\r\n]*scene: emulation active'
    severity: warning
    diagnosis: The game wants Meta's room data (scene API), which the Frame lacks. The adapter can emulate a room from the guardian bounds.
    suggest: [adapter.scene_emul]
@@ -438,11 +554,27 @@ signatures:
    supersedes: [native-crash]
  - id: cortopia-org-id-wait
    # Meta's C# wrapper logs this when the native call returned request id 0 (no callback ever follows); Cortopia's
-    # start-up awaits it forever (GitHub #360)
-    pattern: 'An unknown error occurred\. Request failed\.[\s\S]{0,600}?Cortopia\.Scripts\.Platform\.Meta'
+    # start-up awaits it forever (GitHub #360: Meta.<Initialize>d__13; #422 TMNT: Empire City: <Login>d__17)
+    pattern: 'An unknown error occurred\. Request failed\.[\s\S]{0,600}?Cortopia\.Scripts\.Platform\.(?:Meta|<Login>d__)'
    severity: error
    diagnosis: The game waits forever on its loading screen for an answer from Meta's platform (an org-scoped user id, used as its analytics id) that OVRPort's platform library doesn't give. The patch makes the game skip that one request, as it does without Wi-Fi.
    suggest: [frame.cortopia_org_id]
+  - id: meta-org-scoped-id-wait
+    # OVRPort's ovr_User_GetOrgScopedID returns request id 0 and Meta's wrapper logs "Request failed." with a stack
+    # that names no game code. Eleven Table Tennis (GitHub #452) logs its platform start just before: its
+    # <BuildIdentity>b__0 asks for the id ~0.3 s after "[META.FUN] in meta platform HandlePlatformInitialization"
+    pattern: 'meta platform HandlePlatformInitialization[\s\S]{0,3000}?An unknown error occurred\. Request failed\.'
+    severity: error
+    diagnosis: The game waits on its loading screen for Meta's org-scoped user id, which OVRPort's platform library
+      never answers. The patch answers that request with a fixed id derived from the game's user id.
+    suggest: [frame.ovr_org_scoped_id]
+    supersedes: [meta-request-failed]
+  - id: gazzlers-platform-unsupported
+    # GAZZLERS (GitHub #404): picks Meta/PICO from SystemInfo.deviceModel and throws for Lepton's "Valve Lepton"
+    pattern: 'Exception: Current Platform is not supported[\s\S]{0,300}?PlatformDeterminer\.GetAndroidPlatform'
+    severity: fatal
+    diagnosis: The game decides whether it runs on a Meta Quest or a PICO headset from Android's device name and stops for any other name; the Frame's Android calls itself Valve Lepton. The patch makes the game take its Meta Quest path.
+    suggest: [frame.gazzlers_quest_platform]
  - id: ovr-microphone-crash
    pattern: 'ovr_Microphone_GetOutputBufferMaxSize\+'
    severity: fatal
@@ -507,6 +639,13 @@ signatures:
    severity: error
    diagnosis: Epic Online Services can't save its login keychain and retries without end (a start that never finishes, 100 % CPU). The usual cause is missing internal storage (see lepton-data-link-failed); the patch stops the loop, and EOS then reports the failure to the game once.
    suggest: [frame.eos_keychain_loop]
+  - id: justdance-local-save-off
+    # Just Dance VR's own log line at start (Ubisoft's JdLog): its offline save opens, but this build never writes it
+    pattern: '\|LocalSave +\|OfflineSave_Init succeeded'
+    unless_patch: frame.justdance_local_save  # the line is the same with the fix in the build
+    severity: info
+    diagnosis: Just Dance VR (0.5.4 and later) opens its local save at every start but never writes it (the save request method is empty in this build; on a Quest the progress is kept by Ubisoft's online backend after a Meta sign-in, which the Frame doesn't have), so progress, unlocks and the finished tutorial are lost at every restart. The patch makes the game write its local save; nothing online is touched.
+    suggest: [frame.justdance_local_save]
  - id: pthread-keys-exhausted
    pattern: 'cannot create thread specific key'
    severity: fatal
@@ -535,6 +674,12 @@ signatures:
    diagnosis: The game crashed while leaving VR, inside Valve's foveation layer when it destroys a swapchain (for example Lambda1VR). This can happen after manually quitting; it is not a startup crash and does not explain distorted geometry seen before quitting.
    suggest: []
    supersedes: [native-crash]
+  - id: valve-fdm-render-crash
+    pattern: '(?s)\A(?=.*(?:Fatal signal 11|SIGSEGV))(?=.*vulkan\.freedreno\.so)(?=.*fdm_injection_CmdBeginRendering)'
+    severity: error
+    diagnosis: The game crashed in the graphics driver while Valve's foveation layer started a render pass. Valve's Fixed foveation path crashed AC Nexus like this (#394); builds with FramePort's foveation centring run Fixed on Valve's eye-tracked path instead, so rebuild the game (Update on Frame), or switch Foveated rendering to Eye-tracked or Off.
+    suggest: []
+    supersedes: [native-crash]
  - id: batman-audio-geometry-allocation
    pattern: '(?s)\A(?=.*com\.camouflaj\.manta)(?=.*Trying to allocate: [1-9][0-9]{10,}B)(?=.*MetaXRAudioUnityMemoryAllocator\.cpp)'
    severity: fatal
@@ -3,7 +3,9 @@
 ![FramePort's modules: the desktop app and the CLI drive pipeline.py (add, suggest, build, install, launch test), which uses sources/, analysis/, recommend/, build.py, targets/ and validate/; builds use patches/ and tools/; targets reach the agent on the Steam Frame through frame/ and install/ over SSH](images/architecture.svg)

 ## Data flow for one game
-1. **Source** (`sources/quest_dump.py`): folder with an APK and optional `<package>/` or `obb/` data.
+1. **Source** (`sources/quest_dump.py`): folder with an APK and optional `<package>/` or `obb/` data; SideQuest
+   backups and AXRB downloads are recognised, app bundles (`.xapk`/`.apks`/`.apkm`/`.apkx`, split APKs) are merged
+   into one APK first (`sources/bundles.py`).
 2. **Analysis** (`analysis/detect.py`): package/label/version (pyaxmlparser), ABIs, engine, XR API, graphics API,
   direct-VrApi, GLAD/eglGetProcAddress, Unity MSAA levels, Meta permissions, telemetry references.
 3. **Recipe** (`recommend/engine.py`): every patch's `detect()` suggests itself with a reason; a catalog entry (exact
@@ -16,37 +18,50 @@
   deployment.json, artwork) → `shortcuts` (detached systemd unit stops Steam, writes shortcuts.vdf + grid art,
   restarts Steam).
 6. **Test** (`validate/device.py`): agent `launch_test` (systemd-run launch.sh, wait, stop) → fetch launch.log →
-   `triage.py` (milestones + signatures → suggested patches) → UI offers "apply suggestions and rebuild".
+   `triage.py` (milestones + signatures → suggested patches) → UI offers "apply suggestions and rebuild". Real play
+   sessions are triaged the same way afterwards (`validate/session.py`, game page "Last session").

 ## Extending
 - **New patch**: `patches/frame/<name>.py` with a `Patch` subclass (`detect`, `apply`, optional `validate`), plus a
  signature in `catalog/triage.yaml` and a PLAYBOOK row. Stages: `overport` | `apk` | `install`.
- **Upstream fixed a bug we work around**: register an `UpstreamFix` (`patches/upstream.py`) in the workaround's
+- **Upstream fixed a bug FramePort works around**: register an `UpstreamFix` (`patches/upstream.py`) in the workaround's
  module: a probe that finds the fix in OVRPort's output (True / False / None = can't tell). Each build runs the probes
  on the converted APK and leaves out the workarounds whose fix is there (log "not needed: …", `build.superseded`,
  left out of settings.conf at install; game page and `frameport show` say so). The recipe keeps asking for the fix,
-  so builds made with an older runtime keep the workaround. `FRAMEPORT_KEEP_WORKAROUNDS=1` turns it off.
- **New heuristic**: put it in the patch's `detect()` (and `applies()` for visibility), with the evidence in the
+  so builds made with an older runtime keep the workaround. `FRAMEPORT_KEEP_WORKAROUNDS=1` turns the probes off.
+- **New heuristic**: put the rule in the patch's `detect()` (and `applies()` for visibility), with the evidence in the
  reason text; check `scripts/eval_heuristics.py` still reproduces the catalog and add a test in
  `tests/test_heuristics.py`.
 - **New game recipe**: `catalog/games/<package>.yaml` (or "Save as known-good" in the GUI, which writes to the user
-  catalog). Publish recipes by serving a folder with `index.json` and pointing `FRAMEPORT_CATALOG_URL` at it.
+  catalog). Installed apps fetch `catalog/games/` from GitHub `main` every 6 hours (`recommend/catalog.refresh_remote`),
+  so a merged recipe reaches users without a release; `catalog/triage.yaml` follows the same way. `FRAMEPORT_CATALOG_URL` points the apps at another folder that
+  serves `index.json` + `<package>.yaml` instead.
 - **New target**: implement `targets/base.Target`; the pipeline and UI only use that interface.

-## Oculus Rift (PC VR) games
-`sources/rift_dump` finds Windows game folders; `analysis/rift` (own PE reader) detects exe, bitness, engine, LibOVR vs
-OpenXR, D3D version and Oculus Platform SDK use; ids are `rift.<slug>`. Their only patches are the `pcvr` category
-(`patches/pcvr.py`: Revive, OpenVR backend, crash reporter, Oculus detection, OpenXR layer, Proton
-log/version/env); `base.for_game` keeps Quest and PC VR patches
-apart. "Build" = `pipeline.prepare_rift` (checks + Revive). Revive is a portable tool (`tools/revive.py` unpacks
-`ReviveInstaller.exe` in pure Python: NSIS header + deflate blocks). Targets:
- `targets/pc_revive.PcReviveTarget`: Windows/WSL (`core/winhost.py`), non-Steam shortcut running
-  `ReviveInjector.exe /openxr <exe>` via the agent's VDF code, grid art, local records in `<user data>/pc/`.
+## PC VR (Oculus Rift and SteamVR) games
+`sources/rift_dump` finds Windows game folders (one game per folder); `analysis/rift` (own PE reader) ranks the
+programs, detects bitness, engine, the VR APIs (LibOVR, OpenVR, OpenXR), D3D version and Oculus Platform SDK use; ids
+are `rift.<slug>`. Their only patches are the `pcvr` category (`patches/pcvr.py`: Revive, OpenVR backend, crash
+reporter, Oculus detection, OpenXR layer, launch arguments, Proton version/env); `base.for_game` keeps Quest and PC
+VR patches apart. Repacks are usually pre-patched, so a game is installed unchanged and its program started
+directly; Revive is only suggested for games with LibOVR code, and those run only on the PC (Revive's hooks don't
+work under Proton on ARM64). "Build" = `pipeline.prepare_rift` (checks, plus Revive when the recipe has it). Revive
+is a portable tool (`tools/revive.py` unpacks `ReviveInstaller.exe` in pure Python: NSIS header + deflate blocks).
+Targets:
+- `targets/pc_revive.PcReviveTarget`: Windows/WSL (`core/winhost.py`), non-Steam shortcut (the game's program, or
+  `ReviveInjector.exe [/openxr] <exe>`; Revive's OpenVR backend by default) via the agent's VDF code, grid art, local
+  records in `<user data>/pc/`.
 - `FrameLeptonTarget.install_pcvr` → `installer.install_pcvr` → agent `prepare_pcvr`/`finalize_pcvr`: upload
-  `game/` + `revive/` (+ `xrlayer/` for `pcvr.xr_timefix`, `helpers/` for `pcvr.oculus_unreal`; size-manifest dedupe,
+  `game/` (+ `revive/`, `xrlayer/` for `pcvr.xr_timefix`, `helpers/` for `pcvr.oculus_unreal`; size-manifest dedupe,
  stale files removed), `launch.sh` running the ARM64 Proton chain (built from toolmanifest.vdf; with
-  `pcvr.oculus_unreal` the injector runs through `helpers/fp_oculushmd.exe`, which provides Unreal's
+  `pcvr.oculus_unreal` the program runs through `helpers/fp_oculushmd.exe`, which provides Unreal's
  `OculusHMDConnected` event); `proton_status`/`install_proton` manage Proton from Valve's ARM64 compat list.
+
+## Linux apps and Windows programs
+`pipeline.add_linux_app` (AppImage, archive or folder; library kind `linux`) and `pipeline.add_windows_exe` add
+programs that are installed unchanged. The agent's `finalize_linux` unpacks them, writes the launcher (arm64 builds
+directly, x86_64 builds through Valve's FEX), a Desktop Mode menu entry and, for SteamVR overlay apps, their
+`.vrmanifest` registration; Windows programs run through Proton like PC VR games.
 - **Native binaries** (`artifacts/`): edit `native/…`, run `python native/build.py`, commit the new artifacts + SHA256SUMS,
  run `frameport parity` to see which games change.

@@ -61,18 +76,26 @@ apart. "Build" = `pipeline.prepare_rift` (checks + Revive). Revive is a portable
 - `prepare()` (bundle): `<data>/updates/<ver>/`: download → SHA256SUMS.txt check → extract to `staged/` (ditto on
  macOS) → layout check → on Windows the same Authenticode signer as the running exe → `ready.json`.
 - `apply()`: writes `<data>/updates/apply.{ps1,sh}` and starts it detached; FramePort quits. The script waits for the
-  pid. Windows: backs up the files it replaces (`updates/<ver>/previous`) and copies over the folder (the zip has no
-  folder of its own). macOS/Linux: `mv` target → `.old`, staged → target, rollback on failure, clears the quarantine.
-  Then it relaunches FramePort. Log: `<data>/logs/update.log`.
+  pid. Windows: changes nothing while FramePort or a program file (.exe/.dll/.pyd) is still in use (waits 60 s), backs
+  up the files it replaces (`updates/<ver>/previous`), moves the old version's files the new one doesn't have out of
+  the bundle's own folders (app, Lib, DLLs, site-packages, data) into `previous` too, and copies over the folder (the
+  zip has no folder of its own); a failure deletes the files the update added and restores the rest (GitHub #476: a
+  rollback that kept the new version's added modules made the old version crash at start). Bundles carry
+  `frameport/_bundle_files.txt` (written by `scripts/package.py`, `core/bundle_files.py`): at start the app deletes
+  (or at least never imports) package files the list doesn't have and tells the user to reinstall when compiled
+  modules don't match it — updates made by an older version's script still copy over without cleaning.
+  macOS/Linux: `mv` target → `.old`, staged → target, rollback on failure, clears the quarantine.
+  Then the script relaunches FramePort. Log: `<data>/logs/update.log`.
 GUI: background check 10 s after start + every 6 h → sidebar card + Library bar → dialog with notes → job
 `app-update` (waits for other jobs) → restart. "Install updates automatically": prepare in the background, apply in
 `main()` before the window opens. CLI: once-a-day hint from the cached result (a daemon thread refreshes it), `frameport
 update [--check] [--yes]`. CI runs `scripts/update_smoke.py` on every OS with the archive it just built.

 ## Dynamic data (fetched live, cached, bundled fallback)
-overport CLI release (Android-XR-Bridge/OVRPort, fallback ovrport/app) + patch list + titles, Temurin JRE (Adoptium API), apksigner (Google repository index),
-store artwork/titles (overport image API), catalog (optional remote), Lepton location/appid (Frame appmanifests),
-Steam user (Frame userdata).
+overport CLI release (Android-XR-Bridge/OVRPort, fallback ovrport/app) + patch list + titles, Temurin JRE (Adoptium
+API), apksigner (Google repository index), Cpp2IL and APKEditor (GitHub releases, on first use), store artwork,
+titles and details (overport image API, OculusDB, Steam), catalog recipes and triage signatures (GitHub `main`),
+announcements, Lepton location/appid (Frame appmanifests), Steam user (Frame userdata).

 ## Built on