Showcase: placeholders in the setup command; Monitor charts grow live on film

- The install tutorial (app screen and card) shows curl -fsS <your-PC-address>:8765/<one-time-code> | bash, so
  nobody takes the example for their own command; the card says FramePort fills them in.
- Videos: opening the Monitor tab no longer replays two minutes of samples (its charts raced to catch up); the
  charts start there and grow live, as in the app. The pretend frame rate holds ~72 fps with a short, shallow dip
  now and then (it sat at 55-61 fps for seconds). Both videos re-recorded.

.github/workflows/build.yml

@@ -96,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)
@@ -140,6 +159,12 @@ jobs:
           merge-multiple: true
       - name: Wheel (CLI install via uv tool / pipx / pip, and its self-update)
         run: uv build --wheel -o out && ls out
+      - name: Videos (docs/media, rendered by the showcase workflow; frameport-<name>.mp4 → FramePort-<name>.mp4)
+        run: |
+          for f in docs/media/frameport-*.mp4; do
+            [ -f "$f" ] || continue
+            n=$(basename "$f" .mp4); cp "$f" "out/FramePort-${n#frameport-}.mp4"
+          done
       - name: Checksums
         run: cd out && sha256sum * > SHA256SUMS.txt && cat SHA256SUMS.txt
       - name: Publish release

.github/workflows/showcase.yml

@@ -0,0 +1,107 @@
+name: showcase
+# Docs screenshots and the videos (the demo tour, the install tutorial, …), rendered from the demo library
+# (docs/showcase/, scripts/showcase/; see docs/SHOWCASE.md). Opens or updates one pull request (branch
+# showcase/update) when a picture really changed; the renders are also kept as a workflow artifact either way.
+on:
+  workflow_dispatch:
+    inputs:
+      videos:
+        description: "Videos to record too: names from docs/showcase/videos (e.g. tour install), all, or empty"
+        type: string
+        default: ""
+  push:
+    branches: [main]
+    paths:
+      - "src/frameport/ui/**"
+      - "src/frameport/locales/**"
+      - "docs/showcase/**"
+      - "scripts/showcase/**"
+
+concurrency:
+  group: showcase-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  render:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 60
+    env:
+      PYTHONUTF8: "1"
+      PYTHONIOENCODING: utf-8
+      TZ: UTC
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # the push's changed files decide whether the video is recorded again
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: ffmpeg and fonts
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg fonts-roboto fonts-noto-color-emoji
+      - run: uv sync --extra dev --python 3.12  # the Python the renders are made with locally
+      - name: Chromium for Playwright
+        run: uv run playwright install --with-deps chromium
+      - name: Store art cache (fetched once from the stores the app uses)
+        uses: actions/cache@v6.1.0
+        with:
+          path: ~/.cache/frameport-showcase
+          key: showcase-art-${{ hashFiles('docs/showcase/demo-library.yaml') }}
+          restore-keys: showcase-art-
+
+      - name: Docs screenshots
+        run: uv run python scripts/showcase/render_docs.py --keep showcase-out/screenshots
+
+      - name: Videos
+        # a push records the videos whose storyboard (docs/showcase/videos/<name>.yaml) changed, or all of them when
+        # the recorder changed (UI tweaks alone don't re-record ~10 MB files); Run workflow records what it's asked
+        env:
+          INPUT_VIDEOS: ${{ inputs.videos }}
+          BEFORE: ${{ github.event.before }}
+        run: |
+          if [ "$GITHUB_EVENT_NAME" = workflow_dispatch ]; then
+            read -ra names <<< "$INPUT_VIDEOS"
+            if [ ${#names[@]} -eq 0 ]; then echo "no videos asked for"; exit 0; fi
+            [ "${names[0]}" = all ] && names=()
+            uv run python scripts/showcase/record_video.py "${names[@]}" --work showcase-out/videos
+          else
+            uv run python scripts/showcase/record_video.py --changed-since "$BEFORE" --work showcase-out/videos
+          fi
+
+      - name: Keep the renders
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: showcase
+          path: |
+            showcase-out/screenshots
+            showcase-out/videos/*/video.json
+            docs/media
+            docs/images/tour-teaser.webp
+          if-no-files-found: ignore
+          retention-days: 14
+
+      - name: What changed
+        id: diff
+        run: |
+          git status --short -- docs/images docs/media
+          if [ -n "$(git status --porcelain -- docs/images docs/media)" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"; fi
+      - name: Pull request
+        if: steps.diff.outputs.changed == 'true' && github.ref == 'refs/heads/main'
+        uses: peter-evans/create-pull-request@v8.1.1
+        with:
+          branch: showcase/update
+          delete-branch: true
+          add-paths: |
+            docs/images/*
+            docs/media/*
+          commit-message: "Docs: update screenshots and videos"
+          title: "Update docs screenshots and videos"
+          body: |
+            Rendered by the `showcase` workflow from the demo library (docs/showcase/demo-library.yaml) with a
+            pretend Frame: only pictures that visibly changed are included. Look them over before merging (the
+            run's `showcase` artifact has every render).
+
+            Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

CLAUDE.md

@@ -10,8 +10,20 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
 ## Layout
 - `src/frameport/` — Python package. `pipeline.py` is the API the CLI (`cli.py`) and GUI (`ui/`, Flet 1.0) share.
   - `ui/` — `app.py` shell (sidebar with Frame connection + activity cards, routing, actions, 30 s connection poll),
-    `theme.py` (dark design tokens; change colours/spacing only there), `components.py` (pill, card, callout,
-    status_row, art_fill, confirm, `update()` = safe update: in Flet 1.0 reading `.page` of an unmounted control
+    `theme.py` (design tokens; change colours/spacing only there. Dark-only colour themes (owner: no light mode):
+    built-ins `portal` (default), `portal_oled` (true black) and `original` (the old violet; alias `classic`). Portal =
+    the logo's dichotomy: orange ACCENT = main action + selection, blue SECONDARY = secondary (outlined) buttons,
+    progress, switch tracks, PC; `dual` themes add the blue→orange sidebar edge, two-colour wordmark (`C.wordmark`) and
+    selected-tab fade (`C.portal_gradient`). Installable theme files `<data>/themes/*.json` (docs/THEMES.md: name,
+    base, dual, any subset of `T.TOKENS`; refused if light/unreadable, `T.ThemeError`), Settings → Appearance: cards
+    switch live via `app.restyle()` (rebuilds the shell, drops cached views; setting `ui.theme`), "Install theme
+    file…", "Copy this theme as a file", bin icon removes. Read tokens as `T.NAME` when building — never as a default argument or module-level constant (they
+    keep the import-time theme; module maps refill through `T.on_change`, `tests/test_theme.py` checks defaults)),
+    `glyphs.py` + `icons/` (the logo `logo.svg`/`logo-solid.svg` = a monitor that comes out of a tilted portal as the
+    Frame, and 24 px line glyphs `fp:frame|port|patch|container|test|pc|sync|live|shot|keys|recipe|link`, copied into
+    the assets dir and shown as tinted `ft.Image`s: pass `G.FRAME` … wherever an icon goes, `C.as_icon` / the button
+    helpers handle both kinds; `src/assets/icon.png` = the bundles' app icon), `components.py` (pill, card, callout,
+    checklist, 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; files: the Frame's file manager (persistent
@@ -28,13 +40,24 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
     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) → ffmpeg/x264 + AAC (qualities scale down only; "full" = SteamVR's size) →
-    fragmented MP4 on an SSH exec channel's stdout (the script stops ffmpeg on stdin EOF) → relay on 127.0.0.1 (keeps
-    init + fragments since the last keyframe of the *video* track for late viewers) → player page
+    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); settings; welcome; activity panel). Files, Screenshots and the Library share right-click menus
+    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).
@@ -42,6 +65,14 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
     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.
+    Live Frame data comes from one app-owned `app.monitor_hub` (`frame/monitor_hub.py`): subscribers name modules +
+    interval, the hub runs one agent `_monitor` stream (union of modules, fastest interval; per-module collection
+    needs agent v65), reconnects after a lost stream and stops it when nobody subscribes; `_poll` retries an "error".
+    Subscribers: "monitor" (the Monitor tab, everything, only while shown) and "card" = the sidebar's live Frame card
+    (`ui/frame_card.py` helpers: battery ring, "now playing" row with fps + 2-min sparkline → click opens Monitor;
+    games + battery every 5 s, paused while a job's stage is "Upload…", only while connected and setting
+    `ui.live_frame_card` (Settings → Appearance, default on) is on; else the battery comes from the 30 s poll).
+    ui_smoke injects `FakeMonitorSession` as the hub's `session_factory`.
     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
@@ -50,16 +81,45 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
     **Never recreate clickable controls on progress ticks** (sidebar, activity tiles): update their properties —
     replacing them 5×/s swallowed clicks (couldn't leave the Library during an upload).
     Labelled switches: `C.switch(label, …)` (Material's default label colour is dark on our dark theme).
+    Cover cards (Library grid + shelf): `library.card_hover`/`hover_motion` (lift, art zoom inside the clipped frame,
+    radial `scrim`, accent-tinted shadow) and `C.CoverButton` (frosted round button, accent under the pointer; Play =
+    blue then orange ring ripple + "Starting on Frame…" pill for STARTING_S; its `.status` layer must sit *below*
+    the button in the Stack, else it takes the clicks); the game page's Play turns into "Starting on …" with a spinner
+    (`GameView._starting`). Reduce motion: no lift/zoom/rings. Filled buttons use a glyph's `-solid` variant
+    (`glyphs.solid`, e.g. `frame-solid.svg`: the outline glyph faded into the orange).
+    Empty states (`C.empty_state(..., features=[(icon, heading, sentence)])`): with features the portal is bigger, a
+    soft portal light (`C.portal_glow`) fills the screen and `C.feature_row` says what the screen will show (the
+    not-connected Files/Screenshots/Live/Type/Monitor tabs and the empty Library); the idle Live view is a framed
+    "screen" with its own Start button + `live_features()`, Type on Frame shows `keyboard_tips()` under the box.
+    Setup checklists (Frame → Ready to play, Settings → Tools / This PC) = `C.checklist([C.Check(ok, title, detail,
+    help, fix=(label, icon, handler), extra=control)])`: ok True/False/"warn"/None (= spinner); the fix button shows
+    inline only while an item isn't ready — wire existing actions only. Motion: `app.body` holds an
+    `ft.AnimatedSwitcher` (`app._show_view`): a new route gets a new wrapper (150 ms fade), a same-route redraw swaps
+    the wrapper's content (no animation; persistent views just remount); the wordmark's portal (`wordmark().data`)
+    pulses once when frame_state turns "connected"; both off with setting `ui.reduce_motion` (Settings → Appearance
+    "Reduce motion", `app.reduce_motion`). Settings has a fixed index column (`settings.SECTIONS` order, Appearance
+    first, Remove FramePort last): entries scroll the section column via `scroll_to(scroll_key=…)` (sections wrapped
+    in Containers with `ft.ScrollKey`), the header stays; `app.settings_view.show_section(key)` (ui_smoke
+    `settings-index`).
     Help hints: wording for non-obvious terms lives in `ui/help.py` (`HELP`); show it with `C.help_icon(key)` or the
-    `help=` argument of `section`/`status_row`/`kv`, tooltips via `C.tip()` (wraps). Game actions for the Library
-    right-click menu (one `ft.ContextMenu` around the grid, filled on right-click) and the game page's "…" menu come
-    from `app.game_actions()`. Picking art (`sources.apply_choice`) downloads into a staging dir and keeps the old
+    `help=` argument of `section`/`kv` (`C.Check` help key), tooltips via `C.tip()` (wraps). Game actions for the Library
+    right-click menu (one `ft.ContextMenu` around the grid, filled on right-click; short: `menus.quick_menu`, key actions
+    + "More actions…" = the game page with its full "…" menu opened from code, `app.open_game_menu`) and the game
+    page's "…" menu (`menus.menu_sections` quick=False, sectioned) come from `app.game_actions()`. Picking art (`sources.apply_choice`) downloads into a staging dir and keeps the old
     art if nothing came back; "Update Steam art on Frame" re-sends the art set to the game's anchor (agent ≥ 12).
     Patch descriptions/reasons describe the general case, naming games only as "e.g. …".
   - Installs: queued/cancelled/failed ones are remembered (library setting `ui.installs`) → Library "Resume" bar;
     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).
@@ -111,11 +171,20 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
     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>`): GUI = Add games → "Add a Linux app (arm64)…" /
+  - 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
@@ -131,6 +200,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).
@@ -165,9 +238,15 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
     signed, `ready.json`); `apply()` writes + starts detached `apply.ps1`/`apply.sh` (wait for pid → Windows: copy over,
     replaced files kept in `updates/<ver>/previous` because the zip has no top folder; macOS/Linux: mv to `.old` + swap,
     rollback, `xattr -dr` quarantine → relaunch; `<data>/logs/update.log`). `ui/updater.py`: background check (10 s,
-    then 6 h), sidebar card (hidden control, toggled), Library bar (`library_bar`), notes dialog (`ft.Markdown`), job
+    then 6 h), sidebar card (hidden control, toggled), Library bar (`library_bar`), changelog dialog, job
     `app-update` that restarts only when no other job is active, `apply_pending_at_start()` in `main()` for
-    "Install updates automatically"; Settings → Updates. CLI: `--version`, `frameport update [--check (exit 10)]
+    "Install updates automatically"; Settings → Updates. Changelog: `updates.fetch_changelog` (releases list,
+    `app-releases.json`, same 6 h cache, offline → cached / []) → `ChangelogEntry` (`whats_new()` keeps only the tag
+    message's "What's new" part: CI's intro, update hint and release-footer.md stripped); `between`/`changelog_for`
+    (installed < v ≤ offered, dev entry only when on/choosing dev, skipped versions included), `recent_history`;
+    the update/dev dialogs show one collapsible section per version (`_changes_column`, newest open); after an update
+    `pending_news` (setting `update.last_seen_version`; first start only records it; offline → retried next start)
+    → Library "was updated" bar → "See what's new…"; Settings → Updates "What's new…" = recent history. CLI: `--version`, `frameport update [--check (exit 10)]
     [--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.
@@ -201,11 +280,19 @@ 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> --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
-  patch list). Check every PNG for paths, IPs, user names and repack/scene names before committing.
+- Docs screenshots + videos (docs/SHOWCASE.md): never by hand. `uv run python scripts/showcase/render_docs.py`
+  renders `docs/showcase/shots.yaml` into `docs/images/` (every shot twice, kept when both agree; only visibly changed
+  files are rewritten; `--check` for CI) and `scripts/showcase/record_video.py [names] [--draft]` records the
+  storyboards `docs/showcase/videos/<name>.yaml` (tour = FramePort in use + README teaser; install = the install
+  tutorial: instruction cards for the download / the command on the Frame, the rest filmed from a first start) into
+  `docs/media/frameport-<name>.mp4`. Both build the demo library first (`demo_home.py`, profile `demo` or `fresh`:
+  catalog games from `demo-library.yaml` + `demo-analyses.json`, art/details cached in ~/.cache/frameport-showcase, a
+  pretend Frame from `showcase-frame.json`) in a temp FRAMEPORT_HOME: no personal data, refuses the real data dir
+  and placeholder art; discovery is off and the setup command shows placeholders for the address and code. Steps find elements
+  by name through Flutter's semantics tree (`scripts/showcase/web.py`: text, tooltip; the innermost match wins) —
+  give new icon-only controls a tooltip. The `showcase` workflow renders on UI pushes to main (+ the videos whose
+  storyboard changed, or the ones named on dispatch) and opens PR `showcase/update`; releases attach every video as
+  `FramePort-<name>.mp4`. `scripts/scrub_library.py` (the owner's own library) is only for private screenshots now.
   README rules (owner): states the project is a proof of concept, provides no piracy tools, credits the wrapped
   projects (most functionality is theirs); neutral technical wording; no Quest2Frame mentions anywhere.
 - GUI smoke test: `uv pip install flet-web playwright && playwright install chromium`, then
@@ -271,7 +358,10 @@ The Frame runs firewalld (22 and 32000 open). PC side: the setup server needs in
 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").
+scan redraw ran never closed: "dropped a patch for unknown control"); it also makes property writes (Flet's
+`Prop.__set__`) take the same `app.FLET_LOCK`: a property set on a background thread while the loop packed a patch
+changed the control's `_values` mid-iteration ("dictionary changed size during iteration", a sidebar click's page
+change died while the live Frame card took a sample). Anything that serves the app (ui_smoke, showcase) calls it too.
 **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
@@ -413,7 +503,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
@@ -505,7 +595,7 @@ recipe keeps it on). I Am Cat works with issues (judder; scale 0.8 no help). Rob
 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
+`library.REFRESH_ON_UPDATE`). Analysis fields added later: **bump `analysis/detect.ANALYSIS_VERSION`** (stored as `analysis.extra.analysis_version`); older entries whose APK is still there are analysed again at the GUI's start (background thread, not a job: ~8 s per 900 MB APK) and before a build (`pipeline.refresh_analyses`, GitHub #104); only `analysis`/`suggested` change, user recipes stay; an unreadable APK gets `analysis_failed` = the version (not retried until the next bump). 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
@@ -524,7 +614,7 @@ picker at all: a FramePort fix would be an injected picker activity. Generated c
 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 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.
+**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).
@@ -535,6 +625,75 @@ Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
 **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.
 
@@ -544,6 +703,40 @@ Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
 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`)
@@ -557,6 +750,7 @@ Installed apps find the release themselves (self-update), so the notes are what
   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
@@ -572,6 +766,11 @@ Installed apps find the release themselves (self-update), so the notes are what
   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.

README.md

@@ -9,7 +9,10 @@
 
 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)
+[![FramePort: library, one-click install, play, monitor](docs/images/tour-teaser.webp)](docs/media/frameport-tour.mp4)
+
+▶ [Watch the full tour](docs/media/frameport-tour.mp4) · New to FramePort? [Watch the install tutorial](docs/media/frameport-install.mp4)
+(about 90 seconds each, MP4; also attached to every release)
 
 > **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))
@@ -18,6 +21,8 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V
 
 ## Features
 
+![Library](docs/images/library.png)
+
 - **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.
@@ -28,11 +33,15 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V
   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 arm64 Linux apps (AppImage, a folder, or a zip/tar archive) on the Frame with a Steam
-  shortcut; they run natively on SteamOS.
+- **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.
 
 ## Quick start
@@ -59,9 +68,9 @@ with OBB files): [docs/FAQ.md](docs/FAQ.md).
 ## Type on Frame
 
 Typing in VR is painful, so FramePort turns your computer's keyboard into a keyboard for the Frame. Open **Type on
-Frame** (keyboard icon on the sidebar's Frame card, the Steam Frame page, or a game's menu), select a text field in
-the headset and type: searches, logins, chat, in any app, in Steam or on the desktop. Paste longer text to type it in
-one go. Nothing to install: FramePort adds a virtual keyboard on the Frame while the window is open, without root.
+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.
 
 ![Type on Frame](docs/images/type-on-frame.png)
 
@@ -87,6 +96,17 @@ videos muted). Pick 360p to 1080p, or the headset view's full size. The picture
 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
@@ -94,7 +114,7 @@ will attempt to guess key patches. If you find a new config that works for an ap
 
 **[List of tested games](docs/GAMES.md)**
 
-**Tested something? Share it.** In FramePort open the game → **…** → **Share working config…** (it fills in the
+**Tested something? Share it.** In FramePort open the game → **…** → **Share working recipe…** (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.
 

artifacts/SHA256SUMS

@@ -1,15 +1,17 @@
-48a3ecad77ec0f3215b29070e994590eb9579e04d3c88a47f37f306f9aeb01d9  ./arm64-v8a/libfp_langpack.so
-a5b03bb7ae5d953d7ded2bf117b0a19c57fae604f16f54310847f8e89593dde6  ./arm64-v8a/libfp_ovrp.so
-b5949e9e90e4c51e2733b9f6cd3c857a447552ac7291aec340407c27b034b600  ./arm64-v8a/libfp_vk.so
+e7554c6343ee2989b0a273ee6230e65c25bfe6499eefd00de19f5f0fee58754f  ./arm64-v8a/libfp_langpack.so
+321da502e0f8f46f0880aad39fe6b84bdef88f925164568814cf704a1b31a577  ./arm64-v8a/libfp_ovrp.so
+40defdaddcda53bd2649eb48076fae1622bfc2bfc88e9e03c94fc8b45af2a4f2  ./arm64-v8a/libfp_ovrtrace.so
+7522a7cfb236e48d3442d418c4820cd37760a9627c6bdef80fb0df82df5fd826  ./arm64-v8a/libfp_vk.so
 383054f8b3b41dde76d062c71856cd3163655e50009c08454bc1793f393ead65  ./arm64-v8a/libfpg.so
-8e00552d1ab90f82749db3caad4f773351fa8a28edcc5ea5cbd1b31c434ff32a  ./arm64-v8a/libframe_xrshim.so
-3dfcb0f2bec47857bcecc7261c58e076d872d4649718c40850f29e10c75477dd  ./arm64-v8a/libglshim.so
-0780f29b4844bcf5070929d8118cfcc2e7da2f16dd0dbfe1eaf12be7f5567401  ./arm64-v8a/libopenxr_loader_generic.so
+8a8f6b1da8952cb3933a5b53558424a5fc56043b2527a16bb6dd62a00d2de01a  ./arm64-v8a/libframe_xrshim.so
+fc559dbe0b87eecc3641256837293260cefb7c2ce7b21d808d10edd2a2dba9fc  ./arm64-v8a/libglshim.so
+cc5b493cadefe76ad13fd096d3f8494a140ba593e0e1692db12d284bc548c1cf  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
-32525cd0a9ee3d9993d8871cd6905bdcf22cde4f4ba28f5db6434ce7d6554758  ./arm64-v8a/libvrapi.so
-9c82f4ff57395e220329a22d0f0f47ce88b77132bed4dfb7b57809077fd0d6c4  ./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

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.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.FourPlayersStudio.Retronika.yaml

@@ -0,0 +1,21 @@
+package: com.FourPlayersStudio.Retronika
+title: Retronika
+status: works
+tested_version: 3.2.601
+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: 290bfda3969547d5f1ff621ab5a8be9dd322fc9eee6b243c863576d4ff5b4b81
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261006.6173745'
+  agent: 59
+  issue: 97
+source_hint: Retronika

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.JustAddWater.SniperEliteVR.yaml

@@ -4,14 +4,25 @@ tested_version: '1.03'
 source_hint: Sniper Elite VR
 engine: Unity
 xr: VrApi
-status: unsupported
-notes: 'GPU hang (zink: DEVICE LOST) even with MSAA off.'
-details: Legacy VrApi via OVRPlugin.
+status: works
+notes: Plays with controllers that follow the hands (owner's headset test, Quest 1 build 35713).
+details: 'Unity 2019.4 on its built-in Oculus VR (no Oculus XR Plugin). Its legacy frame loop never waited for frames
+  (GPU hang, zink: DEVICE LOST) and Unity reported only Go controllers: frame.unity_oculus_check. Its frame wait then
+  deadlocked at the Init scene (Unity skipped beginning a frame) and the physics-step pose update located the
+  controllers in the past (hands lagged): both fixed in that patch (revision 5), switched on for this game by ovrp_begin_gate and ovrp_hold_physics. Grabbing an object in the tutorial
+  vibrates the controller; OVRPort''s envelope conversion then allocated ~1 GB/s until the memory cap ended the game:
+  haptic_fix. The Quest 1 build has no arraysources_assets.hd, which the game loads on the Frame (it detects a Quest
+  2) and then skips the .sd bundle: textures are missing unless the .sd file is also present under the .hd name in the
+  game''s obb folder.'
 frame:
 - frame.unity_no_msaa
+- frame.unity_oculus_check
+adapter:
+  haptic_fix: 1
+  ovrp_begin_gate: 1
+  ovrp_hold_physics: 1
 pcvr_alternative: Sniper Elite VR (Steam PC VR). Winter Warrior (Quest) works on the Frame.
 verified:
-  date: '2026-09-28'
-  overport_cli: 1.2.3
-  overport_runtime: 3.4.3-23204ea
-  known_good_sha256: e80883eb6945e267a375edf0ffd789268686440819add9d4dee9fdbdf466cbe4
+  date: '2026-10-07'
+updated: '2026-10-07'
+min_app: 0.12.1

catalog/games/com.NewFolderGames.IAmCat.yaml

@@ -1,13 +1,14 @@
 package: com.NewFolderGames.IAmCat
 title: I Am Cat
-status: issues
-notes: The view vibrates slightly, even when holding still.
+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, so the view judders; scale 0.8 didn't change it. Possible next steps are fixing the
-  multiview path instead or the game's fixed timestep.
+  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
@@ -16,8 +17,11 @@ frame:
 - frame.unity_multipass
 device:
 - device.text_input_window
+adapter:
+  pose_consistency: 1
 verified:
-  date: '2026-10-03'
+  date: '2026-10-05'
   issue: 8
-updated: '2026-10-04'
+updated: '2026-10-05'
+min_app: 0.11.0
 source_hint: I Am Cat

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

@@ -1,15 +1,25 @@
 package: com.StressLevelZero.BONELAB
 title: BONELAB
-status: unsupported
-notes: Crashes while starting its graphics (Vulkan); no fix yet.
-details: SIGSEGV in vkCreateInstance, called from the game's own Vulkan hooks (libSLZQuestNative.so) into code that no
-  longer exists, right after OVRPlugin's pre-initialization creates and destroys an OpenXR instance. Keeping the
-  runtime (vrclient.so) and Steam's Fossilize layer loaded didn't help, so the stale pointer is to memory freed with
-  that first instance.
+status: works
+notes: Builds 1.2068 and 1.2974 play (owner's headset tests). One recipe serves both builds - 1.2068 needs frame.unity_user_presence (head tracking and controls); 1.2974 also needs
+  frame.slz_vulkan_hooks (72 fps after about 35 s of shader prewarming), which changes nothing on 1.2068.
+details: Both builds - 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 only - it adds Stress
+  Level Zero's graphics plugin (libSLZQuestNative.so), which hooks Unity's Vulkan start-up (vkCreateInstance/
+  vkCreateDevice) and vkCreateSampler; on the Frame its vkCreateInstance wrapper calls an invalid pointer right after
+  OVRPlugin's pre-init instance is destroyed (a jump to 0, into an unloaded library, or a hang). frame.slz_vulkan_hooks
+  switches its two registrations off, so Unity starts Vulkan itself; the plugin's pipeline cache isn't used.
 tested_version: 1.2974.57485
 engine: Unity
 xr: OpenXR
+frame:
+- frame.unity_user_presence
+- frame.slz_vulkan_hooks
 verified:
-  date: '2026-10-04'
-updated: '2026-10-04'
+  date: '2026-10-08'
+updated: '2026-10-08'
 source_hint: BONELAB
+min_app: 0.12.1

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.VR_HOT.VR_HOT_Quest.yaml

@@ -0,0 +1,23 @@
+package: com.VR_HOT.VR_HOT_Quest
+title: VR HOT Quest
+status: works
+tested_version: 0.8.8.1
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  controller_models: 1
+  haptic_fix: 1
+verified:
+  date: '2026-10-08'
+  known_good_sha256: c321606c536eba1673572a9f44fd9e20d2cb5bd9609d536189e6ad7057b9cd67
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 59
+  issue: 98
+source_hint: VR-HOT-Quest-0.8.8.1

catalog/games/com.YourCompany.SWP_VR.yaml

@@ -0,0 +1,25 @@
+package: com.YourCompany.SWP_VR
+title: Star Wars Pinball VR
+tested_version: '1.4'
+source_hint: Star Wars Pinball VR
+engine: Unreal
+xr: VrApi
+status: works
+notes: Plays (owner's headset test); one short audio hiccup seen.
+details: 'Unreal 4.25 (GLES) built against OVRPlugin 1.44. Four Frame problems in a row: Zink crashed on Unreal''s
+  multisampled render-to-texture (fault addr 0x10000 on the RHIThread): frame.unreal_gl_shim, which keeps Unreal''s
+  multiview and draws those passes single-sampled; OVRPort''s OVRPlugin lacks ovrp_GetPTWNear, so Unreal''s Oculus
+  module never started VR (then a null pointer in GetMultiViewSceneColor): frame.unreal_ovrp_entrypoints; the engine''s
+  OpenSSL assembly has unpaired return-address checks the Frame''s CPU enforces (SIGILL on the HttpManager thread):
+  frame.pac_hints. Needs its OBB (main.10765).'
+frame:
+- frame.unreal_gl_shim
+- frame.unreal_ovrp_entrypoints
+- frame.pac_hints
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-08'
+  issue: 83
+updated: '2026-10-08'
+min_app: 0.12.1

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.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.cloudheadgames.pistolwhip.yaml

@@ -0,0 +1,22 @@
+package: com.cloudheadgames.pistolwhip
+title: Pistol Whip
+status: works
+notes: 120 HZ
+tested_version: 1.6.0.2
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-08'
+  known_good_sha256: ebd97af54c59d59d473c98492c1bb26ce6059b7e59f27a08acfc5ada23d0b774
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261006.6173745'
+  agent: 59
+  issue: 100
+source_hint: Pistol Whip

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

@@ -1,17 +1,18 @@
 package: com.crowscrowscrows.AccountingPlus
 title: Accounting+
-status: issues
-notes: Starts in VR, but doesn't get past its "press any button" screen.
+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. Controller input reaches the game's OVRInput
-  cleanly (both Touch controllers connected, individual button bits, input focus 1 while focused) but the screen
-  doesn't continue; Cpp2IL can't read this Unity version to see what it waits for.
+  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-04'
-updated: '2026-10-04'
+  date: '2026-10-06'
+updated: '2026-10-06'
+min_app: 0.11.0
 source_hint: Accounting+

catalog/games/com.curif.AgeOfJoy.yaml

@@ -0,0 +1,22 @@
+package: com.curif.AgeOfJoy
+title: AgeOfJoy
+status: works
+tested_version: '1.0'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-08'
+  known_good_sha256: 9780e71e417b86290147c67c83755305801d8957909734c717a519034edefdf9
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261006.6173745'
+  agent: 59
+  issue: 103
+source_hint: AgeOfJoy 05 rc30

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.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.playful.LuckysTale.yaml

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

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/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/triage.yaml

@@ -8,18 +8,48 @@ 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: unreal-msrtt-crash
+    pattern: 'fault addr 0x10000 in tid \d+ \((RHIThread|RenderThread)'
+    severity: fatal
+    diagnosis: The game's render thread jumped to address 0x10000 inside the Frame's GL driver (Mesa/Zink) a few seconds after start. Zink looks up a render-pass cache slot past its end when a game renders through multisampled render-to-texture (Unreal's mobile MSAA, e.g. Star Wars Pinball VR). Load the GL shim, which hides that extension.
+    suggest: [frame.unreal_gl_shim, frame.unity_gl_shim]
+  - id: pac-unpaired
+    pattern: 'ILL_ILLOPN\), fault addr 0x[0-9a-f]+ \(\*pc=0xd50323bf\)'
+    severity: fatal
+    diagnosis: The game crashed on a return-address check (autiasp) its code never signed. The Quest's CPU ignores these checks, the Steam Frame's enforces them; some OpenSSL assembly in game engines has such unpaired checks (e.g. Star Wars Pinball VR on its first network connection, thread HttpManager).
+    suggest: [frame.pac_hints]
   - 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.10.1 clamps the rects - rebuild and reinstall the game.
+    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]
@@ -74,6 +104,12 @@ signatures:
     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: unity-frame-not-begun
+    pattern: 'frame loop shim: frame \d+: the last waited frame wasn.t begun'
+    severity: info
+    diagnosis: Unity skipped beginning a frame (typically while it activates a scene); FramePort's frame wait didn't
+      wait for that frame instead of blocking the game. A few at each scene load are normal.
+    suggest: []
   - id: sdl-no-clipboard
     pattern: 'ClipboardManager\.addPrimaryClipChangedListener|SDLClipboardHandler\.<init>'
     severity: fatal
@@ -86,6 +122,12 @@ signatures:
       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
@@ -96,8 +138,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]
@@ -130,6 +201,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
@@ -154,6 +237,20 @@ 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: slz-vulkan-hook-crash
+    pattern: 'SLZ Graphics plugin loading![\s\S]{0,20000}?E CRASH   : .*pc  0000000000000000'
+    severity: fatal
+    diagnosis: Stress Level Zero's graphics plugin (libSLZQuestNative.so) hooks Unity's Vulkan start-up and calls an invalid function there on the Frame (e.g. BONELAB 1.2974); the game crashes or hangs before its first frame.
+    suggest: [frame.slz_vulkan_hooks]
+    supersedes: [java-crash, native-crash]
   - id: native-crash
     pattern: 'Fatal signal (\d+) \(SIG[A-Z]+\)'
     severity: fatal

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`.

docs/COMPATIBILITY.md

@@ -6,7 +6,7 @@ Other games get suggested patches from detection rules; each suggestion states i
 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
+Tried an untested game? Its page asks how it runs; **Share working recipe…** opens a prefilled GitHub issue so your
 recipe can join the built-in catalog for everyone.
 
 ![Patches](images/patches.png)

docs/DIAGNOSTICS.md

@@ -2,7 +2,7 @@
 
 Two ways users feed results back, both without a GitHub token:
 
-- **Share working config** (game menu, `frameport share-recipe <pkg>`): saves the recipe as a user catalog entry and
+- **Share working recipe** (game menu, `frameport share-recipe <pkg>`): saves the recipe as a user catalog entry and
   opens a prefilled issue from `.github/ISSUE_TEMPLATE/working-config.yml`. A maintainer checks it and adds the label
   `catalog-accepted`. Then `.github/workflows/catalog-from-issue.yml` runs `scripts/catalog_from_issue.py`, which reads
   only the YAML block, validates it, and writes `catalog/games/<pkg>.yaml`, and the workflow opens a PR.

docs/FAQ.md

@@ -24,7 +24,7 @@ Games/                                  ← scan this folder (Add games → Scan
   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
+- **A single game:** Add games → Add an APK… 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

docs/FRAME_RUNTIME.md

@@ -28,6 +28,23 @@
   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),
   KHR_vulkan_enable(2), KHR_opengl_es_enable, KHR_composition_layer_depth, FB_display_refresh_rate, EXT_hand_tracking
@@ -55,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)
@@ -65,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`).
@@ -105,6 +137,24 @@
 - 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.
+- Linux apps' own icons (GitHub #99, agent v64): finalize_linux (and every refresh of the menu entries) copies the
+  app's icon to `<anchor>/artwork/app-icon.{png,svg}`: an AppImage's `squashfs-root/.DirIcon` (usually a symlink),
+  else the `Icon=` of its top-level `.desktop` file (a folder app: the first `.desktop` within 3 levels) looked up
+  next to it, in `(usr/)share/icons/hicolor/*/apps/` and `(usr/)share/pixmaps/`; the biggest PNG ≥128 px, else an
+  SVG, else the biggest PNG. Symlinks are resolved and must stay inside the app folder; absolute and `../` names
+  are ignored. Precedence for the menu entry's `Icon=` and the Steam shortcut's icon: the user's chosen/store icon
+  (`artwork/.icon-source` = `custom`, written by the PC with every art upload) > the app's own (Steam: PNG only) >
+  FramePort's placeholder (`artwork/icon.*`). `StartupWMClass=` is copied from the app's `.desktop` file (Plasma's
+  task bar matches the window to the entry). A PNG ≤1 MiB goes back to the PC (finalize result `app_icon.png`,
+  base64) and becomes the library's icon when the game has none and nothing was picked (`.app-icon` marker = its
+  sha256, no `.picked`); folder apps get it on the PC at add time (`analysis/linux.find_icon`). Not yet seen in
+  Desktop Mode on the device.
 
 ## 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
@@ -127,7 +177,60 @@
   `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.
+  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
 
@@ -139,3 +242,26 @@
   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/GAMES.md

@@ -1,76 +1,98 @@
 # 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…**).
+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 recipe can be shared from the app (**Share working recipe…**).
 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 |  |
+| AgeOfJoy | 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 |  |
+| BONELAB | 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 |  |
+| Pistol Whip | Quest | ✅ Works |  |
 | PowerWash Simulator VR | Quest | ✅ Works |  |
 | QuestCraft | Quest | ✅ Works |  |
+| Retronika | 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 | Quest | ✅ Works |  |
 | Sniper Elite VR: Winter Warrior | Quest | ✅ Works |  |
 | Space Pirate Trainer Quest | Quest | ✅ Works |  |
+| Star Wars Pinball VR | 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 |  |
+| VR HOT Quest | Quest | ✅ Works |  |
 | VR4 | Quest | ✅ Works |  |
 | Wallace & Gromit in The Grand Getaway | Quest | ✅ Works |  |
 | Waltz of the Wizard: Extended Edition | Quest | ✅ Works |  |
 | Wander | Quest | ✅ Works |  |
-| Accounting+ | Quest | ⚠️ Works with issues | Starts in VR, but doesn't get past its "press any button" screen. |
 | Arcsmith | Quest | ⚠️ Works with issues | Right eye distorts during movement (unresolved; swap, tracking, Valve layers, depth and pacing ruled out). |
 | Assassin's Creed Nexus | Quest | ⚠️ Works with issues | Some launch warning text is still upside down; the rest of the UI is fixed by flip emulation. |
-| I Am Cat | Quest | ⚠️ Works with issues | The view vibrates slightly, even when holding still. |
-| Lucky's Tale | Quest | ⚠️ Works with issues | Runs out of memory within a few minutes and freezes the Frame until the game is killed. |
+| 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… |
-| BONELAB | Quest | ❌ Doesn't run | Crashes while starting its graphics (Vulkan); no fix yet. |
+| 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

@@ -1,5 +1,10 @@
 # Installing FramePort
 
+▶ **[Watch the install tutorial](media/frameport-install.mp4)** (about 90 seconds, MP4; also attached to every
+release as `FramePort-install.mp4`): from the download to the first game on the Frame.
+
+[![The install tutorial](media/frameport-install.jpg)](media/frameport-install.mp4)
+
 Download the archive for your computer from the [latest release](https://github.com/spoopyghosty0/frameport/releases/latest)
 and extract it anywhere. No installer or admin rights are needed. On first start FramePort downloads its Java
 runtime, the OVRPort CLI and apksigner into its data folder (Settings → Tools shows them).
@@ -85,13 +90,51 @@ which would end Desktop Mode). This is new: please report anything odd with **Re
 - 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**).
+  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…** 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 → Add 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. For your page there's an "Install with FramePort" button:
+  [INSTALL_BUTTON.md](INSTALL_BUTTON.md). 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)
 
