Android version / web wrapper: warnings only, never unsupported from the manifest alone (owner's call): the recipe notes, game page (warning callout) and CLI say what the manifest asks for; a launch test's triage (android-too-new, web-wrapper) decides

The game page's "What FramePort will do" for a Linux app gets a Desktop Mode switch ("In the menu and on the
desktop", default on): kept in the library entry (desktop_entry; patches don't apply to Linux apps), passed to
finalize_linux at install and applied at once on the Frame through the agent's desktop_entry command when the app is
installed. The agent side (menu + desktop .desktop files, launcher with FRAMEPORT_DESKTOP=1, refresh for existing
installs, removal on uninstall/purge) came with agent v63. Help text desktop_entry, INSTALL/FRAME_RUNTIME/PLAYBOOK,
CLAUDE.md. Game Mode's Steam Input problem from the report is separate.

Closes #84

.github/workflows/build.yml

@@ -1,9 +1,19 @@
 name: build
 on:
   push:
+    branches: [main]
     tags: ["v*"]
   pull_request:
   workflow_dispatch:
+    inputs:
+      dev:
+        description: "Publish the bundles as the dev build (testers: Settings → Updates → Install the latest dev build)"
+        type: boolean
+        default: true
+      notes:
+        description: "What testers should try (shown before they install it)"
+        type: string
+        default: ""
 
 jobs:
   test:
@@ -12,10 +22,13 @@ jobs:
       - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v10.2.0
       - run: uv sync --extra dev
+      - name: Lint
+        run: uv run ruff check .
       - run: uv run pytest -m "not games and not device"
 
   bundle:
     needs: test
+    if: github.event_name != 'push' || startsWith(github.ref, 'refs/tags/v')  # pushes to main: tests only
     permissions:
       contents: read
       id-token: write      # build provenance attestations (Sigstore)
@@ -31,10 +44,13 @@ jobs:
         include:
           - os: windows-latest
             archive: FramePort-windows-x64.zip
-          - os: macos-latest
+          - os: macos-26  # Apple Silicon + Xcode 26 (macos-15's Xcode 16.4 fails a Flutter plugin; macos-latest
+            # went unassigned on 2026-10-02)
             archive: FramePort-macos-arm64.zip
-          - os: ubuntu-latest
+          - os: ubuntu-22.04  # oldest supported: the bundle needs the build host's GLib/glibc or newer
             archive: FramePort-linux-x64.tar.gz
+          - os: ubuntu-22.04-arm  # Linux ARM64 (same base as x64)
+            archive: FramePort-linux-arm64.tar.gz
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v7
@@ -43,11 +59,14 @@ jobs:
         if: runner.os == 'Linux'
         run: sudo apt-get update && sudo apt-get install -y ninja-build libgtk-3-dev
       - run: uv sync --extra dev
+      - name: Dev build version (next patch + .dev<run number>; not committed)
+        if: github.event_name == 'workflow_dispatch' && inputs.dev
+        run: uv run --no-project python scripts/dev_version.py ${{ github.run_number }}
       - id: flet
         run: uv run python scripts/package.py
-        continue-on-error: ${{ runner.os == 'macOS' }}
-      - name: macOS fallback (PyInstaller bundle)
-        if: runner.os == 'macOS' && steps.flet.outcome == 'failure'
+        continue-on-error: ${{ runner.os == 'macOS' || runner.arch == 'ARM64' }}
+      - name: macOS / Linux ARM64 fallback (PyInstaller bundle)
+        if: (runner.os == 'macOS' || runner.arch == 'ARM64') && steps.flet.outcome == 'failure'
         run: uv run --with pyinstaller python scripts/package.py --pyinstaller
 
       # ---- signing: self-signed certificate on Windows, ad-hoc on macOS ----
@@ -77,8 +96,27 @@ jobs:
         if: runner.os == 'macOS'
         run: |
           app=$(find dist -maxdepth 3 -name "*.app" -type d | head -1)
-          codesign --force --deep --sign - "$app"
+          # Re-signing replaces the signature, entitlements included: pass them again, or the file picker refuses to
+          # open ("ENTITLEMENT_NOT_FOUND", GitHub #63). flet build writes them to Release.entitlements; the
+          # PyInstaller fallback has none, so it gets the same set.
+          ent=build/flutter/macos/Runner/Release.entitlements
+          if [ ! -f "$ent" ]; then
+            ent="$RUNNER_TEMP/FramePort.entitlements"
+            cat > "$ent" <<'EOF'
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0"><dict>
+            <key>com.apple.security.cs.allow-jit</key><true/>
+            <key>com.apple.security.cs.allow-unsigned-executable-memory</key><true/>
+            <key>com.apple.security.network.client</key><true/>
+            <key>com.apple.security.network.server</key><true/>
+            <key>com.apple.security.files.user-selected.read-write</key><true/>
+          </dict></plist>
+          EOF
+          fi
+          codesign --force --deep --sign - --entitlements "$ent" "$app"
           codesign --verify --deep --strict --verbose=2 "$app"
+          codesign -d --entitlements - "$app" 2>/dev/null | tee /dev/stderr | grep -q "files.user-selected.read-write"
 
       # ---- package (archives keep permissions/symlinks) + provenance ----
       - name: Package (Windows)
@@ -90,7 +128,9 @@ jobs:
         run: ditto -c -k --keepParent "$(find dist -maxdepth 3 -name '*.app' -type d | head -1)" ${{ matrix.archive }}
       - name: Package (Linux)
         if: runner.os == 'Linux'
-        run: tar czf ${{ matrix.archive }} -C dist --transform 's,^linux,FramePort,' linux
+        run: |  # flet build -> dist/linux; the PyInstaller fallback -> dist/FramePort (one folder)
+          if [ -d dist/linux ]; then tar czf ${{ matrix.archive }} -C dist --transform 's,^linux,FramePort,' linux
+          else tar czf ${{ matrix.archive }} -C dist FramePort; fi
       # self-update with this archive: unpack, verify the layout (+ the signer on Windows), run the real swap script
       - name: Update smoke test
         run: uv run python scripts/update_smoke.py ${{ matrix.archive }}
@@ -132,10 +172,50 @@ jobs:
           git fetch --force origin "refs/tags/${tag}:refs/tags/${tag}"
           whatsnew=$(git tag -l --format='%(contents:body)' "$tag")
           [ -n "$whatsnew" ] || whatsnew=$(git tag -l --format='%(contents:subject)' "$tag")
-          { echo "FramePort ${tag}: Windows (x64), macOS (Apple Silicon) and Linux (x64)."; echo;
+          { echo "FramePort ${tag}: Windows (x64), macOS (Apple Silicon) and Linux (x64, ARM64)."; echo;
             if [ -n "$whatsnew" ] && [ "$(git cat-file -t "$tag")" = tag ]; then
               echo "## What's new"; echo; echo "$whatsnew"; echo; fi
-            echo "Already have FramePort? It offers this update itself (Library → **Update now**, or \`frameport update\`)."
-            echo; sed -n '/^## First launch/,$p' docs/INSTALL.md; } > "$notes"
+            echo "Already have FramePort? It offers this update itself (Library → **Update now**)."
+            echo; cat packaging/release-footer.md; } > "$notes"  # short: the update dialog shows these notes
           gh release delete "$tag" --yes 2>/dev/null || true
           gh release create "$tag" out/* packaging/FramePort-selfsigned.cer --title "FramePort ${tag}" --notes-file "$notes"
+
+  dev-release:
+    # "Run workflow" with dev ticked: replaces the rolling `dev` pre-release (never shown by the automatic update check;
+    # testers install it from Settings → Updates). Same assets + SHA256SUMS as a release.
+    if: github.event_name == 'workflow_dispatch' && inputs.dev
+    needs: bundle
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v10.2.0
+      - id: version
+        run: echo "version=$(uv run --no-project python scripts/dev_version.py ${{ github.run_number }})" >> "$GITHUB_OUTPUT"
+      - uses: actions/download-artifact@v8
+        with:
+          path: out
+          merge-multiple: true
+      - name: Wheel
+        run: uv build --wheel -o out && ls out
+      - name: Checksums
+        run: cd out && sha256sum * > SHA256SUMS.txt && cat SHA256SUMS.txt
+      - name: Publish the dev build
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.version.outputs.version }}
+          NOTES: ${{ inputs.notes }}
+        run: |
+          notes=$(mktemp)
+          last=$(git describe --tags --abbrev=0 --match 'v*' 2>/dev/null || true)
+          { echo "Dev build **${VERSION}** from commit ${GITHUB_SHA::7} ($(date -u +%Y-%m-%d)). For testing fixes before"
+            echo "the next release; you get that release as a normal update."; echo
+            if [ -n "$NOTES" ]; then echo "## Please test"; echo; echo "$NOTES"; echo; fi
+            if [ -n "$last" ]; then echo "## Changes since ${last}"; echo
+              git log --no-merges --format='- %s' "${last}..HEAD" | cut -c1-160 | head -40; fi; } > "$notes"
+          gh release delete dev --yes --cleanup-tag 2>/dev/null || true
+          gh release create dev out/* packaging/FramePort-selfsigned.cer --prerelease --target "$GITHUB_SHA" \
+            --title "FramePort dev build ${VERSION}" --notes-file "$notes"

.gitignore

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

CLAUDE.md

@@ -14,7 +14,45 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
     status_row, art_fill, confirm, `update()` = safe update: in Flet 1.0 reading `.page` of an unmounted control
     raises), `jobs.py` (background FIFO job queue, one at a time, cancel via Reporter; no Flet), `views/`
     (library: search/filters/tags/sort as pure tested helpers; game: hero + one-click install, patches under
-    "Customize"; frame: device + readiness + installed, or connect wizard; settings; welcome; activity panel).
+    "Customize"; frame: device + readiness + installed, or connect wizard; files: the Frame's file manager (persistent
+    like the library; locations = Videos/Downloads/Documents from agent `storage_targets`, each installed Quest game's
+    storage, the home folder; SFTP via `install/files.py` list_dir/upload/download/make_dir/rename/delete, all
+    confined to the location by `files.inside`; Lepton's links in a game's storage can't be renamed/deleted; replaced
+    the "Send files" dialog, game menu → "Add videos & files…" = `go("files", pkg)`; multi-select bar (download/
+    delete); drag-and-drop from the OS via the `flet-dropzone` extension (Apache-2.0, Flutter `desktop_drop`), which
+    only a `flet build` bundle contains: `files.dropzone_available()` keeps it out of source runs and the PyInstaller
+    fallback, which would show an unknown control); screenshots (Steam screenshots on the Frame, `install/screenshots.py`
+    + agent v46 `list_screenshots`/`delete_screenshots`: the Frame files every headset shot under SteamVR 250820, so
+    launch.sh logs `start/end <unix>` to `<anchor>/plays.log` (upgrade_launchers adds it; Proton launchers exec → start
+    only) and shots are matched by time; thumbnails cached in `<data>/screenshots-cache/<frame>/`, shown by asset URL;
+    delete leaves screenshots.vdf alone (Steam rewrites it at exit); game menu → "Screenshots" = `go("screenshots",
+    pkg)`); live view (`views/live.py` + `install/livestream.py`: the Frame's built-in SteamVR "headset view" webcam
+    (`steamvr-v4l2cam.service` → v4l2loopback "SteamVR" /dev/video99, see docs/FRAME_RUNTIME.md) + the default
+    output's pulse monitor (sound) → `fp_venc` (`native/venc`, own clean-room V4L2 driver of the Frame's iris
+    hardware encoder: RGB24→NV12 box downscale with NEON, H.264 CBR, one frame per slot of an even fraction of the
+    panel rate read from DRM, e.g. 96 Hz → 32 fps; stdin `k` = keyframe, EOF = stop; `--probe` / `--selftest`;
+    artifact `linux-arm64-bin/`, synced to `~/.local/share/frameport/bin` by sha256 at stream start, no agent change)
+    piped into ffmpeg (`-c:v copy` + AAC), else the old ffmpeg/x264 30 fps path (qualities scale down only; "full" =
+    SteamVR's size; stderr `live: encoder=… fps=…` → status line) →
+    fragmented MP4 on an SSH exec channel's stdout (stdin EOF stops it) → relay on 127.0.0.1 (a new viewer asks
+    the hardware encoder for a keyframe and waits for it, else gets init + fragments since the last keyframe of the
+    *video* track) → player page
+    `install/live_player.py` (MSE; starts muted as browsers require, "Sound on" button; 0.3 s cushion, catches up at
+    1.1x, seeks only when >2 s behind: seeking to the very edge starved it) opened
+    in the user's default browser: Flet can't show video outside `flet build` bundles; the stream outlives the tab and
+    stops on disconnect/window close); monitor (`views/monitor.py` + `frame/monitor.py` + agent v62 `_monitor`: one
+    JSON sample per tick over an SSH exec channel while the tab is shown (stopped in go/disconnect/on_close, the
+    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
+    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
+    await a FilePicker) must be coroutine functions or go through `page.run_task`: Flet doesn't await a lambda's
+    coroutine (the Files row Download button silently did nothing). `ui_smoke.py --fake-frame --gestures` drives real
+    mouse drags/right-clicks.
     User tags live in library entries (`tags`), filters in library setting `ui.library`.
     **Performance rules** (the app froze before): never put image bytes in controls — artwork is served by URL from the
     GUI assets dir (= user data dir; `ft.run(assets_dir=…)`), as thumbnails (`artwork/thumbs.py`, Pillow); the
@@ -33,11 +71,20 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
     uploads are interruptible (Cancel checked per MiB) and resumable (big files via SFTP `.part` append, small files
     streamed in tar batches; the agent counts files already in `incoming/`). Multi-select in the Library queues
     installs after asking every needed question up front. Failures end in one pop-up (Resume / Uninstall / log).
+  - Other drives (GitHub #90, agent v63): anchors stay in ~/Applications/quest-frame, a game's files may live in
+    `<mount>/FramePort/<pkg>` (`deployment.json` base). Agent `drives` (/proc/mounts, /run/media + Steam library
+    drives; vfat/exfat/ntfs/read-only refused), prepare*/finalize_linux `dest` (unmounted = error, never a fallback;
+    installed games keep their base), `move` (detached systemd-run + `move_status`; cp -a under podman unshare,
+    count+bytes check, symlink retarget, launch.sh: Quest app_dir line / Linux+PC VR rewritten from the record's
+    `launcher` field, else text swap), list_installed `drive`/`drive_missing` (install_state keeps such games
+    "installed"). PC: `install/drives.py`, library setting `install.drive` (Frame page → Storage), game menu
+    "Move to…" (job kind tool-frame), CLI `frame drives`/`frame move`/`install --dest`. Untested on the device.
   - **PC VR repacks are pre-patched to run directly** (proven: Rick and Morty, Vader Immortal run when the exe is
     launched directly; Revive breaks them). So Rift games default to `as_is` = install the copy unchanged and launch
     the exe directly (`pcvr.xr_timefix` for the Frame OpenXR-1.1→1.0 fix, `pcvr.no_crash_reporter` for Unreal).
-    **Revive is off by default, opt-in** (`pcvr.revive`, and `pcvr.oculus_unreal`): only for an un-cracked Oculus game
-    that fails at "Initializing OVR session". Those (Lone Echo, Robo Recall, Lies Beneath: crack .7z not extracted /
+    **Revive is only suggested for games with Oculus (LibOVR) code** (`pcvr.revive`, and `pcvr.oculus_unreal`; repacks
+    with a bundled Revive and SteamVR/OpenXR games run directly): needed by an un-cracked Oculus game that fails at
+    "Initializing OVR session". Those (Lone Echo, Robo Recall, Lies Beneath: crack .7z not extracted /
     Platform SDK) hit Revive's Oculus-runtime **signature check** under Proton-arm64 — Revive's LoadLibrary/WinVerifyTrust
     hooks don't install (ARM64EC), and the game's Oculus SDK shim rejects the unsigned Revive runtime (wintrust +
     crypt32 signer "Oculus VR") — so they don't run on the Frame without extracting the repack's crack (which FramePort
@@ -68,15 +115,35 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
     auto-start SteamVR on Play (`winhost.start_steamvr`); the Frame launcher always uses `/openxr`. UI (`game.py`
     where()) states per-game where it runs; installing an Oculus game on the Frame shows a warning. Migration
     `rift_frame_native` re-analyzes + re-derives existing entries.
+  - Own artwork (0.8.0): game menu → "Use your own artwork…" (also from the Find artwork dialog) =
+    `views/art_dialog.show_custom_art_dialog`: one slot per kind (portrait/landscape/hero/logo/icon), FilePicker →
+    `sources.apply_custom` (Pillow check, ≥64 px, ≤40 MB, scaled to ≤3840 px, PNG if alpha/logo/icon else JPEG,
+    replaces only that kind + its thumbnails, drops the generated cover/banner, writes `.picked` = "custom") /
+    `remove_custom`; Steam shapes are still composed from what exists (`steam.py` PREFER).
   - Art for Rift games: `artwork/sources.py` — Quest version package (OculusDB packageName, exact name or +
     "Unplugged"-type suffix, never sequels) → Meta art; OculusDB square cover; Steam (exact names only); exe icon.
   - Store details (`artwork/details.py`, entry `details`): OculusDB (description, genres, publisher, website; by Quest
     package or Rift match) + Steam appdetails (exact title: developer, release date, up to 6 screenshots → artwork
     `shot_N.jpg`). Meta store pages reject scraping, so Oculus exclusives have no screenshots. Genres become automatic
     tags. Steam shortcuts get a complete composed art set (`artwork/steam.py`: 600×900 / 920×430 / 1920×620 / logo /
-    256 icon, blurred-backdrop compositing for square-only covers) and tags: how it runs, the original platform
+    256 icon, blurred-backdrop compositing for square-only covers; no store art (at most the APK icon) → a placeholder
+    set: the name on a colour from the title hash + the APK icon, `steam_set_for`; 2D Android apps get no store lookups) and tags: how it runs, the original platform
     (Meta Quest / Oculus Rift), genres, user tags — merged with tags set in Steam (non-Steam shortcuts can't hold a
     description).
+  - Linux apps (GitHub #31, library kind `linux`, `linux.<slug>`; x86_64 builds run through FEX (app 3127680, no SLR:
+    RootFS /usr/share/guestos/fex-mesa from the OS image; needs `STEAM_COMPAT_DATA_PATH`, see docs/FRAME_RUNTIME.md):
+    agent v61 `linux_x86_tools`/`pick_tool`, `install_proton`/`proton_status` `kind: linux_x86`, `finalize_linux
+    x86_64`, `installer.ensure_proton(kind=)`; an arm64 program wins over an x86_64 one): GUI = Add
+    games → "Add a Linux app…" /
+    "…folder…" (`app.add_linux` job → `pipeline.add_linux_app`); game page `linux_summary` (program + Change…, AppImage,
+    OpenXR, source) instead of recipe/patches, `C.missing_libraries` callout (Frame deployment, else last install);
+    no Analyze/Rebuild/recipe/share/Game settings actions, Frame only; platform "Linux" badge + library filter; Steam
+    tags "Linux app on Frame"/"Linux"; `_follow_catalog` skips them; local files of a lone AppImage = the file only.
+    Desktop Mode entries (GitHub #84, agent v63): finalize_linux writes `frameport-<slug>.desktop` to
+    ~/.local/share/applications (+ ~/Desktop if it exists; `X-FramePort-Package` marks ours), launch.sh with
+    `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.
   - Quest/Rift twins stay separate entries, shown and named in Steam "Title (Quest)"/"(Rift)" (`core/titles.py`).
   - `Recipe.as_is` = install unchanged (pre-patched libraries): `pipeline.prepare_as_is`; auto for APKs that already
     contain FrameBridge (`frame_patched`). For Rift it changes nothing (the dump is never modified; the Frame copy
@@ -92,6 +159,10 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
   - `patches/` — **the unit of modularity**. `base.py` (Patch interface, registry), `overport.py` (overport CLI patch ids,
     discovered dynamically via `overport patches`), `frame/*.py` (one module per Frame fix), `settings.py` (FrameBridge
     adapter keys + device files as patches). Add a patch = add a module that calls `register(...)`.
+    `upstream.py`: upstream fixes that replace a workaround per build (a probe finds the fix in OVRPort's output →
+    the build leaves the workaround out, `build.superseded`; recipes unchanged). Registered: `ovrport.haptic_envelope`
+    (→ `adapter.haptic_fix`, `frame/haptic_envelope.py`) and `ovrport.microphone_stream` (→ `frame.ovr_microphone`),
+    both fixed in OVRPort runtime 3.4.3-aa54c3f (ovrport/app#73; haptics owner-verified with Lucky's Tale 2026-10-07).
   - `analysis/` — APK/ELF inspection (`detect.py`), `elf.py` (pyelftools reads; own DT_NEEDED writer), `stubgen.py`
     (generates the ovr_* stub .so without a compiler).
   - `apk/` — `axml.py` (binary manifest editor), `workspace.py` (staged zip edits), `sign.py` (apksigner; it aligns too).
@@ -132,11 +203,14 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
     [--yes]`, once-a-day stderr hint read from the cache only (`refresh_cache()` in a daemon thread writes no
     settings, to avoid read-modify-write races). `scripts/update_smoke.py <archive>` runs the real extract + swap script
     (no relaunch) — CI runs it on all three OS with the archive it just built.
-    Verified: Linux + Windows (native, signer check) smoke with the v0.2.0 bundles; macOS only via the CI smoke.
+    Verified end to end (2026-10-02): real 0.3.3 bundles on Windows and Linux (Ubuntu 22.04/WSLg) found, staged and
+    installed 0.3.4 ("Install updates automatically" path) and relaunched as 0.3.4 with settings kept. Not yet clicked
+    by hand: the "Update now" button path (same apply(), called from the running app). macOS: CI smoke only.
 - `agent/frameport_agent.py` — runs **on the Frame** (python3 stdlib only), JSON over SSH. Owns the install layout,
   launch.sh template, Steam shortcuts (binary VDF), launch tests. Bump `AGENT_VERSION` when changing it.
 - `bootstrap/bootstrap.sh` — one-time Frame setup served by the pairing server (sshd, app key, avahi service, Lepton).
-- `catalog/games/<package>.yaml` — 34 recipes verified 2026-09-28 + Deadpool VR (2026-10-01, owner-confirmed); `catalog/triage.yaml` — log signatures → fixes.
+- `catalog/games/<package>.yaml` (installed apps also fetch these from GitHub `main`, see "Catalog updates") — 38 recipes (34 verified 2026-09-28; Deadpool VR, 4XVR, NEX Player and AC Nexus's
+  90 Hz default confirmed later by the owner); `catalog/triage.yaml` — log signatures → fixes.
 - `native/` — sources of the prebuilt binaries in `artifacts/` (adapter, VrApi bridge patches, GL shim, stubs).
   `native/build.py` rebuilds them with NDK r27c (downloaded on demand into `native/.cache`, git-ignored; uses
   `-ffile-prefix-map` so no local paths get embedded; zip symlinks are restored as copies). Users never need the NDK.
@@ -149,9 +223,9 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
 UV_LINK_MODE=copy uv sync --extra dev   # creates/updates ./.venv
 uv run pytest                # unit tests (no device, no game files)
 uv run frameport --help      # CLI;  uv run frameport-gui  for the GUI
-uv run frameport parity --known-good <PATCHED/_known-good-*> --sources "<VR CyberDeck downloads>"
+uv run frameport parity --known-good <PATCHED/_known-good-*> --sources "<folder with the game dumps>"
 ```
-Games/device tests: `pytest -m games` (FRAMEPORT_GAMES=<downloads dir>), `pytest -m device` (FRAMEPORT_FRAME=steamos@host);
+Games tests: `pytest -m games` (FRAMEPORT_GAMES=<downloads dir>); on-device checks are CLI commands (below);
 native layer test: `FRAMEPORT_NATIVE_TESTS=1 pytest -m native` (compiles with the NDK, ~2 min on NTFS).
 Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattributes`).
 - `FRAMEPORT_HOME=<dir>` isolates all app data (tests use it); `FRAMEPORT_JAVA/_OVERPORT_JAR/_APKSIGNER_JAR` override
@@ -159,7 +233,7 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
   artwork, frames.json, the app's SSH key which the dev Frame authorizes).
 - Device checks: `frameport test <pkg>` / `frameport parity-device --results <parity.json> --baseline <launch.txt>
   [--test-only]`; the pre-FramePort baseline is `PATCHED/_known-good-2026-09-28/_frame-state/baseline-launch.txt`.
-- Docs screenshots (`docs/images/`): `python scripts/scrub_library.py ~/.local/share/frameport <dir>` (copies
+- Docs screenshots (`docs/images/`): `python scripts/scrub_library.py ~/.local/share/frameport <dir> --status works,issues` (copies
   library + artwork only; titles replace folder names, local paths → `D:/Games/...`, sort by size) then
   `FRAMEPORT_HOME=<dir> python scripts/ui_smoke.py --out <shots> --docs --fake-frame --game <pkg>` (set
   FRAMEPORT_JAVA/_OVERPORT_JAR/_APKSIGNER_JAR so no tool download toast appears; `--viewport 1280x2600` + crop for the
@@ -178,6 +252,25 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
   an `expand` child in a `wrap=True` Row).
 - Stopping the GUI: `pkill -f` patterns match your own shell — use `pgrep -f "[b]in/frameport-gui|[f]let-desktop-light"`.
 
+## Round-2 polish (2026-10-02)
+- `errors.py`: `explain(exc)` (plain sentence for GUI + CLI), `is_connection_error`. Install/test jobs for the Frame
+  (`Job.needs_frame`) that lose the connection go back to the queue front and the queue pauses (`jobs.paused`);
+  `app._poll` retries every 10 s and resumes (owner-verified on the device 2026-10-02: the queue resumed after the
+  connection was lost). Wake lock: agent v30 `keep_awake` (systemd-inhibit idle:sleep, idle-only
+  fallback because polkit `inhibit-block-sleep` is auth_admin for non-local sessions), held while Frame jobs exist.
+- **Already converted inputs** (`analysis.is_overport_output`, e.g. the owner's library points at `PATCHED/` copies)
+  are not converted again: a second OVRPort run replaced libovrplatformloader.so and dropped its DT_NEEDED on
+  libovrstubs.so (Wallace & Gromit / Espire 2 crashed: cannot locate symbol ovr_…). Alt builds come from the saved
+  `<pkg>.alt-noforcequit.apk`, else one OVRPort run (frame.ovrstubs relinks). `missing_ovr_symbols` only counts
+  linked stub/compat libs. Converted copies in `output/` are removed after a Frame install (`build.keep_copies`).
+- Art: `.picked` marker = user's pick, automatic fetches never overwrite it and only fill missing kinds; a Meta
+  result's picture is the OculusDB image shown in the picker (the ovrp image service served "dogfooding" placeholder
+  covers for some packages, e.g. Asgard's Wrath 2). `steam_art_stale` → game page reminder. No store art → generated
+  `cover.jpg`/`banner.jpg` (APK icon via `fetch.apk_icon`).
+- Game settings dialog (`ui/views/adapter_dialog.py`, metadata `patches/settings.UI`); plain patch summaries
+  (`patches/summaries.py`, `Patch.summary`, "Show technical details" = setting `ui.patch_details`); share nudge
+  (`views/game.should_ask_to_share`); saving a recipe keeps its status (was always "works").
+
 ## Hard-won facts (don't re-learn these)
 **Frame runtime (SteamOS 0.3.0, build 20260922):**
 - No AArch32: 32-bit-only APKs fail with `INSTALL_FAILED_NO_MATCHING_ABIS`. Unfixable; point to Rift + Revive.
@@ -194,7 +287,28 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
 - **Tracking only works with the headset worn.** SSH/headless launches never reach VISIBLE/FOCUSED and poses have
   flags 0x3. So automated tests prove startup (process alive, instance/session created, frames paced), never visuals.
 
+**Setup / pairing (2026-10-02, verified on the device):** Developer Mode = `"DevModeEnabled"` in
+`~/.local/share/Steam/config/config.vdf` (InstallConfigStore/developer), applied by Valve's
+`/usr/bin/steamos-polkit-helpers/steamos-devkit-mode --enable|--disable` (polkit allow_any: no password; enables/
+disables sshd, xrdp, steamos-devkit-service, debug port forwards; sentinel `/etc/steamos-devkit-enabled`). Steam
+re-asserts the config value at every start and rewrites config.vdf on exit → stop Steam, edit, helper, start.
+**Desktop Mode is a nested Plasma inside steam.service** (own XDG_RUNTIME_DIR `/run/user/1000/nested_plasma` + private
+D-Bus): `systemd-run --user` from Konsole fails ("Failed to connect to user scope bus") unless XDG_RUNTIME_DIR/
+DBUS_SESSION_BUS_ADDRESS point at `/run/user/$UID`, and stopping Steam ends the desktop and everything started in
+it → bootstrap.sh runs the Dev Mode job + Lepton request + `/paired` as a user unit (log `~/.cache/frameport-setup.log`);
+no sudo/password anywhere (verified: naive Frame → connected, password never set). Valve's devkit pairing (fallback,
+PC → Frame only): `POST :32000/register` with an **ssh-rsa** key (`connection.devkit_key`, `frame/devkit.py`) works only
+while Steam is in pairing mode (Settings → Developer → Pair new host), else 403 at once; approve hook waits 30 s.
+The Frame runs firewalld (22 and 32000 open). PC side: the setup server needs inbound TCP 8765–8767 — WSL's Hyper-V
+firewall blocks it silently (`DefaultInboundAction Block`): `pairing.ensure_reachable` adds a temporary rule via one
+UAC prompt, removed when the server stops (flag file in %TEMP%, max 35 min); hints per OS after 45 s without a request
+(`pairing.firewall_hint`). Flet 1.0 patches aren't thread-safe → `app.serialize_flet_updates()` (a dialog shown while a
+scan redraw ran never closed: "dropped a patch for unknown control").
 **Lepton:** needs an activity with category **LAUNCHER** (Quest apps often only have INFO → "APP_ACTIVITY is empty").
+**2D apps:** Lepton runs every app headless (`lepton.headless=true`, only OpenXR output reaches the headset) unless the app folder (`<base>/lepton-app/`) has a `lepton-show-flatscreen` file (liblepton/app_metadata.sh) → Waydroid window on gamescope; agent v28 `set_flatscreen` at finalize for `vr_kind == "none"`. Android 11's navbar covered the
+app's controls → patch `device.hide_navbar` (default on for vr_kind none, migration `flat_hide_navbar`) exports
+`qemu.hw.mainkeys=1` as a second line of `LEPTON_GFXRECON_FP_PROPS` (runtime alternatives failed, see
+docs/FRAME_RUNTIME.md). Verified in the headset 2026-10-02 (2048).
 Lepton = Steam app 3029110 (+ "Lepton Development" 3056000, needs Developer Mode). Per-game env: STEAM_COMPAT_INSTALL_PATH
 /DATA_PATH/SHADER_PATH, SteamAppId. Logs: `<base>/launch.log` and `~/.local/share/Steam/logs/lepton-logcats/steamlaunch-<appid>`.
 Containers are podman `lepton-steamlaunch-<appid>`. Some Unreal games create save dirs without u+rwx → launcher repairs every 2 s.
@@ -276,6 +390,12 @@ the **unpatched** upstream of our `frame.vrapi_bridge` (`native/vrapi` unchanged
 experimental CLI built with `-PwithVrApi=true` (stable jars list it but fail). The owner prefers OVRPort's fixes over
 ours where they work as well (less to maintain): compare in the headset before switching a default.
 `frameport install <pkg> --apk <file>` installs a specific (test) build signed with the game's key.
+Headset results (2026-10-02, `PATCHED/_test-ovrport-1.2.5/TESTING.md`): OVRPort's own VrApi translator fails on the
+Frame (Climb 2: requests VkFormat 37 → crash; POTW: no GLES path, missing `vrapi_GetTextureSwapChainHandle`) → keep
+`frame.vrapi_bridge`; those two changes are upstream candidates. 1.2.5 builds (its platform compat, new permissions)
+work. AC Nexus: `patch_ac_nexus_no_appsw_90` is the catalog default (owner preferred 90 Hz); `STRICT` patches are only
+taken from a catalog recipe where `applies()` holds (the AC Nexus ones need build MAIN.450412.207706.final, else the
+whole overport run fails).
 
 **Patching gotchas:**
 - UnityPy re-serialization breaks scene loading → patch QualitySettings ints in place.
@@ -325,7 +445,7 @@ GPU. Learned in the headset: quads can't be a background (the Frame draws quad l
 whatever the order: hid 4XVR's balcony/controllers), and the Frame doesn't reproject a projection layer from its own
 pose (images drawn only after head turns, or ahead from xrWaitFrame and sometimes late, wobbled);
 `equirect_flip/face/res/fps/stereo`), `stable_local`, `focus_hold` (only after 3 s FOCUSED, dips <600 ms),
-`aim_pitch/aim_yaw/aim_forward`, `refresh_rate`, `layer_debug` (diagnostics). 4XVR re-creates LOCAL spaces every 2–4 s
+`aim_pitch/aim_yaw/aim_forward`, `refresh_rate`, `layer_debug` (diagnostics); focus_hold is default-on since 2026-10-05. 4XVR re-creates LOCAL spaces every 2–4 s
 (menu recentring suspect); its theatres are baked 7680×3840 equirect2 images (`assets/100.png` …). Test 360° videos
 (NASA, public domain) are in the Frame's ~/Videos; copies in `~/Downloads/frameport-360`. 4XVR's "Internal Storage"
 lists its own `/sdcard/4XPlayer`, not Movies: agent v25 `link_media` hard-links sent files into an app's own top-level
@@ -335,19 +455,244 @@ swapchain was halved (1536/eye) in case memory is the limit (unverified). Frame
 (SteamVR runtimes, Lepton scripts, logs; never commit Valve binaries): `~/frameport-research/frame-data-2026-09-30/`.
 Not yet verified in the headset.
 
-**Lepton storage (2026-09-30):** each app's /sdcard (= /storage/emulated/0 → `<base>/lepton-data/external`) has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (liblepton/mounting.sh, only if they exist at start); agent v24 `storage_targets` reads that mapping. Android's MediaProvider canonicalises paths to /home/steamos/... and rejects every file ("doesn't appear under [/system/media...]"), `sm list-volumes` is empty: the media index never works, apps must browse folders. Lepton installs with `adb install -g` (runtime permissions granted, MANAGE_EXTERNAL_STORAGE too). Send files: `install/files.py`, `frameport frame send|storage`, GUI Frame → Send files.
+**Companion apps / intents (2026-10-03, tested with Stremio + 4XVR):** a second APK can be installed into a running
+Lepton container (`podman exec -i lepton-steamlaunch-<appid> pm install -g -S <size> < apk`) and runs there, VR
+included (4XVR in Stremio's flatscreen container: FrameBridge 72 fps, settings via LEPTON_ENV_FRAMEBRIDGE_CONFIG). But
+Lepton's services.jar (`ActivityStarter.execute`) intercepts **every** `android.intent.action.VIEW` with data (any
+scheme, explicit component or not, no property to disable): it writes `steam://openurl/<uri>` to `/lepton/steam.pipe`
+(= the host Steam client's `~/.steam/steam.pipe`) and starts nothing. So "open in external player" hand-offs (Stremio
+→ 4XVR) can't work inside Lepton; don't retry without Valve changing it. Lepton installs exactly one `*.apk` per app
+folder (two break `get_apk_path`).
+**Text input (2026-10-03, verified in the headset with Stremio VR):** Lepton's Android has no IME (`ime list` empty)
+and runs VR apps headless (`lepton.headless=true`): no Android window has input focus (`dumpsys input` FocusedWindows
+empty), so neither `input text`, a USB keyboard nor Steam's keyboard reach the app. `lepton-show-flatscreen` on a VR
+app keeps VR working (FrameBridge 72 fps) and gives the window focus; Steam's on-screen keyboard then opens for text
+fields. Unity's TMP_InputField on non-Quest Android waits for the system keyboard (`TouchScreenKeyboardShouldBeUsed`)
+and deselects a frame later unless `isKeyboardUsingEvents` (Android: `InPlaceEditing() && m_HideSoftKeyboard`);
+uGUI InputField's LateUpdate keeps the field when `InPlaceEditing()`. Patch `frame.unity_text_input` rewrites them
+(`mov w0,#0|#1; ret`) at Cpp2IL's **Offset** (= file offset; RVA differs by 0x4000 in Stremio's lib), Cpp2IL
+2022.1 pre-release (Unity 6 / metadata v31; Il2CppDumper can't), cached per libil2cpp sha. `/dev/uinput` has an ACL
+for steamos (Steam Input) → agent v33 `_keyboard` uinput keyboard ("Type on Frame") reaches everything with focus.
+Installing a second APK into a container with `pm install` re-runs Lepton's post-install hook on the **main** app
+(`lepton.active_app_id`; moves its files to /data/steam_app) and corrupts it on the next start (fix: touch the APK →
+re-bake); `cmd_real package install` skips the hook.
+**User reports (2026-10-04, issues #4-#10):** Steam shortcuts go to the signed-in account (`loginusers.vdf`
+MostRecent) else every account (agent v35 `library_users`; it used to refuse with >1 account → Play gave Steam's "Game
+configuration unavailable"); `launch` uses the shortcut's own appid and errors `NOT_IN_LIBRARY`, the app then adds it
+and plays. Unity IL2CPP fixes share one Cpp2IL run (`unity_text_input.Il2cppReturnPatch`, `ALL_TARGETS`, cache keyed by
+global-metadata.dat): `frame.unity_runtime_msaa_off` (OVRManager raises MSAA to 4x at runtime: "Switching to the
+recommended level" → Lucky's Tale restarted the headset; `OVRDisplay.get_recommendedMSAALevel` → 0) and
+`frame.unity_multipass` (Oculus XR Plugin multiview → MultiPass via `OculusSettings.GetStereoRenderingMode`; I Am Cat's
+right eye grey). Both checked against Toy Master's Cpp2IL output, not yet in a headset. VR4 quits itself (System.exit
+after the intro movie) → catalog `use_alt`. **Catalog changes reach existing games** without hardcoded migrations:
+recipes store `catalog_rev` (= `CatalogEntry.rev()`), `library._follow_catalog` re-derives non-user recipes whose entry
+changed; a maintained entry beats the user's shared copy when its `updated`/verified date is later (`catalog._newer`).
+**Round 2 of reports (2026-10-04):** VR4's campaign hang = one fragment shader reading an uninitialized loop counter
+(reporter's capture): vkshim `vk_shader_fix` setting (`<size>:<sha256>:<offset>:<words>`, from the recipe's `adapter:`;
+matched by size + SHA-256, words inserted into a copy) — on the device the module is fixed at load ("fixed shader
+module (6488 -> 6512 bytes)"); campaign itself not yet seen in a headset by us. Text settings (kind "str") stay out of
+the Game settings dialog (saving it dropped them). I Am Cat: `GetStereoRenderingMode` is inlined (no call sites) →
+`Il2cppReturnPatch.field_loads` rewrites the field read in `OculusLoader.Initialize` (Cpp2IL gives the field offset,
+`field:<name>`); verified with Toy Master: eye swapchains array=1 ×2 instead of array=2. Builds record `recipe_fp`
+(`patches/base.recipe_fingerprint`, `Patch.revision`): a changed recipe or revised patch shows "Update on Frame".
+Remembered Frames are found again after an address change (`Frame.relocate`: scan, same SSH host key, before
+login). Packaged apps show artwork by file path (`thumbs.use_file_paths`, #16). Diagnostics: this boot's kernel log.
+Device tests of requested games (2026-10-04, headless): I Am Cat, Myst 3.3.0, BattleGlide, Blade & Sorcery: Nomad
+start (RUNNING, frames). Roblox: SIGSEGV in je_free from libroblox.so ~3 s in (likely its anti-tamper vs the re-signed
+APK). BONELAB (Unity 2021.3 Vulkan, OVRPlugin 1.94): SIGSEGV with pc == fault addr in vkCreateInstance, called from
+libSLZQuestNative.so's Vulkan hooks into an unmapped (unloaded) library right after OVRPlugin's pre-init
+xrDestroyInstance; pinning openxr/vrclient libraries (RTLD_NODELETE) did NOT help — find the unloaded library with the
+linker's dlopen/dlclose logging next. Accounting+ (Unity 2017.4 built-in Oculus, libOVRPlugin + libvrapi): Unity
+never starts VR on the Frame (no OVRPlugin/OpenXR lines; runs as a 2D app), which is why its "controller setup"
+screen can't be passed — Unity 2017's Oculus device check, not the controller profiles. Cpp2IL can't read Unity 2017.
+The Frame's Android runtime (vrclient.so) knows oculus/touch_controller but not Meta's Touch Plus/Pro profiles
+(OVRPlugin suggests those too, routinely) → adapter `profile_remap`.
+Headset round 2 (2026-10-04): the Frame drops focus often (ms to 7 s; only some are presence/standby) → games pause
+or recentre (B&S Player.OnVRPresence → Teleport, BattleGlide/Unreal pauses); focus_hold now 1 s focused / 1 s max dip
+(longer must still pause). Myst crash = vrclient xrSyncActions race after FOCUSED → `sync_guard` (confirmed); its
+object glitches: app space warp suspected (FB_space_warp is advertised and used) → recipe `patch_disable_space_warp`.
+I Am Cat multipass: poses/times consistent, but every frame is submitted after the next xrWaitFrame (one period late;
+Zink + doubled draws) and the game clamps its physics step to 10 ms → judder while still; testing scale 0.8. Roblox's
+newest crash is on Fossilize's recording thread → vk_sanitize extended to own-engine libs (engine "Other").
+Accounting+: unity_oculus_check + native/ovrpshim (libfp_ovrp.so waits via ovrp_WaitToBeginFrame before Unity
+2017's ovrp_Update2) → VR in the headset at ~72 fps (2026-10-04), but stuck at "press any button" although input
+reaches its OVRInput cleanly (probe: both Touch connected 0x63, individual buttons, input focus 1) → works with issues.
+"outside of frame bounds" warnings stay (~2/frame) and are harmless.
+Steam library (GitHub #4/#21/#27, agent v38): shortcuts go to every Steam account (signed-in first; MostRecent isn't
+always the account on the Frame); stop_steam also waits for Steam's helpers; after the restart the agent re-reads
+shortcuts.vdf and writes once more if Steam put its old copy back (`shortcuts_lost`), else reports it. 0.6.3's Play
+auto-repair (`_add_then_play`) crashed (its job got a Job, not a reporter). Uploads resume on a transient OSError.
+Lepton's Android 11 has no clipboard service (134 services; checked with `podman exec … service check clipboard`):
+SDL/LÖVE apps crashed at start → `frame.sdl_clipboard` (`apk/dex.py`: in-place dex edit, nops one invoke, fixes
+the header checksum/signature; verified with LÖVE for Android 11.5, GitHub #24 Dramatic Shape). 2D apps (vr_kind none)
+keep every suggested patch that isn't about VR (`needs_vr = False`), not a fixed list. FramePort on the Frame:
+`frame/local.py` (127.0.0.1, own key authorized; "This Frame (experimental)"; app data in
+~/.local/share/frameport-app because ~/.local/share/frameport is the agent's) and Steam library changes wait while
+Desktop Mode is open. Verified on the device 2026-10-04 (install + launch test from the Frame). Library updates on the
+Frame run one at a time (agent v40 flock): two quick uninstalls used to bring a removed shortcut back (Roblox).
+Headset round 3 (owner's verdicts, 2026-10-04): Blade & Sorcery works — its freezes were the headset's wear sensor
+flickering off while worn (vrserver.txt "HMD off/on" 0.5-2 s) → per-game `focus_hold_ms=2500` (only this game reacts;
+not a default). BattleGlide works (focus_hold). Myst works with issues (object glitches; space warp ruled out, its
+recipe keeps it on). I Am Cat works with issues (judder; scale 0.8 no help). Roblox unsupported (je_free in
+libroblox, also with the Vulkan shim). Installs skip the Steam restart when the shortcut is unchanged and wait while a
+game runs (agent v37). New default fixes in FramePort's code reach games already in a library: after every app update
+`library._follow_catalog` re-derives each non-user recipe once (setting `recipes.app_version`; tests switch it off via
+`library.REFRESH_ON_UPDATE`); analysis fields added later still need a re-analysis. Troubleshooting techniques: docs/PLAYBOOK.md "Debugging techniques". Unity `boot.config` "vulkan" substring mislabels GLES games as Vulkan
+(I Am Cat ran GLES); OVRPlugin's "Unavailable OpenXR extension: XR_FB_scene" is routine (no longer triaged).
+**Round 4 (2026-10-04):** XR_KHR_android_surface_swapchain is listed by the Frame's runtime but returns
+FUNCTION_UNSUPPORTED → adapter `surface_emul` (default on, `native/adapter/surface_swapchain.c`): an ordinary runtime
+swapchain is returned, the game gets a Surface from a SurfaceTexture on a worker thread (own EGL context, JavaVM from
+XrInstanceCreateInfoAndroidKHR), frames are read back (glReadPixels) and uploaded in xrEndFrame (Vulkan: own command
+buffer + fence per panel, never waits; GLES: glTexSubImage2D). I Am Monkey's intro works (owner-confirmed). SUPERHOT
+(Quest) quit at start: its cloud save folder was mode 1700 and Lepton's app writes through the folder's group →
+launch.sh `fix_perms` adds u+rwx,g+rwx (agent v41). Lucky's Tale: Unity's Loading.PreloadManager thread grows the
+native heap ~1 GB/s until the OOM killer (Frame freezes); no fix. `perf` works as steamos (paranoid 2; ptrace_scope 1
+blocks gdb/eu-stack/debuggerd) — see PLAYBOOK "Debugging techniques". QuestCraft downloads its JRE at first run into
+`files/runtimes/JRE` (Pojlib Installer); on the Frame it was missing (unpacked by hand, unverified). WiiCompiled: its launcher shows
+(lepton-show-flatscreen) but imports .wcgame files through Android's document picker (OPEN_DOCUMENT), which Lepton
+lacks (ActivityNotFoundException) → imported by hand: libmain.so + game.json → internal files/game/<profile>,
+DATA/ → external files/WiiCompiledOpenXRVR/DATA, MOD/ → .../RetroRewind6 (decompiled with jadx). Lepton has no
+picker at all: a FramePort fix would be an injected picker activity. Generated cover/banner art used to suppress the
+Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
+**Steam library failures (GitHub #21/#30):** on some Frames Steam never loads FramePort's shortcuts.vdf entries (same SteamOS build and arm64 beta client as the dev Frame; IDs correct; file written before Steam starts): Play → console_log `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` (= "Game configuration unavailable", Steam treats the id as a store app). Cause unknown; agent v42/43 diagnostics: `launch` returns `steam` (started / error + code / silent from console_log), `collect_diag` adds `steam_library` (real Steam dir, beta, Steam start vs vdf write time, entries per account, devkit games) + `steam-console.txt` (incl. Steam's `logs/shortcuts.previous.txt` if present; steamclient.so has "LoadShortcuts: rejecting attempt to load shortcuts: invalid account ID"). **Fallback (agent v43):** when Play gets AppError_9 the agent registers the game through Steam's devkit interface (what Valve's Devkit Management Tool does, MIT: `devkit-1 steam://devkit-1/<~/.steam/steam.token>/create-shortcut?response=<file>&gameid=<id>&directory=~/devkit-game` written to ~/.steam/steam.pipe; answer file / `.error`; `~/devkit-game/<id>/launch.sh` = link to the game's launch.sh, `<id>-argv.json` ["launch.sh"] (relative to the folder), `<id>-settings.json` {steam_play 0, compat_tool ""}). Steam adds it live (no restart), picks its own appid (read back from shortcuts.vdf by DevkitGameID), shows it as a normal non-Steam game named "Devkit Game: <id>" (OpenVR 0, but VR works: owner-verified 2026-10-04), art copied to grid/<appid>*. Ids: letter first, then letters/digits/_ only (spaces, '-', leading digit → "missing/invalid arguments"). Later Plays use the devkit entry; uninstall (`devkit_unregister`, `delete-shortcut` live) and purge remove it. Verified on the dev Frame: register/launch/unregister; the AppError_9 trigger itself only in unit tests. GitHub #42 (two Steam accounts, neither MostRecent): Steam rewrote the active account's shortcuts.vdf without FramePort's entries right after starting, and added the devkit entry live without saving it, so `devkit_appid` (vdf only) failed ("Steam added the devkit entry but didn't save it"); agent v55 `devkit_appid_from_log` reads Steam's `sanitize shortcut app id "~/devkit-game/<id>/launch.sh": replacing 0 with N` console line. GitHub #41 (one account): same Steam behaviour, and every install restarts Steam, which forgets the never-saved devkit entry. Agent v56: the log fallback reads only the current session's console_log.txt; Play re-registers a devkit entry that gets AppError_9; art updates also write the devkit entry's grid art (`copy_grid_art`). Open: why some Frames' Steam never loads or saves shortcuts.vdf (single account too).
+**Exit game (GitHub #36, 2026-10-04):** `Apps.TerminateApp` (what Exit game calls; reachable for tests through Steam's CEF devtools on 127.0.0.1:8080, SharedJSContext, `Runtime.evaluate` — a stdlib websocket client is enough) closed both a normal shortcut and a devkit entry on the dev Frame within 1-3 s. SIGTERM to Steam's `reaper` alone left launch.sh + Lepton (setsid) + the container running (an earlier headset launch ran on for 87 min); SIGTERM to launch.sh cleans up in ~4 s. Agent v44: launch.sh's 2 s loop ends the game when its parent (the reaper) is gone; `upgrade_launchers` (from ensure_host_fixes) adds that to existing launchers in place. Which in-headset exit path fails is still unknown. Screenshots on the Frame: all under SteamVR's appid 250820 (`760/remote/250820/screenshots`, screenshots.vdf has creation time, no game).
+**SteamVR dashboard at game start (2026-10-04):** the dashboard (Resume game / controller / VR options) was open whenever a FramePort game started (also over Lepton's 2D launcher). Steam's UI exposes `SteamClient.OpenVR.VROverlay.{IsDashboardVisible,HideDashboard,ShowDashboard}` (CEF devtools, `steam_js` in the agent). Agent v44: launch.sh starts `_dashboard_worker` (waits for FrameBridge's first `pacing:` line in launch.log, then hides a visible dashboard for 25 s, at most 3 times; log `<base>/dashboard.log`; opt out with env FRAMEPORT_KEEP_DASHBOARD=1). Verified on the dev Frame (dashboard shown → 4XVR launched via Steam → hidden ~5 s after the first frames); not yet seen in the headset. **Headset (ITR2, 2026-10-05): too late** — Steam shows its frame menu (`valve.steam.gamepadui.frame.menu`, vrwebhelper_systemui.txt `[PooledPopups] Showing`) ~0.3 s after the game's first submitted frame (FrameBridge `new layer:`), but the first `pacing:` summary comes ~8 s later; the owner had pressed Resume (`[HideDashboard] return_to_game`) before the worker looked. Agent v52: watches from the first `new layer:` line (incremental log reads, 0.5 s polls, 30 s window). Agent v59: watches 120 s and hides up to 10 times (the menu came back after 30 s in the owner's sessions). Agent v53: stops for good once the player opens the dashboard with the controller (`toggle_dashboard_action` in vrwebhelper_systemui.txt since the worker started): v52 closed it 60 ms after each press, and the game, paused for it, stayed paused.
+**Space warp / ITR2 (2026-10-04):** Into The Radius 2 (UE5, `libUnreal.so` + OVRPlugin, Vulkan) uses Application SpaceWarp (extra swapchains `376x376 format=97` motion vectors + `format=129` depth); #35 reports flickering textures. OVRPort's `patch_disable_space_warp` has no effect on UE5, and hiding XR_FB_space_warp in FrameBridge's enumerate doesn't reach the game either: **OVRPort's dispatcher offers/enables XR_FB_space_warp itself**. FrameBridge `hide_space_warp` (per game, off) hides it and strips `XrCompositionLayerSpaceWarpInfoFB` (1000171000) from the projection views (log `hide_space_warp: removed space warp info`); the game still renders its MV swapchains. Test build installed on the dev Frame; flicker not yet checked in a headset. Heuristic: UE5 + OVRPlugin shows it as an option (off). `equirect_emul` is suggested for Unreal games whose graphics API isn't detected ("GLES or unknown"); on Vulkan it switches itself off (Myst/Riven/ITR2): harmless, but Unreal Vulkan detection is a known gap.
+**PR #34 (merged 2026-10-04, Lucas-Mathieu):** `native/adapter/audio_metadata.h` patches Meta XR Audio Wwise (only build ID e1619e7f…, Batman: Arkham Shadow 1.4.1) so queued audio metadata isn't freed while the current audio frame references it (smoke-bomb crash). Verified headless: installs ("metadata reclamation follows …"), 72 fps; we added a once-per-second scan limit. Outside PRs: review source, rebuild `artifacts/` ourselves, merge locally (contributor's commit kept), push main.
+**Heuristics eval (2026-10-04):** `scripts/eval_heuristics.py "<VR CyberDeck Portable>"` → 19/44 recipes exact, 322/352 fields (most diffs: `frame.unity_text_input` suggested where older catalog recipes lack it; the rest are runtime-only findings: use_alt, vk_shader_fix, focus_hold, sync_guard, multipass). `PATCHED/` copies aren't scored (already converted).
+**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 (agent v51, owner's choice 2026-10-05):** the newest **stable** ARM64 Proton is the default for PC VR games (`pick_proton`: asked-for name/alias, else newest installed stable, else any stable). Agent v49-50 defaulted to Experimental; the owner's headset A/B with Rick and Morty (Experimental 69 % reprojected frames, stable felt much smoother) reverted it. The game page's Customize shows `pcvr.proton_tool` as a dropdown (Stable (default) / Experimental = alias `proton-experimental`); `ensure_proton` installs a chosen one (it asks once more for the runtime Steam only names after Proton is installed; Experimental installed unattended on the device in 53 s). A PC VR launch test that fails on stable suggests Experimental (`pipeline.PROTON_TOOL`, `proton_alternative_worth_trying`, button "Try Proton Experimental and reinstall"). Remaining Rick and Morty stutter on head turns = the game rendering below the refresh rate (reprojection), not Proton.
+**USB cable link (verified 2026-10-05, cabled to the dev PC):** `usb0` is a USB **NCM** gadget (configfs g1: `ncm.usb0` + `ffs.adb`, Valve 28de:2460) set up by `usb-ncm-gadget@usb0.service`, which only runs with `ConditionPathExists=|/etc/systemd/system/adbd.service.d/steamos-devkit-enabled` = **Developer Mode only**. `usb-ncm-dnsmasq@usb0` serves DHCP with fixed `dhcp-host` entries: Frame 10.86.200.233, PC **10.86.200.234** (`frame/usb.py` FRAME_USB_IP/PC_USB_IP). Windows 11 binds its built-in "UsbNcm Host Device" (no driver); WSL mirrored sees eth 10.86.200.234. USB is high-speed (USB 2.0): upload 36.9 MB/s vs 11.3 MB/s home Wi-Fi. Frame→PC over the cable worked without a firewall change. `scripts/usb_autotest.py` (Windows via powershell.exe from WSL), `frameport frame usb-check`. Wizard "Set up with a USB cable" (`PairingServer(host=PC_USB_IP)`; the real bootstrap ran end to end over USB). Discovery dedupes by SSH host key and prefers USB > Frame hotspot > network (`discovery.dedupe`); a lost address is re-found by key (`Frame.relocate`, tested with a dead saved address).
+**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).
+**Start activity / QuestCraft / ITR2 pop-in (2026-10-05):** WiiCompiled's VR part (`QuestActivity`, SDL, process `:game`) stays behind Lepton's flat window when the launcher is shown (`device.text_input_window`). `frame.start_activity` (opt-in; analysis `extra.vr_activity` = the original APK's activity with Meta's VR category when it isn't the launcher) gives that activity's filter LAUNCHER and every other LAUNCHER becomes INFO, per element (`axml.set_start_activity`); Lepton's own `apk-info-extractor --print-activity-name` (on the Frame under Lepton/liblepton/apk_extractor) then answers QuestActivity. **OVRPort gives every MAIN activity LAUNCHER + VR categories**, so the VR activity must come from the original APK's analysis, not the converted manifest. Lepton has no activity override (`APP_ACTIVITY` is reset when app_metadata.sh is sourced). QuestCraft reaches Minecraft 1.21.5 (Fabric, Vivecraft, Sodium; LTW "Large Thin Wrapper" GL 3.0 on the Frame's Zink) and stops at `OpenGL error 1282` in `WindowFramebuffer` createTexture (Minecraft's crash report in `files/instances/1.21.5/crash-reports/`, Pojlib's `files/latestlog.txt`); the vrclient SIGSEGV / "pthread_mutex_lock called on a destroyed mutex" afterwards is only the shutdown (Unity's render thread still in vrclient while the instance is destroyed). ITR2 "models popping in and out" in game: Unreal reads user config from **internal** storage (`lepton-data/internal/<pkg>/files/UnrealGame/<Project>/<Project>/Saved/Config/Android/Engine.ini`, not external); `r.AllowOcclusionQueries=0` there broke its menus (removed again). Vulkan shim `vk_query_slots` (two slots per occlusion query) never saw ITR2 create an occlusion query pool, and the run with it crashed (Unreal RenderThread SIGSEGV, caught by sentry-native: no tombstone; the backtrace is in `cache/sentry/*/.sentry-native/*.run/*.envelope` with module offsets) - left off. Next suspect: Unreal 5 mobile HZB occlusion reading depth stored with Valve's FDM injection layer; test = launcher `VK_INSTANCE_LAYERS=''` (Lepton then loads neither VALVE_rpo nor VALVE_fdm_injection, Fossilize still). QuestCraft: LTW overrides glGetError and returns 0 with `LIBGL_NOERROR` set; Lepton passes `LEPTON_ENV_<NAME>` to the app as `<NAME>`, so catalog `lepton_env: {LEPTON_ENV_LIBGL_NOERROR: '1'}` gets Minecraft past the GL error 1282; then black picture (see the catalog entry). FrameBridge logs `new layer` once per layer type per process and projection views only for the first frames, so a second session in the same process (Vivecraft after Unity) needs `layer_debug=1`.
+**Vulkan validation / ITR2 solved (2026-10-05):** Khronos' validation layer can't come from Lepton (its layer dir is in the read-only guest image; the Linux copies on the Frame are glibc) and a global `debug.vulkan.layers` property (via the LEPTON_GFXRECON_FP_PROPS trick) kills the container at boot. Working recipe: bundle `libVkLayer_khronos_validation.so` (Khronos android-binaries release, arm64-v8a, stored uncompressed) into a test APK re-signed with the game's key (`apk.sign.sign`), install with `frameport install <pkg> --apk`, and set the Vulkan shim's `vk_validation=1` (it adds the layer at vkCreateInstance; findings under the logcat tag VALIDATION in launch.log, each message ID capped at 10). ITR2's flicker + windows behind models = Unreal's Qualcomm shader-resolve subpasses with a depth resolve of a single-sampled depth attachment (VUID-04908/-03179); `vk_spec_fixes=1` drops that resolve (its TRANSFER_DST half never applies to ITR2: the main depth is transient). Valve's VALVE_rpo layer removed ITR2's fog (catalog `lepton_env: VK_INSTANCE_LAYERS: VK_LAYER_VALVE_fdm_injection`). `r.ViewDistanceScale=2` in the internal Saved/Config/Android/Engine.ini only exists on the owner's Frame (the catalog can't write internal storage yet). Launch tests: Lepton prints a transient "is not a running context" on the first start after an APK change (agent v54 `not_started` waits 30 s for "Boot complete!").
+**GitHub #38/#39 (2026-10-05):** PowerWash Simulator stuck at "Waiting.." on a reporter's Frame = Unity sized the right-eye image rect past its swapchain (rect 268+1656 on a 1920-wide swapchain; the runtime's recommended size differs per Frame) and SteamVR rejected every frame (`xrEndFrame failed -25`, XR_ERROR_SWAPCHAIN_RECT_INVALID), after which the game stopped calling xrEndFrame. FrameBridge `rect_clamp` (default on; sizes noted in xrCreateSwapchain; clamped layers count as swapped) keeps projection/quad rects inside their swapchain; triage `swapchain-rect-invalid`. Not reproducible on the dev Frame with `scale` (Unity's eye sizing isn't just the recommended width); no regression there (72 fps). The adapter's revision was NOT bumped (that would mark every installed game outdated): affected users rebuild. The Room VR (#38) = Unity's render thread SIGSEGV in libgallium_dri.so ~30 ms after the game recreates its eye swapchain with samples=4 (FrameBridge retries samples=1); the game's own code turns MSAA on (not OVRManager); candidate fix: hide GL_EXT_multisampled_render_to_texture (GL shim) - needs the APK to test. The launch test passed both (render thread dead / no frames): triage gap.
+**Headset round 2026-10-05 (evening):** I Am Cat's judder = repeated xrLocateViews of one display time returning
+slightly different poses → FrameBridge `pose_consistency` (owner-verified, works). Lucky's Tale freeze on touching a
+save slot = OVRPort's OpenXR dispatcher converting XR_FB_haptic_amplitude_envelope with ns read as s (GitHub #9) →
+xrshim `haptic_fix` (owner-verified); its remaining short pauses were the wear sensor ("HMD off/on" 0.5-1 s in
+`logs/eyetracking.txt`, not vrserver.txt) → **`focus_hold` is on by default with 5 s** (owner's choice; C defaults
+too). The Room VR works (`unity_no_overlay_copy`). BattleSisters (Unity 2019.4 built-in VR, no libOculusXRPlugin.so)
+flooded "outside of frame bounds" ~2400/s and hung the GPU (kernel hangcheck, zink DEVICE LOST) → the ovrpshim frame
+wait now also applies to Unity 2019 without the Oculus XR Plugin (`UnityOculusCheck.legacy_loop`). Vader Immortal
+(UE4, stuck on the loading image after the intro, GitHub #49): VRP repacks carry a Frida gadget (`libfrda.so`,
+config `hijack_responses`), but OVRPort's `patch_clean_up_frida` removes its loadLibrary call, so it never runs on
+the Frame; `frame.ovr_trace` (opt-in, `native/ovrtrace`: 1138 exported ovr_* stubs → real loader functions, logcat
+tag `fp_ovrtrace`: calls, PopMessage answers, unanswered requests every 10 s) is the next diagnostic.
+**Unity built-in VR input (2026-10-05):** probe builds (`FRAMEPORT_INPUT_PROBE=1 frameport build …`; it logs
+trigger/grip crossings too) showed OVRPlugin returns the full Touch state for every controller mask (also Go masks);
+presses reach the games' OVRInput. Accounting+ (Il2CppDumper v6.7.46 reads its Unity 2017 metadata v24, run on Windows)
+passes stance selection (NewtonVR grip/trigger) but its motion warning waits for `Input.GetMouseButtonDown(0/1)`,
+which Lepton never delivers (no focused Android window) → ovrpshim registers its own
+`UnityEngine.Input::GetMouseButtonDown(System.Int32)` icall (il2cpp_add_internal_call, after Unity's: resolve first)
+that adds a click in the frame a Touch trigger or A/B/X/Y is newly pressed (`unity_oculus_check` revision 3).
+BattleSisters (Unity 2019 InputSystem/XR InputDevices via `VrHandInput`): libunity's Oculus module (OVRPlugin
+function table: a global pointer at 0x16b57c0 in this build, slots filled by name, e.g. +0x160 GetControllerState,
++0x168 State2, +0xe8 GetNodePresent) only reports controllers when `strncmp(deviceModel, "Oculus", 6) == 0` (next to
+the Go check `deviceModel == "Oculus Pacific"`); Lepton's model is "Valve Lepton" → Go/unknown → only Go masks polled,
+buttons dead. `unity_oculus_check` revision 4 (`oculus_model_checks`, Unity 2019 only) turns the 17 compares' length
+into 0 (`orr w2, wzr, #6` → `mov w2, #0` after the adrp/add of the "Oculus" literal; the string stays: it is also
+Unity's VR device name). Device result: libunity now polls `ovrp_GetControllerState(0x3)` (Touch); owner-confirmed
+2026-10-06: buttons work. Its first controller vibration then hit OVRPort's haptic-envelope bug (11 GB, OOM kill) →
+`haptic_fix` is now suggested for every game with libOVRPlugin.so (settings detect), BattleSisters works. Ruled out before: ProductName, GetNodePresent, the device-model string itself, exports.
+Accounting+ works (owner, 2026-10-06).
+**Vader Immortal (UE4, GitHub #49, 2026-10-06, headless):** stuck after the intro on an in-game image (the splash
+quad ends ~6 s in; then the game's own projection frames, 72 fps, balanced xrBeginFrame/xrEndFrame). Not the Platform
+SDK (`frame.ovr_trace`: only user + entitlement, both answered) and not the repack's Frida gadget (OVRPort's
+`patch_clean_up_frida` removes its loadLibrary). It **leaks ~430 GPU mappings (/dev/dri/renderD128) and ~20 MB a
+second** (6.5 GB + swap after 5 min, then 26 fps): page-fault stacks (perf -e page-faults, offsets resolved with the
+process maps + vrclient.so's own symbols; its text segment is at file offset + 0x4000) end in SteamVR's runtime:
+`xrBeginFrame → CSxrCompositorOpenVR::BeginFrame → SubmitExplicitTimingData → CVRCompositorSharedTextures::
+BeginGPUTimingCommandBuffer` and `xrEndFrame → CVRCompositorClient::SubmitWithArrayIndexAndTime`. Ruled out: the
+layer color scale/bias + image layout structs (FrameBridge `strip_color_bias` 1/2, diagnostic), Valve's Vulkan
+layers (VK_INSTANCE_LAYERS=""), array swapchains in general (Lucky's Tale/I Am Cat flat). Kernel tracepoints aren't
+allowed for steamos. FrameBridge: `layer_debug` logs xrDestroySwapchain and per-5 s xrBeginFrame/xrEndFrame counts;
+`frame_balance` (ends an open frame before the next begin) exists but Vader never leaves one open. Next (built,
+not yet run: the Frame slept): `layer_debug` also counts xrAcquire/Wait/ReleaseSwapchainImage per 5 s (hooked only
+with layer_debug, after the other conditional hooks) to see whether Vader skips a wait or release: it doesn't (361/361/361 per 5 s).
+FrameBridge `snapshot=N` (`snapshot_gl.c`, GLES): every N s the left-eye image the game submits is read back on its
+own context and saved as `files/fb_snap_0-7.ppm` (quarter size) — headless launches show a black headset view, this
+shows what the game draws. Vader: Lucasfilm logo (an OBB mp4: video works), then its loading card (portrait + segmented
+bar) that never advances; the async loader thread sleeps and OBB reads stop (~168 MB of a 2.7 GB pak).
+**Double launch (agent v57, 2026-10-06):** a second Play while Lepton still boots (~10 s with nothing to see) made
+the second Lepton stop the first one's container ("Waiting for steamlaunch-<appid> (PID …) to exit", exit 137
+"(starting)", "Clearing baked app data due to early exit") and both died (Vader, BattleSisters). launch.sh now takes
+`flock` on `<base>/.launch.lock` (fd 9, inherited by Lepton; the watchdog and dashboard helpers close it with
+`9>&-`); a second launch exits 0 and logs to `<base>/launch-dup.log`. `upgrade_launchers` adds it to existing
+launchers. Verified on the device (second launch during boot: ignored, the first kept running). Vader on its loading
+card ignores input too (owner pressed/held every button: presses reach the runtime, the card never changes).
+**Issue triage round (2026-10-06, owner's headset):** vibration in OVRPlugin games = 2 s vibrations updated per frame and
+stopped with amplitude 0; FrameBridge turns amplitude 0 into xrStopHapticFeedback (else each buzz ran 2 s), haptic_fix
+uses the envelope RMS (was its peak), per-game `haptic_scale` → Creed/The Boys/Jurassic World fine. Lambda1VR (TBXR):
+loader named by Build.MANUFACTURER (`frame.tbxr_vendor`), no graphics extension enabled (FrameBridge adds
+XR_KHR_opengl_es_enable + asks for the requirements on -50), always multisampled render-to-texture (GL shim gives
+single-sampled stand-ins when GL_EXT_multisampled_render_to_texture is hidden) + its xash/ data → works. Jurassic World:
+`frame.vrapi_stub`. Metro Awakening: contributor's vkshim fixes + hide_space_warp + no VALVE_rpo (jumping polygons like
+ITR2). Pinball FX VR: hide_space_warp (stutters). Eleven: a Meta online request fails after platform init → needs Meta
+services. Star Wars Tales: top half black + freeze after loading; ruled out: asset-file paks (never requested), Valve
+foveation (off: no change), GL errors (MESA_DEBUG=1: none), EGL_BAD_ACCESS once in OVRPlugin init (harmless); the game's
+eye image reads back black. BlazeRush: VrApi bridge exports + ovr*_ToString stubs + avatar stub get it to the menu room
+at 72 fps, full input reaches it (diagnostics `input 5s`: Touch type only, sticks 1.0, buttons, poses 0x8f), but the room
+draws no controllers and ignores input; avatar loader forced to its "Failed" path (no logged-in user) changed nothing.
+`frame.ovr_trace` can't trace Unity games (P/Invoke dlsym; nothing imports ovr_*). Headless: the VrApi bridge's 30 s
+head-pose deadline ends VR mode without a worn headset (not a game bug).
+**Lepton storage (2026-09-30):** each app's /sdcard (= /storage/emulated/0 → `<base>/lepton-data/external`) has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (liblepton/mounting.sh, only if they exist at start); agent v24 `storage_targets` reads that mapping. Android's MediaProvider canonicalises paths to /home/steamos/... and rejects every file ("doesn't appear under [/system/media...]"), `sm list-volumes` is empty: the media index never works, apps must browse folders. Lepton installs with `adb install -g` (runtime permissions granted, MANAGE_EXTERNAL_STORAGE too). Files: `install/files.py`, `frameport frame send|storage`, GUI Files tab (formerly Frame → Send files).
 **SteamVR per-app settings (2026-09-30):** editing steamvr.vrsettings while SteamVR runs is lost; the web API (127.0.0.1:27062 /app/setsettings) needs `x-steamvr-secret`. `native/vrsettings` = `fp_vrsettings.exe` (freestanding, OpenVR `FnTable:IVRSettings_003` as a Utility app, loads SteamVR's bin/win64/openvr_api.dll) sets them live and SteamVR persists them: section `steam.app.<shortcut appid>`, keys `preferredRefreshRate` (float) and `motionSmoothingOverride` (0 global, 1 on, 2 off, 3 always). Steam Link (vrlink) lists the Frame's rates 72/80/90/96/108/120/144 in vrserver.txt and follows the per-app preference ("host preferred N Hz"; whether the key is honoured is unverified in-headset yet). Judder metric: vrcompositor.txt session summary dropped + "Timed out. N total" (Stormland: 0 dropped but 313 timeouts in 2 min); fpsVR (`%LOCALAPPDATA%\fpsVR\*.json`, 0.1 ms histograms) gives p99 CPU/GPU ms. `pcvr.steamvr_tuning` (default on, PC only) applies on Play: highest rate whose budget ≥ p99×1.05, at least one step down, smoothing on.
 
+**Language packs (merged from PR #20, 2026-10-04):** overport's `libovrplatformloader.so` is a dispatcher that `dlopen`s Meta's own loader (`libovrplatformloader_meta.so` / `_meta_q1.so`, also `libpxrplatformloader.so`) and keeps its own message queue; `ovr_LanguagePack_GetCurrent/SetCurrent` are 8-byte `return 0` stubs in it, `ovr_AssetFile_GetList` forwards to Meta's loader. `frame.langpacks` (opt-in, `native/langpack`) serves `<tag>.lang` files from the game's data; `elf.hide_exports` marks the loader's exports STB_LOCAL (bionic and glibc only match GLOBAL/WEAK; verified for glibc, bionic's `is_symbol_global_and_defined` is from memory). `libfp_langpack.so` is built here (`python native/build.py --only langpack`) and committed. Owner-verified 2026-10-04: Deadpool VR with only `en.lang` and the patch on plays English dialogue and runs normally (headless launch tests show 2-6 fps while it loads: not a regression sign). A dispatcher answer that arrives after we answered the timed-out GetList is dropped (one answer per request); games already in a library get `lang_packs` filled after an app update (`library._refresh_data_fields`). The library logs to logcat under the tag `fp_langpack` (dirs looked in, packs found, every language-pack call), so it shows up in the game's `launch.log`; an `ovr_AssetFile_GetList` the dispatcher leaves unanswered for 1.5 s is answered with our packs alone. Deadpool VR (Unreal) accepts a pack only when its `Metadata` equals the game's own version string (`ULanguagePacksSubsystem` compares it with `%s.%s.%s.%s.%s` built from the build info, e.g. `1.0.40.356975.Quest` = versionName; found by disassembling `libUE4.so`): the patch writes the APK's versionName into the library (`@FPMETA@` slot, `with_metadata`), `FRAMEPORT_LANGPACK_META` overrides it. Deadpool VR (2026-10-04, headset): German became selectable with that Metadata, but dialogue stayed silent (even English once reported as a pack) while the path was spelled `/sdcard/Android/obb/<pkg>/x.lang`; with the `/storage/emulated/0/Android/obb/<pkg>/x.lang` spelling (Unreal's own, now listed first in `scan_dirs`) German dialogue plays. `FRAMEPORT_LANGPACK_SKIP=<tags>` or a file `fp_langpack_skip` in the obb folder leaves packs out of the list (experiments).
+
 **Unresolved (as of 2026-09-28):** Arcsmith (right-eye distortion) and Time Stall (both eyes) — swap, tracking, Valve
 layers, depth, pacing ruled out. Sniper Elite VR (DEVICE LOST), Espire 1 (Mesa GL upload crash), HITMAN 3 (freedreno
 crash): use PC versions.
 
+**Install links / FrameDrop button protocol (2026-10-07, not yet clicked end to end from a browser):** FrameDrop
+(framedropvr.com, a closed-source Windows sideloader) defines "Install with FrameDrop" buttons:
+`https://framedropvr.com/install?manifest=<url>|url=<file>` → that page opens `framedrop://install?…` (1.6 s, else its
+home page); manifest `{"schema":"framedrop.install/v1","name","files":[{"url","sha256"}]}` (name = Steam title; .apk
+or Linux .zip). `deeplink.py` (no Flet) parses framedrop://, frameport:// and the pasted https link, enforces its
+rules (https; http only on loopback; no credentials; no LAN/loopback/link-local IPs, also after DNS and redirects; URL
+ends in a file name), caps manifests at 256 KiB, ignores non-hex sha256 (FrameDrop's own example has a placeholder),
+downloads into `<data>/downloads/<slug>-<hash>/` (OBBs → `obb/` next to the APK, `.part` removed on cancel/mismatch);
+`pipeline.add_from_link` routes APK / Linux / exe and sets `title` + `title_locked` + `link` (a bare file link keeps
+FramePort's title). GUI: `views/link_dialog.py` (always asks first), Add games → "Install from a link…", CLI
+`frameport open-link [--yes --no-install --gui]`. **A `flet build` bundle can't take a URL argument** (the Flutter
+host treats any argv as a developer page URL), so `urlhandler.py` registers a script, not FramePort.exe: Windows
+HKCU `Software\Classes\{framedrop,frameport}` → hidden PowerShell `frameport-link-handler.ps1`; WSL (source runs)
+the same keys → `wsl.exe -d <distro> -e sh frameport-link-handler.sh`; Linux `frameport-links.desktop` +
+`xdg-mime`; macOS unsupported (Apple Events, paste instead). The script drops the link into `<data>/links/*.link`
+and starts FramePort unless `<data>/gui.alive` is < 10 s old (`gui.starting` stops double starts); the GUI's
+`_watch_links` thread touches the heartbeat and opens links (newest window session). Settings → Install links: one
+switch per scheme (`links.framedrop`, `links.frameport`, default on); a scheme another program owns (FrameDrop) is
+only taken with "Use FramePort for these links" (`register([s], force=True)`); off removes only FramePort's own
+registration (`MARK` in the command). Never registered with FRAMEPORT_HOME/FRAMEPORT_NO_LINK_HANDLER (tests,
+screenshots). Same round: files dropped on the Library (`ui/dropped.py`, bundles only like the Files tab), "Add a
+Windows program (.exe)…" (`pipeline.add_windows_exe`: exe in Downloads/home/drive root copied alone into
+`<data>/windows-apps/<slug>/`), patch `device.display_mode` (Automatic / VR / Flat window → `InstallContext.display`,
+`installer.show_window`). FramePort-only manifest extension `"frameport": {"description", "icon"}` (bad values ignored; icon: same URL rules,
+≤2 MiB, Pillow-checked, ≥32 px, saved as PNG in `<data>/downloads/icons/`, shown in the question by asset URL, then
+`sources.apply_custom(pkg, "icon")` unless `.picked` exists; description fills `details.description` only when
+empty). Bare file links get a title guessed from the file name (`title_from_filename`: version/arch dropped, package
+names → last part). Windows test of 0.12.1.dev191 (2026-10-07): a button click opened the dialog; but a click right
+after closing FramePort did nothing (the closed window's heartbeat was < 10 s old) → the handler scripts now wait
+up to 4 s for the link file to be taken before trusting the heartbeat, the window's CLOSE event / atexit delete
+`gui.alive`, and the Windows command runs under `conhost.exe --headless` (plain `-WindowStyle Hidden` flashed a
+console). Screens: `scripts/ui_smoke.py --links --fake-frame --game <pkg>` (tall pages: `--viewport
+1280x7000`; Flutter's popup menu ignores Escape).
+
 ## Releases, CI, GitHub
+Maintainer-only notes (accounts, credentials, key locations) live in the git-ignored `CLAUDE.local.md`.
 Public repo `github.com/spoopyghosty0/frameport` (branch `main`). Push a `v*` tag → CI (`.github/workflows/build.yml`)
 tests, builds Windows x64 / macOS arm64 / Linux x64 bundles, signs, attests and publishes a GitHub Release
 (`FramePort-*.zip/.tar.gz`, the CLI wheel `frameport-<ver>-py3-none-any.whl`, `SHA256SUMS.txt`,
-`FramePort-selfsigned.cer`; notes = "What's new" from the annotated tag message + `docs/INSTALL.md` from "First launch").
+`FramePort-selfsigned.cer`; notes = "What's new" from the annotated tag message + the short `packaging/release-footer.md`; owner: keep release
+notes short — a few "What's new" bullets, nothing long after them).
 Installed apps find the release themselves (self-update), so the notes are what users see in the update dialog.
+- **Dev builds (for testers, no release):** Actions → build → Run workflow (main), "dev" ticked, optional "notes"
+  (what to test). The bundles get version `<next patch>.dev<run number>` (`scripts/dev_version.py`, not committed) and
+  replace the rolling `dev` pre-release (`dev-release` job; same assets + SHA256SUMS). Automatic update checks ignore
+  pre-releases; testers use Settings → Updates → "Install the latest dev build…" (`updates.check_dev`,
+  `Updater.install_dev`). `parse_version` sorts 0.9.0 < 0.9.1.devN < 0.9.1, so testers get the next release normally.
+- **Upstream trackers:** issues labelled `upstream` (#73 microphone, #74 haptics, #75 VrApi bridge) list our workarounds for OVRPort bugs and how to drop them; check them against OVRPort's latest release before each release.
 - **Release checklist:** bump `src/frameport/_version.py` (the only version; `scripts/package.py` fails a tag build
   whose tag ≠ `v<_version>`), commit, `git tag -a vX.Y.Z -m "FramePort X.Y.Z" -m "<What's new, Markdown bullets>"`,
   push the commit and the tag. Never publish a release without its `SHA256SUMS.txt` (the updater refuses it) and keep
@@ -355,26 +700,32 @@ Installed apps find the release themselves (self-update), so the notes are what
 - Signing is **free/self-signed by the owner's choice** (no paid certs, no SignPath): Windows binaries are signed with
   a self-signed "FramePort (self-signed)" code-signing cert (RSA 3072, valid to 2031, SHA-256
   `4E:12:98:91:62:C0:E4:50:FB:65:1D:34:BB:73:00:09:7B:78:BE:88:5C:A7:6C:42:23:46:9B:92:A1:59:A7:6E`); secrets
-  `WINDOWS_CODESIGN_PFX` (base64) + `WINDOWS_CODESIGN_PASSWORD`. Private key: `~/.config/frameport-signing/` (WSL) and
-  the backup `PATCHED/_signing-keys/frameport-app-codesign/` — never commit it. macOS is ad-hoc signed only (Gatekeeper
+  `WINDOWS_CODESIGN_PFX` (base64) + `WINDOWS_CODESIGN_PASSWORD`. The private key is never committed (its
+  location is in `CLAUDE.local.md`). macOS is ad-hoc signed only (Gatekeeper
   needs right-click → Open; notarization would need the paid Apple program). Users still see SmartScreen unless they
   import the .cer into Trusted Root.
 - CI gotchas: `flet build` needs `--yes --no-rich-output` (it prompts to install Flutter; rich output crashes the
   Windows console) plus PYTHONUTF8; macOS builds need `--python-version 3.12 --arch arm64` (cryptography has no wheels
   for flet's default Python / x86_64 cross-build), with a PyInstaller fallback step; `astral-sh/setup-uv` has no
   floating major tags after v7 → pin the exact version; force-moving a tag starts duplicate runs (cancel one).
+- `jni` (2026-10-06): jni_flutter 1.0.4/1.0.4+1 generate bindings that require jni ^1.1.0 while Flet's build template
+  pins jni 1.0.0 → every `flet build` bundle failed (`JniVersionCheck`, "generated bindings expect package:jni
+  ^1.1.0"). pyproject `[tool.flet.flutter.pubspec.dependency_overrides] jni = "1.1.0"` fixes it (pinning
+  jni_flutter 1.0.4 does not); drop it once Flet's template moves to jni 1.1. A failed tag build publishes nothing:
+  delete and re-push the tag on the fixed commit.
+- macOS runner (2026-10-02): `macos-latest` jobs went unassigned (cancelled after 15 min, no steps); `macos-15`'s Xcode
+  16.4 fails a Flutter plugin (`NWPath has no member`); `macos-26` (Xcode 26) builds with `flet build`. The PyInstaller
+  fallback (`package.py --pyinstaller`) passes `--yes` so a failed `flet build`'s folder doesn't stop it at a prompt.
 - Windows PowerShell calls from Python (`updates._powershell()`): use `%SystemRoot%\System32\WindowsPowerShell\v1.0\
   powershell.exe` with `PSModulePath` removed from the environment — started under PowerShell 7 (CI's default shell,
   or a user's pwsh terminal) it couldn't run Get-AuthenticodeSignature (v0.3.0's Windows update smoke failed on it).
   `v0.3.0` is a tag without a release (that failed build); the updater shipped first in v0.3.1.
-- **This project's GitHub identity is `spoopyghosty0`** (a dedicated account; the machine's default gh/git login is a
-  different, personal account that must never touch this repo). `gh` (`~/.local/bin/gh`) uses it through
-  `GH_CONFIG_DIR=~/.config/gh-spoopyghosty0` (set for Claude Code in the git-ignored `.claude/settings.local.json`);
-  git pushes from this folder authenticate as it through a repo-local credential helper, and commits use the repo-local
-  identity `spoopyghosty0 <336754034+spoopyghosty0@users.noreply.github.com>`. Check with `gh api user --jq .login`
-  before any GitHub action.
-- **No Claude trailers** (`Co-Authored-By: Claude …`, `Claude-Session: …`) in commits or PR descriptions — the owner's
-  rule; history was rewritten to remove them.
+- **Never start PowerShell with `DETACHED_PROCESS` from the packaged app**: it exits 0 without running anything (found
+  in the 0.3.1→0.3.2 end-to-end test: the app quit, nothing updated). `updates.spawn_hidden` = CREATE_NEW_CONSOLE +
+  hidden window; `apply()` waits until the script has logged that it runs and raises otherwise (the app then stays
+  open). Windows installs of 0.3.1/0.3.2 can't update themselves: they need one manual download.
+- The Linux bundle is built on ubuntu-22.04: a 24.04-built Flutter bundle needs GLib 2.80 (`undefined symbol:
+  g_once_init_enter_pointer` on 22.04).
 - **The repo is public: never commit personal data** — the Frame's IP address, the Steam user id, the owner's email,
   local home paths (native builds use `-ffile-prefix-map`). History was rewritten once to remove them.
 
@@ -397,11 +748,14 @@ GLAD/GLES); Unreal → alternate no-ForceQuit build. Score changes with
 - Reinstalls keep one rollback copy (`<base>/previous-game.apk`, `settings.conf.previous`); `frameport frame cleanup`
   removes them (and `--path ~/X` extra folders under home).
 
-## Project status (2026-09-29)
+## Project status (2026-10-02)
+Self-update, the Files tab, OVRPort 1.2.5, non-Quest Android apps (vr_kind) and GUI localisation (tr(), 0.3.x) are
+in; see the sections above. Earlier state (2026-09-29):
 34 Quest games ported; the owner confirmed in the headset that all FramePort-rebuilt games work: 23 work, 5 work with
 issues (Arcsmith/Time Stall eye distortion, AC Nexus some flipped launch text, Phantom DLC button, Silhouette hands),
 6 can't run (Sniper Elite VR, Espire 1, HITMAN, and the 32-bit Journey of the Gods / Shadow Point / Sports Scramble).
-Parity: all 34 rebuilt from the dumps match the known-good builds (`docs/parity-report.md`) and were reinstalled +
+Parity: all 34 rebuilt from the dumps match the known-good builds (`docs/parity-report.md`, generated locally and
+git-ignored; 34/34 again with OVRPort 1.2.5 on 2026-10-02) and were reinstalled +
 launch-tested with 0 regressions (`docs/parity-device-report.md`). `PATCHED/` holds exactly the installed builds.
 Owner preferences: manual installs (no third-party installer apps), Python + Flet, dynamic data over hardcoding,
 free tooling only, public repo scrubbed of personal data, keep the known-good backups.

CODE_OF_CONDUCT.md

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

CONTRIBUTING.md

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

README.md

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

SECURITY.md

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

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,27 @@
+# Third-party notices
+
+FramePort is GPL-3.0-only (see `LICENSE`). It includes or downloads the following third-party work.
+
+## Included in this repository / the release bundles
+| Component | Where | License |
+|---|---|---|
+| OVRPort VrApi → OpenXR adapter (`native/vrapi`, github.com/Android-XR-Bridge/OVRPort), with FramePort's changes | `native/vrapi-bridge/`, `artifacts/arm64-v8a/libvrapi.so` | GPL-3.0 (`native/vrapi-bridge/LICENSE.upstream`) |
+| OVRPort platform compatibility library (`native/platform`) | `native/platformcompat/`, `artifacts/arm64-v8a/libovrplatformcompat.so` | GPL-3.0; Meta Platform SDK headers under the Meta Platform Technologies SDK License (`native/platformcompat/licenses/OCULUS-PLATFORM-SDK.txt`) |
+| Khronos OpenXR SDK headers | used to build the native layers | Apache-2.0 / MIT (`native/vrapi-bridge/licenses/OPENXR-SDK.txt`) |
+| Android NDK runtime (statically linked libc++) | native Android libraries | Apache-2.0 with LLVM exception, plus legacy notices (`native/vrapi-bridge/licenses/ANDROID-NDK.txt`) |
+| Flet and Flutter (desktop app runtime) | release bundles | Apache-2.0 / BSD-3-Clause |
+| flet-dropzone / desktop_drop (drag-and-drop) | release bundles | Apache-2.0 / MIT |
+| Python packages (paramiko, zeroconf, psutil, pyelftools, capstone, UnityPy, PyYAML, requests, typer, pyaxmlparser, Pillow, cryptography, …) | release bundles | their own licenses (see each package's metadata) |
+
+FramePort's own native code (the FrameBridge adapter, GL/Vulkan/OpenXR shims, the Windows helpers) is GPL-3.0-only.
+
+## Downloaded at run time (not redistributed)
+| Tool | Source | License |
+|---|---|---|
+| OVRPort / overport CLI | github.com/Android-XR-Bridge/OVRPort releases (fallback github.com/ovrport/app) | GPL-3.0 |
+| Eclipse Temurin JRE | api.adoptium.net | GPL-2.0 with Classpath Exception |
+| apksigner (Android build-tools) | dl.google.com Android repository | Apache-2.0 |
+| Revive (portable copy, only if Revive isn't installed) | github.com/LibreVR/Revive releases | GPL-3.0 |
+
+Valve's Lepton, Proton and SteamVR, and Meta's software, are used on your devices as installed by Steam / Meta;
+FramePort doesn't distribute them.

artifacts/SHA256SUMS

@@ -1,12 +1,17 @@
-0f681f54b59cfad2efc8883aee5a0971c2fba09d9ba2dca15a136b0ac74a59b8  ./arm64-v8a/libfp_vk.so
-8e00552d1ab90f82749db3caad4f773351fa8a28edcc5ea5cbd1b31c434ff32a  ./arm64-v8a/libframe_xrshim.so
-3dfcb0f2bec47857bcecc7261c58e076d872d4649718c40850f29e10c75477dd  ./arm64-v8a/libglshim.so
-dc62857b4f7a23b194060599339dfe72b38c16cdf4a9eb1b1f3b4d1fb9071a6d  ./arm64-v8a/libopenxr_loader_generic.so
+e7554c6343ee2989b0a273ee6230e65c25bfe6499eefd00de19f5f0fee58754f  ./arm64-v8a/libfp_langpack.so
+98a99cefe93079268d9158b23fa8ad5c7ade8e54c0d31526892635625eb3ef04  ./arm64-v8a/libfp_ovrp.so
+40defdaddcda53bd2649eb48076fae1622bfc2bfc88e9e03c94fc8b45af2a4f2  ./arm64-v8a/libfp_ovrtrace.so
+7522a7cfb236e48d3442d418c4820cd37760a9627c6bdef80fb0df82df5fd826  ./arm64-v8a/libfp_vk.so
+383054f8b3b41dde76d062c71856cd3163655e50009c08454bc1793f393ead65  ./arm64-v8a/libfpg.so
+06c8a17b37cb1513fdfeba87ece457a02097bb22dd0a3a3a8719fb8fea16b52a  ./arm64-v8a/libframe_xrshim.so
+9f5ba793d1804728394a8fe9e83028e13f1bc939b558892e7beb5c3662317259  ./arm64-v8a/libglshim.so
+cc5b493cadefe76ad13fd096d3f8494a140ba593e0e1692db12d284bc548c1cf  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
-32525cd0a9ee3d9993d8871cd6905bdcf22cde4f4ba28f5db6434ce7d6554758  ./arm64-v8a/libvrapi.so
-a79c598744b98b9bf581664a80bcee1a0d11a62fdcdb99f05a0f6f381b6498cd  ./armeabi-v7a/libopenxr_loader_generic.so
+aa4dc0020c77e12d41ef6ce80b23ad90c9cb7e882338eddf2261efe8645cf38d  ./arm64-v8a/libvrapi.so
+c10412dd76a65a1d587b7ed226367d1a6f2bec238c733c97ee67eb8870c868e8  ./armeabi-v7a/libopenxr_loader_generic.so
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 1aa733117cf57ccff7cf23f0425dbfd73b0332a3ef1c905ceeca0ccd0449c4e0  ./linux-arm64/XR_APILAYER_FRAMEPORT_timefix.json
 28c2430a02bbd8902c5bfb9562c6fd0e318654f9e05c095bfeb94b0450ab1b07  ./linux-arm64/libxr_frameport_timefix.so
+b10b3a5c10c3339fc63fd9f6cb4d01ea29be11a863d0ebad1389ea69fd471940  ./linux-arm64-bin/fp_venc
 c2c70f4af1a5c3e6089dff1130161dd417f8044f99ec639eeecf1083930aab16  ./win-x64/fp_oculushmd.exe
 60ebc5fea05b8945082e2ca8b9f2eb74616012a26eb50133af273dff0fcddc42  ./win-x64/fp_vrsettings.exe

bootstrap/bootstrap.sh

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

catalog/games/com.Aldin.WotW.yaml

@@ -0,0 +1,21 @@
+package: com.Aldin.WotW
+title: 'Waltz of the Wizard: Extended Edition'
+status: works
+notes: From what I tested, it just works. My only complaint is that the haptics go pretty crazy. But I don't remember
+  what it was like when I played it in my Quest. So it could be fine. 100% playable.
+tested_version: 5.0.8.1578
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 522cfebf954e1cab6054798479b0b32c5ba9e38cca83dd98db2ac0f7e3c0802a
+  app: 0.9.1
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 48
+  issue: 44
+source_hint: WotW

catalog/games/com.Appnori.AllInOneSports.yaml

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

catalog/games/com.Armature.VR4.yaml

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

catalog/games/com.CMGames.IntoTheRadius2.yaml

@@ -0,0 +1,36 @@
+package: com.CMGames.IntoTheRadius2
+title: Into The Radius 2
+status: works
+notes: Plays well (owner-verified 2026-10-05). Space warp is off, the headset's brief focus losses are hidden
+  (focus_hold, up to 2.5 s), only Valve's foveation layer is loaded (its render-pass optimizer removed the fog) and
+  an invalid depth resolve in Unreal's render passes is dropped (vk_spec_fixes; it made models flicker and windows
+  show behind them). Needs FramePort 0.10.0 or newer. Loading a save can take over a minute.
+details: Unreal Engine 5 game that uses Meta's Application SpaceWarp (extra motion-vector and depth swapchains). OVRPort's
+  patch_disable_space_warp doesn't reach Unreal Engine 5, so FrameBridge's hide_space_warp hides XR_FB_space_warp and
+  removes the space warp info from the eye images. Working config shared in GitHub issue 35. In the headset
+  (2026-10-05) the Frame dropped focus for 0.4 s and 1.0 s within ten seconds and Unreal paused each time; loading a save
+  shows no frames for 40-80 s while the game's Sentry SDK (debug mode) logs its breadcrumbs. Valve's VALVE_rpo
+  (render-pass optimizer) Vulkan layer removes the game's fog (owner-verified 2026-10-05; with only VALVE_fdm_injection
+  loaded the fog renders), which also hid the distance culling; ruled out for the remaining pop-in - Vulkan occlusion
+  query slots, Valve's FDM layer. The cause, found with Khronos' validation layer (vk_validation) - Unreal's render
+  passes use Qualcomm's shader resolve (VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM) together with a depth resolve
+  of a single-sampled depth attachment (VUID-VkSubpassDescription2-flags-04908, -03179), harmless on Quest's driver,
+  wrong depth on the Frame's Mesa; the Vulkan shim's vk_spec_fixes drops that resolve.
+tested_version: 1.2.4
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+adapter:
+  equirect_emul: 1
+  hide_space_warp: 1
+  focus_hold: 1
+  focus_hold_ms: 2500
+  vk_spec_fixes: 1
+lepton_env:
+  VK_INSTANCE_LAYERS: VK_LAYER_VALVE_fdm_injection
+verified:
+  date: '2026-10-05'
+  issue: 35
+min_app: 0.10.0
+source_hint: Into The Radius 2

catalog/games/com.CortopiaStudios.Graves.yaml

@@ -0,0 +1,19 @@
+package: com.CortopiaStudios.Graves
+title: GORN2
+status: works
+tested_version: 1.10.1
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-07'
+  known_good_sha256: d8a7949edc90c19902eb89f888ad6a350475387d630991767b3097667ad16d4c
+  app: 0.12.0
+  overport_cli: 1.2.5
+  issue: 88
+source_hint: GORN 2

catalog/games/com.CyanWorlds.Myst.yaml

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

catalog/games/com.CyanWorlds.Riven.yaml

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

catalog/games/com.FireproofStudios.TheRoomVR.yaml

@@ -0,0 +1,25 @@
+package: com.FireproofStudios.TheRoomVR
+title: The Room VR
+status: works
+notes: Plays normally (it used to stay on a grey screen).
+details: Unity 2018.4 with built-in Oculus support. It started VR only with frame.unity_oculus_check, then Unity's
+  render thread crashed in the GL driver (Zink) when OVROverlay copied a 4x4 fade texture into its overlay layer;
+  frame.unity_no_overlay_copy skips that copy (the fade still works). frame.unity_runtime_msaa_off keeps the eye buffer
+  at one sample (also GitHub issue 38).
+tested_version: '1.02'
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_no_msaa
+- frame.unity_oculus_check
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_no_overlay_copy
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-05'
+  issue: 38
+updated: '2026-10-05'
+min_app: 0.11.0
+source_hint: The Room VR

catalog/games/com.GhostlyBirdGames.BattleGlide.yaml

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

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

@@ -0,0 +1,20 @@
+package: com.ILMxLAB.VaderImmortal.ep1
+title: 'Vader Immortal: Episode I'
+status: issues
+notes: Starts in VR and plays the intro, then stays on the loading card (Vader's portrait with a progress bar).
+details: Unreal Engine 4 (GLES). After the Lucasfilm intro the game shows its loading card and never loads the next
+  scene; it keeps rendering at 72 fps and ignores input. Ruled out so far - Meta platform requests (all answered),
+  video playback (the intro is a video and plays), the no-ForceQuit build, frame and swapchain handling. The Frame's
+  SteamVR runtime also leaks about 20 MB of memory a second while the game runs, which slows it down after a few
+  minutes. Next steps - find what the loading code waits for in the game's engine library (no symbols) and report
+  the runtime leak to Valve. GitHub issue 49.
+tested_version: 1.1.1+667256.cl.387770
+engine: Unreal
+xr: VrApi
+alt_overport:
+- patch_remove_unreal_force_quit
+verified:
+  date: '2026-10-06'
+  issue: 49
+updated: '2026-10-06'
+source_hint: Vader Immortal- Episode I

catalog/games/com.NewFolderGames.IAmCat.yaml

@@ -0,0 +1,27 @@
+package: com.NewFolderGames.IAmCat
+title: I Am Cat
+status: works
+notes: Steady view with pose_consistency (the judder is gone).
+details: Unity 2022.3 with the Oculus XR Plugin falls back to GLES (Zink) on the Frame, where its single-pass
+  (multiview) rendering drew the right eye wrong (GitHub issue 8); frame.unity_multipass renders each eye in its own
+  pass (OculusSettings.GetStereoRenderingMode + its inlined read in OculusLoader.Initialize). Poses and frame times
+  are consistent, but every frame reaches the runtime one display period late (two passes on Zink) and the game
+  clamps its physics step to 10 ms. The judder came from the game locating its views about three times per frame and
+  getting slightly different poses each time; FrameBridge pose_consistency returns the same views for repeated
+  queries of one display time (proposed in GitHub issue 8). The grey right eye on the loading screen is still open.
+tested_version: 1.4.0.0
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.unity_multipass
+device:
+- device.text_input_window
+adapter:
+  pose_consistency: 1
+verified:
+  date: '2026-10-05'
+  issue: 8
+updated: '2026-10-05'
+min_app: 0.11.0
+source_hint: I Am Cat

catalog/games/com.NewFolderGames.IAmMonkey.yaml

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

catalog/games/com.PixelToys.BattleSisters.yaml

@@ -0,0 +1,26 @@
+package: com.PixelToys.BattleSisters
+title: BattleSisters
+status: works
+notes: Starts in VR; controller buttons and vibration work.
+details: Unity 2019.4 with Unity's built-in Oculus support. frame.unity_oculus_check starts VR (Meta's system-app check),
+  adds the frame wait its legacy loop never makes (without it the GPU hung, black screen) and lets Unity's Oculus
+  input accept Lepton's device model (it only reported controllers on a device named "Oculus ...", so buttons were
+  dead). haptic_fix stops the first controller vibration from freezing the Frame (OVRPort's loader read its duration
+  in nanoseconds as seconds and the game ran out of memory).
+tested_version: 1.2.4
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_no_msaa
+- frame.unity_oculus_check
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-06'
+  issue: 48
+updated: '2026-10-06'
+min_app: 0.11.1
+source_hint: Battle Sister

catalog/games/com.StressLevelZero.BONELAB.yaml

@@ -0,0 +1,20 @@
+package: com.StressLevelZero.BONELAB
+title: BONELAB
+status: issues
+notes: Build 1.2068 plays (head tracking and controls work with frame.unity_user_presence); the newer build
+  1.2974 crashes at start (Vulkan), no fix yet.
+details: The game runs (72 fps), but its player body stayed frozen - no head tracking, the controllers stuck to the
+  model, no buttons - although OpenXR input and OVRPlugin's poses were fine. A few seconds after start (when Unity
+  switches XR loaders) OVRPlugin reports the worn headset as not worn (ovrp_GetUserPresent2 -> 0), and BONELAB's
+  Marrow rig only follows the player while Unity's HMD device reports UserPresence (OpenControllerRig checks
+  XRHMD.IsUserPresent every frame). frame.unity_user_presence reports the headset as worn. Build 1.2974 crashed
+  earlier in vkCreateInstance from the game's own Vulkan hooks (libSLZQuestNative.so); not retested.
+tested_version: 1.2068.34555
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_user_presence
+verified:
+  date: '2026-10-06'
+updated: '2026-10-06'
+source_hint: BONELAB

catalog/games/com.ToastVR.RichiesPlankExperience.yaml

@@ -0,0 +1,22 @@
+package: com.ToastVR.RichiesPlankExperience
+title: Richie's Plank Experience
+status: works
+tested_version: 2.3.585
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-07'
+  known_good_sha256: 7eb1366c2398e554624a5d66aefb0c731c64b1b6944bc1726d9187f123c37fb7
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 59
+  issue: 95
+source_hint: apks

catalog/games/com.Ubisoft.ACNexusVR.yaml

@@ -9,8 +9,11 @@ notes: Some launch warning text is still upside down; the rest of the UI is fixe
   may not work.
 details: Ubisoft online login may not work. Data folder holds raw assets (start0..2, .climb, bundles), not .obb
   files; install to obb as-is.
+overport_extra:
+- patch_ac_nexus_no_appsw_90
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 89644a12bf8df956fa3d3a9a40540ba9e1fb62f63494714a05c9f05984383ac8
+  no_appsw_90: '2026-10-02, OVRPort 1.2.5 (owner: 90 Hz felt better than 72 Hz; same known issues)'

catalog/games/com.Warpfrog.BladeAndSorcery.yaml

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

catalog/games/com.beatgames.beatpaber.yaml

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

catalog/games/com.beatgames.beatsaber.lj369vr.yaml

@@ -0,0 +1,21 @@
+package: com.beatgames.beatsaber.lj369vr
+title: Beat Saber
+status: works
+tested_version: 1.40.8_7379
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 6366a5411328b21de9e2da034af78290882b3c27b7a8f0c61688196e91320055
+  app: 0.11.0
+  overport_cli: 1.2.5
+  frame_build: '20261005.6135832'
+  agent: 56
+  issue: 68
+source_hint: Beat Saber

catalog/games/com.beatgames.beatsaber.yaml

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

catalog/games/com.camouflaj.salmon.yaml

@@ -0,0 +1,17 @@
+package: com.camouflaj.salmon
+title: Marvel's Iron Man VR
+status: works
+tested_version: 0.1.0-250068
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 41e0ab90f622afd50accb0b6e2553520d30a6cc82e5ab4cbb2341b48f7316a71
+  app: 0.9.1
+  overport_cli: 1.2.5
+  issue: 47
+source_hint: Marvel's Iron Man VR

catalog/games/com.characterBank.ruinsmagus.yaml

@@ -0,0 +1,21 @@
+package: com.characterBank.ruinsmagus
+title: RUINSMAGUS
+status: works
+tested_version: 1.2.3
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-07'
+  known_good_sha256: 230e5625fbdfebb47c4d96aeb87f45270e4e6c79a33c08315c90626ab7465fe5
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261006.6173745'
+  agent: 59
+  issue: 89
+source_hint: RUINSMAGUS

catalog/games/com.coatsink.alone.yaml

@@ -0,0 +1,25 @@
+package: com.coatsink.alone
+title: Jurassic World Aftermath Collection
+status: works
+notes: Plays (owner's headset test, 2026-10-06).
+tested_version: v3.16
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_no_msaa
+- frame.unity_oculus_check
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+- frame.vrapi_stub
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 0566b39d96258fa15eb1b03f27a7ad4219eb5442b0355cd803ed1cf13313f1b3
+  app: 0.12.0
+updated: '2026-10-06'
+min_app: 0.12.0
+source_hint: Jurassic World Aftermath Collection

catalog/games/com.crowscrowscrows.AccountingPlus.yaml

@@ -0,0 +1,18 @@
+package: com.crowscrowscrows.AccountingPlus
+title: Accounting+
+status: works
+notes: Plays normally, including the "press any button" screen after choosing to sit or stand.
+details: Unity 2017.4 built-in Oculus support. frame.unity_oculus_check gets VR started (Meta's system-app check and
+  the frame wait its legacy loop never makes, libfp_ovrp.so), ~72 fps. The motion warning after the stance selection
+  waits for a mouse click (Input.GetMouseButtonDown), which a Quest delivers for the controller press and Lepton never
+  does; the same library now counts a newly pressed trigger or A/B/X/Y as that click.
+tested_version: 1.24.35
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_oculus_check
+verified:
+  date: '2026-10-06'
+updated: '2026-10-06'
+min_app: 0.11.0
+source_hint: Accounting+

catalog/games/com.drbeef.doom3quest.yaml

@@ -0,0 +1,14 @@
+package: com.drbeef.doom3quest
+title: Doom3Quest
+status: issues
+notes: PDA shows black screen.
+tested_version: 1.4.8
+engine: Other
+xr: OpenXR
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 3c733f5cd08b6fa5d9e2775b1c1aee36b5943518b5d8451ba87e3c59a702afdf
+  app: 0.12.0
+  overport_cli: 1.2.3
+  issue: 77
+source_hint: doom3quest148

catalog/games/com.drbeef.lambda1vr.yaml

@@ -0,0 +1,17 @@
+package: com.drbeef.lambda1vr
+title: Lambda1VR
+status: works
+notes: 'Needs the game data: upload the release''s xash folder to the game''s storage (Files tab) and set --msaa
+  1 in xash/commandline.txt. Owner''s headset test, 2026-10-06.'
+tested_version: 1.7.3
+engine: Other
+xr: OpenXR
+frame:
+- frame.tbxr_vendor
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 10bbccceb8d9a84ff3bcc9a21fd59db52784ff7742998bbe5b30d938dd7b97d2
+  app: 0.12.0
+updated: '2026-10-06'
+min_app: 0.12.0
+source_hint: Lambda1VR

catalog/games/com.enhanceexperience.tetriseffect.yaml

@@ -0,0 +1,18 @@
+package: com.enhanceexperience.tetriseffect
+title: TetrisEffect
+status: works
+notes: Opened the game, messed around with the menu, and played the first level. Works great.
+tested_version: 2.0.2
+engine: Unreal
+xr: VrApi
+alt_overport:
+- patch_remove_unreal_force_quit
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 9ea10027ad8b7aefba8c14f23575c9cbbcaf3b38d12b971ea9c06635721b23c1
+  app: 0.9.1
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 48
+  issue: 45
+source_hint: tetriseffect

catalog/games/com.iillusions.spacepiratetrainerquest.yaml

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

catalog/games/com.lakento.dinosquest.yaml

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

catalog/games/com.odders.shapeit.yaml

@@ -0,0 +1,19 @@
+package: com.odders.shapeit
+title: BodyCombat
+status: works
+tested_version: 3.0.0
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 1aa5b2a46b25c86db65e3355a575af14b5d4d89b967c812274f181aab2e62b33
+  app: 0.9.1
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 48
+  issue: 56
+source_hint: LES MILLS BODYCOMBAT

catalog/games/com.owlchemylabs.jobsimulator.yaml

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

catalog/games/com.parkline.wander.yaml

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

catalog/games/com.playful.LuckysTale.yaml

@@ -0,0 +1,25 @@
+package: com.playful.LuckysTale
+title: Lucky's Tale
+status: works
+notes: Plays normally; touching a save slot no longer freezes the Frame (haptic_fix).
+details: Touching a save slot vibrates the controller through XR_FB_haptic_amplitude_envelope; OVRPort's OpenXR
+  loader converts that envelope with the duration in nanoseconds read as seconds and allocates an enormous buffer, so
+  the Frame ran out of memory and froze (found by the GitHub issue 9 reporter). FrameBridge's extension shim turns the
+  envelope into a plain vibration before OVRPort's loader sees it (haptic_fix). Brief pauses came from the headset's
+  wear sensor flickering, now hidden by focus_hold (on by default).
+tested_version: 1.0.55
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-05'
+  issue: 9
+updated: '2026-10-05'
+min_app: 0.11.0
+source_hint: Luckys Tale

catalog/games/com.qcxr.qcxr.yaml

@@ -0,0 +1,28 @@
+package: com.qcxr.qcxr
+title: QuestCraft
+status: works
+notes: Minecraft runs in VR (Vivecraft, about 72 fps; drops while worlds load). Needs FramePort 0.10.0 or newer for
+  the picture (older versions show black). On first start QuestCraft downloads its Java runtime, which didn't unpack on
+  the Frame once (see details).
+details: QuestCraft downloads its Java runtime (JRE.zip from QuestCraft's GitHub releases) into files/runtimes/JRE
+  on first start; on the Frame that step once left nothing behind ("libjvm.so not found"; unpacked by hand). Two
+  Frame fixes, both owner-verified 2026-10-05. (1) Minecraft 1.21.5 checks GL errors strictly and aborted with
+  "OpenGL error 1282", an error the Frame's Mesa (Zink) reports where Quest's driver doesn't; QuestCraft's GL-to-GLES
+  layer (LTW) ignores GL errors when LIBGL_NOERROR is set, which Lepton passes from LEPTON_ENV_LIBGL_NOERROR. (2) LTW
+  passes desktop GL_DEPTH_COMPONENT32 through, which Mesa rejects, so every framebuffer was incomplete and the picture
+  black; frame.ltw_depth (automatic for APKs with libltw.so) loads GLES through a shim that asks for
+  GL_DEPTH_COMPONENT32F. Left over, harmless so far - Mesa still reports about 4 GL_INVALID_OPERATION per frame
+  ("in glthread", so the call is unknown; mesa_glthread=false would name it).
+tested_version: 6.0.0-RC4
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+lepton_env:
+  LEPTON_ENV_LIBGL_NOERROR: '1'
+verified:
+  date: '2026-10-05'
+updated: '2026-10-05'
+source_hint: QuestCraft

catalog/games/com.resolutiongames.abvriop.santacruz.yaml

@@ -0,0 +1,20 @@
+package: com.resolutiongames.abvriop.santacruz
+title: palazzo_santacruz
+status: works
+notes: Played a few levels. Passthrough also works.
+tested_version: 3.7.6.10866-release
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 394214a68297c1e5b019dc4f65b145e7bd0e98604205616364e0c151c1afd894
+  app: 0.9.1
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 48
+  issue: 46
+source_hint: abvriop

catalog/games/com.resolutiongames.cookinggame.yaml

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

catalog/games/com.roblox.client.yaml

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

catalog/games/com.steelcrategames.keeptalkingandnobodyexplodes.yaml

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

catalog/games/com.stremio.vrone.yaml

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

catalog/games/com.survios.Creed.yaml

@@ -0,0 +1,17 @@
+package: com.survios.Creed
+title: Creed
+status: works
+tested_version: CRU-386950
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+verified:
+  date: '2026-10-05'
+  known_good_sha256: c319dd95198a0a96a883aa70f6be9c843da0a265967fa4a7343ce7e6f4bfdc87
+  app: 0.10.0
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 54
+  issue: 60
+source_hint: Creed Rise to Glory

catalog/games/com.vertigogames.ImpactDevelopment.yaml

@@ -0,0 +1,26 @@
+package: com.vertigogames.ImpactDevelopment
+title: Metro Awakening
+status: works
+notes: Plays (owner's headset test) with the Vulkan shim's fixes, fragment density maps hidden, space warp off and without
+  Valve's VALVE_rpo layer (random jumping polygons in 3D without the last two, as in Into The Radius 2).
+details: Unreal 5.2 (Vulkan) quit itself (ForceQuit, use_alt), then crashed three times in the Frame's Vulkan driver
+  (Turnip) on things Quest's driver ignores - a depth resolve in a subpass without a depth attachment, image barriers
+  and image views for a missing image. Unreal turns on fragment-density-map foveation because the driver offers the
+  extension and then expects the density map from the headset, which the Frame never provides; vk_hide_fdm hides the
+  extension from the game (Valve's own foveation layer is unaffected).
+tested_version: 1.0-916944
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+use_alt: true
+adapter:
+  vk_spec_fixes: 1
+  vk_hide_fdm: 1
+  hide_space_warp: 1
+lepton_env:
+  VK_INSTANCE_LAYERS: VK_LAYER_VALVE_fdm_injection
+verified:
+  date: '2026-10-06'
+updated: '2026-10-06'
+source_hint: Metro Awakening

catalog/games/com.zenstudios.PFXVRQuest.yaml

@@ -0,0 +1,22 @@
+package: com.zenstudios.PFXVRQuest
+title: Pinball FX VR
+status: issues
+notes: Plays; mixed reality mode not working yet. Space warp off (fewer stutters).
+tested_version: '1.9'
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+adapter:
+  equirect_emul: 1
+  hide_space_warp: 1
+verified:
+  date: '2026-10-05'
+  known_good_sha256: ec5491f6a809c0ee9624e4a43aa0f2c307eb048763492d32a00ff4e0511efe54
+  app: 0.9.1
+  overport_cli: 1.2.5
+  frame_build: '20260930.6234839'
+  agent: 48
+  issue: 50
+updated: '2026-10-06'
+source_hint: Pinball FX VR

catalog/games/io.ARVORE.TheBoysVR.yaml

@@ -0,0 +1,21 @@
+package: io.ARVORE.TheBoysVR
+title: The Boys VR
+status: works
+notes: Plays with space warp off (owner's headset test, 2026-10-06; black screen reported before).
+tested_version: 1.1.0.345
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+  hide_space_warp: 1
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 5df46b1771611c607229ee59298d983a4d78a57591d4864a02da2df5d2b6f97b
+  app: 0.12.0
+updated: '2026-10-06'
+min_app: 0.12.0
+source_hint: The Boys

catalog/games/org.timecrisis.quest.yaml

@@ -0,0 +1,18 @@
+package: org.timecrisis.quest
+title: Time Crisis VR (Experimental)
+status: works
+notes: Fully playable at 120hz
+tested_version: 0.8.3
+engine: Other
+xr: OpenXR
+frame:
+- frame.sdl_clipboard
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 4e67411a8e9c0b5fbb19ca7908c4222aa5ad1b2d47a8f4b5018b4fe9c2f5324e
+  app: 0.12.0
+  overport_cli: 1.2.3
+  frame_build: '20261005.6135832'
+  agent: 59
+  issue: 80
+source_hint: TimeCrisisVR-v0.8.3-quest

catalog/games/org.wiicompiled.quest.yaml

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

catalog/games/rift.superhot_vr.yaml

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

catalog/games/ru.targem.blazerush.yaml

@@ -0,0 +1,18 @@
+package: ru.targem.blazerush
+title: BlazeRush
+status: unsupported
+notes: Starts and reaches the menu room, but the room shows no controllers and ignores all input (it all reaches
+  the game); no fix yet.
+tested_version: 1.0.349
+engine: Other
+xr: VrApi
+frame:
+- frame.vrapi_bridge
+- frame.avatar_stub
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 7cbd5d4252788ccd3c95b5c1841dcc798ea029d687938c024e33bd698ba17671
+  app: 0.12.0
+updated: '2026-10-06'
+min_app: 0.12.0
+source_hint: BlazeRush

catalog/games/unity.SUPERHOT_Team.SUPERHOT_VR_QA.yaml

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

catalog/games/us.lighthaus.nanocellx.yaml

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

catalog/triage.yaml

@@ -8,13 +8,38 @@ signatures:
     severity: fatal
     diagnosis: Lepton found no activity with category LAUNCHER.
     suggest: [frame.launcher]
+  - id: linux-x86-no-fex
+    pattern: '(cannot execute binary file: Exec format error|exec format error)'
+    severity: fatal
+    diagnosis: An x86_64 Linux program was started directly; the Frame's arm64 CPU needs FEX (x86 translation) for it. Reinstall the app with FramePort 0.12 or newer, which installs FEX and starts the program through it.
+    suggest: []
   - id: no-arm64
     pattern: 'INSTALL_FAILED_NO_MATCHING_ABIS'
     severity: fatal
     diagnosis: 32-bit-only APK. The Steam Frame has no AArch32; this cannot run. Use the PC (Rift) version via Revive.
     suggest: []
+  - 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 app calls Android 12/13+ classes (android.window.*, VarHandle fences) that the Frame's Android 11 (API 30) container doesn't have; it needs a newer Android (e.g. minSdk 34 apps). Nothing to patch - it can't run until Valve updates the Frame's Android.
+    suggest: []
+  - id: web-wrapper
+    pattern: '(Creating TwaLauncher for com\.oculus\.browser|NameNotFoundException:? com\.oculus\.browser)'
+    severity: fatal
+    diagnosis: The app is a website in an Android wrapper (Trusted Web Activity) that opens Meta's browser (com.oculus.browser), which the Frame doesn't have, so nothing opens. There's no game to port - open the website (TWALauncherActivity's "Using URL" line) in a browser instead.
+    suggest: []
+  - id: unity-render-crash
+    pattern: 'CRASH\s*:.*#\d+\s+pc [0-9a-f]+\s+\S*libgallium_dri\.so'
+    severity: fatal
+    diagnosis: Unity's render thread crashed inside the Frame's GL driver (Mesa/Zink); the picture freezes or stays grey. Known triggers - an OVROverlay copy (try "Unity - skip OVROverlay layers", e.g. The Room VR), MSAA switched on at runtime, a GPU hang (zink DEVICE LOST).
+    suggest: [frame.unity_no_overlay_copy, frame.unity_runtime_msaa_off]
+  - id: swapchain-rect-invalid
+    pattern: 'xrEndFrame failed -25\b'
+    severity: fatal
+    diagnosis: The runtime rejects the game's frames because an image rect reaches past its swapchain (by a few pixels on some Frames); the game stops drawing (e.g. stuck at a "Waiting" box). FrameBridge from FramePort 0.11.0 clamps the rects - rebuild and reinstall the game.
+    suggest: [frame.adapter]
   - id: missing-ovr-symbol
-    pattern: '(UnsatisfiedLinkError|cannot locate symbol) .*"?(ovr_[A-Za-z0-9_]+|ovrMessageType_ToString)'
+    pattern: '(UnsatisfiedLinkError|cannot locate symbol) .*"?(ovr_[A-Za-z0-9_]+|ovr[A-Z][A-Za-z0-9]*_ToString)'
     severity: fatal
     diagnosis: The game imports Meta platform functions overport's loader lacks.
     suggest: [frame.ovrstubs, frame.ovrplatformcompat]
@@ -44,7 +69,49 @@ signatures:
     pattern: 'zink.*DEVICE[_ ]LOST|VK_ERROR_DEVICE_LOST'
     severity: fatal
     diagnosis: The GPU hung (Zink/Mesa). For GLES Unity games MSAA render-to-texture is the usual cause.
-    suggest: [frame.unity_no_msaa]
+    suggest: [frame.unity_no_msaa, frame.unity_runtime_msaa_off]
+  - id: unity-runtime-msaa
+    pattern: 'recommended MSAA level is [248]\. Switching to the recommended level'
+    severity: info
+    diagnosis: The game's OVRManager turns MSAA on at runtime (QualitySettings can't keep it off). On GLES this can
+      hang the Frame's GPU or restart the headset; if it does, keep it off in the game's code.
+    suggest: [frame.unity_runtime_msaa_off]
+  - id: runtime-input-crash
+    pattern: 'vrclient\.so[^\n]*(UpdateActionStateInternal|sxr_xrSyncActions)'
+    severity: fatal
+    diagnosis: The Frame's runtime crashed in its controller-input code (xrSyncActions), typically right after the game
+      got focus. sync_guard serialises input syncs and pauses them briefly after focus returns.
+    suggest: [adapter.sync_guard]
+  - id: focus-dip-teleport
+    pattern: 'OnVRPresence[^\n]*Teleport'
+    severity: warning
+    diagnosis: The game moves the player when the headset reports presence again, which the Frame's brief focus dips
+      trigger (the view jumps). focus_hold hides dips under 600 ms.
+    suggest: [adapter.focus_hold]
+  - id: unity-vr-device-none
+    pattern: 'NewtonVR.*(not setup properly|no headset found)|Loaded VR device: None|XR: Oculus could not be loaded'
+    severity: fatal
+    diagnosis: Unity didn't start its Oculus VR device (older Unity checks for Meta's system apps first), so the game
+      runs as a hidden 2D app.
+    suggest: [frame.unity_oculus_check]
+  - id: sdl-no-clipboard
+    pattern: 'ClipboardManager\.addPrimaryClipChangedListener|SDLClipboardHandler\.<init>'
+    severity: fatal
+    diagnosis: An SDL app (SDL2 / LÖVE) crashed at start because Lepton's Android has no clipboard service.
+    suggest: [frame.sdl_clipboard]
+  - id: controller-profile-rejected
+    pattern: 'PATH_UNSUPPORTED.*xrSuggestInteractionProfileBindings|xrSuggestInteractionProfileBindings.*(-48|PATH_UNSUPPORTED)'
+    severity: info
+    diagnosis: The runtime rejected controller bindings for a profile it doesn't know (Meta's Touch Plus/Pro). Usually
+      harmless (Meta's OVRPlugin suggests plain Touch too); a game that suggests only these gets them again as Touch
+      (profile_remap, on by default; log "controller profile ... -> oculus/touch_controller").
+    suggest: []
+  - id: input-call-failed
+    pattern: 'input_diag: unsupported: (xrStringToPath|xrCreateAction|xrAttachSessionActionSets|xrSyncActions) ->'
+    severity: warning
+    diagnosis: The runtime refused one of the game's controller-input calls (logged by input_diag; the line names the
+      call, the result and the argument), so controls set up through it don't work.
+    suggest: []
   - id: gl-shader-failed
     pattern: 'GLShim\s*: SHADER COMPILE FAILED|#extension directive is not allowed in the middle|could not implicitly convert operands'
     severity: error
@@ -55,8 +122,37 @@ signatures:
     severity: error
     diagnosis: The game submits a VrApi layer type the bridge can't show; whole frames are dropped (black screen).
     suggest: []
+  - id: graphics-requirements-missing
+    pattern: '(XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING|Failed to create XR session: -50\b|xrCreateSession[^\n]*-50\b)'
+    severity: fatal
+    diagnosis: The game creates its OpenXR session without asking for the graphics requirements first; Meta's runtime
+      allows that, the Frame's doesn't (e.g. Lambda1VR). Current FrameBridge builds ask on the game's behalf and retry -
+      rebuild the game.
+    suggest: [frame.adapter]
+    supersedes: [native-crash]
+  - id: avatar-driver-missing
+    pattern: 'OVRAvatar-Loader: DisplayErrorAndExit'
+    severity: fatal
+    diagnosis: Meta's avatar library can't find its driver (it needs Meta's Horizon app) and stops the game (e.g.
+      BlazeRush). Replace it with a do-nothing library; the game runs without Meta avatars.
+    suggest: [frame.avatar_stub]
+    supersedes: [native-crash, java-crash]
+  - id: vrapi-symbol-missing
+    pattern: 'cannot locate symbol "vrapi_\w+"'
+    severity: fatal
+    diagnosis: The game needs a VrApi function its libvrapi.so doesn't have (e.g. BlazeRush before the bridge gained
+      vrapi_PollEvent). Rebuild with the current FramePort; if it persists, report the function name.
+    suggest: []
+    supersedes: [native-crash, java-crash, dlopen-failed]
+  - id: vrapi-before-init
+    pattern: 'VrApiLoader: vrapi_\w+ was called before vrapi_Initialize'
+    severity: fatal
+    diagnosis: Meta's VrApi loader stopped the game. Its OVRPlugin runs on OpenXR but still calls a VrApi function
+      without starting VrApi (e.g. Jurassic World Aftermath); the VrApi bridge can't stand in for this loader.
+    suggest: [frame.vrapi_stub]
+    supersedes: [direct-vrapi, native-crash]
   - id: direct-vrapi
-    pattern: 'vrapi_Initialize|VrApi.*not supported|libvrapi\.so.*(not found|failed)'
+    pattern: '(?<!called before )vrapi_Initialize|VrApi.*not supported|libvrapi\.so.*(not found|failed)'
     severity: warning
     diagnosis: The engine talks to VrApi directly; it needs the VrApi bridge.
     suggest: [frame.vrapi_bridge]
@@ -79,7 +175,8 @@ signatures:
       agent's controller_models command).
     suggest: []
   - id: scene-missing
-    pattern: 'XR_FB_scene|XR_FB_spatial_entity.*(not supported|UNSUPPORTED)|xrQuerySpacesFB'
+    # not OVRPlugin's routine "Unavailable OpenXR extension: XR_FB_scene" (printed by every OVRPlugin game)
+    pattern: '(?<!Unavailable OpenXR extension: )XR_FB_scene|XR_FB_spatial_entity.*(not supported|UNSUPPORTED)|xrQuerySpacesFB'
     severity: warning
     diagnosis: The game uses the Meta scene (room) API; enable the adapter's guardian-based room emulation.
     suggest: [adapter.scene_emul]
@@ -88,6 +185,18 @@ signatures:
     severity: warning
     diagnosis: Runtime lacks timespec time conversion (emulated by the current adapter build).
     suggest: [frame.adapter]
+  - id: unreal-vulkan-driver-crash
+    pattern: '#00 pc [^\n]*/vulkan\.freedreno\.so[\s\S]{0,3000}?lib(Unreal|UE4)\.so'
+    severity: fatal
+    diagnosis: The Frame's Vulkan driver crashed on a call from Unreal. Unreal 5 passes things Quest's driver ignores - a depth resolve in a subpass without a depth attachment (fixed by the Vulkan shim), image barriers and image views for a missing image when it expects fragment density maps (foveation) from the headset (e.g. Metro Awakening).
+    suggest: [frame.vk_sanitize, adapter.vk_spec_fixes, adapter.vk_hide_fdm]
+    supersedes: [native-crash]
+  - id: unreal-fdm-missing
+    pattern: 'vk shim: left out \d+ image barrier\(s\) without an image \(first: layout \d+ -> 1000218000'
+    unless: 'vk shim: fragment density map extensions hidden'
+    severity: warning
+    diagnosis: Unreal expects fragment density maps (foveation) from the headset, which the Frame doesn't provide; its image views for them crash the Frame's driver a few seconds later (e.g. Metro Awakening).
+    suggest: [adapter.vk_hide_fdm]
   - id: fossilize-renderpass
     pattern: '#0\d pc [^\n]*libVkLayer_fossilize\.so[\s\S]{0,4000}?FVulkanRenderPass::FVulkanRenderPass'
     severity: fatal
@@ -112,6 +221,14 @@ signatures:
     diagnosis: overport's OpenXR dispatcher aborted on a swapchain larger than 4096 px (video players, big textures).
     suggest: [frame.swapchain_limit]
     supersedes: [native-crash]
+  - id: ovr-microphone-crash
+    pattern: 'ovr_Microphone_GetOutputBufferMaxSize\+'
+    severity: fatal
+    diagnosis: The game asked OVRPort's Meta platform library for the microphone buffer size before starting the
+      microphone, and the library read the not-yet-opened audio stream (SIGSEGV in libaaudio.so, e.g. Unreal's Oculus
+      voice chat a few seconds after the logo).
+    suggest: [frame.ovr_microphone]
+    supersedes: [native-crash]
   - id: native-crash
     pattern: 'Fatal signal (\d+) \(SIG[A-Z]+\)'
     severity: fatal
@@ -226,6 +343,25 @@ signatures:
     diagnosis: The game crashed under Wine/Proton (set the Proton debug log and check steam-<appid>.log).
     suggest: [pcvr.proton_log]
 
+  - id: save-folder-permission
+    pattern: "(We don't have write permission to|UnauthorizedAccessException: Access to the path \"/(sdcard|storage/emulated/0)/Android/data/)"
+    severity: error
+    diagnosis: The game can't write to a folder it created in its storage (e.g. SUPERHOT's cloud/data, mode 1700, which
+      makes it quit at start). FramePort's launcher (agent 41 or newer) gives such folders owner and group write
+      permission before and during every launch; update the game on the Frame (reinstall) to get the new launcher.
+    suggest: []
+  - id: surface-swapchain-emulated
+    pattern: 'surface_emul: emulated Android surface swapchain'
+    severity: info
+    diagnosis: The game plays a video on a panel through an Android Surface (XR_KHR_android_surface_swapchain), which the
+      Frame's runtime refuses; FrameBridge emulates it (surface_emul) and copies each video frame into the panel.
+    suggest: []
+  - id: surface-swapchain-failed
+    pattern: 'surface_emul: (setup failed|upload failed|EGL context failed|Vulkan upload path unavailable)'
+    severity: warning
+    diagnosis: FrameBridge couldn't emulate an Android video panel (XR_KHR_android_surface_swapchain); the panel stays
+      empty, and a game waiting for its intro video may stay black (e.g. I Am Monkey's intro).
+    suggest: []
 milestones:  # progress markers, in order; the furthest one reached is reported
   - {id: pcvr-launch, kind: pcvr, pattern: 'FramePort: launching|Launched injector with', label: Launcher started}
   - {id: pcvr-oculus-hmd, kind: pcvr, pattern: 'FramePort oculushmd: OculusHMDConnected event ready', label: Oculus headset event provided}

docs/ARCHITECTURE.md

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

docs/AUDIO_METADATA.md

@@ -0,0 +1,31 @@
+# Meta XR Audio metadata lifetime
+
+FrameBridge automatically handles metadata retirement in the verified AArch64
+Meta XR Audio Wwise build (`e1619e7fb839badf0ea5ecc22d9f028d0b17c34d`). It requires
+the build ID and exact function prologues; other builds and 32-bit adapters are
+left unchanged. No additional patch switch or recipe entry is required.
+
+The SDK queues terminated metadata for deletion, then drains those queues before
+reading the current `AkAudioObjects` snapshot. In Batman: Arkham Shadow, that
+snapshot can still reference queued metadata during smoke-bomb playback. The
+audio thread subsequently clears its dirty flags at offset 8 through the stale
+pointer. A hardware watch captured this store in
+`OculusEndpointSink::ConsumeObjectExperimentalMetadata`, at library offset
+`0x2ced90`. Reallocated input tree nodes occupy the same 48-byte size class;
+the stale store corrupts their right pointer and the game crashes later.
+
+`native/adapter/audio_metadata.h` wraps the audio consumption boundary to make
+the current snapshot available to metadata cleanup. `audio_metadata_queue.h`
+retains queued objects still referenced by that snapshot, then reclaims them
+normally when the references disappear. It preserves the SDK's queue mutex,
+virtual deleting destructor, audio parameters and processing. There is no timed
+quarantine, replacement allocator, audio suppression or diagnostic memory arena.
+
+Synthetic regression tests exercise mixed referenced and unreferenced queue
+entries, both metadata types, subsequent retirement, and cleanup without a live
+snapshot. On-headset smoke-bomb tests first showed the observed overwrite stopped,
+then passed with ordinary allocations and all memory diagnostics removed.
+
+The existing `frame.adapter` install step includes the repair in its packaged
+adapter and updates already wrapped APKs. Rebuild the adapters and checksums with
+`python native/build.py --only adapter`.

docs/COMPATIBILITY.md

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

docs/FAQ.md

@@ -0,0 +1,31 @@
+# FAQ
+
+## How should I lay out a game that has OBB files (an APK plus a data folder)?
+
+Give every game its own folder, put the APK in it, and put the game's data next to the APK in a folder named
+after the game's **package name** (the name the `.obb` files contain, e.g. `com.Armature.VR4`):
+
+```
+Games/                                  ← scan this folder (Add games → Scan a folder)
+├── Resident Evil 4/                    ← one folder per game (any name)
+│   ├── VR4.apk                         ← the APK (any file name)
+│   └── com.Armature.VR4/               ← the data folder: exactly the package name
+│       ├── main.203.com.Armature.VR4.obb
+│       └── patch.203.com.Armature.VR4.obb
+└── Beat Saber/
+    └── com.beatgames.beatsaber.apk     ← games without OBBs: just the APK
+```
+
+- **Data folder name:** the package name (`com.Armature.VR4` above), or `obb`. FramePort uses the first of the two
+  that exists and isn't empty.
+- **Everything in that folder is copied** to the game's `Android/obb/<package>/` on the Frame, subfolders included.
+  So games that ship raw data files instead of `.obb` files work the same way.
+- **One game per folder.** Several APKs in one folder count as one game; FramePort uses the first and keeps the others
+  as alternates.
+- **Scanning:** pick the folder that contains the game folders (`Games/` above) to add them all, or one game's folder
+  to add just that game. FramePort looks up to 5 levels deep.
+- **A single game:** Add games → Add an APK file… works with a lone APK too. Its data is found when the data folder sits next
+  to the APK, named as above.
+
+Not sure of the package name? Look at the OBB file names: `main.<version>.<package name>.obb`. Or add the APK
+first: the game's page shows the package name under **Details**.

docs/FRAME_RUNTIME.md

@@ -14,6 +14,36 @@
   `keyring = false` in `~/.config/containers/containers.conf`; a reboot clears already-leaked keys.
 - Picks the activity with category LAUNCHER (`APP_ACTIVITY`). Game data is visible at `/sdcard/Android/{obb,data}/<pkg>`.
 - 64-bit only (no AArch32).
+- `<install>/lepton-shaders/` holds Mesa's shader cache (Lepton sets `mesa.shader.cache.dir=/data/shaders`):
+  `foz_cache.foz` + `foz_cache_idx.foz` per graphics driver (Turnip Vulkan, zink GL), typically 4–6 files and 7–19 MB
+  per game, 2D apps included. It speeds up later starts; deleting it only costs one slower start.
+- **2D apps** (verified 2026-10-02 with an open-source 2048 game): Lepton runs every app headless
+  (`lepton.headless=true`; only OpenXR output reaches the headset) unless the app folder (`STEAM_COMPAT_INSTALL_PATH`)
+  contains a file `lepton-show-flatscreen` (`liblepton/app_metadata.sh`): then Android (11, Waydroid) gets a Wayland
+  window shown as a flat panel in the headset. FramePort creates the file for Android apps without VR. Android's
+  back/home/recents bar is drawn over the app's own controls; `qemu.hw.mainkeys=1` removes it, but it's only read at
+  boot and Lepton has no setting for extra properties, so patch `device.hide_navbar` (default on for apps without
+  VR) passes it as a second line of a
+  `LEPTON_GFXRECON_*` value (Lepton copies those into the boot properties unescaped). Runtime alternatives didn't
+  work on Android 11: `policy_control` is gone, `cmd statusbar send-disable-flag home recents` has no `back` and
+  moves the back button onto the app's controls, the `sysui_nav_bar` layout and disabling SystemUI had no effect.
+
+## Where FramePort keeps games (internal storage, microSD)
+- Every game has an **anchor** on internal storage: `~/Applications/quest-frame/<pkg>/` with `launch.sh`,
+  `deployment.json`, `artwork/` and `plays.log`. Steam's shortcut points at the anchor's `launch.sh`, so it never
+  changes when the files move.
+- The game's files (`lepton-app/`, `lepton-data/` = saves, `lepton-shaders/`, `settings.conf`, `launch.log`; PC VR:
+  `game/`, `revive/`, `compatdata/` = Proton prefix; Linux: `app/`) live in `deployment.json["base"]`: the anchor
+  itself on internal storage, or `<mount>/FramePort/<pkg>` on another drive (GitHub #90, agent v63).
+- SteamOS mounts removable drives (microSD) under `/run/media/<user>/<label or uuid>`; the agent's `drives` reads
+  `/proc/mounts` (plus the drives of Steam library folders) and refuses vfat/exfat/ntfs (Lepton's data and Proton
+  prefixes need Unix owners, permissions and symlinks) and read-only mounts. A drive that isn't mounted is an error for
+  new installs (never a silent fallback to internal storage); `list_installed` marks games on it `drive_missing` and
+  their launchers stop with "storage not mounted?".
+- `move` copies with `cp -a` inside `podman unshare` (files Lepton's containers own belong to subordinate user ids),
+  compares file count + bytes, retargets absolute symlinks into the old folder (the LibOVRRT → Revive redirect), points
+  `launch.sh` at the new folder and only then deletes the old copy; on the same filesystem it renames instead.
+  Moving a game whose Lepton data holds absolute paths, or a PC VR prefix, is not yet verified on the device.
 
 ## OpenXR runtime (as seen by games through overport's loader)
 - Instance extensions present include KHR_android_create_instance (must be enabled; the adapter adds it),
@@ -42,6 +72,10 @@
 ## Graphics stack
 - Vulkan: freedreno (Mesa Turnip); Valve injects `VK_LAYER_VALVE_rpo` and `VALVE_fdm_injection` via
   VK_INSTANCE_LAYERS (set `VK_INSTANCE_LAYERS=""` through `device.lepton_env` to test without them).
+  The FDM layer follows each eye's gaze; one-eye jitter in some games (GitHub #69) is fixed per game with
+  `device.foveation`: `fixed` = `FDM_DEBUG=disable_offsets`, `off` = `VK_INSTANCE_LAYERS=""`. Lepton passes `FDM`,
+  `FDM_DEBUG`, `FOVE_LEVEL` and `FDM_SWAPCHAIN_SIZE` through to the container (liblepton/mounting.sh PASSTHROUGH_VARS);
+  the layers are chosen on the host, so setting them inside the game does nothing.
 - GL ES: Zink (Mesa GL on Vulkan). Strict GLSL (see PLAYBOOK) and occasional `DEVICE LOST` with MSAA render-to-texture.
 
 ## Proton / Windows games (surveyed 2026-09-29; running a Rift game under it not yet verified)
@@ -52,6 +86,17 @@
   SteamLinuxRuntime_4). None are installed by default.
 - `steam -ifrunning steam://install/<appid>` only opens a confirmation dialog in the headset. The agent's unattended
   mode writes an appmanifest stub (StateFlags 1026, installdir from appinfo) and restarts Steam, which then downloads it.
+- **x86_64 Linux apps (agent v61; verified on the device 2026-10-07: an x86_64 glibc test program installed + launch test RUNNING, "machine=x86_64 glibc=2.41"):**
+  FEX is Steam app 3127680 (`fex`, installs as `common/FEX-Emu`, ~6 MB, 21 s via the appmanifest-stub path:
+  `install_proton` / `proton_status` with `kind: linux_x86`). Its toolmanifest commandline is
+  `/fex-compat-tool %verb% --`, **no** require_tool_appid: it does not use the Steam Linux Runtime. fex-compat-tool
+  (Python) runs `<FEX-Emu>/usr/bin/FEX` with RootFS `/usr/share/guestos/fex-mesa` (part of the SteamOS image: an
+  x86 Arch-style root with glibc 2.41, Mesa, graphics_provider.json for x86_64 + i386), emulates x86_64 and i386
+  (emulator.json), honours `STEAM_FEX_TSOENABLED`, `STEAM_FEX_MULTIBLOCK`, `STEAM_COMPAT_FEX_CONFIG`, sets
+  `tu_override_uncached_as_cache_coherent=true` and logs to `/tmp/fex-compat-tool-<pid>.log`. It **exits 1 ("No compat
+  data path?") without `STEAM_COMPAT_DATA_PATH`** (keeps Config.json/AppConfig/Server/Telemetry in `<it>/fex-emu/`):
+  the Linux launcher exports `<base>/compatdata`. Version seen: FEX-2607-76-g37265b1. ldd can't read x86 programs,
+  so the missing-library check is skipped for them; an x86_64 AppImage is extracted through the same chain.
 - The command Steam runs is built from each tool's `toolmanifest.vdf` (`commandline`, `require_tool_appid`):
   `<SLR4-arm64>/_v2-entry-point --verb=waitforexitandrun -- <Proton>/proton waitforexitandrun <exe>`.
 - Proton sets up VR (vrclient/wineopenxr registry) only when `SteamGameId` is set (steam_helper `setup_vr_registry`).
@@ -92,3 +137,119 @@
 - Processes started from Steam (Konsole, SSH sessions?) share steam.service's cgroup: use `systemd-run --user`.
 - SSH: `sshd` must be enabled (`sudo systemctl enable --now sshd`), which needs a user password (`passwd`).
 - mDNS: avahi-daemon runs by default; hostname `frame` → `frame.local`.
+- Desktop Mode menu entries (GitHub #84, agent v63): Linux apps get `~/.local/share/applications/frameport-<slug>.desktop`
+  (+ an executable copy in `~/Desktop` when that folder exists; Plasma starts executable `.desktop` files there
+  without a trust prompt), `Exec=env FRAMEPORT_DESKTOP=1 "<anchor>/launch.sh"`, marked `X-FramePort-Package=<pkg>`.
+  Plasma's launcher exits right after starting the program, so with `FRAMEPORT_DESKTOP=1` the Linux launcher skips
+  its "Steam parent gone → end the app" watchdog and keeps the desktop's DISPLAY/WAYLAND_DISPLAY instead of taking
+  gamescope's from Steam. Not yet tried from the Frame's Desktop Mode.
+
+## Video of the headset view (surveyed 2026-10-05; used by the Live view tab)
+- `steamvr-v4l2cam.service` (user unit, part of gamescope-session.target, `Restart=always`) runs SteamVR's
+  `/opt/steamvr/bin/linuxarm64/v4l2cam --output=99`: it reads the compositor's "Headset View" (IVRHeadsetView) and
+  writes it to a v4l2loopback webcam named **"SteamVR"** (`/dev/video99`, 1920x1080 RGB24, advertised 30 fps, frames
+  arrive at the display rate). Nothing on the Frame reads it by default; idle it costs nothing, read ~0.2 core.
+  It shows what the wearer sees (SteamVR home, Steam's panels; a game's layers are expected but not yet seen in it).
+  Black and ~1 fps (one frame per ~1.0 s) while the headset sleeps (standby): a 30 fps stream then repeats each
+  frame in bursts, which looks like a stall in a player. Its size follows SteamVR's headset view (v4l2cam has no size
+  option), so the live view only scales down (360p/480p/720p/1080p) or sends it as is ("full").
+- Sound: `pactl get-default-sink` (`alsa_loopback_device.stereo.alsa_output.platform-sound.HiFi__Speaker__sink`) and its
+  `.monitor` source carry what the headset plays; the Frame's ffmpeg has the `pulse` input and `aac`. Timestamps: pulse
+  uses the wall clock, v4l2 CLOCK_MONOTONIC → `-ts mono2abs` on the v4l2 input. Don't force
+  `-use_wallclock_as_timestamps` on the pulse input: it stamped bursts of AAC packets with one time.
+- Steam's own game recording / Remote Play / broadcast capture the **gamescope** PipeWire node (`CDesktopCapturePipeWire:
+  ... node path: gamescope`): with gamescope's `--backend openvr` that's only the flat Steam UI, not VR. Steam's arm64
+  `libvideo.so` encodes with x264 (vaapi/nvenc paths don't apply). No cast/spectator feature for the Frame's own VR view
+  exists in Steam's UI; the SteamVR web server (27062) has no mirror route.
+- Encoding: the Qualcomm encoder (`/dev/video23` qcom-iris-encoder, V4L2 M2M) doesn't work with the stock tools (ffmpeg
+  `h264_v4l2m2m` hangs, gst `v4l2h264enc` not-negotiated). ffmpeg + libx264 works: FramePort's live view
+  (`install/livestream.py`: `fps=30` before the scale, ultrafast/zerolatency, 3 threads, nice 10, fragmented MP4 on
+  stdout, + AAC 128k) measured 0.34 core at 720p / 0.56 at 1080p with a quiet picture (video only); expect ~1-1.4
+  cores with a busy scene. That is now only the fallback.
+- Hardware encoding (2026-10-07): the iris encoder works when driven directly through the V4L2 stateful encoder
+  interface. That is FramePort's `fp_venc` (`native/venc`, spec + every measured value in `native/venc/SPEC.md`).
+  Facts:
+  - Device: `/dev/video23` (`/dev/video-enc0` links to it), driver `iris_driver`, M2M multiplanar.
+  - Formats: input NV12/NV21/AB24(RGBA)/QC24/Q08C; output H264/HEVC; sizes 128..8192.
+  - NV12 layout (S_FMT answers):
+    - stride is a multiple of 128;
+    - the returned height is padded to a multiple of 32;
+    - CbCr starts at stride × padded height;
+    - sizeimage is rounded up to 4 KiB;
+    - the default crop is the requested size.
+  - Controls: CBR, FORCE_KEY_FRAME, PREPEND_SPSPPS_TO_IDR, HEADER_MODE joined, FRAME_SKIP_MODE, H.264 profiles
+    Baseline..Constrained High, levels up to 6.0.
+  - The `steamos` user can open it (group video).
+  - The panel's current refresh rate can be read without privileges through DRM: `/dev/dri/card0` is mode 0666, and
+    GETCRTC reports e.g. `2*2160x2160_96` (clock 1402720 kHz / 4448 × 3285 = 96 Hz) even while the headset sleeps.
+    The panel offers 72/80/90/96/108/120/144 Hz.
+  - `/dev/video99` (v4l2loopback) has `max_buffers=2`: a reader asking for more gets 2.
+  - Mid-stream keyframe requests (FORCE_KEY_FRAME) take effect on the next frame, and the GOP restarts from there.
+  - Measured 2026-10-07 with the headset asleep (still picture):
+    - `fp_venc` alone at 32/36 fps: 1% of a core at 1080p, 2.5% at 720p.
+    - Live view end to end: `fp_venc` 2.6% + ffmpeg 8.4% (AAC encoding + muxing).
+  - Conversion cost per new picture (self-test, NEON, 2026-10-07):
+    - 1080p (no scaling): 0.6–1.0 ms.
+    - 720p (exact 3:2 fast path): 1.3–1.65 ms, down from 5.6 ms with the generic box loop (~11 ms at idle clocks).
+    - 360p (3:1 fast path): 0.7 ms.
+    - 480p: 2.8 ms; its 852-px width doesn't repeat cleanly, so it uses the generic path.
+    - At 36 fps with live content that is roughly 2–6% of a core.
+  - ffmpeg with raw H.264 on a pipe:
+    - `-framerate` is ignored.
+    - `-fflags nobuffer` loses the first seconds of tiny frames.
+    - Numbering frames from 0 (`setts`) with no input timestamps holds all output ~7 s next to pulse's audio.
+    - Arrival stamps alone (`-use_wallclock_as_timestamps 1`) bunch frames that are read together: gaps of 0–10 ms
+      and 45+ ms, seen in the headset test as dropped frames.
+    - What works: `-probesize 32 -analyzeduration 0 -use_wallclock_as_timestamps 1` on the input (ffmpeg reads it in
+      step with the audio), then `-bsf:v setts=ts=N*(1/fps)/TB` on the output (exactly even frames; audio still
+      0–N s alongside), plus `frag_keyframe` so that a requested keyframe starts a fragment.
+    - With sound, ffmpeg paces its inputs against each other and pulse's audio arrives later than the wall clock
+      (more while something plays). The video input then counts as ahead, and ffmpeg stops reading it for up to
+      0.7 s, so the writer blocks. That was the cause of 1080p dropping frames: busy 1080p replayed with sound took
+      34–47 s for 20 s of video. Video alone was fine; `nice`, `-raw_packet_size` and the input queue size didn't
+      matter. Shifting the video input back fixes it, but too far makes ffmpeg hold the video for interleaving and
+      release it in clumps: -1 s gave output gaps of up to 550 ms, a longer and stuttering delay in the browser.
+      -0.25 s is the measured sweet spot (no stalled writes at busy 1080p with sound, steady 50–150 ms output; -0.5 s
+      already clumps). Output audio/video spans stay equal because setts sets the output times.
+    - Browser delay (headless Chromium, 720p, 2026-10-07): muted about 0.2–0.35 s behind the newest data; with
+      sound about 1 s. Chrome keeps about 0.6 s of audio ahead and stalls below that, whatever the player does:
+      1.1× catch-up gave 8 stalls per 30 s, no speed-up 1–2, same average lag; 50 ms fragments didn't help. So the
+      player doesn't speed up while sound is on.
+  - Quality (owner's headset test, 2026-10-07): 3 Mbit/s CBR at 720p36 showed heavy compression artifacts. The
+    hardware path now uses VBR with a 1.5× peak (the encoder accepts BITRATE_MODE VBR + BITRATE_PEAK) and higher
+    targets: 360p 1.5, 480p 2.5, 720p 5, 1080p 8, Full 10 Mbit/s. The x264 fallback keeps its rates.
+  - The default sink is SUSPENDED while nothing plays; its monitor still delivers (silent) audio.
+
+## Text input
+
+- Lepton's Android has no on-screen keyboard (IME) and VR apps run headless, so no Android window has keyboard focus
+  and key presses (Steam's keyboard, USB/Bluetooth keyboards, `input text`) don't reach VR apps. The app folder's
+  `lepton-show-flatscreen` marker shows the window (VR keeps working) and gives it focus; Steam's on-screen keyboard
+  then opens for its text fields (FramePort patch `device.text_input_window`).
+- `/dev/uinput` is writable by the steamos user (ACL for Steam Input): a uinput virtual keyboard works like a real
+  one everywhere (FramePort's "Type on Frame", agent `_keyboard`).
+- Unity text fields close without a system keyboard; see `frame.unity_text_input` in PLAYBOOK.md.
+
+
+## Monitoring sources (probed 2026-10-07, SteamOS 0.4.3, kernel 6.18; used by the Monitor tab, agent `_monitor`)
+
+All readable by the steamos user without root; the agent reads them directly (no programs started per sample).
+
+| Metric | Source | Notes |
+|---|---|---|
+| CPU | `/proc/stat` deltas; `cpufreq/policy{0,2,5,7}` | 8 cores in 4 clusters: 0-1 / 2-4 / 5-6 / 7 (max 2.27 / 3.15 / 2.96 / 3.05 GHz) |
+| GPU busy | Sum of `drm-engine-gpu` (ns) deltas in `/proc/<pid>/fdinfo/<fd>` over every render-node fd (msm DRM) | Gives GPU % per process too. A process can hold several render fds: add them all. Lepton games see the node as `/dev/kgsl-3d0` (bind mount of `/dev/dri/renderD128`). `drm-total-memory` reads 0 |
+| GPU clock | `/sys/class/devfreq/3d00000.gpu/{cur,max}_freq` | 231–903 MHz in 12 steps |
+| Memory / pressure | `/proc/meminfo`; `/proc/pressure/{cpu,memory,io}` (`some avg10`) | 16 GB RAM, 8 GB swap |
+| Temperatures | `/sys/class/thermal/thermal_zone*/{type,temp}` | 48 zones: `cpu*`/`cpuss*`, `gpuss-*`, `ddr`, `nsph*` (NPU), `pm8550*`/`pm8010*` (power ICs), `modem*`, `camera*`, `video`, `max1720x_bat*` |
+| Fan | hwmon `slg4ax46073v` `fan1_input` | ~8200 rpm idle |
+| Power | hwmon `max34417_*` `power{1-4}_{label,input}` (µW) | `vph` = whole system (~3.6 W idle), `gfx` = GPU, `apc0/1/2` = CPU clusters, `nsp1/2` = NPU; each read is an I2C transfer (~0.7 ms wall), so only these are read |
+| Battery | `power_supply/max1720x_bat_7-36` | `current_now` (µA, negative = draining) × `voltage_now` (µV) = watts; `time_to_empty_now`/`time_to_full_now` (s), `cycle_count`, `health`, `temp` (0.1 °C) |
+| Game fps | `<base>/launch.log` lines `FrameBridge: pacing: N fps …` (every ~5 s) | Quest games only; SteamVR writes PC VR frame stats only as an end-of-session summary in `vrcompositor.txt` |
+| Game container | conmon `-n lepton-steamlaunch-<appid>`; its child's `/proc/<pid>/cgroup` → `cpu.stat`, `memory.current` | The container's ~90 Android processes show as uid 1000 on the host and can be signalled (4XVR, 2026-10-07); Android names them after the package's last 15 characters (`lus4xvrplayerov`), the full name is in `cmdline` |
+
+Cost: a naive sample (fds of ~520 processes scanned) took 43 ms CPU. With kernel threads skipped after their first
+sighting, command lines checked once per process, render fds cached (rescanned every 60 s, every 4 s for busy young
+game processes without one), temperatures every 2 s, the CPU-cluster power rails every 5 s and the battery gauge every
+2-10 s, the stream measured ~10-13 ms CPU per 1 s tick on the device (idle clocks; idle or with 4XVR running) = about
+1 % of one core, ~0.15 % of the whole CPU. The I2C sensors (power monitors, battery gauge) are the slowest reads.

docs/FRAME_SETUP.md

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

docs/GAMES.md

@@ -0,0 +1,93 @@
+# Tested games
+
+Games tested on the Steam Frame with FramePort's recipes. Games not listed here may work too: FramePort suggests patches for them, and a working config can be shared from the app (**Share working config…**).
+Tested a game? [Share a working config](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml) or [report a problem](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml) (in the app: the game's **…** menu does both and fills in the details).
+Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
+
+| Game | Platform | Status | Notes |
+|---|---|---|---|
+| 4XVR Video Player | Quest | ✅ Works |  |
+| Accounting+ | Quest | ✅ Works |  |
+| AllInOneSports | Quest | ✅ Works |  |
+| Asgard's Wrath 2 | Quest | ✅ Works |  |
+| BAM | Quest | ✅ Works |  |
+| BARTENDER VR SIMULATOR | Quest | ✅ Works |  |
+| Batman: Arkham Shadow | Quest | ✅ Works |  |
+| BattleGlide | Quest | ✅ Works |  |
+| BattleSisters | Quest | ✅ Works |  |
+| Beat Saber | Quest | ✅ Works |  |
+| Beat Saber | Quest | ✅ Works |  |
+| Beat Saber (co-existence build) | Quest | ✅ Works |  |
+| Blade & Sorcery: Nomad | Quest | ✅ Works |  |
+| BodyCombat | Quest | ✅ Works |  |
+| Carve Snowboarding | Quest | ✅ Works |  |
+| Cook-Out | Quest | ✅ Works |  |
+| Creed | Quest | ✅ Works |  |
+| Demeter | Quest | ✅ Works |  |
+| Dinosaur Island | Quest | ✅ Works |  |
+| Espire 2 | Quest | ✅ Works |  |
+| Genotype | Quest | ✅ Works |  |
+| GORN2 | Quest | ✅ Works |  |
+| H.U.N.T | Quest | ✅ Works |  |
+| I Am Cat | Quest | ✅ Works |  |
+| I Am Monkey | Quest | ✅ Works |  |
+| In Death: Unchained | Quest | ✅ Works |  |
+| Into The Radius 2 | Quest | ✅ Works |  |
+| Job Simulator | Quest | ✅ Works |  |
+| Jurassic World Aftermath Collection | Quest | ✅ Works |  |
+| Keep Talking and Nobody Explodes | Quest | ✅ Works |  |
+| Lambda1VR | Quest | ✅ Works |  |
+| LEGO® Bricktales | Quest | ✅ Works |  |
+| Lucky's Tale | Quest | ✅ Works |  |
+| Marvel's Deadpool VR | Quest | ✅ Works |  |
+| Marvel's Iron Man VR | Quest | ✅ Works |  |
+| Medieval Dynasty New Settlement | Quest | ✅ Works |  |
+| Metro Awakening | Quest | ✅ Works |  |
+| Mobile Suit Gundam: Silver Phantom | Quest | ✅ Works |  |
+| Nano | Quest | ✅ Works |  |
+| NEX Player | Quest | ✅ Works |  |
+| NOPE CHALLENGE | Quest | ✅ Works |  |
+| palazzo_santacruz | Quest | ✅ Works |  |
+| Path of the Warrior | Quest | ✅ Works |  |
+| PowerWash Simulator VR | Quest | ✅ Works |  |
+| QuestCraft | Quest | ✅ Works |  |
+| Richie's Plank Experience | Quest | ✅ Works |  |
+| Rick and Morty: Virtual Rick-ality | PC VR | ✅ Works |  |
+| Riven | Quest | ✅ Works |  |
+| Robo Recall | Quest | ✅ Works |  |
+| RUINSMAGUS | Quest | ✅ Works |  |
+| Sniper Elite VR: Winter Warrior | Quest | ✅ Works |  |
+| Space Pirate Trainer Quest | Quest | ✅ Works |  |
+| Stremio | Quest | ✅ Works |  |
+| SUPERHOT VR | PC VR | ✅ Works |  |
+| SUPERHOT VR | Quest | ✅ Works |  |
+| TetrisEffect | Quest | ✅ Works |  |
+| The Boys VR | Quest | ✅ Works |  |
+| The Climb 2 | Quest | ✅ Works |  |
+| The Room VR | Quest | ✅ Works |  |
+| Time Crisis VR (Experimental) | Quest | ✅ Works |  |
+| Toy Master | Quest | ✅ Works |  |
+| Under Cover | Quest | ✅ Works |  |
+| VR4 | Quest | ✅ Works |  |
+| Wallace & Gromit in The Grand Getaway | Quest | ✅ Works |  |
+| Waltz of the Wizard: Extended Edition | Quest | ✅ Works |  |
+| Wander | Quest | ✅ Works |  |
+| Arcsmith | Quest | ⚠️ Works with issues | Right eye distorts during movement (unresolved; swap, tracking, Valve layers, depth and pacing ruled out). |
+| Assassin's Creed Nexus | Quest | ⚠️ Works with issues | Some launch warning text is still upside down; the rest of the UI is fixed by flip emulation. |
+| BONELAB | Quest | ⚠️ Works with issues | Build 1.2068 plays (head tracking and controls work with frame.unity_user_presence); the newer build 1.2974 crashes at start (Vulkan), no fix yet. |
+| Doom3Quest | Quest | ⚠️ Works with issues | PDA shows black screen. |
+| Myst | Quest | ⚠️ Works with issues | Minor graphical glitches on some objects. |
+| Phantom: Covert Ops | Quest | ⚠️ Works with issues | DLC/store button crashes (no Meta store). |
+| Pinball FX VR | Quest | ⚠️ Works with issues | Plays; mixed reality mode not working yet. |
+| Silhouette | Quest | ⚠️ Works with issues | Hand-tracking game; the Frame synthesizes hands from controllers, so it is janky. |
+| Time Stall | Quest | ⚠️ Works with issues | Both eyes distort during movement (unresolved). |
+| Vader Immortal: Episode I | Quest | ⚠️ Works with issues | Starts in VR and plays the intro, then stays on the loading card (Vader's portrait with a progress bar). |
+| WiiCompiled VR | Quest | ⚠️ Works with issues | To add a game: in FramePort's Files tab, upload your .wcgame file to this game's storage, folder Android/data/org.wiicompiled.quest/files/WiiCompiledOpenXRVR… |
+| BlazeRush | Quest | ❌ Doesn't run | Starts and reaches the menu room, but the room shows no controllers and ignores all input (it all reaches the game); no fix yet. |
+| Espire 1: VR Operative (Quest Edition) | Quest | ❌ Doesn't run | Mesa GL driver crash during texture upload. |
+| HITMAN 3 VR: Reloaded | Quest | ❌ Doesn't run | Vulkan driver crash (freedreno), even without Valve layers. |
+| Journey of the Gods | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |
+| Roblox | Quest | ❌ Doesn't run | Crashes on its first VR frame on the Frame. |
+| Shadow Point | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |
+| Sniper Elite VR | Quest | ❌ Doesn't run | GPU hang (zink: DEVICE LOST) even with MSAA off. |
+| Sports Scramble (Santa Cruz) | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |

docs/INSTALL.md

@@ -8,7 +8,8 @@ runtime, the OVRPort CLI and apksigner into its data folder (Settings → Tools
 |---|---|---|
 | Windows 10/11 (x64) | `FramePort-windows-x64.zip` | `FramePort.exe` |
 | macOS (Apple Silicon) | `FramePort-macos-arm64.zip` | `FramePort.app` |
-| Linux (x64, GTK 3) | `FramePort-linux-x64.tar.gz` | `FramePort/FramePort` |
+| Linux (x64, GTK 3; Ubuntu 22.04 or newer) | `FramePort-linux-x64.tar.gz` | `FramePort/FramePort` |
+| Linux (ARM64, GTK 3; Ubuntu 22.04 or newer) | `FramePort-linux-arm64.tar.gz` | `FramePort/FramePort` |
 | Command line only (Python 3.11+) | `frameport-<version>-py3-none-any.whl` | `frameport --help` |
 
 The command-line version installs from the wheel's release link with `uv tool install <link>` (or pipx / pip).
@@ -22,19 +23,154 @@ start shows a warning:
   `FramePort-selfsigned.cer` (attached to each release) into *Trusted Root Certification Authorities* (Current User) to
   show FramePort as the publisher; the certificate can only sign code. Remove it with `certmgr.msc`.
 - **macOS:** right-click `FramePort.app` → **Open** → **Open** (once), or `xattr -dr com.apple.quarantine FramePort.app`.
-- **Linux:** `tar xzf FramePort-linux-x64.tar.gz && ./FramePort/FramePort`.
+- **Linux:** `tar xzf FramePort-linux-x64.tar.gz && ./FramePort/FramePort` (ARM64: `FramePort-linux-arm64.tar.gz`).
 
 ## Connecting the Steam Frame
 
-1. On the Frame: Settings → System → Developer → turn on **Developer Mode**. The Frame and the computer must be on the
-   same network.
-2. In FramePort open **Steam Frame**. A Frame in Developer Mode appears in the list.
-3. First time only: on the Frame switch to Desktop mode (Steam button → Power → Switch to Desktop), open Konsole and
-   run the command FramePort shows. It enables SSH, authorises this computer and installs Valve's Android runtime
-   (Lepton) if needed.
+The Frame and the computer must be on the same network.
+
+1. In FramePort open **Steam Frame** and click **Show setup command**.
+2. First time only, on the Frame:
+   1. Open the **SteamVR dashboard → Launch a program → Desktop**: the Linux desktop opens on a virtual screen.
+   2. Open the app menu (bottom-left corner of that desktop) → **System → Konsole** (or search for Konsole).
+   3. Type the command FramePort shows exactly as shown (on-screen keyboard or any USB/Bluetooth keyboard) and press
+      **Enter**. It looks like `curl -fsS 192.168.1.20:8765/1a2b3c4d | bash`: your computer's address, then a
+      one-time code.
+   4. After a few seconds the desktop closes by itself (Steam restarts once); that's expected. If
+      Steam asks to install **Lepton** (Valve's Android runtime), confirm it.
+
+   FramePort connects by itself within a minute. No password is needed. The command lets FramePort in and turns on
+   **Developer Mode** (which includes SSH); everything it changes is listed in [FRAME_SETUP.md](FRAME_SETUP.md).
+3. Later starts: a Frame in Developer Mode appears in the list and FramePort connects to it automatically. (If you
+   turn Developer Mode off in Settings → System → Developer, turn it on again there.)
+
+**Without Konsole:** turn on Developer Mode yourself (Settings → System → Developer). The Frame then appears under
+**On your network**. On the Frame open Settings → Developer → **Pair new host**, then click **Connect** in FramePort
+and approve it on the Frame (Valve's own devkit pairing; it only sends this computer's key to the Frame). Install
+Lepton from the Steam Frame page afterwards if it's missing.
+
+### With a USB cable
+
+For networks that block the setup (guest Wi-Fi, firewalls, discovery not working), and for faster uploads:
+
+1. On the Frame, turn on **Developer Mode** (Settings → System → Developer Mode). The Frame's USB network only exists
+   in Developer Mode.
+2. Connect the Frame's USB-C port to the computer.
+3. In FramePort: **Steam Frame → Set up with a USB cable**. FramePort detects the cable and shows the setup command,
+   which reaches the computer over the cable. Already set up? It connects over the cable right away.
+
+The cable needs no driver on Windows 10/11, macOS or Linux, and the computer gets an address from the Frame
+automatically. Uploads use the cable whenever it's plugged in (about 37 MB/s, ~3× typical Wi-Fi), even when FramePort
+connected over Wi-Fi. Unplug it any time: FramePort finds the Frame on Wi-Fi again by itself.
+
+### Firewalls
+
+If the setup command only says "timed out", a firewall on your computer blocks the Frame; the setup page
+says which after about 45 seconds. Details per system: [FRAME_SETUP.md](FRAME_SETUP.md#network-and-firewalls).
+
+## Running FramePort on the Frame (experimental)
+
+FramePort can run on the Steam Frame itself, without a PC: in **Desktop Mode**, download
+`FramePort-linux-arm64.tar.gz`, unpack it (`tar xzf FramePort-linux-arm64.tar.gz`) and start `FramePort/FramePort`.
+Turn on **Developer Mode** first (Steam → Settings → System); FramePort then manages "This Frame" directly, with
+no pairing. Games are added to the Steam library when you go back to **Gaming Mode** (Steam has to restart for it,
+which would end Desktop Mode). This is new: please report anything odd with **Report a problem**.
+
+## Installing games
+
+- **Install on Frame** on a game's page (or select several in the Library and install them together). Installs run
+  one after another in the background; **Activity** shows the current one at the top.
+- **Update all** reinstalls every game whose build changed (e.g. after a FramePort update). Questions that need an
+  answer (e.g. Oculus games that can't run on the Frame) are asked once, for all games.
+- If the Frame goes to sleep, turns off or leaves the Wi-Fi, the queue **waits** and continues once it's back; uploads
+  pick up where they stopped. While installs run, FramePort keeps the Frame from going to sleep. Before a large batch
+  it checks the Frame has enough free space.
+- **microSD card / other drives:** the **Steam Frame** page's **Storage** section lists the Frame's drives and sets
+  where new games go (**Install new games to**). Games go into a `FramePort` folder on the card. To move a game that's
+  installed already, right-click it → **Move to…** (the game must be closed; saves, settings and the Steam entry stay).
+  A game on the card only starts while the card is inserted (FramePort then says "SD Card not inserted"). Cards
+  formatted as FAT, exFAT or NTFS can't hold games: format the card in SteamOS first.
+- Your own game files are never changed. The converted copy is temporary: it's removed once the game is on the Frame
+  (Settings → Installing: keep them, or remove all now).
+- **Game settings…** (game menu or the Steam Frame page): sharpness, refresh rate, controllers, menus, 360° video and
+  mixed-reality options in plain words, only those that matter for the game. Changes are kept with the game and,
+  when it's installed, used the next time it starts.
+- Ordinary Android apps (no VR) are installed unchanged and shown as a flat window in the headset. Android's
+  back/home/recents buttons are hidden by default (patch **Hide Android's navigation bar**). If FramePort guesses
+  wrong (a phone app shows nothing in the headset, or a VR app opens as a flat window), choose **VR** or **Flat
+  window** under **Show as VR or as a flat window** in the game's **Customize** section, then **Update on Frame**.
+- **Add games → Add a Windows program (.exe)…** adds a single Windows program; the Frame runs it through Proton (as a
+  window unless it is a VR game). A program sitting in Downloads, the home folder or a drive root is copied on its
+  own first, so the install doesn't upload everything next to it.
+- In the packaged app you can also **drag files onto the Library**: APKs, Linux apps (AppImage, `.zip`/`.tar.gz`),
+  Windows programs (`.exe`), folders, or a FrameDrop manifest (`.json`).
+
+### Install links ("Install with FrameDrop" buttons)
+
+Some developers put an **Install with FrameDrop** button on their site (the one-click protocol of the FrameDrop
+sideloader, documented at framedropvr.com/docs). FramePort understands the same links:
+
+- **Clicking a button** opens FramePort (or the window that's already open) on Windows and Linux. FramePort shows
+  the title, the files, their size and whether a checksum is given, and asks before it downloads anything. Then it
+  downloads the build, adds it to your library and starts the usual install on the Frame. If no Frame is connected,
+  the game is added now and installs once the Frame is back.
+- **Add games → Install from a link…** takes the button's address (right-click → Copy link), a `framedrop://` or
+  `frameport://` link, a manifest (`.json`) or a direct link to an APK, a Linux build or a Windows program. Use it on
+  macOS, where web pages can't hand links to FramePort yet.
+- **Settings → Install links** has one switch for `framedrop://` links (the buttons) and one for FramePort's own
+  `frameport://` links. Both are on by default. If FrameDrop is installed too and already opens `framedrop://`
+  links, FramePort leaves them to it; **Use FramePort for these links** takes them over (turn the switch off to give
+  them back).
+- **For developers:** a FrameDrop manifest works as it is
+  (`{"schema": "framedrop.install/v1", "name": "…", "files": [{"url": "https://…", "sha256": "…"}]}`). FramePort
+  also reads an optional `"frameport": {"description": "…", "icon": "https://….png"}` object (FrameDrop ignores
+  it): the install question then shows the icon and description, and they become the game's icon and "About this
+  game" text when no store has them. Without a manifest (a bare file link) FramePort guesses the title from the
+  file name and replaces it with the app's own name once it's downloaded.
+- Only `https://` links to public servers are used (plain `http://` only on this PC, for testing); links with a
+  user name or password, or pointing into your local network, are refused. Only install from sites you trust.
+
+![Game page](images/game.png)
+
+Each game has **Game settings** in plain words (sharpness, refresh rate, controllers, menus, 360° video, mixed
+reality), showing only what matters for that game. Changes are kept with the game and reach the Frame right away.
+
+![Game settings](images/game-settings.png)
+
+## Typing on the Frame
+
+- **Type on Frame** (its own tab in the sidebar; also on the Steam Frame page and in a game's menu): while the tab is
+  open, this computer's keyboard works as a keyboard plugged into the Frame. Select a text field in the headset (in
+  an app, Steam or the desktop) and type; Esc and shortcuts go to the Frame too. Paste longer text into the box to
+  type it in one go (US keyboard layout). Opening another tab disconnects the keyboard.
+- **Steam's on-screen keyboard** opens for text fields of apps shown as a window (2D apps, and VR apps with
+  **Show the app's Android window**). Steam lists that window as **Gamescope** (the Frame's display compositor);
+  leave it open: it's what receives the typing, the VR view isn't affected.
+- **Unity apps whose text fields close at once** (a caret flashes, nothing can be typed): FramePort suggests
+  **Make Unity text fields work** for them. The first time, it downloads Cpp2IL (a tool that finds the right spot in the
+  game's code, ~17 MB). Games added before this version: open the game's menu → **Analyze again**, then reinstall.
+
+## Watching the Frame (Monitor)
+
+- **Monitor** (its own tab in the sidebar) shows live what the Frame is doing while the tab is open: the running game
+  with its frame rate (Quest games), CPU, graphics chip, memory, the hottest temperature with the fan speed, power
+  draw and battery time left, each with a 2-minute chart. **Show details** adds every CPU core, all temperature
+  sensors, where the power goes and the network.
+- **Processes**: **Game** (default) lists the running game's processes, **Steam & SteamVR** and **All** show more.
+  Right-click a process (or use **⋯**) to end it, force-kill it or end its whole game; **End game** on the game card
+  closes the game the way Steam's Exit game does. A lock marks programs whose end would close Steam, SteamVR or the
+  desktop: FramePort asks again before ending those.
+- The numbers come every second (or every 2/5 s) and cost the Frame about 1 % of one CPU core; nothing keeps
+  running on the Frame after you leave the tab.
 
 ## Updating
 
+**Game configs** (the tested recipes in the catalog) update by themselves: FramePort checks GitHub every 6 hours for
+newly confirmed or fixed configs and uses them without a FramePort update; a game whose recipe changed then shows
+**Update on Frame**. Configs that need a newer FramePort are skipped until you update. Settings → Data shows the last
+check (**Check now**) and turns this off.
+
+
 FramePort checks for a new release at start and every 6 hours (it only downloads the release information). When one
 exists, the Library shows **Update now**: FramePort downloads the new version, verifies it against the release's
 `SHA256SUMS.txt` (on Windows also the signature), restarts and opens as the new version. Games, settings, signing keys
@@ -44,14 +180,19 @@ Settings → **Updates**: turn the check off, or turn on **Install updates autom
 installs at the next start). If FramePort's folder isn't writable, **Update now** opens the release page instead. The
 update log is `logs/update.log` in the data folder.
 
+**Dev builds:** when you're asked to test a fix before it's released, use Settings → Updates → **Install the latest
+dev build…**. It shows what to test, then installs like an update (same checks). Dev builds are less tested; the next
+release is offered to you as a normal update.
+
 Command line: `frameport update` (`--check` only checks, exit code 10 = update available; `--yes` doesn't ask).
 `FRAMEPORT_NO_UPDATE_CHECK=1` turns all checks off.
 
-## Oculus Rift (PC VR) games
+## PC VR games
 
-Scan a folder of Rift games (one folder per game) or use **Add games → Add one game folder…**. FramePort finds the
-game's program and asks when there is more than one candidate. **Already patched** on a game page installs a copy
-unchanged. FramePort uses an installed Revive, or downloads a portable copy.
+PC VR games are Windows VR games (OpenXR, SteamVR or Oculus). Scan a folder of them (one folder per game) or use
+**Add games → Add one game folder…**. FramePort finds the game's program and asks when there is more than one
+candidate. **Already patched** on a game page installs a copy unchanged. Oculus-only games need Revive: FramePort uses
+an installed Revive, or downloads a portable copy.
 
 - **Play from this PC:** Windows with Steam and SteamVR. **Install on this PC** adds the game to Steam; stream it to the
   Frame with Steam Link. If a game can't keep up with the refresh rate, FramePort lowers the rate and enables motion
@@ -60,21 +201,83 @@ unchanged. FramePort uses an installed Revive, or downloads a portable copy.
   on the game page.
 - Games that use the Oculus Platform SDK check the licence through the Oculus app, so they run on the PC only.
 
-## Videos, documents and mods
+**Windows games without VR:** **Add games → Add one game folder…** with the game's folder (pick the program that
+starts it if asked). FramePort installs it on the Frame and Proton runs it as a window, like Steam's own Windows games;
+it shows up in the Frame's Steam library tagged "Windows game on Frame". Whether a game runs depends on Proton on ARM
+(x86 games run through emulation).
 
-Steam Frame → **Send files** (or a game's menu → **Add videos & files…**) copies files to the Frame. **Videos**,
-**Downloads** and **Documents** appear inside every Quest game as `/sdcard/Movies`, `/sdcard/Download` and
-`/sdcard/Documents`. Apps find them by browsing folders; Android's media index doesn't work on the Frame. Command
-line: `frameport frame send <files> --to videos`.
+## Linux apps
+
+The Frame runs SteamOS on an arm64 CPU, so native Linux apps built for **aarch64/arm64** run on it directly (no
+Android container, no Proton). **Add games → Add a Linux app…** takes an AppImage or a `.zip`/`.tar.gz`/
+`.tar.xz` archive; **Add a Linux app folder…** takes an unpacked app. FramePort finds the program that starts it (the
+game page's **Change…** picks another one) and whether it's a VR (OpenXR) app. **Install on Frame** uploads it
+unchanged and adds it to the Frame's Steam library, tagged "Linux app on Frame"; Play, launch tests and Uninstall
+work like for other games.
+
+- **x86_64 builds** run through **FEX**, Valve's x86 translator, with the x86 system libraries SteamOS ships for it
+  (the way Steam on the Frame runs x86 Linux games). The first install of one installs FEX on the Frame (Steam
+  restarts once and downloads it, a few MB). They run slower than arm64 builds: when an app offers both, FramePort picks the arm64 one. The game
+  page shows which CPU a build is for.
+- The app must bring the libraries SteamOS doesn't have (checked for arm64 builds; x86_64 builds use FEX's x86
+  system, which has glibc and Mesa, and aren't checked ahead). If some are missing, the install reports them and the game
+  page lists them: look for a build that includes them.
+- **Desktop Mode:** Linux apps also appear in Desktop Mode's application menu and as an icon on its desktop. Some
+  apps work better there, with a mouse and keyboard, than in Gaming Mode (where Steam Input turns the controllers into
+  a gamepad). Switch it off per app on the game page (**Desktop Mode**).
+- From the command line: `frameport add-linux <AppImage, folder or archive> [--exe <program>]`.
+
+## Files on the Frame (videos, documents, mods, saves)
+
+The **Files** tab manages files on the Frame over the same connection as installs; no other transfer app is needed.
+Pick a location, browse folders, and use **Upload files** / **Upload folder**, **New folder**, or the download, rename
+and delete buttons on each entry. Right-click an entry (or the empty space) for the same actions in a menu. Tick
+several entries (or the box above the list for all), or click and drag across them, to download or delete them
+together; a right-click on one of them then acts on all. The **Screenshots** tab and the **Library** work the same
+way: right-click for a menu, drag across cards to select several. In the downloaded app you can also drag files and folders from Explorer / Finder / your file manager onto
+the list to upload them into the open folder. Uploads and downloads run in the Activity panel, resume after an interruption and
+skip files that are already there.
+
+- **Videos**, **Downloads** and **Documents** appear inside every Quest game as `/sdcard/Movies`, `/sdcard/Download`
+  and `/sdcard/Documents`. Apps find files by browsing folders; Android's media index doesn't work on the Frame.
+- Under **Game storage**, each installed game has its own `/sdcard` (mods, saves). A game's menu → **Add videos and
+  files…** opens it. Video players that list only their own folder (e.g. 4XVR's "Internal Storage" = `4XPlayer`) find
+  videos uploaded into that folder.
+- **Home folder** shows everything in the Frame's home folder (hidden files with **Show hidden files**).
+
+Command line: `frameport frame send <files> --dest videos` (`frameport frame storage` lists the destinations).
 
 ## Sharing a working game, reporting a problem
 
 - **Share working config…** (game menu): opens a prefilled GitHub issue with the game's patches and settings. Accepted
-  configs become built-in recipes.
-- **Report a problem…** (game menu, or Settings → Problems & feedback): saves a diagnostics zip to Documents (logs,
+  configs become built-in recipes. Untested games ask on their page once they've been installed or tested: **It
+  works**, **It has issues** or **It doesn't run**.
+- **Report a problem…** (game menu, or Settings → Problems and feedback): saves a diagnostics zip to Documents (logs,
   recipe, device details; IP addresses, user names, home folders and Steam ids replaced) and opens a prefilled GitHub
   issue to attach it to. Command line: `frameport diag report <game>`, `frameport share-recipe <game>`.
 
+## Command line
+
+Everything the app does is also a `frameport` command (in a source checkout: `uv run frameport`); `frameport --help`
+and `frameport <command> --help` describe every option. The main ones:
+
+| Command | What it does |
+|---|---|
+| `scan <folder>` / `list` / `show <game>` | add games, list the library, show a game's analysis and patches |
+| `add-linux <path>` | add a Linux app, arm64 or x86_64 (AppImage, folder or archive) |
+| `recipe <game> --enable/--disable <patch>` | change a game's patches (`patches` lists them all) |
+| `build <game>` / `install <game>` / `test <game>` | build, install on the Frame (`--to pc` for PC VR on this PC), launch test |
+| `frame discover` / `frame connect` / `frame info` | find, pair with and describe the Frame |
+| `frame send` / `frame storage` / `frame cleanup` | copy files to the Frame, show where they go, free space |
+| `frame drives` / `frame move <game> --to <drive>` / `install --dest <drive>` | the Frame's drives (microSD), move a game, install to a drive |
+| `tools status` / `tools install` | the tools FramePort downloads |
+| `open-link "<link>"` | install from an "Install with FrameDrop" button's address or a manifest/APK/zip link (`--yes`, `--no-install`) |
+| `diag report <game>` / `share-recipe <game>` | report a problem / share a working recipe |
+| `update` | update FramePort |
+
+Exit codes: 0 done, 1 something failed, 2 wrong usage, 10 (`update --check`) a newer version exists. Errors are
+one line on stderr; `FRAMEPORT_DEBUG=1` shows the full traceback.
+
 ## Uninstalling
 
 Settings → **Uninstall FramePort…** (or `frameport uninstall-app`) removes its data folder, the Steam shortcuts it

docs/PLAYBOOK.md

@@ -13,7 +13,26 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 ## Startup failures (visible in launch.log)
 | Symptom | Cause | Fix |
 |---|---|---|
+| One eye (usually the right) shimmers or jitters in the 3D view while menus and panels look steady; pacing is clean (GitHub #69, e.g. RTCWQuest, Moss) | Valve's eye-tracked foveation layer (`VALVE_fdm_injection`) moves its low-density regions with each eye's gaze, and the right eye's gaze filter restarts often (`CEyePoseUKF R: Large dt … Bootstrapped` in `~/.local/share/Steam/logs/eyetracking.txt`) | Customize → "Eye-tracked foveation (Valve)" (`device.foveation`): **Fixed** (`FDM_DEBUG=disable_offsets`, keeps the GPU saving) or **Off** (`VK_INSTANCE_LAYERS=""`); catalog field `foveation:` |
+| A Unity OpenXR game closes right after the OpenXR instance is created: `F VrApiLoader: vrapi_SetPropertyInt was called before vrapi_Initialize()!`, SIGABRT on UnityMain (GitHub #62, Jurassic World Aftermath) | the APK still ships Meta's VrApi loader; OVRPlugin (1.89, on OpenXR) calls it without starting VrApi and Meta's loader aborts. The VrApi bridge can't replace it (39 of the loader's 114 functions: OVRPlugin wouldn't link) | `frame.vrapi_stub` (same exports, each returns 0); triage `vrapi-before-init` |
+| A VrApi game exits at once: `UnsatisfiedLinkError … dlopen failed: cannot locate symbol "vrapi_PollEvent"` (GitHub #57, BlazeRush) | the engine imports a VrApi function the VrApi bridge didn't implement | the bridge has `vrapi_PollEvent`, `RecenterPose`, `SetDisplayRefreshRate`, `GetSystemPropertyFloatArray` (rebuild the game); the static check "VrApi functions resolvable" names any other missing one; triage `vrapi-symbol-missing` |
+| A Team Beef port (Lambda1VR, RTCWQuest, …) exits at once: `UnsatisfiedLinkError: dlopen failed: library "libopenxr_loader_valve.so" not found` (GitHub #59) | TBXR loads `openxr_loader_<Build.MANUFACTURER>` (Lepton: valve) and takes the Meta path only when `strstr(OPENXR_HMD, "meta")` matches, else Pico's | `frame.tbxr_vendor` (empty `libopenxr_loader_valve.so` + the "meta" literal → "alve"). Game data (`xash/`, …) goes to /sdcard: upload it with the Files tab to the game's storage. Black eyes with `TBXR: Incomplete frame buffer object: GL_FRAMEBUFFER_INCOMPLETE_MULTISAMPLE`: TBXR always uses multisampled render-to-texture (even `--msaa 1`); `frame.tbxr_vendor` links the GL shim, which hands it single-sampled versions (log `GL shim: multisampled render-to-texture … drawn single-sampled`) |
+| Logos and a loading animation, then black (no crash, frames keep coming) in a game whose OBB folder has extra `*.pak` files (GitHub #61, Star Wars: Tales from the Galaxy's Edge: seasons + Wwise banks) | the game asks Meta's platform for these asset files (`ovr_AssetFile_GetList` / `DownloadById`); OVRPort's loader doesn't know them, so the content never "arrives" | `frame.asset_files` (native/langpack lists the data's `*.pak` as installed `default` assets, IAP `free`, and answers DownloadById at once with the path; off: env FRAMEPORT_ASSET_FILES=0) |
+| `cannot locate symbol "ovrPeerConnectionState_ToString"` (or another `ovr<Enum>_ToString`) at start (BlazeRush, GitHub #57) | OVRPort's platform loader lacks several Platform SDK enum helpers | `frame.ovrstubs` now stubs them too; `*_ToString` stubs return "" (not NULL) |
+| Exits right after the OpenXR instance is created: `Failed to create XR session: -50` (`XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING`, Lambda1VR) | the game skips `xrGet*GraphicsRequirementsKHR`; Meta's runtime tolerates it, SteamVR's doesn't. Lambda1VR's TBXR doesn't even enable `XR_KHR_opengl_es_enable` (only `XR_EXT_local_floor`) | FrameBridge adds `XR_KHR_opengl_es_enable` when an app enables no graphics API extension, asks for the requirements on the game's behalf and retries xrCreateSession once (logs `added XR_KHR_opengl_es_enable …`, `the app skipped …; asked for it`; every launch logs the final extension list `xrCreateInstance with N extension(s)`); triage `graphics-requirements-missing`. Verified headless: Lambda1VR runs at 72 fps |
+| Exits at start: `OVRAvatar-Loader: DisplayErrorAndExit: Failed to launch SystemActivities` after `ovrAvatar_Initialize: Failed to load AvatarSDK driver` (BlazeRush, GitHub #57) | Meta's avatar loader needs Horizon; it then tries Meta's error screen and aborts | `frame.avatar_stub` (same exports, do nothing); triage `avatar-driver-missing`. Games that ship the library but don't start avatars at launch (Lucky's Tale, BattleSisters, Arcsmith) don't need it |
+| Frame freezes or the game is killed (OOM) on the first controller vibration (e.g. Lucky's Tale's save slots, BattleSisters) | OVRPort runtimes up to 3.4.3-23204ea read the haptic envelope's duration (ns) as seconds and allocate gigabytes of samples (GitHub #9, ovrport/app#73) | `adapter.haptic_fix` (envelope → one plain vibration in `native/xrshim`). Fixed in runtime 3.4.3-aa54c3f: builds made with it leave the workaround out by themselves (log "not needed: adapter.haptic_fix", `frameport show` "last build left out"); rebuild an older build to switch |
+| Controller vibrations much stronger than on a Quest (The Boys VR, Jurassic World, BONELAB, …) | OVRPlugin games send amplitude envelopes; `haptic_fix` turned each into one vibration at the envelope's *peak* for its whole duration (a short fading pulse became a long full-strength buzz) | `haptic_fix` now uses the envelope's RMS; Game settings → "Vibration strength" (`haptic_scale`, 0-1) scales every vibration in FrameBridge; launch.log shows the first requests (`haptic: …`). OVRPlugin stops a vibration with amplitude 0 (2 s duration): FrameBridge turns that into xrStopHapticFeedback (without it the last buzz ran its full 2 s) |
+| Play or a launch test fails at once: `Game files missing at <path> (storage not mounted?)` in launch.log, or "… files are on a drive that isn't inserted" (GitHub #90) | the game was installed or moved to a microSD card (`<mount>/FramePort/<pkg>`) that isn't inserted or mounted now | insert the card; or move the game back (game menu → Move to…, `frameport frame move <pkg> --to internal`) once the card is back. `frameport frame drives` shows what the agent sees (exFAT/NTFS cards are refused: format in SteamOS) |
+| A Linux app started from Desktop Mode's menu closes after ~2 s, or opens on the wrong display (GitHub #84) | its launcher predates agent v63: the "Steam parent gone" watchdog ended it when Plasma's launcher exited, and it took gamescope's DISPLAY from Steam | connect FramePort once (agent v63's `upgrade_launchers` adds the `FRAMEPORT_DESKTOP` checks; the menu entry runs `env FRAMEPORT_DESKTOP=1 <anchor>/launch.sh`). Game Mode controller problems in such apps are Steam Input's (a separate issue) |
 | Every game suddenly fails to start: `crun: create keyring …: Disk quota exceeded`, `is not a running context` | rootless podman leaked a kernel keyring per launch; 200-key quota exhausted | `keyring = false` in `~/.config/containers/containers.conf` (FramePort agent does it), then reboot the Frame once |
+| A Unity app's text field shows a caret for a moment and loses focus; no keyboard appears (e.g. Stremio VR login) | Unity's TMP_InputField/InputField wait for Android's on-screen keyboard and close themselves without one (Lepton has none); headless VR apps also have no focused Android window, so no key press reaches them | `frame.unity_text_input` (Cpp2IL finds `TouchScreenKeyboardShouldBeUsed`/`isKeyboardUsingEvents`, rewritten to false/true) + `device.text_input_window` (lepton-show-flatscreen: Steam's keyboard and Type on Frame work) |
+| Play gives Steam's "Game configuration unavailable"; Steam's console_log: `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` | this Frame's Steam never loaded FramePort's shortcuts.vdf entry (it treats the id as a store app); cause unknown (GitHub #21/#30) | automatic since agent v43: Play registers the game through Steam's devkit interface ("Devkit Game: …", `devkit_register`) and starts that; uninstall removes it. Agent v58: a devkit entry Steam forgot after a restart is added again live on Play (no NOT_IN_LIBRARY → no Steam restart), and installs/art updates of devkit games only copy art (no Steam restart, GitHub #41) |
+| Steam's Exit game leaves the game running (container `lepton-steamlaunch-<appid>` still up) | Steam stopped only its `reaper`; launch.sh and Lepton (setsid) never got a signal (GitHub #36) | agent v44: launch.sh's 2 s loop ends the game when its parent is gone (`upgrade_launchers` adds it to existing launchers); by hand: `podman kill lepton-steamlaunch-<appid>` |
+| Black screen at start while audio/ExoPlayer runs; log `xrEndFrame: dropped N unusable layer(s)`, a quad layer with swapchain 0x0 (e.g. I Am Monkey's intro video) | The game plays video into an Android-surface swapchain (XR_KHR_android_surface_swapchain); the Frame's runtime lists the extension but returns FUNCTION_UNSUPPORTED | adapter `surface_emul` (default on): FrameBridge gives the player a SurfaceTexture-backed Surface and copies each frame into an ordinary swapchain (log `surface_emul: …`) |
+| The game quits right after start: `Something failed to initialize. Quitting!` / `We don't have write permission to …/files/cloud/data` (e.g. SUPERHOT) | The game created a save folder with mode 1700; inside Lepton the app writes through the folder's group | launch.sh `fix_perms` adds owner + group write to every folder in the game's storage (agent 41); reinstall to get the new launcher |
+| The whole Frame slows to a halt, then the game is killed (`Out of memory: Killed process … anon-rss:10+ GB`), e.g. Lucky's Tale | The game's own memory grows ~1 GB/s on Unity's `Loading.PreloadManager` thread (perf page-fault profile); not the flat window, not the text-input patches | none yet: mark unsupported; profile with `perf record -p <pid> -e page-faults --call-graph fp` (works as steamos, `perf_event_paranoid` 2) |
+| A Linux app exits at once: `cannot execute binary file: Exec format error` in launch.log | an x86_64 program started directly (installed before FramePort ran x86 builds through FEX, or by hand) | reinstall it: x86_64 Linux apps install FEX on the Frame and start through it (agent v61, `kind: linux_x86`; FEX also needs `STEAM_COMPAT_DATA_PATH`: "No compat data path?" in launch.log = an agent v60 launcher, reinstall); triage `linux-x86-no-fex`. Prefer an arm64 build when the app offers one |
 | `APP_ACTIVITY is empty`, nothing starts | Manifest has category INFO only; Lepton needs LAUNCHER | `frame.launcher` (automatic) |
 | PC VR game on the Frame shows as a flat window / Revive: `Unable to load LibOVRRT DLL` / `LoaderInstance::CreateInstance chained CreateInstance call failed` | Frame SteamVR runtime rejects OpenXR apiVersion 1.1 (`XR_ERROR_API_VERSION_UNSUPPORTED`), which Proton 11's VR helper requests | `pcvr.xr_timefix` (Frame OpenXR layer, default on): retries xrCreateInstance as 1.0 |
 | Unreal PC VR game on the Frame runs as a flat window although OpenXR works (no `LogHMD` OVRPlugin lines; Unreal logs nothing when it skips the Oculus plugin) / launch.log: `FramePort oculushmd: could not create the OculusHMDConnected event` | UE's OculusHMD (and LibOVR's `ovr_Detect`) only start when the Windows event `OculusHMDConnected` exists and is signalled; on a PC the Oculus service creates it. Revive hooks `OpenEventW` for it, but that relies on Detours patching Wine's (ARM64EC) kernelbase | `pcvr.oculus_unreal` (default for Unreal Rift games; PC VR counterpart of overport's `patch_oculus_unreal`): launch.sh runs the injector through `fp_oculushmd.exe`, which provides the real event until the game exits |
@@ -26,12 +45,18 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Uploads to the Frame are slow (~15 MB/s) | PC and Frame both on Wi-Fi through the home router | Connect the PC to the Frame's own hotspot (or a USB cable): FramePort uses the direct link automatically (~80-100 MB/s); job log line "Transfer link" |
 | PC VR game exits right away: `Unhandled Exception: 0xc06d007e` (after `FOnlineSubsystemOculus::InitWithWindowsPlatform`) | Delay-loaded `LibOVRPlatform64_1.dll` (Oculus Platform SDK, installed with the Oculus app) is missing | None on the Frame (entitlement check; FramePort doesn't replace it). PC mode with the Oculus app |
 | Unreal PC VR game opens the crash reporter instead of closing | UE starts CrashReportClient.exe on a crash | `pcvr.no_crash_reporter` (default for Unreal Rift games): `-nocrashreports` + CrashReportClient.exe renamed `.disabled` in the Frame copy |
+| A backup's game was added without its data (library `data_dir` null, `data_bytes` 0) although the folder has .obb files | The OBBs sit in a layout the scan didn't know: `<game>/obb/<package>/`, `Android/obb/<package>/`, or SideQuest-style `<game>/apk/x.apk` + `<game>/obb/<package>/` | `sources/quest_dump.find_data_dir` finds a `<package>` folder with .obb files ≤3 levels below the APK's folder or ≤2 below its parent (skipping neighbouring folders with APKs: other games); an `apk`/`apks` folder counts as part of its game folder. Add the folder again (Analyze again doesn't look for data) |
+| Unreal game: `JNI_OnLoad` (OVRPlugin), then silence: no OpenXR instance, no crash, no frames (GitHub #85 TRIANGLE STRATEGY; launch-test finding `missing-obb`) | Installed without its OBB: the manifest says `com.epicgames.ue4.GameActivity.bHasOBBFiles` = true (UE5: `com.epicgames.unreal.…`) but the library has no data folder (`data_dir` null, `data_bytes` 0) | Put the .obb files in a `<package>` (or `obb/`) folder next to the APK, add the folder again, reinstall. Analysis `extra.expects_obb`; the game page, the install question and `frameport scan`/`install` warn; launch tests that sent no frames get the `missing-obb` finding from the library (the game logs nothing). Unity split-binary builds have no reliable sign in the APK |
 | `INSTALL_FAILED_NO_MATCHING_ABIS` | 32-bit-only APK; Frame has no AArch32 | None. PC/Rift version via Revive |
+| Crash at start: `NoClassDefFoundError: … Landroid/window/OnBackInvokedCallback;` or `NoSuchMethodError: No static method storeStoreFence()V in class Ljava/lang/invoke/VarHandle;` (GitHub #71/#72, triage `android-too-new`) | The APK needs Android 13+ (minSdk 33 or more; those were 34) and calls its classes at start; Lepton's Android is 11 (API 30). OVRPort lowers minSdk to 29, so it installs anyway. minSdk ≤ 32 (Quest's Android 12L) is fine: 16 working catalog games declare 32 | None (analysis `extra.min_sdk` > 32 → a warning on the game page/CLI and in the recipe notes; never unsupported from the manifest alone, the launch test's triage decides). Waits for Valve to update Lepton's Android |
+| Nothing opens; `TWALauncherActivity: Using URL from Manifest (https://…)`, `Creating TwaLauncher for com.oculus.browser`, `NameNotFoundException: com.oculus.browser` (GitHub #86 Mahjong Table VR, triage `web-wrapper`) | The APK is a Trusted Web Activity (Bubblewrap / Meta's PWA packaging): a website that opens in Meta's browser, which Lepton doesn't have | None: open the URL in a browser. Analysis `extra.web_wrapper` (manifest meta-data `android.support.customtabs.trusted.DEFAULT_URL`, resolved through resources.arsc, or androidbrowserhelper's LauncherActivity) → a warning with the URL (not unsupported: the manifest alone never decides) |
 | `UnsatisfiedLinkError` / `cannot locate symbol "ovr_…"` | overport's platform loader lacks Meta platform functions | `frame.ovrstubs` (automatic, generated stubs) |
 | missing `ovrMessageType_ToString` | same, but the game needs a real string | `frame.ovrplatformcompat` (automatic) |
+| The game stays in its built-in language or waits at start although its OBB / files hold language packs (`<tag>.lang`, e.g. `de.lang`) | overport's platform loader answers `ovr_LanguagePack_GetCurrent/SetCurrent` with request id 0, so the game never gets the pack's path | `frame.langpacks` (opt-in, experimental, shown for games whose data has `*.lang`; `native/langpack`, build it with `python native/build.py --only langpack`). Default pack: the one the game applies, else env `FRAMEPORT_LANGPACK=<tag>`, else the only pack; search path override `FRAMEPORT_LANGPACK_DIRS`. Unreal games (Deadpool VR) grey out a pack whose asset `Metadata` differs from the game's version string: the patch writes the APK's versionName as Metadata (env `FRAMEPORT_LANGPACK_META` overrides) and reports the pack under the `/storage/emulated/0/Android/obb/<pkg>/` spelling of its path; with `/sdcard/…` the text switched but the dialogue stayed silent (verified in the headset with Deadpool VR) |
 | `ClassNotFoundException com.oculus.os.AnalyticsEvent` → abort | Quest telemetry lookup in Meta XR Audio (Unreal build) or native code | `frame.metaxr_telemetry` + `frame.oculusos` (automatic) |
 | `JNI DETECTED ERROR`, `GetStringUTFChars … NULL` | CheckJNI is on because overport marks the app debuggable | `frame.nodebug` |
 | Unreal game quits a few seconds after start (`System.exit`) | ForceQuit after a failed Quest platform check | alternate build with `patch_remove_unreal_force_quit` (`use_alt`) |
+| Unreal game crashes a few seconds after the logo with no backtrace (Unreal's own signal handler hides it: logcat-crash.log empty, Zygote `exited due to signal 11`); the crashing thread is `GameThread`, pc in `libaaudio.so`, lr `libovrplatformloader.so (ovr_Microphone_GetOutputBufferMaxSize+0x10)`; the last platform call is `ovr_Microphone_Create` (e.g. The Walking Dead: Saints & Sinners Ch. 2) | OVRPort's platform loader opens the microphone's AAudio stream only in `ovr_Microphone_Start`, but `GetOutputBufferMaxSize` reads that stream unchecked; Unreal's Oculus voice asks for the size right after `Create` | `frame.ovr_microphone` (NULL check rewritten in place; size 0 until the microphone starts). OVRPort runtime 3.4.3-aa54c3f has the check itself: builds made with it leave the patch out (log "not needed: frame.ovr_microphone", `patches/upstream.py`) |
 | `xrCreateSwapchain` -26 / format unsupported (GLES) | Frame takes only sRGB formats, no MSAA | adapter `swapchain_fix` (default on) |
 | Frames rejected, "Waiting…" forever | a layer uses a failed swapchain or an extension that isn't enabled (e.g. equirect2) | adapter `layer_fix` (default on) |
 | `xrConvert…TimeKHR` FUNCTION_UNSUPPORTED spam; VrApi bridge stalls before recenter | runtime lacks timespec conversion | current adapter emulates it |
@@ -47,14 +72,31 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Video stutters although fps is steady | video frame rate doesn't divide the refresh rate (30 fps at 72 Hz) | `adapter.refresh_rate` (e.g. 90 for 30 fps, 72 for 24 fps); `layer_debug` logs the offered rates and the app's own requests |
 | PC VR game judders/stutters although the GPU keeps up; vrcompositor.txt "Timed out. N total" high or frames dropped | the game misses the headset's refresh (e.g. 96 Hz = 10.4 ms; Stormland's slow frames take 10.7 ms) | `pcvr.steamvr_tuning` (default on): next Play sets SteamVR per-app `preferredRefreshRate` + `motionSmoothingOverride` via `fp_vrsettings.exe` |
 | Quest app keeps recentering / snapping the view when you turn your head; log shows session state 5→4→3→4→5 within a second | the Frame briefly takes focus; the app recenters on focus changes | unfixed: hiding the dips (debounce) made AC Nexus stay black, so it was removed |
-| Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | send files with Frame → Send files (~/Videos = /sdcard/Movies) and browse folders in the app |
+| Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | upload in the Files tab (Videos = /sdcard/Movies) and browse folders in the app |
+| Batman: Arkham Shadow closes during smoke-bomb effects; later input-tree corruption | Meta XR Audio Wwise deletes queued metadata still referenced by the current audio frame, then writes through the stale pointer | FrameBridge automatically retires metadata after current-frame references disappear, for the verified AArch64 SDK build only; see [AUDIO_METADATA.md](AUDIO_METADATA.md) |
+| Game stays on a loading or "Waiting" box although it reached FOCUSED; log `FrameBridge: xrEndFrame failed -25` then no more `pacing:` lines (e.g. PowerWash Simulator on some Frames, GitHub #39) | The eye image rect ends a few pixels past its swapchain (Unity rounds the swapchain width, the runtime's recommended size differs per Frame); SteamVR rejects every frame with XR_ERROR_SWAPCHAIN_RECT_INVALID | FrameBridge clamps every projection/quad image rect to its swapchain (`rect_clamp`, default on since 0.11.0; log `rect_clamp: view N image rect clamped`): rebuild + reinstall the game |
 | Game (Unity, GLES) freezes, `zink: DEVICE LOST` | multisampled render-to-texture hangs the GPU | `frame.unity_no_msaa`; if it persists: unfixable → PC version |
+| Only the Android home screen shows; the log has Unity's VR device as `None` (e.g. Accounting+, Unity 2017) | Unity 2017–2018 built-in Oculus support starts VR only when `com.oculus.systemactivities` is installed; Lepton has no Meta system apps, so Unity falls back to non-VR | `frame.unity_oculus_check`: that package name in libunity.so → `android`, plus `native/ovrpshim` (libfp_ovrp.so): Unity 2017's legacy frame loop (`ovrp_Update2`/`ovrp_BeginFrame`) never calls `ovrp_WaitToBeginFrame`, so without the shim no `xrWaitFrame` happens, `CompositorOpenXR::Update … outside of frame bounds` floods the log and the dashboard freezes. With it: log `ovrp frame loop shim: waited for frame N`, ~71 fps. Accounting+ then stops at "press any button" although its OVRInput gets clean input (`INPUT_PROBE` in the patch logs connected controllers/buttons/input focus per call) — unresolved |
+| Black flat window, then a GPU hang: kernel `hangcheck detected gpu lockup` (offending task the game), `zink: DEVICE LOST`, Unity render-thread crash; `outside of frame bounds` thousands of times a second (e.g. BattleSisters, Unity 2019.4) | Unity 2019 on its built-in VR (no `libOculusXRPlugin.so`) uses the same legacy frame loop as Unity 2017: no `xrWaitFrame`, the render thread floods the GPU | `frame.unity_oculus_check` adds the ovrpshim frame wait for these too (revision 2) |
+| Unreal game stuck on a loading image after the intro, frames keep coming (72 fps), no crash (e.g. Vader Immortal) | suspect: a Meta Platform SDK request no message ever answers | diagnostics: `frame.ovr_trace` (opt-in) logs every `ovr_*` call, the answers `ovr_PopMessage` returns and every 10 s the unanswered requests (`fp_ovrtrace` in launch.log). Never fake an entitlement answer |
+| Own-engine game crashes in `libVkLayer_fossilize.so` (Fossilize's recording thread, e.g. Roblox) | same as Deadpool VR: uninitialised pointers in what Fossilize records | `frame.vk_sanitize` now also covers own-engine libraries that load `libvulkan.so` by name |
+| Crash right after the game gets focus, in `vrclient.so … UpdateActionStateInternal` / `sxr_xrSyncActions` (e.g. Myst) | a race in the Frame runtime's input code on the first sync after focus (not every launch) | adapter `sync_guard` (input syncs one at a time with event polling, paused 250 ms after FOCUSED) |
+| View jumps sideways / game pauses or freezes for a moment every few seconds (e.g. Blade & Sorcery, BattleGlide) | the Frame drops focus for ~0.5 s (FOCUSED→VISIBLE→SYNCHRONIZED); games pause or re-align the player (`OnVRPresence … Teleport`) | adapter `focus_hold` |
+| SDL / LÖVE app crashes at start: `NullPointerException … ClipboardManager.addPrimaryClipChangedListener` in `SDLClipboardHandler.<init>` (e.g. Dramatic Shape) | Lepton's Android has no clipboard service (`service check clipboard`: not found) | `frame.sdl_clipboard` (that call → nops in classes.dex, in place, `apk/dex.py`); reproduced and verified with LÖVE for Android 11.5 |
+| Controllers do nothing (e.g. stuck on a setup screen); log: `xrSuggestInteractionProfileBindings … XR_ERROR_PATH_UNSUPPORTED` | the game only suggests bindings for Meta's newer profiles (Touch Plus / Touch Pro); the Frame's Android runtime knows `oculus/touch_controller`, not those | adapter `profile_remap` (default on): the bindings are suggested again for Touch (log: `controller profile … -> oculus/touch_controller`) |
+| Some buttons do nothing or the wrong thing (e.g. a Quest game's X/Y on the Frame's left controller) | the game binds only Quest Touch and SteamVR maps Touch onto the Frame controllers with its own remap (Touch left X/Y land on the d-pad, right X and Y repeat B), or the runtime rejected a profile or an input call | turn on adapter `input_diag` (diagnostics, off by default; `frameport settings <pkg> input_diag=1`) and look for `input_diag:` lines: `bindings: <profile> accepted` or `unsupported: interaction profile <profile> -> <result>` with the rejected paths, `bindings: /user/hand/<hand> uses <profile>`, `unsupported: function <name>`, `unsupported: xrCreateAction -> <result> (<action>)` |
+| Unity game hangs or the whole Frame restarts (e.g. in a menu); log: `The current MSAA level is 0, but the recommended MSAA level is 4. Switching to the recommended level.` (e.g. Lucky's Tale) | Meta's OVRManager (`useRecommendedMSAALevel`) turns 4x MSAA on at runtime, past QualitySettings; multisampled render-to-texture on GLES/Zink hangs the GPU | `frame.unity_runtime_msaa_off` (Cpp2IL: `OVRDisplay.get_recommendedMSAALevel` → 0) |
+| Unity game: one eye shows only effects or grey, the other is fine (e.g. I Am Cat, Oculus XR Plugin on GLES) | the game's single-pass multiview rendering goes wrong for array slice 1 (the adapter submits both slices correctly) | `frame.unity_multipass` (Cpp2IL: `OculusSettings.GetStereoRenderingMode` → MultiPass); `swap_eyes=1` tells whether the game or the adapter is at fault |
 | Setup/intro loops every launch (Espire 2) | save folders created without write permission | launcher repairs permissions every 2 s (built in) |
 | VrApi bridge: never enters VR | Frame reaches FOCUSED later than Quest; tracking only when worn | bridge waits 30 s; test in the headset |
 
 ## Picture problems (headset on)
 | Symptom | Cause | Fix |
 |---|---|---|
+| 2D Android app: Steam says it's running but nothing shows | Lepton runs apps headless unless the app folder has `lepton-show-flatscreen` | FramePort adds it for apps without VR (agent v28+); reinstall apps installed before |
+| A phone/tablet app shows nothing in the headset, or a VR app opens as a flat window | FramePort's VR/2D guess (`vr_kind`) is wrong for this app | patch `device.display_mode` → **Flat window** or **VR** (Customize → "Show as VR or as a flat window"), then Update on Frame |
+| "Install with FrameDrop" button opens FrameDrop (or nothing) instead of FramePort | another program owns `framedrop://`, or the switch is off, or macOS (Flet can't receive links there) | Settings → Install links → **Use FramePort for these links**; else Add games → Install from a link… (paste the button's address) |
+| 2D Android app: back/home/recents buttons cover the app's own buttons | Android's navigation bar | patch `device.hide_navbar` (on by default for apps without VR) sets `qemu.hw.mainkeys=1`; reinstall to apply |
 | Black screen, audio works, GLES engine with direct VrApi | Mesa rejects Quest-style GLSL | `frame.gl_shim` (logs `GLShim: SHADER COMPILE FAILED` + source lines) |
 | Black screen, audio works, log `Unsupported VrApi layer type N` | bridge drops frames containing that layer | extend the bridge (cylinder=3 is converted to a quad already) |
 | Only some draws visible (e.g. controllers) + `glGetError 0x502` | multiview shaders used on single-view FBOs | GL shim `gl_hide_multiview=1` (default) |
@@ -66,15 +108,60 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | MR game stuck waiting for room data (Demeter) | no Meta scene API | adapter `scene_emul=1` (+ `frame.meta_permissions`) |
 | Hand-tracking game janky (Silhouette) | Frame synthesizes hands from controllers | `controller_fix=0` passes hands through; not really fixable |
 | Eye distortion while moving (Arcsmith, Time Stall) | unknown (not eye swap, tracking, Valve layers, depth or pacing) | unresolved |
+| One eye grey / only effects (I Am Cat, Unity Oculus XR Plugin on GLES) | the game's multiview pass draws array slice 1 wrong on Zink | `frame.unity_multipass` (also rewrites the getter's inlined read in `OculusLoader.Initialize`; check for two `array=1` eye swapchains) |
+| View vibrates even when holding still after `frame.unity_multipass` (I Am Cat) | poses/times are consistent, but two passes on Zink make every frame one period late, and the game clamps its physics step to 10 ms | not fixed (scale 0.8 didn't help); next ideas: fix multiview instead, or the game's fixed timestep |
+| Game freezes / pauses for 0.5-2 s now and then, no flicker (e.g. Blade & Sorcery, Lucky's Tale) | the headset's wear sensor flickers off while worn (`logs/eyetracking.txt` `HMD off, stopping eye tracking` … `HMD on`), the Frame turns it into a focus loss and Quest games that pause on focus loss pause | adapter `focus_hold` (on by default since 2026-10-05, dips up to `focus_hold_ms` = 5000 ms are hidden; longer ones still pause) |
+| Minor glitches on some objects (Myst, Unreal Vulkan) | unknown; not application space warp (turning it off changed nothing and ran worse) | unresolved |
+| Graphics crash in vkCreateInstance with pc == fault address, from the game's own Vulkan hooks (BONELAB 1.2974 `libSLZQuestNative`) | a pointer into memory freed with OVRPlugin's pre-init OpenXR instance; not the runtime (vrclient.so) or Fossilize being unloaded (keeping both loaded with RTLD_NODELETE didn't help) | unresolved |
+| Unity game shows a picture but the player body is frozen: no head tracking, the controllers stay on the model, no buttons, although OpenXR input works (BONELAB 1.2068, Oculus XR Plugin) | OVRPlugin reports the headset as not worn (`ovrp_GetUserPresent2` → 0) a few seconds after start, and the game's rig only follows a present user (Marrow `XRHMD.IsUserPresent` = Unity's HMD `UserPresence`) | `frame.unity_user_presence` (the Oculus XR Plugin's lookup → `libfp_ovrp.so`, reports present; log `user presence: OVRPlugin 0 …`) |
+| Unreal 5 game crashes at its first render pass, backtrace `vulkan.freedreno.so` ← `libVkLayer_fossilize.so` ← `libfp_vk.so (create_render_pass2)` (Metro Awakening) | a subpass without a depth attachment names a depth/stencil resolve attachment; the Frame's Turnip reads the missing depth attachment (NULL) | the Vulkan shim drops that resolve (always, FramePort after 0.11.0; log `dropped the depth resolve of subpass N (no depth attachment)`); triage `unreal-vulkan-driver-crash` |
+| Unreal 5 game crashes in `vulkan.freedreno.so` called straight from `libUnreal.so` right after its swapchains, or a few seconds into the first frames (Metro Awakening) | Unreal turns on fragment-density-map foveation because Turnip offers VK_EXT_fragment_density_map, then records barriers (to `FRAGMENT_DENSITY_MAP_OPTIMAL`) and image views (2D array R8G8) for a density map the Frame never provides (VK_NULL_HANDLE); Turnip dereferences it | adapter `vk_hide_fdm=1` (the game doesn't see the extension) + `vk_spec_fixes=1` (leaves out null-image barriers, refuses null-image views); triage `unreal-fdm-missing`. Found by disassembling the driver at the crash pc: the struct offsets (0x58 = VkSubpassDescription2, 0x48/0x60 = image barriers, viewType/format in registers) name the call |
+| Own-engine game crashes in `je_free` from its own library on the first frames (Roblox) | the game frees memory it doesn't own; not the Vulkan shim or the format fallback | unsupported |
+
+## Live view (Live view tab, `install/livestream.py`)
+| Symptom | Cause | Fix |
+|---|---|---|
+| Status line says "software encoder" (30 fps, the Frame's CPU busier) | `fp_venc --probe` failed (missing upload, encoder busy or refused a format: exit 4) or the helper couldn't be put on the Frame | on the Frame: `~/.local/share/frameport/bin/fp_venc --probe; echo $?` and `--selftest`; the app log names upload failures. `FP_VENC_DISABLE=1` forces the fallback for tests |
+| Picture drifts out of sync with the sound | the hardware path relies on one H.264 frame per fps slot (ffmpeg `-framerate`); `fp_venc: stats … skipped=` > 0 on stderr means slots were skipped | see the stats line (every 10 s); a stopped/suspended Frame skips slots on purpose |
+| Viewer joins only after several seconds | the keyframe request (`k` on the channel) didn't reach the encoder; the viewer then waits for the next regular keyframe (4 s) | check `live: encoder=hardware` came first (requests are sent only then) |
 
 ## Debugging techniques that worked
 - A user's problem report: `frameport diag inspect <FramePort-diag-*.zip>` re-triages its launch log with the current
   signatures; the zip has the recipe, analysis, ELF/PE imports, Frame logs and versions (docs/DIAGNOSTICS.md).
 - Read `<base>/launch.log` (logcat mirror). Filter the game's pid: `Start proc <pid>:<package>`.
+- **Monitor tab** (GUI, while a game runs): fps from FrameBridge's pacing lines next to GPU busy %, the hottest
+  sensor, memory pressure and per-process CPU/GPU/memory. A memory runaway (Lucky's Tale, Vader Immortal) shows as
+  rising memory + "waiting" before the OOM kill; a GPU-bound game as GPU near 100 % with fps under target; heat as the
+  temperature tile turning amber/red. Sources and costs: FRAME_RUNTIME.md "Monitoring sources".
 - The adapter logs as `FrameBridge` (settings, xrCreateInstance result, swapchain retries, pacing fps).
 - For GLES/GLAD engines, wrap `eglGetProcAddress` to see shader compile errors (build the shim with `-DGLSHIM_TRACE`
   for per-FBO draw counts and draw-call errors; the bridge has `-DOVP_GL_DIAG` for eye-image readback).
 - Anything visual needs one headset session per iteration — batch hypotheses into each build.
+- Headless launch tests never get focus: they prove startup, not play. Crashes right after FOCUSED (Myst), focus
+  dips and judder only show up in a headset session: ask for one, then `frameport diag collect <pkg>` (it contains
+  the headset sessions too, plus this boot's kernel log).
+- Which library a stale pointer belonged to: turn on the Android linker's log for one run by adding
+  `debug.ld.app.<pkg>=dlopen` as an extra line of `LEPTON_GFXRECON_FP_PROPS` (first line `0`) in the game's
+  launch.sh on the Frame (back it up, restore it after) and look for `dlclose: unloading "…"`.
+- Memory runaways / busy loops: `perf` works as steamos (`perf_event_paranoid` 2, user space only; `ptrace_scope` 1
+  blocks eu-stack/gdb/debuggerd). `perf record -p <pid> -e page-faults -c 64 --call-graph fp` names the thread
+  touching new memory (`perf script -F comm,tid,ip,dso`); `-t <tid> -F 499` samples one thread. Map IL2CPP
+  addresses with a full Cpp2IL diffable-cs dump (method `Offset` = address − the r-xp mapping of libil2cpp.so).
+  Sample memory per mapping name from `/proc/<pid>/smaps` (`[anon:libc_malloc]` = native heap).
+- Unity catches native crashes itself: no debuggerd backtrace in Lepton's logcat-crash.log, but a
+  `tombstone_00` in the game's `Android/data/<pkg>/files/` with the memory map (map pc/lr/registers to libraries).
+- Focus losses: the game sees FOCUSED→VISIBLE→SYNCHRONIZED (OVRPlugin `[XR_SESSION]`, FrameBridge `focus_hold:`
+  lines); the cause is on the host: `~/.local/share/Steam/logs/vrserver.txt` (`HMD off/on`, `entering standby`,
+  `SystemButtonDown` in vrclient_vrcompositor.txt) and XRService (`[UserPresence]`, `IMUFallback`). Compare the times
+  (Lepton logs UTC, host logs local time).
+- A Unity getter patch that changes nothing: the compiler may have inlined it (no `BL` to its address in
+  libil2cpp.so) — patch the field read in the caller (`Il2cppReturnPatch.field_loads`).
+- Fixes found by users count: a reporter's shader capture (VR4) became the `vk_shader_fix` recipe data (match by size
+  + SHA-256, insert words); verify on the device that the log shows the module being fixed.
+- Don't install or test on the Frame while the owner is playing: adding a library entry restarts Steam (FramePort
+  now skips the restart when the shortcut is unchanged and waits while a game runs), and a launch test starts a game.
+- Catalog YAML: a `: ` inside an unquoted value breaks the file and the loader skipped it silently (the game vanished
+  from the list); `tests/test_catalog_files.py` now catches it.
 - Keep the known-good APK and roll back if a change regresses (`PATCHED/_known-good-*`).
 
 ## When it can't run on the Frame

docs/STYLE.md

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

native/README.md

@@ -1,5 +1,9 @@
 # Native components
 
+FrameBridge includes automatic metadata retirement for the verified Meta XR Audio
+Wwise build; see [AUDIO_METADATA.md](../docs/AUDIO_METADATA.md) for its lifetime
+invariant and regression coverage. It uses the existing adapter installation.
+
 Sources of the prebuilt binaries in `../artifacts/` (committed, with `SHA256SUMS`). End users never compile anything;
 developers rebuild with `python native/build.py` (downloads NDK r27c, OpenXR headers at pinned commits, d8 into
 `native/.cache/`, git-ignored). The adapter, GL shim and platform compat rebuild byte-identically; the VrApi bridge
@@ -7,13 +11,15 @@ embeds debug paths (`-g`) and the dex depends on the d8 version, so those differ
 
 | Dir | Artifact | What / why |
 |---|---|---|
-| `adapter/` | `{arm64-v8a,armeabi-v7a}/libopenxr_loader_generic.so` | **FrameBridge**: replaces overport's generic loader (which is renamed `libopenxr_loader_original.so`) and fixes Steam Frame runtime gaps. Hooks xrCreateInstance, swapchains, xrEndFrame, spaces, xrPollEvent, … everything else is forwarded by `gen_forwarders.py`-generated tail calls. `scene_emu.c` = Meta scene/spatial-entity emulation; `flip_vk.c` = Vulkan blit for VERTICAL_FLIP quads. `session_fixes.c` = per-game session fixes, all off by default and hooked only when on (`layer_debug` diagnostics, `stable_local`, `focus_hold`, aim correction `aim_pitch/aim_yaw/aim_forward`, `refresh_rate`); `layer_emul_gl.c` = `equirect_emul` (GLES sessions only): 360° equirect/equirect2 layers become one adapter projection layer, drawn by a worker thread with its own EGL context shared with the app's: each 360° image is converted to a cube map only when it changes, and the view is redrawn only after a 4° head turn (GL/EGL resolved with dlopen, so Vulkan games never load them); `layer_math.h` = their pose/face math, tested on the host by `tests/test_layer_emul.py`. `render_model.c` = XR_FB_render_model emulation (setting `controller_models`, off by default): serves `files/framebridge/controller_{left,right}.glb`, which the agent converts on the Frame from SteamVR's own Frame controller render models (never shipped by FramePort); tested on the host by `tests/test_render_model.py`. Settings: `libframe_settings.so` in the APK + `settings.conf`/`framebridge.conf` on the Frame. |
-| `vrapi-bridge/` | `arm64-v8a/libvrapi.so` | VrApi → OpenXR bridge from [Android-XR-Bridge/OVRPort](https://github.com/Android-XR-Bridge/OVRPort) `native/vrapi` at 5e7df52 (GPL-3.0, `LICENSE.upstream`; unchanged upstream as of OVRPort v1.2.5, which ships the unpatched code as its opt-in `patch_vrapi_openxr` in experimental CLI builds), with our changes in `upstream-patches/`: GLES sessions + GL texture swapchains, cylinder→quad layers, GL vertical flip, UNORM↔sRGB format twins, 30 s VR-mode deadline, VALID-only recenter, loading-icon layers skipped, diagnostics behind `-DOVP_GL_DIAG`. |
+| `adapter/` | `{arm64-v8a,armeabi-v7a}/libopenxr_loader_generic.so` | **FrameBridge**: replaces overport's generic loader (which is renamed `libopenxr_loader_original.so`) and fixes Steam Frame runtime gaps. Hooks xrCreateInstance, swapchains, xrEndFrame, spaces, xrPollEvent, … everything else is forwarded by `gen_forwarders.py`-generated tail calls. `scene_emu.c` = Meta scene/spatial-entity emulation; `flip_vk.c` = Vulkan blit for VERTICAL_FLIP quads. `session_fixes.c` = per-game session fixes, all off by default and hooked only when on (`layer_debug` diagnostics, `stable_local`, `focus_hold`, aim correction `aim_pitch/aim_yaw/aim_forward`, `refresh_rate`); `input_diag.c` = controller-input diagnostics (setting `input_diag`, off by default and hooked only when on; logs suggested interaction profiles and the runtime's answers, each hand's current profile, functions the runtime lacks and failing input/haptics/perf calls, each line once; tested on the host by `tests/test_input_diag.py`); `layer_emul_gl.c` = `equirect_emul` (GLES sessions only): 360° equirect/equirect2 layers become one adapter projection layer, drawn by a worker thread with its own EGL context shared with the app's: each 360° image is converted to a cube map only when it changes, and the view is redrawn only after a 4° head turn (GL/EGL resolved with dlopen, so Vulkan games never load them); `layer_math.h` = their pose/face math, tested on the host by `tests/test_layer_emul.py`. `render_model.c` = XR_FB_render_model emulation (setting `controller_models`, off by default): serves `files/framebridge/controller_{left,right}.glb`, which the agent converts on the Frame from SteamVR's own Frame controller render models (never shipped by FramePort); tested on the host by `tests/test_render_model.py`. Settings: `libframe_settings.so` in the APK + `settings.conf`/`framebridge.conf` on the Frame. |
+| `vrapi-bridge/` | `arm64-v8a/libvrapi.so` | VrApi → OpenXR bridge from [Android-XR-Bridge/OVRPort](https://github.com/Android-XR-Bridge/OVRPort) `native/vrapi` at 5e7df52 (GPL-3.0, `LICENSE.upstream`; unchanged upstream as of OVRPort v1.2.5, which ships the unpatched code as its opt-in `patch_vrapi_openxr` in experimental CLI builds), with our changes in `upstream-patches/`: GLES sessions + GL texture swapchains, cylinder→quad layers, GL vertical flip, UNORM↔sRGB format twins, 30 s VR-mode deadline, VALID-only recenter, loading-icon layers skipped, `vrapi_PollEvent`/`RecenterPose`/`SetDisplayRefreshRate`/`GetSystemPropertyFloatArray` (BlazeRush imports them, GitHub #57), diagnostics behind `-DOVP_GL_DIAG`. `upstream-patches/` reproduces these sources from the fork's `native/vrapi` (checked 2026-10-06 against its latest commit); upstream PRs Android-XR-Bridge/OVRPort#3-#8, tracked in GitHub #75. |
 | `platformcompat/` | `arm64-v8a/libovrplatformcompat.so` | Real `ovrMessageType_ToString` (same fork, `native/platform`). |
+| `langpack/` | `arm64-v8a/libfp_langpack.so` | Language packs for the Meta Platform SDK (patch `frame.langpacks`, opt-in). overport's platform loader is a dispatcher in front of Meta's own loader and answers `ovr_LanguagePack_GetCurrent/SetCurrent` with `return 0` (no reply ever). This library becomes the loader's first DT_NEEDED; the loader's own exports of the 31 functions it defines are made STB_LOCAL in `.dynsym` (`elf.hide_exports`, nothing moves), so symbol lookups reach the library first. It serves `<tag>.lang` files found in the game's OBB / app files (`$FRAMEPORT_LANGPACK_DIRS` overrides the search path) through `ovr_LanguagePack_*`, `ovr_AssetFile_GetList` (the loader's list + the packs) and `ovr_AssetFile_StatusById`; its own message queue is merged into `ovr_PopMessage`, and every handle that is not ours (an address-range check) goes to the loader's original function, whose address is read at run time from the loader's in-memory `.dynsym`. With patch `frame.asset_files` (marker byte `@FPASSETS@`, or env `FRAMEPORT_ASSET_FILES=1`) it also lists the data's `*.pak` content files as installed `default` asset files and answers `ovr_AssetFile_DownloadById` for them at once (a completed `DownloadUpdate`, then the result with the path). Host-tested against a stand-in loader (`tests/test_langpack.py`, plain `cc`, no NDK); the bionic/headset side is unverified. |
 | `glshim/` | `arm64-v8a/libglshim.so` | Mesa GLSL compatibility for GLAD engines (hooks eglGetProcAddress): comments out `#pragma` before `#extension`, enables `GL_EXT_shader_implicit_conversions`, hides GL_OVR_multiview (`gl_hide_multiview`, default 1) and logs failed shaders. `-DGLSHIM_TRACE` adds per-FBO draw/error tracing. |
 | `xrlayer/` | `linux-arm64/libxr_frameport_timefix.so` + `XR_APILAYER_FRAMEPORT_timefix.json` | OpenXR API layer for Windows PC VR games under Proton on the Frame (glibc aarch64, built freestanding with the NDK's clang), on by default (patch `pcvr.xr_timefix`). Retries `xrCreateInstance` as an OpenXR 1.0 app when the runtime rejects 1.1 (the Frame's SteamVR runtime does, and Proton 11's VR helper asks for 1.1). Also emulates `xrConvertTimespecTimeToTimeKHR`/`xrConvertTimeToTimespecTimeKHR` if the runtime refuses them (the Frame's Android runtime does; its Linux runtime, used by Proton, supports them as of 2026-09-29 — so this part is only a fallback; Proton's wineopenxr needs them for `XR_KHR_win32_convert_performance_counter_time`, which Revive requires) with the adapter's xrWaitFrame-calibrated offset, and drops the extension from xrCreateInstance if the runtime rejects it. Enabled per game by the Proton launch.sh (`XR_API_LAYER_PATH`, `XR_ENABLE_API_LAYERS`). `tests/test_xrlayer.py` builds it for x86_64 and drives it via ctypes. |
 | `oculushmd/` | `win-x64/fp_oculushmd.exe` | PC VR counterpart of overport's `patch_oculus_unreal` (patch `pcvr.oculus_unreal`, default for Unreal Rift games on the Frame). Unreal's OculusHMD and LibOVR's `ovr_Detect` only start when the Windows named event `OculusHMDConnected` exists and is signalled (the Oculus service creates it). `fp_oculushmd.exe <command line>` creates it (manual reset, signalled), runs the command (Revive's injector) in a job object and keeps the event until every process in the job — the game and its children — has exited (fallback without job support: 3 minutes); returns the command's exit code and logs `FramePort oculushmd: …` to stderr (launch.log). Freestanding Windows x64 console exe (no CRT, no Windows SDK): the NDK's clang + `lld-link /Brepro` with a kernel32 import library generated by `llvm-dlltool`, so it's byte-reproducible. Tested on Windows from WSL with a build whose event name is `-DEVENT_NAME=L"…"` (the Oculus service owns the real event on a PC with the Oculus app). |
 | `xrshim/` | `arm64-v8a/libframe_xrshim.so` | FrameBridge extension shim, only in builds with `controller_models=1`. overport's dispatcher (`libopenxr_loader.so`) answers `xrGetInstanceProcAddr` from a fixed table and refuses everything else (`overportOXR: Unknown proc addr: xrLoadRenderModelFB`), so the adapter never sees XR_FB_render_model lookups. Meta's OVRPlugin gets the function with `dlopen("libopenxr_loader.so")` + `dlsym`, so FramePort rewrites that `.rodata` string in `libOVRPlugin.so` (same length, in place) to `libframe_xrshim.so`. The shim returns the adapter's emulated functions (`framebridge_extension_proc`) and forwards every other name to overport. A DT_NEEDED interposer does not work here (dlsym on a handle searches that library first); tried and dropped. |
+| `venc/` | `linux-arm64-bin/fp_venc` | Hardware H.264 encoder for the live view, run on the Frame (spec: `venc/SPEC.md`). Reads SteamVR's "headset view" webcam (v4l2loopback `/dev/video99`, RGB24), box-scales and converts it to NV12 (BT.709 limited range; `convert.c`, NEON with a bit-identical scalar reference, also built for x86_64 by the host test), and feeds the SoC's V4L2 stateful encoder (`dev-encoder.rst`, Qualcomm iris `/dev/video-enc0`): CBR, no B-frames, SPS/PPS on every IDR, one frame per slot of a fixed grid (fps = a divisor of the panel refresh read through DRM KMS, default cap 45), Annex B on stdout. stdin `k` = keyframe, `q`/EOF = drain and stop; `--probe` prints the setup as JSON, `--selftest` compares NEON and scalar output. Fully static and freestanding (raw syscalls, own `_start`; only the NDK's kernel UAPI headers, staged in `.cache/uapi-arm64`), byte-reproducible. Lives in `linux-arm64-bin/` because `linux-arm64/` is uploaded whole as the OpenXR layer. |
 | `java-stubs/` | `dex/oculusos-stubs.dex` | No-op `com.oculus.os.AnalyticsEvent` / `UnifiedTelemetryLogger` for native code that looks them up. |
 
 The ovr_* stub library is *not* prebuilt: `src/frameport/analysis/stubgen.py` generates it per game from the exact

native/adapter/audio_metadata.h

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Meta XR Audio Wwise metadata retirement. Enabled automatically for the
+// exact verified AArch64 SDK build; unrelated libraries remain untouched.
+#pragma once
+#if defined(__aarch64__)
+#include <pthread.h>
+#include <sched.h>
+#include <sys/mman.h>
+#include <unistd.h>
+#include <stdint.h>
+#include <time.h>
+#include <link.h>
+#include <string.h>
+static size_t mx_audio_page;
+static void *mx_audio_detour(unsigned char *address,void *replacement,const uint32_t expected[4]) {
+    if(memcmp(address,expected,16)) return NULL;
+    unsigned char *trampoline=mmap(NULL,mx_audio_page,PROT_READ|PROT_WRITE,MAP_PRIVATE|MAP_ANONYMOUS,-1,0);
+    if(trampoline==MAP_FAILED) return NULL;
+    uint32_t branch[2]={0x58000050u,0xd61f0200u}; // ldr x16, +8; br x16
+    memcpy(trampoline,address,16);
+    memcpy(trampoline+16,branch,8);
+    uintptr_t continuation=(uintptr_t)address+16;
+    memcpy(trampoline+24,&continuation,8);
+    __builtin___clear_cache((char*)trampoline,(char*)trampoline+32);
+    if(mprotect(trampoline,mx_audio_page,PROT_READ|PROT_EXEC)) return NULL;
+    unsigned char *page=(unsigned char*)((uintptr_t)address&~(mx_audio_page-1));
+    if(mprotect(page,mx_audio_page,PROT_READ|PROT_WRITE|PROT_EXEC)) return NULL;
+    memcpy(address,branch,8);
+    memcpy(address+8,&replacement,8);
+    __builtin___clear_cache((char*)address,(char*)address+16);
+    mprotect(page,mx_audio_page,PROT_READ|PROT_EXEC);
+    return trampoline;
+}
+#include "audio_metadata_queue.h"
+typedef struct {float previous,current;} MxAudioRamp;
+static uintptr_t mx_audio_base;
+// set once the library was found but isn't the verified build: stop looking (xrPollEvent runs several times a frame)
+static int mx_audio_checked;
+static uint64_t (*mx_audio_consume_original)(void*,void*,void*,const void*,MxAudioRamp);
+static void mx_audio_kill(unsigned experimental) {
+    void *mutex=(void*)(mx_audio_base+(experimental?0x5fe2e0:0x5fe380));
+    int (*trylock)(void*)=(void*)(mx_audio_base+0x5b369c);
+    void (*unlock)(void*)=(void*)(mx_audio_base+0x5b36bc);
+    if(!trylock(mutex))return;
+    mx_audio_drain((void**)(mx_audio_base+(experimental?0x5fe2d8:0x5fe378)),experimental?40:24);
+    unlock(mutex);
+}
+static void mx_audio_kill_experimental(void) {mx_audio_kill(1);}
+static void mx_audio_kill_regular(void) {mx_audio_kill(0);}
+static uint64_t mx_audio_consume(void *sink,void *main_mix,void *passthrough,const void *objects,MxAudioRamp ramp) {
+    const unsigned char *previous=mx_audio_objects;mx_audio_objects=objects;
+    // An audio thread can enter just after its prologue was patched, before
+    // the installing thread publishes the completed trampoline.
+    uint64_t (*original)(void*,void*,void*,const void*,MxAudioRamp);
+    while(!(original=__atomic_load_n(&mx_audio_consume_original,__ATOMIC_ACQUIRE)))sched_yield();
+    uint64_t result=original(sink,main_mix,passthrough,objects,ramp);
+    mx_audio_objects=previous;return result;
+}
+static int mx_audio_find(struct dl_phdr_info *info,size_t size,void *unused) {
+    (void)size;(void)unused;
+    if(!strstr(info->dlpi_name,"/libMetaXRAudioWwise.so"))return 0;
+    if(mx_audio_base)return 1;
+    const unsigned char id[20]={0xe1,0x61,0x9e,0x7f,0xb8,0x39,0xba,0xdf,0x0e,0xa5,0xec,0xc2,0x2d,0x9f,0x02,0x8d,0x0b,0x17,0xc3,0x4d};
+    int match=0;
+    for(unsigned i=0;i<info->dlpi_phnum;i++)if(info->dlpi_phdr[i].p_type==PT_NOTE) {
+        const unsigned char *p=(void*)(info->dlpi_addr+info->dlpi_phdr[i].p_vaddr);
+        const unsigned char *end=p+info->dlpi_phdr[i].p_memsz;
+        while(p+sizeof(Elf64_Nhdr)<=end) {
+            const Elf64_Nhdr *note=(void*)p;
+            const unsigned char *name=p+sizeof(*note),*desc=name+((note->n_namesz+3)&~3u);
+            const unsigned char *next=desc+((note->n_descsz+3)&~3u);
+            if(next>end || next<=p)break;
+            if(note->n_type==NT_GNU_BUILD_ID && note->n_namesz==4 && !memcmp(name,"GNU",4) && note->n_descsz==20 && !memcmp(desc,id,20))match=1;
+            p=next;
+        }
+    }
+    if(!match){__atomic_store_n(&mx_audio_checked,1,__ATOMIC_RELEASE);return 1;}
+    const uint32_t consume[4]={0xd10743ff,0x6d1623e9,0xa9177bfd,0xa9186ffc};
+    const uint32_t kill[4]={0xa9bd7bfd,0xf9000bf5,0xa9024ff4,0x910003fd};
+    unsigned char *base=(void*)info->dlpi_addr;
+    if(memcmp(base+0x2c8fac,consume,16) || memcmp(base+0x2be2c0,kill,16) || memcmp(base+0x2be7b0,kill,16)) {
+        __atomic_store_n(&mx_audio_checked,1,__ATOMIC_RELEASE);return 1;
+    }
+    __atomic_store_n(&mx_audio_base,info->dlpi_addr,__ATOMIC_RELEASE);
+    void *original=mx_audio_detour(base+0x2c8fac,(void*)mx_audio_consume,consume);
+    __atomic_store_n(&mx_audio_consume_original,original,__ATOMIC_RELEASE);
+    if(!__atomic_load_n(&mx_audio_consume_original,__ATOMIC_ACQUIRE)) {
+        __atomic_store_n(&mx_audio_base,0,__ATOMIC_RELEASE);return 1;
+    }
+    if(!mx_audio_detour(base+0x2be2c0,(void*)mx_audio_kill_experimental,kill) || !mx_audio_detour(base+0x2be7b0,(void*)mx_audio_kill_regular,kill)) {
+        LOG("FrameBridge audio metadata: incomplete installation");return 1;
+    }
+    LOG("FrameBridge audio metadata: metadata reclamation follows current audio-frame references; Meta audio base=%p",base);
+    return 1;
+}
+static pthread_mutex_t mx_audio_install_mutex=PTHREAD_MUTEX_INITIALIZER;
+static void mx_audio_initialize(void) {
+    if(__atomic_load_n(&mx_audio_base,__ATOMIC_ACQUIRE) || __atomic_load_n(&mx_audio_checked,__ATOMIC_ACQUIRE))return;
+    // until the game loads the library: look at most once a second (dl_iterate_phdr takes the linker's lock)
+    static _Atomic long mx_audio_last_scan;
+    struct timespec now;clock_gettime(CLOCK_MONOTONIC,&now);
+    if(now.tv_sec==mx_audio_last_scan)return;
+    mx_audio_last_scan=now.tv_sec;
+    if(pthread_mutex_trylock(&mx_audio_install_mutex))return;
+    if(!mx_audio_page)mx_audio_page=(size_t)sysconf(_SC_PAGESIZE);
+    if(!mx_audio_base)dl_iterate_phdr(mx_audio_find,NULL);
+    pthread_mutex_unlock(&mx_audio_install_mutex);
+}
+#else
+static void mx_audio_initialize(void) {}
+#endif

native/adapter/audio_metadata_queue.h

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: GPL-3.0-only
+#pragma once
+#include <stdint.h>
+#include <stddef.h>
+#include <string.h>
+// Experimental lifetime repair for the pinned Meta XR Audio Wwise build.
+// A queued metadata object must not be reclaimed while the current immutable
+// AkAudioObjects snapshot still references it. Preserve the SDK's queue mutex,
+// virtual destructor, list linkage, audio processing, and dirty-flag writes.
+static _Thread_local const unsigned char *mx_audio_objects;
+static unsigned mx_audio_held,mx_audio_reclaimed;
+static int mx_audio_referenced(const void *pointer) {
+    if(!mx_audio_objects)return 0;
+    uint32_t count;memcpy(&count,mx_audio_objects,4);
+    const unsigned char *const *objects;memcpy(&objects,mx_audio_objects+16,8);
+    // Refuse to reclaim on an unrecognised snapshot rather than dereferencing
+    // unbounded arrays. These bounds exceed the game's ordinary voice counts.
+    if(count>4096 || (count && !objects))return 1;
+    for(unsigned i=0;i<count;i++) {
+        const unsigned char *object=objects[i];if(!object)continue;
+        uint32_t metadata_count;const unsigned char *metadata;
+        memcpy(&metadata,object+104,8);memcpy(&metadata_count,object+112,4);
+        if(metadata_count>4096 || (metadata_count && !metadata))return 1;
+        for(unsigned j=0;j<metadata_count;j++) {
+            const void *parameter;memcpy(&parameter,metadata+(size_t)j*24+8,8);
+            if(parameter==pointer)return 1;
+        }
+    }
+    return 0;
+}
+// Caller holds the original queue's mutex, just as ExecuteKillList did.
+static void mx_audio_drain(void **head,size_t next_offset) {
+    void **link=head;
+    while(*link) {
+        void *pointer=*link;void **next=(void**)((unsigned char*)pointer+next_offset);
+        if(mx_audio_referenced(pointer)) {
+            link=next;
+            unsigned held=__atomic_fetch_add(&mx_audio_held,1,__ATOMIC_RELAXED);
+            if(held<8)LOG("FrameBridge audio metadata: queued metadata=%p still referenced by audio frame; retained",pointer);
+        } else {
+            *link=*next;
+            void (**table)(void*)=*(void (***)(void*))pointer;
+            table[1](pointer);
+            __atomic_fetch_add(&mx_audio_reclaimed,1,__ATOMIC_RELAXED);
+        }
+    }
+}

native/adapter/eye_debug.c

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

native/adapter/forwarders.S

@@ -1,19 +1,4 @@
 // Generated: register-preserving tail-call forwarders (see frame_adapter.c).
-    .text
-    .p2align 2
-    .globl xrApplyHapticFeedback
-    .type xrApplyHapticFeedback, %function
-xrApplyHapticFeedback:
-    adrp x16, fwd_xrApplyHapticFeedback
-    ldr x16, [x16, :lo12:fwd_xrApplyHapticFeedback]
-    br x16
-    .size xrApplyHapticFeedback, .-xrApplyHapticFeedback
-    .data
-    .p2align 3
-    .globl fwd_xrApplyHapticFeedback
-    .hidden fwd_xrApplyHapticFeedback
-fwd_xrApplyHapticFeedback:
-    .quad frame_unsupported
     .text
     .p2align 2
     .globl xrAttachSessionActionSets
@@ -28,21 +13,6 @@ xrAttachSessionActionSets:
     .globl fwd_xrAttachSessionActionSets
     .hidden fwd_xrAttachSessionActionSets
 fwd_xrAttachSessionActionSets:
-    .quad frame_unsupported
-    .text
-    .p2align 2
-    .globl xrBeginFrame
-    .type xrBeginFrame, %function
-xrBeginFrame:
-    adrp x16, fwd_xrBeginFrame
-    ldr x16, [x16, :lo12:fwd_xrBeginFrame]
-    br x16
-    .size xrBeginFrame, .-xrBeginFrame
-    .data
-    .p2align 3
-    .globl fwd_xrBeginFrame
-    .hidden fwd_xrBeginFrame
-fwd_xrBeginFrame:
     .quad frame_unsupported
     .text
     .p2align 2
@@ -403,21 +373,6 @@ xrPathToString:
     .globl fwd_xrPathToString
     .hidden fwd_xrPathToString
 fwd_xrPathToString:
-    .quad frame_unsupported
-    .text
-    .p2align 2
-    .globl xrReleaseSwapchainImage
-    .type xrReleaseSwapchainImage, %function
-xrReleaseSwapchainImage:
-    adrp x16, fwd_xrReleaseSwapchainImage
-    ldr x16, [x16, :lo12:fwd_xrReleaseSwapchainImage]
-    br x16
-    .size xrReleaseSwapchainImage, .-xrReleaseSwapchainImage
-    .data
-    .p2align 3
-    .globl fwd_xrReleaseSwapchainImage
-    .hidden fwd_xrReleaseSwapchainImage
-fwd_xrReleaseSwapchainImage:
     .quad frame_unsupported
     .text
     .p2align 2
@@ -523,20 +478,5 @@ xrSyncActions:
     .globl fwd_xrSyncActions
     .hidden fwd_xrSyncActions
 fwd_xrSyncActions:
-    .quad frame_unsupported
-    .text
-    .p2align 2
-    .globl xrWaitSwapchainImage
-    .type xrWaitSwapchainImage, %function
-xrWaitSwapchainImage:
-    adrp x16, fwd_xrWaitSwapchainImage
-    ldr x16, [x16, :lo12:fwd_xrWaitSwapchainImage]
-    br x16
-    .size xrWaitSwapchainImage, .-xrWaitSwapchainImage
-    .data
-    .p2align 3
-    .globl fwd_xrWaitSwapchainImage
-    .hidden fwd_xrWaitSwapchainImage
-fwd_xrWaitSwapchainImage:
     .quad frame_unsupported
     .section .note.GNU-stack,"",%progbits

native/adapter/forwarders.inc

@@ -1,7 +1,5 @@
 // Generated from overport 3.4.3 libopenxr_loader_generic.so exports minus hooked functions.
-FORWARD(xrApplyHapticFeedback)
 FORWARD(xrAttachSessionActionSets)
-FORWARD(xrBeginFrame)
 FORWARD(xrBeginSession)
 FORWARD(xrCreateAction)
 FORWARD(xrCreateActionSet)
@@ -26,7 +24,6 @@ FORWARD(xrGetReferenceSpaceBoundsRect)
 FORWARD(xrGetSystem)
 FORWARD(xrGetViewConfigurationProperties)
 FORWARD(xrPathToString)
-FORWARD(xrReleaseSwapchainImage)
 FORWARD(xrRequestExitSession)
 FORWARD(xrResultToString)
 FORWARD(xrStopHapticFeedback)
@@ -34,4 +31,3 @@ FORWARD(xrStringToPath)
 FORWARD(xrStructureTypeToString)
 FORWARD(xrSuggestInteractionProfileBindings)
 FORWARD(xrSyncActions)
-FORWARD(xrWaitSwapchainImage)

native/adapter/forwarders_arm32.S

@@ -3,23 +3,6 @@
     .arm
     .text
     .p2align 2
-    .globl xrApplyHapticFeedback
-    .type xrApplyHapticFeedback, %function
-xrApplyHapticFeedback:
-    ldr ip, 1f
-2:  add ip, pc, ip
-    ldr ip, [ip]
-    bx ip
-1:  .word fwd_xrApplyHapticFeedback - (2b + 8)
-    .size xrApplyHapticFeedback, .-xrApplyHapticFeedback
-    .data
-    .p2align 2
-    .globl fwd_xrApplyHapticFeedback
-    .hidden fwd_xrApplyHapticFeedback
-fwd_xrApplyHapticFeedback:
-    .word frame_unsupported
-    .text
-    .p2align 2
     .globl xrAttachSessionActionSets
     .type xrAttachSessionActionSets, %function
 xrAttachSessionActionSets:
@@ -34,23 +17,6 @@ xrAttachSessionActionSets:
     .globl fwd_xrAttachSessionActionSets
     .hidden fwd_xrAttachSessionActionSets
 fwd_xrAttachSessionActionSets:
-    .word frame_unsupported
-    .text
-    .p2align 2
-    .globl xrBeginFrame
-    .type xrBeginFrame, %function
-xrBeginFrame:
-    ldr ip, 1f
-2:  add ip, pc, ip
-    ldr ip, [ip]
-    bx ip
-1:  .word fwd_xrBeginFrame - (2b + 8)
-    .size xrBeginFrame, .-xrBeginFrame
-    .data
-    .p2align 2
-    .globl fwd_xrBeginFrame
-    .hidden fwd_xrBeginFrame
-fwd_xrBeginFrame:
     .word frame_unsupported
     .text
     .p2align 2
@@ -459,23 +425,6 @@ xrPathToString:
     .globl fwd_xrPathToString
     .hidden fwd_xrPathToString
 fwd_xrPathToString:
-    .word frame_unsupported
-    .text
-    .p2align 2
-    .globl xrReleaseSwapchainImage
-    .type xrReleaseSwapchainImage, %function
-xrReleaseSwapchainImage:
-    ldr ip, 1f
-2:  add ip, pc, ip
-    ldr ip, [ip]
-    bx ip
-1:  .word fwd_xrReleaseSwapchainImage - (2b + 8)
-    .size xrReleaseSwapchainImage, .-xrReleaseSwapchainImage
-    .data
-    .p2align 2
-    .globl fwd_xrReleaseSwapchainImage
-    .hidden fwd_xrReleaseSwapchainImage
-fwd_xrReleaseSwapchainImage:
     .word frame_unsupported
     .text
     .p2align 2
@@ -595,22 +544,5 @@ xrSyncActions:
     .globl fwd_xrSyncActions
     .hidden fwd_xrSyncActions
 fwd_xrSyncActions:
-    .word frame_unsupported
-    .text
-    .p2align 2
-    .globl xrWaitSwapchainImage
-    .type xrWaitSwapchainImage, %function
-xrWaitSwapchainImage:
-    ldr ip, 1f
-2:  add ip, pc, ip
-    ldr ip, [ip]
-    bx ip
-1:  .word fwd_xrWaitSwapchainImage - (2b + 8)
-    .size xrWaitSwapchainImage, .-xrWaitSwapchainImage
-    .data
-    .p2align 2
-    .globl fwd_xrWaitSwapchainImage
-    .hidden fwd_xrWaitSwapchainImage
-fwd_xrWaitSwapchainImage:
     .word frame_unsupported
     .section .note.GNU-stack,"",%progbits

native/adapter/frame_adapter.c

@@ -26,6 +26,9 @@
 //    render_model.c);
 //  * per-game session fixes (session_fixes.c, all off by default): layer_debug diagnostics, stable_local,
 //    focus_hold, aim pose correction (aim_pitch/aim_yaw/aim_forward), refresh_rate;
+//  * optionally logs controller-input diagnostics: suggested interaction profiles and the runtime's answers, each
+//    hand's current profile, functions the runtime lacks, failing input/haptics/perf calls (input_diag,
+//    input_diag.c, off by default);
 //  * optionally shows 360° (equirect/equirect2) layers as cube-face quads drawn by a worker thread with a shared
 //    GLES context (equirect_emul, layer_emul_gl.c; GLES sessions only, off by default).
 //
@@ -45,17 +48,63 @@
 #include <string.h>
 
 #define TAG "FrameBridge"
-#define LOG(...) __android_log_print(ANDROID_LOG_INFO, TAG, __VA_ARGS__)
+#include <stdarg.h>
+#include <time.h>
+// Everything also goes to <app external files>/framebridge.log when eye_debug is on: some games end Lepton's logcat
+// mirror early (WiiCompiled), so a headset session's diagnostics would otherwise be lost.
+static FILE *log_file;
+static void fb_log(const char *fmt, ...) __attribute__((format(printf, 1, 2)));
+static void fb_log(const char *fmt, ...) {
+    va_list args;
+    va_start(args, fmt);
+    __android_log_vprint(ANDROID_LOG_INFO, TAG, fmt, args);
+    va_end(args);
+    if (!log_file) return;
+    struct timespec now;
+    clock_gettime(CLOCK_REALTIME, &now);
+    flockfile(log_file);
+    fprintf(log_file, "%lld.%03ld ", (long long)now.tv_sec, now.tv_nsec / 1000000);
+    va_start(args, fmt);
+    vfprintf(log_file, fmt, args);
+    va_end(args);
+    fputc('\n', log_file);
+    fflush(log_file);
+    funlockfile(log_file);
+}
+#define LOG(...) fb_log(__VA_ARGS__)
+#include "audio_metadata.h"
 
 static void *loader;
 static PFN_xrGetInstanceProcAddr next_gipa;
 static pthread_once_t init_once = PTHREAD_ONCE_INIT;
 static XrInstance active_instance = XR_NULL_HANDLE;
+static void *android_vm;     // JavaVM from XrInstanceCreateInfoAndroidKHR (surface_swapchain.c)
+static int surface_emul = 1;  // setting: emulate Android surface swapchains
+static int eye_debug;          // setting: per-eye diagnostics + file log (eye_debug.c)
+static int release_wait;       // setting: wait for the app's GPU work before releasing images (2 = after 60 s: A/B)
+static void surf_on_destroy(XrSwapchain handle);
 
 static float scale = 1.0f;
 static int foveation_fix = 1;
+// hide XR_FB_space_warp: games then render every frame themselves (UE5 Application SpaceWarp flickered on the Frame,
+// e.g. Into The Radius 2; OVRPort's patch_disable_space_warp doesn't reach UE5's OpenXR plugin)
+static int hide_space_warp = 0;
+static int strip_color_bias = 0;
+static int snapshot = 0;  // seconds between eye-image snapshots (snapshot_gl.c; 0 = off)
+static char snap_dir[256];
+static void snap_on_create(XrSwapchain handle, const XrSwapchainCreateInfo *info);
+static void snap_on_destroy(XrSwapchain handle);
+static void snap_on_enumerate(XrSwapchain handle, uint32_t count, const XrSwapchainImageBaseHeader *images);
+static void snap_on_acquire(XrSwapchain handle, uint32_t index);
+static void snap_end_frame(const XrFrameEndInfo *info);
+static int frame_balance = 0;  // end a still-open frame before the next xrBeginFrame
+static int frame_begins, frame_discarded, frame_ends, frame_balanced;  // per pacing period (layer_debug)
+static int frame_open;
+static int sc_acquires, sc_waits, sc_releases, sc_wait_fails;  // per pacing period (layer_debug)  // drop XrCompositionLayerColorScaleBiasKHR (the runtime's color pass)
 static int controller_fix = 1;
 static int swapchain_fix = 1;
+static int rect_clamp = 1;
+static int pose_consistency = 0;  // repeat xrLocateViews queries for one display time get the same poses (GitHub #8)  // clamp submitted image rects to their swapchain (SteamVR rejects a 1 px overrun)
 static int layer_fix = 1;
 static int mutable_fix = 0;
 static int swap_eyes = 0;
@@ -76,9 +125,14 @@ static int no_equirect, no_equirect2, no_cylinder, no_cube;
 static int runtime_has_fb_passthrough, emulate_passthrough, alpha_blend_failed;
 static int controller_models;  // serve Frame controller models via XR_FB_render_model (render_model.c)
 // Per-game settings, all off by default (session_fixes.c, layer_emul_gl.c).
+static int sync_guard;       // xrSyncActions one at a time with xrPollEvent, paused briefly after focus returns
+static int profile_remap = 1; // Meta's newer controller profiles (rejected by the Frame) -> oculus/touch_controller
 static int layer_debug;      // diagnostics: layers, swapchains, session states, spaces, aim/grip, refresh rates
+static int input_diag;       // diagnostics: controller profiles, bindings, missing functions, failing input calls
 static int stable_local;     // keep every LOCAL space the app creates on the session-start origin
-static int focus_hold;       // hide brief focus dips once the session has been focused for a while
+static int focus_hold = 1;   // hide brief focus dips once the session has been focused for a while
+static float focus_hold_ms = 5000;  // longest focus dip focus_hold hides
+static float haptic_scale = 1.0f;   // vibration strength (0-1), all vibration types (xrApplyHapticFeedback)
 static float aim_pitch, aim_yaw, aim_forward;  // aim pose correction (degrees, degrees, metres)
 static float refresh_rate;   // requested display refresh rate (Hz), 0 = the app's choice
 static int equirect_emul;    // show 360 layers as cube faces (GLES)
@@ -98,8 +152,14 @@ static void read_settings(const char *path) {
     while (fgets(line, sizeof(line), f)) {
         if (sscanf(line, "scale=%f", &value) == 1 && value >= 0.5f && value <= 2.0f) scale = value;
         if (sscanf(line, "foveation_fix=%f", &value) == 1) foveation_fix = value != 0;
+        if (sscanf(line, "hide_space_warp=%f", &value) == 1) hide_space_warp = value != 0;
+        if (sscanf(line, "strip_color_bias=%f", &value) == 1) strip_color_bias = (int)value;
+        if (sscanf(line, "frame_balance=%f", &value) == 1) frame_balance = value != 0;
+        if (sscanf(line, "snapshot=%f", &value) == 1) snapshot = value > 0 ? (int)value : 0;
         if (sscanf(line, "controller_fix=%f", &value) == 1) controller_fix = value != 0;
         if (sscanf(line, "swapchain_fix=%f", &value) == 1) swapchain_fix = value != 0;
+        if (sscanf(line, "rect_clamp=%f", &value) == 1) rect_clamp = value != 0;
+        if (sscanf(line, "pose_consistency=%f", &value) == 1) pose_consistency = value != 0;
         if (sscanf(line, "layer_fix=%f", &value) == 1) layer_fix = value != 0;
         if (sscanf(line, "mutable_fix=%f", &value) == 1) mutable_fix = value != 0;
         if (sscanf(line, "swap_eyes=%f", &value) == 1) swap_eyes = value != 0;
@@ -115,8 +175,16 @@ static void read_settings(const char *path) {
         if (sscanf(line, "scene_depth=%f", &value) == 1 && value > 0.5f && value < 20.0f) scene_depth = value;
         if (sscanf(line, "controller_models=%f", &value) == 1) controller_models = value != 0;
         if (sscanf(line, "layer_debug=%f", &value) == 1) layer_debug = value != 0;
+        if (sscanf(line, "input_diag=%f", &value) == 1) input_diag = value != 0;
+        if (sscanf(line, "surface_emul=%f", &value) == 1) surface_emul = value != 0;
+        if (sscanf(line, "eye_debug=%f", &value) == 1) eye_debug = value != 0;
+        if (sscanf(line, "release_wait=%f", &value) == 1) release_wait = (int)value;
+        if (sscanf(line, "profile_remap=%f", &value) == 1) profile_remap = value != 0;
+        if (sscanf(line, "sync_guard=%f", &value) == 1) sync_guard = value != 0;
         if (sscanf(line, "stable_local=%f", &value) == 1) stable_local = value != 0;
         if (sscanf(line, "focus_hold=%f", &value) == 1) focus_hold = value != 0;
+        if (sscanf(line, "focus_hold_ms=%f", &value) == 1 && value >= 100 && value <= 5000) focus_hold_ms = value;
+        if (sscanf(line, "haptic_scale=%f", &value) == 1 && value >= 0 && value <= 1) haptic_scale = value;
         if (sscanf(line, "aim_pitch=%f", &value) == 1 && fabsf(value) <= 90) aim_pitch = value;
         if (sscanf(line, "aim_yaw=%f", &value) == 1 && fabsf(value) <= 90) aim_yaw = value;
         if (sscanf(line, "aim_forward=%f", &value) == 1 && fabsf(value) <= 0.5f) aim_forward = value;
@@ -163,6 +231,20 @@ static void initialize(void) {
     }
     const char *env = getenv("FRAMEBRIDGE_CONFIG");
     if (env && *env) read_settings(env);
+    if (snapshot && *process && !strchr(process, '/')) {
+        snprintf(snap_dir, sizeof(snap_dir), "/sdcard/Android/data/%s/files", process);
+        LOG("per-game: snapshot every %d s to %s/fb_snap_N.ppm", snapshot, snap_dir);
+    }
+    if (eye_debug && *process && !strchr(process, '/')) {
+        snprintf(path, sizeof(path), "/sdcard/Android/data/%s/files/framebridge.log", process);
+        log_file = fopen(path, "a");
+    }
+    if (input_diag) LOG("per-game: input_diag=1 (controller-input diagnostics)");
+    if (hide_space_warp) LOG("per-game: hide_space_warp=1 (XR_FB_space_warp hidden, space warp info removed)");
+    if (strip_color_bias) LOG("per-game: strip_color_bias=%d (layer color scale/bias removed)", strip_color_bias);
+    if (frame_balance) LOG("per-game: frame_balance=1 (an open frame is ended before the next one begins)");
+    if (eye_debug || release_wait) LOG("per-game: eye_debug=%d release_wait=%d log_file=%s", eye_debug, release_wait,
+                                       log_file ? path : "none");
     if (controller_models && *process && !strchr(process, '/')) render_model_init(process);
 
     LOG("scale=%.2f foveation_fix=%d controller_fix=%d swapchain_fix=%d layer_fix=%d mutable_fix=%d swap_eyes=%d passthrough_emul=%d respace_kick=%d flip_quads=%d controller_models=%d loader=%s",
@@ -193,7 +275,10 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
 
     int chained = 0, enabled = 0;
     for (const XrBaseInStructure *p = (const XrBaseInStructure *)info->next; p; p = p->next)
-        if (p->type == XR_TYPE_INSTANCE_CREATE_INFO_ANDROID_KHR) chained = 1;
+        if (p->type == XR_TYPE_INSTANCE_CREATE_INFO_ANDROID_KHR) {
+            chained = 1;
+            android_vm = ((const struct { XrStructureType type; const void *next; void *vm; void *activity; } *)p)->vm;
+        }
     for (uint32_t i = 0; i < info->enabledExtensionCount; ++i)
         if (!strcmp(info->enabledExtensionNames[i], "XR_KHR_android_create_instance")) enabled = 1;
 
@@ -215,7 +300,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
     }
 
     XrInstanceCreateInfo fixed = *info;
-    const char **names = calloc(info->enabledExtensionCount + 2, sizeof(*names));
+    const char **names = calloc(info->enabledExtensionCount + 3, sizeof(*names));
     if (!names) { free(available); return XR_ERROR_OUT_OF_MEMORY; }
     uint32_t kept = 0;
     for (uint32_t i = 0; i < info->enabledExtensionCount; ++i) {
@@ -223,6 +308,10 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
         int supported = !available;  // if we could not enumerate, pass everything through
         for (uint32_t j = 0; available && j < available_count && !supported; ++j)
             supported = !strcmp(available[j].extensionName, ext);
+        if (hide_space_warp && !strcmp(ext, "XR_FB_space_warp")) {
+            LOG("hide_space_warp: XR_FB_space_warp not enabled");
+            continue;
+        }
         if (supported) names[kept++] = ext;
         else if (scene_emul && is_scene_extension(ext)) {
             if (!emulate_scene) LOG("emulating Meta scene/spatial-entity extensions from the guardian bounds");
@@ -239,6 +328,19 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
         names[kept++] = "XR_KHR_android_create_instance";
         LOG("added %s", "XR_KHR_android_create_instance");
     }
+    {   // no graphics API extension at all: Meta's runtime still accepts a GLES session, the Frame's doesn't
+        // (Lambda1VR's TBXR enables only XR_EXT_local_floor). Add GLES, which every such app uses, if offered.
+        int graphics = 0, gles_offered = 0;
+        for (uint32_t i = 0; i < kept; ++i)
+            graphics |= !strcmp(names[i], "XR_KHR_opengl_es_enable") || !strcmp(names[i], "XR_KHR_vulkan_enable") ||
+                        !strcmp(names[i], "XR_KHR_vulkan_enable2");
+        for (uint32_t j = 0; available && j < available_count; ++j)
+            gles_offered |= !strcmp(available[j].extensionName, "XR_KHR_opengl_es_enable");
+        if (!graphics && gles_offered) {
+            names[kept++] = "XR_KHR_opengl_es_enable";
+            LOG("added XR_KHR_opengl_es_enable (the app enabled no graphics API extension)");
+        }
+    }
     if (refresh_rate > 0) {  // the refresh_rate setting needs XR_FB_display_refresh_rate even if the app doesn't use it
         int requested = 0, offered = 0;
         for (uint32_t i = 0; i < kept; ++i) requested |= !strcmp(names[i], "XR_FB_display_refresh_rate");
@@ -247,6 +349,14 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
     }
     fixed.enabledExtensionNames = names;
     fixed.enabledExtensionCount = kept;
+    {   // what the runtime gets (diagnostics: e.g. a graphics extension the app forgot)
+        char list[1024] = "";
+        for (uint32_t i = 0; i < kept; ++i) {
+            size_t len = strlen(list);
+            snprintf(list + len, sizeof list - len, "%s%s", i ? " " : "", names[i] + (strncmp(names[i], "XR_", 3) ? 0 : 3));
+        }
+        LOG("xrCreateInstance with %u extension(s): %s", kept, list);
+    }
     for (uint32_t j = 0; available && j < available_count; ++j)
         if (!strcmp(available[j].extensionName, "XR_FB_composition_layer_image_layout")) runtime_has_image_layout = 1;
     // Layer types are only valid if their extension ends up enabled; some apps submit them regardless.
@@ -259,10 +369,11 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
     }
     no_equirect = !has_equirect; no_equirect2 = !has_equirect2; no_cylinder = !has_cylinder; no_cube = !has_cube;
     free(available);
+    mx_audio_initialize();
     XrResult result = fn(&fixed, instance);
     free(names);
     LOG("xrCreateInstance result=%d", result);
-    if (XR_SUCCEEDED(result)) active_instance = *instance;
+    if (XR_SUCCEEDED(result)) { active_instance = *instance; mx_audio_initialize(); }
     return result;
 }
 
@@ -333,6 +444,45 @@ static void remember_swapchain(XrSwapchain handle) {
     pthread_mutex_unlock(&swapchains_lock);
 }
 
+// Swapchain sizes, to keep submitted image rects inside them (rect_clamp).
+#define MAX_SIZES 256
+static struct { XrSwapchain handle; uint32_t w, h; } sizes[MAX_SIZES];
+static pthread_mutex_t sizes_lock = PTHREAD_MUTEX_INITIALIZER;
+
+static void note_swapchain_size(XrSwapchain handle, uint32_t w, uint32_t h) {
+    pthread_mutex_lock(&sizes_lock);
+    int slot = -1;
+    for (int i = 0; i < MAX_SIZES; ++i) {
+        if (sizes[i].handle == handle) { slot = i; break; }
+        if (slot < 0 && sizes[i].handle == XR_NULL_HANDLE) slot = i;
+    }
+    if (slot >= 0) { sizes[slot].handle = handle; sizes[slot].w = w; sizes[slot].h = h; }
+    pthread_mutex_unlock(&sizes_lock);
+}
+
+static int swapchain_size(XrSwapchain handle, uint32_t *w, uint32_t *h) {
+    int found = 0;
+    pthread_mutex_lock(&sizes_lock);
+    for (int i = 0; i < MAX_SIZES && !found; ++i)
+        if (sizes[i].handle == handle && handle != XR_NULL_HANDLE) { *w = sizes[i].w; *h = sizes[i].h; found = 1; }
+    pthread_mutex_unlock(&sizes_lock);
+    return found;
+}
+
+// Clamp `r` to a w x h image; returns whether it changed.
+static int clamp_rect(XrRect2Di *r, uint32_t w, uint32_t h) {
+    XrRect2Di c = *r;
+    if (c.offset.x < 0) { c.extent.width += c.offset.x; c.offset.x = 0; }
+    if (c.offset.y < 0) { c.extent.height += c.offset.y; c.offset.y = 0; }
+    if ((uint32_t)c.offset.x >= w || (uint32_t)c.offset.y >= h) return 0;  // nothing sensible to keep: leave it
+    if ((int64_t)c.offset.x + c.extent.width > (int64_t)w) c.extent.width = (int32_t)(w - (uint32_t)c.offset.x);
+    if ((int64_t)c.offset.y + c.extent.height > (int64_t)h) c.extent.height = (int32_t)(h - (uint32_t)c.offset.y);
+    if (c.extent.width <= 0 || c.extent.height <= 0) return 0;
+    int changed = memcmp(&c, r, sizeof c) != 0;
+    *r = c;
+    return changed;
+}
+
 static void forget_swapchain(XrSwapchain handle) {
     pthread_mutex_lock(&swapchains_lock);
     for (size_t i = 0; i < swapchain_count; ++i)
@@ -374,6 +524,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
     if (equirect_emul && swapchain && emul_virtual_create(session, &fixed, swapchain)) {
         remember_swapchain(*swapchain);
         emul_on_create_swapchain(*swapchain, &fixed);
+        snap_on_create(*swapchain, &fixed);
         return XR_SUCCESS;
     }
     XrResult result = fn(session, &fixed, swapchain);
@@ -382,8 +533,10 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
         (unsigned long long)fixed.usageFlags, (unsigned long long)fixed.createFlags, result);
     if (XR_SUCCEEDED(result)) {
         remember_swapchain(*swapchain);
+        note_swapchain_size(*swapchain, fixed.width, fixed.height);
         flip_on_create_swapchain(*swapchain, &fixed);
         emul_on_create_swapchain(*swapchain, &fixed);
+        snap_on_create(*swapchain, &fixed);
         return result;
     }
     if (!swapchain_fix) return result;
@@ -404,8 +557,10 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
     }
     if (XR_SUCCEEDED(result)) {
         remember_swapchain(*swapchain);
+        note_swapchain_size(*swapchain, fixed.width, fixed.height);
         flip_on_create_swapchain(*swapchain, &fixed);
         emul_on_create_swapchain(*swapchain, &fixed);
+        snap_on_create(*swapchain, &fixed);
     }
     return result;
 }
@@ -413,9 +568,15 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
 XRAPI_ATTR XrResult XRAPI_CALL xrDestroySwapchain(XrSwapchain swapchain) {
     PFN_xrDestroySwapchain fn = (PFN_xrDestroySwapchain)lookup(active_instance, "xrDestroySwapchain");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (layer_debug) {
+        static int logged;
+        if (logged++ < 200) LOG("layer_debug: xrDestroySwapchain %p", (void *)swapchain);
+    }
     forget_swapchain(swapchain);
+    surf_on_destroy(swapchain);
     flip_on_destroy(swapchain);
     emul_on_destroy_swapchain(swapchain);
+    snap_on_destroy(swapchain);
     if (equirect_emul && emul_is_virtual(swapchain)) { emul_virtual_destroy(swapchain); return XR_SUCCESS; }
     return fn(swapchain);
 }
@@ -665,13 +826,47 @@ XRAPI_ATTR XrResult XRAPI_CALL xrDestroySpace(XrSpace space) {
     return fn ? fn(space) : XR_ERROR_FUNCTION_UNSUPPORTED;
 }
 
+#include "input_diag.c"
 #include "session_fixes.c"
 #include "layer_emul_gl.c"
+#include "snapshot_gl.c"
+#include "surface_swapchain.c"
+#include "eye_debug.c"
+
+// OpenXR requires xrGet*GraphicsRequirementsKHR before xrCreateSession; Meta's runtime doesn't enforce it, the Frame's
+// does (XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING, e.g. Lambda1VR's TBXR). Ask on the app's behalf, once, and retry.
+static int ask_graphics_requirements(XrInstance instance, const XrSessionCreateInfo *info) {
+    const XrBaseInStructure *binding = info ? (const XrBaseInStructure *)info->next : NULL;
+    for (; binding; binding = binding->next) {
+        const char *name = NULL;
+        XrStructureType type = 0;
+        if (binding->type == (XrStructureType)1000024001) {  // XR_TYPE_GRAPHICS_BINDING_OPENGL_ES_ANDROID_KHR
+            name = "xrGetOpenGLESGraphicsRequirementsKHR";
+            type = (XrStructureType)1000024003;               // XR_TYPE_GRAPHICS_REQUIREMENTS_OPENGL_ES_KHR
+        } else if (binding->type == (XrStructureType)1000025000) {  // XR_TYPE_GRAPHICS_BINDING_VULKAN_KHR
+            name = "xrGetVulkanGraphicsRequirementsKHR";
+            type = (XrStructureType)1000025002;               // XR_TYPE_GRAPHICS_REQUIREMENTS_VULKAN_KHR
+        }
+        if (!name) continue;
+        // XrGraphicsRequirementsOpenGLESKHR and ...VulkanKHR share this layout
+        struct { XrStructureType type; void *next; XrVersion min, max; } req = {type, NULL, 0, 0};
+        typedef XrResult (XRAPI_PTR *PFN_requirements)(XrInstance, XrSystemId, void *);
+        PFN_requirements get = (PFN_requirements)lookup(instance, name);
+        if (!get && type == (XrStructureType)1000025002)  // XR_KHR_vulkan_enable2 apps: same struct and call
+            get = (PFN_requirements)lookup(instance, "xrGetVulkanGraphicsRequirements2KHR");
+        XrResult r = get ? get(instance, info->systemId, &req) : XR_ERROR_FUNCTION_UNSUPPORTED;
+        LOG("xrCreateSession: the app skipped %s; asked for it (result=%d)", name, (int)r);
+        return XR_SUCCEEDED(r);
+    }
+    return 0;
+}
 
 XRAPI_ATTR XrResult XRAPI_CALL xrCreateSession(XrInstance instance, const XrSessionCreateInfo *info, XrSession *session) {
     PFN_xrCreateSession fn = (PFN_xrCreateSession)lookup(instance, "xrCreateSession");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
     XrResult result = fn(instance, info, session);
+    if (result == XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING && ask_graphics_requirements(instance, info))
+        result = fn(instance, info, session);
     if (XR_SUCCEEDED(result)) {
         flip_emul = flip_emul_setting;
         flip_on_create_session(info);
@@ -682,6 +877,63 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSession(XrInstance instance, const XrSess
     return result;
 }
 
+// Vibrations: logged (the first few, to see what games ask for) and scaled by haptic_scale. Plain vibrations, Meta's
+// amplitude envelopes and PCM buffers all pass here: games' own calls, OVRPort's VrApi bridge and the xrshim alike.
+static int haptics_logged;
+static XrResult apply_haptics(XrSession session, const XrHapticActionInfo *info, const XrHapticBaseHeader *feedback) {
+    PFN_xrApplyHapticFeedback fn = (PFN_xrApplyHapticFeedback)lookup(active_instance, "xrApplyHapticFeedback");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (!feedback) return fn(session, info, feedback);
+    if (feedback->type == XR_TYPE_HAPTIC_VIBRATION) {
+        XrHapticVibration v = *(const XrHapticVibration *)feedback;
+        if (haptics_logged++ < 8)
+            LOG("haptic: vibration amplitude=%.2f duration=%lld ns frequency=%.0f (scale %.2f)", v.amplitude,
+                (long long)v.duration, v.frequency, haptic_scale);
+        v.amplitude *= haptic_scale;
+        if (v.amplitude <= 0.001f) {
+            // OVRPlugin stops a vibration by sending amplitude 0 with its usual 2 s duration (Jurassic World, The Boys
+            // VR): on a Quest that stops the motor; OpenXR's stop is xrStopHapticFeedback, and without it the last
+            // buzz ran its full 2 s
+            PFN_xrStopHapticFeedback stop = (PFN_xrStopHapticFeedback)lookup(active_instance, "xrStopHapticFeedback");
+            if (stop) return stop(session, info);
+        }
+        return fn(session, info, (const XrHapticBaseHeader *)&v);
+    }
+    if (feedback->type == (XrStructureType)1000173001 || feedback->type == (XrStructureType)1000209001) {
+        // XR_TYPE_HAPTIC_AMPLITUDE_ENVELOPE_VIBRATION_FB / XR_TYPE_HAPTIC_PCM_VIBRATION_FB: a sample buffer
+        typedef struct { XrStructureType type; const void *next; XrDuration duration; uint32_t count; const float *s; } env_t;
+        typedef struct { XrStructureType type; const void *next; uint32_t count; const float *s; float rate; XrBool32 append;
+                         uint32_t *consumed; } pcm_t;
+        int envelope = feedback->type == (XrStructureType)1000173001;
+        uint32_t n = envelope ? ((const env_t *)feedback)->count : ((const pcm_t *)feedback)->count;
+        const float *in = envelope ? ((const env_t *)feedback)->s : ((const pcm_t *)feedback)->s;
+        if (haptics_logged++ < 8) {
+            float peak = 0;
+            for (uint32_t i = 0; in && i < n; ++i) peak = fmaxf(peak, in[i]);
+            LOG("haptic: %s %u samples peak=%.2f (scale %.2f)", envelope ? "envelope" : "pcm", n, peak, haptic_scale);
+        }
+        if (haptic_scale >= 0.999f || !in || !n || n > 1u << 20) return fn(session, info, feedback);
+        float *scaled = malloc(n * sizeof *scaled);
+        if (!scaled) return fn(session, info, feedback);
+        for (uint32_t i = 0; i < n; ++i) scaled[i] = in[i] * haptic_scale;
+        XrResult r;
+        if (envelope) { env_t e = *(const env_t *)feedback; e.s = scaled; r = fn(session, info, (const XrHapticBaseHeader *)&e); }
+        else { pcm_t c = *(const pcm_t *)feedback; c.s = scaled; r = fn(session, info, (const XrHapticBaseHeader *)&c); }
+        free(scaled);
+        return r;
+    }
+    return fn(session, info, feedback);
+}
+
+XRAPI_ATTR XrResult XRAPI_CALL xrApplyHapticFeedback(XrSession session, const XrHapticActionInfo *info,
+                                                    const XrHapticBaseHeader *feedback) {
+    XrResult result = apply_haptics(session, info, feedback);
+    if (input_diag && XR_FAILED(result))  // always hooked (haptic_scale), so input_diag reports failures here
+        diag_call_failed("xrApplyHapticFeedback", result,
+                         feedback && feedback->type != XR_TYPE_HAPTIC_VIBRATION ? "(not XrHapticVibration)" : NULL);
+    return result;
+}
+
 XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateSwapchainImages(XrSwapchain swapchain, uint32_t capacity, uint32_t *count,
         XrSwapchainImageBaseHeader *images) {
     PFN_xrEnumerateSwapchainImages fn = (PFN_xrEnumerateSwapchainImages)lookup(active_instance, "xrEnumerateSwapchainImages");
@@ -691,10 +943,28 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateSwapchainImages(XrSwapchain swapchain,
     if (XR_SUCCEEDED(result) && images && capacity && count) {
         flip_on_enumerate_images(swapchain, *count, images);
         emul_on_enumerate(swapchain, *count < capacity ? *count : capacity, images);
+        snap_on_enumerate(swapchain, *count < capacity ? *count : capacity, images);
     }
     return result;
 }
 
+// counted for layer_debug (an app that skips the wait or release keeps runtime resources alive)
+XRAPI_ATTR XrResult XRAPI_CALL xrWaitSwapchainImage(XrSwapchain swapchain, const XrSwapchainImageWaitInfo *info) {
+    PFN_xrWaitSwapchainImage fn = (PFN_xrWaitSwapchainImage)lookup(active_instance, "xrWaitSwapchainImage");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    XrResult result = fn(swapchain, info);
+    __atomic_add_fetch(&sc_waits, 1, __ATOMIC_RELAXED);
+    if (result != XR_SUCCESS) __atomic_add_fetch(&sc_wait_fails, 1, __ATOMIC_RELAXED);
+    return result;
+}
+
+XRAPI_ATTR XrResult XRAPI_CALL xrReleaseSwapchainImage(XrSwapchain swapchain, const XrSwapchainImageReleaseInfo *info) {
+    PFN_xrReleaseSwapchainImage fn = (PFN_xrReleaseSwapchainImage)lookup(active_instance, "xrReleaseSwapchainImage");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    __atomic_add_fetch(&sc_releases, 1, __ATOMIC_RELAXED);
+    return fn(swapchain, info);
+}
+
 XRAPI_ATTR XrResult XRAPI_CALL xrAcquireSwapchainImage(XrSwapchain swapchain, const XrSwapchainImageAcquireInfo *info,
         uint32_t *index) {
     PFN_xrAcquireSwapchainImage fn = (PFN_xrAcquireSwapchainImage)lookup(active_instance, "xrAcquireSwapchainImage");
@@ -706,7 +976,12 @@ XRAPI_ATTR XrResult XRAPI_CALL xrAcquireSwapchainImage(XrSwapchain swapchain, co
         return XR_SUCCESS;
     }
     XrResult result = fn(swapchain, info, index);
-    if (XR_SUCCEEDED(result) && index) { flip_on_acquire(swapchain, *index); emul_on_acquire(swapchain, *index); }
+    __atomic_add_fetch(&sc_acquires, 1, __ATOMIC_RELAXED);
+    if (XR_SUCCEEDED(result) && index) {
+        flip_on_acquire(swapchain, *index);
+        emul_on_acquire(swapchain, *index);
+        snap_on_acquire(swapchain, *index);
+    }
     return result;
 }
 
@@ -720,6 +995,7 @@ static XrSession focused_session = XR_NULL_HANDLE;
 static int kicks_pending = -1;  // -1: not yet armed
 
 XRAPI_ATTR XrResult XRAPI_CALL xrPollEvent(XrInstance instance, XrEventDataBuffer *event) {
+    mx_audio_initialize();
     PFN_xrPollEvent fn = (PFN_xrPollEvent)lookup(instance, "xrPollEvent");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
     if (emulate_scene && event) {
@@ -728,7 +1004,13 @@ XRAPI_ATTR XrResult XRAPI_CALL xrPollEvent(XrInstance instance, XrEventDataBuffe
         pthread_mutex_unlock(&scene_lock);
         if (got) return XR_SUCCESS;
     }
+    if (sync_guard) pthread_mutex_lock(&sync_lock);
     XrResult result = focus_hold && event ? focus_hold_poll(fn, instance, event) : fn(instance, event);
+    if (sync_guard) {
+        if (result == XR_SUCCESS && event && session_state_of(event) == XR_SESSION_STATE_FOCUSED)
+            sync_resume_at = monotonic_ns() + SYNC_GUARD_PAUSE_NS;
+        pthread_mutex_unlock(&sync_lock);
+    }
     if (result == XR_SUCCESS && event && (layer_debug || stable_local)) {
         if (event->type == XR_TYPE_EVENT_DATA_SESSION_STATE_CHANGED && layer_debug)
             LOG("layer_debug: session state %d at %.3f", ((const XrEventDataSessionStateChanged *)event)->state,
@@ -802,11 +1084,69 @@ XRAPI_ATTR XrResult XRAPI_CALL xrWaitFrame(XrSession session, const XrFrameWaitI
     return result;
 }
 
+// pose_consistency (GitHub #8, proposed by Klownicle for I Am Cat): the game asks xrLocateViews ~3 times per frame
+// for the same display time and got slightly different poses each time (tenths of a degree), so parts of its pipeline
+// rendered with different heads: judder. The first fully tracked answer for (session, space, view configuration,
+// display time) is kept and repeated; a new display time, another space or a failed/untracked answer is never cached.
+#define POSE_CACHE 8
+static struct {
+    XrSession session; XrSpace space; XrViewConfigurationType config; XrTime time;
+    XrViewStateFlags flags; uint32_t count; XrPosef pose[2]; XrFovf fov[2];
+} pose_cache[POSE_CACHE];
+static int pose_cache_next, pose_cache_hits;
+static pthread_mutex_t pose_cache_lock = PTHREAD_MUTEX_INITIALIZER;
+#define POSE_TRACKED (XR_VIEW_STATE_ORIENTATION_VALID_BIT | XR_VIEW_STATE_POSITION_VALID_BIT | \
+                      XR_VIEW_STATE_ORIENTATION_TRACKED_BIT | XR_VIEW_STATE_POSITION_TRACKED_BIT)
+
+static int pose_cache_lookup(XrSession session, const XrViewLocateInfo *info, XrViewState *state, uint32_t capacity,
+                             uint32_t *count, XrView *views) {
+    int hit = 0;
+    pthread_mutex_lock(&pose_cache_lock);
+    for (int i = 0; i < POSE_CACHE && !hit; ++i) {
+        if (pose_cache[i].session != session || pose_cache[i].space != info->space ||
+            pose_cache[i].config != info->viewConfigurationType || pose_cache[i].time != info->displayTime ||
+            !pose_cache[i].count || capacity < pose_cache[i].count)
+            continue;
+        state->viewStateFlags = pose_cache[i].flags;
+        *count = pose_cache[i].count;
+        for (uint32_t v = 0; v < pose_cache[i].count; ++v) {  // only the values: the caller's type/next stay
+            views[v].pose = pose_cache[i].pose[v];
+            views[v].fov = pose_cache[i].fov[v];
+        }
+        hit = 1;
+    }
+    if (hit && pose_cache_hits++ == 0) LOG("pose_consistency: repeated query answered with the frame's first poses");
+    pthread_mutex_unlock(&pose_cache_lock);
+    return hit;
+}
+
+static void pose_cache_store(XrSession session, const XrViewLocateInfo *info, const XrViewState *state,
+                             uint32_t count, const XrView *views) {
+    if (count == 0 || count > 2 || (state->viewStateFlags & POSE_TRACKED) != POSE_TRACKED) return;
+    pthread_mutex_lock(&pose_cache_lock);
+    int slot = pose_cache_next;
+    pose_cache_next = (pose_cache_next + 1) % POSE_CACHE;
+    pose_cache[slot].session = session;
+    pose_cache[slot].space = info->space;
+    pose_cache[slot].config = info->viewConfigurationType;
+    pose_cache[slot].time = info->displayTime;
+    pose_cache[slot].flags = state->viewStateFlags;
+    pose_cache[slot].count = count;
+    for (uint32_t v = 0; v < count; ++v) {
+        pose_cache[slot].pose[v] = views[v].pose;
+        pose_cache[slot].fov[v] = views[v].fov;
+    }
+    pthread_mutex_unlock(&pose_cache_lock);
+}
+
 XRAPI_ATTR XrResult XRAPI_CALL xrLocateViews(XrSession session, const XrViewLocateInfo *info, XrViewState *state,
         uint32_t capacity, uint32_t *count, XrView *views) {
     PFN_xrLocateViews fn = (PFN_xrLocateViews)lookup(active_instance, "xrLocateViews");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    int cacheable = pose_consistency && info && state && count && views && capacity > 0;
+    if (cacheable && pose_cache_lookup(session, info, state, capacity, count, views)) return XR_SUCCESS;
     XrResult result = fn(session, info, state, capacity, count, views);
+    if (cacheable && result == XR_SUCCESS) pose_cache_store(session, info, state, *count, views);
     if (equirect_emul && XR_SUCCEEDED(result) && info && count && views && state &&
         (state->viewStateFlags & XR_VIEW_STATE_ORIENTATION_VALID_BIT))
         emul_on_locate_views(info->space, info->displayTime, *count < capacity ? *count : capacity, views);
@@ -849,9 +1189,41 @@ XRAPI_ATTR XrResult XRAPI_CALL xrLocateViews(XrSession session, const XrViewLoca
     return result;
 }
 
+// xrBeginFrame: counted for layer_debug. A game that begins a new frame while the previous one is still open
+// (never ended) makes the runtime discard it; the Frame's runtime then never recycles that frame's GPU timing
+// command buffer (Vader Immortal: ~430 GPU mappings / 20 MB a second). frame_balance ends the open frame first,
+// with no layers, as the runtime expects.
+static XrTime last_begin_display_time;
+XRAPI_ATTR XrResult XRAPI_CALL xrBeginFrame(XrSession session, const XrFrameBeginInfo *info) {
+    PFN_xrBeginFrame fn = (PFN_xrBeginFrame)lookup(active_instance, "xrBeginFrame");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (frame_open && frame_balance) {
+        PFN_xrEndFrame end = (PFN_xrEndFrame)lookup(active_instance, "xrEndFrame");
+        XrFrameEndInfo empty = {XR_TYPE_FRAME_END_INFO, NULL, last_begin_display_time ? last_begin_display_time
+                                                                                        : last_predicted_time,
+                                XR_ENVIRONMENT_BLEND_MODE_OPAQUE, 0, NULL};
+        XrResult r = end ? end(session, &empty) : XR_ERROR_FUNCTION_UNSUPPORTED;
+        static int logged;
+        if (logged++ < 3) LOG("frame_balance: ended an open frame before xrBeginFrame (result %d)", r);
+        __atomic_add_fetch(&frame_balanced, 1, __ATOMIC_RELAXED);
+    }
+    XrResult result = fn(session, info);
+    __atomic_add_fetch(&frame_begins, 1, __ATOMIC_RELAXED);
+    if (result == XR_FRAME_DISCARDED) __atomic_add_fetch(&frame_discarded, 1, __ATOMIC_RELAXED);
+    if (XR_SUCCEEDED(result)) {
+        frame_open = 1;
+        last_begin_display_time = last_predicted_time;
+    }
+    return result;
+}
+
 XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInfo *info) {
     PFN_xrEndFrame fn = (PFN_xrEndFrame)lookup(active_instance, "xrEndFrame");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    frame_open = 0;
+    __atomic_add_fetch(&frame_ends, 1, __ATOMIC_RELAXED);
+    snap_end_frame(info);
+    if (eye_debug) eye_debug_end_frame(session, info);
     {   // frame pacing statistics every ~5 s: fps and submitted-vs-predicted display time
         static struct timespec start;
         static int frames;
@@ -867,6 +1239,24 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
         if (elapsed >= 5.0) {
             LOG("pacing: %.1f fps, displayTime vs predicted: avg %.2f ms, max %.2f ms", frames / elapsed,
                 drift_sum / (double)frames / 1e6, drift_max / 1e6);
+            if (layer_debug)
+                LOG("layer_debug: swapchain images: %d acquired, %d waited (%d not ok), %d released",
+                    __atomic_exchange_n(&sc_acquires, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&sc_waits, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&sc_wait_fails, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&sc_releases, 0, __ATOMIC_RELAXED));
+            if (layer_debug)
+                LOG("layer_debug: frames: %d xrBeginFrame (%d discarded), %d xrEndFrame, %d balanced",
+                    __atomic_exchange_n(&frame_begins, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&frame_discarded, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&frame_ends, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&frame_balanced, 0, __ATOMIC_RELAXED));
+            if (layer_debug)
+                LOG("layer_debug: input: %d xrSyncActions (%d ok, last %d), %d bool reads, %d pressed",
+                    __atomic_exchange_n(&input_syncs, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&input_sync_ok, 0, __ATOMIC_RELAXED), input_last_sync_result,
+                    __atomic_exchange_n(&input_bool_reads, 0, __ATOMIC_RELAXED),
+                    __atomic_exchange_n(&input_bool_true, 0, __ATOMIC_RELAXED));
             frames = 0; drift_sum = drift_max = 0;
         }
     }
@@ -951,6 +1341,13 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
                 continue;
             }
         }
+        if (layer && (layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD || layer->type == XR_TYPE_COMPOSITION_LAYER_CYLINDER_KHR) &&
+            !surf_prepare_layer(layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD
+                                    ? ((const XrCompositionLayerQuad *)layer)->subImage.swapchain
+                                    : ((const XrCompositionLayerCylinderKHR *)layer)->subImage.swapchain)) {
+            ++dropped;  // an emulated video surface without a frame yet
+            continue;
+        }
         if (!layer || (layer_fix && !layer_usable(layer))) { ++dropped; continue; }
         if (layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD) {
             const XrCompositionLayerQuad *flipped = flip_quad(session, (const XrCompositionLayerQuad *)layer, &quads[count]);
@@ -987,6 +1384,73 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
             if (!logged++) LOG("strip_depth: removed depth info from projection layer");
             ++swapped;
         }
+        {
+            // XR_KHR_composition_layer_color_scale_bias (1000034000) on the layer itself: logged when its values
+            // change (layer_debug); with strip_color_bias the runtime never gets it (Vader Immortal: the Frame's
+            // runtime allocates GPU memory for it every frame and never frees it)
+            const XrBaseInStructure *head = (const XrBaseInStructure *)layer->next;
+            const XrCompositionLayerColorScaleBiasKHR *cb = NULL;
+            for (const XrBaseInStructure *n = head; n; n = n->next)
+                if (n->type == XR_TYPE_COMPOSITION_LAYER_COLOR_SCALE_BIAS_KHR) cb = (const XrCompositionLayerColorScaleBiasKHR *)n;
+            if (cb && layer_debug) {
+                static float last[8] = {-1};
+                float now[8] = {cb->colorScale.r, cb->colorScale.g, cb->colorScale.b, cb->colorScale.a,
+                                cb->colorBias.r, cb->colorBias.g, cb->colorBias.b, cb->colorBias.a};
+                static int logged;
+                if (memcmp(now, last, sizeof(now)) && logged++ < 100) {
+                    LOG("layer_debug: layer type=%d color scale %.2f %.2f %.2f %.2f bias %.2f %.2f %.2f %.2f", layer->type,
+                        now[0], now[1], now[2], now[3], now[4], now[5], now[6], now[7]);
+                    memcpy(last, now, sizeof(now));
+                }
+            }
+            if (cb && strip_color_bias && (layer->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION ||
+                                           layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD)) {
+                const XrBaseInStructure *rest = head;  // skip leading color structs; one further down drops the chain
+                while (rest && rest->type == XR_TYPE_COMPOSITION_LAYER_COLOR_SCALE_BIAS_KHR) rest = rest->next;
+                for (const XrBaseInStructure *n = rest; n; n = n->next)
+                    if (n->type == XR_TYPE_COMPOSITION_LAYER_COLOR_SCALE_BIAS_KHR) rest = NULL;
+                if (strip_color_bias > 1) rest = NULL;  // 2: the layer's whole extension chain (diagnostics)
+                if (layer->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION) {
+                    if (layer != (const XrCompositionLayerBaseHeader *)&projections[count])
+                        projections[count] = *(const XrCompositionLayerProjection *)layer;
+                    projections[count].next = rest;
+                    layer = (const XrCompositionLayerBaseHeader *)&projections[count];
+                } else {
+                    if (layer != (const XrCompositionLayerBaseHeader *)&quads[count])
+                        quads[count] = *(const XrCompositionLayerQuad *)layer;
+                    quads[count].next = rest;
+                    layer = (const XrCompositionLayerBaseHeader *)&quads[count];
+                }
+                static int logged;
+                if (!logged++) LOG("strip_color_bias: removed the color scale/bias from a layer");
+                ++swapped;
+            }
+        }
+        if (hide_space_warp && layer->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
+            ((const XrCompositionLayerProjection *)layer)->viewCount == 2) {
+            // The game may still attach XrCompositionLayerSpaceWarpInfoFB (1000171000) to its views: OVRPort's
+            // dispatcher offers XR_FB_space_warp itself even when hidden here. Unlink it (keeping what follows when
+            // it heads the chain, else the whole chain) so the runtime never uses the motion vectors.
+            const XrCompositionLayerProjection *src = (const XrCompositionLayerProjection *)layer;
+            int found = 0;
+            for (uint32_t v = 0; v < 2; ++v)
+                for (const XrBaseInStructure *n = (const XrBaseInStructure *)src->views[v].next; n; n = n->next)
+                    found |= n->type == 1000171000;
+            if (found) {
+                if (layer != (const XrCompositionLayerBaseHeader *)&projections[count]) projections[count] = *src;
+                for (uint32_t v = 0; v < 2; ++v) {
+                    views[count][v] = src->views[v];
+                    const XrBaseInStructure *head = (const XrBaseInStructure *)src->views[v].next;
+                    if (head && head->type == 1000171000) views[count][v].next = head->next;
+                    else if (head) views[count][v].next = NULL;
+                }
+                projections[count].views = views[count];
+                layer = (const XrCompositionLayerBaseHeader *)&projections[count];
+                static int logged;
+                if (!logged++) LOG("hide_space_warp: removed space warp info from the eye images");
+                ++swapped;
+            }
+        }
         if (swap_eyes && layer->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
             ((const XrCompositionLayerProjection *)layer)->viewCount == 2) {
             // Show each eye the image the game rendered for it: keep poses/FOVs, swap sub-images.
@@ -1004,6 +1468,51 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
             layer = (const XrCompositionLayerBaseHeader *)&projections[count];
             ++swapped;
         }
+        if (rect_clamp) {
+            // Keep every image rect inside its swapchain: Unity/OVRPlugin can size the eye area a few pixels past
+            // the image on some Frames (PowerWash Simulator: rect 268+1656 on a 1920 wide swapchain) and SteamVR
+            // then rejects every frame with XR_ERROR_SWAPCHAIN_RECT_INVALID (-25) (GitHub #39).
+            uint32_t w, h;
+            if (layer->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
+                ((const XrCompositionLayerProjection *)layer)->viewCount <= 2) {
+                const XrCompositionLayerProjection *cur = (const XrCompositionLayerProjection *)layer;
+                int over = 0;
+                for (uint32_t v = 0; v < cur->viewCount; ++v) {
+                    XrRect2Di r = cur->views[v].subImage.imageRect;
+                    if (swapchain_size(cur->views[v].subImage.swapchain, &w, &h) && clamp_rect(&r, w, h)) over = 1;
+                }
+                if (over) {
+                    if (layer != (const XrCompositionLayerBaseHeader *)&projections[count]) projections[count] = *cur;
+                    if (projections[count].views != views[count])
+                        for (uint32_t v = 0; v < cur->viewCount; ++v) views[count][v] = cur->views[v];
+                    for (uint32_t v = 0; v < cur->viewCount; ++v)
+                        if (swapchain_size(views[count][v].subImage.swapchain, &w, &h) &&
+                            clamp_rect(&views[count][v].subImage.imageRect, w, h)) {
+                            static int logged;
+                            if (logged++ < 3)
+                                LOG("rect_clamp: view %u image rect clamped to %dx%d at %d,%d (swapchain %ux%u)", v,
+                                    views[count][v].subImage.imageRect.extent.width,
+                                    views[count][v].subImage.imageRect.extent.height,
+                                    views[count][v].subImage.imageRect.offset.x,
+                                    views[count][v].subImage.imageRect.offset.y, w, h);
+                        }
+                    projections[count].views = views[count];
+                    layer = (const XrCompositionLayerBaseHeader *)&projections[count];
+                    ++swapped;
+                }
+            } else if (layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD) {
+                const XrCompositionLayerQuad *q = (const XrCompositionLayerQuad *)layer;
+                XrRect2Di r = q->subImage.imageRect;
+                if (swapchain_size(q->subImage.swapchain, &w, &h) && clamp_rect(&r, w, h)) {
+                    if (layer != (const XrCompositionLayerBaseHeader *)&quads[count]) quads[count] = *q;
+                    quads[count].subImage.imageRect = r;
+                    layer = (const XrCompositionLayerBaseHeader *)&quads[count];
+                    ++swapped;
+                    static int logged;
+                    if (!logged++) LOG("rect_clamp: quad image rect clamped (swapchain %ux%u)", w, h);
+                }
+            }
+        }
         kept[count++] = layer;
     }
     XrFrameEndInfo fixed = *info;
@@ -1079,6 +1588,19 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetCurrentInteractionProfile(XrSession session,
         (PFN_xrGetCurrentInteractionProfile)lookup(active_instance, "xrGetCurrentInteractionProfile");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
     XrResult result = fn(session, user, state);
+    if (input_diag && XR_SUCCEEDED(result) && state) input_diag_current_profile(user, state->interactionProfile);
+    if (layer_debug && active_instance) {  // which device each hand has, as the runtime reports it
+        PFN_xrPathToString str = (PFN_xrPathToString)lookup(active_instance, "xrPathToString");
+        char who[XR_MAX_PATH_LENGTH] = "?", what[XR_MAX_PATH_LENGTH] = "(none)";
+        uint32_t n = 0;
+        if (str) {
+            str(active_instance, user, sizeof(who), &n, who);
+            if (XR_SUCCEEDED(result) && state && state->interactionProfile)
+                str(active_instance, state->interactionProfile, sizeof(what), &n, what);
+        }
+        static int logged;
+        if (logged++ < 40) LOG("layer_debug: interaction profile of %s: %s (result %d)", who, what, result);
+    }
     if (!controller_fix || XR_FAILED(result) || !state || !state->interactionProfile || !active_instance)
         return result;
     PFN_xrPathToString to_string = (PFN_xrPathToString)lookup(active_instance, "xrPathToString");
@@ -1098,7 +1620,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateInstanceExtensionProperties(const char
         XR_NULL_HANDLE, "xrEnumerateInstanceExtensionProperties");
     if (!fn) return XR_ERROR_INITIALIZATION_FAILED;
     if (!count) return XR_ERROR_VALIDATION_FAILURE;
-    if ((!foveation_fix && !passthrough_emul && !scene_emul && !controller_models) || layer)
+    if ((!foveation_fix && !hide_space_warp && !passthrough_emul && !scene_emul && !controller_models) || layer)
         return fn(layer, capacity, count, properties);
 
     uint32_t total = 0;
@@ -1115,6 +1637,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateInstanceExtensionProperties(const char
         if (!strcmp(all[i].extensionName, "XR_FB_passthrough")) runtime_has_fb_passthrough = 1;
         if (!strcmp(all[i].extensionName, XR_FB_RENDER_MODEL_EXTENSION_NAME)) runtime_has_render_model = 1;
         if (foveation_fix && strstr(all[i].extensionName, "foveation")) continue;
+        if (hide_space_warp && !strcmp(all[i].extensionName, "XR_FB_space_warp")) continue;
         if (properties && kept < capacity) properties[kept] = all[i];
         ++kept;
     }
@@ -1182,6 +1705,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
     if (!emulated && emulate_scene && !strcmp(name, "xrLocateSpacesKHR")) emulated = (PFN_xrVoidFunction)emu_locate_spaces_khr;
     if (emulated) { *function = emulated; return XR_SUCCESS; }
     HOOK(xrGetSystemProperties)
+    HOOK(xrApplyHapticFeedback)
     HOOK(xrCreateReferenceSpace)
     HOOK(xrLocateViews)
     HOOK(xrPollEvent)
@@ -1197,6 +1721,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
     HOOK(xrCreateSwapchain)
     HOOK(xrDestroySwapchain)
     HOOK(xrEndFrame)
+    HOOK(xrBeginFrame)
     HOOK(xrLocateHandJointsEXT)
     HOOK(xrGetCurrentInteractionProfile)
     HOOK(xrEnumerateInstanceExtensionProperties)
@@ -1211,12 +1736,28 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
     if (layer_debug || refresh_rate > 0) {
         HOOK_AS(xrRequestDisplayRefreshRateFB, hook_request_refresh_rate)
     }
-    if (layer_debug || aim_correction_on()) {
+    if (surface_emul) HOOK_AS(xrCreateSwapchainAndroidSurfaceKHR, hook_xrCreateSwapchainAndroidSurfaceKHR)
+    if (eye_debug || release_wait) HOOK_AS(xrReleaseSwapchainImage, eye_hook_xrReleaseSwapchainImage)
+    if (layer_debug) {  // counters only; every other wait/release hook above takes precedence
+        HOOK(xrWaitSwapchainImage)
+        HOOK(xrReleaseSwapchainImage)
+    }
+    if (sync_guard || layer_debug || input_diag) HOOK_AS(xrSyncActions, hook_xrSyncActions)
+    if (layer_debug) HOOK_AS(xrGetActionStateBoolean, hook_xrGetActionStateBoolean)
+    if (layer_debug || aim_correction_on() || profile_remap || input_diag)
         HOOK_AS(xrSuggestInteractionProfileBindings, hook_xrSuggestInteractionProfileBindings)
+    if (layer_debug || aim_correction_on()) {
         HOOK_AS(xrCreateActionSpace, hook_xrCreateActionSpace)
     }
 #undef HOOK_AS
 #undef HOOK
+    if (input_diag) {  // logs only: wraps a few input/haptics/perf calls, notes lookups the runtime can't answer
+        PFN_xrVoidFunction diag = input_diag_hook(name);
+        XrResult result = next_gipa(instance, name, function);
+        input_diag_lookup(instance, name, result, *function);
+        if (diag && XR_SUCCEEDED(result) && *function) *function = diag;
+        return result;
+    }
     return next_gipa(instance, name, function);
 }