@@ -102,10 +145,10 @@ reality), showing only what matters for that game. Changes are kept with the gam
 
 ## Typing on the Frame
 
-- **Type on Frame** (Steam Frame page, a game's menu, or the keyboard icon on the sidebar's Frame card): while the
-  window is open, this computer's keyboard works as a keyboard plugged into the Frame. Select a text field in the
-  headset (in an app, Steam or the desktop) and type; Esc and shortcuts go to the Frame too. Paste longer text into
-  the box to type it in one go (US keyboard layout). Click **Done** to disconnect.
+- **Type on Frame** (its own tab in the sidebar; also on the Steam Frame page): 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.
@@ -113,6 +156,19 @@ reality), showing only what matters for that game. Changes are kept with the gam
   **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
@@ -140,7 +196,7 @@ Command line: `frameport update` (`--check` only checks, exit code 10 = update a
 ## PC VR games
 
 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
+**Add games → Add a PC 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.
 
@@ -151,23 +207,30 @@ an installed Revive, or downloads a portable copy.
   on the game page.
 - Games that use the Oculus Platform SDK check the licence through the Oculus app, so they run on the PC only.
 
-**Windows games without VR:** **Add games → Add one game folder…** with the game's folder (pick the program that
+**Windows games without VR:** **Add games → Add a PC 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).
 
-## Linux apps (arm64)
+## 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 (arm64)…** takes an AppImage or a `.zip`/`.tar.gz`/
+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 can't run on the Frame: FramePort says so when you add one. Look for an aarch64/arm64 download.
-- The app must bring the libraries SteamOS doesn't have. If some are missing, the install reports them and the game
+- **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)
@@ -192,7 +255,7 @@ Command line: `frameport frame send <files> --dest videos` (`frameport frame sto
 
 ## 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
+- **Share working recipe…** (game menu): opens a prefilled GitHub issue with the game's patches and settings. Accepted
   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,
@@ -207,12 +270,14 @@ 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 an arm64 Linux app (AppImage, folder or archive) |
+| `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 |
 

docs/INSTALL_BUTTON.md

@@ -0,0 +1,99 @@
+# "Install with FramePort" button
+
+A button for web pages and READMEs that opens a game straight in FramePort. Clicking it hands FramePort an install
+link; FramePort shows what it would download and asks before it does anything (see
+[Install links](INSTALL.md#install-links-install-with-framedrop-buttons)).
+
+<p>
+  <img src="badges/install-with-frameport-animated.svg" alt="Install with FramePort" width="216" height="60">
+</p>
+
+## Files
+
+All files are in [`docs/badges/`](badges/). Each SVG is self-contained (no external fonts or images), 216 × 60.
+
+| File | Use it for |
+|---|---|
+| [`install-with-frameport.svg`](badges/install-with-frameport.svg) | Everywhere. No motion. |
+| [`install-with-frameport-animated.svg`](badges/install-with-frameport-animated.svg) | GitHub READMEs and other pages that only allow images. The glow plays by itself every 6 seconds: blue swells from the left, the portal between "Frame" and "Port" flares, then orange swells on the right. |
+| [`install-with-frameport-hover.svg`](badges/install-with-frameport-hover.svg) | Websites where you can paste HTML. The glow brightens and the middle portal lights up while the pointer is on the button. It only reacts to the mouse when the SVG code is placed in the page itself (see below). |
+| [`install-with-frameport@2x.png`](badges/install-with-frameport@2x.png) | Places without SVG support (some forums, email). 432 × 120; show it at 216 × 60. |
+
+Both animated versions stop moving for visitors who turn on reduced motion in their system settings.
+
+## The link
+
+The button links to an install link, which names either a manifest or one file:
+
+```
+frameport://install?manifest=<URL-encoded https address of a manifest .json>
+frameport://install?url=<URL-encoded https address of an .apk, a Linux build (.zip, .tar.*, .AppImage) or a Windows .exe>
+```
+
+The manifest is the FrameDrop format, which FramePort reads as it is:
+
+```json
+{
+  "schema": "framedrop.install/v1",
+  "name": "My Game",
+  "files": [{ "url": "https://example.com/my-game.apk", "sha256": "<64 hex digits>" }],
+  "frameport": { "description": "One sentence about the game.", "icon": "https://example.com/icon.png" }
+}
+```
+
+`name` becomes the game's title in Steam. `sha256` is optional but recommended: FramePort checks the download
+against it. The `frameport` object is optional and ignored by FrameDrop; its icon and description are shown in the
+install question. Only public `https://` addresses are accepted.
+
+To build a link from Python: `frameport.deeplink.make_link(manifest_url="https://…/my-game.json")`.
+
+## On a website
+
+Image version (any page):
+
+```html
+<a href="frameport://install?manifest=https%3A%2F%2Fexample.com%2Fmy-game.json">
+  <img src="install-with-frameport.svg" alt="Install with FramePort" width="216" height="60">
+</a>
+```
+
+Hover version: paste the contents of `install-with-frameport-hover.svg` inside the link instead of the `<img>`, and
+give the link an accessible name:
+
+```html
+<a href="frameport://install?manifest=https%3A%2F%2Fexample.com%2Fmy-game.json" aria-label="Install with FramePort">
+  <svg …>…</svg>  <!-- the whole file -->
+</a>
+```
+
+Host the files yourself, or load them from jsDelivr, which serves them with the right content type:
+`https://cdn.jsdelivr.net/gh/spoopyghosty0/frameport@main/docs/badges/install-with-frameport.svg` (replace `main`
+with a release tag such as `v0.12.0` to pin a version; jsDelivr caches `@main` for up to 12 hours).
+
+## In a GitHub README
+
+GitHub removes links that don't start with `https://` or `http://` from READMEs, so a `frameport://` link there is
+not clickable. Link the button to an `https://` page instead, for example your release page with instructions, or
+FrameDrop's install page, which opens `framedrop://` links (FramePort opens those too while Settings → Install links
+→ `framedrop://` is on):
+
+```markdown
+[![Install with FramePort](https://cdn.jsdelivr.net/gh/spoopyghosty0/frameport@main/docs/badges/install-with-frameport-animated.svg)](https://framedropvr.com/install?manifest=https%3A%2F%2Fexample.com%2Fmy-game.json)
+```
+
+Use the animated or still SVG; the hover version doesn't react inside a README, because GitHub shows SVGs as
+images.
+
+## If a visitor doesn't have FramePort
+
+A `frameport://` link does nothing visible (or shows the browser's "no app for this link" message) when FramePort
+isn't installed. Put a line next to the button such as "Needs [FramePort](https://github.com/spoopyghosty0/frameport)
+on Windows or Linux." On macOS, web pages can't hand links to FramePort yet: users paste the link into Add games →
+Add from a link….
+
+## Usage rules
+
+- Keep the alt text "Install with FramePort".
+- Don't recolor, stretch, crop or redraw the button, and don't show it smaller than 40 px tall.
+- Leave some space around it (at least 8 px) so it doesn't touch other buttons.
+- It works on light and dark pages as it is; there is no light version.

docs/PLAYBOOK.md

@@ -13,13 +13,28 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 ## Startup failures (visible in launch.log)
 | Symptom | Cause | Fix |
 |---|---|---|
+| A launch test suggests a fix (e.g. triage `sdl-no-clipboard` → `frame.sdl_clipboard`) but the game page doesn't show it / lists it as not applicable; or a game added long ago lacks warnings newer ones get (Android version, web wrapper, missing OBB) (GitHub #104, Dramatic Shape) | the library entry was analysed by an older FramePort: the analysis field the patch reads (`sdl_java`, `min_sdk`, `web_wrapper`, `expects_obb`, …) is missing, so `applies()` is false | entries whose `analysis.extra.analysis_version` is below `detect.ANALYSIS_VERSION` are analysed again at the GUI's start (background) and before a build (`pipeline.refresh_analyses`); by hand: game menu → "Analyze again", then Update on Frame. An unreadable APK is marked `analysis_failed` (retried after the next version bump). Adding an analysis field: bump `ANALYSIS_VERSION` |
+| 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, Sniper Elite VR's tutorial grab: memory grows ~1 GB/s until the kill) | 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); also reached from Unity's legacy `ovrp_SetControllerHaptics`; perf page faults all in `libopenxr_loader.so` `xrApplyHapticFeedback` | `adapter.haptic_fix` (envelope → one plain vibration in `native/xrshim`; PCM vibrations (`XrHapticPcmVibrationFB`) are converted the same way). 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) |
+| A Linux app (AppImage) shows no/FramePort's placeholder icon in Desktop Mode or Steam (GitHub #99) | before agent v64 only FramePort's art set's icon was used, and a lone AppImage has no store art | connect FramePort once (agent v64 copies the app's `.DirIcon` / `.desktop` `Icon=` to `<anchor>/artwork/app-icon.*` and refreshes the menu entry); reinstall to also get it into the library + Steam shortcut. Still the placeholder: check `<base>/app/squashfs-root/.DirIcon` and the `.desktop` file's `Icon=` (an icon outside the app folder or only an XPM isn't used); a chosen icon (`artwork/.icon-source` = `custom`) always wins |
 | 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 |
+| 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 |
@@ -32,13 +47,19 @@ 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) |
+| Game hangs at start / never loads although its .obb files are right there: next to the APK, in an `obb` folder beside an `apk` folder inside a `<package>` folder, or a SideQuest backup (`<timestamp>_<versionCode>.apk`) (GitHub #85, #91) | No folder named after the package, so the folder-layout checks found nothing and no OBB was uploaded | `quest_dump.find_data` then looks for the files by name, `(main\|patch).<versionCode>.<package>.obb` (any case), in the APK's folder, its parent and up to 3 levels below each (folders with their own APKs are other games); prefers the folder and files of the APK's own versionCode, else the newest older, else any version. When that folder also holds other things (the APK itself, other games' OBBs), the library entry gets `data_files` and only those files are uploaded, counted and deleted with the game. Add the folder again |
+| Unreal game: `JNI_OnLoad` (OVRPlugin), then silence: no OpenXR instance, no crash, no frames (GitHub #85 TRIANGLE STRATEGY; launch-test finding `missing-obb`) | Installed without its OBB: the manifest says `com.epicgames.ue4.GameActivity.bHasOBBFiles` = true (UE5: `com.epicgames.unreal.…`) but the library has no data folder (`data_dir` null, `data_bytes` 0) | Put the .obb files in a `<package>` (or `obb/`) folder next to the APK, add the folder again, reinstall. Analysis `extra.expects_obb`; the game page, the install question and `frameport scan`/`install` warn; launch tests that sent no frames get the `missing-obb` finding from the library (the game logs nothing). Unity split-binary builds count too (`extra.unity_split`, `analysis/unity_split.py`): an XR-plugin build (Oculus XR Plugin / Unity OpenXR library) without `assets/bin/Data/UnitySubsystems/` in the APK, or BuildSettings listing more scenes than the APK has `levelN` files (globalgamemanagers loose or read from the head of data.unity3d); exact on the 48 Unity APKs of the dumps (13 split, 17 full games; OBBs of full builds are asset bundles or sound banks) |
 | `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 |
@@ -56,14 +77,22 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Quest app keeps recentering / snapping the view when you turn your head; log shows session state 5→4→3→4→5 within a second | the Frame briefly takes focus; the app recenters on focus changes | unfixed: hiding the dips (debounce) made AC Nexus stay black, so it was removed |
 | Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | upload in the Files tab (Videos = /sdcard/Movies) and browse folders in the app |
 | 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.10.1; log `rect_clamp: view N image rect clamped`): rebuild + reinstall the game |
+| 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 |
+| Unreal GLES game crashes ~3 s after start: `Fatal signal 11 … fault addr 0x10000 in tid … (RHIThread)`, `#01 … libgallium_dri.so` (GitHub #83 Star Wars Pinball VR, triage `unreal-msrtt-crash`) | Unreal's mobile MSAA renders through multisampled render-to-texture; Zink's `find_rp_state` then indexes `rendering_state_cache[6]` one past its end (sample count ≥ 32) and calls a junk hash function (0x10000). Mesa bug (no bounds check) | `frame.unreal_gl_shim` (GL shim with `gl_hide_msrtt`, multiview kept for Unreal: Unreal 4.25 only enables multiview with GL_OVR_multiview, GL_OVR_multiview2 **and** GL_OVR_multiview_multisampled_render_to_texture, so the shim keeps the last one visible for Unreal and maps glFramebufferTextureMultisampleMultiviewOVR to the single-sampled glFramebufferTextureMultiviewOVR; log `multiview multisampled render-to-texture (N samples) drawn single-sampled`) |
+| Crash with `SIGILL (ILL_ILLOPN)` and `*pc=0xd50323bf` (autiasp), e.g. on Unreal's HttpManager thread (GitHub #83 Star Wars Pinball VR, triage `pac-unpaired`) | The engine's OpenSSL ARMv8 assembly has autiasp without a matching paciasp (libUE4.so: 38 paciasp, 40 autiasp; Poly1305 NEON). Quest CPUs treat PAC hints as NOPs, the Frame's CPU checks them | `frame.pac_hints`: in a library with unpaired counts every paciasp/autiasp becomes a NOP (in place) |
+| Unreal game (OVRPlugin) never starts VR: launch.log has `OVRPlugin: JNI_OnLoad` but never `CompositorOpenXR::PreInitialize`, no OpenXR session, then a crash a few seconds in (e.g. Star Wars Pinball VR, UE 4.25: null pointer in `FSceneRenderer::GetMultiViewSceneColor`, GitHub #83) | Unreal's Oculus module looks up every `ovrp_*` function of the OVRPlugin it was built against (`InitializeOculusPluginWrapper`, all ANDed); OVRPort's OpenXR OVRPlugin lacks a few old ones (UE 4.25 / OVRPlugin 1.44: `ovrp_GetPTWNear`), so the wrapper fails and OculusHMD is never pre-initialised | `frame.unreal_ovrp_entrypoints` (suggested when analysis `unreal_ovrp_lookups` name functions the shipped OVRPlugin lacks): generated `libfp_ovrpstubs.so` (DT_NEEDED of libOVRPlugin.so; dlsym on the plugin's handle searches its dependencies) with a stand-in per missing name returning ovrpFailure (-1000); build note lists the names |
 | Only the Android home screen shows; the log has Unity's VR device as `None` (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) |
+| Unity built-in VR game (with `frame.unity_oculus_check`) freezes at a scene switch: the log stops after `Boot: Activating Scene: …`, the process stays alive, every thread sleeps (e.g. Sniper Elite VR, Unity 2019.4) | The shim's `xrWaitFrame` blocks until the previously waited frame is begun; Unity skipped beginning it at the scene switch and its render thread then waited for the main thread (gdb: UnityMain in vrclient `CSxrSession::StartNextFrame` ← `ovrp_WaitToBeginFrame` ← `fpov_Update2`). OVRPlugin also only begins the frame index it waited for | `frame.unity_oculus_check` revision 5: libunity.so's `ovrp_BeginFrame`/`ovrp_EndFrame` go through the shim, which waits ≤ 50 ms for the last waited frame to begin, else skips the wait (log `the last waited frame wasn't begun`), and gives a begin/end of another index the waited one |
+| Unity built-in VR game: the hands/weapons trail the controllers by centimetres when moving (headset fine, 72 fps), e.g. Sniper Elite VR | Unity's physics-step `ovrp_Update2` (prediction 0) makes OVRPlugin locate the nodes at the monotonic clock's "now", the XrTime base on a Quest but 0.05–0.9 s behind the Frame's XrTime; the runtime extrapolates backwards and the render-step reads after it get those poses too. A larger prediction is capped by OVRPlugin (~0.07 s) | `frame.unity_oculus_check` revision 5 holds the physics-step update back: both steps read the render update's display-time poses |
+| 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) |
@@ -73,6 +102,8 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | 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 → Add 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) |
@@ -87,15 +118,29 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Eye distortion while moving (Arcsmith, Time Stall) | unknown (not eye swap, tracking, Valve layers, depth or pacing) | unresolved |
 | One eye grey / only effects (I Am Cat, Unity Oculus XR Plugin on GLES) | the game's multiview pass draws array slice 1 wrong on Zink | `frame.unity_multipass` (also rewrites the getter's inlined read in `OculusLoader.Initialize`; check for two `array=1` eye swapchains) |
 | View vibrates even when holding still after `frame.unity_multipass` (I Am Cat) | poses/times are consistent, but two passes on Zink make every frame one period late, and the game clamps its physics step to 10 ms | not fixed (scale 0.8 didn't help); next ideas: fix multiview instead, or the game's fixed timestep |
-| Game freezes / pauses for 1-2 s now and then, no flicker; only some games (Blade & Sorcery) | the headset's wear sensor flickers off while worn (SteamVR vrserver.txt `HMD off, stopping eye tracking` … `HMD on`), the Frame turns it into a focus loss and Quest games that pause on focus loss pause | adapter `focus_hold=1` + `focus_hold_ms=2500` per game; native games don't react, so it's per game |
+| 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 `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 crashes or hangs right as Vulkan starts, after `SLZ Graphics plugin loading!` and OVRPlugin's pre-init `xrDestroyInstance`: SIGSEGV with pc 0 (or pc == fault address in an unloaded library), x16/x23 in `libSLZQuestNative.so` (BONELAB 1.2974) | Stress Level Zero's graphics plugin hooks Unity's Vulkan start-up (IUnityGraphicsVulkanV2 interception: vkCreateInstance/vkCreateDevice) and vkCreateSampler; its vkCreateInstance wrapper calls an invalid pointer on the Frame | `frame.slz_vulkan_hooks` (its two registrations become no-ops; Unity starts Vulkan itself; ~35 s of shader prewarming without its pipeline cache) |
+| 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).
@@ -111,6 +156,14 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
   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).
+- Hangs (every thread asleep): backtraces of all threads with gdb. Root inside the Lepton container may ptrace the
+  game (the host's `ptrace_scope` 1 doesn't apply there) and the guest has `gdbserver64`; `debuggerd -b` fails (no
+  tombstoned). Copy every mapped library to a local sysroot (`podman exec <container> cat /proc/<pid>/maps`, then
+  `tar -chf - -T <list>` through `podman exec -i`; the app's own libs from the installed `lepton-app/game.apk` at their
+  `/data/app/…/lib/arm64` path), then on the PC: `gdb -batch -ex "set sysroot <dir>" -ex "target remote | ssh
+  steamos@<frame> podman exec -i lepton-steamlaunch-<appid> gdbserver64 - --attach <pid in the container>" -ex
+  "thread apply all bt 25" -ex detach` (`set sysroot target:` makes gdbserver assert in linux_mntns_readlink).
+  `/proc/<pid>/task/*/syscall` (read inside the container) shows each thread's syscall and pc without a debugger.
 - 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:`

docs/SHOWCASE.md

@@ -0,0 +1,152 @@
+# Screenshots and videos
+
+The pictures in the docs and the videos are rendered by scripts, never taken by hand. The scripts show the real
+FramePort GUI with a demo library and a pretend Steam Frame, drive it the way a person would, and film or photograph
+it:
+
+| What | Source | Output |
+|---|---|---|
+| Docs screenshots | `docs/showcase/shots.yaml` | `docs/images/*.png` |
+| Demo tour (about 95 s) | `docs/showcase/videos/tour.yaml` | `docs/media/frameport-tour.mp4` (+ `.jpg` poster), `docs/images/tour-teaser.webp` (README) |
+| Install tutorial (about 90 s) | `docs/showcase/videos/install.yaml` | `docs/media/frameport-install.mp4` (+ `.jpg` poster) |
+
+Nothing comes from anyone's own library. The demo library (`docs/showcase/demo-library.yaml`) lists real catalog
+games, so recipes and patches are the ones FramePort really uses. Their technical analysis (`demo-analyses.json`:
+engine, VR API, libraries, sizes) was exported from real APK analyses without any paths. Art, in-game screenshots
+and store details come from the same public sources the app uses and are cached in `~/.cache/frameport-showcase`.
+The renderer refuses to run in FramePort's own data folder, scans the demo data for home paths and IP addresses
+first, and stops when a store didn't send art (placeholders never reach the docs; `--allow-missing-art` overrides
+that). Frame discovery is switched off during a render (no real device on your network can appear), and the setup
+command shows placeholders for the address and code (each PC has its own), never this computer's.
+
+## Running it
+
+You need the dev extras, Chromium for Playwright and ffmpeg:
+
+```
+UV_LINK_MODE=copy uv sync --extra dev
+uv run playwright install chromium        # once
+uv run python scripts/showcase/render_docs.py               # all screenshots → docs/images (changed ones only)
+uv run python scripts/showcase/render_docs.py --only game,monitor --out /tmp/shots
+uv run python scripts/showcase/record_video.py install --draft   # quick 720p check of a storyboard edit
+uv run python scripts/showcase/record_video.py              # every video → docs/media (+ the README teaser)
+uv run python scripts/showcase/record_video.py tour install # some
+```
+
+Every screenshot is rendered twice, each in a fresh window, and kept only when both agree (the headless GPU now and
+then draws a glyph wrong); a third render settles a disagreement, and `--fast` renders once for trying out an edit.
+A shot whose steps fail is tried again and never written. A screenshot is rewritten only when it visibly changed
+(`render_docs.changed`: anti-aliasing noise doesn't count), so running it twice changes nothing. `--check` writes
+nothing and exits 1 when a docs image is out of date.
+
+For videos, `--names` prints what can be clicked after each scene and `SHOWCASE_DEBUG=1` prints every step with its
+start time (which step waited); `--draft --scenes a,b` records only some scenes. A video is encoded at the best
+quality that fits its `budget_mb` (12 by default), a teaser at 4 MB.
+
+## Videos
+
+One storyboard per video in `docs/showcase/videos/<name>.yaml`; adding a file adds a video (CI and releases pick it
+up by itself). The output must be `docs/media/frameport-<name>.mp4`: releases attach it as `FramePort-<name>.mp4`.
+
+```yaml
+output: docs/media/frameport-install.mp4
+teaser: docs/images/tour-teaser.webp     # optional: a looping WebP from the scenes' `teaser` parts
+budget_mb: 12
+poster_at: 9                             # the poster frame, seconds after the title card
+start:
+  profile: fresh          # demo = FramePort in use (games installed, BONELAB running); fresh = its first start
+  frame: disconnected     # connected (default) or disconnected
+  route: welcome          # the page filming starts on (default library)
+  stream: live            # the monitor stream: live (default) or frozen
+setup:                    # steps before filming starts (a failure stops the recording)
+  - hook: {name: first_run, args: ["D:/Games", 1.4]}
+vars: {game: com.playful.LuckysTale}     # ${game} in any step
+title: {heading: Installing FramePort, line: …, seconds: 3.4}
+end: {heading: You're set, line: …, footer: github.com/spoopyghosty0/frameport, seconds: 4}
+scenes:
+  - name: connect                        # a filmed scene
+    caption: ["Connect your Steam Frame", "Once: FramePort shows a command to run on the Frame"]
+    teaser: [0.6, 4.0]                   # optional: this part goes into the teaser
+    hold: 1.5                            # seconds of filming after the last step (default 0.6)
+    steps: [...]
+  - name: on-the-frame                   # an instruction card: for what happens outside FramePort
+    seconds: 10
+    card:
+      eyebrow: "Step 3 · On the Frame, first time only"
+      heading: Run the setup command
+      steps: ["In the SteamVR dashboard: **Launch a program** → **Desktop**", …]   # **bold** = a button or menu
+      code: "curl -fsS <your-PC-address>:8765/<one-time-code> | bash"
+      note: "Your address and code differ."
+```
+
+Filmed scenes are one continuous session: each starts where the last one left off. Cards are rendered at the end
+and slotted in, with crossfades between everything. The `fresh` profile starts FramePort as on a new computer: an
+empty library, the welcome screen and a Frame that isn't set up. Its games wait for the pretend folder scan.
+
+## Writing steps
+
+Shots and scenes use one step language (`scripts/showcase/steps.py`). A step is a one-key mapping:
+
+```yaml
+- go: monitor                                  # a sidebar route
+- nav: "Monitor"                               # click that tab (checked: the page really changed)
+- open_game: ${game}                           # or {package: …, advanced: true}
+- call: {fn: settings_dialog, args: ["${game}"]}   # any app method
+- hover: "Batman: Arkham Shadow"               # the pointer: by name…
+- click: {name: "Lucky's Tale", dy: 0.35}      # …offset inside the element (fraction of its size, or px)
+- click: "Install on Frame"                    # right_click, double_click, drag: [from, …, to]
+- type: "ri"                                   # press: Escape
+- wait_for: "BONELAB · 2026-10-04 21:50"
+- wait: 1.2
+- hook: {name: held_install, args: ["${new_game}"]}   # the pretend Frame's scripted events
+```
+
+Elements are found by name through Flutter's accessibility tree: their visible text, a tooltip or a semantics
+label. Exact names win over prefixes, and buttons and cards win over plain text. When several match, the innermost
+one wins (a list carries the text of its rows; the row is meant). Icon-only buttons need a tooltip to be found,
+which also helps screen readers. The pointer moves on eased, slightly curved paths and is drawn into the picture,
+with a ring on every click. To open a game from a cover card, click its title (`dy: 0.35`): the card's middle is its
+Play/Install button.
+
+Hooks (`steps.HOOKS`) cover what a real Frame would do:
+- `fake_install`: an install through the real job queue with every real stage name and a launch test that passes.
+- `held_install`: an install that stops mid-upload, for screenshots of the progress.
+- `connect` and `disconnect`
+- `first_run`: a first start. The welcome screen's tool download is a pretend one, and "Scan a folder…" scans a
+  folder at once (the native folder picker can't be scripted).
+- `pairing_done`: the Frame ran the setup command, so FramePort connects.
+- `live_stream`: a test picture through the real relay.
+- `monitor_details`, `type_tab`, `select_files` and `settings_section`.
+
+In a video, clicking Install runs the scripted install, and the game is then installed on the pretend Frame.
+
+Pictures must not change from one run to the next:
+- Screenshot and file dates are fixed.
+- The Monitor's stream stops after its two-minute history.
+- The pointer leaves the page before a still picture is taken.
+- Each shot gets a fresh window and browser.
+- A picture is taken once the page has stopped changing.
+
+Live data, such as the live view's relay port and data rate, doesn't belong in a docs screenshot.
+
+## How it runs on GitHub
+
+The `showcase` workflow (`.github/workflows/showcase.yml`):
+1. **When it runs:** on pushes to `main` that touch the UI, its translations or the showcase files, and on
+   **Run workflow**.
+2. **What it renders:** the screenshots every time. Videos when their storyboard changed (all of them when the
+   scripts changed), or the ones named on a manual run (`all`, or e.g. `tour install`). UI tweaks alone don't
+   re-commit 10 MB videos.
+3. **What happens next:** every render is uploaded as the run's `showcase` artifact. When a picture changed, the
+   workflow opens or updates the pull request on branch `showcase/update`, which you review and merge.
+
+Releases attach every committed video as `FramePort-<name>.mp4`.
+
+## Gallery
+
+These are renders the README doesn't show (yet):
+
+| | |
+|---|---|
+| ![Installing](images/install-progress.png) | ![Live view](images/live-view.png) |
+| ![Appearance](images/appearance.png) | ![Game page](images/game.png) |

docs/THEMES.md

@@ -0,0 +1,61 @@
+# Themes
+
+FramePort comes with three colour themes, all dark:
+
+| Theme | Look |
+|---|---|
+| **Portal** (default) | The logo's two portals: orange for actions and the current selection, blue for secondary actions, progress and the PC side. |
+| **Portal (OLED)** | Portal on true black, for OLED screens. |
+| **Original** | FramePort's first look, with a violet accent. |
+
+Switch in **Settings → Appearance**. The change applies at once.
+
+## Your own theme
+
+A theme is a small JSON file. To make one:
+
+1. In **Settings → Appearance**, pick the theme closest to what you want and click **Copy this theme as a file**.
+2. Paste it into a text editor and save it as `something.json`.
+3. Change the name and the colours you want different. You can delete every colour you keep: missing colours come
+   from the `base` theme.
+4. Back in **Settings → Appearance**, click **Install theme file…** and choose the file. FramePort checks it,
+   switches to it and keeps a copy in its data folder (`themes/`), so you can delete the original.
+
+To remove an installed theme, click the bin icon on its card.
+
+### Format
+
+```json
+{
+  "name": "Ember & Ice",
+  "base": "portal",
+  "dual": true,
+  "colors": {
+    "ACCENT": "#FF5A36",
+    "SECONDARY": "#5CE1E6"
+  }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `name` | Shown on the theme's card (up to 40 characters). |
+| `base` | The built-in theme that fills in every colour the file leaves out: `portal` (default), `portal_oled` or `original`. |
+| `dual` | `true`: two-colour touches like Portal's (blue-to-orange sidebar edge, two-colour "FramePort", the selected tab's fade, blue secondary buttons). `false`: one accent, like Original. Default: the base's. |
+| `colors` | Any of the colours below, as `#RRGGBB` or `#RGB`. Names may be upper or lower case. |
+
+| Colour | Used for |
+|---|---|
+| `BG` | Window background |
+| `SIDEBAR` | Sidebar and activity panel |
+| `SURFACE`, `SURFACE_2`, `SURFACE_3` | Cards; raised and hovered parts; inputs and chips |
+| `BORDER`, `BORDER_STRONG` | Outlines |
+| `TEXT`, `TEXT_2`, `TEXT_3` | Main text; secondary text; captions and disabled text |
+| `ACCENT`, `ACCENT_SOFT`, `ON_ACCENT` | Main buttons and the current selection; its tint; text on it |
+| `SECONDARY`, `SECONDARY_SOFT` | Secondary buttons, progress, switch tracks; its tint |
+| `OK`, `WARN`, `ERROR`, `INFO` | Status: works, needs attention, failed, information |
+| `PC` | PC VR games and "on this PC" |
+
+FramePort refuses a theme file it can't show well, and says why: a light window background (FramePort is dark only),
+text that's hard to read on cards, an unknown colour name or a value that isn't a colour. An example is in
+[`themes/example-theme.json`](themes/example-theme.json).

docs/badges/install-with-frameport-animated.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="216" height="60" viewBox="0 0 216 60" role="img" aria-label="Install with FramePort"><title>Install with FramePort</title><style>.fp-wb,.fp-wo{transform-box:view-box}
+.fp-wb{transform-origin:0 0;animation:fp-wb 6s ease-in-out infinite}
+.fp-wo{transform-origin:216px 0;animation:fp-wo 6s ease-in-out infinite}
+.fp-core{animation:fp-core 6s ease-in-out infinite}
+@keyframes fp-wb{0%,10%,100%{opacity:.45;transform:scaleX(1)}32%{opacity:1;transform:scaleX(1.5)}54%{opacity:.3;transform:scaleX(1)}}
+@keyframes fp-core{0%,28%,100%{opacity:0}42%{opacity:1}60%{opacity:0}}
+@keyframes fp-wo{0%,38%,100%{opacity:.6;transform:scaleX(1)}60%{opacity:1;transform:scaleX(1.4)}84%{opacity:.6;transform:scaleX(1)}}
+@media (prefers-reduced-motion:reduce){.fp-wb,.fp-wo,.fp-core{animation:none!important}}</style><defs>
+  <linearGradient id="fab" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".46"/><stop offset=".55" stop-color="#3AA8FF" stop-opacity="0"/></linearGradient>
+  <linearGradient id="fao" x1="0" y1="0" x2="1" y2="0"><stop offset=".45" stop-color="#FF8A1F" stop-opacity="0"/><stop offset="1" stop-color="#FF8A1F" stop-opacity=".34"/></linearGradient>
+  <radialGradient id="far" gradientUnits="userSpaceOnUse" cx="122" cy="39" r="46" gradientTransform="translate(122 39) scale(1 .62) translate(-122 -39)"><stop offset="0" stop-color="#FFE2BD" stop-opacity=".42"/><stop offset=".25" stop-color="#FF8A1F" stop-opacity=".2"/><stop offset=".6" stop-color="#3AA8FF" stop-opacity=".08"/><stop offset="1" stop-color="#3AA8FF" stop-opacity="0"/></radialGradient>
+  <clipPath id="fac"><rect x="1" y="1" width="214" height="58" rx="11.5"/></clipPath></defs>
+  <rect x=".5" y=".5" width="215" height="59" rx="12" fill="#0D0E12" stroke="#2A2D37"/>
+  <g clip-path="url(#fac)"><rect class="fp-wb" x="1" y="1" width="214" height="58" fill="url(#fab)" opacity=".45"/><rect class="fp-wo" x="1" y="1" width="214" height="58" fill="url(#fao)" opacity=".6"/><rect class="fp-core" x="1" y="1" width="214" height="58" fill="url(#far)" opacity="0"/></g>
+  <g transform="translate(10 10) scale(0.625)">
+  <defs><linearGradient id="fal0" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".18"/><stop offset=".5" stop-color="#3AA8FF" stop-opacity="0"/><stop offset=".5" stop-color="#FF8A1F" stop-opacity="0"/><stop offset="1" stop-color="#FF8A1F" stop-opacity=".18"/></linearGradient>
+  <linearGradient id="fal1" gradientUnits="userSpaceOnUse" x1="26" y1="0" x2="38" y2="0"><stop offset=".3" stop-color="#3AA8FF"/><stop offset=".7" stop-color="#FF8A1F"/></linearGradient>
+  <clipPath id="fal2"><polygon points="-30,-30 49.145,-30 8.855,94 -30,94"/></clipPath><clipPath id="fal3"><polygon points="55.145,-30 94,-30 94,94 14.855,94"/></clipPath></defs>
+  <rect width="64" height="64" rx="15" fill="#101218"/><rect width="64" height="64" rx="15" fill="url(#fal0)"/>
+  <g clip-path="url(#fal2)"><path d="M34 15H9a3 3 0 0 0-3 3v20a3 3 0 0 0 3 3h25z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"/><rect class="fp-scr" x="10.5" y="19.5" width="24" height="17" rx="1" fill="#3AA8FF" fill-opacity="0.35"/><path d="M18 41v6M11 47h14" stroke="#ECEDF3" stroke-width="3" stroke-linecap="round"/></g>
+  <g clip-path="url(#fal3)"><path d="M56.5 31.5H58.5" stroke="#ECEDF3" stroke-width="3.4" stroke-linecap="round"/><path d="M22 21h27a8 8 0 0 1 8 8v5a8 8 0 0 1-8 8H48.65a3 3 0 0 1-2.6-1.5l-1-1.7a.9.9 0 0 0-1.6 0l-1 1.7a3 3 0 0 1-2.6 1.5H22z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"/><g class="fp-lens"><ellipse cx="39.5" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"/><ellipse cx="49" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"/></g></g>
+  <g transform="rotate(18 32 32)"><g class="fp-ptl"><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="#08090C" stroke="#08090C" stroke-width="5.8"/><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="none" stroke="url(#fal1)" stroke-opacity=".25" stroke-width="6.46" class="fp-halo"/><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="url(#fal1)" fill-opacity="0.14" stroke="url(#fal1)" stroke-width="3.4"/></g></g></g>
+  <text x="60" y="25" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="9.5" font-weight="600" letter-spacing="1.4" fill="#A7ABB7">INSTALL WITH</text>
+  <text x="60" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#FF8A1F" textLength="53.1" lengthAdjust="spacingAndGlyphs">Frame</text>
+  <g transform="translate(115.25999999999999 29.36) scale(0.8035714285714286)"><g class="fp-ptl"><defs><linearGradient id="fawr" gradientUnits="userSpaceOnUse" x1="2" y1="0" x2="14" y2="0"><stop offset=".3" stop-color="#FF8A1F"/><stop offset=".7" stop-color="#3AA8FF"/></linearGradient></defs>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="none" stroke="url(#fawr)" stroke-opacity=".35" stroke-width="5" class="fp-halo"/>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="#0D0E12" stroke="url(#fawr)" stroke-width="2.6"/></g></g>
+  <text x="130.27714285714285" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#3AA8FF" textLength="36.9" lengthAdjust="spacingAndGlyphs">Port</text></svg>

docs/badges/install-with-frameport-hover.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="216" height="60" viewBox="0 0 216 60" role="img" aria-label="Install with FramePort"><title>Install with FramePort</title><style>.fp-wb,.fp-wo{transform-box:view-box;transition:opacity .5s ease,transform .7s cubic-bezier(.2,.8,.2,1)}
+.fp-wb{transform-origin:0 0}.fp-wo{transform-origin:216px 0}
+.fp-core{transition:opacity .6s ease}
+svg:hover .fp-wb{opacity:1;transform:scaleX(1.4)}svg:hover .fp-wo{opacity:1;transform:scaleX(1.3)}
+svg:hover .fp-core{opacity:1}
+@media (prefers-reduced-motion:reduce){.fp-wb,.fp-wo,.fp-core{transition:none!important}}</style><defs>
+  <linearGradient id="fhb" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".46"></stop><stop offset=".55" stop-color="#3AA8FF" stop-opacity="0"></stop></linearGradient>
+  <linearGradient id="fho" x1="0" y1="0" x2="1" y2="0"><stop offset=".45" stop-color="#FF8A1F" stop-opacity="0"></stop><stop offset="1" stop-color="#FF8A1F" stop-opacity=".34"></stop></linearGradient>
+  <radialGradient id="fhr" gradientUnits="userSpaceOnUse" cx="122" cy="39" r="46" gradientTransform="translate(122 39) scale(1 .62) translate(-122 -39)"><stop offset="0" stop-color="#FFE2BD" stop-opacity=".42"></stop><stop offset=".25" stop-color="#FF8A1F" stop-opacity=".2"></stop><stop offset=".6" stop-color="#3AA8FF" stop-opacity=".08"></stop><stop offset="1" stop-color="#3AA8FF" stop-opacity="0"></stop></radialGradient>
+  <clipPath id="fhc"><rect x="1" y="1" width="214" height="58" rx="11.5"></rect></clipPath></defs>
+  <rect x=".5" y=".5" width="215" height="59" rx="12" fill="#0D0E12" stroke="#2A2D37"></rect>
+  <g clip-path="url(#fhc)"><rect class="fp-wb" x="1" y="1" width="214" height="58" fill="url(#fhb)" opacity=".45"></rect><rect class="fp-wo" x="1" y="1" width="214" height="58" fill="url(#fho)" opacity=".6"></rect><rect class="fp-core" x="1" y="1" width="214" height="58" fill="url(#fhr)" opacity="0"></rect></g>
+  <g transform="translate(10 10) scale(0.625)">
+  <defs><linearGradient id="fhl0" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".18"></stop><stop offset=".5" stop-color="#3AA8FF" stop-opacity="0"></stop><stop offset=".5" stop-color="#FF8A1F" stop-opacity="0"></stop><stop offset="1" stop-color="#FF8A1F" stop-opacity=".18"></stop></linearGradient>
+  <linearGradient id="fhl1" gradientUnits="userSpaceOnUse" x1="26" y1="0" x2="38" y2="0"><stop offset=".3" stop-color="#3AA8FF"></stop><stop offset=".7" stop-color="#FF8A1F"></stop></linearGradient>
+  <clipPath id="fhl2"><polygon points="-30,-30 49.145,-30 8.855,94 -30,94"></polygon></clipPath><clipPath id="fhl3"><polygon points="55.145,-30 94,-30 94,94 14.855,94"></polygon></clipPath></defs>
+  <rect width="64" height="64" rx="15" fill="#101218"></rect><rect width="64" height="64" rx="15" fill="url(#fhl0)"></rect>
+  <g clip-path="url(#fhl2)"><path d="M34 15H9a3 3 0 0 0-3 3v20a3 3 0 0 0 3 3h25z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"></path><rect class="fp-scr" x="10.5" y="19.5" width="24" height="17" rx="1" fill="#3AA8FF" fill-opacity="0.35"></rect><path d="M18 41v6M11 47h14" stroke="#ECEDF3" stroke-width="3" stroke-linecap="round"></path></g>
+  <g clip-path="url(#fhl3)"><path d="M56.5 31.5H58.5" stroke="#ECEDF3" stroke-width="3.4" stroke-linecap="round"></path><path d="M22 21h27a8 8 0 0 1 8 8v5a8 8 0 0 1-8 8H48.65a3 3 0 0 1-2.6-1.5l-1-1.7a.9.9 0 0 0-1.6 0l-1 1.7a3 3 0 0 1-2.6 1.5H22z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"></path><g class="fp-lens"><ellipse cx="39.5" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"></ellipse><ellipse cx="49" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"></ellipse></g></g>
+  <g transform="rotate(18 32 32)"><g class="fp-ptl"><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="#08090C" stroke="#08090C" stroke-width="5.8"></ellipse><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="none" stroke="url(#fhl1)" stroke-opacity=".25" stroke-width="6.46" class="fp-halo"></ellipse><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="url(#fhl1)" fill-opacity="0.14" stroke="url(#fhl1)" stroke-width="3.4"></ellipse></g></g></g>
+  <text x="60" y="25" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="9.5" font-weight="600" letter-spacing="1.4" fill="#A7ABB7">INSTALL WITH</text>
+  <text x="60" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#FF8A1F" textLength="53.1" lengthAdjust="spacingAndGlyphs">Frame</text>
+  <g transform="translate(115.25999999999999 29.36) scale(0.8035714285714286)"><g class="fp-ptl"><defs><linearGradient id="fhwr" gradientUnits="userSpaceOnUse" x1="2" y1="0" x2="14" y2="0"><stop offset=".3" stop-color="#FF8A1F"></stop><stop offset=".7" stop-color="#3AA8FF"></stop></linearGradient></defs>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="none" stroke="url(#fhwr)" stroke-opacity=".35" stroke-width="5" class="fp-halo"></ellipse>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="#0D0E12" stroke="url(#fhwr)" stroke-width="2.6"></ellipse></g></g>
+  <text x="130.27714285714285" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#3AA8FF" textLength="36.9" lengthAdjust="spacingAndGlyphs">Port</text></svg>

docs/badges/install-with-frameport.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="216" height="60" viewBox="0 0 216 60" role="img" aria-label="Install with FramePort"><title>Install with FramePort</title><defs>
+  <linearGradient id="fsb" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".46"/><stop offset=".55" stop-color="#3AA8FF" stop-opacity="0"/></linearGradient>
+  <linearGradient id="fso" x1="0" y1="0" x2="1" y2="0"><stop offset=".45" stop-color="#FF8A1F" stop-opacity="0"/><stop offset="1" stop-color="#FF8A1F" stop-opacity=".34"/></linearGradient>
+  <radialGradient id="fsr" gradientUnits="userSpaceOnUse" cx="122" cy="39" r="46" gradientTransform="translate(122 39) scale(1 .62) translate(-122 -39)"><stop offset="0" stop-color="#FFE2BD" stop-opacity=".42"/><stop offset=".25" stop-color="#FF8A1F" stop-opacity=".2"/><stop offset=".6" stop-color="#3AA8FF" stop-opacity=".08"/><stop offset="1" stop-color="#3AA8FF" stop-opacity="0"/></radialGradient>
+  <clipPath id="fsc"><rect x="1" y="1" width="214" height="58" rx="11.5"/></clipPath></defs>
+  <rect x=".5" y=".5" width="215" height="59" rx="12" fill="#0D0E12" stroke="#2A2D37"/>
+  <g clip-path="url(#fsc)"><rect class="fp-wb" x="1" y="1" width="214" height="58" fill="url(#fsb)" opacity=".45"/><rect class="fp-wo" x="1" y="1" width="214" height="58" fill="url(#fso)" opacity=".6"/><rect class="fp-core" x="1" y="1" width="214" height="58" fill="url(#fsr)" opacity="0"/></g>
+  <g transform="translate(10 10) scale(0.625)">
+  <defs><linearGradient id="fsl0" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".18"/><stop offset=".5" stop-color="#3AA8FF" stop-opacity="0"/><stop offset=".5" stop-color="#FF8A1F" stop-opacity="0"/><stop offset="1" stop-color="#FF8A1F" stop-opacity=".18"/></linearGradient>
+  <linearGradient id="fsl1" gradientUnits="userSpaceOnUse" x1="26" y1="0" x2="38" y2="0"><stop offset=".3" stop-color="#3AA8FF"/><stop offset=".7" stop-color="#FF8A1F"/></linearGradient>
+  <clipPath id="fsl2"><polygon points="-30,-30 49.145,-30 8.855,94 -30,94"/></clipPath><clipPath id="fsl3"><polygon points="55.145,-30 94,-30 94,94 14.855,94"/></clipPath></defs>
+  <rect width="64" height="64" rx="15" fill="#101218"/><rect width="64" height="64" rx="15" fill="url(#fsl0)"/>
+  <g clip-path="url(#fsl2)"><path d="M34 15H9a3 3 0 0 0-3 3v20a3 3 0 0 0 3 3h25z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"/><rect class="fp-scr" x="10.5" y="19.5" width="24" height="17" rx="1" fill="#3AA8FF" fill-opacity="0.35"/><path d="M18 41v6M11 47h14" stroke="#ECEDF3" stroke-width="3" stroke-linecap="round"/></g>
+  <g clip-path="url(#fsl3)"><path d="M56.5 31.5H58.5" stroke="#ECEDF3" stroke-width="3.4" stroke-linecap="round"/><path d="M22 21h27a8 8 0 0 1 8 8v5a8 8 0 0 1-8 8H48.65a3 3 0 0 1-2.6-1.5l-1-1.7a.9.9 0 0 0-1.6 0l-1 1.7a3 3 0 0 1-2.6 1.5H22z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"/><g class="fp-lens"><ellipse cx="39.5" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"/><ellipse cx="49" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"/></g></g>
+  <g transform="rotate(18 32 32)"><g class="fp-ptl"><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="#08090C" stroke="#08090C" stroke-width="5.8"/><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="none" stroke="url(#fsl1)" stroke-opacity=".25" stroke-width="6.46" class="fp-halo"/><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="url(#fsl1)" fill-opacity="0.14" stroke="url(#fsl1)" stroke-width="3.4"/></g></g></g>
+  <text x="60" y="25" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="9.5" font-weight="600" letter-spacing="1.4" fill="#A7ABB7">INSTALL WITH</text>
+  <text x="60" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#FF8A1F" textLength="53.1" lengthAdjust="spacingAndGlyphs">Frame</text>
+  <g transform="translate(115.25999999999999 29.36) scale(0.8035714285714286)"><g class="fp-ptl"><defs><linearGradient id="fswr" gradientUnits="userSpaceOnUse" x1="2" y1="0" x2="14" y2="0"><stop offset=".3" stop-color="#FF8A1F"/><stop offset=".7" stop-color="#3AA8FF"/></linearGradient></defs>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="none" stroke="url(#fswr)" stroke-opacity=".35" stroke-width="5" class="fp-halo"/>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="#0D0E12" stroke="url(#fswr)" stroke-width="2.6"/></g></g>
+  <text x="130.27714285714285" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#3AA8FF" textLength="36.9" lengthAdjust="spacingAndGlyphs">Port</text></svg>

docs/showcase/demo-library.yaml

@@ -0,0 +1,64 @@
+# The demo library for the docs screenshots and the demo tour (built by scripts/showcase/demo_home.py into an
+# isolated FRAMEPORT_HOME; see docs/SHOWCASE.md). Real catalog games, so recipes, patches and store art are the
+# ones FramePort really uses; the technical analysis of each (engine, XR API, libraries, sizes) is in
+# demo-analyses.json, exported from real APK analyses without any paths. Nothing here is anyone's own data.
+#
+# Per game:
+#   frame:   on the pretend Frame: internal | sd | outdated (internal, but an older build: "Update on Frame");
+#            left out = not installed
+#   played:  last played, days before the render (the Library sorts the "On your Frame" shelf by it)
+#   added:   added to the library, days before the render (default 30)
+#   tested:  the last launch test passed (default: when installed)
+#   tags:    user tags (store genres become tags by themselves)
+#   title:   overrides the catalog/store title
+#   art:     pick = the art a user gets from Find artwork's Meta result (when the store's own art is a placeholder)
+
+frame:
+  battery: 82                       # %
+  running: com.StressLevelZero.BONELAB   # the game the Monitor tab and the sidebar's live card show (it needs
+                                         # store screenshots: Take screenshot adds one of it)
+
+games:
+  - package: com.camouflaj.manta
+    frame: internal
+    played: 0.6
+    tags: [Favorites]
+  - package: com.Sanzaru.Wrath2
+    art: pick       # the store's image service has a placeholder cover for it: use the picker's Meta result
+    frame: sd
+    played: 1.2
+    tags: [Favorites]
+  - package: com.twistedpixelgames.PILO
+    frame: internal
+    played: 2.4
+  - package: com.StressLevelZero.BONELAB
+    frame: internal
+    played: 0.05
+  - package: com.vertigogames.ImpactDevelopment
+    frame: outdated
+    played: 4.5
+  - package: com.CyanWorlds.Myst
+    frame: sd
+    played: 6
+  - package: com.playful.LuckysTale
+    frame: internal
+    played: 9
+    tags: [Favorites]
+  - package: com.FuturLab.PowerWashSimulator
+    frame: internal
+    played: 12
+  - package: com.CyanWorlds.Riven
+    added: 2
+  - package: com.FireproofStudios.TheRoomVR
+  - package: com.NewFolderGames.IAmCat
+  - package: com.BithellGames.Arcsmith
+  - package: com.zenstudios.PFXVRQuest
+  - package: com.Ubisoft.ACNexusVR
+  - package: com.Solfar.InDeath
+  - package: com.survios.Creed
+  - package: com.crytek.climb2
+  - package: com.thunderful.legobricktales
+  - package: com.GhostlyBirdGames.BattleGlide
+  - package: cn.vr4p.oculus4xvrplayerov
+  - package: rift.rick_and_morty_virtual_rick_ality
+    added: 5

docs/showcase/shots.yaml

@@ -0,0 +1,109 @@
+# The docs screenshots: scripts/showcase/render_docs.py renders each into docs/images/<name>.png from the demo
+# library (demo-library.yaml) with a pretend Frame, and rewrites a file only when the picture really changed.
+# Steps: see scripts/showcase/steps.py. Each shot starts in a fresh window (its own app session).
+#
+#   viewport: [w, h]   browser size in px (default below); scale: UI scale (1.0)
+#   crop:     {dialog: true, pad}: the open dialog; {anchor: <name>, left, top, width, height}: a box placed
+#             relative to the top-left corner of the element called <name> (left/top may be negative);
+#             or {x, y, width, height} in page px
+#   docs:     where the image is used (checked by the tests: every image a doc shows has an entry here)
+
+vars:
+  game: com.camouflaj.manta          # installed on the pretend Frame
+  new_game: com.CyanWorlds.Riven     # in the library, not installed yet
+
+defaults:
+  viewport: [1280, 820]
+
+shots:
+  - name: library
+    docs: [README.md]
+    steps:
+      - go: library
+      - wait_for: "On your Frame"
+      - settle: true
+
+  - name: game
+    docs: [docs/INSTALL.md, docs/SHOWCASE.md]
+    viewport: [1280, 1100]
+    steps:
+      - open_game: ${game}
+      - wait_for: "Where it's installed"
+
+  - name: game-settings
+    docs: [docs/INSTALL.md]
+    steps:
+      - open_game: ${game}
+      - call: {fn: settings_dialog, args: ["${game}"]}
+      - wait_for: "Game settings"
+    crop: {dialog: true}
+
+  - name: patches
+    docs: [docs/COMPATIBILITY.md]
+    viewport: [1280, 2600]
+    steps:
+      - open_game: {package: "${game}", advanced: true}
+      - wait_for: "What FramePort will do"
+    crop: {anchor: "What FramePort will do", left: -32, top: -12, width: 1044, height: 820}
+
+  - name: frame
+    docs: [docs/COMPATIBILITY.md]
+    steps:
+      - go: frame
+      - wait_for: "Ready to play"
+
+  - name: files
+    docs: [docs/COMPATIBILITY.md]
+    steps:
+      - go: files
+      - wait_for: "Upload files…"
+      - wait: 1.0
+      - hook: {name: select_files, args: [1, 2]}
+
+  - name: screenshots
+    docs: [README.md]
+    steps:
+      - go: screenshots
+      - wait_for: "Take screenshot"
+
+  - name: screenshot-viewer
+    docs: [README.md]
+    steps:
+      - go: screenshots
+      - wait_for: "Take screenshot"
+      - wait: 1.5
+      - call: {fn: screenshots_view.viewer, args: [0]}
+      - wait_for: "Close"
+
+  - name: type-on-frame
+    docs: [README.md]
+    steps:
+      - hook: type_tab
+      - wait_for: "Keyboard connected"
+
+  - name: monitor
+    docs: [README.md]
+    viewport: [1280, 1150]
+    steps:
+      - go: monitor
+      - wait_for: "Processes"
+
+  # newer screens (docs/SHOWCASE.md's gallery; the README picks what it needs)
+  - name: live-view        # idle: a running stream shows its relay's random port and the data rate (no stable picture)
+    docs: [docs/SHOWCASE.md]
+    steps:
+      - go: live
+      - wait_for: "What the player sees"
+
+  - name: install-progress
+    docs: [docs/SHOWCASE.md]
+    steps:
+      - hook: {name: held_install, args: ["${new_game}"]}
+      - open_game: ${new_game}
+      - wait_for: "Cancel"
+
+  - name: appearance
+    docs: [docs/SHOWCASE.md]
+    steps:
+      - go: settings
+      - wait_for: "Portal (OLED)"

docs/showcase/videos/install.yaml

@@ -0,0 +1,125 @@
+# The install tutorial: from the download to the first game on the Steam Frame (docs/INSTALL.md links it; every
+# release attaches it as FramePort-install.mp4). FramePort starts as on a new computer (the "fresh" demo profile:
+# empty library, welcome screen, no Frame set up); what happens outside FramePort (the download, a command typed
+# on the Frame) is told on instruction cards. Recorded by scripts/showcase/record_video.py; the format is in
+# docs/SHOWCASE.md ("Videos").
+
+output: docs/media/frameport-install.mp4
+budget_mb: 12
+poster_at: 9
+start:
+  profile: fresh           # FramePort's first start
+  frame: disconnected      # the Frame isn't set up yet
+  route: welcome
+setup:
+  - hook: {name: first_run, args: ["D:/Games", 1.4]}   # the tool download and the folder scan, at a watchable pace
+
+vars:
+  game: com.playful.LuckysTale
+
+title:
+  heading: Installing FramePort
+  line: From the download to your first game on the Steam Frame
+  seconds: 3.4
+end:
+  heading: You're set
+  line: Your game is in the Frame's Steam library. More help in docs/INSTALL.md
+  footer: github.com/spoopyghosty0/frameport
+  seconds: 4.0
+
+scenes:
+  - name: download
+    seconds: 7.5
+    card:
+      eyebrow: "Step 1 · On your computer"
+      heading: Download FramePort
+      steps:
+        - "Open **github.com/spoopyghosty0/frameport** → **Releases** → the latest one"
+        - "Download the archive for your computer: **FramePort-windows-x64.zip**, **FramePort-macos-arm64.zip** or **FramePort-linux-x64.tar.gz**"
+        - "Extract it anywhere. There's no installer and no admin rights are needed"
+
+  - name: first-start
+    seconds: 7.5
+    card:
+      eyebrow: "Step 2 · First start"
+      heading: Start FramePort
+      steps:
+        - "**Windows:** open **FramePort.exe**. At “Windows protected your PC” choose **More info** → **Run anyway**"
+        - "**macOS:** right-click **FramePort.app** → **Open** → **Open**"
+        - "**Linux:** run **FramePort/FramePort**"
+      note: "FramePort is signed with a free certificate, so your system asks once."
+
+  - name: welcome
+    caption: ["FramePort gets itself ready", "It downloads the tools it uses (Java, OVRPort, apksigner) by itself"]
+    hold: 1.0
+    steps:
+      - wait: 1.0
+      - hook: {name: wait_jobs, args: [40]}
+      - wait_for: "Java, OVRPort and apksigner are ready."
+      - wait: 1.0
+
+  - name: connect
+    caption: ["Connect your Steam Frame", "Once: FramePort shows a command to run on the Frame"]
+    hold: 1.5
+    steps:
+      - click: "Set up the Frame"
+      - wait: 1.6
+      - click: "Show setup command"
+      - wait_for: "Waiting for your Frame"
+      - wait: 1.0
+      - hover: "Copy"
+      - wait: 1.4
+
+  - name: on-the-frame
+    seconds: 10
+    card:
+      eyebrow: "Step 3 · On the Frame, first time only"
+      heading: Run the setup command
+      steps:
+        - "In the SteamVR dashboard: **Launch a program** → **Desktop**"
+        - "Open the app menu (bottom left) → **System** → **Konsole**"
+        - "Type the command FramePort shows and press **Enter**"
+      code: "curl -fsS <your-PC-address>:8765/<one-time-code> | bash"
+      note: "FramePort shows your PC's address and a one-time code in place of **<…>**. The desktop closes by itself after a few seconds (Steam restarts once); if Steam asks to install **Lepton**, confirm it. No password is needed."
+
+  - name: connected
+    caption: ["Your Frame is connected", "From now on FramePort finds it by itself"]
+    hold: 1.2
+    steps:
+      - hook: {name: pairing_done, args: [1.6]}
+      - wait_for: "Ready to play"
+      - wait: 1.2
+      - hover: "Quest games (Lepton)"
+      - wait: 1.6
+
+  - name: add-games
+    caption: ["Add your games", "Point FramePort at the folder with your games"]
+    hold: 1.0
+    steps:
+      - nav: "Library"
+      - wait: 1.2
+      - click: "Scan a folder…"
+      - hook: {name: wait_jobs, args: [40]}
+      - wait: 1.2
+      - hover: {name: "Lucky's Tale", dy: 0.3}
+      - wait: 1.0
+
+  - name: install
+    caption: ["Install a game", "FramePort patches it, installs it and adds it to the Frame's Steam library"]
+    hold: 1.2
+    steps:
+      - click: {name: "Lucky's Tale", dy: 0.35}   # (the title: the card's middle is its Install button)
+      - wait_for: "Where it's installed"           # (the game page: a click that missed fails here)
+      - wait: 1.2
+      - click: "Install on Frame"
+      - wait: 0.6
+      - move: [860, 640]
+      - hook: {name: wait_jobs, args: [45]}
+      - wait: 1.0
+
+  - name: play
+    caption: ["Play", "Start it from FramePort, or from Steam in the headset"]
+    steps:
+      - click: "Play on Frame"
+      - wait: 2.6
+      - park: true

docs/showcase/videos/tour.yaml

@@ -0,0 +1,134 @@
+# The demo tour: FramePort in use (README teaser, docs/media, every release as FramePort-tour.mp4).
+# Recorded by scripts/showcase/record_video.py; the storyboard format is in docs/SHOWCASE.md ("Videos").
+
+output: docs/media/frameport-tour.mp4
+teaser: docs/images/tour-teaser.webp
+budget_mb: 12
+start:
+  profile: demo           # the library in use: games installed on the pretend Frame, BONELAB running
+  frame: connected
+
+vars:
+  game: com.camouflaj.manta        # installed on the pretend Frame
+  new_game: com.CyanWorlds.Riven   # installed during the tour
+
+title:
+  heading: FramePort
+  line: Quest, Android and PC VR games on the Steam Frame
+  seconds: 3.2
+end:
+  heading: FramePort
+  line: Open source · bring your own games
+  footer: github.com/spoopyghosty0/frameport
+  seconds: 3.6
+
+scenes:
+  - name: library
+    caption: ["Your library, ready for the Frame", "Quest, Android and PC VR games from your own folders"]
+    teaser: [0.8, 3.2]
+    steps:
+      - go: library
+      - wait: 1.2
+      - hover: {name: "Batman: Arkham Shadow", dy: 0.3}
+      - wait: 1.0
+      - hover: {name: "Marvel's Deadpool VR", dy: 0.3}
+      - wait: 0.8
+      - hover: "Assassin's Creed Nexus"
+      - wait: 0.8
+      - hover: "Lucky's Tale"
+      - wait: 0.8
+      - park: true
+      - type: "ri"
+      - wait: 1.6
+
+  - name: game
+    caption: ["Every game gets its own recipe", "Known-good fixes from the catalog, or suggested from the game itself"]
+    steps:
+      - click: {name: "Riven", dy: 0.35}   # (the title: the card's middle is its Install button)
+      - wait: 1.8
+      - hover: "Works"
+      - wait: 0.7
+      - scroll: {dy: 420, at: [860, 560]}
+      - wait: 1.2
+      - scroll: {dy: -420, at: [860, 560]}
+      - wait: 0.5
+
+  - name: install
+    caption: ["One click to install", "Patched, signed, uploaded, added to Steam and launch-tested"]
+    teaser: [0.6, 4.0]
+    hold: 1.2
+    steps:
+      - click: "Install on Frame"
+      - wait: 0.6
+      - move: [860, 640]
+      - hook: {name: wait_jobs, args: [45]}
+      - wait: 1.0
+
+  - name: play
+    caption: ["Play from your PC", "Starts the game in the headset through Steam"]
+    teaser: [4.3, 3.2]
+    steps:
+      - nav: "Library"
+      - call: library_view.clear_search
+      - wait: 1.4
+      - hover: {name: "Asgard's Wrath 2", dy: 0.3}
+      - wait: 0.6
+      - hover: {name: "Batman: Arkham Shadow", dy: 0.3}
+      - wait: 0.6
+      - click: {name: "Play on Frame", nth: 0}
+      - wait: 2.6
+      - park: true
+      - wait: 0.4
+
+  - name: monitor
+    caption: ["See what the Frame is doing", "Frame rate, CPU, GPU, temperatures and every process, live"]
+    teaser: [0.5, 2.6]
+    steps:
+      - nav: "Monitor"
+      - wait: 2.4
+      - hover: "Temperature"   # (a tile only: "GPU" is also the process table's sortable column)
+      - wait: 1.0
+      - hover: "Battery"
+      - wait: 1.0
+      - click: "Show details"
+      - wait: 1.8
+      - park: true
+
+  - name: screenshots
+    caption: ["Screenshots from the headset", "Take one from the PC, then view or download them"]
+    steps:
+      - nav: "Screenshots"
+      - wait: 1.6
+      - click: "Take screenshot"
+      - wait_for: "BONELAB · 2026-10-04 21:50"
+      - wait: 0.8
+      - click: "BONELAB · 2026-10-04 21:50"
+      - wait: 2.0
+      - click: "Close"
+      - wait: 0.4
+
+  - name: files
+    caption: ["Files on the Frame", "Videos, mods and saves: upload, download, select with a drag"]
+    steps:
+      - nav: "Files"
+      - wait: 1.6
+      - drag: ["Concert 8K 3D.mp4", "Mars landing (VR180).mkv"]
+      - wait: 1.0
+      - right_click: "Earth from orbit (360).mp4"
+      - wait: 1.4
+      - press: Escape
+      - wait: 0.6
+
+  - name: themes
+    caption: ["Make it yours", "Dark themes, including true black for OLED screens"]
+    steps:
+      - nav: "Settings"
+      - wait: 1.4
+      - click: "Portal (OLED)"
+      - wait: 1.4
+      - click: "Original"
+      - wait: 1.4
+      - click: "Portal"
+      - wait: 1.0
+      - nav: "Library"
+      - wait: 1.4

docs/themes/example-theme.json

@@ -0,0 +1,13 @@
+{
+  "name": "Ember & Ice",
+  "base": "portal",
+  "dual": true,
+  "colors": {
+    "ACCENT": "#FF5A36",
+    "ACCENT_SOFT": "#3A1710",
+    "SECONDARY": "#5CE1E6",
+    "SECONDARY_SOFT": "#0E3033",
+    "PC": "#5CE1E6",
+    "INFO": "#5CE1E6"
+  }
+}

native/README.md

@@ -11,14 +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`. Host-tested against a stand-in loader (`tests/test_langpack.py`, plain `cc`, no NDK); the bionic/headset side is unverified. |
+| `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/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).
 //
@@ -86,9 +89,22 @@ 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;  // clamp submitted image rects to their swapchain (SteamVR rejects a 1 px overrun)
+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;
@@ -112,9 +128,11 @@ static int controller_models;  // serve Frame controller models via XR_FB_render
 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 float focus_hold_ms = 1000;  // longest focus dip focus_hold hides
+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)
@@ -135,9 +153,13 @@ static void read_settings(const char *path) {
         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;
@@ -153,6 +175,7 @@ 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;
@@ -161,6 +184,7 @@ static void read_settings(const char *path) {
         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;
@@ -207,11 +231,18 @@ 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);
@@ -269,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) {
@@ -297,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");
@@ -305,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.
@@ -472,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);
@@ -483,6 +536,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
         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;
@@ -506,6 +560,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
         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;
 }
@@ -513,10 +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);
 }
@@ -766,15 +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);
@@ -785,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");
@@ -794,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");
@@ -809,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;
 }
 
@@ -912,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);
@@ -959,9 +1189,40 @@ 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;
@@ -978,6 +1239,18 @@ 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),
@@ -1111,6 +1384,48 @@ 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
@@ -1273,6 +1588,7 @@ 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)";
@@ -1389,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)
@@ -1404,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)
@@ -1420,15 +1738,26 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
     }
     if (surface_emul) HOOK_AS(xrCreateSwapchainAndroidSurfaceKHR, hook_xrCreateSwapchainAndroidSurfaceKHR)
     if (eye_debug || release_wait) HOOK_AS(xrReleaseSwapchainImage, eye_hook_xrReleaseSwapchainImage)
-    if (sync_guard || layer_debug) HOOK_AS(xrSyncActions, hook_xrSyncActions)
+    if (layer_debug) {  // 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)
+    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);
 }
 

native/adapter/input_diag.c

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Included by frame_adapter.c (before session_fixes.c). input_diag: controller-input diagnostics, off by default and
+// hooked only when on; logs only, never changes what the game or the runtime sees. Each distinct line is logged once:
+//  * every interaction profile the game suggests bindings for, with the runtime's answer; a rejected profile lists
+//    all its binding paths ("unsupported: interaction profile ...");
+//  * the profile the runtime reports for each hand (xrGetCurrentInteractionProfile, before controller_fix rewrites
+//    the answer for the game): a game without a Steam Frame binding gets SteamVR's Touch remap, so this shows
+//    whether the game's input runs through it;
+//  * functions the game looks up that the runtime doesn't provide ("unsupported: function ...");
+//  * failing input, haptics and performance calls with the result name and the argument that failed.
+
+#define DIAG_MAX 512
+#define DIAG_KEY (2 * XR_MAX_PATH_LENGTH + 32)
+static uint64_t diag_seen[DIAG_MAX];  // FNV-1a hashes of the keys already logged
+static int diag_count;
+static pthread_mutex_t diag_lock = PTHREAD_MUTEX_INITIALIZER;
+
+static int diag_first(const char *key) {  // 1 the first time `key` is seen; 0 for everything after DIAG_MAX keys
+    uint64_t hash = 14695981039346656037ull;
+    for (const unsigned char *c = (const unsigned char *)key; *c; ++c) hash = (hash ^ *c) * 1099511628211ull;
+    pthread_mutex_lock(&diag_lock);
+    int first = 1;
+    for (int i = 0; i < diag_count && first; ++i) first = diag_seen[i] != hash;
+    if (first && diag_count < DIAG_MAX) diag_seen[diag_count++] = hash;
+    else if (first) {  // full: stop rather than repeat a per-frame failure
+        static int full;
+        if (!full) { full = 1; LOG("input_diag: %d distinct findings, logging no more", DIAG_MAX); }
+        first = 0;
+    }
+    pthread_mutex_unlock(&diag_lock);
+    return first;
+}
+
+static const char *diag_result_name(XrResult result, char *buf, size_t size) {
+    PFN_xrResultToString fn =
+        active_instance ? (PFN_xrResultToString)lookup(active_instance, "xrResultToString") : NULL;
+    char name[XR_MAX_RESULT_STRING_SIZE];
+    if (fn && XR_SUCCEEDED(fn(active_instance, result, name))) snprintf(buf, size, "%s", name);
+    else snprintf(buf, size, "%d", result);
+    return buf;
+}
+
+static void diag_call_failed(const char *fn, XrResult result, const char *detail) {
+    char key[DIAG_KEY], name[XR_MAX_RESULT_STRING_SIZE];
+    snprintf(key, sizeof(key), "%s:%d:%s", fn, result, detail ? detail : "");
+    if (diag_first(key))
+        LOG("input_diag: unsupported: %s -> %s%s%s", fn, diag_result_name(result, name, sizeof(name)),
+            detail ? " " : "", detail ? detail : "");
+}
+
+// Called by hook_xrSuggestInteractionProfileBindings with the runtime's answer to the game's own suggestion (before
+// profile_remap suggests it again for Touch).
+static void input_diag_suggested(XrInstance instance, const XrInteractionProfileSuggestedBinding *suggested,
+                                 XrResult result, PFN_xrPathToString to_string) {
+    if (!input_diag || !suggested || !to_string) return;
+    char profile[XR_MAX_PATH_LENGTH] = "?", key[DIAG_KEY], name[XR_MAX_RESULT_STRING_SIZE];
+    uint32_t size = 0;
+    to_string(instance, suggested->interactionProfile, sizeof(profile), &size, profile);
+    snprintf(key, sizeof(key), "suggest:%s:%d", profile, result);
+    if (!diag_first(key)) return;
+    if (XR_SUCCEEDED(result)) {
+        LOG("input_diag: bindings: %s accepted (%u paths)", profile, suggested->countSuggestedBindings);
+        return;
+    }
+    LOG("input_diag: unsupported: interaction profile %s -> %s (%u bindings):", profile,
+        diag_result_name(result, name, sizeof(name)), suggested->countSuggestedBindings);
+    for (uint32_t i = 0; i < suggested->countSuggestedBindings; ++i) {
+        char path[XR_MAX_PATH_LENGTH];
+        if (XR_SUCCEEDED(to_string(instance, suggested->suggestedBindings[i].binding, sizeof(path), &size, path)))
+            LOG("input_diag:   %s", path);
+    }
+}
+
+// Called by xrGetCurrentInteractionProfile with the runtime's answer.
+static void input_diag_current_profile(XrPath user, XrPath profile) {
+    PFN_xrPathToString to_string =
+        active_instance ? (PFN_xrPathToString)lookup(active_instance, "xrPathToString") : NULL;
+    if (!input_diag || !to_string) return;
+    char u[XR_MAX_PATH_LENGTH] = "?", p[XR_MAX_PATH_LENGTH] = "none", key[DIAG_KEY];
+    uint32_t size = 0;
+    to_string(active_instance, user, sizeof(u), &size, u);
+    if (profile) to_string(active_instance, profile, sizeof(p), &size, p);
+    snprintf(key, sizeof(key), "current:%s:%s", u, p);
+    if (diag_first(key)) LOG("input_diag: bindings: %s uses %s", u, p);
+}
+
+// ---------------------------------------------------------------- failing calls
+// xrSyncActions and xrSuggestInteractionProfileBindings are reported from session_fixes.c's hooks,
+// xrApplyHapticFeedback from frame_adapter.c's (always hooked for haptic_scale).
+#define DIAG_CHECKED(name, params, args, detail)                                                                    \
+    static XRAPI_ATTR XrResult XRAPI_CALL diag_##name params {                                                     \
+        PFN_##name fn = (PFN_##name)lookup(active_instance, #name);                                                \
+        if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;                                                             \
+        XrResult result = fn args;                                                                                 \
+        if (XR_FAILED(result)) diag_call_failed(#name, result, detail);                                            \
+        return result;                                                                                             \
+    }
+static const char *diag_name_detail(const char *name) {
+    static __thread char buf[XR_MAX_PATH_LENGTH + 8];
+    snprintf(buf, sizeof(buf), "(%s)", name ? name : "null");
+    return buf;
+}
+static const char *diag_perf_detail(XrPerfSettingsDomainEXT domain, XrPerfSettingsLevelEXT level) {
+    static __thread char buf[64];
+    snprintf(buf, sizeof(buf), "(domain %d level %d)", (int)domain, (int)level);
+    return buf;
+}
+DIAG_CHECKED(xrStringToPath, (XrInstance instance, const char *path, XrPath *out), (instance, path, out),
+             diag_name_detail(path))
+DIAG_CHECKED(xrCreateAction, (XrActionSet set, const XrActionCreateInfo *info, XrAction *action), (set, info, action),
+             diag_name_detail(info ? info->actionName : NULL))
+DIAG_CHECKED(xrAttachSessionActionSets, (XrSession session, const XrSessionActionSetsAttachInfo *info),
+             (session, info), NULL)
+DIAG_CHECKED(xrPerfSettingsSetPerformanceLevelEXT,
+             (XrSession session, XrPerfSettingsDomainEXT domain, XrPerfSettingsLevelEXT level),
+             (session, domain, level), diag_perf_detail(domain, level))
+#undef DIAG_CHECKED
+
+// xrGetInstanceProcAddr: our wrapper for `name`, NULL if it isn't one of ours.
+static PFN_xrVoidFunction input_diag_hook(const char *name) {
+#define DIAG(fn) if (!strcmp(name, #fn)) return (PFN_xrVoidFunction)diag_##fn;
+    DIAG(xrStringToPath)
+    DIAG(xrCreateAction)
+    DIAG(xrAttachSessionActionSets)
+    DIAG(xrPerfSettingsSetPerformanceLevelEXT)
+#undef DIAG
+    return NULL;
+}
+
+// After the runtime's own lookup: a function the game asked for that the runtime doesn't provide.
+static void input_diag_lookup(XrInstance instance, const char *name, XrResult result, PFN_xrVoidFunction fn) {
+    if (!input_diag || instance == XR_NULL_HANDLE || (XR_SUCCEEDED(result) && fn)) return;
+    char key[DIAG_KEY], rname[XR_MAX_RESULT_STRING_SIZE];
+    snprintf(key, sizeof(key), "fn:%s", name);
+    if (diag_first(key))
+        LOG("input_diag: unsupported: function %s not provided by the runtime (%s)", name,
+            diag_result_name(result, rname, sizeof(rname)));
+}

native/adapter/session_fixes.c

@@ -110,11 +110,12 @@ static int input_syncs, input_sync_ok, input_bool_reads, input_bool_true, input_
 static XRAPI_ATTR XrResult XRAPI_CALL hook_xrSyncActions(XrSession session, const XrActionsSyncInfo *info) {
     PFN_xrSyncActions fn = (PFN_xrSyncActions)lookup(active_instance, "xrSyncActions");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
-    if (!sync_guard) {  // installed for layer_debug only: count
+    if (!sync_guard) {  // installed for layer_debug / input_diag only: count, report failures
         XrResult r = fn(session, info);
         __atomic_add_fetch(&input_syncs, 1, __ATOMIC_RELAXED);
         if (r == XR_SUCCESS) __atomic_add_fetch(&input_sync_ok, 1, __ATOMIC_RELAXED);
         input_last_sync_result = r;
+        if (input_diag && XR_FAILED(r)) diag_call_failed("xrSyncActions", r, NULL);
         return r;
     }
     pthread_mutex_lock(&sync_lock);
@@ -123,6 +124,7 @@ static XRAPI_ATTR XrResult XRAPI_CALL hook_xrSyncActions(XrSession session, cons
     pthread_mutex_unlock(&sync_lock);
     static int logged;
     if (wait > 0 && logged++ < 5) LOG("sync_guard: input paused for %.0f ms after focus returned", wait / 1e6);
+    if (input_diag && XR_FAILED(r)) diag_call_failed("xrSyncActions", r, NULL);
     return r;
 }
 
@@ -140,7 +142,7 @@ static XRAPI_ATTR XrResult XRAPI_CALL hook_xrGetActionStateBoolean(XrSession ses
 // ---------------------------------------------------------------- focus_hold
 #define FOCUS_HOLD_MIN_FOCUSED_NS 1000000000ll  // only after this long in FOCUSED (start-up transitions untouched;
                                                 // 3 s let a 27 ms dip through in Blade & Sorcery)
-// dips longer than focus_hold_ms (setting, default 1000) are delivered (late, in order): taking the headset off or the
+// dips longer than focus_hold_ms (setting, default 5000) are delivered (late, in order): taking the headset off or the
 // system menu must still pause the game. A longer limit is for headsets whose wear sensor flickers ("HMD off" for
 // 0.5-2 s while worn; Blade & Sorcery pauses on each)
 #define FOCUS_HOLD_MAX_DIP_NS ((int64_t)(focus_hold_ms * 1000000.0f))
@@ -324,6 +326,7 @@ static XRAPI_ATTR XrResult XRAPI_CALL hook_xrSuggestInteractionProfileBindings(X
                 note_pose_binding(suggested->suggestedBindings[i].action, path);
         }
     XrResult r = fn(instance, suggested);
+    input_diag_suggested(instance, suggested, r, to_string);  // the runtime's answer to the game's own suggestion
     if (!profile_remap || !suggested || !to_string) return r;
     char profile[XR_MAX_PATH_LENGTH] = {0};
     uint32_t size = 0;

native/adapter/snapshot_gl.c

@@ -0,0 +1,173 @@
+// FramePort FrameBridge: eye-image snapshots for headless diagnostics (setting snapshot=<seconds>, GLES games only).
+// Every <seconds>, at xrEndFrame, the left-eye image the game just submitted (projection layer, view 0: its swapchain
+// image and array layer) is read back on the game's own GL context and written at a quarter of its size as
+// /sdcard/Android/data/<package>/files/fb_snap_<n>.ppm (n = 0-7, the oldest is overwritten). Nobody wears the headset
+// in a launch test, so the headset view stays black: this shows what the game itself draws (e.g. which screen it is
+// stuck on). The game's framebuffer, pack-buffer and pack-alignment bindings are restored afterwards.
+#define SNAP_MAX_SWAPCHAINS 16
+#define SNAP_MAX_IMAGES 8
+#define SNAP_SCALE 4
+
+
+#define SNAP_GL_FUNCS(X) X(glGenFramebuffers) X(glDeleteFramebuffers) X(glBindFramebuffer) X(glFramebufferTexture2D) \
+    X(glFramebufferTextureLayer) X(glCheckFramebufferStatus) X(glReadPixels) X(glGetIntegerv) X(glPixelStorei) \
+    X(glBindBuffer) X(glGetError)
+#define SNAP_DECLARE(fn) static __typeof__(&fn) s_##fn;
+SNAP_GL_FUNCS(SNAP_DECLARE)
+#undef SNAP_DECLARE
+static EGLContext (*s_eglGetCurrentContext)(void);
+
+static struct {
+    XrSwapchain handle;
+    uint32_t width, height, array_size, count, last_acquired;
+    GLuint images[SNAP_MAX_IMAGES];
+} snap_chains[SNAP_MAX_SWAPCHAINS];
+static pthread_mutex_t snap_lock = PTHREAD_MUTEX_INITIALIZER;
+
+static int snap_load_gl(void) {
+    static int state;  // 0 untried, 1 ok, -1 failed
+    if (state) return state > 0;
+    void *egl = dlopen("libEGL.so", RTLD_NOW | RTLD_LOCAL), *gles = dlopen("libGLESv3.so", RTLD_NOW | RTLD_LOCAL);
+    int ok = egl && gles;
+    if (ok) s_eglGetCurrentContext = (EGLContext (*)(void))dlsym(egl, "eglGetCurrentContext");
+#define SNAP_RESOLVE(fn) ok &= gles && (s_##fn = (__typeof__(s_##fn))dlsym(gles, #fn)) != NULL;
+    SNAP_GL_FUNCS(SNAP_RESOLVE)
+#undef SNAP_RESOLVE
+    state = ok && s_eglGetCurrentContext ? 1 : -1;
+    if (state < 0) LOG("snapshot: OpenGL ES not available, no snapshots");
+    return state > 0;
+}
+
+static int snap_find(XrSwapchain handle, int create) {
+    for (int i = 0; i < SNAP_MAX_SWAPCHAINS; ++i)
+        if (snap_chains[i].handle == handle) return i;
+    if (!create) return -1;
+    for (int i = 0; i < SNAP_MAX_SWAPCHAINS; ++i)
+        if (!snap_chains[i].handle) { snap_chains[i].handle = handle; snap_chains[i].count = 0; return i; }
+    return -1;
+}
+
+static void snap_on_create(XrSwapchain handle, const XrSwapchainCreateInfo *info) {
+    if (!snapshot || !info) return;
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(handle, 1);
+    if (i >= 0) {
+        snap_chains[i].width = info->width;
+        snap_chains[i].height = info->height;
+        snap_chains[i].array_size = info->arraySize ? info->arraySize : 1;
+    }
+    pthread_mutex_unlock(&snap_lock);
+}
+
+static void snap_on_destroy(XrSwapchain handle) {
+    if (!snapshot) return;
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(handle, 0);
+    if (i >= 0) snap_chains[i].handle = XR_NULL_HANDLE;
+    pthread_mutex_unlock(&snap_lock);
+}
+
+static void snap_on_enumerate(XrSwapchain handle, uint32_t count, const XrSwapchainImageBaseHeader *images) {
+    if (!snapshot || !images || !count || images->type != (XrStructureType)1000024002) return;  // OPENGL_ES_KHR
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(handle, 1);
+    if (i >= 0) {
+        uint32_t n = count < SNAP_MAX_IMAGES ? count : SNAP_MAX_IMAGES;
+        const emul_gles_image *gl = (const emul_gles_image *)images;
+        for (uint32_t k = 0; k < n; ++k) snap_chains[i].images[k] = gl[k].image;
+        snap_chains[i].count = n;
+    }
+    pthread_mutex_unlock(&snap_lock);
+}
+
+static void snap_on_acquire(XrSwapchain handle, uint32_t index) {
+    if (!snapshot) return;
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(handle, 0);
+    if (i >= 0) snap_chains[i].last_acquired = index;
+    pthread_mutex_unlock(&snap_lock);
+}
+
+static void snap_write(const unsigned char *rgba, uint32_t w, uint32_t h, int n) {
+    char path[320];
+    snprintf(path, sizeof(path), "%s/fb_snap_%d.ppm", snap_dir, n);
+    FILE *f = fopen(path, "wb");
+    if (!f) { LOG("snapshot: can't write %s", path); return; }
+    uint32_t ow = w / SNAP_SCALE, oh = h / SNAP_SCALE;
+    fprintf(f, "P6\n%u %u\n255\n", ow, oh);
+    unsigned char *row = malloc((size_t)ow * 3);
+    for (uint32_t y = 0; row && y < oh; ++y) {
+        const unsigned char *src = rgba + (size_t)(h - 1 - y * SNAP_SCALE) * w * 4;  // GL rows are bottom-up
+        for (uint32_t x = 0; x < ow; ++x) {
+            const unsigned char *p = src + (size_t)x * SNAP_SCALE * 4;
+            row[x * 3] = p[0], row[x * 3 + 1] = p[1], row[x * 3 + 2] = p[2];
+        }
+        fwrite(row, 1, (size_t)ow * 3, f);
+    }
+    free(row);
+    fclose(f);
+    LOG("snapshot: %s (%ux%u)", path, ow, oh);
+}
+
+static void snap_end_frame(const XrFrameEndInfo *info) {
+    if (!snapshot || !*snap_dir || !info) return;
+    static int64_t next_ns;
+    static int taken;
+    struct timespec now;
+    clock_gettime(CLOCK_MONOTONIC, &now);
+    int64_t t = (int64_t)now.tv_sec * 1000000000ll + now.tv_nsec;
+    if (t < next_ns) return;
+    next_ns = t + (int64_t)snapshot * 1000000000ll;
+    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)
+            proj = (const XrCompositionLayerProjection *)info->layers[i];
+    if (!proj || !snap_load_gl()) return;
+    if (!s_eglGetCurrentContext()) {
+        static int logged;
+        if (!logged++) LOG("snapshot: no GL context current in xrEndFrame, no snapshot");
+        return;
+    }
+    const XrSwapchainSubImage *sub = &proj->views[0].subImage;
+    pthread_mutex_lock(&snap_lock);
+    int i = snap_find(sub->swapchain, 0);
+    GLuint tex = 0;
+    uint32_t w = 0, h = 0, array_size = 1;
+    if (i >= 0 && snap_chains[i].count && snap_chains[i].last_acquired < snap_chains[i].count) {
+        tex = snap_chains[i].images[snap_chains[i].last_acquired];
+        w = snap_chains[i].width, h = snap_chains[i].height, array_size = snap_chains[i].array_size;
+    }
+    pthread_mutex_unlock(&snap_lock);
+    if (!tex || !w || !h) return;
+    GLint read_fb = 0, pack_buffer = 0, pack_alignment = 4;
+    s_glGetIntegerv(GL_READ_FRAMEBUFFER_BINDING, &read_fb);
+    s_glGetIntegerv(GL_PIXEL_PACK_BUFFER_BINDING, &pack_buffer);
+    s_glGetIntegerv(GL_PACK_ALIGNMENT, &pack_alignment);
+    GLuint fb = 0;
+    s_glGenFramebuffers(1, &fb);
+    s_glBindFramebuffer(GL_READ_FRAMEBUFFER, fb);
+    if (array_size > 1)
+        s_glFramebufferTextureLayer(GL_READ_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, tex, 0, (GLint)sub->imageArrayIndex);
+    else
+        s_glFramebufferTexture2D(GL_READ_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, tex, 0);
+    unsigned char *rgba = NULL;
+    if (s_glCheckFramebufferStatus(GL_READ_FRAMEBUFFER) == GL_FRAMEBUFFER_COMPLETE &&
+        (rgba = malloc((size_t)w * h * 4))) {
+        s_glBindBuffer(GL_PIXEL_PACK_BUFFER, 0);
+        s_glPixelStorei(GL_PACK_ALIGNMENT, 1);
+        s_glReadPixels(0, 0, (GLsizei)w, (GLsizei)h, GL_RGBA, GL_UNSIGNED_BYTE, rgba);
+    } else {
+        static int logged;
+        if (logged++ < 3) LOG("snapshot: eye image %u not readable (framebuffer incomplete)", tex);
+    }
+    s_glPixelStorei(GL_PACK_ALIGNMENT, pack_alignment);
+    s_glBindBuffer(GL_PIXEL_PACK_BUFFER, (GLuint)pack_buffer);
+    s_glBindFramebuffer(GL_READ_FRAMEBUFFER, (GLuint)read_fb);
+    s_glDeleteFramebuffers(1, &fb);
+    while (s_glGetError() != GL_NO_ERROR) {}  // our calls must not leave errors for the game to find
+    if (rgba) {
+        snap_write(rgba, w, h, taken++ % 8);
+        free(rgba);
+    }
+}

native/build.py

@@ -7,10 +7,10 @@ Everything is fetched on demand into native/.cache (git-ignored):
   - Temurin JDK 21 (javac) and Android build-tools (d8) for the Java stub classes
 Then builds: FrameBridge adapter (arm64 + arm32), VrApi bridge, platform compat, language packs, GL shim, oculusos stub dex, the
 timefix OpenXR layer for Proton games (linux-arm64, glibc; the NDK's clang builds it freestanding), the
-OculusHMDConnected helper for Rift games under Proton (win-x64 PE; the NDK's clang + lld-link, no Windows SDK), and
-rewrites artifacts/SHA256SUMS. Run `frameport parity` afterwards to see which games change.
+OculusHMDConnected helper for Rift games under Proton (win-x64 PE; the NDK's clang + lld-link, no Windows SDK), the
+live view's hardware H.264 encoder fp_venc (linux-arm64-bin, static freestanding executable), and rewrites artifacts/SHA256SUMS. Run `frameport parity` afterwards to see which games change.
 
-    python native/build.py [--only adapter,bridge,compat,langpack,glshim,eglfmt,dex,xrlayer,oculushmd,xrshim,vkshim,ovrpshim,vrsettings] [--ndk PATH]
+    python native/build.py [--only adapter,bridge,compat,langpack,glshim,eglfmt,ovrtrace,dex,xrlayer,oculushmd,xrshim,vkshim,ovrpshim,vrsettings,venc] [--ndk PATH]
 """
 from __future__ import annotations
 
@@ -158,6 +158,32 @@ def build_xrlayer(tc: Path):
     shutil.copy(src / "XR_APILAYER_FRAMEPORT_timefix.json", out / "XR_APILAYER_FRAMEPORT_timefix.json")
 
 
+def uapi_arm64(tc: Path) -> Path:
+    """Only the kernel UAPI headers of the NDK sysroot (linux/, asm-generic/, drm/, aarch64 asm/), rebuilt every time,
+    so no bionic libc header can end up on a freestanding build's include path."""
+    inc = tc / "sysroot/usr/include"
+    dest = CACHE / "uapi-arm64"
+    shutil.rmtree(dest, ignore_errors=True)
+    for d in ("linux", "asm-generic", "drm"):
+        shutil.copytree(inc / d, dest / d)
+    shutil.copytree(inc / "aarch64-linux-android/asm", dest / "asm")
+    return dest
+
+
+def build_venc(tc: Path):
+    """fp_venc (Linux aarch64, runs on the Frame): SteamVR headset view -> V4L2 hardware H.264 encoder -> stdout, for the
+    live view. Fully static and freestanding (raw syscalls, own _start), so it needs no libc at build or run time.
+    Goes to linux-arm64-bin/, not linux-arm64/ (that folder is uploaded whole as the OpenXR layer)."""
+    src = HERE / "venc"
+    uapi = uapi_arm64(tc)
+    out = ART / "linux-arm64-bin"
+    out.mkdir(parents=True, exist_ok=True)
+    run([tc / "bin/clang", "--target=aarch64-linux-gnu", "-ffreestanding", "-nostdlib", "-nostdlibinc", "-static",
+         "-fno-stack-protector", "-fno-builtin", "-O2", "-Wall", "-Wextra", "-Werror", "-fuse-ld=lld",
+         "-Wl,--build-id=none", "-Wl,-z,max-page-size=65536", "-e", "_start", "-I", src / "include", "-I", uapi,
+         f"-ffile-prefix-map={HERE}=native", "fp_venc.c", "convert.c", "sys.c", "-o", out / "fp_venc"], cwd=src)
+
+
 OCULUSHMD_IMPORTS = ("CreateEventW", "CreateJobObjectW", "AssignProcessToJobObject", "QueryInformationJobObject",
                      "CreateProcessW", "ResumeThread", "WaitForSingleObject", "GetExitCodeProcess", "CloseHandle",
                      "Sleep", "GetCommandLineW", "GetLastError", "GetStdHandle", "WriteFile", "ExitProcess")
@@ -249,6 +275,14 @@ def build_eglfmt(tc: Path):
          "-Wl,--no-as-needed", "-lEGL", "-Wl,--as-needed", "-ldl", "-llog", "-o", ART / "arm64-v8a/libfpg.so"], cwd=src)
 
 
+def build_ovrtrace(tc: Path):
+    """Meta Platform SDK tracer (see ovrtrace/ovrtrace.c): diagnostics, the game's engine library loads it first."""
+    src = HERE / "ovrtrace"
+    run([exe(tc, "aarch64-linux-android29-clang"), "-shared", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror",
+         "-Wl,-soname,libfp_ovrtrace.so", "-Wl,-z,max-page-size=16384", "ovrtrace.c", "-ldl", "-llog",
+         "-o", ART / "arm64-v8a/libfp_ovrtrace.so"], cwd=src)
+
+
 def build_xrshim(tc: Path):
     """FrameBridge extension shim (see xrshim/xrshim.c): DT_NEEDED-injected in front of overport's libopenxr_loader.so."""
     src = HERE / "xrshim"
@@ -318,7 +352,7 @@ def write_sums():
 
 def main():
     ap = argparse.ArgumentParser()
-    ap.add_argument("--only", default="adapter,bridge,compat,langpack,glshim,eglfmt,dex,xrlayer,oculushmd,xrshim,vkshim,ovrpshim,vrsettings")
+    ap.add_argument("--only", default="adapter,bridge,compat,langpack,glshim,eglfmt,ovrtrace,dex,xrlayer,oculushmd,xrshim,vkshim,ovrpshim,vrsettings,venc")
     ap.add_argument("--ndk")
     args = ap.parse_args()
     parts = set(args.only.split(","))
@@ -327,11 +361,11 @@ def main():
     tc = clang_dir(ndk(args.ndk)) if parts - {"dex"} else None
     steps = {"adapter": lambda: build_adapter(tc), "bridge": lambda: build_bridge(tc), "compat": lambda: build_compat(tc),
              "langpack": lambda: build_langpack(tc),
-             "glshim": lambda: build_glshim(tc), "eglfmt": lambda: build_eglfmt(tc), "xrshim": lambda: build_xrshim(tc), "dex": build_dex, "xrlayer": lambda: build_xrlayer(tc),
+             "glshim": lambda: build_glshim(tc), "eglfmt": lambda: build_eglfmt(tc), "ovrtrace": lambda: build_ovrtrace(tc), "xrshim": lambda: build_xrshim(tc), "dex": build_dex, "xrlayer": lambda: build_xrlayer(tc),
              "oculushmd": lambda: build_oculushmd(tc), "vkshim": lambda: build_vkshim(tc),
              "ovrpshim": lambda: build_ovrpshim(tc),
-             "vrsettings": lambda: build_vrsettings(tc)}
-    for name in ("adapter", "bridge", "compat", "langpack", "glshim", "eglfmt", "xrshim", "vkshim", "ovrpshim", "dex", "xrlayer", "oculushmd", "vrsettings"):
+             "vrsettings": lambda: build_vrsettings(tc), "venc": lambda: build_venc(tc)}
+    for name in ("adapter", "bridge", "compat", "langpack", "glshim", "eglfmt", "ovrtrace", "xrshim", "vkshim", "ovrpshim", "dex", "xrlayer", "oculushmd", "vrsettings", "venc"):
         if name in parts:
             log(f"build {name}")
             steps[name]()

native/glshim/glshim.c

@@ -13,9 +13,14 @@
 
 #define LOG(...) __android_log_print(ANDROID_LOG_INFO, "GLShim", __VA_ARGS__)
 
-static const char *const hidden[] = {
+static const char *const hidden_multiview[] = {
     "GL_OVR_multiview", "GL_OVR_multiview2", "GL_OVR_multiview_multisampled_render_to_texture",
+};
+// multisampled render-to-texture: Unity renders a runtime MSAA eye buffer through it, which crashes Zink (SIGSEGV in
+// libgallium_dri.so, e.g. The Room VR); hidden, Unity uses an ordinary MSAA renderbuffer + resolve
+static const char *const hidden_msrtt[] = {
     "GL_EXT_multisampled_render_to_texture", "GL_EXT_multisampled_render_to_texture2",
+    "GL_OVR_multiview_multisampled_render_to_texture",
 };
 
 static void *gles;
@@ -25,23 +30,52 @@ static void (*real_glGetIntegerv)(GLenum, GLint *);
 static __eglMustCastToProperFunctionPointerType (*real_eglGetProcAddress)(const char *);
 static pthread_once_t once = PTHREAD_ONCE_INIT;
 
-static int hide_multiview = 1;
+static int hide_multiview = -1;  // -1: not set (Unity and Unreal keep multiview, everything else hides it)
+static int hide_msrtt = 1;
+// Unreal (4.25) only turns on its mobile multiview when GL_OVR_multiview, GL_OVR_multiview2 AND
+// GL_OVR_multiview_multisampled_render_to_texture are all there (FOpenGLES::ProcessExtensions). Hiding the last one
+// with the MSRTT extensions switched Unreal's multiview off, so for Unreal it stays visible and its function draws
+// single-sampled (glFramebufferTextureMultiviewOVR), like the EXT stand-ins below.
+static int unreal;
 
-static void read_conf(void) {
-    char pkg[256] = {0}, path[512];
-    FILE *f = fopen("/proc/self/cmdline", "r");
+static void read_conf_file(const char *path) {
+    FILE *f = fopen(path, "r");
     if (!f) return;
-    size_t n = fread(pkg, 1, sizeof(pkg) - 1, f);
+    char line[256];
+    while (fgets(line, sizeof(line), f)) {
+        if (!strncmp(line, "gl_hide_multiview=", 18)) hide_multiview = atoi(line + 18);
+        if (!strncmp(line, "gl_hide_msrtt=", 14)) hide_msrtt = atoi(line + 14);
+    }
     fclose(f);
-    pkg[n] = 0;
+}
+
+// The same settings sources as FrameBridge, later ones winning: the build's libframe_settings.so (next to this
+// library), the game's framebridge.conf, then FRAMEBRIDGE_CONFIG (Lepton's per-game settings.conf).
+static void read_conf(void) {
+    Dl_info info;
+    char path[600];
+    if (dladdr((void *)read_conf, &info) && info.dli_fname) {
+        const char *slash = strrchr(info.dli_fname, '/');
+        if (slash && slash - info.dli_fname < 500) {
+            snprintf(path, sizeof(path), "%.*s/libframe_settings.so", (int)(slash - info.dli_fname), info.dli_fname);
+            read_conf_file(path);
+        }
+    }
+    char pkg[256] = {0};
+    FILE *f = fopen("/proc/self/cmdline", "r");
+    if (f) {
+        size_t n = fread(pkg, 1, sizeof(pkg) - 1, f);
+        fclose(f);
+        pkg[n] = 0;
+    }
     char *colon = strchr(pkg, ':');
     if (colon) *colon = 0;
-    snprintf(path, sizeof(path), "/sdcard/Android/data/%s/files/framebridge.conf", pkg);
-    if (!(f = fopen(path, "r"))) return;
-    char line[128];
-    while (fgets(line, sizeof(line), f))
-        if (!strncmp(line, "gl_hide_multiview=", 18)) hide_multiview = atoi(line + 18);
-    fclose(f);
+    if (*pkg && !strchr(pkg, '/')) {
+        snprintf(path, sizeof(path), "/sdcard/Android/data/%s/files/framebridge.conf", pkg);
+        read_conf_file(path);
+    }
+    const char *env = getenv("FRAMEBRIDGE_CONFIG");
+    if (env && *env) read_conf_file(env);
 }
 
 // Logging wrappers for the framebuffer calls engines use for eye buffers.
@@ -306,13 +340,31 @@ static void init(void) {
     real_glGetStringi = gles ? dlsym(gles, "glGetStringi") : NULL;
     real_glGetIntegerv = gles ? dlsym(gles, "glGetIntegerv") : NULL;
     real_eglGetProcAddress = egl ? dlsym(egl, "eglGetProcAddress") : NULL;
-    LOG("GL shim active: hide_multiview=%d", hide_multiview);
+    static const char *const engines[] = {"libunity.so", "libUE4.so", "libUnreal.so"};
+    int engine_found = 0;
+    for (unsigned i = 0; i < sizeof engines / sizeof *engines && !engine_found; i++) {
+        void *engine = dlopen(engines[i], RTLD_NOW | RTLD_NOLOAD);
+        if (engine) {
+            engine_found = 1;
+            unreal = i > 0;
+            dlclose(engine);
+        }
+    }
+    // Unity and Unreal render multiview themselves and only need MSRTT hidden
+    if (hide_multiview < 0) hide_multiview = !engine_found;
+    unreal = unreal && hide_msrtt && !hide_multiview;  // only matters while MSRTT is hidden and multiview kept
+    LOG("GL shim active: hide_multiview=%d hide_msrtt=%d%s", hide_multiview, hide_msrtt,
+        unreal ? " (Unreal: multiview MSRTT kept, drawn single-sampled)" : "");
 }
 
 static int is_hidden(const char *name) {
-    if (!hide_multiview) return 0;
-    for (size_t i = 0; i < sizeof(hidden) / sizeof(hidden[0]); ++i)
-        if (!strcmp(name, hidden[i])) return 1;
+    if (hide_multiview)
+        for (size_t i = 0; i < sizeof(hidden_multiview) / sizeof(hidden_multiview[0]); ++i)
+            if (!strcmp(name, hidden_multiview[i])) return 1;
+    if (hide_msrtt)
+        for (size_t i = 0; i < sizeof(hidden_msrtt) / sizeof(hidden_msrtt[0]); ++i)
+            if (!strcmp(name, hidden_msrtt[i]))
+                return !(unreal && !strcmp(name, "GL_OVR_multiview_multisampled_render_to_texture"));
     return 0;
 }
 
@@ -362,6 +414,32 @@ __attribute__((visibility("default"))) const GLubyte *glGetString(GLenum name) {
     return (const GLubyte *)filtered;
 }
 
+// With GL_EXT_multisampled_render_to_texture hidden (gl_hide_msrtt), an app that calls its functions anyway (Team
+// Beef's TBXR, e.g. Lambda1VR: color via glFramebufferTexture2DMultisampleEXT, depth via
+// glRenderbufferStorageMultisampleEXT) gets plain single-sampled versions, so both attachments match: Zink called
+// the mix GL_FRAMEBUFFER_INCOMPLETE_MULTISAMPLE and the eyes stayed black.
+typedef void (*PFN_FT2D)(GLenum, GLenum, GLenum, GLuint, GLint);
+typedef void (*PFN_RBS)(GLenum, GLenum, GLsizei, GLsizei);
+static PFN_FT2D r_plain_ft2d;
+static PFN_RBS r_plain_rbs;
+static int msrtt_logged;
+static void plain_ft2dms(GLenum target, GLenum attachment, GLenum textarget, GLuint texture, GLint level, GLsizei samples) {
+    if (!msrtt_logged++) LOG("GL shim: multisampled render-to-texture (%d samples) drawn single-sampled", (int)samples);
+    if (r_plain_ft2d) r_plain_ft2d(target, attachment, textarget, texture, level);
+}
+static void plain_rbsms(GLenum target, GLsizei samples, GLenum format, GLsizei width, GLsizei height) {
+    (void)samples;
+    if (r_plain_rbs) r_plain_rbs(target, format, width, height);
+}
+static PFN_FTMV r_plain_ftmv;
+static int mv_msrtt_logged;
+static void plain_ftmsmv(GLenum target, GLenum attachment, GLuint texture, GLint level, GLsizei samples,
+                         GLint base, GLsizei views) {
+    if (!mv_msrtt_logged++)
+        LOG("GL shim: multiview multisampled render-to-texture (%d samples) drawn single-sampled", (int)samples);
+    if (r_plain_ftmv) r_plain_ftmv(target, attachment, texture, level, base, views);
+}
+
 __attribute__((visibility("default"))) __eglMustCastToProperFunctionPointerType eglGetProcAddress(const char *name) {
     pthread_once(&once, init);
     if (name && !strcmp(name, "glGetStringi")) return (__eglMustCastToProperFunctionPointerType)glGetStringi;
@@ -370,6 +448,17 @@ __attribute__((visibility("default"))) __eglMustCastToProperFunctionPointerType
     __eglMustCastToProperFunctionPointerType fn = real_eglGetProcAddress ? real_eglGetProcAddress(name) : NULL;
     if (!fn || !name) return fn;
 #define WRAP(sym, real, w) if (!strcmp(name, sym)) { real = (void *)fn; return (__eglMustCastToProperFunctionPointerType)w; }
+    if (hide_msrtt && (!strcmp(name, "glFramebufferTexture2DMultisampleEXT") ||
+                       !strcmp(name, "glRenderbufferStorageMultisampleEXT"))) {
+        if (!r_plain_ft2d) r_plain_ft2d = (PFN_FT2D)real_eglGetProcAddress("glFramebufferTexture2D");
+        if (!r_plain_rbs) r_plain_rbs = (PFN_RBS)real_eglGetProcAddress("glRenderbufferStorage");
+        return name[2] == 'F' ? (__eglMustCastToProperFunctionPointerType)plain_ft2dms
+                              : (__eglMustCastToProperFunctionPointerType)plain_rbsms;
+    }
+    if (unreal && !strcmp(name, "glFramebufferTextureMultisampleMultiviewOVR")) {
+        if (!r_plain_ftmv) r_plain_ftmv = (PFN_FTMV)real_eglGetProcAddress("glFramebufferTextureMultiviewOVR");
+        return (__eglMustCastToProperFunctionPointerType)plain_ftmsmv;
+    }
 #ifdef GLSHIM_TRACE  // build with -DGLSHIM_TRACE for eye-buffer / draw / error tracing
     WRAP("glFramebufferTextureMultiviewOVR", real_ftmv, w_ftmv)
     WRAP("glFramebufferTextureMultisampleMultiviewOVR", real_ftmsmv, w_ftmsmv)

native/langpack/langpack.c

@@ -30,6 +30,12 @@
 //
 // Which pack is "current": the one the game applied with SetCurrent; else $FRAMEPORT_LANGPACK (a tag); else the only
 // pack if there is exactly one.
+//
+// Content files (patch frame.asset_files, which sets the marker byte g_assets_slot; or FRAMEPORT_ASSET_FILES=1):
+// every *.pak next to the game's OBB is also listed as an installed asset file of type "default" (Meta's type for
+// content that comes with the game, IAP status "free"), named after the file. ovr_AssetFile_DownloadById on one of
+// them answers at once with a completed download update and a result carrying the file's path (nothing is copied).
+// E.g. Star Wars: Tales from the Galaxy's Edge, whose seasons and sound banks are such files (ETacoDLC::Season1...).
 #define _GNU_SOURCE
 #include <ctype.h>
 #include <dirent.h>
@@ -93,6 +99,8 @@ static int g_traced;
 #define MSG_ASSETFILE_STATUSBYID 0x5D955D38u
 #define MSG_LANGUAGEPACK_GETCURRENT 0x1F90F0D5u
 #define MSG_LANGUAGEPACK_SETCURRENT 0x5B4FBBE0u
+#define MSG_ASSETFILE_DOWNLOADBYID 0x2D008992u
+#define MSG_NOTIFICATION_DOWNLOADUPDATE 0x2FDD0CCDu
 
 #define MAXP 32
 #define PATHLEN 1024
@@ -206,6 +214,12 @@ DEFORIG(u64, AssetFileDownloadResult_GetAssetId, (const void *r), (r))
 DEFORIG(const char *, AssetFileDownloadResult_GetFilepath, (const void *r), (r))
 DEFORIG(u64, AssetFile_GetList, (void), ())
 DEFORIG(u64, AssetFile_StatusById, (u64 id), (id))
+DEFORIG(u64, AssetFile_DownloadById, (u64 id), (id))
+DEFORIG(void *, Message_GetAssetFileDownloadUpdate, (const void *m), (m))
+DEFORIG(u64, AssetFileDownloadUpdate_GetAssetFileId, (const void *u), (u))
+DEFORIG(u64, AssetFileDownloadUpdate_GetBytesTotal, (const void *u), (u))
+DEFORIG(long long, AssetFileDownloadUpdate_GetBytesTransferred, (const void *u), (u))
+DEFORIG(_Bool, AssetFileDownloadUpdate_GetCompleted, (const void *u), (u))
 DEFORIG(int, Error_GetCode, (const void *e), (e))
 DEFORIG(int, Error_GetHttpCode, (const void *e), (e))
 DEFORIG(const char *, Error_GetMessage, (const void *e), (e))
@@ -216,9 +230,12 @@ DEFORIG(const char *, Error_GetDisplayableMessage, (const void *e), (e))
  * ------------------------------------------------------------------------------------------------------------- */
 
 typedef struct {
-    char tag[48];
+    char tag[48];  // language packs: the BCP47 tag; content files: empty
+    char name[128];  // content files: the file name (the asset's name)
     char path[PATHLEN];
     u64 id;
+    long long size;
+    int content;
 } pack_t;
 
 static const struct {
@@ -263,8 +280,9 @@ static int valid_tag(const char *t) {
 
 static void add_pack(pack_t *out, int *n, const char *tag, const char *path) {
     for (int i = 0; i < *n; i++)
-        if (tag_eq(out[i].tag, tag)) return;  // first one wins
+        if (!out[i].content && tag_eq(out[i].tag, tag)) return;  // first one wins
     pack_t *p = &out[(*n)++];
+    memset(p, 0, sizeof *p);
     snprintf(p->tag, sizeof p->tag, "%s", tag);
     snprintf(p->path, sizeof p->path, "%s", path);
     p->id = hash_tag(tag);
@@ -272,6 +290,37 @@ static void add_pack(pack_t *out, int *n, const char *tag, const char *path) {
 
 static int g_logged_dirs;
 
+// frame.asset_files sets the byte after the marker to '1' (frameport.patches.frame.langpack.with_assets)
+#define ASSETS_MARK "@FPASSETS@"
+__attribute__((used)) static char g_assets_slot[sizeof ASSETS_MARK + 1] = ASSETS_MARK "0";
+
+static int assets_enabled(void) {
+    const char *env = getenv("FRAMEPORT_ASSET_FILES");
+    if (env && *env) return *env == '1';
+    return ((const volatile char *)g_assets_slot)[sizeof ASSETS_MARK - 1] == '1';
+}
+
+static u64 hash_name(const char *name) {
+    u64 h = 1469598103934665603ULL ^ 0x66;  // FNV-1a, seeded apart from the tags
+    for (const char *p = name; *p; p++) {
+        h ^= (unsigned char)((*p >= 'A' && *p <= 'Z') ? *p + 32 : *p);
+        h *= 1099511628211ULL;
+    }
+    return 0x4650000000000000ULL | (h & 0x0000FFFFFFFFFFFFULL);
+}
+
+static void add_content(pack_t *out, int *n, const char *name, const char *path, long long size) {
+    for (int i = 0; i < *n; i++)
+        if (out[i].content && strcasecmp(out[i].name, name) == 0) return;  // first one wins
+    pack_t *p = &out[(*n)++];
+    memset(p, 0, sizeof *p);
+    p->content = 1;
+    snprintf(p->name, sizeof p->name, "%.127s", name);  // (callers pass names shorter than 128)
+    snprintf(p->path, sizeof p->path, "%s", path);
+    p->size = size;
+    p->id = hash_name(name);
+}
+
 // Tags to leave out of the list (comma separated, case-insensitive): env FRAMEPORT_LANGPACK_SKIP, plus the lines
 // of a file "fp_langpack_skip" in any scanned folder. For finding out which pack a game needs reported: e.g. a game
 // whose built-in language works without being a "pack".
@@ -323,6 +372,9 @@ static void scan_dir(const char *dir, int depth, pack_t *out, int *n) {
                 memcpy(tag, e->d_name, len - 5);
                 tag[len - 5] = 0;
                 if (valid_tag(tag) && !skipped(tag)) add_pack(out, n, tag, path);
+            } else if (len > 4 && strcasecmp(e->d_name + len - 4, ".pak") == 0 && assets_enabled() &&
+                       strlen(e->d_name) < sizeof out[0].name) {
+                add_content(out, n, e->d_name, path, (long long)st.st_size);
             }
         }
     }
@@ -347,8 +399,10 @@ static int scan(pack_t *out) {
     static int last = -1;
     if (n != last) {
         last = n;
-        fplog("%d language pack(s) found", n);
-        for (int i = 0; i < n; i++) fplog("  pack %s -> %s", out[i].tag, out[i].path);
+        fplog("%d language pack(s) and content file(s) found", n);
+        for (int i = 0; i < n; i++)
+            fplog("  %s %s -> %s", out[i].content ? "content" : "pack", out[i].content ? out[i].name : out[i].tag,
+                  out[i].path);
     }
     g_logged_dirs = 1;
     return n;
@@ -390,10 +444,10 @@ static char g_current[48];  // tag the game applied with SetCurrent
 
 static int find_tag(const pack_t *p, int n, const char *tag) {
     for (int i = 0; i < n; i++)
-        if (tag_eq(p[i].tag, tag)) return i;
+        if (!p[i].content && tag_eq(p[i].tag, tag)) return i;
     int bl = base_len(tag);  // "de-DE" -> "de" (and the reverse: "de" asked, "de-de" present)
     for (int i = 0; i < n; i++)
-        if (base_len(p[i].tag) == bl && strncasecmp(p[i].tag, tag, (size_t)bl) == 0) return i;
+        if (!p[i].content && base_len(p[i].tag) == bl && strncasecmp(p[i].tag, tag, (size_t)bl) == 0) return i;
     return -1;
 }
 
@@ -411,7 +465,10 @@ static int pick_current(const pack_t *p, int n) {
         int i = find_tag(p, n, env);
         if (i >= 0) return i;
     }
-    return n == 1 ? 0 : -1;
+    int only = -1, langs = 0;
+    for (int i = 0; i < n; i++)
+        if (!p[i].content) only = i, langs++;
+    return langs == 1 ? only : -1;
 }
 
 /* ---------------------------------------------------------------------------------------------------------------
@@ -460,12 +517,19 @@ typedef struct {
     char msg[128];
 } err_t;
 
+typedef struct {
+    u64 id;
+    long long total, done;
+    int completed;
+} update_t;
+
 typedef struct msg {
     struct msg *all_next, *q_next;
     u32 type;
     u64 req;
-    int is_error, has_det, has_res;
+    int is_error, has_det, has_res, has_upd;
     err_t err;
+    update_t upd;
     details_t det;
     lang_t lng;
     result_t res;
@@ -525,6 +589,16 @@ static void fail(msg_t *m, int code, const char *text) {
 }
 
 static void fill_details(details_t *d, lang_t *l, const pack_t *p) {
+    if (p->content) {  // content that comes with the game: Meta's "default" asset type, nothing to buy
+        d->id = p->id;
+        snprintf(d->type, sizeof d->type, "default");
+        snprintf(d->status, sizeof d->status, "installed");
+        snprintf(d->iap, sizeof d->iap, "free");
+        snprintf(d->path, sizeof d->path, "%s", p->path);
+        d->meta[0] = 0;
+        d->lang = NULL;
+        return;
+    }
     d->id = p->id;
     snprintf(d->type, sizeof d->type, "language_pack");
     snprintf(d->status, sizeof d->status, "installed");
@@ -722,6 +796,35 @@ EXPORT u64 ovr_AssetFile_StatusById(u64 id) {
     return o_AssetFile_StatusById(id);
 }
 
+EXPORT u64 ovr_AssetFile_DownloadById(u64 id) {
+    fplog("AssetFile_DownloadById(%llu)%s", (unsigned long long)id, (id >> 48) == 0x4650 ? " (ours)" : "");
+    if ((id >> 48) != 0x4650) return o_AssetFile_DownloadById(id);
+    pack_t packs[MAXP];
+    int n = scan(packs), i = 0;
+    while (i < n && packs[i].id != id) i++;
+    msg_t *m = new_msg(MSG_ASSETFILE_DOWNLOADBYID, 0);
+    if (!m) return 0;
+    u64 req = m->req;
+    if (i == n) {
+        fail(m, 404, "asset file not found");
+        post(m);
+        return req;
+    }
+    // already on the device: a finished download update, then the result with the file's path
+    msg_t *u = new_msg(MSG_NOTIFICATION_DOWNLOADUPDATE, 0);
+    if (u) {
+        u->req = 0;  // notifications carry no request id
+        u->upd = (update_t){packs[i].id, packs[i].size, packs[i].size, 1};
+        u->has_upd = 1;
+        post(u);
+    }
+    m->res.id = packs[i].id;
+    snprintf(m->res.path, sizeof m->res.path, "%s", packs[i].path);
+    m->has_res = 1;
+    post(m);
+    return req;
+}
+
 /* ---------------------------------------------------------------------------------------------------------------
  * Message loop
  * ------------------------------------------------------------------------------------------------------------- */
@@ -813,6 +916,12 @@ EXPORT void *ovr_Message_GetAssetFileDownloadResult(const void *h) {
     return m->has_res ? (void *)&m->res : NULL;
 }
 
+EXPORT void *ovr_Message_GetAssetFileDownloadUpdate(const void *h) {
+    msg_t *m = owner(h);
+    if (!m) return o_Message_GetAssetFileDownloadUpdate(h);
+    return m->has_upd ? (void *)&m->upd : NULL;
+}
+
 EXPORT void *ovr_Message_GetAssetDetailsArray(const void *h) {
     msg_t *m = owner(h);
     if (!m) return o_Message_GetAssetDetailsArray(h);
@@ -903,6 +1012,19 @@ EXPORT const char *ovr_AssetFileDownloadResult_GetFilepath(const void *h) {
     return IS_OURS(h) ? ((const result_t *)h)->path : o_AssetFileDownloadResult_GetFilepath(h);
 }
 
+EXPORT u64 ovr_AssetFileDownloadUpdate_GetAssetFileId(const void *h) {
+    return IS_OURS(h) ? ((const update_t *)h)->id : o_AssetFileDownloadUpdate_GetAssetFileId(h);
+}
+EXPORT u64 ovr_AssetFileDownloadUpdate_GetBytesTotal(const void *h) {
+    return IS_OURS(h) ? (u64)((const update_t *)h)->total : o_AssetFileDownloadUpdate_GetBytesTotal(h);
+}
+EXPORT long long ovr_AssetFileDownloadUpdate_GetBytesTransferred(const void *h) {
+    return IS_OURS(h) ? ((const update_t *)h)->done : o_AssetFileDownloadUpdate_GetBytesTransferred(h);
+}
+EXPORT _Bool ovr_AssetFileDownloadUpdate_GetCompleted(const void *h) {
+    return IS_OURS(h) ? (_Bool)((const update_t *)h)->completed : o_AssetFileDownloadUpdate_GetCompleted(h);
+}
+
 EXPORT int ovr_Error_GetCode(const void *h) { return IS_OURS(h) ? ((const err_t *)h)->code : o_Error_GetCode(h); }
 EXPORT int ovr_Error_GetHttpCode(const void *h) { return IS_OURS(h) ? ((const err_t *)h)->http : o_Error_GetHttpCode(h); }
 EXPORT const char *ovr_Error_GetMessage(const void *h) {

native/ovrpshim/ovrpshim.c

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-3.0-only
-// FramePort OVRPlugin frame-loop shim for Unity 2017-2018 built-in Oculus support.
+// FramePort OVRPlugin shim: the frame loop for Unity 2017-2018 built-in Oculus support, and Unity's user presence.
 //
 // That Unity drives OVRPlugin with the legacy frame loop: ovrp_Update2(render step, frame index, ...) on the main
 // thread, then ovrp_BeginFrame / ovrp_EndFrame on the render thread. It never calls ovrp_WaitToBeginFrame, which
@@ -9,10 +9,14 @@
 //
 // FramePort renames the "ovrp_Update2" lookup in libunity.so to "fpov_Update2" (same length) and adds this library to
 // libOVRPlugin.so's DT_NEEDED, so Unity's dlsym on the plugin finds this function: it waits for the frame first (once
-// per frame index, render step only), then calls the real ovrp_Update2.
+// per frame index, render step only), then calls the real ovrp_Update2 (render step; the physics step: see below).
 #include <android/log.h>
 #include <dlfcn.h>
 #include <pthread.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
 
 #define TAG "FrameBridge"
 #define EXPORT __attribute__((visibility("default")))
@@ -25,28 +29,168 @@ static PFN_Update2 real_update2;
 static PFN_WaitToBeginFrame real_wait;
 static pthread_once_t once = PTHREAD_ONCE_INIT;
 
+// Per-game settings (the same sources as FrameBridge and the GL shim, later ones winning): the frame-begin gate and
+// the held-back physics update below were needed by Sniper Elite VR; in Unity 2019 games (BattleSisters) holding the
+// physics update back made the hands lag and the gate made loading screens stutter, so both are off unless the recipe
+// turns them on (ovrp_begin_gate=1, ovrp_hold_physics=1).
+static int begin_gate, hold_physics;
+
+static void read_conf_file(const char *path) {
+    FILE *f = fopen(path, "r");
+    if (!f) return;
+    char line[256];
+    while (fgets(line, sizeof(line), f)) {
+        if (!strncmp(line, "ovrp_begin_gate=", 16)) begin_gate = atoi(line + 16);
+        if (!strncmp(line, "ovrp_hold_physics=", 18)) hold_physics = atoi(line + 18);
+    }
+    fclose(f);
+}
+
+static void read_conf(void) {
+    Dl_info info;
+    char path[600];
+    if (dladdr((void *)read_conf, &info) && info.dli_fname) {
+        const char *slash = strrchr(info.dli_fname, '/');
+        if (slash && slash - info.dli_fname < 500) {
+            snprintf(path, sizeof(path), "%.*s/libframe_settings.so", (int)(slash - info.dli_fname), info.dli_fname);
+            read_conf_file(path);
+        }
+    }
+    char pkg[256] = {0};
+    FILE *f = fopen("/proc/self/cmdline", "r");
+    if (f) {
+        size_t n = fread(pkg, 1, sizeof(pkg) - 1, f);
+        fclose(f);
+        pkg[n] = 0;
+    }
+    char *colon = strchr(pkg, ':');
+    if (colon) *colon = 0;
+    if (*pkg && !strchr(pkg, '/')) {
+        snprintf(path, sizeof(path), "/sdcard/Android/data/%s/files/framebridge.conf", pkg);
+        read_conf_file(path);
+    }
+    const char *env = getenv("FRAMEBRIDGE_CONFIG");
+    if (env && *env) read_conf_file(env);
+}
+
 static void init(void) {
+    read_conf();
     void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
     if (!ovrp) ovrp = dlopen("libOVRPlugin.so", RTLD_NOW);
     if (ovrp) {
         real_update2 = (PFN_Update2)dlsym(ovrp, "ovrp_Update2");
         real_wait = (PFN_WaitToBeginFrame)dlsym(ovrp, "ovrp_WaitToBeginFrame");
     }
-    LOG("ovrp frame loop shim: ovrp_Update2 %s, ovrp_WaitToBeginFrame %s", real_update2 ? "OK" : "MISSING",
-        real_wait ? "OK" : "MISSING");
+    LOG("ovrp frame loop shim: ovrp_Update2 %s, ovrp_WaitToBeginFrame %s, begin gate %d, hold physics %d",
+        real_update2 ? "OK" : "MISSING", real_wait ? "OK" : "MISSING", begin_gate, hold_physics);
 }
 
 #define STEP_RENDER (-1)  // ovrpStep_Render
 
+static void mouse_click_frame(void);  // below: controller presses as Unity mouse clicks
+
+// xrWaitFrame blocks until the frame waited for before it has begun (xrBeginFrame). Unity begins frames on its render
+// thread, which sometimes skips one (scene activation) and then waits for the main thread: our next wait never
+// returned (Sniper Elite VR hung at its Init scene, main thread in SteamVR's CSxrSession::StartNextFrame, render
+// thread idle). FramePort also renames libunity.so's "ovrp_BeginFrame"/"ovrp_EndFrame" lookups to the functions below.
+// Once a begin has come through, the main thread first waits (≤ BEGIN_TIMEOUT_MS) for the last waited frame to begin
+// and skips this frame's wait if it doesn't (normally the render thread begins it within a frame: pacing unchanged).
+// OVRPlugin only begins the frame index it waited for (else "outside of frame bounds" and no xrBeginFrame, after which
+// the next wait blocked for good), so a begin of another index while a wait is outstanding becomes a begin of the
+// waited index, and the matching end follows it.
+#define BEGIN_TIMEOUT_MS 50
+static pthread_mutex_t begin_lock = PTHREAD_MUTEX_INITIALIZER;
+static pthread_cond_t begin_cond = PTHREAD_COND_INITIALIZER;
+static int begin_hooked;     // fpov_BeginFrame has been called: the gate is armed
+static int outstanding = -1; // frame index waited for and not begun yet, else -1 (under begin_lock)
+static int remap_from = -1, remap_to = -1;  // the last begin that was given the waited index (for its end)
+
+static int last_wait_begun(int frame_index) {
+    if (!begin_gate) return 1;
+    pthread_mutex_lock(&begin_lock);
+    struct timespec until;
+    clock_gettime(CLOCK_REALTIME, &until);
+    until.tv_nsec += BEGIN_TIMEOUT_MS * 1000000L;
+    if (until.tv_nsec >= 1000000000L) until.tv_sec++, until.tv_nsec -= 1000000000L;
+    while (begin_hooked && outstanding >= 0)
+        if (pthread_cond_timedwait(&begin_cond, &begin_lock, &until)) break;
+    int ok = !begin_hooked || outstanding < 0;
+    if (ok) outstanding = frame_index;
+    pthread_mutex_unlock(&begin_lock);
+    return ok;
+}
+
+// Unity's physics step updates OVRPlugin's poses with prediction 0 ("now"). OVRPlugin takes "now" from the monotonic
+// clock, which is the XrTime base on a Quest but not on the Frame (its XrTime ran 0.05-0.9 s ahead), so it located
+// every node that much in the past (the runtime extrapolates backwards), and the render-step reads after it got those
+// poses too: the game's hands trailed the controllers by several centimetres whenever they moved (Sniper Elite VR). A
+// larger prediction doesn't reach (OVRPlugin caps it at ~0.07 s), so the physics update isn't passed on: OVRPlugin
+// keeps the render update's display-time poses for the whole frame (physics and render reads agree).
+#define STEP_PHYSICS 0
+
 EXPORT int fpov_Update2(int step, int frame_index, double prediction_seconds) {
     pthread_once(&once, init);
-    static int last_waited = -1, logged;
+    static int last_waited = -1, rendered, logged, skipped, last_result;
     if (step == STEP_RENDER && real_wait && frame_index != last_waited) {
         last_waited = frame_index;
-        int r = real_wait(frame_index);
-        if (logged++ < 3) LOG("ovrp frame loop shim: waited for frame %d: %d", frame_index, r);
+        if (last_wait_begun(frame_index)) {
+            int r = real_wait(frame_index);
+            if (logged++ < 3) LOG("ovrp frame loop shim: waited for frame %d: %d", frame_index, r);
+        } else if (skipped++ < 20 || skipped % 1000 == 0) {
+            LOG("ovrp frame loop shim: frame %d: the last waited frame wasn't begun within %d ms, not waiting "
+                "(%d times)", frame_index, BEGIN_TIMEOUT_MS, skipped);
+        }
+        mouse_click_frame();
     }
-    return real_update2 ? real_update2(step, frame_index, prediction_seconds) : -1000;  // ovrpFailure
+    if (hold_physics && step == STEP_PHYSICS && rendered) return last_result;  // see above: keeps the display-time poses
+    int r = real_update2 ? real_update2(step, frame_index, prediction_seconds) : -1000;  // ovrpFailure
+    if (step == STEP_RENDER) rendered = 1, last_result = r;
+    return r;
+}
+
+// Unity's legacy ovrp_BeginFrame(frameIndex) / ovrp_EndFrame(frameIndex) on the render thread; further arguments
+// (older plugins) are passed on as they are
+typedef int (*PFN_FrameCall)(long, long, long, long);
+
+static PFN_FrameCall ovrp_fn(const char *name) {
+    void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
+    PFN_FrameCall fn = ovrp ? (PFN_FrameCall)dlsym(ovrp, name) : 0;
+    LOG("ovrp frame loop shim: %s %s", name, fn ? "OK" : "MISSING");
+    return fn;
+}
+
+EXPORT int fpov_BeginFrame(long frame, long b, long c, long d) {
+    static PFN_FrameCall real;
+    static int logged;
+    pthread_once(&once, init);  // the settings (begin_gate) before the first begin
+    if (!real) real = ovrp_fn("ovrp_BeginFrame");
+    pthread_mutex_lock(&begin_lock);
+    long index = frame;
+    if (begin_gate && outstanding >= 0 && outstanding != (int)frame) {
+        index = outstanding;
+        remap_from = (int)frame, remap_to = outstanding;
+    } else {
+        remap_from = remap_to = -1;
+    }
+    pthread_mutex_unlock(&begin_lock);
+    int r = real ? real(index, b, c, d) : -1000;
+    if (index != frame && logged++ < 20)
+        LOG("ovrp frame loop shim: begin frame %ld as waited frame %ld: %d", frame, index, r);
+    pthread_mutex_lock(&begin_lock);
+    begin_hooked = 1;
+    outstanding = -1;  // the waited frame (if any) is begun now
+    pthread_cond_broadcast(&begin_cond);
+    pthread_mutex_unlock(&begin_lock);
+    return r;
+}
+
+EXPORT int fpov_EndFrame(long frame, long b, long c, long d) {
+    static PFN_FrameCall real;
+    if (!real) real = ovrp_fn("ovrp_EndFrame");
+    pthread_mutex_lock(&begin_lock);
+    if ((int)frame == remap_from) frame = remap_to;
+    pthread_mutex_unlock(&begin_lock);
+    return real ? real(frame, b, c, d) : -1000;
 }
 
 // ---------------------------------------------------------------- input diagnostics (pass-through)
@@ -116,7 +260,7 @@ static void note_state(const char *which, unsigned int mask, const State *s) {
     while (i < 8 && masks[i].seen && masks[i].mask != mask) i++;
     if (i == 8) return;
     if (!masks[i].seen || masks[i].buttons != s->words[1] || masks[i].connected != s->words[0]) {
-        if (changes++ < 120)
+        if (changes++ < 400)
             LOG("ovrp input: %s(mask 0x%x): connected 0x%x buttons 0x%x touches 0x%x%s", which, mask, s->words[0],
                 s->words[1], s->words[2], masks[i].seen ? "" : " (first call with this mask)");
         masks[i].seen = 1;
@@ -140,6 +284,22 @@ EXPORT int fpov_GetControllerState4(unsigned int mask, State *state) {
     pthread_once(&input_once, input_init);
     int r = real_state4 ? real_state4(mask, state) : -1000;
     if (state) {
+        // ovrpControllerState4 continues with 4 floats after the 4 masks: L/R IndexTrigger, L/R HandTrigger. OVRInput
+        // turns them into the trigger/grip buttons at 0.5; log each time one crosses it (per requested mask)
+        const float *axis = (const float *)((const char *)state + 16);
+        static struct { unsigned int mask, bits; } seen[8];
+        static int axis_logs;
+        unsigned int bits = 0;
+        for (int k = 0; k < 4; ++k) bits |= (axis[k] >= 0.5f) << k;
+        int i = 0;
+        while (i < 8 && seen[i].mask && seen[i].mask != mask) i++;
+        if (i < 8 && (!seen[i].mask || seen[i].bits != bits)) {
+            if (seen[i].mask && axis_logs++ < 200)
+                LOG("ovrp input: State4(mask 0x%x) triggers L %.2f R %.2f grips L %.2f R %.2f", mask, axis[0], axis[1],
+                    axis[2], axis[3]);
+            seen[i].mask = mask;
+            seen[i].bits = bits;
+        }
         note_state("State4", mask, state);
         state->words[1] = unstick(state->words[1]);
     }
@@ -193,3 +353,105 @@ EXPORT int fpov_GetAppHasInputFocus(int *has_focus) {
     if (has_focus) *has_focus = 1;
     return 0;  // ovrpSuccess
 }
+
+// ---------------------------------------------------------------- controller presses as mouse clicks
+// Unity 2017-2019 games made for Go/Gear VR-era input wait for Input.GetMouseButtonDown(0/1), which a Quest delivers
+// for the controller's primary press (Accounting+'s "press any button" motion warning checks only that). Lepton runs
+// VR apps without a focused Android window, so no touch/mouse event ever arrives. IL2CPP looks engine functions up by
+// name (il2cpp_resolve_icall) on first use: this registers a replacement for UnityEngine.Input::GetMouseButtonDown
+// that returns Unity's answer, or true in the frame a Touch trigger (>= 0.5) or A/B/X/Y is newly pressed.
+#define MOUSE_ICALL "UnityEngine.Input::GetMouseButtonDown(System.Int32)"
+typedef void (*PFN_AddICall)(const char *name, const void *fn);
+typedef const void *(*PFN_ResolveICall)(const char *name);
+typedef int (*PFN_MouseDown)(int button);
+static PFN_MouseDown real_mouse_down;
+static volatile int click_now;  // set for the frame in which a press began
+
+static int fp_mouse_down(int button) {
+    int real = real_mouse_down ? real_mouse_down(button) : 0;
+    return real || ((button == 0 || button == 1) && click_now);
+}
+
+static void mouse_install(void) {
+    static int tries;
+    if (real_mouse_down || tries > 600) return;  // ~10 s of frames
+    tries++;
+    PFN_AddICall add = (PFN_AddICall)dlsym(RTLD_DEFAULT, "il2cpp_add_internal_call");
+    PFN_ResolveICall resolve = (PFN_ResolveICall)dlsym(RTLD_DEFAULT, "il2cpp_resolve_icall");
+    if (!add || !resolve) {
+        void *il2cpp = dlopen("libil2cpp.so", RTLD_NOW | RTLD_NOLOAD);
+        if (il2cpp) {
+            add = (PFN_AddICall)dlsym(il2cpp, "il2cpp_add_internal_call");
+            resolve = (PFN_ResolveICall)dlsym(il2cpp, "il2cpp_resolve_icall");
+        }
+    }
+    if (!add || !resolve) return;
+    const void *current = resolve(MOUSE_ICALL);
+    if (!current) return;  // Unity hasn't registered its own yet: try again next frame
+    real_mouse_down = (PFN_MouseDown)current;
+    add(MOUSE_ICALL, (const void *)fp_mouse_down);
+    LOG("controller presses count as mouse clicks (%s %s)", MOUSE_ICALL,
+        resolve(MOUSE_ICALL) == (const void *)fp_mouse_down ? "replaced" : "NOT replaced");
+}
+
+static void mouse_click_frame(void) {
+    mouse_install();
+    pthread_once(&input_once, input_init);
+    static int was_pressed;
+    unsigned char raw[512] __attribute__((aligned(16))) = {0};  // ovrpControllerState4 (+ room for newer layouts)
+    int pressed = 0;
+    if (real_state4 && real_state4(0x3, (State *)raw) >= 0) {
+        const unsigned int *w = (const unsigned int *)raw;
+        const float *axis = (const float *)(raw + 16);  // L/R IndexTrigger, L/R HandTrigger
+        pressed = (w[1] & 0x303u) != 0 || axis[0] >= 0.5f || axis[1] >= 0.5f;  // A, B, X, Y or a trigger
+    }
+    click_now = pressed && !was_pressed;
+    was_pressed = pressed;
+}
+
+// ---------------------------------------------------------------- hand nodes
+// Unity's built-in Oculus XR input creates its left/right controller devices (InputDevices.GetDeviceAtXRNode, the
+// Touch buttons and triggers games read through CommonUsages) for the hand nodes OVRPlugin reports as present
+// (ovrp_GetNodePresent). Logged per node; a hand node whose Touch controller is connected counts as present.
+typedef int (*PFN_NodePresent)(int node);
+#define NODE_HAND_LEFT 3
+#define NODE_HAND_RIGHT 4
+
+EXPORT int fpov_GetNodePresent(int node) {
+    static PFN_NodePresent real;
+    static int logged[16];
+    pthread_once(&input_once, input_init);
+    if (!real) {
+        void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
+        if (ovrp) real = (PFN_NodePresent)dlsym(ovrp, "ovrp_GetNodePresent");
+    }
+    int present = real ? real(node) : 0, answer = present;
+    if (!present && (node == NODE_HAND_LEFT || node == NODE_HAND_RIGHT) && real_connected)
+        answer = (real_connected() & (node == NODE_HAND_LEFT ? 0x1u : 0x2u)) != 0;  // LTouch / RTouch
+    if (node >= 0 && node < 16 && logged[node] != (answer ? 2 : 1)) {
+        logged[node] = answer ? 2 : 1;
+        LOG("ovrp node %d present: OVRPlugin %d -> Unity %d", node, present, answer);
+    }
+    return answer;
+}
+
+// ---------------------------------------------------------------- user presence (patch frame.unity_user_presence)
+// Unity's Oculus XR Plugin gives its HMD input device a UserPresence feature from ovrp_GetUserPresent2. On the Frame
+// OVRPort's OVRPlugin answers "not worn" a few seconds after start while the headset is worn, and games that drive
+// their rig only while the user is present stay frozen (BONELAB's Marrow rig: XRHMD.IsUserPresent). The plugin's
+// lookup is renamed to this function, which reports the user as present and logs OVRPlugin's own answer on change.
+typedef int (*PFN_UserPresent2)(int *present);
+
+EXPORT int fpov_GetUserPresent2(int *present) {
+    static PFN_UserPresent2 real;
+    if (!real) {
+        void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
+        if (ovrp) real = (PFN_UserPresent2)dlsym(ovrp, "ovrp_GetUserPresent2");
+    }
+    int value = 0, r = real ? real(&value) : -1000;
+    static int last = -2, logged;
+    if ((r < 0 ? -1 : value) != last && logged++ < 20) LOG("user presence: OVRPlugin %d (result %d) -> 1", value, r);
+    last = r < 0 ? -1 : value;
+    if (present) *present = 1;
+    return 0;  // ovrpSuccess
+}

native/ovrtrace/ovrtrace.c

@@ -0,0 +1,203 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// FramePort Meta Platform SDK tracer (diagnostics, patch frame.ovr_trace): logs the game's ovr_* calls and the
+// messages that answer them, to find a request that never gets an answer (a game waiting forever, e.g. Vader
+// Immortal after its intro). Nothing is answered or changed here: every call goes to the real function.
+//
+// Wiring: this library is the first DT_NEEDED of the game's engine library, so the engine's ovr_* imports resolve to
+// the exports below. Each export is a tiny assembly stub that saves the argument registers (x0-x8, d0-d7), asks
+// trace_before() for the real function (dlsym on the platform loader's handle, which also finds the language-pack
+// library's functions when frame.langpacks is on), calls it with the original registers, then reports the result to
+// trace_after(). Signatures don't matter (functions with more than 8 integer arguments would; the Platform SDK has
+// none). Logcat tag fp_ovrtrace.
+//
+// What is logged: the first calls of every function (argument 0 and the result), every message ovr_PopMessage
+// returns (type, request id, error flag), and every 10 s the request ids no message has answered yet with the
+// function that made them ("request" = a function whose name says it starts one: the result is kept when it looks
+// like a request id and the function isn't an accessor).
+#define _GNU_SOURCE
+#include <android/log.h>
+#include <dlfcn.h>
+#include <pthread.h>
+#include <stdint.h>
+#include <string.h>
+#include <time.h>
+
+#define TAG "fp_ovrtrace"
+#define LOG(...) __android_log_print(ANDROID_LOG_INFO, TAG, __VA_ARGS__)
+
+static const char *const NAMES[] = {
+#define N(name) #name,
+#include "names.inc"
+#undef N
+};
+#define COUNT (sizeof(NAMES) / sizeof(NAMES[0]))
+
+static void *real_fn[COUNT];
+static int calls[COUNT];
+static int is_pop[COUNT], is_request[COUNT];
+static void *loader;
+static pthread_once_t once = PTHREAD_ONCE_INIT;
+static pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;
+
+typedef uint32_t (*get_type_t)(const void *);
+typedef uint64_t (*get_id_t)(const void *);
+typedef _Bool (*is_error_t)(const void *);
+static get_type_t msg_type;
+static get_id_t msg_id;
+static is_error_t msg_error;
+
+#define PENDING 256
+static struct { uint64_t id; int fn; double t; } pending[PENDING];
+static double last_report;
+
+static double now(void) {
+    struct timespec ts;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    return ts.tv_sec + ts.tv_nsec * 1e-9;
+}
+
+// accessors read data out of handles; everything else that returns a 64-bit id starts a request
+static int looks_like_request(const char *n) {
+    static const char *const accessors[] = {"ovr_Message_", "Array_", "_Get", "_Is", "_Has", "_Create", "_Destroy",
+                                            "_Set", "_Free", "ovr_PopMessage", "ovr_Platform", "ovr_GetLoggedInUser",
+                                            "ovr_Error_", "Options_", "ovr_Voip_", "ovr_Net_", "ovr_Microphone_"};
+    for (size_t i = 0; i < sizeof(accessors) / sizeof(accessors[0]); ++i)
+        if (strstr(n, accessors[i])) return 0;
+    return 1;
+}
+
+static void init(void) {
+    loader = dlopen("libovrplatformloader.so", RTLD_NOW | RTLD_NOLOAD);
+    if (!loader) loader = dlopen("libovrplatformloader.so", RTLD_NOW);
+    for (size_t i = 0; i < COUNT; ++i) {
+        is_pop[i] = !strcmp(NAMES[i], "ovr_PopMessage");
+        is_request[i] = looks_like_request(NAMES[i]);
+        // "requests" whose names start with Get (e.g. ovr_User_GetLoggedInUser): Area_GetX with an upper-case X
+        const char *u = strchr(NAMES[i] + 4, '_');
+        if (u && !strncmp(u, "_Get", 4) && strncmp(NAMES[i], "ovr_Message_", 12) && !strstr(NAMES[i], "Array_"))
+            is_request[i] = 2;  // maybe: kept only when the result looks like a request id
+    }
+    if (loader) {
+        msg_type = (get_type_t)dlsym(loader, "ovr_Message_GetType");
+        msg_id = (get_id_t)dlsym(loader, "ovr_Message_GetRequestID");
+        msg_error = (is_error_t)dlsym(loader, "ovr_Message_IsError");
+    }
+    LOG("tracer active: %zu functions, platform loader %s", COUNT, loader ? "OK" : "MISSING");
+    last_report = now();
+}
+
+void *fp_trace_before(uint64_t idx, uint64_t arg0) __attribute__((visibility("hidden")));
+void *fp_trace_before(uint64_t idx, uint64_t arg0) {
+    pthread_once(&once, init);
+    if (idx >= COUNT) return NULL;
+    if (!real_fn[idx] && loader) real_fn[idx] = dlsym(loader, NAMES[idx]);
+    int n = __atomic_add_fetch(&calls[idx], 1, __ATOMIC_RELAXED);
+    if (n <= 3 && !is_pop[idx]) LOG("call %s(0x%llx)%s", NAMES[idx], (unsigned long long)arg0,
+                                    real_fn[idx] ? "" : " - not in the loader: returns 0");
+    return real_fn[idx];
+}
+
+static void report_pending(double t) {
+    int shown = 0;
+    for (int i = 0; i < PENDING; ++i) {
+        if (!pending[i].id) continue;
+        if (shown++ < 12)
+            LOG("unanswered after %.0f s: request %llu from %s", t - pending[i].t, (unsigned long long)pending[i].id,
+                NAMES[pending[i].fn]);
+    }
+    if (shown) LOG("%d request(s) without an answer", shown);
+}
+
+uint64_t fp_trace_after(uint64_t idx, uint64_t ret) __attribute__((visibility("hidden")));
+uint64_t fp_trace_after(uint64_t idx, uint64_t ret) {
+    if (idx >= COUNT) return ret;
+    double t = now();
+    pthread_mutex_lock(&lock);
+    if (is_pop[idx]) {
+        if (ret && msg_type && msg_id) {
+            const void *m = (const void *)(uintptr_t)ret;
+            uint64_t id = msg_id(m);
+            int answered = -1;
+            for (int i = 0; i < PENDING; ++i)
+                if (pending[i].id && pending[i].id == id) { answered = pending[i].fn; pending[i].id = 0; break; }
+            LOG("message type=0x%08x request=%llu error=%d%s%s", msg_type(m), (unsigned long long)id,
+                msg_error ? msg_error(m) : -1, answered >= 0 ? " answers " : "", answered >= 0 ? NAMES[answered] : "");
+        }
+    } else {
+        int n = calls[idx];
+        if (n <= 3) LOG("  %s -> 0x%llx", NAMES[idx], (unsigned long long)ret);
+        // request ids are small positive counters; pointers (handles) are large
+        if (is_request[idx] && ret && ret < (1ull << 40)) {
+            for (int i = 0; i < PENDING; ++i)
+                if (!pending[i].id) { pending[i].id = ret; pending[i].fn = (int)idx; pending[i].t = t; break; }
+            if (n <= 20) LOG("request %llu <- %s", (unsigned long long)ret, NAMES[idx]);
+        }
+    }
+    if (t - last_report >= 10.0) {
+        last_report = t;
+        report_pending(t);
+    }
+    pthread_mutex_unlock(&lock);
+    return ret;
+}
+
+// The shared stub: x16 = function index. Saves the argument registers, gets the real function, calls it with them,
+// reports the result. x8 (indirect result) and d0-d7 (float/HFA arguments) are preserved, x0/x1/d0-d3 returned.
+__asm__(
+    ".text\n"
+    ".p2align 2\n"
+    "fp_trace_common:\n"
+    "  stp x29, x30, [sp, #-224]!\n"
+    "  mov x29, sp\n"
+    "  stp x0, x1, [sp, #16]\n"
+    "  stp x2, x3, [sp, #32]\n"
+    "  stp x4, x5, [sp, #48]\n"
+    "  stp x6, x7, [sp, #64]\n"
+    "  stp d0, d1, [sp, #80]\n"
+    "  stp d2, d3, [sp, #96]\n"
+    "  stp d4, d5, [sp, #112]\n"
+    "  stp d6, d7, [sp, #128]\n"
+    "  stp x8, x16, [sp, #144]\n"
+    "  mov x0, x16\n"
+    "  ldr x1, [sp, #16]\n"
+    "  bl fp_trace_before\n"
+    "  str x0, [sp, #160]\n"
+    "  ldp x0, x1, [sp, #16]\n"
+    "  ldp x2, x3, [sp, #32]\n"
+    "  ldp x4, x5, [sp, #48]\n"
+    "  ldp x6, x7, [sp, #64]\n"
+    "  ldp d0, d1, [sp, #80]\n"
+    "  ldp d2, d3, [sp, #96]\n"
+    "  ldp d4, d5, [sp, #112]\n"
+    "  ldp d6, d7, [sp, #128]\n"
+    "  ldr x8, [sp, #144]\n"
+    "  ldr x17, [sp, #160]\n"
+    "  cbz x17, 1f\n"
+    "  blr x17\n"
+    "  b 2f\n"
+    "1:\n"
+    "  mov x0, #0\n"
+    "  mov x1, #0\n"
+    "  movi d0, #0\n"
+    "2:\n"
+    "  stp x0, x1, [sp, #16]\n"
+    "  stp d0, d1, [sp, #80]\n"
+    "  stp d2, d3, [sp, #96]\n"
+    "  ldr x0, [sp, #152]\n"
+    "  ldr x1, [sp, #16]\n"
+    "  bl fp_trace_after\n"
+    "  ldp x0, x1, [sp, #16]\n"
+    "  ldp d0, d1, [sp, #80]\n"
+    "  ldp d2, d3, [sp, #96]\n"
+    "  ldp x29, x30, [sp], #224\n"
+    "  ret\n");
+
+// one exported stub per name: x16 = its index
+#define STR2(x) #x
+#define STR(x) STR2(x)
+static const int dummy_index_base __attribute__((unused)) = 0;
+#define N(name)                                                    \
+    __asm__(".text\n.p2align 2\n.globl " #name "\n.type " #name ", %function\n" #name ":\n" \
+            "  mov x16, #" STR(__COUNTER__) "\n  b fp_trace_common\n");
+#include "names.inc"
+#undef N

native/venc/SPEC.md

@@ -0,0 +1,215 @@
+# fp_venc — specification
+
+A small program that runs **on the Steam Frame** (SteamOS, aarch64 Linux with glibc) and hardware-encodes the
+SteamVR "headset view" webcam to an H.264 elementary stream on stdout. FramePort's live view (PC side) pipes that
+stream into ffmpeg on the Frame, which adds sound and packs fragmented MP4. The program is used for **live viewing
+only**: low latency, constant bitrate, evenly spaced frames, a keyframe whenever the viewer side asks for one.
+
+Sources: the Linux kernel's V4L2 documentation (`Documentation/userspace-api/media/v4l/dev-encoder.rst` = the
+memory-to-memory stateful encoder interface, `ext-ctrls-codec.rst`, `buffer.rst`, `vidioc-*.rst`), the DRM KMS UAPI
+(`drm_mode.h`), and the facts measured on the Frame listed in "Measured facts". Nothing else.
+
+## Files
+- `native/venc/convert.h`, `convert.c` — the picture converter (pure computation, no syscalls). Must compile for
+  **aarch64** (NEON path + scalar path) **and x86_64** (scalar path only; used by the host unit test).
+- `native/venc/sys.h` (+ `.c` if wanted) — raw Linux aarch64 syscalls (`svc #0`), `_start`, `memcpy`/`memset`/`memmove`
+  (the compiler may emit calls to them), small string/number helpers (parse decimal, print decimal, write a whole buffer).
+- `native/venc/fp_venc.c` — command line, source, encoder, DRM refresh query, main loop.
+- `native/venc/include/sys/time.h` — minimal stub so the kernel UAPI `linux/videodev2.h` compiles without a libc
+  (`struct timeval { long tv_sec; long tv_usec; };` and whatever else that header needs).
+- `native/build.py` — a `build_venc(tc)` step (see "Build").
+
+Keep it small and readable: plain C11, no clever macros, comments that explain *why*. Target ≤ ~900 lines total.
+
+## Build
+No libc exists at build time (the toolchain is the Android NDK's clang; its sysroot is bionic). The program is a fully
+static, freestanding executable:
+
+```
+clang --target=aarch64-linux-gnu -ffreestanding -nostdlib -nostdlibinc -static -fno-stack-protector
+      -fno-builtin -O2 -Wall -Wextra -Werror -fuse-ld=lld -Wl,--build-id=none -Wl,-z,max-page-size=65536
+      -e _start -I native/venc/include -I <uapi> -ffile-prefix-map=<native dir>=native
+      fp_venc.c convert.c [sys.c] -o artifacts/linux-arm64-bin/fp_venc
+```
+- `<uapi>`: a staging directory made by build.py under `native/.cache/uapi-arm64/` containing **only** copies of the
+  NDK sysroot's kernel UAPI folders `usr/include/linux`, `usr/include/asm-generic`, `usr/include/drm` and
+  `usr/include/aarch64-linux-android/asm` (as `asm/`). Never put the bionic libc headers on the include path.
+- `stdint.h`, `stddef.h`, `stdbool.h` and `arm_neon.h` come from clang's own resource directory (allowed).
+- Floating point is allowed but not needed; prefer integer math.
+- Add `venc` to build.py's `--only` default list, the docstring, the `steps` dict and the ordered build tuple (last).
+  The step creates `artifacts/linux-arm64-bin/` itself (not `linux-arm64/`: that folder is uploaded whole as the OpenXR layer). `write_sums()` then lists the new file.
+- The binary must be reproducible (same source → same bytes) and contain no local paths.
+
+## Command line
+```
+fp_venc [--height N] [--bitrate BPS] [--peak BPS] [--fps N] [--max-fps N] [--gop-seconds N]
+        [--source PATH] [--encoder PATH] [--probe | --selftest]
+```
+- `--height N`: output height, scaled **down** only. Default: the source height. See "Output size".
+- `--bitrate BPS`: target bitrate in bit/s. Default 3000000.
+- `--peak BPS`: above the bitrate = VBR capped at this peak (the live view uses 1.5×), else CBR.
+- `--fps N`: output frame rate; overrides the automatic choice.
+- `--max-fps N`: cap for the automatic choice. Default 45.
+- `--gop-seconds N`: keyframe interval in seconds. Default 4.
+- `--source PATH`: V4L2 capture device. Default: the `/dev/videoN` whose `/sys/class/video4linux/videoN/name` is
+  exactly `SteamVR` (strip the trailing newline).
+- `--encoder PATH`: the encoder node. Default: `/dev/video-enc0` if it exists, else the first
+  `/sys/class/video4linux/videoN` whose `name` contains `encoder` and that passes the capability check below.
+- `--probe`: do every setup step up to and including buffer allocation (no STREAMON, no frames), print the info JSON
+  (below) on **stdout**, exit.
+- `--selftest`: run the converter self-test (below) and exit. Needs no devices.
+
+Exit codes: 0 ok · 1 self-test failed / runtime error after streaming started · 2 bad arguments · 3 no source
+device · 4 hardware encoder not usable (missing, wrong caps, a required format refused, any setup ioctl failed).
+When the environment variable `FP_VENC_DISABLE=1` is set, setup fails with exit 4 (used to test the fallback).
+The environment is on the stack after argv (`_start`: `argc` at `[sp]`, `argv` at `sp+8`, `envp` after argv's NULL).
+
+### Info JSON
+One line, keys in this order, no spaces:
+`{"encoder":"/dev/video23","source":"/dev/video99","src":[1920,1080],"out":[1280,720],"refresh":96,"fps":32,"bitrate":3000000}`
+`refresh` is the panel rate in whole Hz (0 when unknown). In normal (streaming) mode the same line is written to
+**stderr** right after setup, prefixed `fp_venc: info ` — the PC side reads it for its status line.
+
+## Frame rate
+1. Read the panel's current refresh rate through DRM (read-only, no master needed; `/dev/dri/card0` is mode 0666 on
+   the Frame): open `/dev/dri/card0` (`O_RDWR|O_CLOEXEC`), `DRM_IOCTL_MODE_GETRESOURCES` once for the counts and
+   once more with an array for the CRTC ids, then `DRM_IOCTL_MODE_GETCRTC` for each. Among CRTCs with `mode_valid`,
+   take the one with the largest `hdisplay × vdisplay`. Rate in milli-Hz = `clock(kHz) × 1 000 000 / (htotal × vtotal)`;
+   round to whole Hz. Any failure → refresh unknown.
+2. `fps` = `--fps` if given; else if the refresh is known: `refresh / ceil(refresh / max_fps)` (integer division,
+   rounded to nearest): 72→36, 80→40, 90→45, 96→32, 108→36, 120→40, 144→36; else 30.
+Rationale: frames on an even grid of the panel's refresh look smooth; 30 fps on a 72/96 Hz panel judders.
+
+## Output size
+`out_h = min(--height or src_h, src_h)`, rounded **down** to even. `out_w = floor(src_w × out_h / src_h)` rounded down
+to even. Both ≥ 2. (1920×1080 → 360: 640×360; 480: 852×480; 720: 1280×720; 1080: 1920×1080.)
+
+## Converter (`convert.h`)
+```c
+#include <stdint.h>
+#include <stddef.h>
+void   fp_out_size(int src_w, int src_h, int max_h, int *out_w, int *out_h);   /* rule above; max_h <= 0 = src_h */
+size_t fp_scratch_size(int src_w, int src_h, int out_w, int out_h);           /* bytes of scratch fp_convert needs */
+/* RGB24 (R,G,B bytes) → NV12 (BT.709, limited range). Writes out_w×out_h luma and out_w×out_h/2 interleaved CbCr. */
+void   fp_convert_scalar(const uint8_t *src, int src_w, int src_h, int src_stride,
+                         uint8_t *y, int y_stride, uint8_t *uv, int uv_stride,
+                         int out_w, int out_h, void *scratch);
+void   fp_convert(/* same parameters */);   /* NEON on aarch64; identical to fp_convert_scalar elsewhere */
+```
+Both functions must produce **bit-identical** output; the exact definition is:
+
+1. **Scaling (box average).** For output column `i` the source columns are `[x0, x1)` with
+   `x0 = i·src_w / out_w`, `x1 = (i+1)·src_w / out_w` (integer division); rows likewise with `src_h/out_h`. Each
+   channel of output pixel (i, j) is `(S + n/2) / n` (integer division), `S` = sum of that channel over the block,
+   `n` = block width × block height. When the size is unchanged this is the identity.
+2. **Luma** from each scaled pixel (R, G, B):
+   `Y = 16 + ((47·R + 157·G + 16·B + 128) >> 8)`.
+3. **Chroma** per 2×2 block of scaled pixels: first average each channel, `C = (c00 + c01 + c10 + c11 + 2) >> 2`,
+   then `Cb = 128 + ((−26·R − 86·G + 112·B + 128) >> 8)`, `Cr = 128 + ((112·R − 102·G − 10·B + 128) >> 8)`
+   (`>>` on a signed 32-bit value = floor division by 256). Write Cb then Cr.
+4. Clamp Y to [16, 235] and Cb/Cr to [16, 240] (the formulas already stay inside; clamp anyway).
+The input is sRGB-encoded full-range RGB; no linearisation (video expects gamma-encoded values).
+
+**Performance:** at 1920×1080 → 1920×1080 the aarch64 `fp_convert` should take ≤ 4 ms per frame on one core; scaled
+outputs not more. Suggested shape (free to differ if output stays identical): NEON vertical accumulation of the rows of
+each output row into a uint16/uint32 row buffer, horizontal block sums + division (a per-block-size reciprocal table is
+fine only if it is exact for every possible sum; otherwise divide), NEON colour conversion with `vld3`/widening
+multiplies. The identity size gets a direct NEON path (no box step). Exact 3:2 and 3:1 ratios (720p and 360p from
+1080p) get their own NEON paths: the boxes repeat every 3 source pixels (widths 1,2 resp. 3), so the averages are
+rounding shifts / an exact multiply (×7282 >> 16 = ÷9 for every possible sum). The self-test covers them, including
+columns left over after the 48-pixel steps (1158×648 → 432/216).
+
+### Self-test (`--selftest`)
+Deterministic synthetic images (a 32-bit LCG noise image, a horizontal gradient, solid black/white/red/green/blue,
+a 1-pixel checkerboard) at source sizes 1920×1080, 1922×1080, 333×201 and 64×64, each converted for max heights
+{source height, 720, 480, 360, 100} where ≤ source height. `fp_convert` must equal `fp_convert_scalar` byte for byte
+(Y and UV planes, using strides larger than the width to catch stride bugs). Print `fp_venc: selftest ok (N cases)` or
+the first mismatch (size, plane, x, y, both values) on stderr; exit 0/1. Also time 50 conversions 1920×1080→1080 and
+→720 and print the average ms each.
+
+## Source (V4L2 capture, `/dev/video99`)
+v4l2loopback device written by SteamVR's `v4l2cam` (single-planar `V4L2_BUF_TYPE_VIDEO_CAPTURE`).
+- Open `O_RDWR|O_NONBLOCK|O_CLOEXEC`. `VIDIOC_QUERYCAP`: needs `V4L2_CAP_VIDEO_CAPTURE` + `V4L2_CAP_STREAMING`
+  (check `device_caps` when `V4L2_CAP_DEVICE_CAPS` is set). `VIDIOC_G_FMT`: pixelformat must be `V4L2_PIX_FMT_RGB24`
+  (else exit 4); use its width, height and `bytesperline` (0 → width×3).
+- `VIDIOC_REQBUFS` 3 × `V4L2_MEMORY_MMAP`, `VIDIOC_QUERYBUF` + `mmap(PROT_READ, MAP_SHARED)` each, `VIDIOC_QBUF` all,
+  `VIDIOC_STREAMON`.
+- At most one dequeued buffer is held (the newest frame). When a newer one is dequeued, re-queue the held one first.
+  Drain all ready buffers on each wake-up so the held one is always the newest.
+
+## Encoder (V4L2 memory-to-memory, multi-planar)
+Follow the "Initialization" and "Encoding" sections of `dev-encoder.rst`:
+1. Open `O_RDWR|O_NONBLOCK|O_CLOEXEC`. `VIDIOC_QUERYCAP`: needs `V4L2_CAP_VIDEO_M2M_MPLANE` and
+   `V4L2_CAP_STREAMING` (in `device_caps`).
+2. **Coded format first** — `VIDIOC_S_FMT` on `V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`: `pixelformat = V4L2_PIX_FMT_H264`,
+   width/height = out size, `num_planes = 1`. Must come back as H264 (else exit 4). Its `sizeimage` is the size of
+   the encoded-frame buffers.
+3. **Raw format** — `VIDIOC_S_FMT` on `V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`: `V4L2_PIX_FMT_NV12`, out size,
+   `num_planes = 1`, `colorspace = V4L2_COLORSPACE_REC709`, `ycbcr_enc = V4L2_YCBCR_ENC_709`,
+   `quantization = V4L2_QUANTIZATION_LIM_RANGE`, `xfer_func = V4L2_XFER_FUNC_709`. Use what comes back:
+   `num_planes` must be 1 (else exit 4); `stride = plane_fmt[0].bytesperline`; the returned `height` is the padded
+   height `H'`; the CbCr plane starts at `stride × H'` inside the same buffer; require
+   `stride × H' × 3/2 ≤ plane_fmt[0].sizeimage` and `stride ≥ out_w` (else exit 4).
+4. **Visible rectangle** — `VIDIOC_S_SELECTION` (type `V4L2_BUF_TYPE_VIDEO_OUTPUT`, target `V4L2_SEL_TGT_CROP`,
+   rect 0,0,out_w,out_h). If the driver rejects the single-planar type, retry with the `_MPLANE` type. Failure is only
+   a warning when `G_SELECTION` already reports that rectangle.
+5. **Frame rate** — `VIDIOC_S_PARM` on the OUTPUT queue: `timeperframe = 1/fps` (warning on failure).
+6. **Controls** — `VIDIOC_S_EXT_CTRLS` (or `VIDIOC_S_CTRL` one by one), each best-effort: a refused control prints
+   `fp_venc: warning: <name> refused (<errno>)` and continues:
+   - `V4L2_CID_MPEG_VIDEO_H264_PROFILE` = HIGH; `V4L2_CID_MPEG_VIDEO_H264_LEVEL` = the lowest level whose limits
+     (H.264 Table A-1: MaxFS macroblocks per frame, MaxMBPS macroblocks per second, MaxBR ×1.25 for High in kbit/s)
+     fit out size × fps × bitrate, among 3.1, 3.2, 4, 4.1, 4.2, 5, 5.1, 5.2;
+   - `V4L2_CID_MPEG_VIDEO_BITRATE_MODE` = CBR; `V4L2_CID_MPEG_VIDEO_BITRATE` = bitrate;
+     `V4L2_CID_MPEG_VIDEO_BITRATE_PEAK` = bitrate; `V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE` = 1;
+   - `V4L2_CID_MPEG_VIDEO_B_FRAMES` = 0; `V4L2_CID_MPEG_VIDEO_GOP_SIZE` = fps × gop_seconds;
+   - `V4L2_CID_MPEG_VIDEO_HEADER_MODE` = JOINED_WITH_1ST_FRAME; `V4L2_CID_MPEG_VIDEO_PREPEND_SPSPPS_TO_IDR` = 1
+     (every keyframe is decodable on its own — a viewer may join at any keyframe);
+   - `V4L2_CID_MPEG_VIDEO_FRAME_SKIP_MODE` = DISABLED (one output frame per input frame: the PC side derives
+     timestamps from the frame count).
+7. **Buffers** — `VIDIOC_REQBUFS` OUTPUT_MPLANE 4 × MMAP and CAPTURE_MPLANE 4 × MMAP; `VIDIOC_QUERYBUF` + `mmap` every
+   buffer (OUTPUT: read/write, fill with Y=16/CbCr=128 once so padding rows are defined; CAPTURE: read).
+   (`--probe` stops here: print the JSON, exit 0.)
+8. Queue all CAPTURE buffers, `VIDIOC_STREAMON` both queues.
+9. Per frame: write NV12 into a free OUTPUT buffer (`bytesused` = sizeimage), `VIDIOC_QBUF`. Dequeue finished OUTPUT
+   buffers (they become free). Dequeue CAPTURE buffers: write `bytesused − data_offset` bytes from
+   `mem + data_offset` to stdout, re-queue. `V4L2_BUF_FLAG_ERROR` on a capture buffer: re-queue, count, don't write.
+   `V4L2_BUF_FLAG_LAST`: the encoder is drained.
+10. **Keyframe on request** — set `V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME` (button) just before queuing the next frame.
+11. **Stop** — `VIDIOC_ENCODER_CMD` `V4L2_ENC_CMD_STOP`, keep dequeuing/writing CAPTURE buffers until one has
+    `V4L2_BUF_FLAG_LAST` (or 1 s passes), `VIDIOC_STREAMOFF` both queues, close, exit 0.
+
+## Main loop and timing
+- Ignore `SIGPIPE` (`rt_sigaction` with `SIG_IGN`; no restorer needed for SIG_IGN) so a closed stdout is an `EPIPE`
+  error → stop quietly (exit 0).
+- **stdin protocol** (stdin is the SSH channel; non-blocking reads after `poll`): byte `k` = request a keyframe;
+  byte `q` or end of file = stop (step 11); other bytes ignored.
+- **Fixed frame grid.** `t0` = `CLOCK_MONOTONIC` when streaming starts; slot `n` is due at `t0 + n·10⁹/fps` ns.
+  Exactly **one** frame is queued per slot, always: at slot time, convert the held (newest) source frame — even if it
+  was already used, e.g. while the headset is in standby the source delivers ~1 fps — so the stream's frame count
+  always equals elapsed time × fps. The ffmpeg side relies on that (`-framerate fps`, no timestamps in the stream).
+  Before the first source frame arrives, submit black frames (Y=16, CbCr=128).
+- If no OUTPUT buffer is free at slot time, wait for one (it's the encoder's latency; normal is a few ms). If the loop
+  falls behind (several slots due), submit the missed slots back to back with the same picture. If more than `fps`
+  slots (1 s) are missed at once (e.g. the process was stopped), log it, skip forward to the current slot and continue.
+- Wait with `ppoll` on: source fd (POLLIN), encoder fd (POLLIN = capture ready, POLLOUT = output buffer done),
+  stdin (POLLIN|POLLHUP), timeout = time to the next slot.
+- stdout writes are blocking writes of whole packets (loop over partial writes; `EINTR`/`EAGAIN` retry).
+- Every 10 s print one stderr line: `fp_venc: stats frames=<n> repeats=<frames that reused an already-sent picture>
+  late=<slots submitted late> skipped=<slots skipped> kbps=<average output bitrate>`.
+- All stderr lines start with `fp_venc: `. No output on stdout except the H.264 stream (or the probe JSON).
+
+## Measured facts (the Frame, SteamOS 0.3.0 kernel 6.18, 2026-10-07)
+- Encoder: `/dev/video23` (`/dev/video-enc0` → it), name `qcom-iris-encoder`, driver `iris_driver`, caps
+  M2M multiplanar + streaming. OUTPUT formats: Q08C, NV12, NV21, AB24, QC24. CAPTURE formats: H264, HEVC. Frame sizes
+  128×128 … 8192×8192 step 1. The `steamos` user can open it (group `video`).
+- NV12 S_FMT results (stride / returned height / sizeimage): 640×360 → 640/384/368640; 854×480 → 896/480/647168;
+  1280×720 → 1280/736/1413120; 1920×1080 → 1920/1088/3133440. Default OUTPUT crop = the requested size.
+- Controls present: B_FRAMES (0–7), GOP_SIZE, BITRATE_MODE (VBR, CBR), BITRATE / BITRATE_PEAK (≤ 245 000 000),
+  FRAME_RC_ENABLE, HEADER_MODE (separate, joined with 1st frame), FORCE_KEY_FRAME, H264 PROFILE (Baseline, Constrained
+  Baseline, Main, High, Constrained High), H264 LEVEL (1 … 6.0, default 5), PREPEND_SPSPPS_TO_IDR, FRAME_SKIP_MODE,
+  H264 entropy (CABAC default), I/P QP ranges, intra-refresh period, LTR, hierarchical coding.
+- Source: `/dev/video99`, v4l2loopback, name `SteamVR`, single-planar capture, RGB24 only, 1920×1080, bytesperline
+  5760, advertised 30 fps but frames come at the panel rate when worn, ~1.1 fps in standby.
+- DRM: `/dev/dri/card0` (msm, mode 0666); one active CRTC 4320×2160 (`2*2160x2160_96`, clock 1402720 kHz,
+  htotal 4448, vtotal 3285 → 96.00 Hz). The panel offers 72/80/90/96/108/120/144 Hz.
+- ffmpeg's stock `h264_v4l2m2m` hangs on this encoder; that's why this program exists.

native/venc/convert.c

@@ -0,0 +1,356 @@
+/* RGB24 -> NV12 converter (see convert.h and SPEC.md "Converter"). The scalar code is the definition; the NEON code
+ * must produce the same bytes (fp_venc --selftest compares them). */
+#include "convert.h"
+
+#if defined(__aarch64__)
+#include <arm_neon.h>
+#endif
+
+void fp_out_size(int src_w, int src_h, int max_h, int *out_w, int *out_h)
+{
+    int h = (max_h <= 0 || max_h > src_h) ? src_h : max_h;
+    h &= ~1;
+    int w = (int)((int64_t)src_w * h / src_h) & ~1;
+    *out_w = w < 2 ? 2 : w;
+    *out_h = h < 2 ? 2 : h;
+}
+
+static size_t align16(size_t n) { return (n + 15) & ~(size_t)15; }
+
+/* Scratch layout for scaled output: per-column channel sums of the current output row's source rows (uint32, or
+ * uint16 in the NEON path), the source column where each output column starts, and two scaled RGB rows (one NV12
+ * row pair: chroma needs both). */
+size_t fp_scratch_size(int src_w, int src_h, int out_w, int out_h)
+{
+    (void)src_h;
+    (void)out_h;
+    return align16((size_t)src_w * 3 * 4) + align16(((size_t)out_w + 1) * 4) + align16((size_t)out_w * 6 + 16);
+}
+
+static uint8_t clamp_u8(int v, int lo, int hi) { return (uint8_t)(v < lo ? lo : v > hi ? hi : v); }
+
+/* BT.709 limited range. `>>` on a negative int is an arithmetic (floor) shift with clang/gcc on every target we
+ * build for, which is what the spec's formula means. */
+static uint8_t luma(int r, int g, int b) { return clamp_u8(16 + ((47 * r + 157 * g + 16 * b + 128) >> 8), 16, 235); }
+static uint8_t cb_of(int r, int g, int b) { return clamp_u8(128 + ((-26 * r - 86 * g + 112 * b + 128) >> 8), 16, 240); }
+static uint8_t cr_of(int r, int g, int b) { return clamp_u8(128 + ((112 * r - 102 * g - 10 * b + 128) >> 8), 16, 240); }
+
+/* One NV12 row pair from two RGB rows, columns [x, w) (w even). */
+static void pair_scalar(const uint8_t *r0, const uint8_t *r1, int x, int w, uint8_t *y0, uint8_t *y1, uint8_t *uv)
+{
+    for (; x < w; x += 2) {
+        const uint8_t *a = r0 + x * 3, *b = r1 + x * 3;
+        y0[x] = luma(a[0], a[1], a[2]);
+        y0[x + 1] = luma(a[3], a[4], a[5]);
+        y1[x] = luma(b[0], b[1], b[2]);
+        y1[x + 1] = luma(b[3], b[4], b[5]);
+        int r = (a[0] + a[3] + b[0] + b[3] + 2) >> 2;
+        int g = (a[1] + a[4] + b[1] + b[4] + 2) >> 2;
+        int bl = (a[2] + a[5] + b[2] + b[5] + 2) >> 2;
+        uv[x] = cb_of(r, g, bl);
+        uv[x + 1] = cr_of(r, g, bl);
+    }
+}
+
+struct layout { uint32_t *colsum; int32_t *xb; uint8_t *rgb; };
+
+static struct layout split(void *scratch, int src_w, int out_w)
+{
+    struct layout l;
+    uint8_t *p = scratch;
+    l.colsum = (uint32_t *)p;
+    p += align16((size_t)src_w * 3 * 4);
+    l.xb = (int32_t *)p;
+    p += align16(((size_t)out_w + 1) * 4);
+    l.rgb = p;
+    for (int i = 0; i <= out_w; i++) l.xb[i] = (int32_t)((int64_t)i * src_w / out_w);
+    return l;
+}
+
+void fp_convert_scalar(const uint8_t *src, int src_w, int src_h, int src_stride,
+                       uint8_t *y, int y_stride, uint8_t *uv, int uv_stride,
+                       int out_w, int out_h, void *scratch)
+{
+    if (out_w == src_w && out_h == src_h) {
+        for (int j = 0; j < out_h; j += 2)
+            pair_scalar(src + (size_t)j * src_stride, src + (size_t)(j + 1) * src_stride, 0, out_w,
+                        y + (size_t)j * y_stride, y + (size_t)(j + 1) * y_stride, uv + (size_t)(j / 2) * uv_stride);
+        return;
+    }
+    struct layout l = split(scratch, src_w, out_w);
+    int cols = src_w * 3;
+    for (int j = 0; j < out_h; j++) {
+        int ya = (int)((int64_t)j * src_h / out_h), yb = (int)((int64_t)(j + 1) * src_h / out_h);
+        for (int k = 0; k < cols; k++) l.colsum[k] = 0;
+        for (int r = ya; r < yb; r++) {
+            const uint8_t *row = src + (size_t)r * src_stride;
+            for (int k = 0; k < cols; k++) l.colsum[k] += row[k];
+        }
+        uint8_t *out = l.rgb + (size_t)(j & 1) * out_w * 3;
+        for (int i = 0; i < out_w; i++) {
+            int xa = l.xb[i], xe = l.xb[i + 1];
+            uint64_t n = (uint64_t)(xe - xa) * (uint64_t)(yb - ya);
+            for (int c = 0; c < 3; c++) {
+                uint64_t s = 0;
+                for (int x = xa; x < xe; x++) s += l.colsum[x * 3 + c];
+                out[i * 3 + c] = (uint8_t)((s + n / 2) / n);
+            }
+        }
+        if (j & 1)
+            pair_scalar(l.rgb, l.rgb + (size_t)out_w * 3, 0, out_w, y + (size_t)(j - 1) * y_stride,
+                        y + (size_t)j * y_stride, uv + (size_t)(j / 2) * uv_stride);
+    }
+}
+
+#if defined(__aarch64__)
+
+/* 16 pixels of 2 rows -> 32 luma bytes + 8 CbCr pairs. All intermediates fit: luma sums <= 220*255+128 < 2^16
+ * (uint16), chroma partial sums stay within +-28688 (int16). vrshrn_n_u16(x, 8) == (x + 128) >> 8 and
+ * vrshrq_n_u16(x, 2) == (x + 2) >> 2 exactly (the rounding add is done without overflow). */
+static inline uint8x16_t luma16(uint8x16x3_t p)
+{
+    uint16x8_t lo = vmull_u8(vget_low_u8(p.val[0]), vdup_n_u8(47));
+    lo = vmlal_u8(lo, vget_low_u8(p.val[1]), vdup_n_u8(157));
+    lo = vmlal_u8(lo, vget_low_u8(p.val[2]), vdup_n_u8(16));
+    uint16x8_t hi = vmull_u8(vget_high_u8(p.val[0]), vdup_n_u8(47));
+    hi = vmlal_u8(hi, vget_high_u8(p.val[1]), vdup_n_u8(157));
+    hi = vmlal_u8(hi, vget_high_u8(p.val[2]), vdup_n_u8(16));
+    uint8x16_t yv = vaddq_u8(vcombine_u8(vrshrn_n_u16(lo, 8), vrshrn_n_u16(hi, 8)), vdupq_n_u8(16));
+    return vminq_u8(vmaxq_u8(yv, vdupq_n_u8(16)), vdupq_n_u8(235));
+}
+
+static inline uint8x8_t chroma8(int16x8_t r, int16x8_t g, int16x8_t b, int16_t kr, int16_t kg, int16_t kb)
+{
+    int16x8_t v = vmulq_n_s16(r, kr);
+    v = vmlaq_n_s16(v, g, kg);
+    v = vmlaq_n_s16(v, b, kb);
+    v = vshrq_n_s16(vaddq_s16(v, vdupq_n_s16(128)), 8);              /* arithmetic = floor */
+    v = vaddq_s16(v, vdupq_n_s16(128));
+    v = vminq_s16(vmaxq_s16(v, vdupq_n_s16(16)), vdupq_n_s16(240));
+    return vqmovun_s16(v);
+}
+
+static void pair_neon(const uint8_t *r0, const uint8_t *r1, int w, uint8_t *y0, uint8_t *y1, uint8_t *uv)
+{
+    int x = 0;
+    for (; x + 16 <= w; x += 16) {
+        uint8x16x3_t a = vld3q_u8(r0 + x * 3), b = vld3q_u8(r1 + x * 3);
+        vst1q_u8(y0 + x, luma16(a));
+        vst1q_u8(y1 + x, luma16(b));
+        int16x8_t rr = vreinterpretq_s16_u16(vrshrq_n_u16(vpadalq_u8(vpaddlq_u8(a.val[0]), b.val[0]), 2));
+        int16x8_t gg = vreinterpretq_s16_u16(vrshrq_n_u16(vpadalq_u8(vpaddlq_u8(a.val[1]), b.val[1]), 2));
+        int16x8_t bb = vreinterpretq_s16_u16(vrshrq_n_u16(vpadalq_u8(vpaddlq_u8(a.val[2]), b.val[2]), 2));
+        uint8x8x2_t c;
+        c.val[0] = chroma8(rr, gg, bb, -26, -86, 112);
+        c.val[1] = chroma8(rr, gg, bb, 112, -102, -10);
+        vst2_u8(uv + x, c);
+    }
+    pair_scalar(r0, r1, x, w, y0, y1, uv);
+}
+
+/* Box sums of one output row's source rows, as uint16 (callers ensure rows * 255 fits). */
+static void vsum16(const uint8_t *src, int src_stride, int ya, int yb, int cols, uint16_t *cs)
+{
+    const uint8_t *row = src + (size_t)ya * src_stride;
+    int k = 0;
+    for (; k + 16 <= cols; k += 16) {
+        uint8x16_t v = vld1q_u8(row + k);
+        vst1q_u16(cs + k, vmovl_u8(vget_low_u8(v)));
+        vst1q_u16(cs + k + 8, vmovl_high_u8(v));
+    }
+    for (; k < cols; k++) cs[k] = row[k];
+    for (int r = ya + 1; r < yb; r++) {
+        row = src + (size_t)r * src_stride;
+        k = 0;
+        for (; k + 16 <= cols; k += 16) {
+            uint8x16_t v = vld1q_u8(row + k);
+            vst1q_u16(cs + k, vaddw_u8(vld1q_u16(cs + k), vget_low_u8(v)));
+            vst1q_u16(cs + k + 8, vaddw_high_u8(vld1q_u16(cs + k + 8), v));
+        }
+        for (; k < cols; k++) cs[k] = (uint16_t)(cs[k] + row[k]);
+    }
+}
+
+/* Exact fast paths for the two ratios the live view uses from SteamVR's 1920x1080: 3:2 (720p) and 3:1 (360p). The
+ * box rule (x0 = i * src / out) then repeats every 3 source pixels: 3:2 gives widths 1, 2, 1, 2, ... (rows alike),
+ * 3:1 width 3. Same bytes as the generic path, without its per-pixel scalar loop. */
+
+/* 48 pixels of an RGB row -> ph[c][k] = channel c of pixels 3g+k, g = 0..15. */
+static inline void load48(const uint8_t *row, uint8x16_t ph[3][3])
+{
+    uint8_t planes[3][48];
+    for (int q = 0; q < 3; q++) {
+        uint8x16x3_t p = vld3q_u8(row + q * 48);
+        for (int c = 0; c < 3; c++) vst1q_u8(planes[c] + q * 16, p.val[c]);
+    }
+    for (int c = 0; c < 3; c++) {
+        uint8x16x3_t s = vld3q_u8(planes[c]);
+        ph[c][0] = s.val[0], ph[c][1] = s.val[1], ph[c][2] = s.val[2];
+    }
+}
+
+/* (a + b + c + d + 2) >> 2 for 16 lanes. */
+static inline uint8x16_t avg4(uint8x16_t a, uint8x16_t b, uint8x16_t c, uint8x16_t d)
+{
+    uint16x8_t lo = vaddq_u16(vaddl_u8(vget_low_u8(a), vget_low_u8(b)), vaddl_u8(vget_low_u8(c), vget_low_u8(d)));
+    uint16x8_t hi = vaddq_u16(vaddl_high_u8(a, b), vaddl_high_u8(c, d));
+    return vcombine_u8(vrshrn_n_u16(lo, 2), vrshrn_n_u16(hi, 2));
+}
+
+/* Store even/odd output pixels (16 each per channel) as 32 interleaved RGB pixels. */
+static inline void store_pairs(uint8_t *out, uint8x16_t even[3], uint8x16_t odd[3])
+{
+    uint8x16x3_t a, b;
+    for (int c = 0; c < 3; c++) a.val[c] = vzip1q_u8(even[c], odd[c]), b.val[c] = vzip2q_u8(even[c], odd[c]);
+    vst3q_u8(out, a);
+    vst3q_u8(out + 48, b);
+}
+
+/* 3 source rows -> 2 RGB output rows (3:2 both ways): row a from r0 alone, row b from r1 + r2. */
+static void rows_3to2(const uint8_t *r0, const uint8_t *r1, const uint8_t *r2, int src_w, uint8_t *oa, uint8_t *ob)
+{
+    int x = 0;
+    uint8_t *pa = oa, *pb = ob;
+    for (; x + 48 <= src_w; x += 48, pa += 96, pb += 96) {
+        uint8x16_t a[3][3], b[3][3], c[3][3], ea[3], odda[3], eb[3], oddb[3];
+        load48(r0 + x * 3, a), load48(r1 + x * 3, b), load48(r2 + x * 3, c);
+        for (int ch = 0; ch < 3; ch++) {
+            ea[ch] = a[ch][0];                                              /* 1x1 */
+            odda[ch] = vrhaddq_u8(a[ch][1], a[ch][2]);                      /* 2x1: (s + 1) >> 1 */
+            eb[ch] = vrhaddq_u8(b[ch][0], c[ch][0]);                        /* 1x2 */
+            oddb[ch] = avg4(b[ch][1], b[ch][2], c[ch][1], c[ch][2]);        /* 2x2: (s + 2) >> 2 */
+        }
+        store_pairs(pa, ea, odda);
+        store_pairs(pb, eb, oddb);
+    }
+    for (; x < src_w; x += 3, pa += 6, pb += 6)
+        for (int ch = 0; ch < 3; ch++) {
+            const uint8_t *p0 = r0 + x * 3 + ch, *p1 = r1 + x * 3 + ch, *p2 = r2 + x * 3 + ch;
+            pa[ch] = p0[0];
+            pa[3 + ch] = (uint8_t)((p0[3] + p0[6] + 1) >> 1);
+            pb[ch] = (uint8_t)((p1[0] + p2[0] + 1) >> 1);
+            pb[3 + ch] = (uint8_t)((p1[3] + p1[6] + p2[3] + p2[6] + 2) >> 2);
+        }
+}
+
+/* 3 source rows -> 1 RGB output row (3:1 both ways): (sum of 9 + 4) / 9, the division as *7282 >> 16 (exact for
+ * every sum up to 9 * 255 + 4). */
+static void row_3to1(const uint8_t *r0, const uint8_t *r1, const uint8_t *r2, int src_w, uint8_t *out)
+{
+    int x = 0;
+    uint8_t *p = out;
+    for (; x + 48 <= src_w; x += 48, p += 48) {
+        uint8x16_t a[3][3], b[3][3], c[3][3];
+        load48(r0 + x * 3, a), load48(r1 + x * 3, b), load48(r2 + x * 3, c);
+        uint8x16x3_t o;
+        for (int ch = 0; ch < 3; ch++) {
+            uint16x8_t lo = vdupq_n_u16(4), hi = vdupq_n_u16(4);
+            for (int k = 0; k < 3; k++) {
+                lo = vaddw_u8(vaddw_u8(vaddw_u8(lo, vget_low_u8(a[ch][k])), vget_low_u8(b[ch][k])), vget_low_u8(c[ch][k]));
+                hi = vaddw_high_u8(vaddw_high_u8(vaddw_high_u8(hi, a[ch][k]), b[ch][k]), c[ch][k]);
+            }
+            uint16x4_t m = vdup_n_u16(7282);
+            uint16x8_t qlo = vcombine_u16(vshrn_n_u32(vmull_u16(vget_low_u16(lo), m), 16),
+                                          vshrn_n_u32(vmull_u16(vget_high_u16(lo), m), 16));
+            uint16x8_t qhi = vcombine_u16(vshrn_n_u32(vmull_u16(vget_low_u16(hi), m), 16),
+                                          vshrn_n_u32(vmull_u16(vget_high_u16(hi), m), 16));
+            o.val[ch] = vcombine_u8(vmovn_u16(qlo), vmovn_u16(qhi));
+        }
+        vst3q_u8(p, o);
+    }
+    for (; x < src_w; x += 3, p += 3)
+        for (int ch = 0; ch < 3; ch++) {
+            int s = 4;
+            for (int k = 0; k < 3; k++) s += r0[(x + k) * 3 + ch] + r1[(x + k) * 3 + ch] + r2[(x + k) * 3 + ch];
+            p[ch] = (uint8_t)(s / 9);
+        }
+}
+
+#define MAX_RECIP_BW 64
+
+void fp_convert(const uint8_t *src, int src_w, int src_h, int src_stride,
+                uint8_t *y, int y_stride, uint8_t *uv, int uv_stride,
+                int out_w, int out_h, void *scratch)
+{
+    if (out_w == src_w && out_h == src_h) {
+        for (int j = 0; j < out_h; j += 2)
+            pair_neon(src + (size_t)j * src_stride, src + (size_t)(j + 1) * src_stride, out_w,
+                      y + (size_t)j * y_stride, y + (size_t)(j + 1) * y_stride, uv + (size_t)(j / 2) * uv_stride);
+        return;
+    }
+    if (src_w * 2 == out_w * 3 && src_h * 2 == out_h * 3) {   /* 3:2 (out_h even: whole 3-row groups) */
+        struct layout l = split(scratch, src_w, out_w);
+        uint8_t *a = l.rgb, *b = l.rgb + (size_t)out_w * 3;
+        for (int t = 0; t < out_h / 2; t++) {
+            const uint8_t *r0 = src + (size_t)(3 * t) * src_stride;
+            rows_3to2(r0, r0 + src_stride, r0 + 2 * (size_t)src_stride, src_w, a, b);
+            pair_neon(a, b, out_w, y + (size_t)(2 * t) * y_stride, y + (size_t)(2 * t + 1) * y_stride,
+                      uv + (size_t)t * uv_stride);
+        }
+        return;
+    }
+    if (src_w == out_w * 3 && src_h == out_h * 3) {           /* 3:1 */
+        struct layout l = split(scratch, src_w, out_w);
+        uint8_t *a = l.rgb, *b = l.rgb + (size_t)out_w * 3;
+        for (int j = 0; j < out_h; j += 2) {
+            const uint8_t *r0 = src + (size_t)(3 * j) * src_stride, *r3 = r0 + 3 * (size_t)src_stride;
+            row_3to1(r0, r0 + src_stride, r0 + 2 * (size_t)src_stride, src_w, a);
+            row_3to1(r3, r3 + src_stride, r3 + 2 * (size_t)src_stride, src_w, b);
+            pair_neon(a, b, out_w, y + (size_t)j * y_stride, y + (size_t)(j + 1) * y_stride,
+                      uv + (size_t)(j / 2) * uv_stride);
+        }
+        return;
+    }
+    int bh_max = (src_h + out_h - 1) / out_h + 1;
+    if (bh_max > 257) {   /* uint16 column sums would overflow: extreme downscale, not worth a NEON path */
+        fp_convert_scalar(src, src_w, src_h, src_stride, y, y_stride, uv, uv_stride, out_w, out_h, scratch);
+        return;
+    }
+    struct layout l = split(scratch, src_w, out_w);
+    uint16_t *cs = (uint16_t *)l.colsum;
+    int cols = src_w * 3;
+    for (int j = 0; j < out_h; j++) {
+        int ya = (int)((int64_t)j * src_h / out_h), yb = (int)((int64_t)(j + 1) * src_h / out_h);
+        int bh = yb - ya;
+        vsum16(src, src_stride, ya, yb, cols, cs);
+        /* (S + n/2) / n as a multiply: with m = ceil(2^32 / n) and e = m*n - 2^32 < n, floor(x*m / 2^32) ==
+         * floor(x / n) whenever x*e < 2^32. Here x < 256*n, so n <= 4096 is enough. Otherwise divide. */
+        uint64_t recip[MAX_RECIP_BW + 1];
+        for (int bw = 1; bw <= MAX_RECIP_BW; bw++) {
+            uint64_t n = (uint64_t)bw * bh;
+            recip[bw] = n <= 4096 ? ((1ULL << 32) + n - 1) / n : 0;
+        }
+        uint8_t *out = l.rgb + (size_t)(j & 1) * out_w * 3;
+        for (int i = 0; i < out_w; i++) {
+            int xa = l.xb[i], bw = l.xb[i + 1] - xa;
+            const uint16_t *c = cs + xa * 3;
+            uint32_t sr = 0, sg = 0, sb = 0;
+            for (int x = 0; x < bw; x++, c += 3) sr += c[0], sg += c[1], sb += c[2];
+            uint64_t n = (uint64_t)bw * bh, half = n / 2;
+            uint64_t m = bw <= MAX_RECIP_BW ? recip[bw] : 0;
+            if (m) {
+                out[i * 3] = (uint8_t)(((sr + half) * m) >> 32);
+                out[i * 3 + 1] = (uint8_t)(((sg + half) * m) >> 32);
+                out[i * 3 + 2] = (uint8_t)(((sb + half) * m) >> 32);
+            } else {
+                out[i * 3] = (uint8_t)((sr + half) / n);
+                out[i * 3 + 1] = (uint8_t)((sg + half) / n);
+                out[i * 3 + 2] = (uint8_t)((sb + half) / n);
+            }
+        }
+        if (j & 1)
+            pair_neon(l.rgb, l.rgb + (size_t)out_w * 3, out_w, y + (size_t)(j - 1) * y_stride,
+                      y + (size_t)j * y_stride, uv + (size_t)(j / 2) * uv_stride);
+    }
+}
+
+#else
+
+void fp_convert(const uint8_t *src, int src_w, int src_h, int src_stride,
+                uint8_t *y, int y_stride, uint8_t *uv, int uv_stride,
+                int out_w, int out_h, void *scratch)
+{
+    fp_convert_scalar(src, src_w, src_h, src_stride, y, y_stride, uv, uv_stride, out_w, out_h, scratch);
+}
+
+#endif

native/venc/convert.h

@@ -0,0 +1,27 @@
+/* RGB24 -> NV12 picture converter for fp_venc (pure computation, no syscalls). See native/venc/SPEC.md "Converter".
+ * Built for aarch64 (NEON + scalar) and for x86_64 (scalar only; the host unit test loads it with ctypes). */
+#ifndef FP_VENC_CONVERT_H
+#define FP_VENC_CONVERT_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+/* Output size: height = min(max_h, src_h) (max_h <= 0 = src_h), width keeps the aspect; both rounded down to even,
+ * both >= 2. */
+void fp_out_size(int src_w, int src_h, int max_h, int *out_w, int *out_h);
+
+/* Bytes of scratch memory fp_convert/fp_convert_scalar need for these sizes. */
+size_t fp_scratch_size(int src_w, int src_h, int out_w, int out_h);
+
+/* RGB24 (R,G,B bytes) -> NV12 (BT.709, limited range): box-average downscale to out_w x out_h (out_w <= src_w,
+ * out_h <= src_h, both even), then out_w x out_h luma bytes and out_w x out_h/2 interleaved Cb,Cr bytes. */
+void fp_convert_scalar(const uint8_t *src, int src_w, int src_h, int src_stride,
+                       uint8_t *y, int y_stride, uint8_t *uv, int uv_stride,
+                       int out_w, int out_h, void *scratch);
+
+/* Same result, byte for byte; NEON on aarch64, fp_convert_scalar elsewhere. */
+void fp_convert(const uint8_t *src, int src_w, int src_h, int src_stride,
+                uint8_t *y, int y_stride, uint8_t *uv, int uv_stride,
+                int out_w, int out_h, void *scratch);
+
+#endif