OVRPort 1.2.5, documentation with screenshots, store description cleanup

- The overport CLI now comes from Android-XR-Bridge/OVRPort (fallback ovrport/app); its four new patches are described and shown only where they apply; parity classifies the 1.2.5 differences (VR metadata, config version, CLI-added platform compat) as expected: 34/34 at parity. - README rewritten (purpose, getting started, what works, credits, legal), INSTALL tightened, screenshots in docs/images (scripts/scrub_library.py + ui_smoke --docs --fake-frame), Quest2Frame references removed. - Game page: store descriptions without Markdown/[media] markup; themed labels on all switches. - `frameport install --apk` installs a given build (headset A/B tests).
FramePort 0.3.1
2026-10-06 17:00:43 +02:00 · 2026-10-02 00:32:14 -04:00 · 2026-10-01 23:20:19 -04:00 · 2026-10-01 23:10:50 -04:00 · 2026-10-01 22:59:56 -04:00 · 2026-10-01 21:53:06 -04:00
187 changed files with 20076 additions and 846 deletions
@@ -6,7 +6,7 @@ description: Port a Meta Quest standalone game (APK + OBB dump) to the Valve Ste
 # Port a Quest game to the Steam Frame

 Work from the repo root (`frameport/`). Read `CLAUDE.md` (facts) and `docs/PLAYBOOK.md` (symptom → fix) first.
-Set `UV_PROJECT_ENVIRONMENT=~/.cache/frameport-venv` (the repo is on NTFS).
+The dev environment is `.venv` in the repo root (`UV_LINK_MODE=copy uv sync --extra dev` if it's missing).

 ## 1. Setup (once)
 ```
@@ -1,6 +1,7 @@
 * text=auto eol=lf
 *.so binary
 *.dex binary
+*.exe binary
 *.apk binary
 *.png binary
 *.jpg binary
@@ -0,0 +1,44 @@
+name: Problem report
+description: A game or FramePort doesn't work (FramePort → "Report a problem…" fills this in and saves a diagnostics zip).
+title: "[Problem] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please attach the **diagnostics zip** FramePort saved (drag it into the "Diagnostics" box below). It contains
+        logs, the recipe and device details with personal data removed — no game files. Without the app, it can be
+        read with `frameport diag inspect <zip>`.
+  - type: input
+    id: game
+    attributes:
+      label: Game
+      description: Title — package id (version, engine / XR API); empty for app problems
+  - type: textarea
+    id: description
+    attributes:
+      label: What happens?
+      description: What you did, what you expected, what you saw (in the headset, if it started)
+    validations:
+      required: true
+  - type: textarea
+    id: findings
+    attributes:
+      label: Launch test / triage
+      description: Filled in by FramePort from the last launch test
+  - type: textarea
+    id: recipe
+    attributes:
+      label: Recipe
+      render: yaml
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+  - type: textarea
+    id: logs
+    attributes:
+      label: Diagnostics
+      description: Drag the FramePort-diag-*.zip here (max 25 MB)
+    validations:
+      required: true
@@ -0,0 +1 @@
+blank_issues_enabled: true
@@ -0,0 +1,49 @@
+name: Working configuration
+description: Submit a recipe that works on the Steam Frame (FramePort → game menu → "Share working config…" fills this in).
+title: "[Working config] "
+labels: ["working-config"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks! A maintainer reviews the recipe; once it's labelled `catalog-accepted`, a pull request adding it to
+        `catalog/games/` is opened automatically. Please don't paste game files or links to them.
+  - type: input
+    id: game
+    attributes:
+      label: Game
+      description: Title — package id (platform, version, engine / XR API)
+    validations:
+      required: true
+  - type: input
+    id: result
+    attributes:
+      label: Result
+      description: works or issues (+ the last headless launch test)
+    validations:
+      required: true
+  - type: textarea
+    id: recipe
+    attributes:
+      label: Recipe
+      description: The catalog entry (catalog/games/<package>.yaml). Don't edit the package line.
+      render: yaml
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: FramePort, tool and SteamOS versions
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: What you checked in the headset, known issues, anything unusual
+  - type: checkboxes
+    id: confirm
+    attributes:
+      label: Confirmation
+      options:
+        - label: I played the game in the headset with this recipe (headless launch tests can't check the picture).
+          required: true
@@ -91,6 +91,9 @@ jobs:
      - name: Package (Linux)
        if: runner.os == 'Linux'
        run: tar czf ${{ matrix.archive }} -C dist --transform 's,^linux,FramePort,' linux
+      # self-update with this archive: unpack, verify the layout (+ the signer on Windows), run the real swap script
+      - name: Update smoke test
+        run: uv run python scripts/update_smoke.py ${{ matrix.archive }}
      - name: Attest build provenance
        if: github.event_name != 'pull_request'
        uses: actions/attest-build-provenance@v4
@@ -109,10 +112,13 @@ jobs:
      contents: write
    steps:
      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
      - uses: actions/download-artifact@v8
        with:
          path: out
          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: Checksums
        run: cd out && sha256sum * > SHA256SUMS.txt && cat SHA256SUMS.txt
      - name: Publish release
@@ -121,7 +127,15 @@ jobs:
        run: |
          tag="${GITHUB_REF_NAME}"
          notes=$(mktemp)
+          # "What's new" = the annotated tag's message (FramePort's update dialog shows it); checkout may leave the
+          # tag lightweight, so fetch the tag object itself
+          git fetch --force origin "refs/tags/${tag}:refs/tags/${tag}"
+          whatsnew=$(git tag -l --format='%(contents:body)' "$tag")
+          [ -n "$whatsnew" ] || whatsnew=$(git tag -l --format='%(contents:subject)' "$tag")
          { echo "FramePort ${tag}: Windows (x64), macOS (Apple Silicon) and Linux (x64)."; echo;
-            sed -n '/^## First launch/,$p' docs/INSTALL.md; } > "$notes"
+            if [ -n "$whatsnew" ] && [ "$(git cat-file -t "$tag")" = tag ]; then
+              echo "## What's new"; echo; echo "$whatsnew"; echo; fi
+            echo "Already have FramePort? It offers this update itself (Library → **Update now**, or \`frameport update\`)."
+            echo; sed -n '/^## First launch/,$p' docs/INSTALL.md; } > "$notes"
          gh release delete "$tag" --yes 2>/dev/null || true
          gh release create "$tag" out/* packaging/FramePort-selfsigned.cer --title "FramePort ${tag}" --notes-file "$notes"
@@ -0,0 +1,52 @@
+name: catalog-from-issue
+# A maintainer adds the label `catalog-accepted` to a "Working configuration" issue → this opens a PR adding the
+# recipe to catalog/games/. Never runs for unlabelled issues; the issue text is only read by the validating script
+# (never interpolated into shell commands). Needs Settings → Actions → "Allow GitHub Actions to create pull requests".
+on:
+  issues:
+    types: [labeled]
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+jobs:
+  recipe-pr:
+    if: github.event.label.name == 'catalog-accepted' && contains(github.event.issue.labels.*.name, 'working-config')
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }}
+      ISSUE: ${{ github.event.issue.number }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uv sync
+      - name: Write the recipe
+        id: recipe
+        run: |
+          gh issue view "$ISSUE" --json body -q .body > "$RUNNER_TEMP/body.md"
+          uv run python scripts/catalog_from_issue.py "$RUNNER_TEMP/body.md" --issue "$ISSUE" | tee "$RUNNER_TEMP/out.txt"
+          grep '^package=' "$RUNNER_TEMP/out.txt" >> "$GITHUB_OUTPUT"
+      - name: Check it loads
+        env:
+          PKG: ${{ steps.recipe.outputs.package }}
+        run: uv run python -c "import os, sys; from frameport.recommend import catalog; sys.exit(os.environ['PKG'] not in catalog.load(refresh=True))"
+      - name: Open the pull request
+        env:
+          PKG: ${{ steps.recipe.outputs.package }}
+        run: |
+          branch="catalog/issue-$ISSUE"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$branch"
+          git add "catalog/games/$PKG.yaml"
+          git commit -m "catalog: $PKG (from #$ISSUE)"
+          git push --force origin "$branch"
+          if ! gh pr view "$branch" >/dev/null 2>&1; then
+            gh pr create --head "$branch" --title "catalog: $PKG" \
+              --body "Recipe submitted in #$ISSUE (working configuration). Closes #$ISSUE."
+          fi
+      - name: Report a failure on the issue
+        if: failure()
+        run: gh issue comment "$ISSUE" --body "Couldn't turn this into a catalog recipe — see the workflow run ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}."
@@ -11,3 +11,5 @@ parity-report.md
 .pytest_cache/
 native/.cache/
 native/**/build/
+# per-machine Claude Code settings (contain home paths)
+.claude/settings.local.json
@@ -8,7 +8,87 @@ install over SSH (agent) → Steam shortcut → headless launch test + log triag
 Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRAME_RUNTIME.md` for runtime facts.

 ## Layout
- `src/frameport/` — Python package. `pipeline.py` is the API the CLI (`cli.py`) and GUI (`ui/app.py`, Flet 1.0) share.
+- `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
+    raises), `jobs.py` (background FIFO job queue, one at a time, cancel via Reporter; no Flet), `views/`
+    (library: search/filters/tags/sort as pure tested helpers; game: hero + one-click install, patches under
+    "Customize"; frame: device + readiness + installed, or connect wizard; settings; welcome; activity panel).
+    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
+    library view is persistent, streams cards in batches from a background thread and filters by toggling visibility;
+    job/connection events call `app.refresh_view()` (targeted), not `render()`; no I/O in render paths.
+    **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).
+    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
+    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).
+  - **PC VR repacks are pre-patched to run directly** (proven: Rick and Morty, Vader Immortal run when the exe is
+    launched directly; Revive breaks them). So Rift games default to `as_is` = install the copy unchanged and launch
+    the exe directly (`pcvr.xr_timefix` for the Frame OpenXR-1.1→1.0 fix, `pcvr.no_crash_reporter` for Unreal).
+    **Revive is off by default, opt-in** (`pcvr.revive`, and `pcvr.oculus_unreal`): only for an un-cracked Oculus game
+    that fails at "Initializing OVR session". Those (Lone Echo, Robo Recall, Lies Beneath: crack .7z not extracted /
+    Platform SDK) hit Revive's Oculus-runtime **signature check** under Proton-arm64 — Revive's LoadLibrary/WinVerifyTrust
+    hooks don't install (ARM64EC), and the game's Oculus SDK shim rejects the unsigned Revive runtime (wintrust +
+    crypt32 signer "Oculus VR") — so they don't run on the Frame without extracting the repack's crack (which FramePort
+    doesn't do). `VD.bat` is Virtual Desktop's launcher: ignore it except as an exe-location hint. Library migration
+    `rift_run_direct` resets existing recipes.
+    Auto launch-test is skipped on PC installs (it would start the game on the user's desktop). Launch tests collect the Unreal
+    game log + crash summaries from the Proton prefix; triage `unreal-crash`. Lies Beneath via Proton without Revive
+    crashed (UE 4.23 "Unhandled exception").
+  - Rift scanning: `sources/rift_dump.scan` = the scanned folder's subfolders are games (one per folder; a folder is a
+    game if all candidate exes sit under one child), recursing into collections; `analysis/rift.py` walks once,
+    filters helpers + non-GUI PEs, `rank_exes` (Unreal *-Shipping beats its launcher, Steam builds −10, ambiguous →
+    `exe_confirmed=False` → GUI exe dialog), `clean_title`, fingerprint (unchanged folders aren't re-analyzed),
+    modular-Unreal Oculus plugin DLLs + UTF-16 markers count as LibOVR, `revive_bundled` → as-is.
+  - Rift VR-API routing (`analysis/rift.py`): `openvr`/`openxr`/`libovr` detected from imports + bundled DLLs (NOT the
+    universal-in-Unreal `IVRSystem`/`VR_InitInternal` strings). `frame_native = (openxr or openvr) and not libovr` =
+    confidently runs on the Frame via wineopenxr (SteamVR), no Revive. Any LibOVR game → `needs_revive` → **PC only**
+    on the Frame (Revive's ARM64EC hooks don't work under Proton-arm64, and FramePort does **not** defeat the Oculus
+    runtime Authenticode signature check). Patch `pcvr.libovr_redirect` (Frame, default on for Revive games, agent v19 `set_libovr_redirect`) symlinks Revive's
+runtime as `LibOVRRT{64,32}_1.dll` in the game's exe dir **and next to every OVRPlugin.dll** (Unreal's OVR shim
+searches its own module dir, not the exe dir) — the LoadLibrary redirect (pure runtime substitution), which
+does NOT touch the game's runtime signature check (a checking build still fails at `-3021`; only non-checking builds
+run). PoC verified on-device (2026-09-30): with the redirect, Lone Echo's Oculus SDK now loads Revive's runtime and
+reaches Oculus API init (`-3021`) instead of failing to load a runtime at all — i.e. the substitution works; `-3021`
+is the downstream signature/runtime-init stage the redirect doesn't touch. (OVRPlugin/Unreal builds use a more
+restrictive LibOVRRT search; the next-to-OVRPlugin placement covers the common case.)
+Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
+    not via static detection. PC installs default to Revive's **OpenVR** backend (`pcvr.revive_openvr` on) and
+    auto-start SteamVR on Play (`winhost.start_steamvr`); the Frame launcher always uses `/openxr`. UI (`game.py`
+    where()) states per-game where it runs; installing an Oculus game on the Frame shows a warning. Migration
+    `rift_frame_native` re-analyzes + re-derives existing entries.
+  - Art for Rift games: `artwork/sources.py` — Quest version package (OculusDB packageName, exact name or +
+    "Unplugged"-type suffix, never sequels) → Meta art; OculusDB square cover; Steam (exact names only); exe icon.
+  - Store details (`artwork/details.py`, entry `details`): OculusDB (description, genres, publisher, website; by Quest
+    package or Rift match) + Steam appdetails (exact title: developer, release date, up to 6 screenshots → artwork
+    `shot_N.jpg`). Meta store pages reject scraping, so Oculus exclusives have no screenshots. Genres become automatic
+    tags. Steam shortcuts get a complete composed art set (`artwork/steam.py`: 600×900 / 920×430 / 1920×620 / logo /
+    256 icon, blurred-backdrop compositing for square-only covers) and tags: how it runs, the original platform
+    (Meta Quest / Oculus Rift), genres, user tags — merged with tags set in Steam (non-Steam shortcuts can't hold a
+    description).
+  - Quest/Rift twins stay separate entries, shown and named in Steam "Title (Quest)"/"(Rift)" (`core/titles.py`).
+  - `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
+    still gets launch fixes like the crash-reporter rename — `-nocrashreports` alone doesn't stop UE 4.23) — it does
+    **not** turn Revive off: a repack's patches (cracks, `VD.bat` = Virtual Desktop's Oculus
+    runtime) give a LibOVR game no Oculus runtime on the Frame; Revive is that runtime (Lone Echo without it: EXITED
+    in seconds). SteamVR builds (Rick and Morty) turn Revive off via their recipe (`pcvr_remove`, catalog `as_is`).
+  - Play: Library hover button / right-click / game page / Frame rows → agent `launch` = `steam://rungameid/<appid<<32
+    | 0x02000000>` through the Frame's Steam (in-headset session); PC: Windows Steam. Launch tests use a
+    flask icon (SCIENCE_OUTLINED) so they aren't confused with Play.
+  - `uninstall.py` + `frameport uninstall-app` + Settings: removes the data dir (after an optional key backup zip),
+    PC Steam shortcuts, the WSL Revive copy, and via agent `purge` FramePort's games/files on the Frame.
  - `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(...)`.
@@ -17,26 +97,86 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
  - `apk/` — `axml.py` (binary manifest editor), `workspace.py` (staged zip edits), `sign.py` (apksigner; it aligns too).
  - `recommend/` — `catalog.py` (known-good recipes: user > remote `FRAMEPORT_CATALOG_URL` > bundled), `engine.py`.
  - `tools/` — portable toolchain (Temurin JRE, overport jar, apksigner) downloaded dynamically into the user data dir.
+    The overport CLI comes from the downstream fork **Android-XR-Bridge/OVRPort** (stable `vX.Y.Z` releases,
+    `OVRPort-<ver>-stable-cli.jar`; fallback ovrport/app `cli-jar.zip`), see "overport" below.
  - `frame/` — SSH (paramiko), mDNS discovery, pairing server; `install/installer.py`; `validate/` (static, device, triage).
-  - `targets/` — `Target` interface; `frame_lepton.py` now, `revive.py` placeholder (PC VR later).
+  - `targets/` — `Target` interface; `frame_lepton.py` (Quest via Lepton + Rift via Proton), `pc_revive.py` (Rift games
+    on this Windows/WSL PC via Revive + local Steam shortcut; `core/winhost.py` = Windows/WSL helpers).
+  - Oculus Rift (PC VR): `sources/rift_dump.py`, `analysis/rift.py` (own PE reader), `patches/pcvr.py` (category
+    `pcvr`, shown as patches; `base.for_game` separates Quest/PC VR patches), `tools/revive.py` (Revive: FRAMEPORT_REVIVE_DIR >
+    the user's installed Revive (C:\Program Files\Revive, else registry HKLM/HKCU\Software\Revive; version = GitHub
+    release matching the DLL build date, since Revive's version resources are stale) > portable copy unpacked from
+    ReviveInstaller.exe in pure Python; never replaces the user's install). Library ids `rift.<slug>`, entries have `kind: rift`.
  - `parity.py` — rebuild catalog games from dumps and classify every APK entry difference vs known-good builds.
+  - `diag/` — user feedback without tokens (docs/DIAGNOSTICS.md): `redact.py` (every file/issue text: IPs, hosts,
+    home dirs, Steam ids, dump folders → placeholders), `bundle.py` (redacted diagnostics zip; agent v21
+    `collect_diag`; `frameport diag collect|inspect|report`), `issue.py` (prefilled GitHub issue-form links, ≤7.5k
+    chars). "Share working config" → `working-config.yml` issue → maintainer label `catalog-accepted` →
+    `catalog-from-issue.yml` workflow (`scripts/catalog_from_issue.py` validates) opens a catalog PR. App log:
+    `core/applog.py` (`<data>/logs/app.log`, finished GUI jobs in `<data>/logs/jobs/`).
+  - Self-update (docs/ARCHITECTURE.md "Self-update", docs/INSTALL.md "Updating"): `_version.py` = the only version
+    (`frameport.__version__`; pyproject reads it via hatch `dynamic`; app log, diagnostics, User-Agent, Settings use
+    it — never `importlib.metadata`, bundles have no dist-info). `updates.py` (no Flet): `check()` = GitHub
+    releases/latest via `cached_json("app-release.json")`, 6 h, skips drafts/prereleases and the user's skipped version
+    (settings `update.last_check`/`skipped`/`auto_check`/`auto_install`/`cli_hint`; env `FRAMEPORT_NO_UPDATE_CHECK`);
+    `install_kind()` = `bundle` (psutil exe path → FramePort.exe's folder / FramePort.app / FramePort/FramePort),
+    `source` (`.git` checkout: `git pull --ff-only` + `uv sync`, refused on a dirty tree), `wheel` (`uv tool`/pipx/pip
+    reinstall of the release's `.whl`); `prepare()` → `<data>/updates/<ver>/` (SHA256SUMS.txt required + checked,
+    layout checked, Windows: the new FramePort.exe must have the running exe's Authenticode signer when that one is
+    signed, `ready.json`); `apply()` writes + starts detached `apply.ps1`/`apply.sh` (wait for pid → Windows: copy over,
+    replaced files kept in `updates/<ver>/previous` because the zip has no top folder; macOS/Linux: mv to `.old` + swap,
+    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
+    `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)]
+    [--yes]`, once-a-day stderr hint read from the cache only (`refresh_cache()` in a daemon thread writes no
+    settings, to avoid read-modify-write races). `scripts/update_smoke.py <archive>` runs the real extract + swap script
+    (no relaunch) — CI runs it on all three OS with the archive it just built.
+    Verified: Linux + Windows (native, signer check) smoke with the v0.2.0 bundles; macOS only via the CI smoke.
 - `agent/frameport_agent.py` — runs **on the Frame** (python3 stdlib only), JSON over SSH. Owns the install layout,
  launch.sh template, Steam shortcuts (binary VDF), launch tests. Bump `AGENT_VERSION` when changing it.
 - `bootstrap/bootstrap.sh` — one-time Frame setup served by the pairing server (sshd, app key, avahi service, Lepton).
- `catalog/games/<package>.yaml` — 34 recipes verified 2026-09-28; `catalog/triage.yaml` — log signatures → fixes.
+- `catalog/games/<package>.yaml` — 34 recipes verified 2026-09-28 + Deadpool VR (2026-10-01, owner-confirmed); `catalog/triage.yaml` — log signatures → fixes.
 - `native/` — sources of the prebuilt binaries in `artifacts/` (adapter, VrApi bridge patches, GL shim, stubs).
-  `native/build.sh` rebuilds them with NDK r27c (downloaded on demand; never committed). Users never need the NDK.
+  `native/build.py` rebuilds them with NDK r27c (downloaded on demand into `native/.cache`, git-ignored; uses
+  `-ffile-prefix-map` so no local paths get embedded; zip symlinks are restored as copies). Users never need the NDK.
+- `scripts/` — `package.py` (flet build/pack), `eval_heuristics.py` (score heuristics), `ui_smoke.py` (GUI screenshots).
+- `docs/` — PLAYBOOK, FRAME_RUNTIME, ARCHITECTURE, INSTALL (end users), parity reports (offline + device).

 ## Dev commands
 ```
-export UV_PROJECT_ENVIRONMENT=~/.cache/frameport-venv   # keep the venv off NTFS (repo lives on D:)
-uv sync --extra dev          # or: uv pip install -e .[dev]
+# the dev venv is .venv in the repo root (git-ignored); on the NTFS drive uv needs UV_LINK_MODE=copy
+UV_LINK_MODE=copy uv sync --extra dev   # creates/updates ./.venv
 uv run pytest                # unit tests (no device, no game files)
 uv run frameport --help      # CLI;  uv run frameport-gui  for the GUI
 uv run frameport parity --known-good <PATCHED/_known-good-*> --sources "<VR CyberDeck downloads>"
 ```
-Games/device tests: `pytest -m games` (FRAMEPORT_GAMES=<downloads dir>), `pytest -m device` (FRAMEPORT_FRAME=steamos@host).
+Games/device tests: `pytest -m games` (FRAMEPORT_GAMES=<downloads dir>), `pytest -m device` (FRAMEPORT_FRAME=steamos@host);
+native layer test: `FRAMEPORT_NATIVE_TESTS=1 pytest -m native` (compiles with the NDK, ~2 min on NTFS).
 Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattributes`).
+- `FRAMEPORT_HOME=<dir>` isolates all app data (tests use it); `FRAMEPORT_JAVA/_OVERPORT_JAR/_APKSIGNER_JAR` override
+  managed tools. Real app data (WSL): `~/.local/share/frameport` (tools, overport workspace + game keystores, library,
+  artwork, frames.json, the app's SSH key which the dev Frame authorizes).
+- Device checks: `frameport test <pkg>` / `frameport parity-device --results <parity.json> --baseline <launch.txt>
+  [--test-only]`; the pre-FramePort baseline is `PATCHED/_known-good-2026-09-28/_frame-state/baseline-launch.txt`.
+- Docs screenshots (`docs/images/`): `python scripts/scrub_library.py ~/.local/share/frameport <dir>` (copies
+  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.
+  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
+  `FRAMEPORT_HOME=<test dir> python scripts/ui_smoke.py --out <dir> [--game <pkg>] [--frame steamos@<host>] [--update]` (`--update` = fake release: banner, dialog, Settings → Updates) and look
+  at the PNGs. Flet 1.0 notes: `ft.run` must own the main thread; background work via `page.run_thread`; FilePicker is
+  awaited (`await ft.FilePicker().get_directory_path()`); dialogs via `page.show_dialog/pop_dialog`; running from
+  source needs `flet-desktop` (declared) and web mode needs `flet-web`.
+- GUI scale: `theme.set_scale()` (library setting `ui.scale`, "auto" = halfway to Windows' AppliedDPI/96 under WSL (150 % → 125 %; full was too large), where the
+  Linux window gets no Windows scaling; Settings → Appearance; applied at start). Sizes go through tokens or
+  `T.px(n)`, Material defaults through the theme's text_theme; never hardcode a bare pixel number in ui/.
+  `scripts/ui_smoke.py --scale 1.5 --viewport 2560x1440` renders it. Flet draws a grey box for invalid layouts (e.g.
+  an `expand` child in a `wrap=True` Row).
+- Stopping the GUI: `pkill -f` patterns match your own shell — use `pgrep -f "[b]in/frameport-gui|[f]let-desktop-light"`.

 ## Hard-won facts (don't re-learn these)
 **Frame runtime (SteamOS 0.3.0, build 20260922):**
@@ -63,6 +203,56 @@ since boot every game fails with `crun: create keyring …: Disk quota exceeded`
 `keyring = false` in `~/.config/containers/containers.conf` (agent `ensure_host_fixes`, bootstrap); leaked keys only
 go away with a reboot. Check usage: `grep "^ *1000:" /proc/key-users` (agent `info` → kernel_keys).

+**Proton on the Frame (2026-09-29):** Steam registers ARM64 tools from app "Steam Frame ARM64 Compat List"
+(`proton_11-arm64` 4628740 needs SLR4-arm64 4185400; `proton-experimental-arm64` 4427310; `fex` 3127680) — not installed
+by default; `steam://install/<id>` only opens a dialog in the headset (agent `install_proton` mode `unattended` =
+appmanifest stubs + Steam restart; untested on device). Proton only sets up VR/wineopenxr when `SteamGameId` is set.
+Host OpenXR = SteamVR (`~/.config/openxr/1/active_runtime.json`). Steam VR games on the Frame (Pistol Whip etc.) are
+APKs via Lepton. Verified on the device: the app installs Proton itself (`installer.ensure_proton`: appmanifest stubs +
+Steam restart, ~90 s); Proton runs x86 code; wineopenxr gets registered; headless launches need DISPLAY/
+GAMESCOPE_WAYLAND_DISPLAY from Steam's environment (launch.sh imports them). The **Linux** SteamVR runtime supports
+XR_KHR_convert_timespec_time (only the Android runtime lacks it). **But it only accepts OpenXR 1.0 apps**: apiVersion
+1.1 → XR_ERROR_API_VERSION_UNSUPPORTED, and Proton 11's vrhelper asks for 1.1 → no VR at all (flat window; Revive:
+"Unable to load LibOVRRT DLL"). FramePort's layer (`native/xrlayer`, `artifacts/linux-arm64`, patch `pcvr.xr_timefix`,
+default on + one-time library migration in `core/library._migrate`) retries as 1.0. Proton's container (pressure-vessel)
+**drops `XR_API_LAYER_PATH`**, so the agent registers the layer as an explicit layer in
+`~/.local/share/openxr/1/api_layers/explicit.d/` (library: shared copy in `~/.local/share/frameport/xrlayer/`); it
+only loads when `XR_ENABLE_API_LAYERS` names it. Unreal PC VR games get
+`pcvr.no_crash_reporter` by default (`-nocrashreports` + CrashReportClient.exe renamed `.disabled` in the Frame copy)
+and `pcvr.oculus_unreal` (PC VR counterpart of overport's `patch_oculus_unreal`: UE's OculusHMD needs the Windows event
+`OculusHMDConnected`; launch.sh wraps the injector in `helpers/fp_oculushmd.exe` = `native/oculushmd`,
+`artifacts/win-x64`, which provides it until the game's job is empty; untested on the device yet).
+Rift games tried on the Frame: Rick and Morty (SteamVR build, no Revive: "OpenVR initialized!" with the layer; flat
+before — confirm in the headset), Lies Beneath (Oculus Store UE 4.23 build: delay-loads `LibOVRPlatform64_1.dll` =
+Platform SDK → crash 0xc06d007e; needs the Oculus app, FramePort doesn't replace it; also OVRPlugin's LibOVR shim
+reports "Unable to load LibOVRRT DLL" before any OpenXR call — likely needs a real Oculus runtime install, unverified).
+Launch tests ignore log files older than the launch (stale Proton/game logs used to be triaged). Revive injector CLI: `ReviveInjector.exe [/openxr] <exe path>`
+(joins args; logs to `%LOCALAPPDATA%\Revive\ReviveInjector.txt`). On WSL, run Windows programs from Windows paths
+(`\\wsl$` is unreliable), so PC mode copies Revive to `%LOCALAPPDATA%\FramePort`.
+FramePort never bypasses Oculus entitlement checks (Platform SDK games: flagged, PC mode with the Oculus app only).
+
+**Upload speed (measured 2026-09-29):** via the home router (PC Wi-Fi → router → Frame wlan0) only 15-18 MB/s, the
+same for paramiko, OpenSSH and 4 parallel streams, so the network path is the limit, not the SSH code. Direct to the
+Frame's hotspot (`wlanap` 10.35.78.1; the owner's PC has Valve's USB Wi-Fi dongle on it) 83 MB/s OpenSSH / 97 MB/s
+paramiko; reading dumps from D: via WSL drvfs is then the cap (~82 MB/s). `Frame.fast_link()` (installer
+`transfer_link`, uploads ≥64 MiB) uses usb0 > wlanap when reachable **and** the host key matches the paired Frame.
+**Platform SDK detection** must include delay imports (`PEInfo.delay_imports`), modular Unreal's
+`*-OnlineSubsystemOculus-*.dll` and Ready At Dawn's `pnsovr.dll`: Robo Recall, Lies Beneath and Lone Echo I/II all use
+it; without the Oculus app they crash with 0xc06d007e (triage `delayload-missing`) — not fixable legitimately.
+GUI: Frame → Installed → folder icon = file browser (agent `list_files`, flags files missing vs the install
+manifest); Settings → About shows the bundled agent version and the Frame's.
+
+**Revive under Proton arm64 (Lone Echo, 2026-09-29):** Revive's Detours hooks (LoadLibraryW/ExW, OpenEventW, the
+signature check) don't take effect: Wine's kernelbase is ARM64EC. The LibOVR shim in the game then does a plain
+`LoadLibrary("LibOVRRT64_1.dll")` search (exe dir, cwd, system32, windows, PATH — no registry, `OculusBase` or
+`LIBOVR_DLL_DIR` used by this build) → `Failed to initialize Oculus API (-3001)` (= Lies Beneath's "Unable to load
+LibOVRRT DLL"). A symlink `pfx/drive_c/windows/system32/LibOVRRT64_1.dll -> <base>/revive/LibReviveXR64.dll` (Wine
+maps a symlink to the already-loaded module) gets past it to **-3021 = ovrError_LibSignCheck**: the shim only accepts
+an Oculus-signed runtime. Next step (not done): make the runtime check pass without Detours, e.g. an injected helper
+that patches the game's import table (IAT) for LoadLibrary*/WinVerifyTrust, or a prefix-level override. This is
+runtime interop (what Revive does), not the Platform SDK licence check (which FramePort never touches).
+Uninstall (Quest, saves kept) used to leave `deployment.json` → still "installed"; fixed (agent v16).
+
 **Discovery/network:** Developer-Mode SteamOS devices announce `_steamos-devkit._tcp` (TXT `login=steamos`) — use it;
 they don't publish `_ssh._tcp`. The Frame has several links: `wlan0` (home Wi-Fi), `wlanap` = its own hotspot at
 10.35.78.1/24 (a PC can join it directly), `usb0` = USB gadget network 10.86.200.233/29 (up when cabled to a PC).
@@ -76,6 +266,16 @@ stopping Steam kills them → always run that work via `systemd-run --user` (the
 **overport:** always `--version=latest`; `--workspace` holds runtimes and **per-package keystores (password
 "password", alias "key") — never lose them**: updates must be signed with the same key or saves are lost on reinstall.
 Output is deterministic (same input + runtime → same bytes), which is what makes parity testing possible.
+**OVRPort 1.2.5 (2026-10-01, the fork's first release; CLI-only):** same commands (`patches [--json]`, `patch`, `help`,
+`install`), but `patch` rejects unknown/duplicate args, unknown patch ids and an empty `--patches=`
+(`tools/overport.patch` refuses empty lists). After patching it adds `libovrplatformcompat.so` itself when the platform
+loader lacks `ovrMessageType_ToString` (our `frame.ovrplatformcompat` then skips: same library). New patches (all off;
+`patches/overport.py`): `patch_ac_nexus_no_appsw_72/_90` (AC Nexus build 207706 only, exclusive),
+`patch_disable_meta_xr_audio_telemetry` (x86_64 emulators: hidden), `patch_vrapi_openxr` = OVRPort's VrApi adapter =
+the **unpatched** upstream of our `frame.vrapi_bridge` (`native/vrapi` unchanged since our 5e7df52), only usable with an
+experimental CLI built with `-PwithVrApi=true` (stable jars list it but fail). The owner prefers OVRPort's fixes over
+ours where they work as well (less to maintain): compare in the headset before switching a default.
+`frameport install <pkg> --apk <file>` installs a specific (test) build signed with the game's key.

 **Patching gotchas:**
 - UnityPy re-serialization breaks scene loading → patch QualitySettings ints in place.
@@ -88,15 +288,126 @@ Output is deterministic (same input + runtime → same bytes), which is what mak
 - VrApi-direct engines (CryEngine Climb 2, POTW) need the VrApi bridge; the bridge drops whole frames on unknown layer
  types (→ black screen with audio).

+**Steam Frame controller models (2026-09-30, not yet seen in a game):** adapter setting `controller_models`
+(`native/adapter/render_model.c`) emulates XR_FB_render_model and serves `files/framebridge/controller_{left,right}.glb`;
+agent v20 (`install_controller_models`, command `controller_models`) converts the Frame's SteamVR render models
+(folder name matching "frame" + left/right, OBJ+PNG, `openxr_grip` component → grip space) at finalize/set_settings.
+Valve's models are never committed or copied off the Frame. Only games that use Meta's runtime controller models
+benefit (manifest `RENDER_MODEL` permission/feature → suggested); **none of the 34 catalog games do** (they ship their
+own meshes: that would need per-game asset replacement). Model discovery and conversion
+checked on the device 2026-09-30: `/opt/steamvr/drivers/frame_controller/resources/rendermodels/frame_controller_{left,right}`
+(component OBJs in model space = the whole `<name>.obj`, one `_color.png` 2048² near-black, `openxr_grip` rotates about
+X only; hidden-by-default components like `status` are skipped) → ~2 MB glb each, ~1 s. Not yet seen in a game (none
+of the installed builds has the new adapter, and none requests runtime models), so whether Meta's SDK attaches runtime models at the grip pose is unverified.
+**overport's dispatcher (`libopenxr_loader.so`) only forwards functions in its own table** (`overportOXR: Unknown
+proc addr: …`), so adapter emulations of functions it doesn't know are unreachable. For XR_FB_render_model,
+`native/xrshim` fills the gap: OVRPlugin's `dlopen("libopenxr_loader.so")` string is rewritten to the shim (see
+native/README). Verified on the device with Toy Master (2026-09-30): `extension shim: xrLoadRenderModelFB -> FrameBridge`.
+Toy Master doesn't request a model after that (it uses its own), so the glb loading path is only unit-tested.
+
+**Crash backtraces (2026-09-30):** Lepton writes tombstones only to `lepton-logcats/steamlaunch-<appid>/logcat-crash.log` (after "Dumping logcat"), not launch.log; agent v23 launch tests wait for it and return `crash_log`, triage gets it via `triage(..., crash=)` (not pid-filtered: tombstones come from crash_dump's pid). The guest is `userdebug` (`ro.debuggable=1`), so Lepton's Fossilize layer loads into every app whatever the APK's debuggable flag; it has no off switch. Fossilize crashed Deadpool VR on uninitialized attachment-reference pNexts (several, in FVulkanRenderPass and the render-target layout) → `frame.vk_sanitize` = `native/vkshim` (engine's `dlopen("libvulkan.so")` string → `libfp_vk.so`, wraps vkCreateRenderPass2/KHR, drops unreadable/wrong-sType pNexts; verified: game runs). overport's dispatcher aborts on swapchains > 4096 px (`cmp wN,#4096` in xrCreateSwapchain) → `frame.swapchain_limit` (verified with 4XVR, 7680×3840 accepted by the runtime). Both are default-on (parity classifies their rewrites as
+"expected"; library migration `quest_binary_fixes_v2`). The adapter shows cylinder layers (4XVR's movie screen) as ~15° quad strips (`cylinder_strips`, setting
+`cylinder_strips`); the runtime composites them at full resolution. Equirect (360°) layers are dropped: drawing
+them ourselves (GLES renderer in xrEndFrame: stutter, never showed 4XVR's VR video; Vulkan renderer: hung the
+Frame's GPU in AC Nexus; reading the newest *released* image broke 4XVR's theatre) was removed again on the owner's
+request — don't retry without a new approach. Converted layers must count as "swapped" or the original layer list
+is submitted (runtime returns -2 for every frame). A focus debounce (hiding the Frame's brief
+FOCUSED→VISIBLE→SYNCHRONIZED dips, which make 4XVR recenter) was also removed: AC Nexus stayed black with it (it
+hid 521 ms focus changes at start). The new approach (below) is per-game, off the app's render thread, GLES-only.
+
+**360° layers / 4XVR (2026-09-30):** the Frame's Android SteamVR runtime (`/opt/steamvr/bin/androidarm64/vrclient.so`,
+mounted in Lepton as `/data/steamvr/runtime`) only composites quad + projection layers (cube/cylinder/equirect(2)
+are enum names only) — nothing to unlock. Per-game adapter settings (off by default, hooks installed only when on):
+`equirect_emul` (GLES only: a worker thread with a shared EGL context converts each 360° image to a cube map when it
+changes and draws one adapter projection layer from it for every frame with exactly that frame's views (the app's own
+projection views, else xrLocateViews at displayTime); xrEndFrame waits ≤6 ms for the worker's CPU submit, never the
+GPU. Learned in the headset: quads can't be a background (the Frame draws quad layers above all projection layers
+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
+(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
+folder (`app_media_dirs`), `frameport frame send --app <pkg>`, GUI game page "Add videos" (players) / "Add videos &
+files…". A 4XVR webm stereo swapchain was refused with XR_ERROR_LIMIT_REACHED (-10) → right eye grey; our projection
+swapchain was halved (1536/eye) in case memory is the limit (unverified). Frame data snapshot
+(SteamVR runtimes, Lepton scripts, logs; never commit Valve binaries): `~/frameport-research/frame-data-2026-09-30/`.
+Not yet verified in the headset.
+
+**Lepton storage (2026-09-30):** each app's /sdcard (= /storage/emulated/0 → `<base>/lepton-data/external`) has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (liblepton/mounting.sh, only if they exist at start); agent v24 `storage_targets` reads that mapping. Android's MediaProvider canonicalises paths to /home/steamos/... and rejects every file ("doesn't appear under [/system/media...]"), `sm list-volumes` is empty: the media index never works, apps must browse folders. Lepton installs with `adb install -g` (runtime permissions granted, MANAGE_EXTERNAL_STORAGE too). Send files: `install/files.py`, `frameport frame send|storage`, GUI Frame → Send files.
+**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.
+
 **Unresolved (as of 2026-09-28):** Arcsmith (right-eye distortion) and Time Stall (both eyes) — swap, tracking, Valve
 layers, depth, pacing ruled out. Sniper Elite VR (DEVICE LOST), Espire 1 (Mesa GL upload crash), HITMAN 3 (freedreno
 crash): use PC versions.

-## Releases
-Push a `v*` tag → CI builds Windows/macOS(arm64)/Linux bundles, signs Windows binaries with the self-signed
-certificate (secrets `WINDOWS_CODESIGN_PFX` base64 + `WINDOWS_CODESIGN_PASSWORD`; public cert `packaging/`,
-private copy only on the maintainer's machine + backup), ad-hoc signs the macOS app, adds build attestations and
-publishes a GitHub Release with SHA256SUMS. macOS x86_64 isn't built (cryptography cross-build fails).
+## Releases, CI, GitHub
+Public repo `github.com/spoopyghosty0/frameport` (branch `main`). Push a `v*` tag → CI (`.github/workflows/build.yml`)
+tests, builds Windows x64 / macOS arm64 / Linux x64 bundles, signs, attests and publishes a GitHub Release
+(`FramePort-*.zip/.tar.gz`, the CLI wheel `frameport-<ver>-py3-none-any.whl`, `SHA256SUMS.txt`,
+`FramePort-selfsigned.cer`; notes = "What's new" from the annotated tag message + `docs/INSTALL.md` from "First launch").
+Installed apps find the release themselves (self-update), so the notes are what users see in the update dialog.
+- **Release checklist:** bump `src/frameport/_version.py` (the only version; `scripts/package.py` fails a tag build
+  whose tag ≠ `v<_version>`), commit, `git tag -a vX.Y.Z -m "FramePort X.Y.Z" -m "<What's new, Markdown bullets>"`,
+  push the commit and the tag. Never publish a release without its `SHA256SUMS.txt` (the updater refuses it) and keep
+  the asset names (`updates.ASSETS`) — renaming them breaks updating for every installed copy.
+- Signing is **free/self-signed by the owner's choice** (no paid certs, no SignPath): Windows binaries are signed with
+  a self-signed "FramePort (self-signed)" code-signing cert (RSA 3072, valid to 2031, SHA-256
+  `4E:12:98:91:62:C0:E4:50:FB:65:1D:34:BB:73:00:09:7B:78:BE:88:5C:A7:6C:42:23:46:9B:92:A1:59:A7:6E`); secrets
+  `WINDOWS_CODESIGN_PFX` (base64) + `WINDOWS_CODESIGN_PASSWORD`. Private key: `~/.config/frameport-signing/` (WSL) and
+  the backup `PATCHED/_signing-keys/frameport-app-codesign/` — never commit it. macOS is ad-hoc signed only (Gatekeeper
+  needs right-click → Open; notarization would need the paid Apple program). Users still see SmartScreen unless they
+  import the .cer into Trusted Root.
+- CI gotchas: `flet build` needs `--yes --no-rich-output` (it prompts to install Flutter; rich output crashes the
+  Windows console) plus PYTHONUTF8; macOS builds need `--python-version 3.12 --arch arm64` (cryptography has no wheels
+  for flet's default Python / x86_64 cross-build), with a PyInstaller fallback step; `astral-sh/setup-uv` has no
+  floating major tags after v7 → pin the exact version; force-moving a tag starts duplicate runs (cancel one).
+- Windows PowerShell calls from Python (`updates._powershell()`): use `%SystemRoot%\System32\WindowsPowerShell\v1.0\
+  powershell.exe` with `PSModulePath` removed from the environment — started under PowerShell 7 (CI's default shell,
+  or a user's pwsh terminal) it couldn't run Get-AuthenticodeSignature (v0.3.0's Windows update smoke failed on it).
+  `v0.3.0` is a tag without a release (that failed build); the updater shipped first in v0.3.1.
+- **This project's GitHub identity is `spoopyghosty0`** (a dedicated account; the machine's default gh/git login is a
+  different, personal account that must never touch this repo). `gh` (`~/.local/bin/gh`) uses it through
+  `GH_CONFIG_DIR=~/.config/gh-spoopyghosty0` (set for Claude Code in the git-ignored `.claude/settings.local.json`);
+  git pushes from this folder authenticate as it through a repo-local credential helper, and commits use the repo-local
+  identity `spoopyghosty0 <336754034+spoopyghosty0@users.noreply.github.com>`. Check with `gh api user --jq .login`
+  before any GitHub action.
+- **No Claude trailers** (`Co-Authored-By: Claude …`, `Claude-Session: …`) in commits or PR descriptions — the owner's
+  rule; history was rewritten to remove them.
+- **The repo is public: never commit personal data** — the Frame's IP address, the Steam user id, the owner's email,
+  local home paths (native builds use `-ffile-prefix-map`). History was rewritten once to remove them.
+
+## Heuristics (games not in the catalog)
+Each patch's `detect()` suggests itself from the Analysis; `applies()` says whether it can matter at all (the UI/CLI
+hide non-applicable patches; enabled ones are always shown). Rules learned from the 34 games:
+MR-only (PASSTHROUGH required + BOUNDARYLESS_APP) → force_passthrough, + USE_SCENE → scene_emul + meta_permissions;
+hand tracking required → controller_fix=0; OVRPlugin + ≥20 GiB → disable_space_warp; Unreal ≤4.21 or Unreal Meta XR
+Audio → nodebug; Oculus-OS class referenced by the Unreal audio build or ≥2 Meta libs → oculusos; legacy-VrApi Unity
+GLES with MSAA → unity_no_msaa; CryEngine → user.cfg r_variable_rate_shading=0; direct VrApi → bridge (+GL shim for
+GLAD/GLES); Unreal → alternate no-ForceQuit build. Score changes with
+`python scripts/eval_heuristics.py "<dumps>"` (catalog off vs verified recipes; currently 33/34 exact — Phantom's
+"use the no-ForceQuit build" is only detectable at runtime via triage). Add a rule → re-run the eval + `pytest -m games`.
+
+## Frame operations
+- Find/connect: `frameport frame discover` / `frame info` (the remembered Frame is in `<user data>/frames.json`).
+- Power off over SSH: plain `systemctl poweroff` is refused by polkit for remote sessions; this works:
+  `ssh steamos@<frame> 'systemd-run --user --wait --pipe --quiet systemctl poweroff'`. `sudo` needs the user's password
+  (not known to Claude). A reboot clears leaked kernel keyrings.
+- Reinstalls keep one rollback copy (`<base>/previous-game.apk`, `settings.conf.previous`); `frameport frame cleanup`
+  removes them (and `--path ~/X` extra folders under home).
+
+## Project status (2026-09-29)
+34 Quest games ported; the owner confirmed in the headset that all FramePort-rebuilt games work: 23 work, 5 work with
+issues (Arcsmith/Time Stall eye distortion, AC Nexus some flipped launch text, Phantom DLC button, Silhouette hands),
+6 can't run (Sniper Elite VR, Espire 1, HITMAN, and the 32-bit Journey of the Gods / Shadow Point / Sports Scramble).
+Parity: all 34 rebuilt from the dumps match the known-good builds (`docs/parity-report.md`) and were reinstalled +
+launch-tested with 0 regressions (`docs/parity-device-report.md`). `PATCHED/` holds exactly the installed builds.
+Owner preferences: manual installs (no third-party installer apps), Python + Flet, dynamic data over hardcoding,
+free tooling only, public repo scrubbed of personal data, keep the known-good backups.
+Rift/PC VR support (2026-09-29): implemented + unit-tested, not yet tried with a real Rift game on the PC or Frame
+(needs a Rift dump, and Proton installed on the Frame). Open ideas: exe-icon artwork for Rift games, macOS x86_64 bundle, USB-cable connection (Frame `usb0`, untested),
+the unresolved eye distortion, and testing the release bundles on real Windows/macOS machines (never launched yet).

 ## Conventions
 - Dynamic first: fetch live data (tool versions, overport patch list/titles, artwork, catalog) with cache + bundled
@@ -1,36 +1,107 @@
 # FramePort

-Play your Meta Quest standalone games on the **Valve Steam Frame**. FramePort patches a Quest APK so it runs in the
-Frame's Lepton Android runtime, validates the result, installs it over Wi-Fi and adds it to your Steam library with
-artwork. Think Morphe/ReVanced Manager, for Quest → Steam Frame:
+FramePort installs Meta Quest standalone games and Oculus Rift PC VR games on the **Valve Steam Frame**. It patches a
+game so it runs on the Frame's runtimes, copies it to the headset over Wi-Fi and adds it to the Frame's Steam library
+with artwork.

-1. **Connect your Frame** once: the app shows one command to paste into the Frame's desktop terminal (it turns on SSH,
-   trusts the app, and installs Lepton). After that the app finds the Frame on your network by itself.
-2. **Add games**: scan a folder of Quest dumps (APK + OBB) or add an APK.
-3. **Review patches**: every game gets suggested patches (overport's plus Steam Frame fixes), each with a reason.
-   34 games have verified recipes; unknown games get heuristics.
-4. **Patch, validate, install**: signature/alignment/dependency checks, upload (resumable, skips data already on the
-   Frame), Steam shortcut + artwork, and a headless launch test with log triage that suggests fixes.
+![Library](docs/images/library.png)

-FramePort downloads and manages its own tools (Java runtime, [overport](https://github.com/ovrport/app) CLI,
-apksigner). Nothing is installed system-wide, and no Android SDK/NDK is needed.
+## Purpose

-## Install
- **App bundles**: download from [Releases](https://github.com/spoopyghosty0/frameport/releases) (Windows x64, macOS
-  Apple Silicon, Linux x64); see `docs/INSTALL.md` for the first-launch warning (self-signed / ad-hoc signed) and
-  how to verify a download. Built by CI (`.github/workflows/build.yml`, `flet build`).
- **From source**: `uv sync && uv run frameport-gui` (CLI: `uv run frameport --help`).
+FramePort is a **proof of concept**: it shows that VR software built for other platforms (Meta Quest, Oculus Rift) can
+run on the Steam Frame with a translation layer and a few targeted fixes. Most of the work is done by the projects
+FramePort wraps (see [Built on](#built-on)); FramePort selects and applies their fixes per game, adds Steam
+Frame-specific patches, and handles installing, testing and launching.

-## Status of tested games
-See `catalog/games/` (and the Library screen): 23 work, 5 work with issues, 6 can't run on the Frame (3 are 32-bit
-only; PC VR alternatives are listed). Details and how problems were solved: `docs/PLAYBOOK.md`.
-All 34 recipes were verified by rebuilding from the original dumps (`docs/parity-report.md`: 34/34 match the
-hand-made known-good builds) and reinstalling + launch-testing on a Frame (`docs/parity-device-report.md`: 0 regressions).
+FramePort is **not a piracy tool**. It does not download, share or unlock games, and it does not remove DRM, licence or
+entitlement checks. Use it only with games you own. Games that check their licence through the Oculus Platform SDK are
+marked as not runnable on the Frame.

-## Legal
-Use only with games you own. FramePort does not download games. It is GPL-3.0-only because it bundles code derived
-from GPL-3.0 projects (Quest2Frame's hook technique in the adapter, the Android-XR-Bridge/OVRPort VrApi bridge).
-overport is downloaded from its official releases and is not redistributed.
+## Getting started
+
+1. **Download** the archive for your computer from the
+   [latest release](https://github.com/spoopyghosty0/frameport/releases/latest) and extract it anywhere:
+
+   | Computer | File | Start |
+   |---|---|---|
+   | Windows 10/11 (x64) | `FramePort-windows-x64.zip` | `FramePort.exe` |
+   | macOS (Apple Silicon) | `FramePort-macos-arm64.zip` | `FramePort.app` |
+   | Linux (x64) | `FramePort-linux-x64.tar.gz` | `FramePort/FramePort` |
+
+   The builds are self-signed, so the first start shows a warning: Windows → **More info → Run anyway**;
+   macOS → right-click the app → **Open**. Details: [docs/INSTALL.md](docs/INSTALL.md).
+2. **Get the tools**: on first start FramePort downloads what it needs (Java runtime, OVRPort, apksigner) into its own
+   folder. Nothing is installed system-wide.
+3. **Connect the Frame**: turn on Developer Mode on the Frame (Settings → System → Developer). In FramePort open
+   **Steam Frame**; if the Frame isn't listed, switch it to Desktop mode, open Konsole and paste the one command
+   FramePort shows. This is needed once.
+4. **Add games**: **Add games → Scan a folder** with your Quest game backups (APK + OBB) or Rift game folders.
+   FramePort identifies each game and fetches its artwork and store details.
+5. **Install**: open a game and click **Install on Frame**. FramePort patches, checks, uploads and adds the game to the
+   Frame's Steam library, then runs a short launch test.
+6. **Play**: put the headset on and start the game from the Steam library (or click **Play on Frame**).
+
+![Game page](docs/images/game.png)
+
+FramePort updates itself: when a new version is released, the Library shows **Update now**.
+
+## What works
+
+The built-in catalog has tested settings for 38 games (27 work, 5 work with known issues, 6 can't run on the Frame).
+Other games get suggested patches from detection rules; each suggestion states its reason, and every patch can be
+switched on or off under **Customize**.
+
+![Patches](docs/images/patches.png)
+
+- Quest games run in Valve's Android runtime (Lepton). 32-bit-only Quest games can't run (the Frame has no 32-bit ARM
+  support).
+- Rift games run through Proton on the Frame (experimental) or on a Windows PC with SteamVR, streamed to the Frame.
+  Games that use the Oculus Platform SDK need the Oculus app and a licence, so they run on the PC only.
+- Automated launch tests confirm a game starts; visuals can only be checked in the headset.
+
+![Steam Frame](docs/images/frame.png)
+
+## Built on
+
+FramePort is a front end for other projects; most of the functionality comes from them:
+
+| Project | Used for |
+|---|---|
+| [OVRPort](https://github.com/Android-XR-Bridge/OVRPort) (overport, originally [ovrport/app](https://github.com/ovrport/app)) | Converts Quest games to OpenXR: its CLI applies the game patches and supplies the OpenXR loader; FramePort also includes its VrApi→OpenXR adapter |
+| Valve Lepton, Proton and SteamVR | Run Android games, Windows games and OpenXR on the Frame |
+| [Revive](https://github.com/LibreVR/Revive) (LibreVR) | Runs Oculus Rift games on OpenXR / SteamVR |
+| Mesa (Zink) | OpenGL ES on Vulkan on the Frame |
+| [Khronos OpenXR SDK](https://github.com/KhronosGroup/OpenXR-SDK) | OpenXR headers for the native layers |
+| Eclipse Temurin, Android apksigner, Android NDK | Java runtime, APK signing, building the native layers |
+| [Flet](https://flet.dev) | The desktop app |
+| OculusDB, Steam store | Game descriptions, genres and artwork |
+
+FramePort's own parts: game detection and recipes, the Steam Frame OpenXR adapter (FrameBridge) and the other native
+fixes in `native/`, the installer agent that runs on the Frame, and the desktop/command-line app.
+
+## Command line
+
+The same functions are available as `frameport` (included in the source tree; also released as a Python wheel):
+`frameport scan`, `frameport build`, `frameport install`, `frameport test`, `frameport update`. Run
+`frameport --help` for the full list.
+
+## Documentation
+
+- [docs/INSTALL.md](docs/INSTALL.md): installing, first launch, updating, Rift games, sending files, reporting problems.
+- [docs/PLAYBOOK.md](docs/PLAYBOOK.md): symptoms and fixes per game.
+- [docs/FRAME_RUNTIME.md](docs/FRAME_RUNTIME.md): Steam Frame runtime facts.
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): how the code is organised.

 ## Development
-See `CLAUDE.md` (architecture, commands, findings) and `docs/ARCHITECTURE.md`.
+
+```
+uv sync --extra dev
+uv run frameport-gui        # the app
+uv run pytest               # tests
+```
+
+See `CLAUDE.md` for project notes and `native/README.md` for the native components.
+
+## License
+
+GPL-3.0-only (it includes GPL-3.0 code from OVRPort). Not affiliated with Valve or Meta.
@@ -1,6 +1,12 @@
+0f681f54b59cfad2efc8883aee5a0971c2fba09d9ba2dca15a136b0ac74a59b8  ./arm64-v8a/libfp_vk.so
+8e00552d1ab90f82749db3caad4f773351fa8a28edcc5ea5cbd1b31c434ff32a  ./arm64-v8a/libframe_xrshim.so
 3dfcb0f2bec47857bcecc7261c58e076d872d4649718c40850f29e10c75477dd  ./arm64-v8a/libglshim.so
-ca27ffa2122def910697ddcaff64f25cfdbc63e2017c738155866ff2fcdb5e12  ./arm64-v8a/libopenxr_loader_generic.so
+dc62857b4f7a23b194060599339dfe72b38c16cdf4a9eb1b1f3b4d1fb9071a6d  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
 32525cd0a9ee3d9993d8871cd6905bdcf22cde4f4ba28f5db6434ce7d6554758  ./arm64-v8a/libvrapi.so
-f3aa9419155b8970617fc0d68527a73c39abc82303214c159194c439bb776fd6  ./armeabi-v7a/libopenxr_loader_generic.so
+a79c598744b98b9bf581664a80bcee1a0d11a62fdcdb99f05a0f6f381b6498cd  ./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
+c2c70f4af1a5c3e6089dff1130161dd417f8044f99ec639eeecf1083930aab16  ./win-x64/fp_oculushmd.exe
+60ebc5fea05b8945082e2ca8b9f2eb74616012a26eb50133af273dff0fcddc42  ./win-x64/fp_vrsettings.exe
@@ -0,0 +1,11 @@
+{
+    "file_format_version": "1.0.0",
+    "api_layer": {
+        "name": "XR_APILAYER_FRAMEPORT_timefix",
+        "library_path": "./libxr_frameport_timefix.so",
+        "api_version": "1.0",
+        "implementation_version": "1",
+        "description": "FramePort: XR_KHR_convert_timespec_time emulation for Proton games on the Steam Frame",
+        "instance_extensions": [{"name": "XR_KHR_convert_timespec_time", "extension_version": "1"}]
+    }
+}
@@ -0,0 +1,20 @@
+package: cn.vr4p.oculus4xvrplayerov
+title: 4XVR Video Player
+status: works
+notes: 'Native OpenXR GLES video player. 360 theatres/videos (equirect2 layers, which the Frame lacks) are drawn
+  by FrameBridge''s equirect_emul; stable_local/focus_hold stop the menu recentring; scale 0.75 keeps the menu screen
+  at 72 fps (the runtime asks for 4536 px per eye). Confirmed in the headset by the owner (2026-10-01). Its "Internal
+  Storage" list is /sdcard/4XPlayer: send videos with the game page''s "Add videos".'
+details: 'Settings: equirect_emul (GLES worker draws 360 layers into a projection layer), stable_local, focus_hold,
+  scale 0.75; frame.swapchain_limit for its 7680x3840 theatre swapchains.'
+tested_version: 2.0.22
+engine: Other
+xr: OpenXR
+adapter:
+  equirect_emul: 1
+  stable_local: 1
+  focus_hold: 1
+  scale: 0.75
+verified:
+  date: '2026-10-01'
+source_hint: 4XVR Video Player
@@ -1,7 +1,7 @@
 package: com.Armature.SportsScramble
 title: Sports Scramble (Santa Cruz)
 tested_version: '1.0'
-source_hint: Sports Scramble v88+1.0
+source_hint: Sports Scramble
 engine: Unreal
 xr: VrApi
 status: unsupported
@@ -1,7 +1,7 @@
 package: com.Astrea.Gundam
 title: 'Mobile Suit Gundam: Silver Phantom'
 tested_version: 1.1.58.402
-source_hint: Mobile Suit Gundam- Silver Phantom v868+1.1.58.402
+source_hint: 'Mobile Suit Gundam- Silver Phantom'
 engine: Unity
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.BithellGames.Arcsmith
 title: Arcsmith
 tested_version: '1.128'
-source_hint: Arcsmith v128+1.128
+source_hint: Arcsmith
 engine: Unity
 xr: VrApi
 status: issues
@@ -1,7 +1,7 @@
 package: com.BolverkGames.GenotypeGame
 title: Genotype
 tested_version: '1.8'
-source_hint: Genotype v922+1.8
+source_hint: Genotype
 engine: Unity
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.DigitalLode.Espire1
 title: 'Espire 1: VR Operative (Quest Edition)'
 tested_version: 1.13.36
-source_hint: Espire 1- VR Operative v2025+1.13.36
+source_hint: 'Espire 1- VR Operative'
 engine: Unreal
 xr: VrApi
 status: unsupported
@@ -1,7 +1,7 @@
 package: com.DigitalLode.Espire2
 title: Espire 2
 tested_version: 1.7.13
-source_hint: Espire 2- Stealth Operatives v9187+1.7.13
+source_hint: 'Espire 2- Stealth Operatives'
 engine: Unreal
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.FuturLab.PowerWashSimulator
 title: PowerWash Simulator VR
 tested_version: 2.5.0
-source_hint: PowerWash Simulator VR v3055+2.5.0
+source_hint: PowerWash Simulator VR
 engine: Unity
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.JustAddWater.SniperEliteVR
 title: Sniper Elite VR
 tested_version: '1.03'
-source_hint: Sniper Elite VR v35713+1.03
+source_hint: Sniper Elite VR
 engine: Unity
 xr: VrApi
 status: unsupported
@@ -1,7 +1,7 @@
 package: com.JustAddWater.SniperEliteVR_EN
 title: 'Sniper Elite VR: Winter Warrior'
 tested_version: 1.0.1
-source_hint: Sniper Elite VR- Winter Warrior v125+1.0.1
+source_hint: 'Sniper Elite VR- Winter Warrior'
 engine: Unity
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.Novelab.Demeter
 title: Demeter
 tested_version: 1.1.0
-source_hint: Demeter v53+1.1.0
+source_hint: Demeter
 engine: Unity
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.Sanzaru.Wrath2
 title: Asgard's Wrath 2
 tested_version: 12.1.1689309
-source_hint: Asgards Wrath 2 v5513+12.1.1689309
+source_hint: Asgards Wrath 2
 engine: Unreal
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.Solfar.InDeath
 title: 'In Death: Unchained'
 tested_version: 1.8.0
-source_hint: In Death- Unchained v123248087+1.8.0
+source_hint: 'In Death- Unchained'
 engine: Unreal
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.TeamPanoptes.SilhouetteVR
 title: Silhouette
 tested_version: 1.3.0
-source_hint: Silhouette v200090+1.3.0
+source_hint: Silhouette
 engine: Unity
 xr: OpenXR
 status: issues
@@ -1,7 +1,7 @@
 package: com.Ubisoft.ACNexusVR
 title: Assassin's Creed Nexus
 tested_version: MAIN.450412.207706.final
-source_hint: Assassins Creed Nexus VR v207706+MAIN.450412.207706.final
+source_hint: Assassins Creed Nexus VR
 engine: Unity
 xr: OpenXR
 status: issues
@@ -1,7 +1,7 @@
 package: com.VRFactory.VRBartender
 title: BARTENDER VR SIMULATOR
 tested_version: 1.9.2.7
-source_hint: BARTENDER VR SIMULATOR v1338+1.9.2.7
+source_hint: BARTENDER VR SIMULATOR
 engine: Unreal
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.ViteiBackroom.Powder
 title: Carve Snowboarding
 tested_version: '1.09'
-source_hint: Carve Snowboarding v585+1.09
+source_hint: Carve Snowboarding
 engine: Unreal
 xr: VrApi
 status: works
@@ -1,7 +1,7 @@
 package: com.YourCompany.RoboRecall
 title: Robo Recall
 tested_version: '1.0'
-source_hint: Robo Recall- Unplugged v47091+1.0
+source_hint: 'Robo Recall- Unplugged'
 engine: Unreal
 xr: VrApi
 status: works
@@ -1,7 +1,7 @@
 package: com.camouflaj.manta
 title: 'Batman: Arkham Shadow'
 tested_version: 1.4.1-350961
-source_hint: Batman- Arkham Shadow (Inc Lang Packs) v350961+1.4.1-350961
+source_hint: 'Batman- Arkham Shadow'
 engine: Unity
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.coatsink.nexus
 title: Shadow Point
 tested_version: '1.4'
-source_hint: Shadow Point v47+1.4
+source_hint: Shadow Point
 engine: Unity
 xr: VrApi
 status: unsupported
@@ -1,7 +1,7 @@
 package: com.com.spectralgames.Medieval
 title: Medieval Dynasty New Settlement
 tested_version: '2.4'
-source_hint: Medieval Dynasty New Settlement v233+2.4
+source_hint: Medieval Dynasty New Settlement
 engine: Unity
 xr: OpenXR
 status: works
@@ -1,8 +1,8 @@
 package: com.crytek.climb2
 title: The Climb 2
 tested_version: '2.2'
-source_hint: The Climb 2 v974+2.2
-engine: Other
+source_hint: The Climb 2
+engine: CryEngine
 xr: VrApi
 status: works
 notes: 'CryEngine direct VrApi (Vulkan): VrApi bridge + platform compat; user.cfg disables VRS.'
@@ -1,7 +1,7 @@
 package: com.forcefieldxr.timestall
 title: Time Stall
 tested_version: '1.0'
-source_hint: Time Stall v631960+1.0
+source_hint: Time Stall
 engine: Unreal
 xr: VrApi
 status: issues
@@ -1,7 +1,7 @@
 package: com.gritGames.Nope
 title: NOPE CHALLENGE
 tested_version: 1.0.964.7166
-source_hint: NOPE CHALLENGE v964+1.0.964.7166
+source_hint: NOPE CHALLENGE
 engine: Unreal
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.iillusions.bamgame
 title: BAM
 tested_version: '1.2'
-source_hint: BAM v2786+1.2
+source_hint: BAM
 engine: Unity
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.nDreams.PhantomQuest
 title: 'Phantom: Covert Ops'
 tested_version: '1.2'
-source_hint: Phantom- Covert Ops v498003+1.2
+source_hint: 'Phantom- Covert Ops'
 engine: Unreal
 xr: VrApi
 status: issues
@@ -0,0 +1,11 @@
+package: com.nexxr.nexplayer
+title: NEX Player
+status: works
+notes: 'Confirmed in the headset by the owner (2026-10-01): 72 fps, local 2D/360/3D videos play (it browses /sdcard/Movies
+  itself). USB-drive browsing can''t work in Lepton.'
+tested_version: 1.3.1.0
+engine: Unity
+xr: OpenXR
+verified:
+  date: '2026-10-01'
+source_hint: NEX - NEXt-Gen Video Player
@@ -1,7 +1,7 @@
 package: com.noghost.thegrandgetaway
 title: Wallace & Gromit in The Grand Getaway
 tested_version: 1.0.34
-source_hint: Wallace & Gromit in The Grand Getaway v141+1.0.34
+source_hint: Wallace & Gromit in The Grand Getaway
 engine: Unreal
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.sigtrapgames.undercover
 title: Under Cover
 tested_version: 1.1.3r2
-source_hint: Under Cover v10147+1.1.3r2
+source_hint: Under Cover
 engine: Unity
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: com.thunderful.legobricktales
 title: LEGO® Bricktales
 tested_version: '2.1'
-source_hint: LEGO Bricktales v201449+2.1
+source_hint: LEGO Bricktales
 engine: Unity
 xr: OpenXR
 status: works
@@ -0,0 +1,17 @@
+package: com.twistedpixelgames.PILO
+title: Marvel's Deadpool VR
+status: works
+notes: 'Unreal (Vulkan): Lepton''s Fossilize layer crashed on uninitialized render-pass pNexts; frame.vk_sanitize
+  fixes it. Confirmed working in the headset by the owner (2026-10-01).'
+details: Needs frame.vk_sanitize (native/vkshim) and frame.swapchain_limit; space warp disabled (32 GiB OVRPlugin
+  game).
+tested_version: 1.0.40.356975.Quest
+engine: Unreal
+xr: OpenXR
+overport_extra:
+- patch_disable_space_warp
+alt_overport:
+- patch_remove_unreal_force_quit
+verified:
+  date: '2026-10-01'
+source_hint: Marvels Deadpool VR
@@ -1,7 +1,7 @@
 package: com.twistedpixelgames.POTW_App
 title: Path of the Warrior
 tested_version: 21.11.10.358057
-source_hint: Path of the Warrior v498+21.11.10.358057
+source_hint: Path of the Warrior
 engine: Other
 xr: VrApi
 status: works
@@ -1,7 +1,7 @@
 package: com.xrgames.hitman3reloaded
 title: 'HITMAN 3 VR: Reloaded'
 tested_version: 0.0.3469 main-14813cc56
-source_hint: HITMAN 3 VR- Reloaded v3469+0.0.3469
+source_hint: 'HITMAN 3 VR- Reloaded'
 engine: Other
 xr: OpenXR
 status: unsupported
@@ -1,7 +1,7 @@
 package: gg.trs.grappa
 title: Journey of the Gods
 tested_version: 1.0.479431
-source_hint: Journey of the Gods v479431+1.0.479431
+source_hint: Journey of the Gods
 engine: Unreal
 xr: VrApi
 status: unsupported
@@ -0,0 +1,23 @@
+package: rift.rick_and_morty_virtual_rick_ality
+title: 'Rick and Morty: Virtual Rick-ality'
+kind: rift
+tested_version: v2288226
+source_hint: 'Rick and Morty - Virtual Rick-ality'
+engine: Unity
+xr: OpenVR
+status: works
+notes: Runs on the Frame under Proton without Revive (this build talks to SteamVR directly). Slight stutter.
+details: The dump's executable already uses SteamVR (OpenVR), so it is installed as it is; Proton's VR bridge only
+  starts with FramePort's OpenXR layer (the Frame runtime accepts OpenXR 1.0 apps only). Confirmed in the headset.
+as_is: true
+pcvr:
+- pcvr.xr_timefix
+pcvr_remove:
+- pcvr.revive
+verified:
+  date: '2026-09-29'
+  target: frame
+  frame_os: SteamOS 0.4.2 (build 20260928.6175029)
+  proton: proton_11-arm64
+  exe: Rick and Morty - Virtual Rick-ality/RickAndMortyVR.exe
+  exe_sha256: 01678ebd02edec86258c482fbb5d00f3f0474e1a6515a905531f81df1a80ec50
@@ -1,7 +1,7 @@
 package: studio.NewFolderGames.ToyMaster
 title: Toy Master
 tested_version: 1.1.2
-source_hint: Toy Master v6+1.1.2
+source_hint: Toy Master
 engine: Unity
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: us.lighthaus.nanocellx
 title: Nano
 tested_version: '1.711'
-source_hint: Nano v334+1.711
+source_hint: Nano
 engine: Unity
 xr: OpenXR
 status: works
@@ -1,7 +1,7 @@
 package: xyz.muware.hunt.vr
 title: H.U.N.T
 tested_version: 0.1.2
-source_hint: H.U.N.T v11+0.1.2
+source_hint: H.U.N.T
 engine: Unity
 xr: OpenXR
 status: works
@@ -36,6 +36,7 @@ signatures:
    use_alt: true
  - id: swapchain-format
    pattern: 'xrCreateSwapchain.*(-26|FORMAT_UNSUPPORTED)|swapchain format .* rejected'
+    unless: 'FrameBridge:\s+retry (samples=1|format=\d+) result=0'  # the adapter's fallback worked
    severity: error
    diagnosis: The Frame rejected the swapchain format (GLES games must use sRGB formats, no MSAA).
    suggest: [adapter.swapchain_fix]
@@ -64,6 +65,19 @@ signatures:
    severity: error
    diagnosis: The game needs Meta passthrough; the adapter emulates it.
    suggest: [adapter.passthrough_emul, patch_force_passthrough]
+  - id: render-model-requested
+    pattern: 'dropped unsupported extension XR_FB_render_model'
+    severity: info
+    diagnosis: The game asks the headset for its controller models (XR_FB_render_model), which the Frame lacks, so it
+      shows its own (Quest) controllers or none. The adapter can serve the Steam Frame controllers instead.
+    suggest: [adapter.controller_models]
+  - id: controller-models-missing
+    pattern: 'FrameBridge: controller models not found'
+    severity: warning
+    diagnosis: Steam Frame controller models are on, but the converted models aren't in the game's files dir (the
+      agent found no Frame controller render models in SteamVR at install time; see the install log, or run the
+      agent's controller_models command).
+    suggest: []
  - id: scene-missing
    pattern: 'XR_FB_scene|XR_FB_spatial_entity.*(not supported|UNSUPPORTED)|xrQuerySpacesFB'
    severity: warning
@@ -74,6 +88,30 @@ signatures:
    severity: warning
    diagnosis: Runtime lacks timespec time conversion (emulated by the current adapter build).
    suggest: [frame.adapter]
+  - id: fossilize-renderpass
+    pattern: '#0\d pc [^\n]*libVkLayer_fossilize\.so[\s\S]{0,4000}?FVulkanRenderPass::FVulkanRenderPass'
+    severity: fatal
+    diagnosis: Lepton's Fossilize layer crashed while recording a render pass (the engine leaves an attachment reference's pNext uninitialized).
+    suggest: [frame.vk_sanitize]
+    supersedes: [native-crash]
+  - id: equirect-layers-dropped
+    pattern: 'new layer: type=100009100\d [^\n]*usable=0|new layer: type=1000018000 [^\n]*usable=0'
+    severity: warning
+    diagnosis: The game shows 360° (equirect) layers, e.g. a video player's theatre or 360° videos, which the Frame's
+      runtime can't composite, so they are missing. GLES games can get them back as panels around the player.
+    suggest: [adapter.equirect_emul]
+  - id: equirect-emul-disabled
+    pattern: 'equirect_emul: (disabled|drawing failed|not a GLES session)'
+    severity: warning
+    diagnosis: The 360° layer emulation switched itself off for this session (no shared GLES context, or drawing
+      failed); the 360° layers are dropped as without it. See the lines before it in the log.
+    suggest: []
+  - id: swapchain-size-abort
+    pattern: '#01 pc [^\n]*libopenxr_loader\.so \(xrCreateSwapchain\+|Wrong createInfo size'
+    severity: fatal
+    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: native-crash
    pattern: 'Fatal signal (\d+) \(SIG[A-Z]+\)'
    severity: fatal
@@ -106,7 +144,95 @@ signatures:
    severity: warning
    diagnosis: The game created folders it can't write (saves break). The FramePort launcher repairs permissions every 2 s.
    suggest: []
+  # ---- PC VR (Oculus Rift games under Revive; on the Frame under Proton). kind: pcvr = only for those logs
+  - id: proton-missing-runtime
+    kind: pcvr
+    pattern: 'needs Steam app \d+ \(runtime\)|_v2-entry-point: (No such file|not found)'
+    severity: fatal
+    diagnosis: The Steam Linux Runtime that Proton needs isn't installed on the Frame.
+    suggest: []
+  - id: revive-inject-failed
+    kind: pcvr
+    pattern: 'Failed to create process'
+    severity: fatal
+    diagnosis: Revive's injector could not start the game (wrong exe path, or a 32-bit/64-bit mismatch).
+    suggest: []
+  - id: oculus-hmd-event
+    kind: pcvr
+    pattern: 'FramePort oculushmd: could not (create the OculusHMDConnected event|start the command)'
+    severity: error
+    diagnosis: FramePort's Oculus detection helper couldn't provide the OculusHMDConnected event (or couldn't start the game). Unreal's Oculus plugin then skips VR silently and the game runs as a flat window.
+    suggest: [pcvr.oculus_unreal, pcvr.proton_log]
+  - id: openxr-no-runtime
+    kind: pcvr
+    # (not the loader's 'xrCreateInstance failed': Proton's own OpenXR probe fails once and retries on the Frame)
+    pattern: 'XR_ERROR_RUNTIME_(UNAVAILABLE|FAILURE)|No OpenXR runtime|OpenXR runtime (is )?not (found|available)|failed to (create|initialize) (the )?OpenXR'
+    severity: fatal
+    diagnosis: No OpenXR runtime reached the game. On a PC start SteamVR (or set it as the OpenXR runtime); on the Frame Proton couldn't bridge to the Frame runtime.
+    suggest: []
+  - id: openxr-missing-ext
+    kind: pcvr
+    pattern: 'XR_ERROR_EXTENSION_NOT_PRESENT|XR_KHR_D3D11_enable.*(not|unsupported)'
+    severity: fatal
+    diagnosis: The OpenXR runtime lacks an extension Revive requires (XR_KHR_D3D11_enable / win32 time conversion).
+    suggest: [pcvr.xr_timefix, pcvr.revive_openvr]
+  - id: openxr-api-version
+    kind: pcvr
+    pattern: 'LoaderInstance::CreateInstance chained CreateInstance call failed|XR_ERROR_API_VERSION_UNSUPPORTED|Unable to load LibOVRRT DLL'
+    severity: fatal
+    diagnosis: Proton's VR setup couldn't create an OpenXR instance (the Frame's SteamVR runtime only accepts OpenXR 1.0 apps; Proton asks for 1.1), so the game got no VR — a flat window, or Revive fails with "Unable to load LibOVRRT DLL".
+    suggest: [pcvr.xr_timefix]
+  - id: openxr-time-conversion
+    kind: pcvr
+    pattern: 'xrConvert(TimespecTimeToTime|TimeToTimespecTime)KHR failed|XR_KHR_convert_timespec_time not available'
+    severity: error
+    diagnosis: The OpenXR runtime refused time conversion, which Proton needs for Windows games' performance-counter times.
+    suggest: [pcvr.xr_timefix]
+  - id: delayload-missing
+    kind: pcvr
+    pattern: '[Ee]xception:? 0xc06d007e|code=c06d007e'
+    severity: fatal
+    diagnosis: A DLL the game loads on demand is missing (Windows delay-load error). For Oculus Store games this is usually LibOVRPlatform64_1.dll, the Oculus Platform SDK that the Oculus app installs for the licence check; FramePort doesn't replace it, so such games need the Oculus app (PC mode).
+    suggest: []
+    supersedes: [unreal-crash, wine-crash]  # the crash is this missing DLL; don't send the user after other fixes
+  - id: oculus-entitlement
+    kind: pcvr
+    pattern: '(?i)entitlement (check )?fail|ovr_PlatformInitialize.*(fail|error)|ovrPlatformInitialize_(NotEntitled|Uninitialized|PreLoaded|FileInvalid|SignatureInvalid|UnableToVerify)'
+    severity: fatal
+    diagnosis: The Oculus Platform SDK entitlement check failed. The game needs the Oculus app running with a license you own (PC mode only).
+    suggest: []
+  - id: vcruntime-missing
+    kind: pcvr
+    pattern: '(?i)(MSVCP|VCRUNTIME)\d+[_\d]*\.dll.*(not found|missing)'
+    severity: error
+    diagnosis: The game needs a Microsoft Visual C++ runtime. Install the vc_redist that ships with the game (or winetricks vcrun2019 in the prefix).
+    suggest: []
+  - id: dxvk-device-lost
+    kind: pcvr
+    pattern: 'DXVK: .*(DEVICE_LOST|Device lost)|VK_ERROR_DEVICE_LOST'
+    severity: fatal
+    diagnosis: The GPU driver lost the device while running the game (D3D through DXVK on freedreno).
+    suggest: [pcvr.proton_log]
+  - id: unreal-crash
+    kind: pcvr
+    pattern: 'CrashReportClient|UE4CC-Windows|UECC-Windows|Fatal error!|Unhandled Exception: EXCEPTION'
+    severity: fatal
+    diagnosis: The game crashed (Unreal's crash reporter started). See the game log and crash summary in the log. Common causes are that no VR runtime reached the game (Revive off) or a GPU or driver problem under Proton.
+    suggest: [pcvr.revive, pcvr.proton_log, pcvr.no_crash_reporter]
+  - id: wine-crash
+    kind: pcvr
+    pattern: 'Unhandled exception: page fault|wine: Unhandled|Backtrace:'
+    severity: error
+    diagnosis: The game crashed under Wine/Proton (set the Proton debug log and check steam-<appid>.log).
+    suggest: [pcvr.proton_log]
+
 milestones:  # progress markers, in order; the furthest one reached is reported
+  - {id: pcvr-launch, kind: pcvr, pattern: 'FramePort: launching|Launched injector with', label: Launcher started}
+  - {id: pcvr-oculus-hmd, kind: pcvr, pattern: 'FramePort oculushmd: OculusHMDConnected event ready', label: Oculus headset event provided}
+  - {id: pcvr-inject, kind: pcvr, pattern: 'Succesfully injected|Successfully injected', label: Revive injected into the game}
+  - {id: pcvr-window, kind: pcvr, pattern: 'Executable name: (?!steam\.exe|CrashReportClient)\S+\.exe|Creating Gamescope surface', label: Game window created}
+  - {id: pcvr-openxr, kind: pcvr, pattern: 'wineopenxr: .*[Ss]ession|LibReviveXR|Revive.*OpenXR|xrCreateSession', label: OpenXR reached}
+  - {id: pcvr-session, kind: pcvr, pattern: 'xrCreateSession|XR_SESSION_STATE_(READY|SYNCHRONIZED)', label: OpenXR session created}
  - {id: container, pattern: 'Boot complete!', label: Lepton container started}
  - {id: process, pattern: 'Start proc \d+:', label: App process started}
  - {id: adapter, pattern: 'FrameBridge: scale=', label: FrameBridge adapter loaded}
@@ -1,15 +1,15 @@
 # Architecture

 ```
-            ┌────────────── UI (Flet, ui/app.py) ─────────────┐   ┌── CLI (cli.py) ──┐
+            ┌──────── UI (Flet, ui/: app shell + views/) ─────┐   ┌── CLI (cli.py) ──┐
            └───────────────────────┬─────────────────────────┘   └────────┬─────────┘
                                    ▼                                      ▼
                          pipeline.py  (add → suggest → build → install → test)
      ┌──────────────┬──────────────┼───────────────┬───────────────┬──────────────┐
  sources/      analysis/      recommend/        build.py        targets/       validate/
  quest_dump    detect, elf    catalog, engine   overport →      base.Target    static, device,
-                stubgen        (+ catalog/*.yaml) patches(apk) →  frame_lepton   triage (+triage.yaml)
-                                                  apk/sign        revive (todo)
+  rift_dump     stubgen, rift  (+ catalog/*.yaml) patches(apk) →  frame_lepton   triage (+triage.yaml)
+                                                  apk/sign        pc_revive
                                    │                │                 │
                              patches/ registry   tools/ toolchain   frame/ ssh, discovery, pairing
                              overport, frame/*,  (JRE, overport,    install/installer ──► agent (on Frame)
@@ -22,8 +22,9 @@
   direct-VrApi, GLAD/eglGetProcAddress, Unity MSAA levels, Meta permissions, telemetry references.
 3. **Recipe** (`recommend/engine.py`): every patch's `detect()` suggests itself with a reason; a catalog entry (exact
   known-good recipe) overrides heuristics. The UI shows toggles; the user confirms.
-4. **Build** (`build.py`): overport (defaults + extras) → apk-stage patches in `order` on an `ApkWorkspace` → apksigner
-   (with the package's own keystore) → static validation. Optional alternate build (e.g. without Unreal ForceQuit).
+4. **Build** (`build.py`): overport CLI (OVRPort; defaults + extras) → apk-stage patches in `order` on an
+   `ApkWorkspace` → apksigner (with the package's own keystore) → static validation. Optional alternate build (e.g.
+   without Unreal ForceQuit).
 5. **Install** (`install/installer.py` + `agent/frameport_agent.py`): `prepare` (paths, what's already there) → SFTP
   uploads with resume → `finalize` (move into place, settings.conf/framebridge.conf, device files, launch.sh,
   deployment.json, artwork) → `shortcuts` (detached systemd unit stops Steam, writes shortcuts.vdf + grid art,
@@ -34,13 +35,52 @@
 ## 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`.
+- **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`.
 - **New game recipe**: `catalog/games/<package>.yaml` (or "Save as known-good" in the GUI, which writes to the user
  catalog). Publish recipes by serving a folder with `index.json` and pointing `FRAMEPORT_CATALOG_URL` at it.
- **New target** (Revive/PC VR): implement `targets/base.Target`; the pipeline and UI only use that interface.
- **Native binaries** (`artifacts/`): edit `native/…`, run `native/build.sh`, commit the new artifacts + SHA256SUMS,
+- **New target**: implement `targets/base.Target`; the pipeline and UI only use that interface.
+
+## Oculus Rift (PC VR) games
+`sources/rift_dump` finds Windows game folders; `analysis/rift` (own PE reader) detects exe, bitness, engine, LibOVR vs
+OpenXR, D3D version and Oculus Platform SDK use; ids are `rift.<slug>`. Their only patches are the `pcvr` category
+(`patches/pcvr.py`: Revive, OpenVR backend, crash reporter, Oculus detection, OpenXR layer, Proton
+log/version/env); `base.for_game` keeps Quest and PC VR patches
+apart. "Build" = `pipeline.prepare_rift` (checks + Revive). Revive is a portable tool (`tools/revive.py` unpacks
+`ReviveInstaller.exe` in pure Python: NSIS header + deflate blocks). Targets:
+- `targets/pc_revive.PcReviveTarget`: Windows/WSL (`core/winhost.py`), non-Steam shortcut running
+  `ReviveInjector.exe /openxr <exe>` via the agent's VDF code, grid art, local records in `<user data>/pc/`.
+- `FrameLeptonTarget.install_pcvr` → `installer.install_pcvr` → agent `prepare_pcvr`/`finalize_pcvr`: upload
+  `game/` + `revive/` (+ `xrlayer/` for `pcvr.xr_timefix`, `helpers/` for `pcvr.oculus_unreal`; size-manifest dedupe,
+  stale files removed), `launch.sh` running the ARM64 Proton chain (built from toolmanifest.vdf; with
+  `pcvr.oculus_unreal` the injector runs through `helpers/fp_oculushmd.exe`, which provides Unreal's
+  `OculusHMDConnected` event); `proton_status`/`install_proton` manage Proton from Valve's ARM64 compat list.
+- **Native binaries** (`artifacts/`): edit `native/…`, run `python native/build.py`, commit the new artifacts + SHA256SUMS,
  run `frameport parity` to see which games change.

+## Self-update (`updates.py`, `ui/updater.py`, `cli.py update`)
+```
+check()  GitHub releases/latest (cached 6 h, drafts/prereleases skipped, "skipped" version remembered)
+   │     → Update(version, notes = release body incl. "What's new" from the annotated tag, asset for this OS, sums, wheel)
+   ▼
+install_kind()  bundle (running exe inside FramePort.exe's folder / FramePort.app / FramePort/FramePort)
+   │            source (git checkout) → git pull --ff-only + uv sync     wheel (uv tool / pipx / pip) → reinstall wheel
+   ▼ bundle
+prepare()  <data>/updates/<ver>/: download → SHA256SUMS.txt check → extract to staged/ (ditto on macOS) → layout check
+   │       → Windows: same Authenticode signer as the running exe → ready.json
+   ▼
+apply()   writes <data>/updates/apply.{ps1,sh}, starts it detached; FramePort quits. The script waits for the pid,
+          Windows: backs up the files it replaces (updates/<ver>/previous) and copies over the folder (the zip has
+          no folder of its own); macOS/Linux: mv target → .old, staged → target, rollback on failure, clears the
+          quarantine; then relaunches. Log: <data>/logs/update.log.
+```
+GUI: background check 10 s after start + every 6 h → sidebar card + Library bar → dialog with notes → job
+`app-update` (waits for other jobs) → restart. "Install updates automatically": prepare in the background, apply in
+`main()` before the window opens. CLI: once-a-day hint from the cached result (a daemon thread refreshes it), `frameport
+update [--check] [--yes]`. CI runs `scripts/update_smoke.py` on every OS with the archive it just built.
+
 ## Dynamic data (fetched live, cached, bundled fallback)
-overport release + patch list + patch titles (GitHub), Temurin JRE (Adoptium API), apksigner (Google repository index),
+overport CLI release (Android-XR-Bridge/OVRPort, fallback ovrport/app) + patch list + titles, Temurin JRE (Adoptium API), apksigner (Google repository index),
 store artwork/titles (overport image API), catalog (optional remote), Lepton location/appid (Frame appmanifests),
 Steam user (Frame userdata).
@@ -0,0 +1,63 @@
+# Diagnostics bundles and shared recipes
+
+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
+  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.
+  - The PR step needs Settings → Actions → "Allow GitHub Actions to create and approve pull requests".
+  - Create the labels `working-config`, `catalog-accepted` and `bug` once.
+- **Report a problem / Collect logs** (game menu, Settings, the failure pop-up, `frameport diag report|collect`): writes
+  a redacted zip and opens a prefilled `bug-report.yml` issue.
+  - GitHub has no API for issue attachments, so the user drags the zip in (25 MB max; the bundle stays under 24 MB).
+  - Prefilled links are capped at about 7.5k characters. Free text is trimmed first; the recipe is never cut.
+
+Code: `src/frameport/diag/` (`redact.py`, `bundle.py`, `issue.py`), agent command `collect_diag` (agent ≥ 21),
+`Target.collect_diag`, `core/applog.py` (app log + saved job logs).
+
+## Bundle layout (schema 1)
+```
+README.md                    what's where (for whoever opens it)
+manifest.json                versions (app, agent, tools, SteamOS build, Proton), games, warnings, redaction counts
+app/app.log                  the app's log (<data>/logs/app.log, rotated 2 MB × 3)
+app/jobs/*.log               saved GUI job logs (<data>/logs/jobs, last 30): build, install, test, ...
+app/settings.json            library settings, catalog sources
+frame/info.json              agent `info` (SteamOS build, Lepton, Proton, installed games, kernel keys)
+frame/host.json              OpenXR runtime + explicit layers, podman containers, containers.conf, uptime
+frame/XRService-*.log        the Frame's OpenXR runtime (SteamVR XRService) log, newest
+games/<pkg>/entry.json       library entry: analysis, recipe, build checks, installs, last_test (store text dropped)
+games/<pkg>/recipe.yaml      the recipe in catalog form;  catalog-<origin>.yaml = the catalog entry it came from
+games/<pkg>/triage.json      newest local launch log re-triaged with the bundling app's signatures
+games/<pkg>/logs/*.log       launch-test logs kept on the PC (last 5)
+games/<pkg>/package/         stand-in for the game files (no content):
+    apk_files.json           every APK entry + size
+    AndroidManifest.xml      decoded manifest
+    elf.json                 per lib/*.so: DT_NEEDED, ovr*/xr*/vrapi_/gl*/JNI exports + imports
+    files.json, pe.json      Rift: file list; PE imports / delay imports of the exe and VR DLLs
+games/<pkg>/target/          from the Frame (or the PC): launch.sh, settings.conf, deployment.json, launch.log,
+                             launch-test.log (PC VR), lepton-steamlaunch-<appid>.log, logcat-{main,crash,system,...}.log,
+                             ReviveInjector.txt / steam-<appid>.log / game-log-N.txt (PC VR), files.json (+ missing)
+```
+Each log keeps at most its last 4 MB (2 MB per file from the Frame).
+
+## Redaction
+`diag/redact.py` runs on every file and on the issue text.
+- **Exact values:** the data dir → `<data>`, home dirs → `<home>`, user names → `<user>`, PC and Frame host names and
+  saved Frame addresses → `<host>`, Steam account ids from the Frame's `info` and the PC's Steam → `<steam-id>`, the
+  folders holding the user's game dumps → `<source>`.
+- **Patterns:** IPv4 addresses (first octet ≥ 10, so version numbers survive), IPv6, MAC, SteamID64, `userdata/<id>`,
+  e-mail addresses (file names like `x@123.txt` excluded), and any `/home/<u>`, `/Users/<u>`, `C:\Users\<u>` or
+  `/mnt/c/Users/<u>`.
+- **Kept:** generic accounts that identify no one: `steamos`, `steamuser` (Proton), `root`, `deck`.
+
+## Debugging from a bundle (no game, no Frame, no GUI)
+1. `frameport diag inspect <zip>` (`--json` for everything). It prints the versions and warnings, the last launch
+   test, and a fresh triage of the newest launch log with the current `catalog/triage.yaml`.
+2. Match the findings and log lines against `docs/PLAYBOOK.md` (symptom → fix) and `docs/FRAME_RUNTIME.md`.
+3. Check the analysis in `entry.json` (engine, XR API, `extra`: missing ovr symbols, features, Unreal version) and
+   `package/elf.json` against the heuristics in CLAUDE.md. Compare `recipe.yaml` with catalog games that use the same
+   engine and API.
+4. Compare `manifest.json → env.frame.build_id` with the build the docs describe: SteamOS updates change the runtime.
+5. A new failure signature means adding a patch module, a `triage.yaml` signature, a PLAYBOOK row and a unit test (see
+   Conventions). Then `diag inspect` on the same zip should report it.
@@ -22,8 +22,16 @@
  FB_swapchain_update_state, FB_space_warp, EXT_frame_synthesis, … (full list in any launch.log, tag overportOXR).
 - Missing (emulated by the adapter): XR_FB_passthrough, XR_FB_scene / spatial_entity(_query/_storage/_container) /
  scene_capture, XR_FB_composition_layer_image_layout (flip), XR_KHR_convert_timespec_time (returns
-  FUNCTION_UNSUPPORTED). Missing (dropped): XR_KHR_composition_layer_equirect2, XR_KHR_composition_layer_cylinder
+  FUNCTION_UNSUPPORTED). XR_FB_render_model is presumably missing too (not checked on the device yet); the adapter
+  emulates it only with `controller_models=1` and uses a native one if the runtime ever has it. Missing (dropped): XR_KHR_composition_layer_equirect2, XR_KHR_composition_layer_cylinder
  (the VrApi bridge converts cylinders to quads).
+- Layer types (checked 2026-09-30 in `/opt/steamvr/bin/androidarm64/vrclient.so`, the Android-side runtime Lepton
+  mounts at `/data/steamvr/runtime`): its compositors (`CSxrCompositorPrism`, `CSxrCompositorOpenVR`) only have
+  `ComposeLayerQuad` and `ComposeLayerProjection`; cube/cylinder/equirect/equirect2 exist only as enum names, so
+  there is nothing to switch on. It has a layer limit ("Exceeded the layer limit"; the value is logged by
+  `layer_debug` from `maxLayerCount`). The adapter emulates cylinders (strips) and, per game, equirect layers
+  (`equirect_emul`, an adapter projection layer). Quad layers are drawn above every projection layer regardless of
+  submission order (seen 2026-10-01: quads placed before 4XVR's projection layer covered it).
 - Swapchain formats: GLES `GL_SRGB8_ALPHA8` (35907) / `GL_SRGB8` (35905) only, samples = 1. Vulkan: 43 (R8G8B8A8_SRGB)
  and 50, not 37/44 (UNORM).
 - Environment blend: ALPHA_BLEND available (greyscale passthrough cameras).
@@ -36,6 +44,47 @@
  VK_INSTANCE_LAYERS (set `VK_INSTANCE_LAYERS=""` through `device.lepton_env` to test without them).
 - 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)
+- Steam on the Frame registers ARM64 compat tools from the app **"Steam Frame ARM64 Compat List"** (appinfo
+  `extended.compat_tools`, found dynamically by the agent): `proton_11-arm64` (4628740, needs
+  `steamlinuxruntime_steamrt4-arm64` 4185400), `proton-experimental-arm64` (4427310), `fex` (3127680, FEX-Emu for
+  Linux x86 binaries; `/usr/bin/FEXBash` shows the chain steam-launch-wrapper → reaper → fex-compat-tool →
+  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.
+- 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`).
+- Host OpenXR runtime for Linux processes: `~/.config/openxr/1/active_runtime.json` → `/opt/steamvr/steamxr_linuxarm64.json`
+  ("SteamVR", `bin/linuxarm64/vrclient.so`); implicit API layer `XrApiLayer_VALVE_fdm_injection`.
+- The "Steam" VR games in the Frame's library (Pistol Whip, Job Simulator, SUPERHOT VR) are APKs run by Lepton, not
+  Proton.
+- Verified on the device (agent `proton_selftest`, `xr_layer_test`): FramePort installs Proton 11 (ARM64) + SLR4 by
+  itself (~90 s); Proton runs x86 `cmd.exe` in ~3 s; with `SteamGameId` set it registers wineopenxr
+  (`HKLM\Software\Khronos\OpenXR\1` → `C:\openxr\wineopenxr64.json`). Headless launches need the display session (`DISPLAY=:0`,
+  `GAMESCOPE_WAYLAND_DISPLAY=gamescope-0`), else Wine can't create windows and the process hangs.
+- The Linux SteamVR runtime (Proton's loader `files/lib/aarch64-linux-gnu/libopenxr_loader.so.1`) **does** support
+  `XR_KHR_convert_timespec_time` (unlike the Android runtime Quest games see), so wineopenxr's
+  `XR_KHR_win32_convert_performance_counter_time` works.
+- **The Linux SteamVR runtime only accepts OpenXR 1.0 apps**: `xrCreateInstance` with `apiVersion` 1.1 returns
+  `XR_ERROR_API_VERSION_UNSUPPORTED` (-4), with any extensions; 1.0 works (checked 2026-09-29, SteamOS 0.4.2). Proton
+  11's VR helper (`proton_vrhelper`) requests 1.1, so without help VR never starts for Proton games: the log shows
+  `LoaderInstance::CreateInstance chained CreateInstance call failed`, games run as a flat window (Rick and Morty) and
+  Revive's OVRPlugin reports `ovr_Initialize failed: Unable to load LibOVRRT DLL` (Lies Beneath, then a crash).
+  FramePort's OpenXR layer (`native/xrlayer`, patch `pcvr.xr_timefix`, default on for PC VR games) retries such a
+  create as 1.0; enabled by `XR_ENABLE_API_LAYERS` from launch.sh. Proton's Steam Linux Runtime container drops
+  `XR_API_LAYER_PATH` (it keeps `XR_ENABLE_API_LAYERS`), so the agent registers the layer as an explicit layer in
+  `~/.local/share/openxr/1/api_layers/explicit.d/` (home is shared into the container) with an absolute library path.
+- Oculus Store builds that delay-load `LibOVRPlatform64_1.dll` (Platform SDK, e.g. Lies Beneath) crash with
+  `0xc06d007e` (delay-load module not found): that DLL comes with the Oculus app, which the Frame doesn't have. (No Oculus runtime DLLs or
+  registry keys are needed: Revive's LibOVRRT hook works once OpenXR does.)
+- Unreal's Oculus plugin (and LibOVR's `ovr_Detect`) first checks for the Windows event `OculusHMDConnected` (created
+  by the Oculus service on a PC) and silently skips VR without it. Revive hooks `OpenEventW` for that — Lies Beneath
+  got as far as OVRPlugin, so the hook evidently works there — but it depends on Detours patching Wine's kernelbase,
+  which is ARM64EC code under Proton arm64. Patch `pcvr.oculus_unreal` (default for Unreal Rift games) makes it
+  independent of that: launch.sh starts the injector through `helpers/fp_oculushmd.exe` (`native/oculushmd`), which
+  creates the real event and keeps it until the game (tracked by a job object) has exited.
+
 ## Steam integration
 - Non-Steam shortcut: binary `userdata/<id>/config/shortcuts.vdf`; appid = crc32(exe+title) | 0x80000000;
  artwork in `config/grid/<appid>p.*` (portrait), `<appid>.*` (landscape), `<appid>_hero.*`, `<appid>_logo.*`.
@@ -1,37 +1,89 @@
 # Installing FramePort

-Download the archive for your OS from the [latest release](https://github.com/spoopyghosty0/frameport/releases/latest)
-and extract it anywhere. No installer and no admin rights are needed. On first start, open **Tools → Install
-missing** once: FramePort downloads its own Java runtime, the overport CLI and apksigner into its data folder.
+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).

-| OS | Archive | Start |
+| Computer | Archive | Start |
 |---|---|---|
 | Windows 10/11 (x64) | `FramePort-windows-x64.zip` | `FramePort.exe` |
 | macOS (Apple Silicon) | `FramePort-macos-arm64.zip` | `FramePort.app` |
-| Linux (x64) | `FramePort-linux-x64.tar.gz` | `FramePort/FramePort` (needs GTK 3) |
+| Linux (x64, GTK 3) | `FramePort-linux-x64.tar.gz` | `FramePort/FramePort` |
+| Command line only (Python 3.11+) | `frameport-<version>-py3-none-any.whl` | `frameport --help` |
+
+The command-line version installs from the wheel's release link with `uv tool install <link>` (or pipx / pip).

 ## First launch

-FramePort is free and signed with its own **self-signed** certificate (Windows) and **ad-hoc** signature (macOS),
-not a paid one, so your OS warns the first time:
+The builds are signed with a free self-signed certificate (Windows) and an ad-hoc signature (macOS), so the first
+start shows a warning:

- **Windows:** SmartScreen shows "Windows protected your PC" → click **More info** → **Run anyway**.
-  Optional, to make Windows show "FramePort" as a verified publisher: import `FramePort-selfsigned.cer` (attached
-  to each release) into **Trusted Root Certification Authorities** (right-click → Install Certificate → Current User →
-  "Place all certificates in the following store"). The certificate is limited to code signing and cannot issue other
-  certificates. SmartScreen is reputation-based, so it may still warn for new versions. Only do this if you trust the
-  builds from this repository; remove it any time with `certmgr.msc`.
- **macOS:** right-click `FramePort.app` → **Open** → **Open** (only needed once), or run
-  `xattr -dr com.apple.quarantine FramePort.app`.
+- **Windows:** "Windows protected your PC" → **More info** → **Run anyway**. Optional: import
+  `FramePort-selfsigned.cer` (attached to each release) into *Trusted Root Certification Authorities* (Current User) to
+  show FramePort as the publisher; the certificate can only sign code. Remove it with `certmgr.msc`.
+- **macOS:** right-click `FramePort.app` → **Open** → **Open** (once), or `xattr -dr com.apple.quarantine FramePort.app`.
 - **Linux:** `tar xzf FramePort-linux-x64.tar.gz && ./FramePort/FramePort`.

+## Connecting the Steam Frame
+
+1. On the Frame: Settings → System → Developer → turn on **Developer Mode**. The Frame and the computer must be on the
+   same network.
+2. In FramePort open **Steam Frame**. A Frame in Developer Mode appears in the list.
+3. First time only: on the Frame switch to Desktop mode (Steam button → Power → Switch to Desktop), open Konsole and
+   run the command FramePort shows. It enables SSH, authorises this computer and installs Valve's Android runtime
+   (Lepton) if needed.
+
+## Updating
+
+FramePort checks for a new release at start and every 6 hours (it only downloads the release information). When one
+exists, the Library shows **Update now**: FramePort downloads the new version, verifies it against the release's
+`SHA256SUMS.txt` (on Windows also the signature), restarts and opens as the new version. Games, settings, signing keys
+and the Frame connection are kept. Running installs finish first. **Later** skips that version.
+
+Settings → **Updates**: turn the check off, or turn on **Install updates automatically** (downloads in the background,
+installs at the next start). If FramePort's folder isn't writable, **Update now** opens the release page instead. The
+update log is `logs/update.log` in the data folder.
+
+Command line: `frameport update` (`--check` only checks, exit code 10 = update available; `--yes` doesn't ask).
+`FRAMEPORT_NO_UPDATE_CHECK=1` turns all checks off.
+
+## Oculus Rift (PC VR) games
+
+Scan a folder of Rift games (one folder per game) or use **Add games → Add one game folder…**. FramePort finds the
+game's program and asks when there is more than one candidate. **Already patched** on a game page installs a copy
+unchanged. FramePort uses an installed Revive, or downloads a portable copy.
+
+- **Play from this PC:** Windows with Steam and SteamVR. **Install on this PC** adds the game to Steam; stream it to the
+  Frame with Steam Link. If a game can't keep up with the refresh rate, FramePort lowers the rate and enables motion
+  smoothing in SteamVR's per-game settings the next time you press Play.
+- **Play on the Frame (experimental):** Steam Frame → *PC VR games (Proton)* → **Install**, then **Install on Frame**
+  on the game page.
+- Games that use the Oculus Platform SDK check the licence through the Oculus app, so they run on the PC only.
+
+## Videos, documents and mods
+
+Steam Frame → **Send files** (or a game's menu → **Add videos & files…**) copies files to the Frame. **Videos**,
+**Downloads** and **Documents** appear inside every Quest game as `/sdcard/Movies`, `/sdcard/Download` and
+`/sdcard/Documents`. Apps find them by browsing folders; Android's media index doesn't work on the Frame. Command
+line: `frameport frame send <files> --to videos`.
+
+## Sharing a working game, reporting a problem
+
+- **Share working config…** (game menu): opens a prefilled GitHub issue with the game's patches and settings. Accepted
+  configs become built-in recipes.
+- **Report a problem…** (game menu, or Settings → Problems & feedback): saves a diagnostics zip to Documents (logs,
+  recipe, device details; IP addresses, user names, home folders and Steam ids replaced) and opens a prefilled GitHub
+  issue to attach it to. Command line: `frameport diag report <game>`, `frameport share-recipe <game>`.
+
+## Uninstalling
+
+Settings → **Uninstall FramePort…** (or `frameport uninstall-app`) removes its data folder, the Steam shortcuts it
+added on this computer and, optionally, its games on the Frame (saves can be kept). It first saves your signing keys
+to Documents: game updates must be signed with the same key. Then delete the program folder.
+
 ## Verify a download

-Every archive has a GitHub build attestation proving it was built by this repository's CI from a tagged commit:
-
-```
-gh attestation verify FramePort-windows-x64.zip -R spoopyghosty0/frameport
-```
-
-and `SHA256SUMS.txt` lists the checksums (`sha256sum -c SHA256SUMS.txt`). The Windows certificate's SHA-256
-fingerprint is `4E:12:98:91:62:C0:E4:50:FB:65:1D:34:BB:73:00:09:7B:78:BE:88:5C:A7:6C:42:23:46:9B:92:A1:59:A7:6E`.
+Each archive has a GitHub build attestation:
+`gh attestation verify FramePort-windows-x64.zip -R spoopyghosty0/frameport`. `SHA256SUMS.txt` lists the checksums
+(`sha256sum -c SHA256SUMS.txt`). Windows certificate SHA-256 fingerprint:
+`4E:12:98:91:62:C0:E4:50:FB:65:1D:34:BB:73:00:09:7B:78:BE:88:5C:A7:6C:42:23:46:9B:92:A1:59:A7:6E`.
@@ -1,6 +1,6 @@
 # Porting playbook: symptom → cause → fix

-Everything here was hit for real while porting 34 Quest games to the Steam Frame (Sept 2026). The machine-readable
+Everything here was hit while porting Quest and Rift games to the Steam Frame (Sept–Oct 2026; 38 catalog recipes). The machine-readable
 version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); keep both in sync.

 ## Fast path for a new game
@@ -15,6 +15,17 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 |---|---|---|
 | Every game suddenly fails to start: `crun: create keyring …: Disk quota exceeded`, `is not a running context` | rootless podman leaked a kernel keyring per launch; 200-key quota exhausted | `keyring = false` in `~/.config/containers/containers.conf` (FramePort agent does it), then reboot the Frame once |
 | `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 |
+| PC VR game runs as a flat 2D window (no VR) | SteamVR was not running, so Revive/LibOVR had no runtime to bind to | FramePort now auto-starts SteamVR on Play; make sure your headset/SteamVR come up before the game |
+| PC VR game crashed launching via Steam on the OpenXR backend | Revive's newer OpenXR backend was less reliable | PC now defaults to Revive's OpenVR (SteamVR) backend; reinstall to apply |
+| Oculus PC VR game: `Unable to load LibOVRRT DLL` / `-3001` on the Frame | The game can't find a VR runtime (Revive's LoadLibrary hook doesn't work under Proton-arm64) | `pcvr.libovr_redirect` (default on) symlinks Revive's runtime as `LibOVRRT{64,32}_1.dll` in the exe dir — pure substitution; a build that checks the runtime signature then hits `-3021` (not bypassed) |
+| Oculus Rift game won't run on the Steam Frame | Oculus/LibOVR game: needs Revive, whose hooks don't work under Proton-arm64, and FramePort won't defeat the Oculus runtime signature check | Play it on this PC (SteamVR + Revive). Only OpenVR/OpenXR-native Rift games run on the Frame |
+| Un-cracked Oculus PC VR game: "Initializing OVR session" then exits / signature check on the runtime | Revive's hooks don't install on Proton-arm64; the Oculus shim rejects the unsigned Revive runtime | Not runnable on the Frame without the repack's crack extracted (not done by FramePort); use the PC version |
+| PC VR game: `Failed to initialize Oculus API (-3001)` / `Unable to load LibOVRRT DLL` | Revive's LoadLibrary hook doesn't work under Proton arm64 (ARM64EC kernelbase); the game's LibOVR shim finds no runtime DLL | Symlink `LibOVRRT64_1.dll` → Revive's DLL in the prefix's system32 (manual so far) → then -3021 (runtime signature check; open) |
+| 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 |
 | `INSTALL_FAILED_NO_MATCHING_ABIS` | 32-bit-only APK; Frame has no AArch32 | None. PC/Rift version via Revive |
 | `UnsatisfiedLinkError` / `cannot locate symbol "ovr_…"` | overport's platform loader lacks Meta platform functions | `frame.ovrstubs` (automatic, generated stubs) |
 | missing `ovrMessageType_ToString` | same, but the game needs a real string | `frame.ovrplatformcompat` (automatic) |
@@ -24,6 +35,19 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | `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 |
+| Crash on the first frame, backtrace `libVkLayer_fossilize.so` ← `FVulkanRenderPass::FVulkanRenderPass` (crash logcat) | the engine leaves the pNext of unused Vulkan attachment references uninitialized; Lepton always loads Steam's Fossilize layer (guest is userdebug, so even a non-debuggable APK gets it), which follows the pointer | `frame.vk_sanitize` (default on for Unreal; Vulkan shim `libfp_vk.so`; triage `fossilize-renderpass`), e.g. Deadpool VR |
+| SIGABRT right after start, backtrace `libopenxr_loader.so (xrCreateSwapchain+…)` | overport's dispatcher aborts on swapchains > 4096 px ("Wrong createInfo size"); video players use 7680×3840 theatre textures | `frame.swapchain_limit` (default on; guard → 16384 px; triage `swapchain-size-abort`), e.g. 4XVR |
+| Video/menu panel missing, log `dropped N unusable layer(s)` with cylinder (1000017000) or equirect2 (1000091000) layers | the Frame runtime lacks XR_KHR_composition_layer_cylinder/equirect(2)/cube (its SteamVR runtime only composites quad + projection layers) | adapter shows cylinders as flat strips (setting `cylinder_strips`, default on); 360° equirect layers (theatres, 360° videos): `adapter.equirect_emul` (GLES only, per game) |
+| 360° theatre / 360° video black or missing (e.g. 4XVR) | equirect layers dropped | `adapter.equirect_emul=1`: a worker thread with a shared GLES context converts each 360° image to a cube map when it changes and draws one adapter projection layer from it for every frame with exactly that frame's views; it replaces the 360° layers in place, so the game's own projection layer (balcony, controllers, 360° videos it draws itself) stays on top. Quads can't be used: the Frame draws quad layers above every projection layer whatever the order. Log: `first 360 view ready`, `in 5 s: N 360 image update(s) … M view redraw(s)`. Upside down / mirrored / behind you: `equirect_flip` 1/2/4 (`frameport settings <pkg> equirect_flip=1`, no rebuild). Never Vulkan (a Vulkan renderer hung the Frame's GPU in AC Nexus) |
+| Unity game hangs right after its first frames, no `pacing:` lines; SIGQUIT dump shows UnityMain in a game library's `JNI_OnLoad` → `usleep` (e.g. SKYBOX: `libskybox.so`, `SignatureChecker`) | the game checks its APK signing certificate; every port is re-signed | can't be fixed without defeating anti-tamper (FramePort doesn't): mark "Can't run". Diagnose hangs: `podman exec <container> kill -3 <pid>` writes all thread stacks to launch.log |
+| Video player doesn't list sent videos (e.g. 4XVR "Internal Storage" only shows some) | the player lists its own /sdcard folder (4XVR: /sdcard/4XPlayer), not /sdcard/Movies; Android's media index doesn't work in Lepton | GUI game page "Add videos" / "Add videos & files…" (Videos + the app's own folder, hard links) or `frameport frame send <files> --app <pkg>` |
+| One eye grey in a stereo video, log `xrCreateSwapchain … result=-10` | the runtime refused a swapchain (XR_ERROR_LIMIT_REACHED) | fewer/smaller swapchains: lower `equirect_res`; unresolved |
+| Menu/screen jumps to where you look (e.g. 4XVR) | the app re-creates LOCAL spaces (4XVR: every 2–4 s) and the Frame places them at the current head yaw, or the app recentres after the Frame's brief focus dips | turn on `adapter.layer_debug`, check `that LOCAL space sits at … deg` vs `focus_hold: hid a … ms focus dip`; fixes: `adapter.stable_local` (new LOCAL spaces line up with the first) / `adapter.focus_hold` (hides dips < 600 ms after 3 s focused; never at start-up: a global debounce broke AC Nexus) |
+| Pointer misses menu items | the Frame's aim pose differs from Touch's | `adapter.layer_debug` logs `aim in grip … pitch/yaw`; correct with `aim_pitch`/`aim_yaw`/`aim_forward` (`frameport settings`, no rebuild) |
+| Video stutters although fps is steady | video frame rate doesn't divide the refresh rate (30 fps at 72 Hz) | `adapter.refresh_rate` (e.g. 90 for 30 fps, 72 for 24 fps); `layer_debug` logs the offered rates and the app's own requests |
+| PC VR game judders/stutters although the GPU keeps up; vrcompositor.txt "Timed out. N total" high or frames dropped | the game misses the headset's refresh (e.g. 96 Hz = 10.4 ms; Stormland's slow frames take 10.7 ms) | `pcvr.steamvr_tuning` (default on): next Play sets SteamVR per-app `preferredRefreshRate` + `motionSmoothingOverride` via `fp_vrsettings.exe` |
+| Quest app keeps recentering / snapping the view when you turn your head; log shows session state 5→4→3→4→5 within a second | the Frame briefly takes focus; the app recenters on focus changes | unfixed: hiding the dips (debounce) made AC Nexus stay black, so it was removed |
+| Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | send files with Frame → Send files (~/Videos = /sdcard/Movies) and browse folders in the app |
 | Game (Unity, GLES) freezes, `zink: DEVICE LOST` | multisampled render-to-texture hangs the GPU | `frame.unity_no_msaa`; if it persists: unfixable → PC version |
 | Setup/intro loops every launch (Espire 2) | save folders created without write permission | launcher repairs permissions every 2 s (built in) |
 | VrApi bridge: never enters VR | Frame reaches FOCUSED later than Quest; tracking only when worn | bridge waits 30 s; test in the headset |
@@ -37,11 +61,15 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Upside-down image in a GL bridge game | GL images start at the bottom row | fixed in the bridge (swap angleUp/Down for GL chains) |
 | UI panels upside down (AC Nexus) | XrCompositionLayerImageLayoutFB VERTICAL_FLIP unsupported | adapter `flip_emul=1` (default); rotating quads makes them vanish |
 | Passthrough black (BAM) | XR_FB_passthrough missing | adapter `passthrough_emul=1` (default) + `patch_force_passthrough` for MR-only games |
+| Quest Touch controllers (or none) shown in a game that uses Meta's runtime controller models | XR_FB_render_model missing on the Frame | adapter `controller_models=1`: the agent converts the Frame's SteamVR controller models to glb at install, the adapter serves them. Games with their own controller meshes aren't affected (none of the 34 catalog games use runtime models) |
+| `overportOXR: Unknown proc addr: xr…` for a function the adapter emulates | overport's dispatcher only forwards functions in its own table | route the plugin's lookups through `native/xrshim` (done for XR_FB_render_model when `controller_models=1`) |
 | MR game stuck waiting for room data (Demeter) | no Meta scene API | adapter `scene_emul=1` (+ `frame.meta_permissions`) |
 | Hand-tracking game janky (Silhouette) | Frame synthesizes hands from controllers | `controller_fix=0` passes hands through; not really fixable |
 | Eye distortion while moving (Arcsmith, Time Stall) | unknown (not eye swap, tracking, Valve layers, depth or pacing) | unresolved |

 ## 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>`.
 - 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`
@@ -51,5 +79,25 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke

 ## When it can't run on the Frame
 Stream PC VR instead: native Steam version if one exists (Espire 1: 669290; HITMAN WoA: 1659040; Sniper Elite VR),
-or the Rift version through Revive + SteamVR (Journey of the Gods, Shadow Point). The catalog stores these as
-`pcvr_alternative`; a Revive target is planned (`targets/revive.py`).
+or the Rift version through Revive (Journey of the Gods, Shadow Point). The catalog stores these as
+`pcvr_alternative`. FramePort handles Rift games itself (next section).
+
+## Oculus Rift (PC VR) games
+Scan a folder with Rift game dumps (Windows game folders) like Quest dumps; they get ids `rift.<slug>` and the
+"PC VR (Revive / Proton)" patch group. Two ways to run them:
+- **This PC** (`--to pc`, GUI "Install on this PC"): a non-Steam shortcut in the local Windows Steam runs
+  `ReviveInjector.exe /openxr "<game.exe>"` (FramePort's portable Revive; on WSL copied to
+  `%LOCALAPPDATA%\FramePort`). Play on the Frame by streaming from SteamVR.
+- **The Frame** (GUI "Install on Frame (Proton)"): game + Revive are uploaded to `~/Applications/quest-frame/rift.*`,
+  and launch.sh runs them with the Frame's ARM64 Proton (Frame → Install Proton first). Experimental.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| "Proton isn't installed on the Frame yet" | ARM64 Proton / Steam Linux Runtime 4 (arm64) not downloaded | Frame → Install Proton (confirm in the headset) or "Install without confirming" (`frameport frame proton --install --unattended`) |
+| Game quits at once; `ovrPlatformInitialize_NotEntitled` / entitlement failed | Oculus Platform SDK entitlement check (FramePort flags these: "Uses the Oculus Platform SDK") | PC mode with the Oculus app installed and a license you own. FramePort doesn't bypass entitlement checks |
+| `Failed to create process` in ReviveInjector.txt | wrong exe, or 32/64-bit mismatch | check the detected exe on the game page; rescan |
+| `XR_ERROR_RUNTIME_UNAVAILABLE` / no OpenXR runtime (PC) | SteamVR not running / not the OpenXR runtime | start SteamVR, set it as OpenXR runtime; or `pcvr.revive_openvr` |
+| `XR_ERROR_EXTENSION_NOT_PRESENT` / `xrConvertTimespecTimeToTimeKHR failed` (Frame) | ReviveXR needs `XR_KHR_win32_convert_performance_counter_time`; wineopenxr builds it on the host's timespec conversion. The Frame's Linux runtime supports it (2026-09-29), unlike its Android runtime | `pcvr.xr_timefix` (off by default): FramePort's timefix OpenXR layer emulates it like the Quest adapter |
+| Proton game hangs at start in a headless/SSH launch; log `no driver could be loaded` / `explorer process failed to start` | no display session (DISPLAY/GAMESCOPE_WAYLAND_DISPLAY) | the Proton launch.sh takes them from the running Steam (built in) |
+| Unreal game starts (window created) then `CrashReportClient` runs | the game crashed under Proton; often no VR runtime reached it (Revive off) | keep `pcvr.revive` on (repacks' bundled LibRevive64.dll isn't loaded by itself); read the game log + crash summary in the launch log |
+| `VK_ERROR_DEVICE_LOST` under DXVK | freedreno GPU hang | `pcvr.proton_log` to capture; PC mode |
@@ -7,10 +7,13 @@ 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. Settings: `libframe_settings.so` in the APK + `settings.conf`/`framebridge.conf` on the Frame. Hook technique from Quest2Frame's `frame_bridge.c` (GPL-3.0). |
-| `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`), 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`); `layer_emul_gl.c` = `equirect_emul` (GLES sessions only): 360° equirect/equirect2 layers become one adapter projection layer, drawn by a worker thread with its own EGL context shared with the app's: each 360° image is converted to a cube map only when it changes, and the view is redrawn only after a 4° head turn (GL/EGL resolved with dlopen, so Vulkan games never load them); `layer_math.h` = their pose/face math, tested on the host by `tests/test_layer_emul.py`. `render_model.c` = XR_FB_render_model emulation (setting `controller_models`, off by default): serves `files/framebridge/controller_{left,right}.glb`, which the agent converts on the Frame from SteamVR's own Frame controller render models (never shipped by FramePort); tested on the host by `tests/test_render_model.py`. Settings: `libframe_settings.so` in the APK + `settings.conf`/`framebridge.conf` on the Frame. |
+| `vrapi-bridge/` | `arm64-v8a/libvrapi.so` | VrApi → OpenXR bridge from [Android-XR-Bridge/OVRPort](https://github.com/Android-XR-Bridge/OVRPort) `native/vrapi` at 5e7df52 (GPL-3.0, `LICENSE.upstream`; unchanged upstream as of OVRPort v1.2.5, which ships the unpatched code as its opt-in `patch_vrapi_openxr` in experimental CLI builds), with our changes in `upstream-patches/`: GLES sessions + GL texture swapchains, cylinder→quad layers, GL vertical flip, UNORM↔sRGB format twins, 30 s VR-mode deadline, VALID-only recenter, loading-icon layers skipped, diagnostics behind `-DOVP_GL_DIAG`. |
 | `platformcompat/` | `arm64-v8a/libovrplatformcompat.so` | Real `ovrMessageType_ToString` (same fork, `native/platform`). |
 | `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. |
 | `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
@@ -3,8 +3,6 @@
 //
 // Installed as lib/arm64-v8a/libopenxr_loader_generic.so; overport's real generic
 // loader is renamed to libopenxr_loader_original.so and loaded from the same dir.
-// Hook technique follows Quest2Frame's frame_bridge.c (GPL-3.0-only,
-// github.com/MichaelScottsman/Quest2Frame).
 //
 // Fixes applied:
 //  * adds XR_KHR_android_create_instance when the app chains
@@ -23,7 +21,13 @@
 //    (passthrough_emul);
 //  * optionally tells the app its reference spaces changed once the session is focused, so apps that
 //    created them before tracking started recreate them (respace_kick);
-//  * optionally flips quad layers vertically for apps whose UI panels show upside down (flip_quads).
+//  * optionally flips quad layers vertically for apps whose UI panels show upside down (flip_quads);
+//  * optionally serves Steam Frame controller models through XR_FB_render_model (controller_models,
+//    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 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).
 //
 // Settings (key=value lines), later sources override earlier ones:
 //   <libdir>/libframe_settings.so
@@ -34,6 +38,7 @@
 #include <openxr/openxr.h>
 #include <android/log.h>
 #include <dlfcn.h>
+#include <math.h>
 #include <pthread.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -59,6 +64,7 @@ static int respace_kick = 0;
 static int strip_depth = 0;
 static int flip_quads = 0;
 static int flip_emul_setting = 1;
+static int cylinder_strips_on = 1;  // show cylinder layers as flat quad strips (cylinder_strips)
 static int scene_emul;  // scene emulation setting (per game)
 static float scene_height = 2.5f;  // scene emulation ceiling height (m)
 static float scene_width, scene_depth;  // optional room size override (m)
@@ -68,6 +74,21 @@ static int runtime_has_image_layout;  // runtime supports XR_FB_composition_laye
 // Layer types whose extension the runtime lacks (dropped at xrCreateInstance) are removed from frames.
 static int no_equirect, no_equirect2, no_cylinder, no_cube;
 static int runtime_has_fb_passthrough, emulate_passthrough, alpha_blend_failed;
+static int controller_models;  // serve Frame controller models via XR_FB_render_model (render_model.c)
+// Per-game settings, all off by default (session_fixes.c, layer_emul_gl.c).
+static int layer_debug;      // diagnostics: layers, swapchains, session states, spaces, aim/grip, refresh rates
+static int stable_local;     // keep every LOCAL space the app creates on the session-start origin
+static int focus_hold;       // hide brief focus dips once the session has been focused for a while
+static float 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)
+static int equirect_face = 1536;  // max cube map face size (px)
+static int equirect_res = 1536;   // projection image size per eye (px)
+static int equirect_flip;    // source orientation fix: 1 upside down, 2 mirrored, 4 turned 180 degrees
+static float equirect_fps = 60;   // max redraws per second per 360 layer (0 = no limit)
+static int equirect_stereo;  // 0 auto (mono if the layer limit can't hold both eyes), 1 stereo, 2 mono
+static XrTime last_predicted_time;
+static void render_model_init(const char *package);

 static void read_settings(const char *path) {
    FILE *f = fopen(path, "r");
@@ -87,10 +108,25 @@ static void read_settings(const char *path) {
        if (sscanf(line, "strip_depth=%f", &value) == 1) strip_depth = value != 0;
        if (sscanf(line, "flip_quads=%f", &value) == 1) flip_quads = value != 0;
        if (sscanf(line, "flip_emul=%f", &value) == 1) flip_emul_setting = value != 0;
+        if (sscanf(line, "cylinder_strips=%f", &value) == 1) cylinder_strips_on = value != 0;
        if (sscanf(line, "scene_emul=%f", &value) == 1) scene_emul = value != 0;
        if (sscanf(line, "scene_height=%f", &value) == 1 && value > 1.5f && value < 5.0f) scene_height = value;
        if (sscanf(line, "scene_width=%f", &value) == 1 && value > 0.5f && value < 20.0f) scene_width = value;
        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, "stable_local=%f", &value) == 1) stable_local = value != 0;
+        if (sscanf(line, "focus_hold=%f", &value) == 1) focus_hold = value != 0;
+        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;
+        if (sscanf(line, "refresh_rate=%f", &value) == 1 && (value == 0 || (value >= 60 && value <= 144))) refresh_rate = value;
+        if (sscanf(line, "equirect_emul=%f", &value) == 1) equirect_emul = value != 0;
+        if (sscanf(line, "equirect_face=%f", &value) == 1 && value >= 256 && value <= 2730) equirect_face = (int)value;
+        if (sscanf(line, "equirect_res=%f", &value) == 1 && value >= 512 && value <= 4096) equirect_res = (int)value;
+        if (sscanf(line, "equirect_flip=%f", &value) == 1 && value >= 0 && value <= 7) equirect_flip = (int)value;
+        if (sscanf(line, "equirect_fps=%f", &value) == 1 && value >= 0 && value <= 144) equirect_fps = value;
+        if (sscanf(line, "equirect_stereo=%f", &value) == 1 && value >= 0 && value <= 2) equirect_stereo = (int)value;
    }
    fclose(f);
    LOG("settings read from %s", path);
@@ -127,10 +163,16 @@ static void initialize(void) {
    }
    const char *env = getenv("FRAMEBRIDGE_CONFIG");
    if (env && *env) read_settings(env);
+    if (controller_models && *process && !strchr(process, '/')) render_model_init(process);

-    LOG("scale=%.2f foveation_fix=%d controller_fix=%d swapchain_fix=%d layer_fix=%d mutable_fix=%d swap_eyes=%d passthrough_emul=%d respace_kick=%d flip_quads=%d loader=%s",
+    LOG("scale=%.2f foveation_fix=%d controller_fix=%d swapchain_fix=%d layer_fix=%d mutable_fix=%d swap_eyes=%d passthrough_emul=%d respace_kick=%d flip_quads=%d controller_models=%d loader=%s",
        scale, foveation_fix, controller_fix, swapchain_fix, layer_fix, mutable_fix, swap_eyes, passthrough_emul,
-        respace_kick, flip_quads, next_gipa ? "OK" : (dlerror() ?: "FAILED"));
+        respace_kick, flip_quads, controller_models, next_gipa ? "OK" : (dlerror() ?: "FAILED"));
+    if (layer_debug || stable_local || focus_hold || aim_pitch || aim_yaw || aim_forward || refresh_rate || equirect_emul)
+        LOG("per-game: layer_debug=%d stable_local=%d focus_hold=%d aim=%.1f/%.1f/%.3f refresh_rate=%.0f equirect_emul=%d "
+            "(face %d, res %d, flip %d, fps %.0f, stereo %d)", layer_debug, stable_local, focus_hold, aim_pitch, aim_yaw,
+            aim_forward, refresh_rate, equirect_emul, equirect_face, equirect_res, equirect_flip, equirect_fps,
+            equirect_stereo);
 }

 static PFN_xrVoidFunction lookup(XrInstance instance, const char *name) {
@@ -142,6 +184,7 @@ static PFN_xrVoidFunction lookup(XrInstance instance, const char *name) {
 }

 #include "scene_emu.c"
+#include "render_model.c"

 XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info, XrInstance *instance) {
    PFN_xrCreateInstance fn = (PFN_xrCreateInstance)lookup(XR_NULL_HANDLE, "xrCreateInstance");
@@ -172,7 +215,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
    }

    XrInstanceCreateInfo fixed = *info;
-    const char **names = calloc(info->enabledExtensionCount + 1, sizeof(*names));
+    const char **names = calloc(info->enabledExtensionCount + 2, 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) {
@@ -184,6 +227,9 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
        else if (scene_emul && is_scene_extension(ext)) {
            if (!emulate_scene) LOG("emulating Meta scene/spatial-entity extensions from the guardian bounds");
            emulate_scene = 1;
+        } else if (controller_models && render_models_available && !strcmp(ext, XR_FB_RENDER_MODEL_EXTENSION_NAME)) {
+            emulate_render_model = 1;
+            LOG("emulating XR_FB_render_model with Steam Frame controller models");
        } else if (passthrough_emul && !strcmp(ext, "XR_FB_passthrough")) {
            emulate_passthrough = 1;
            LOG("emulating XR_FB_passthrough with alpha-blended environment");
@@ -193,6 +239,12 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
        names[kept++] = "XR_KHR_android_create_instance";
        LOG("added %s", "XR_KHR_android_create_instance");
    }
+    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");
+        for (uint32_t j = 0; available && j < available_count; ++j) offered |= !strcmp(available[j].extensionName, "XR_FB_display_refresh_rate");
+        if (!requested && offered) { names[kept++] = "XR_FB_display_refresh_rate"; LOG("added XR_FB_display_refresh_rate (refresh_rate)"); }
+    }
    fixed.enabledExtensionNames = names;
    fixed.enabledExtensionCount = kept;
    for (uint32_t j = 0; available && j < available_count; ++j)
@@ -290,6 +342,13 @@ static void forget_swapchain(XrSwapchain handle) {

 static void flip_on_create_swapchain(XrSwapchain handle, const XrSwapchainCreateInfo *info);
 static void flip_on_destroy(XrSwapchain handle);
+static void emul_on_create_swapchain(XrSwapchain handle, const XrSwapchainCreateInfo *info);
+static void emul_on_destroy_swapchain(XrSwapchain handle);
+static int emul_virtual_create(XrSession session, const XrSwapchainCreateInfo *info, XrSwapchain *out);
+static int emul_is_virtual(XrSwapchain handle);
+static void emul_virtual_destroy(XrSwapchain handle);
+static XrResult emul_virtual_enumerate(XrSwapchain handle, uint32_t capacity, uint32_t *count, XrSwapchainImageBaseHeader *images);
+static void emul_on_acquire(XrSwapchain handle, uint32_t index);

 static int known_swapchain(XrSwapchain handle) {
    int found = 0;
@@ -312,11 +371,21 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
        fixed.next = p;
    }
    if (mutable_fix) fixed.usageFlags |= XR_SWAPCHAIN_USAGE_MUTABLE_FORMAT_BIT;
+    if (equirect_emul && swapchain && emul_virtual_create(session, &fixed, swapchain)) {
+        remember_swapchain(*swapchain);
+        emul_on_create_swapchain(*swapchain, &fixed);
+        return XR_SUCCESS;
+    }
    XrResult result = fn(session, &fixed, swapchain);
-    LOG("xrCreateSwapchain %ux%u format=%lld samples=%u array=%u faces=%u usage=0x%llx result=%d", fixed.width,
-        fixed.height, (long long)fixed.format, fixed.sampleCount, fixed.arraySize, fixed.faceCount,
-        (unsigned long long)fixed.usageFlags, result);
-    if (XR_SUCCEEDED(result)) { remember_swapchain(*swapchain); flip_on_create_swapchain(*swapchain, &fixed); return result; }
+    LOG("xrCreateSwapchain %ux%u format=%lld samples=%u array=%u faces=%u usage=0x%llx flags=0x%llx result=%d",
+        fixed.width, fixed.height, (long long)fixed.format, fixed.sampleCount, fixed.arraySize, fixed.faceCount,
+        (unsigned long long)fixed.usageFlags, (unsigned long long)fixed.createFlags, result);
+    if (XR_SUCCEEDED(result)) {
+        remember_swapchain(*swapchain);
+        flip_on_create_swapchain(*swapchain, &fixed);
+        emul_on_create_swapchain(*swapchain, &fixed);
+        return result;
+    }
    if (!swapchain_fix) return result;

    // Frame's runtime rejects some GLES formats (GL_RGBA8) and MSAA swapchains (overport #71).
@@ -333,7 +402,11 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
            LOG("  retry format=%lld result=%d", (long long)replacement, result);
        }
    }
-    if (XR_SUCCEEDED(result)) { remember_swapchain(*swapchain); flip_on_create_swapchain(*swapchain, &fixed); }
+    if (XR_SUCCEEDED(result)) {
+        remember_swapchain(*swapchain);
+        flip_on_create_swapchain(*swapchain, &fixed);
+        emul_on_create_swapchain(*swapchain, &fixed);
+    }
    return result;
 }

@@ -342,23 +415,73 @@ XRAPI_ATTR XrResult XRAPI_CALL xrDestroySwapchain(XrSwapchain swapchain) {
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
    forget_swapchain(swapchain);
    flip_on_destroy(swapchain);
+    emul_on_destroy_swapchain(swapchain);
+    if (equirect_emul && emul_is_virtual(swapchain)) { emul_virtual_destroy(swapchain); return XR_SUCCESS; }
    return fn(swapchain);
 }

+// ---- cylinder layers (XR_KHR_composition_layer_cylinder), which the Frame runtime lacks: shown as a few flat quads
+// (chords of the arc), each showing its share of the image. The runtime composites them from the app's own image at
+// full resolution, and they stay within centimetres of where the app aims its pointer at the curved surface.
+static XrVector3f strip_rotate(XrQuaternionf q, XrVector3f v) {  // v' = v + 2w(u x v) + 2 u x (u x v)
+    XrVector3f u = {q.x, q.y, q.z}, t = {2 * (u.y * v.z - u.z * v.y), 2 * (u.z * v.x - u.x * v.z), 2 * (u.x * v.y - u.y * v.x)};
+    return (XrVector3f){v.x + q.w * t.x + (u.y * t.z - u.z * t.y), v.y + q.w * t.y + (u.z * t.x - u.x * t.z),
+                        v.z + q.w * t.z + (u.x * t.y - u.y * t.x)};
+}
+
+static XrQuaternionf strip_mul(XrQuaternionf a, XrQuaternionf b) {
+    return (XrQuaternionf){a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y, a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
+                           a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w, a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z};
+}
+
+// Returns the number of quads written to out (0 = not possible). budget = layers still allowed in the frame.
+static int cylinder_strips(const XrCompositionLayerCylinderKHR *c, XrCompositionLayerQuad *out, int budget) {
+    if (c->centralAngle <= 0 || c->aspectRatio <= 0) return 0;
+    float r = c->radius > 0 && c->radius < 1e4f ? c->radius : 3.0f;
+    int n = (int)ceilf(c->centralAngle / 0.26f);  // ~15 degrees per strip
+    if (n > 8) n = 8;
+    if (n > budget) n = budget;
+    if (n < 1) return 0;
+    float a = c->centralAngle / (float)n, height = r * c->centralAngle / c->aspectRatio;
+    const XrRect2Di rect = c->subImage.imageRect;
+    for (int i = 0; i < n; ++i) {
+        float phi = -c->centralAngle / 2 + (i + 0.5f) * a;  // + = towards +X (the image's right)
+        XrQuaternionf yaw = {0, sinf(-phi / 2), 0, cosf(-phi / 2)};
+        XrPosef pose;
+        pose.orientation = strip_mul(c->pose.orientation, yaw);
+        XrVector3f d = strip_rotate(pose.orientation, (XrVector3f){0, 0, -r * cosf(a / 2)});
+        pose.position = (XrVector3f){c->pose.position.x + d.x, c->pose.position.y + d.y, c->pose.position.z + d.z};
+        int32_t x0 = rect.offset.x + (int32_t)((int64_t)rect.extent.width * i / n);
+        int32_t x1 = rect.offset.x + (int32_t)((int64_t)rect.extent.width * (i + 1) / n);
+        XrSwapchainSubImage sub = c->subImage;
+        sub.imageRect = (XrRect2Di){{x0, rect.offset.y}, {x1 - x0, rect.extent.height}};
+        out[i] = (XrCompositionLayerQuad){XR_TYPE_COMPOSITION_LAYER_QUAD, c->next, c->layerFlags, c->space,
+                                          c->eyeVisibility, sub, pose, {2 * r * sinf(a / 2), height}};
+    }
+    static int logged;
+    if (logged++ < 3) LOG("cylinder layer -> %d quad strips (r=%.2f angle=%.2f)", n, r, c->centralAngle);
+    return n;
+}
+
 // A layer is usable if every swapchain it references was created successfully.
+// Swapchains the runtime can show: created by it (adapter-served 360 pictures only feed the adapter's own drawing).
+static int runtime_swapchain(XrSwapchain handle) {
+    return known_swapchain(handle) && !(equirect_emul && emul_is_virtual(handle));
+}
+
 static int layer_usable(const XrCompositionLayerBaseHeader *layer) {
    switch (layer->type) {
    case XR_TYPE_COMPOSITION_LAYER_PROJECTION: {
        const XrCompositionLayerProjection *p = (const XrCompositionLayerProjection *)layer;
        for (uint32_t v = 0; v < p->viewCount; ++v)
-            if (!known_swapchain(p->views[v].subImage.swapchain)) return 0;
+            if (!runtime_swapchain(p->views[v].subImage.swapchain)) return 0;
        return 1;
    }
    case XR_TYPE_COMPOSITION_LAYER_QUAD:
-        return known_swapchain(((const XrCompositionLayerQuad *)layer)->subImage.swapchain);
+        return runtime_swapchain(((const XrCompositionLayerQuad *)layer)->subImage.swapchain);
    case XR_TYPE_COMPOSITION_LAYER_CYLINDER_KHR:
        if (no_cylinder) return 0;
-        return known_swapchain(((const XrCompositionLayerCylinderKHR *)layer)->subImage.swapchain);
+        return runtime_swapchain(((const XrCompositionLayerCylinderKHR *)layer)->subImage.swapchain);
    case XR_TYPE_COMPOSITION_LAYER_EQUIRECT_KHR:
        if (no_equirect) return 0;
        return known_swapchain(((const XrCompositionLayerEquirectKHR *)layer)->subImage.swapchain);
@@ -367,7 +490,7 @@ static int layer_usable(const XrCompositionLayerBaseHeader *layer) {
        return known_swapchain(((const XrCompositionLayerEquirect2KHR *)layer)->subImage.swapchain);
    case XR_TYPE_COMPOSITION_LAYER_CUBE_KHR:
        if (no_cube) return 0;
-        return known_swapchain(((const XrCompositionLayerCubeKHR *)layer)->swapchain);
+        return runtime_swapchain(((const XrCompositionLayerCubeKHR *)layer)->swapchain);
    default:
        return 1;  // layer types without swapchains (e.g. passthrough) or unknown: pass through
    }
@@ -450,7 +573,11 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetSystemProperties(XrInstance instance, XrSyst
    PFN_xrGetSystemProperties fn = (PFN_xrGetSystemProperties)lookup(instance, "xrGetSystemProperties");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
    XrResult result = fn(instance, system, properties);
-    if (XR_SUCCEEDED(result) && (emulate_passthrough || emulate_scene) && properties)
+    if (XR_SUCCEEDED(result) && properties && layer_debug)
+        LOG("layer_debug: system '%s' maxLayerCount=%u max swapchain %ux%u", properties->systemName,
+            properties->graphicsProperties.maxLayerCount, properties->graphicsProperties.maxSwapchainImageWidth,
+            properties->graphicsProperties.maxSwapchainImageHeight);
+    if (XR_SUCCEEDED(result) && (emulate_passthrough || emulate_scene || emulate_render_model) && properties)
        for (XrBaseOutStructure *p = (XrBaseOutStructure *)properties->next; p; p = p->next) {
            if (p->type == XR_TYPE_SYSTEM_PASSTHROUGH_PROPERTIES_FB)
                ((XrSystemPassthroughPropertiesFB *)p)->supportsPassthrough = XR_TRUE;
@@ -458,6 +585,8 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetSystemProperties(XrInstance instance, XrSyst
                ((XrSystemSpatialEntityPropertiesFB *)p)->supportsSpatialEntity = XR_TRUE;
            if (p->type == XR_TYPE_SYSTEM_PASSTHROUGH_PROPERTIES2_FB)
                ((XrSystemPassthroughProperties2FB *)p)->capabilities = XR_PASSTHROUGH_CAPABILITY_BIT_FB;
+            if (p->type == XR_TYPE_SYSTEM_RENDER_MODEL_PROPERTIES_FB && emulate_render_model)
+                ((XrSystemRenderModelPropertiesFB *)p)->supportsRenderModelLoading = XR_TRUE;
        }
    return result;
 }
@@ -536,11 +665,20 @@ XRAPI_ATTR XrResult XRAPI_CALL xrDestroySpace(XrSpace space) {
    return fn ? fn(space) : XR_ERROR_FUNCTION_UNSUPPORTED;
 }

+#include "session_fixes.c"
+#include "layer_emul_gl.c"
+
 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 (XR_SUCCEEDED(result)) { flip_emul = flip_emul_setting; flip_on_create_session(info); scene_on_create_session(*session); }
+    if (XR_SUCCEEDED(result)) {
+        flip_emul = flip_emul_setting;
+        flip_on_create_session(info);
+        scene_on_create_session(*session);
+        session_fixes_on_create_session(*session);
+        emul_on_create_session(*session, info);
+    }
    return result;
 }

@@ -548,8 +686,12 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateSwapchainImages(XrSwapchain swapchain,
        XrSwapchainImageBaseHeader *images) {
    PFN_xrEnumerateSwapchainImages fn = (PFN_xrEnumerateSwapchainImages)lookup(active_instance, "xrEnumerateSwapchainImages");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
-    XrResult result = fn(swapchain, capacity, count, images);
-    if (XR_SUCCEEDED(result) && images && capacity && count) flip_on_enumerate_images(swapchain, *count, images);
+    XrResult result = equirect_emul && emul_is_virtual(swapchain) ? emul_virtual_enumerate(swapchain, capacity, count, images)
+                                                                  : fn(swapchain, capacity, count, images);
+    if (XR_SUCCEEDED(result) && images && capacity && count) {
+        flip_on_enumerate_images(swapchain, *count, images);
+        emul_on_enumerate(swapchain, *count < capacity ? *count : capacity, images);
+    }
    return result;
 }

@@ -557,8 +699,14 @@ XRAPI_ATTR XrResult XRAPI_CALL xrAcquireSwapchainImage(XrSwapchain swapchain, co
        uint32_t *index) {
    PFN_xrAcquireSwapchainImage fn = (PFN_xrAcquireSwapchainImage)lookup(active_instance, "xrAcquireSwapchainImage");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (equirect_emul && emul_is_virtual(swapchain)) {  // adapter-served write-once picture: one image
+        if (!index) return XR_ERROR_VALIDATION_FAILURE;
+        *index = 0;
+        emul_on_acquire(swapchain, 0);
+        return XR_SUCCESS;
+    }
    XrResult result = fn(swapchain, info, index);
-    if (XR_SUCCEEDED(result) && index) flip_on_acquire(swapchain, *index);
+    if (XR_SUCCEEDED(result) && index) { flip_on_acquire(swapchain, *index); emul_on_acquire(swapchain, *index); }
    return result;
 }

@@ -580,7 +728,17 @@ XRAPI_ATTR XrResult XRAPI_CALL xrPollEvent(XrInstance instance, XrEventDataBuffe
        pthread_mutex_unlock(&scene_lock);
        if (got) return XR_SUCCESS;
    }
-    XrResult result = fn(instance, event);
+    XrResult result = focus_hold && event ? focus_hold_poll(fn, instance, event) : fn(instance, event);
+    if (result == XR_SUCCESS && event && (layer_debug || stable_local)) {
+        if (event->type == XR_TYPE_EVENT_DATA_SESSION_STATE_CHANGED && layer_debug)
+            LOG("layer_debug: session state %d at %.3f", ((const XrEventDataSessionStateChanged *)event)->state,
+                monotonic_ns() / 1e9);
+        if (event->type == XR_TYPE_EVENT_DATA_REFERENCE_SPACE_CHANGE_PENDING) {
+            const XrEventDataReferenceSpaceChangePending *e = (const XrEventDataReferenceSpaceChangePending *)event;
+            if (layer_debug) LOG("layer_debug: runtime reference space change pending type=%d", e->referenceSpaceType);
+            if (e->referenceSpaceType == XR_REFERENCE_SPACE_TYPE_LOCAL) local_anchor_stale = 1;
+        }
+    }
    if (!respace_kick || !event) return result;
    if (result == XR_SUCCESS && event->type == XR_TYPE_EVENT_DATA_SESSION_STATE_CHANGED) {
        const XrEventDataSessionStateChanged *e = (const XrEventDataSessionStateChanged *)event;
@@ -611,17 +769,22 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateReferenceSpace(XrSession session, const X
        XrSpace *space) {
    PFN_xrCreateReferenceSpace fn = (PFN_xrCreateReferenceSpace)lookup(active_instance, "xrCreateReferenceSpace");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    XrReferenceSpaceCreateInfo fixed;
+    if (stable_local && info && info->referenceSpaceType == XR_REFERENCE_SPACE_TYPE_LOCAL) {
+        fixed = *info;
+        fixed.poseInReferenceSpace = stable_local_pose(session, info->poseInReferenceSpace);
+        info = &fixed;
+    }
    XrResult result = fn(session, info, space);
    if (info && space) {
        LOG("xrCreateReferenceSpace type=%d result=%d space=%p", info->referenceSpaceType, result,
            (void *)(uintptr_t)*space);
+        if (layer_debug && XR_SUCCEEDED(result)) debug_reference_space(session, info, *space);
        if (XR_SUCCEEDED(result) && info->referenceSpaceType == XR_REFERENCE_SPACE_TYPE_VIEW) view_space_handle = *space;
    }
    return result;
 }

-static XrTime last_predicted_time;
-
 XRAPI_ATTR XrResult XRAPI_CALL xrWaitFrame(XrSession session, const XrFrameWaitInfo *info, XrFrameState *state) {
    PFN_xrWaitFrame fn = (PFN_xrWaitFrame)lookup(active_instance, "xrWaitFrame");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
@@ -634,6 +797,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrWaitFrame(XrSession session, const XrFrameWaitI
        // predictedDisplayTime is about one display period ahead of "now".
        xr_time_offset = (int64_t)(state->predictedDisplayTime - state->predictedDisplayPeriod) - mono;
        xr_time_calibrated = 1;
+        if (layer_debug) debug_aim_vs_grip(state->predictedDisplayTime);
    }
    return result;
 }
@@ -643,6 +807,9 @@ XRAPI_ATTR XrResult XRAPI_CALL xrLocateViews(XrSession session, const XrViewLoca
    PFN_xrLocateViews fn = (PFN_xrLocateViews)lookup(active_instance, "xrLocateViews");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
    XrResult result = fn(session, info, state, capacity, 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);
    // respace_kick trigger: ~90 consecutive untracked head poses in a non-VIEW space.
    static int untracked;
    if (respace_kick && XR_SUCCEEDED(result) && state && info && info->space != view_space_handle) {
@@ -706,6 +873,38 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
    if ((!layer_fix && !swap_eyes && !emulate_passthrough && !flip_quads && !flip_emul && !strip_depth) || !info || !info->layerCount ||
        info->layerCount > 64)
        return fn(session, info);
+    if (layer_debug) {  // the submitted layer list (order, flags, eyes, chained structs) whenever its shape changes
+        static char last[1024];
+        char now[1024];
+        size_t used = 0;
+        for (uint32_t i = 0; i < info->layerCount && used < sizeof(now) - 64; ++i) {
+            const XrCompositionLayerBaseHeader *l = info->layers[i];
+            if (!l) continue;
+            int eye = -1;
+            if (l->type == XR_TYPE_COMPOSITION_LAYER_QUAD) eye = ((const XrCompositionLayerQuad *)l)->eyeVisibility;
+            if (l->type == XR_TYPE_COMPOSITION_LAYER_CYLINDER_KHR) eye = ((const XrCompositionLayerCylinderKHR *)l)->eyeVisibility;
+            if (l->type == XR_TYPE_COMPOSITION_LAYER_EQUIRECT2_KHR) eye = ((const XrCompositionLayerEquirect2KHR *)l)->eyeVisibility;
+            used += (size_t)snprintf(now + used, sizeof(now) - used, " [%d f=0x%llx e=%d", l->type,
+                                     (unsigned long long)l->layerFlags, eye);
+            if (l->type == XR_TYPE_COMPOSITION_LAYER_EQUIRECT2_KHR) {  // mapping + source size: 360 vs 180, SBS halves
+                const XrCompositionLayerEquirect2KHR *q = (const XrCompositionLayerEquirect2KHR *)l;
+                used += (size_t)snprintf(now + used, sizeof(now) - used, " h=%.2f u=%.2f l=%.2f r=%.1f rect=%d,%d %dx%d",
+                                         q->centralHorizontalAngle, q->upperVerticalAngle, q->lowerVerticalAngle,
+                                         q->radius, q->subImage.imageRect.offset.x, q->subImage.imageRect.offset.y,
+                                         q->subImage.imageRect.extent.width, q->subImage.imageRect.extent.height);
+            }
+            for (const XrBaseInStructure *n = (const XrBaseInStructure *)l->next; n && used < sizeof(now) - 32; n = n->next)
+                used += (size_t)snprintf(now + used, sizeof(now) - used, " n=%d", n->type);
+            used += (size_t)snprintf(now + used, sizeof(now) - used, "]");
+        }
+        if (strcmp(now, last)) {
+            LOG("layer_debug: frame layers blend=%d:%s", info->environmentBlendMode, now);
+            snprintf(last, sizeof(last), "%s", now);
+        }
+    }
+    // equirect_emul: the frame's 360 layers are replaced by one emulated projection layer (at the first one's place)
+    const XrCompositionLayerBaseHeader *emul_layer_out = NULL;
+    int emul_first = layer_fix && emul_active() ? emul_prepare_frame(info, &emul_layer_out) : -1;
    const XrCompositionLayerBaseHeader *kept[64];
    XrCompositionLayerProjection projections[64];
    XrCompositionLayerProjectionView views[64][2];
@@ -735,6 +934,23 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
                LOG("new layer: type=%d swapchain=%p flip_tag=%d usable=%d", layer->type, key, tagged, layer_usable(layer));
            }
        }
+        if (emul_first >= 0 && emul_layer_out && emul_is_equirect(layer)) {
+            if ((int)i == emul_first) kept[count++] = emul_layer_out;  // all 360 layers are drawn into it
+            ++swapped;
+            continue;
+        }
+        if (layer_fix && cylinder_strips_on && no_cylinder && layer->type == XR_TYPE_COMPOSITION_LAYER_CYLINDER_KHR &&
+            runtime_swapchain(((const XrCompositionLayerCylinderKHR *)layer)->subImage.swapchain)) {
+            // keep the whole frame within the runtime's layer limit: every later layer still needs a slot
+            int budget = 16 - (int)count - (int)(info->layerCount - i - 1);
+            int n = cylinder_strips((const XrCompositionLayerCylinderKHR *)layer, &quads[count], budget < 64 - (int)count ? budget : 64 - (int)count);
+            if (n > 0) {
+                for (int k = 0; k < n; ++k) kept[count + k] = (const XrCompositionLayerBaseHeader *)&quads[count + k];
+                count += (uint32_t)n;
+                ++swapped;
+                continue;
+            }
+        }
        if (!layer || (layer_fix && !layer_usable(layer))) { ++dropped; continue; }
        if (layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD) {
            const XrCompositionLayerQuad *flipped = flip_quad(session, (const XrCompositionLayerQuad *)layer, &quads[count]);
@@ -882,12 +1098,13 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateInstanceExtensionProperties(const char
        XR_NULL_HANDLE, "xrEnumerateInstanceExtensionProperties");
    if (!fn) return XR_ERROR_INITIALIZATION_FAILED;
    if (!count) return XR_ERROR_VALIDATION_FAILURE;
-    if ((!foveation_fix && !passthrough_emul && !scene_emul) || layer) return fn(layer, capacity, count, properties);
+    if ((!foveation_fix && !passthrough_emul && !scene_emul && !controller_models) || layer)
+        return fn(layer, capacity, count, properties);

    uint32_t total = 0;
    XrResult result = fn(layer, 0, &total, NULL);
    if (XR_FAILED(result)) return result;
-    XrExtensionProperties *all = calloc(total + 1 + SCENE_EXTENSION_COUNT, sizeof(*all));
+    XrExtensionProperties *all = calloc(total + 2 + SCENE_EXTENSION_COUNT, sizeof(*all));
    if (!all) return XR_ERROR_OUT_OF_MEMORY;
    for (uint32_t i = 0; i < total; ++i) all[i].type = XR_TYPE_EXTENSION_PROPERTIES;
    result = fn(layer, total, &total, all);
@@ -896,6 +1113,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateInstanceExtensionProperties(const char
    uint32_t kept = 0;
    for (uint32_t i = 0; i < total; ++i) {
        if (!strcmp(all[i].extensionName, "XR_FB_passthrough")) runtime_has_fb_passthrough = 1;
+        if (!strcmp(all[i].extensionName, XR_FB_RENDER_MODEL_EXTENSION_NAME)) runtime_has_render_model = 1;
        if (foveation_fix && strstr(all[i].extensionName, "foveation")) continue;
        if (properties && kept < capacity) properties[kept] = all[i];
        ++kept;
@@ -916,6 +1134,12 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateInstanceExtensionProperties(const char
        if (properties && kept < capacity) properties[kept] = fake;
        ++kept;
    }
+    if (controller_models && render_models_available && !runtime_has_render_model) {
+        XrExtensionProperties fake = {XR_TYPE_EXTENSION_PROPERTIES, NULL, XR_FB_RENDER_MODEL_EXTENSION_NAME,
+                                      XR_FB_render_model_SPEC_VERSION};
+        if (properties && kept < capacity) properties[kept] = fake;
+        ++kept;
+    }
    free(all);
    *count = kept;
    return (capacity && capacity < kept) ? XR_ERROR_SIZE_INSUFFICIENT : XR_SUCCESS;
@@ -928,6 +1152,12 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateApiLayerProperties(uint32_t capacity,
    return fn ? fn(capacity, count, properties) : XR_ERROR_INITIALIZATION_FAILED;
 }

+// For native/xrshim: emulated functions that overport's dispatcher doesn't know (it never asks us for them).
+__attribute__((visibility("default"))) PFN_xrVoidFunction framebridge_extension_proc(const char *name) {
+    pthread_once(&init_once, initialize);
+    return name ? render_model_emulation(name) : NULL;
+}
+
 XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const char *name,
        PFN_xrVoidFunction *function) {
    pthread_once(&init_once, initialize);
@@ -948,6 +1178,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
    }
    PFN_xrVoidFunction emulated = passthrough_emulation(name);
    if (!emulated) emulated = scene_emulation(name);
+    if (!emulated) emulated = render_model_emulation(name);
    if (!emulated && emulate_scene && !strcmp(name, "xrLocateSpacesKHR")) emulated = (PFN_xrVoidFunction)emu_locate_spaces_khr;
    if (emulated) { *function = emulated; return XR_SUCCESS; }
    HOOK(xrGetSystemProperties)
@@ -969,6 +1200,22 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
    HOOK(xrLocateHandJointsEXT)
    HOOK(xrGetCurrentInteractionProfile)
    HOOK(xrEnumerateInstanceExtensionProperties)
+    // Per-game hooks: only installed when their setting is on, so other games run through exactly the same calls.
+#define HOOK_AS(fn, impl) if (!strcmp(name, #fn)) { *function = (PFN_xrVoidFunction)impl; return XR_SUCCESS; }
+    if (equirect_emul) {
+        HOOK_AS(xrReleaseSwapchainImage, hook_xrReleaseSwapchainImage)
+        HOOK_AS(xrWaitSwapchainImage, hook_xrWaitSwapchainImage)
+        HOOK_AS(xrDestroySession, hook_xrDestroySession)
+    }
+    if (layer_debug || refresh_rate > 0 || equirect_emul) HOOK_AS(xrBeginSession, hook_xrBeginSession)
+    if (layer_debug || refresh_rate > 0) {
+        HOOK_AS(xrRequestDisplayRefreshRateFB, hook_request_refresh_rate)
+    }
+    if (layer_debug || aim_correction_on()) {
+        HOOK_AS(xrSuggestInteractionProfileBindings, hook_xrSuggestInteractionProfileBindings)
+        HOOK_AS(xrCreateActionSpace, hook_xrCreateActionSpace)
+    }
+#undef HOOK_AS
 #undef HOOK
    return next_gipa(instance, name, function);
 }
@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Pose / direction math shared by the adapter's per-game fixes (session_fixes.c, layer_emul_gl.c). Header-only and
+// free of Android/GL dependencies so tests/test_layer_emul.py can compile it for the host.
+#ifndef FRAMEBRIDGE_LAYER_MATH_H
+#define FRAMEBRIDGE_LAYER_MATH_H
+#include <math.h>
+#include <openxr/openxr.h>
+
+#define LM_PI 3.14159265358979323846f
+
+static inline XrVector3f lm_rotate(XrQuaternionf q, XrVector3f v) {  // v' = v + 2w(u x v) + 2 u x (u x v)
+    XrVector3f u = {q.x, q.y, q.z}, t = {2 * (u.y * v.z - u.z * v.y), 2 * (u.z * v.x - u.x * v.z), 2 * (u.x * v.y - u.y * v.x)};
+    return (XrVector3f){v.x + q.w * t.x + (u.y * t.z - u.z * t.y), v.y + q.w * t.y + (u.z * t.x - u.x * t.z),
+                        v.z + q.w * t.z + (u.x * t.y - u.y * t.x)};
+}
+
+static inline XrQuaternionf lm_qmul(XrQuaternionf a, XrQuaternionf b) {
+    return (XrQuaternionf){a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y, a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
+                           a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w, a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z};
+}
+
+static inline XrQuaternionf lm_qconj(XrQuaternionf q) { return (XrQuaternionf){-q.x, -q.y, -q.z, q.w}; }
+
+static inline XrQuaternionf lm_axis_angle(float x, float y, float z, float radians) {
+    float s = sinf(radians / 2);
+    return (XrQuaternionf){x * s, y * s, z * s, cosf(radians / 2)};
+}
+
+// a∘b: the pose b (expressed in a's frame) expressed in a's parent frame.
+static inline XrPosef lm_pose_mul(XrPosef a, XrPosef b) {
+    XrVector3f p = lm_rotate(a.orientation, b.position);
+    return (XrPosef){lm_qmul(a.orientation, b.orientation),
+                     {a.position.x + p.x, a.position.y + p.y, a.position.z + p.z}};
+}
+
+static inline XrPosef lm_pose_inv(XrPosef a) {
+    XrQuaternionf q = lm_qconj(a.orientation);
+    XrVector3f p = lm_rotate(q, a.position);
+    return (XrPosef){q, {-p.x, -p.y, -p.z}};
+}
+
+// Rotation angle (radians) of a pose: how far it is from identity.
+static inline float lm_angle(XrQuaternionf q) {
+    float w = fabsf(q.w) > 1 ? 1 : fabsf(q.w);
+    return 2 * acosf(w);
+}
+
+static inline float lm_length(XrVector3f v) { return sqrtf(v.x * v.x + v.y * v.y + v.z * v.z); }
+
+static inline float lm_dot(XrVector3f a, XrVector3f b) { return a.x * b.x + a.y * b.y + a.z * b.z; }
+
+// ---- cube faces used to show 360° (equirect) layers as world-locked quads.
+// Face f looks along lm_face_rotation(f) * (0,0,-1): 0 = -Z (front), 1 = +X (right), 2 = +Z (back), 3 = -X (left),
+// 4 = +Y (up), 5 = -Y (down). The same rotation orients the face's quad (a quad faces +Z, so it faces the centre).
+static inline XrQuaternionf lm_face_rotation(int face) {
+    switch (face) {
+    case 1: return lm_axis_angle(0, 1, 0, -LM_PI / 2);
+    case 2: return lm_axis_angle(0, 1, 0, LM_PI);
+    case 3: return lm_axis_angle(0, 1, 0, LM_PI / 2);
+    case 4: return lm_axis_angle(1, 0, 0, LM_PI / 2);
+    case 5: return lm_axis_angle(1, 0, 0, -LM_PI / 2);
+    default: return (XrQuaternionf){0, 0, 0, 1};
+    }
+}
+
+// Direction (layer space) of the point (u, v) in [-1, 1]² of face f (u = right, v = up on the face's quad).
+static inline XrVector3f lm_face_dir(int face, float u, float v) {
+    return lm_rotate(lm_face_rotation(face), (XrVector3f){u, v, -1});
+}
+
+// Pose of face f's quad: `distance` metres from the layer's origin, facing it.
+static inline XrPosef lm_face_pose(XrPosef layer, int face, float distance) {
+    XrPosef local = {lm_face_rotation(face), lm_face_dir(face, 0, 0)};
+    local.position.x *= distance; local.position.y *= distance; local.position.z *= distance;
+    return lm_pose_mul(layer, local);
+}
+
+// GL cube map convention (the equirect_emul shader's cube_dir): direction of texel (s, t) = ((u + 1) / 2, (v + 1) / 2)
+// on face GL_TEXTURE_CUBE_MAP_POSITIVE_X + face.
+static inline XrVector3f lm_glcube_dir(int face, float u, float v) {
+    switch (face) {
+    case 0: return (XrVector3f){1, -v, -u};
+    case 1: return (XrVector3f){-1, -v, u};
+    case 2: return (XrVector3f){u, 1, v};
+    case 3: return (XrVector3f){u, -1, -v};
+    case 4: return (XrVector3f){u, -v, 1};
+    default: return (XrVector3f){-u, -v, -1};
+    }
+}
+
+// GL's cube map lookup (OpenGL ES 3.0 spec, table 3.21): direction -> face and (s, t).
+static inline int lm_glcube_lookup(XrVector3f d, float *s, float *t) {
+    float ax = fabsf(d.x), ay = fabsf(d.y), az = fabsf(d.z), sc, tc, ma;
+    int face;
+    if (ax >= ay && ax >= az) { face = d.x > 0 ? 0 : 1; ma = ax; sc = d.x > 0 ? -d.z : d.z; tc = -d.y; }
+    else if (ay >= az) { face = d.y > 0 ? 2 : 3; ma = ay; sc = d.x; tc = d.y > 0 ? d.z : -d.z; }
+    else { face = d.z > 0 ? 4 : 5; ma = az; sc = d.z > 0 ? d.x : -d.x; tc = -d.y; }
+    *s = (sc / ma + 1) / 2;
+    *t = (tc / ma + 1) / 2;
+    return face;
+}
+
+// Equirect2 mapping (XR_KHR_composition_layer_equirect2): direction (layer space) -> normalized image coordinates
+// (u right, v up; v = 0 at lowerVerticalAngle). Longitude 0 is the -Z axis, growing towards +X.
+// Returns 0 when the direction is outside the layer's angles.
+static inline int lm_equirect2_uv(XrVector3f d, float central, float upper, float lower, float *u, float *v) {
+    float len = lm_length(d);
+    if (len <= 0 || central <= 0 || upper <= lower) return 0;
+    float lon = atan2f(d.x, -d.z), lat = asinf(fmaxf(-1.0f, fminf(1.0f, d.y / len)));
+    *u = lon / central + 0.5f;
+    *v = (lat - lower) / (upper - lower);
+    return *u >= 0 && *u <= 1 && *v >= 0 && *v <= 1;
+}
+
+// Is any part of face f within `cos_limit` (cosine of the angle) of `forward` (unit, layer space)? Samples a grid on
+// the face, so it is conservative up to the grid spacing (the caller adds a margin to cos_limit for that).
+static inline int lm_face_visible(int face, XrVector3f forward, float cos_limit) {
+    for (int i = 0; i <= 4; ++i)
+        for (int j = 0; j <= 4; ++j) {
+            XrVector3f d = lm_face_dir(face, -1 + 0.5f * i, -1 + 0.5f * j);
+            if (lm_dot(d, forward) / lm_length(d) >= cos_limit) return 1;
+        }
+    return 0;
+}
+
+// Cosine of the angle between the face's centre direction and `forward` (unit): sort key, larger = closer to view.
+static inline float lm_face_score(int face, XrVector3f forward) { return lm_dot(lm_face_dir(face, 0, 0), forward); }
+
+#endif
@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// XR_FB_render_model emulation (controller_models): serves Steam Frame controller models to games that ask the
+// runtime for controller models (Meta XR SDK "runtime controller" / OVRRuntimeController, Unreal OculusXR), so they
+// show the controllers in your hands instead of Quest Touch controllers. Games that ship their own controller meshes
+// don't use this extension and are not affected.
+//
+// The models are glTF binaries converted on the Frame from its own SteamVR render models by the FramePort agent:
+//   /sdcard/Android/data/<package>/files/framebridge/controller_{left,right}.glb
+// Only active when both files exist and the runtime lacks XR_FB_render_model (a native one is used as is).
+// Included by frame_adapter.c.
+
+static int render_models_available;    // both .glb files present
+static int runtime_has_render_model;
+static int emulate_render_model;
+static char render_model_dir[512];
+
+static const char *const render_model_paths[2] = {"/model_fb/controller/left", "/model_fb/controller/right"};
+static const char *const render_model_files[2] = {"controller_left.glb", "controller_right.glb"};
+static const char *const render_model_names[2] = {"Steam Frame Controller Left", "Steam Frame Controller Right"};
+#define RENDER_MODEL_VENDOR_VALVE 0x28DE
+#define RENDER_MODEL_KEY_BASE 0x46500000u  // keys: base + 1 (left), base + 2 (right)
+
+static void render_model_scan(const char *dir) {
+    snprintf(render_model_dir, sizeof(render_model_dir), "%s", dir);
+    char path[640];
+    int found = 0;
+    for (int i = 0; i < 2; ++i) {
+        snprintf(path, sizeof(path), "%s/%s", render_model_dir, render_model_files[i]);
+        FILE *f = fopen(path, "rb");
+        if (f) { ++found; fclose(f); }
+    }
+    render_models_available = found == 2;
+    LOG("controller models %s in %s", render_models_available ? "found" : "not found", render_model_dir);
+}
+
+static void render_model_init(const char *package) {
+    if (!package || !*package) return;
+    char dir[512];
+    snprintf(dir, sizeof(dir), "/sdcard/Android/data/%s/files/framebridge", package);
+    render_model_scan(dir);
+}
+
+static int render_model_index(XrPath path) {
+    PFN_xrStringToPath to_path = (PFN_xrStringToPath)lookup(active_instance, "xrStringToPath");
+    if (!to_path || !active_instance) return -1;
+    for (int i = 0; i < 2; ++i) {
+        XrPath p = XR_NULL_PATH;
+        if (XR_SUCCEEDED(to_path(active_instance, render_model_paths[i], &p)) && p == path) return i;
+    }
+    return -1;
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL emu_enumerate_render_model_paths(XrSession session, uint32_t capacity,
+        uint32_t *count, XrRenderModelPathInfoFB *paths) {
+    (void)session;
+    if (!count) return XR_ERROR_VALIDATION_FAILURE;
+    *count = 2;
+    if (!capacity) return XR_SUCCESS;
+    if (capacity < 2 || !paths) return XR_ERROR_SIZE_INSUFFICIENT;
+    PFN_xrStringToPath to_path = (PFN_xrStringToPath)lookup(active_instance, "xrStringToPath");
+    if (!to_path) return XR_ERROR_RUNTIME_FAILURE;
+    for (int i = 0; i < 2; ++i) {
+        XrResult r = to_path(active_instance, render_model_paths[i], &paths[i].path);
+        if (XR_FAILED(r)) return r;
+    }
+    return XR_SUCCESS;
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL emu_get_render_model_properties(XrSession session, XrPath path,
+        XrRenderModelPropertiesFB *properties) {
+    (void)session;
+    if (!properties) return XR_ERROR_VALIDATION_FAILURE;
+    XrRenderModelFlagsFB requested = XR_RENDER_MODEL_SUPPORTS_GLTF_2_0_SUBSET_1_BIT_FB;
+    for (const XrBaseInStructure *p = (const XrBaseInStructure *)properties->next; p; p = p->next)
+        if (p->type == XR_TYPE_RENDER_MODEL_CAPABILITIES_REQUEST_FB)
+            requested = ((const XrRenderModelCapabilitiesRequestFB *)p)->flags;
+    int i = render_model_index(path);
+    if (i < 0) {
+        properties->modelKey = XR_NULL_RENDER_MODEL_KEY_FB;
+        return XR_ERROR_PATH_UNSUPPORTED;
+    }
+    properties->vendorId = RENDER_MODEL_VENDOR_VALVE;
+    snprintf(properties->modelName, sizeof(properties->modelName), "%s", render_model_names[i]);
+    properties->modelKey = (XrRenderModelKeyFB)(RENDER_MODEL_KEY_BASE + 1 + i);
+    properties->modelVersion = 1;
+    // One mesh, one PNG texture, no animation: fits subset 1 and therefore every subset an app can ask for.
+    properties->flags = requested & XR_RENDER_MODEL_SUPPORTS_GLTF_2_0_SUBSET_2_BIT_FB
+        ? XR_RENDER_MODEL_SUPPORTS_GLTF_2_0_SUBSET_2_BIT_FB : XR_RENDER_MODEL_SUPPORTS_GLTF_2_0_SUBSET_1_BIT_FB;
+    static int logged[2];
+    if (!logged[i]++) LOG("render model %s -> %s/%s", render_model_paths[i], render_model_dir, render_model_files[i]);
+    return XR_SUCCESS;
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL emu_load_render_model(XrSession session, const XrRenderModelLoadInfoFB *info,
+        XrRenderModelBufferFB *buffer) {
+    (void)session;
+    if (!info || !buffer) return XR_ERROR_VALIDATION_FAILURE;
+    uint64_t key = (uint64_t)info->modelKey;
+    if (key != RENDER_MODEL_KEY_BASE + 1 && key != RENDER_MODEL_KEY_BASE + 2) return XR_ERROR_RENDER_MODEL_KEY_INVALID_FB;
+    int i = (int)(key - RENDER_MODEL_KEY_BASE - 1);
+    char path[640];
+    snprintf(path, sizeof(path), "%s/%s", render_model_dir, render_model_files[i]);
+    FILE *f = fopen(path, "rb");
+    if (!f) { LOG("render model %s missing", path); return XR_ERROR_RENDER_MODEL_KEY_INVALID_FB; }
+    long size = -1;
+    if (!fseek(f, 0, SEEK_END)) size = ftell(f);
+    if (size <= 0 || size > 0x7fffffffL || fseek(f, 0, SEEK_SET)) { fclose(f); return XR_ERROR_RUNTIME_FAILURE; }
+    buffer->bufferCountOutput = (uint32_t)size;
+    if (!buffer->bufferCapacityInput) { fclose(f); return XR_SUCCESS; }
+    if (buffer->bufferCapacityInput < (uint32_t)size || !buffer->buffer) { fclose(f); return XR_ERROR_SIZE_INSUFFICIENT; }
+    size_t got = fread(buffer->buffer, 1, (size_t)size, f);
+    fclose(f);
+    return got == (size_t)size ? XR_SUCCESS : XR_ERROR_RUNTIME_FAILURE;
+}
+
+static PFN_xrVoidFunction render_model_emulation(const char *name) {
+    if (!emulate_render_model) return NULL;
+    if (!strcmp(name, "xrEnumerateRenderModelPathsFB")) return (PFN_xrVoidFunction)emu_enumerate_render_model_paths;
+    if (!strcmp(name, "xrGetRenderModelPropertiesFB")) return (PFN_xrVoidFunction)emu_get_render_model_properties;
+    if (!strcmp(name, "xrLoadRenderModelFB")) return (PFN_xrVoidFunction)emu_load_render_model;
+    return NULL;
+}
@@ -0,0 +1,313 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Included by frame_adapter.c. Per-game session fixes, all off by default (enabled in a game's recipe):
+//  * layer_debug: diagnostics only — layer/swapchain details, session-state timing, reference-space creation (and how
+//    far each new LOCAL space is from the session's first one), aim vs grip poses, refresh-rate calls;
+//  * stable_local: every LOCAL reference space the app creates coincides with the one at session start (for runtimes
+//    that place each new LOCAL space at the current head yaw, which makes menus jump to where you look);
+//  * focus_hold: hides brief FOCUSED -> VISIBLE -> (SYNCHRONIZED) dips once the session has been focused for a while
+//    (apps that recentre on regaining focus);
+//  * aim_pitch / aim_yaw / aim_forward: correct the aim pose of controllers (pointer rays) by a fixed offset;
+//  * refresh_rate: display refresh rate requested at session start (and instead of the app's own requests).
+#include "layer_math.h"
+
+static void emul_on_begin_session(const XrSessionBeginInfo *info);  // layer_emul_gl.c
+
+static int64_t monotonic_ns(void) {
+    struct timespec now;
+    clock_gettime(CLOCK_MONOTONIC, &now);
+    return (int64_t)now.tv_sec * 1000000000ll + now.tv_nsec;
+}
+
+// ---------------------------------------------------------------- stable_local
+static XrSpace local_anchor = XR_NULL_HANDLE;  // private LOCAL space created right after xrCreateSession
+static int local_anchor_stale;                 // runtime announced a LOCAL change (user recentre): re-anchor
+static XrSpace debug_first_local = XR_NULL_HANDLE;  // layer_debug: first LOCAL space, to measure later ones against
+
+static XrSpace create_local(XrSession session) {
+    PFN_xrCreateReferenceSpace create = (PFN_xrCreateReferenceSpace)lookup(active_instance, "xrCreateReferenceSpace");
+    XrReferenceSpaceCreateInfo ci = {XR_TYPE_REFERENCE_SPACE_CREATE_INFO, NULL, XR_REFERENCE_SPACE_TYPE_LOCAL,
+                                     {{0, 0, 0, 1}, {0, 0, 0}}};
+    XrSpace space = XR_NULL_HANDLE;
+    if (!create || XR_FAILED(create(session, &ci, &space))) return XR_NULL_HANDLE;
+    return space;
+}
+
+static void destroy_space(XrSpace space) {
+    PFN_xrDestroySpace destroy = (PFN_xrDestroySpace)lookup(active_instance, "xrDestroySpace");
+    if (destroy && space) destroy(space);
+}
+
+// Pose of `space` in `base` at the latest predicted display time; 0 if not (yet) known.
+static int locate_pose(XrSpace space, XrSpace base, XrPosef *pose) {
+    PFN_xrLocateSpace locate = (PFN_xrLocateSpace)lookup(active_instance, "xrLocateSpace");
+    if (!locate || !space || !base || !last_predicted_time) return 0;
+    XrSpaceLocation loc = {XR_TYPE_SPACE_LOCATION, NULL, 0, {{0, 0, 0, 1}, {0, 0, 0}}};
+    if (XR_FAILED(locate(space, base, last_predicted_time, &loc))) return 0;
+    const XrSpaceLocationFlags valid = XR_SPACE_LOCATION_ORIENTATION_VALID_BIT | XR_SPACE_LOCATION_POSITION_VALID_BIT;
+    if ((loc.locationFlags & valid) != valid) return 0;
+    *pose = loc.pose;
+    return 1;
+}
+
+static void session_fixes_on_create_session(XrSession session) {
+    if (stable_local) {
+        local_anchor = create_local(session);
+        LOG("stable_local: session anchor %s", local_anchor ? "created" : "FAILED");
+    }
+}
+
+// The pose to create an app LOCAL space with, so that it coincides with the session-start LOCAL space.
+static XrPosef stable_local_pose(XrSession session, XrPosef app_pose) {
+    if (!local_anchor) return app_pose;
+    XrSpace fresh = create_local(session);
+    if (!fresh) return app_pose;
+    XrPosef anchor_in_fresh;
+    int known = locate_pose(local_anchor, fresh, &anchor_in_fresh);
+    if (known && local_anchor_stale) {  // the user recentred: from now on the new LOCAL origin is the anchor
+        destroy_space(local_anchor);
+        local_anchor = fresh;
+        local_anchor_stale = 0;
+        LOG("stable_local: re-anchored after a runtime recentre");
+        return app_pose;
+    }
+    destroy_space(fresh);
+    if (!known) return app_pose;
+    float moved = lm_length(anchor_in_fresh.position), turned = lm_angle(anchor_in_fresh.orientation);
+    if (moved < 0.01f && turned < 0.01f) return app_pose;  // runtime kept LOCAL stable: nothing to correct
+    LOG("stable_local: new LOCAL space is %.3f m / %.1f deg from the session's, compensating", moved,
+        turned * 180 / LM_PI);
+    return lm_pose_mul(anchor_in_fresh, app_pose);
+}
+
+static void debug_reference_space(XrSession session, const XrReferenceSpaceCreateInfo *info, XrSpace space) {
+    const XrPosef *p = &info->poseInReferenceSpace;
+    LOG("layer_debug: space created type=%d space=%p pose=(%.3f,%.3f,%.3f | %.3f,%.3f,%.3f,%.3f) t=%.3f",
+        info->referenceSpaceType, (void *)(uintptr_t)space, p->position.x, p->position.y, p->position.z,
+        p->orientation.x, p->orientation.y, p->orientation.z, p->orientation.w, monotonic_ns() / 1e9);
+    if (info->referenceSpaceType != XR_REFERENCE_SPACE_TYPE_LOCAL) return;
+    if (!debug_first_local) { debug_first_local = create_local(session); return; }
+    XrPosef rel;
+    if (locate_pose(space, debug_first_local, &rel))
+        LOG("layer_debug: that LOCAL space sits at %.3f m / %.1f deg (yaw %.1f) from the session's first LOCAL space",
+            lm_length(rel.position), lm_angle(rel.orientation) * 180 / LM_PI,
+            2 * atan2f(rel.orientation.y, rel.orientation.w) * 180 / LM_PI);
+    else
+        LOG("layer_debug: that LOCAL space can't be located yet (no tracking)");
+}
+
+// ---------------------------------------------------------------- focus_hold
+#define FOCUS_HOLD_MIN_FOCUSED_NS 3000000000ll  // only after this long in FOCUSED (start-up transitions untouched)
+#define FOCUS_HOLD_MAX_DIP_NS 600000000ll       // dips longer than this are delivered (late, in order)
+static struct {
+    XrEventDataBuffer events[6];
+    int count, holding, delivering;
+    int64_t since;
+} held;
+static int is_focused;
+static int64_t focused_since;
+
+static int session_state_of(const XrEventDataBuffer *event) {
+    return event->type == XR_TYPE_EVENT_DATA_SESSION_STATE_CHANGED ? (int)((const XrEventDataSessionStateChanged *)event)->state : -1;
+}
+
+static void focus_hold_note(int state) {
+    if (state == XR_SESSION_STATE_FOCUSED && !is_focused) { is_focused = 1; focused_since = monotonic_ns(); }
+    else if (state >= 0 && state != XR_SESSION_STATE_FOCUSED) is_focused = 0;
+}
+
+static XrResult focus_hold_poll(PFN_xrPollEvent fn, XrInstance instance, XrEventDataBuffer *event) {
+    for (;;) {
+        if (held.delivering) {  // hand held events to the app, oldest first
+            if (held.count) {
+                *event = held.events[0];
+                memmove(&held.events[0], &held.events[1], (size_t)--held.count * sizeof(held.events[0]));
+                focus_hold_note(session_state_of(event));
+                return XR_SUCCESS;
+            }
+            held.delivering = 0;
+        }
+        XrResult result = fn(instance, event);
+        int64_t now = monotonic_ns();
+        if (result != XR_SUCCESS) {
+            if (held.holding && now - held.since > FOCUS_HOLD_MAX_DIP_NS) {
+                LOG("focus_hold: focus lost for > %lld ms, delivering %d state change(s)",
+                    FOCUS_HOLD_MAX_DIP_NS / 1000000, held.count);
+                held.holding = 0; held.delivering = 1;
+                continue;
+            }
+            return result;
+        }
+        int state = session_state_of(event);
+        if (state < 0) return result;  // other events pass straight through
+        if (held.holding) {
+            if (state == XR_SESSION_STATE_FOCUSED) {
+                LOG("focus_hold: hid a %.0f ms focus dip (%d state change(s))", (now - held.since) / 1e6, held.count);
+                held.count = 0; held.holding = 0;
+                continue;  // the app never saw it leave FOCUSED
+            }
+            if (held.count < 6) held.events[held.count++] = *event;
+            if (state != XR_SESSION_STATE_VISIBLE && state != XR_SESSION_STATE_SYNCHRONIZED) {
+                held.holding = 0; held.delivering = 1;  // stopping, loss pending, exiting: deliver everything now
+            }
+            continue;
+        }
+        if (state == XR_SESSION_STATE_VISIBLE && is_focused && now - focused_since >= FOCUS_HOLD_MIN_FOCUSED_NS) {
+            held.holding = 1; held.since = now; held.count = 0;
+            held.events[held.count++] = *event;
+            continue;
+        }
+        focus_hold_note(state);
+        return result;
+    }
+}
+
+// ---------------------------------------------------------------- aim pose correction + aim/grip diagnostics
+#define MAX_POSE_ACTIONS 64
+static struct { XrAction action; int aim; } pose_actions[MAX_POSE_ACTIONS];
+static int pose_action_count;
+static struct { XrSpace space; XrPath subaction; int aim; } pose_spaces[MAX_POSE_ACTIONS];
+static int pose_space_count;
+static pthread_mutex_t pose_lock = PTHREAD_MUTEX_INITIALIZER;
+
+static int aim_correction_on(void) { return aim_pitch != 0 || aim_yaw != 0 || aim_forward != 0; }
+
+static void note_pose_binding(XrAction action, const char *path) {
+    size_t n = strlen(path);
+    int aim = n >= 9 && !strcmp(path + n - 9, "/aim/pose");
+    int grip = n >= 10 && !strcmp(path + n - 10, "/grip/pose");
+    if (!aim && !grip) return;
+    pthread_mutex_lock(&pose_lock);
+    int known = 0;
+    for (int i = 0; i < pose_action_count; ++i) known |= pose_actions[i].action == action;
+    if (!known && pose_action_count < MAX_POSE_ACTIONS) {
+        pose_actions[pose_action_count].action = action;
+        pose_actions[pose_action_count++].aim = aim;
+    }
+    pthread_mutex_unlock(&pose_lock);
+}
+
+static int pose_action_kind(XrAction action) {  // 1 aim, 0 grip, -1 unknown
+    int kind = -1;
+    pthread_mutex_lock(&pose_lock);
+    for (int i = 0; i < pose_action_count && kind < 0; ++i)
+        if (pose_actions[i].action == action) kind = pose_actions[i].aim;
+    pthread_mutex_unlock(&pose_lock);
+    return kind;
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL hook_xrSuggestInteractionProfileBindings(XrInstance instance,
+        const XrInteractionProfileSuggestedBinding *suggested) {
+    PFN_xrSuggestInteractionProfileBindings fn =
+        (PFN_xrSuggestInteractionProfileBindings)lookup(instance, "xrSuggestInteractionProfileBindings");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    PFN_xrPathToString to_string = (PFN_xrPathToString)lookup(instance, "xrPathToString");
+    if (suggested && to_string)
+        for (uint32_t i = 0; i < suggested->countSuggestedBindings; ++i) {
+            char path[XR_MAX_PATH_LENGTH];
+            uint32_t size = 0;
+            if (XR_SUCCEEDED(to_string(instance, suggested->suggestedBindings[i].binding, sizeof(path), &size, path)))
+                note_pose_binding(suggested->suggestedBindings[i].action, path);
+        }
+    return fn(instance, suggested);
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL hook_xrCreateActionSpace(XrSession session, const XrActionSpaceCreateInfo *info,
+        XrSpace *space) {
+    PFN_xrCreateActionSpace fn = (PFN_xrCreateActionSpace)lookup(active_instance, "xrCreateActionSpace");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (!info) return fn(session, info, space);
+    int kind = pose_action_kind(info->action);
+    XrActionSpaceCreateInfo fixed = *info;
+    if (kind == 1 && aim_correction_on()) {
+        XrQuaternionf q = lm_qmul(lm_axis_angle(0, 1, 0, aim_yaw * LM_PI / 180), lm_axis_angle(1, 0, 0, aim_pitch * LM_PI / 180));
+        XrPosef correction = {q, {0, 0, -aim_forward}};
+        fixed.poseInActionSpace = lm_pose_mul(correction, info->poseInActionSpace);
+        static int logged;
+        if (logged++ < 4) LOG("aim correction: pitch %.1f deg, yaw %.1f deg, forward %.3f m", aim_pitch, aim_yaw, aim_forward);
+    }
+    XrResult result = fn(session, &fixed, space);
+    if (layer_debug && XR_SUCCEEDED(result) && space && kind >= 0) {
+        pthread_mutex_lock(&pose_lock);
+        if (pose_space_count < MAX_POSE_ACTIONS) {
+            pose_spaces[pose_space_count].space = *space;
+            pose_spaces[pose_space_count].subaction = info->subactionPath;
+            pose_spaces[pose_space_count++].aim = kind;
+        }
+        pthread_mutex_unlock(&pose_lock);
+        LOG("layer_debug: %s action space %p (subaction %llu)", kind ? "aim" : "grip", (void *)(uintptr_t)*space,
+            (unsigned long long)info->subactionPath);
+    }
+    return result;
+}
+
+// layer_debug: about once a second, the aim pose of each hand expressed in its grip pose.
+static void debug_aim_vs_grip(XrTime time) {
+    static int64_t last;
+    int64_t now = monotonic_ns();
+    if (!layer_debug || !time || now - last < 1000000000ll) return;
+    last = now;
+    PFN_xrLocateSpace locate = (PFN_xrLocateSpace)lookup(active_instance, "xrLocateSpace");
+    if (!locate) return;
+    pthread_mutex_lock(&pose_lock);
+    for (int a = 0; a < pose_space_count; ++a) {
+        if (!pose_spaces[a].aim) continue;
+        for (int g = 0; g < pose_space_count; ++g) {
+            if (pose_spaces[g].aim || pose_spaces[g].subaction != pose_spaces[a].subaction) continue;
+            XrSpaceLocation loc = {XR_TYPE_SPACE_LOCATION, NULL, 0, {{0, 0, 0, 1}, {0, 0, 0}}};
+            if (XR_SUCCEEDED(locate(pose_spaces[a].space, pose_spaces[g].space, time, &loc)) &&
+                (loc.locationFlags & XR_SPACE_LOCATION_ORIENTATION_VALID_BIT)) {
+                XrQuaternionf q = loc.pose.orientation;
+                float pitch = asinf(fmaxf(-1, fminf(1, 2 * (q.w * q.x - q.y * q.z)))) * 180 / LM_PI;
+                float yaw = atan2f(2 * (q.w * q.y + q.x * q.z), 1 - 2 * (q.x * q.x + q.y * q.y)) * 180 / LM_PI;
+                LOG("layer_debug: aim in grip (subaction %llu): pos %.3f,%.3f,%.3f pitch %.1f yaw %.1f flags 0x%llx",
+                    (unsigned long long)pose_spaces[a].subaction, loc.pose.position.x, loc.pose.position.y,
+                    loc.pose.position.z, pitch, yaw, (unsigned long long)loc.locationFlags);
+            }
+            break;
+        }
+    }
+    pthread_mutex_unlock(&pose_lock);
+}
+
+// ---------------------------------------------------------------- refresh rate
+static void debug_refresh_rates(XrSession session) {
+    PFN_xrEnumerateDisplayRefreshRatesFB enumerate =
+        (PFN_xrEnumerateDisplayRefreshRatesFB)lookup(active_instance, "xrEnumerateDisplayRefreshRatesFB");
+    PFN_xrGetDisplayRefreshRateFB get = (PFN_xrGetDisplayRefreshRateFB)lookup(active_instance, "xrGetDisplayRefreshRateFB");
+    float rates[32], current = 0;
+    uint32_t n = 0;
+    char text[256] = "";
+    if (enumerate && XR_SUCCEEDED(enumerate(session, 32, &n, rates)))
+        for (uint32_t i = 0, used = 0; i < n && i < 32 && used < sizeof(text) - 8; ++i)
+            used += (uint32_t)snprintf(text + used, sizeof(text) - used, " %.0f", rates[i]);
+    if (get) get(session, &current);
+    LOG("layer_debug: refresh rates offered:%s; current %.1f Hz", *text ? text : " (unknown)", current);
+}
+
+static void refresh_on_begin_session(XrSession session) {
+    if (layer_debug) debug_refresh_rates(session);
+    if (refresh_rate <= 0) return;
+    PFN_xrRequestDisplayRefreshRateFB request =
+        (PFN_xrRequestDisplayRefreshRateFB)lookup(active_instance, "xrRequestDisplayRefreshRateFB");
+    XrResult result = request ? request(session, refresh_rate) : XR_ERROR_FUNCTION_UNSUPPORTED;
+    LOG("refresh_rate: requested %.1f Hz at session start: result %d", refresh_rate, result);
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL hook_request_refresh_rate(XrSession session, float rate) {
+    PFN_xrRequestDisplayRefreshRateFB fn =
+        (PFN_xrRequestDisplayRefreshRateFB)lookup(active_instance, "xrRequestDisplayRefreshRateFB");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    float wanted = refresh_rate > 0 ? refresh_rate : rate;
+    XrResult result = fn(session, wanted);
+    LOG("refresh rate: app asked for %.1f Hz, requested %.1f Hz: result %d", rate, wanted, result);
+    // A refused override keeps the current rate (as frame-control's compat layer does) instead of failing the app.
+    return XR_FAILED(result) && refresh_rate > 0 ? XR_SUCCESS : result;
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL hook_xrBeginSession(XrSession session, const XrSessionBeginInfo *info) {
+    PFN_xrBeginSession fn = (PFN_xrBeginSession)lookup(active_instance, "xrBeginSession");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    XrResult result = fn(session, info);
+    if (XR_SUCCEEDED(result)) { emul_on_begin_session(info); refresh_on_begin_session(session); }
+    return result;
+}
@@ -5,10 +5,12 @@ Everything is fetched on demand into native/.cache (git-ignored):
  - Android NDK r27c (27.2.12479018) from Google's repository (checksummed via repository2-3.xml)
  - OpenXR headers at the commits each component was written against (KhronosGroup/OpenXR-SDK)
  - Temurin JDK 21 (javac) and Android build-tools (d8) for the Java stub classes
-Then builds: FrameBridge adapter (arm64 + arm32), VrApi bridge, platform compat, GL shim, oculusos stub dex, and
+Then builds: FrameBridge adapter (arm64 + arm32), VrApi bridge, platform compat, GL shim, oculusos stub dex, the
+timefix OpenXR layer for Proton games (linux-arm64, glibc; the NDK's clang builds it freestanding), the
+OculusHMDConnected helper for Rift games under Proton (win-x64 PE; the NDK's clang + lld-link, no Windows SDK), and
 rewrites artifacts/SHA256SUMS. Run `frameport parity` afterwards to see which games change.

-    python native/build.py [--only adapter,bridge,compat,glshim,dex] [--ndk PATH]
+    python native/build.py [--only adapter,bridge,compat,glshim,dex,xrlayer,oculushmd,xrshim,vkshim,vrsettings] [--ndk PATH]
 """
 from __future__ import annotations

@@ -34,8 +36,9 @@ REPO = "https://dl.google.com/android/repository/"
 OPENXR = {  # component -> OpenXR-SDK commit its headers came from
    "adapter": "f2448a8797c85814aa892efc1ab8707900fbcc78",
    "bridge": "7f9285bce1ce8b69bb75554bf788666579d0c35e",
+    "xrlayer": "f2448a8797c85814aa892efc1ab8707900fbcc78",
 }
-OPENXR_HEADERS = ("openxr.h", "openxr_platform.h", "openxr_platform_defines.h")
+OPENXR_HEADERS = ("openxr.h", "openxr_platform.h", "openxr_platform_defines.h", "openxr_loader_negotiation.h")


 def log(msg):
@@ -81,13 +84,29 @@ def ndk(explicit: str | None) -> Path:
        with zipfile.ZipFile(z) as zf:
            zf.extractall(CACHE / "ndk-extract")
        top = next((CACHE / "ndk-extract").iterdir())
-        top.rename(dest)
+        shutil.move(str(top), str(dest))  # (a plain rename can fail on NTFS while the folder is being scanned)
        shutil.rmtree(CACHE / "ndk-extract", ignore_errors=True)
+        restore_symlinks(z, dest)
        for p in (dest / "toolchains/llvm/prebuilt").rglob("bin/*"):
            p.chmod(0o755)
    return dest


+def restore_symlinks(archive: Path, dest: Path) -> None:
+    """zipfile writes symlinks (clang -> clang-18, ...) as small text files; replace them with copies of their
+    targets (copies also work on filesystems without symlinks)."""
+    with zipfile.ZipFile(archive) as zf:
+        links = [i for i in zf.infolist() if (i.external_attr >> 16) & 0o170000 == 0o120000]
+        for _ in range(3):  # links to links
+            for info in links:
+                rel = Path(*Path(info.filename).parts[1:])
+                path = dest / rel
+                target = (path.parent / zf.read(info).decode()).resolve()
+                if target.is_file() and (not path.exists() or path.stat().st_size < 256):
+                    path.unlink(missing_ok=True)
+                    shutil.copy2(target, path)
+
+
 def clang_dir(ndk_root: Path) -> Path:
    host = {"Linux": "linux-x86_64", "Darwin": "darwin-x86_64", "Windows": "windows-x86_64"}[platform.system()]
    return ndk_root / "toolchains/llvm/prebuilt" / host
@@ -119,11 +138,69 @@ def build_adapter(tc: Path):
    common = ["-shared", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror", "-Wno-gnu-conditional-omitted-operand",
              "-Wno-missing-field-initializers", "-Wl,-Bsymbolic", "-Wl,-soname,libopenxr_loader_generic.so", "-I", inc]
    run([exe(tc, "aarch64-linux-android29-clang"), *common, "-Wl,-z,max-page-size=16384", "frame_adapter.c", "forwarders.S",
-         "-ldl", "-llog", "-o", ART / "arm64-v8a/libopenxr_loader_generic.so"], cwd=src)
-    run([exe(tc, "armv7a-linux-androideabi29-clang"), *common, "frame_adapter.c", "forwarders_arm32.S", "-ldl", "-llog",
+         "-ldl", "-llog", "-lm", "-o", ART / "arm64-v8a/libopenxr_loader_generic.so"], cwd=src)
+    run([exe(tc, "armv7a-linux-androideabi29-clang"), *common, "frame_adapter.c", "forwarders_arm32.S", "-ldl", "-llog", "-lm",
         "-o", ART / "armeabi-v7a/libopenxr_loader_generic.so"], cwd=src)


+def build_xrlayer(tc: Path):
+    """OpenXR API layer for Linux aarch64 (glibc), loaded by Proton's wineopenxr host loader on the Frame. Freestanding:
+    no libc headers or link-time libs; clock_gettime binds to the process's libc at load time."""
+    src = HERE / "xrlayer"
+    inc = openxr_include("xrlayer")
+    out = ART / "linux-arm64"
+    out.mkdir(parents=True, exist_ok=True)
+    run([tc / "bin/clang", "--target=aarch64-linux-gnu", "-ffreestanding", "-nostdlibinc", "-fno-stack-protector",
+         "-fvisibility=hidden", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror", "-I", src / "include", "-I", inc,
+         f"-ffile-prefix-map={HERE}=native", "-shared", "-nostdlib", "-fuse-ld=lld", "-Wl,--build-id=none",
+         "-Wl,-z,max-page-size=65536", "-Wl,--hash-style=both", "-Wl,-soname,libxr_frameport_timefix.so",
+         "timefix_layer.c", "-o", out / "libxr_frameport_timefix.so"], cwd=src)
+    shutil.copy(src / "XR_APILAYER_FRAMEPORT_timefix.json", out / "XR_APILAYER_FRAMEPORT_timefix.json")
+
+
+OCULUSHMD_IMPORTS = ("CreateEventW", "CreateJobObjectW", "AssignProcessToJobObject", "QueryInformationJobObject",
+                     "CreateProcessW", "ResumeThread", "WaitForSingleObject", "GetExitCodeProcess", "CloseHandle",
+                     "Sleep", "GetCommandLineW", "GetLastError", "GetStdHandle", "WriteFile", "ExitProcess")
+
+
+def build_oculushmd(tc: Path, out: Path | None = None, defines=()):
+    """fp_oculushmd.exe (Windows x64, run by Proton on the Frame): provides the OculusHMDConnected event for Unreal
+    Rift games. Freestanding: no CRT; the kernel32 import library is generated from a .def by llvm-dlltool."""
+    src = HERE / "oculushmd"
+    out = out or ART / "win-x64"
+    out.mkdir(parents=True, exist_ok=True)
+    work = CACHE / "oculushmd"
+    work.mkdir(parents=True, exist_ok=True)
+    (work / "kernel32.def").write_text("LIBRARY kernel32.dll\nEXPORTS\n" + "".join(f"    {n}\n" for n in OCULUSHMD_IMPORTS))
+    run([tc / "bin/llvm-dlltool", "-m", "i386:x86-64", "-d", work / "kernel32.def", "-l", work / "kernel32.lib"])
+    run([tc / "bin/clang", "--target=x86_64-pc-windows-msvc", "-ffreestanding", "-nostdlibinc", "-fno-stack-protector",
+         "-fno-builtin", "-O2", "-Wall", "-Wextra", "-Werror", f"-ffile-prefix-map={HERE}=native", *defines, "-c",
+         "fp_oculushmd.c", "-o", work / "fp_oculushmd.obj"], cwd=src)
+    run([tc / "bin/lld-link", "/nologo", "/Brepro", "/nodefaultlib", "/entry:start", "/subsystem:console",
+         "/dynamicbase", "/highentropyva", "/nxcompat", work / "fp_oculushmd.obj", work / "kernel32.lib",
+         f"/out:{out / 'fp_oculushmd.exe'}"])
+
+
+VRSETTINGS_IMPORTS = ("LoadLibraryA", "GetProcAddress", "GetCommandLineA", "GetStdHandle", "WriteFile", "ExitProcess")
+
+
+def build_vrsettings(tc: Path):
+    """fp_vrsettings.exe (Windows x64, run on the PC): SteamVR settings through OpenVR's IVRSettings (see the source)."""
+    src = HERE / "vrsettings"
+    out = ART / "win-x64"
+    out.mkdir(parents=True, exist_ok=True)
+    work = CACHE / "vrsettings"
+    work.mkdir(parents=True, exist_ok=True)
+    (work / "kernel32.def").write_text("LIBRARY kernel32.dll\nEXPORTS\n" + "".join(f"    {n}\n" for n in VRSETTINGS_IMPORTS))
+    run([tc / "bin/llvm-dlltool", "-m", "i386:x86-64", "-d", work / "kernel32.def", "-l", work / "kernel32.lib"])
+    run([tc / "bin/clang", "--target=x86_64-pc-windows-msvc", "-ffreestanding", "-nostdlibinc", "-fno-stack-protector",
+         "-fno-builtin", "-O2", "-Wall", "-Wextra", "-Werror", f"-ffile-prefix-map={HERE}=native", "-c",
+         "fp_vrsettings.c", "-o", work / "fp_vrsettings.obj"], cwd=src)
+    run([tc / "bin/lld-link", "/nologo", "/Brepro", "/nodefaultlib", "/entry:start", "/subsystem:console",
+         "/dynamicbase", "/highentropyva", "/nxcompat", work / "fp_vrsettings.obj", work / "kernel32.lib",
+         f"/out:{out / 'fp_vrsettings.exe'}"])
+
+
 def build_bridge(tc: Path):
    src = HERE / "vrapi-bridge"
    inc = openxr_include("bridge")
@@ -153,6 +230,23 @@ def build_glshim(tc: Path):
         "-Wl,-z,max-page-size=16384", "glshim.c", "-ldl", "-llog", "-o", ART / "arm64-v8a/libglshim.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"
+    run([exe(tc, "aarch64-linux-android29-clang"), "-shared", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror",
+         "-fvisibility=hidden", "-I", openxr_include("adapter"), "-Wl,-soname,libframe_xrshim.so",
+         "-Wl,-z,max-page-size=16384", "xrshim.c", "-ldl", "-llog", "-o", ART / "arm64-v8a/libframe_xrshim.so"], cwd=src)
+
+
+def build_vkshim(tc: Path):
+    """Vulkan shim (see vkshim/vkshim.c): the engine's dlopen("libvulkan.so") string is pointed at it."""
+    src = HERE / "vkshim"
+    run([exe(tc, "aarch64-linux-android29-clang"), "-shared", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror",
+         "-fvisibility=hidden", "-Wl,-soname,libfp_vk.so", "-Wl,-z,max-page-size=16384", "vkshim.c",
+         "-Wl,--no-as-needed", "-lvulkan", "-Wl,--as-needed", "-ldl", "-llog", "-o", ART / "arm64-v8a/libfp_vk.so"],
+        cwd=src)
+
+
 def build_dex():
    javac = shutil.which("javac")
    if not javac:
@@ -197,7 +291,7 @@ def write_sums():

 def main():
    ap = argparse.ArgumentParser()
-    ap.add_argument("--only", default="adapter,bridge,compat,glshim,dex")
+    ap.add_argument("--only", default="adapter,bridge,compat,glshim,dex,xrlayer,oculushmd,xrshim,vkshim,vrsettings")
    ap.add_argument("--ndk")
    args = ap.parse_args()
    parts = set(args.only.split(","))
@@ -205,8 +299,10 @@ def main():
        (ART / d).mkdir(parents=True, exist_ok=True)
    tc = clang_dir(ndk(args.ndk)) if parts - {"dex"} else None
    steps = {"adapter": lambda: build_adapter(tc), "bridge": lambda: build_bridge(tc), "compat": lambda: build_compat(tc),
-             "glshim": lambda: build_glshim(tc), "dex": build_dex}
-    for name in ("adapter", "bridge", "compat", "glshim", "dex"):
+             "glshim": lambda: build_glshim(tc), "xrshim": lambda: build_xrshim(tc), "dex": build_dex, "xrlayer": lambda: build_xrlayer(tc),
+             "oculushmd": lambda: build_oculushmd(tc), "vkshim": lambda: build_vkshim(tc),
+             "vrsettings": lambda: build_vrsettings(tc)}
+    for name in ("adapter", "bridge", "compat", "glshim", "xrshim", "vkshim", "dex", "xrlayer", "oculushmd", "vrsettings"):
        if name in parts:
            log(f"build {name}")
            steps[name]()
@@ -0,0 +1,140 @@
+/* fp_oculushmd.exe — the PC VR counterpart of overport's patch_oculus_unreal, for Rift games under Proton on the Frame.
+ *
+ * Unreal's OculusVR plugin (and LibOVR's ovr_Detect) only start when the Windows named event "OculusHMDConnected"
+ * exists and is signalled; on a real PC the Oculus service creates it. Without it Unreal never loads OVRPlugin and the
+ * game runs as a flat window. Revive hooks OpenEventW for the same purpose, but that relies on Detours patching Wine's
+ * kernelbase, which is ARM64EC code under Proton arm64. This helper simply provides the real event:
+ *
+ *     fp_oculushmd.exe <command line to run>      (e.g. ReviveInjector.exe /openxr Z:\...\Game-Win64-Shipping.exe)
+ *
+ * It creates the event (manual reset, signalled), runs the command inside a job object and stays alive (keeping the
+ * event) until every process in the job has exited — ReviveInjector exits right after starting the game, the game
+ * and its children stay in the job. Returns the exit code of the command.
+ *
+ * Freestanding (no CRT, no Windows SDK headers): built by native/build.py with the NDK's clang + lld-link.
+ */
+typedef void *HANDLE;
+typedef unsigned long DWORD;
+typedef int BOOL;
+typedef unsigned short WORD;
+typedef unsigned short WCHAR;
+typedef long long LONGLONG;
+
+typedef struct {
+    DWORD cb;
+    WCHAR *lpReserved, *lpDesktop, *lpTitle;
+    DWORD dwX, dwY, dwXSize, dwYSize, dwXCountChars, dwYCountChars, dwFillAttribute, dwFlags;
+    WORD wShowWindow, cbReserved2;
+    unsigned char *lpReserved2;
+    HANDLE hStdInput, hStdOutput, hStdError;
+} STARTUPINFOW;
+
+typedef struct {
+    HANDLE hProcess, hThread;
+    DWORD dwProcessId, dwThreadId;
+} PROCESS_INFORMATION;
+
+typedef struct {
+    LONGLONG TotalUserTime, TotalKernelTime, ThisPeriodTotalUserTime, ThisPeriodTotalKernelTime;
+    DWORD TotalPageFaultCount, TotalProcesses, ActiveProcesses, TotalTerminatedProcesses;
+} JOBOBJECT_BASIC_ACCOUNTING_INFORMATION;
+
+#define WINAPI __attribute__((ms_abi))
+#define IMPORT __declspec(dllimport)
+IMPORT HANDLE WINAPI CreateEventW(void *, BOOL, BOOL, const WCHAR *);
+IMPORT HANDLE WINAPI CreateJobObjectW(void *, const WCHAR *);
+IMPORT BOOL WINAPI AssignProcessToJobObject(HANDLE, HANDLE);
+IMPORT BOOL WINAPI QueryInformationJobObject(HANDLE, int, void *, DWORD, DWORD *);
+IMPORT BOOL WINAPI CreateProcessW(const WCHAR *, WCHAR *, void *, void *, BOOL, DWORD, void *, const WCHAR *,
+                                  STARTUPINFOW *, PROCESS_INFORMATION *);
+IMPORT DWORD WINAPI ResumeThread(HANDLE);
+IMPORT DWORD WINAPI WaitForSingleObject(HANDLE, DWORD);
+IMPORT BOOL WINAPI GetExitCodeProcess(HANDLE, DWORD *);
+IMPORT BOOL WINAPI CloseHandle(HANDLE);
+IMPORT void WINAPI Sleep(DWORD);
+IMPORT WCHAR *WINAPI GetCommandLineW(void);
+IMPORT DWORD WINAPI GetLastError(void);
+IMPORT HANDLE WINAPI GetStdHandle(DWORD);
+IMPORT BOOL WINAPI WriteFile(HANDLE, const void *, DWORD, DWORD *, void *);
+IMPORT __attribute__((noreturn)) void WINAPI ExitProcess(unsigned);
+
+#define CREATE_SUSPENDED 0x4
+#define STD_ERROR_HANDLE ((DWORD)-12)
+#define JobObjectBasicAccountingInformation 1
+#ifndef EVENT_NAME /* overridable for tests on a PC where the Oculus service owns the real one */
+#define EVENT_NAME L"OculusHMDConnected"  /* OVR_HMD_CONNECTED_EVENT_NAME */
+#endif
+#define GRACE_MS 180000 /* no job tracking: keep the event this long after the command exits (Unreal checks at start) */
+
+static void say(const char *msg) {
+    DWORD n = 0, len = 0;
+    while (msg[len]) len++;
+    WriteFile(GetStdHandle(STD_ERROR_HANDLE), msg, len, &n, 0);
+}
+
+static void say_error(const char *msg) {  /* msg + " (error N)" */
+    char buf[16], *p = buf + sizeof buf;
+    DWORD e = GetLastError();
+    *--p = 0, *--p = '\n', *--p = ')';
+    do *--p = (char)('0' + e % 10); while (e /= 10);
+    say(msg);
+    say(" (error ");
+    say(p);
+}
+
+/* The command line after our own program name (quoted or not), without leading blanks. */
+static WCHAR *rest_of_command_line(WCHAR *p) {
+    if (*p == '"') {
+        for (p++; *p && *p != '"'; p++) {}
+        if (*p) p++;
+    } else {
+        while (*p && *p != ' ' && *p != '\t') p++;
+    }
+    while (*p == ' ' || *p == '\t') p++;
+    return p;
+}
+
+void start(void) {
+    WCHAR *cmd = rest_of_command_line(GetCommandLineW());
+    if (!*cmd) {
+        say("usage: fp_oculushmd.exe <command line>\n");
+        ExitProcess(2);
+    }
+    HANDLE event = CreateEventW(0, 1, 1, EVENT_NAME);
+    if (event)
+        say("FramePort oculushmd: OculusHMDConnected event ready\n");
+    else
+        say_error("FramePort oculushmd: could not create the OculusHMDConnected event");
+
+    static STARTUPINFOW si;  /* static: zeroed without memset */
+    static PROCESS_INFORMATION pi;
+    si.cb = sizeof si;
+    if (!CreateProcessW(0, cmd, 0, 0, 0, CREATE_SUSPENDED, 0, 0, &si, &pi)) {
+        say_error("FramePort oculushmd: could not start the command");
+        ExitProcess(1);
+    }
+    HANDLE job = CreateJobObjectW(0, 0);
+    BOOL tracked = job && AssignProcessToJobObject(job, pi.hProcess);
+    ResumeThread(pi.hThread);
+    CloseHandle(pi.hThread);
+    WaitForSingleObject(pi.hProcess, 0xFFFFFFFF);
+    DWORD code = 1;
+    GetExitCodeProcess(pi.hProcess, &code);
+    CloseHandle(pi.hProcess);
+
+    if (tracked) {  /* the game started by the command (and its children) are in the job too */
+        say("FramePort oculushmd: waiting for the game to exit\n");
+        for (;;) {
+            static JOBOBJECT_BASIC_ACCOUNTING_INFORMATION info;
+            if (!QueryInformationJobObject(job, JobObjectBasicAccountingInformation, &info, sizeof info, 0)
+                || info.ActiveProcesses == 0)
+                break;
+            Sleep(1000);
+        }
+    } else {
+        say("FramePort oculushmd: no job tracking; keeping the event for 3 minutes\n");
+        Sleep(GRACE_MS);
+    }
+    if (event) CloseHandle(event);
+    ExitProcess(code);
+}
@@ -0,0 +1,286 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// FramePort Vulkan shim: drops invalid pNext pointers from render-pass create infos before they reach the Vulkan
+// loader. Some engines (e.g. Unreal builds such as Deadpool VR) leave the pNext of unused attachment references
+// uninitialized. The Frame's driver never reads it, but Lepton always loads Steam's Fossilize layer, which records
+// every render pass, follows the garbage pointer and crashes (SIGSEGV in libVkLayer_fossilize.so).
+//
+// The engine finds Vulkan with dlopen("libvulkan.so") + dlsym, so FramePort points that string in the engine library
+// at this shim (patches/frame/vk_sanitize.py). dlsym on the shim finds the functions below first and every other
+// symbol in its dependency, the real libvulkan.so. Valid pointers are kept; a pointer is dropped only when it isn't
+// readable memory or doesn't point at a structure type the parent may chain.
+#define _GNU_SOURCE
+#include <vulkan/vulkan.h>
+#include <android/log.h>
+#include <dlfcn.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <pthread.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+#define TAG "FrameBridge"
+#define EXPORT __attribute__((visibility("default")))
+#define LOG(...) __android_log_print(ANDROID_LOG_INFO, TAG, __VA_ARGS__)
+
+static void *real_vk;
+static PFN_vkGetInstanceProcAddr real_gipa;
+static PFN_vkGetDeviceProcAddr real_gdpa;
+static PFN_vkCreateRenderPass2 real_rp2_trampoline;
+static pthread_once_t once = PTHREAD_ONCE_INIT;
+
+static void init(void) {
+    real_vk = dlopen("libvulkan.so", RTLD_NOW | RTLD_LOCAL);
+    if (real_vk) {
+        real_gipa = (PFN_vkGetInstanceProcAddr)dlsym(real_vk, "vkGetInstanceProcAddr");
+        real_gdpa = (PFN_vkGetDeviceProcAddr)dlsym(real_vk, "vkGetDeviceProcAddr");
+        real_rp2_trampoline = (PFN_vkCreateRenderPass2)dlsym(real_vk, "vkCreateRenderPass2");
+    }
+    LOG("vk shim: libvulkan.so %s", real_gipa && real_gdpa ? "OK" : "MISSING");
+}
+
+// ---------------------------------------------------------------- pointer checks
+
+static pthread_mutex_t probe_lock = PTHREAD_MUTEX_INITIALIZER;
+static int probe_fd[2] = {-1, -1};
+
+// readable(p, n): the kernel copies from p without faulting (write to a pipe fails with EFAULT otherwise)
+static int readable(const void *p, size_t n) {
+    if (!p || ((uintptr_t)p & 7)) return 0;
+    pthread_mutex_lock(&probe_lock);
+    if (probe_fd[0] < 0 && pipe2(probe_fd, O_CLOEXEC | O_NONBLOCK)) {
+        pthread_mutex_unlock(&probe_lock);
+        return 1;  // can't check: trust the pointer (the previous behaviour)
+    }
+    ssize_t w = write(probe_fd[1], p, n);
+    int ok = w == (ssize_t)n;
+    char sink[64];
+    while (w > 0) {
+        ssize_t r = read(probe_fd[0], sink, w < (ssize_t)sizeof sink ? (size_t)w : sizeof sink);
+        if (r <= 0) break;
+        w -= r;
+    }
+    pthread_mutex_unlock(&probe_lock);
+    return ok;
+}
+
+static int valid_next(const void *p, const VkStructureType *allowed, int n) {
+    if (!readable(p, sizeof(VkBaseInStructure))) return 0;
+    VkStructureType s = ((const VkBaseInStructure *)p)->sType;
+    for (int i = 0; i < n; i++)
+        if (allowed[i] == s) return 1;
+    return 0;
+}
+
+// ---------------------------------------------------------------- scratch memory for the cleaned copies
+
+typedef struct { void *blocks[64]; int n; } Arena;
+
+static void *arena_dup(Arena *a, const void *src, size_t size) {
+    if (a->n >= 64) return NULL;
+    void *p = malloc(size ? size : 1);
+    if (!p) return NULL;
+    memcpy(p, src, size);
+    a->blocks[a->n++] = p;
+    return p;
+}
+
+static void arena_free(Arena *a) {
+    for (int i = 0; i < a->n; i++) free(a->blocks[i]);
+    a->n = 0;
+}
+
+static int fixes_logged;
+
+static const VkStructureType REF_NEXT[] = {VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_STENCIL_LAYOUT};
+static const VkStructureType DESC_NEXT[] = {VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_STENCIL_LAYOUT};
+static const VkStructureType DEP_NEXT[] = {VK_STRUCTURE_TYPE_MEMORY_BARRIER_2};
+
+// A copy of `refs` whose pNext pointers are valid (or NULL); the original when nothing needed fixing.
+static const VkAttachmentReference2 *clean_refs(Arena *a, const VkAttachmentReference2 *refs, uint32_t count, int *fixes) {
+    if (!refs || !count) return refs;
+    VkAttachmentReference2 *copy = NULL;
+    for (uint32_t i = 0; i < count; i++) {
+        if (refs[i].pNext && !valid_next(refs[i].pNext, REF_NEXT, 1)) {
+            if (!copy && !(copy = arena_dup(a, refs, sizeof *refs * count))) return refs;
+            copy[i].pNext = NULL;
+            (*fixes)++;
+        }
+    }
+    return copy ? copy : refs;
+}
+
+// Structures that may be chained to a subpass or to the create info, with their size (so a chain can be cut after
+// them) and whether they hold an attachment reference to clean.
+static size_t chain_size(VkStructureType s) {
+    switch (s) {
+    case VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE: return sizeof(VkSubpassDescriptionDepthStencilResolve);
+    case VK_STRUCTURE_TYPE_FRAGMENT_SHADING_RATE_ATTACHMENT_INFO_KHR: return sizeof(VkFragmentShadingRateAttachmentInfoKHR);
+    case VK_STRUCTURE_TYPE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_INFO_EXT: return sizeof(VkMultisampledRenderToSingleSampledInfoEXT);
+    case VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_CREATE_INFO_EXT: return sizeof(VkRenderPassFragmentDensityMapCreateInfoEXT);
+    case VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO: return sizeof(VkRenderPassMultiviewCreateInfo);
+    case VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO: return sizeof(VkRenderPassInputAttachmentAspectCreateInfo);
+    case VK_STRUCTURE_TYPE_RENDER_PASS_CREATION_CONTROL_EXT: return sizeof(VkRenderPassCreationControlEXT);
+    case VK_STRUCTURE_TYPE_RENDER_PASS_CREATION_FEEDBACK_CREATE_INFO_EXT: return sizeof(VkRenderPassCreationFeedbackCreateInfoEXT);
+    case VK_STRUCTURE_TYPE_RENDER_PASS_SUBPASS_FEEDBACK_CREATE_INFO_EXT: return sizeof(VkRenderPassSubpassFeedbackCreateInfoEXT);
+    case VK_STRUCTURE_TYPE_RENDER_PASS_STRIPE_BEGIN_INFO_ARM: return 0;  // not a create-info chain member
+    default: return 0;
+    }
+}
+
+// Walk a pNext chain from `head` (the pNext value of a structure we own a copy of); returns the new head. Known
+// members are copied so a bad link after them can be cut; an unknown but valid member ends the checks (it can't be
+// copied without knowing its size, so what follows it stays as is).
+static const void *clean_chain(Arena *a, const void *head, int *fixes) {
+    const void *first = head;
+    VkBaseOutStructure *prev = NULL;  // our copy of the previous member
+    const void *cur = head;
+    while (cur) {
+        if (!readable(cur, sizeof(VkBaseInStructure))) {
+            if (prev) prev->pNext = NULL; else first = NULL;
+            (*fixes)++;
+            break;
+        }
+        VkStructureType s = ((const VkBaseInStructure *)cur)->sType;
+        size_t size = chain_size(s);
+        if (!size || !readable(cur, size)) {
+            if (!size && s < 1100000000u && (s < 1000u || s >= 1000000000u)) break;  // plausible unknown member: keep
+            if (prev) prev->pNext = NULL; else first = NULL;
+            (*fixes)++;
+            break;
+        }
+        VkBaseOutStructure *copy = arena_dup(a, cur, size);
+        if (!copy) break;
+        if (s == VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE) {
+            VkSubpassDescriptionDepthStencilResolve *r = (void *)copy;
+            r->pDepthStencilResolveAttachment = clean_refs(a, r->pDepthStencilResolveAttachment, 1, fixes);
+        } else if (s == VK_STRUCTURE_TYPE_FRAGMENT_SHADING_RATE_ATTACHMENT_INFO_KHR) {
+            VkFragmentShadingRateAttachmentInfoKHR *r = (void *)copy;
+            r->pFragmentShadingRateAttachment = clean_refs(a, r->pFragmentShadingRateAttachment, 1, fixes);
+        }
+        if (prev) prev->pNext = copy; else first = copy;
+        prev = copy;
+        cur = copy->pNext;
+    }
+    return first;
+}
+
+static VkRenderPassCreateInfo2 clean_create_info(Arena *a, const VkRenderPassCreateInfo2 *ci, int *fixes) {
+    VkRenderPassCreateInfo2 out = *ci;
+    out.pNext = clean_chain(a, ci->pNext, fixes);
+    if (ci->pAttachments && ci->attachmentCount) {
+        VkAttachmentDescription2 *d = arena_dup(a, ci->pAttachments, sizeof *d * ci->attachmentCount);
+        if (d) {
+            for (uint32_t i = 0; i < ci->attachmentCount; i++)
+                if (d[i].pNext && !valid_next(d[i].pNext, DESC_NEXT, 1)) { d[i].pNext = NULL; (*fixes)++; }
+            out.pAttachments = d;
+        }
+    }
+    if (ci->pSubpasses && ci->subpassCount) {
+        VkSubpassDescription2 *sp = arena_dup(a, ci->pSubpasses, sizeof *sp * ci->subpassCount);
+        if (sp) {
+            for (uint32_t i = 0; i < ci->subpassCount; i++) {
+                sp[i].pNext = clean_chain(a, sp[i].pNext, fixes);
+                sp[i].pInputAttachments = clean_refs(a, sp[i].pInputAttachments, sp[i].inputAttachmentCount, fixes);
+                sp[i].pColorAttachments = clean_refs(a, sp[i].pColorAttachments, sp[i].colorAttachmentCount, fixes);
+                sp[i].pResolveAttachments = clean_refs(a, sp[i].pResolveAttachments, sp[i].colorAttachmentCount, fixes);
+                sp[i].pDepthStencilAttachment = clean_refs(a, sp[i].pDepthStencilAttachment, 1, fixes);
+            }
+            out.pSubpasses = sp;
+        }
+    }
+    if (ci->pDependencies && ci->dependencyCount) {
+        VkSubpassDependency2 *dep = arena_dup(a, ci->pDependencies, sizeof *dep * ci->dependencyCount);
+        if (dep) {
+            for (uint32_t i = 0; i < ci->dependencyCount; i++)
+                if (dep[i].pNext && !valid_next(dep[i].pNext, DEP_NEXT, 1)) { dep[i].pNext = NULL; (*fixes)++; }
+            out.pDependencies = dep;
+        }
+    }
+    return out;
+}
+
+// ---------------------------------------------------------------- entry points
+
+#define MAX_DEVICES 8
+static struct { VkDevice device; PFN_vkCreateRenderPass2 rp2, rp2khr; } devices[MAX_DEVICES];
+static PFN_vkCreateRenderPass2 fallback_rp2khr;  // from vkGetInstanceProcAddr
+static pthread_mutex_t dev_lock = PTHREAD_MUTEX_INITIALIZER;
+
+static PFN_vkCreateRenderPass2 real_for(VkDevice device, int khr) {
+    PFN_vkCreateRenderPass2 fn = NULL;
+    pthread_mutex_lock(&dev_lock);
+    for (int i = 0; i < MAX_DEVICES; i++)
+        if (devices[i].device == device) { fn = khr ? devices[i].rp2khr : devices[i].rp2; break; }
+    pthread_mutex_unlock(&dev_lock);
+    if (!fn && real_gdpa) fn = (PFN_vkCreateRenderPass2)real_gdpa(device, khr ? "vkCreateRenderPass2KHR" : "vkCreateRenderPass2");
+    if (!fn) fn = khr ? fallback_rp2khr : real_rp2_trampoline;
+    return fn;
+}
+
+static VkResult create_render_pass2(VkDevice device, const VkRenderPassCreateInfo2 *ci, const VkAllocationCallbacks *alloc,
+                                    VkRenderPass *rp, int khr) {
+    PFN_vkCreateRenderPass2 real = real_for(device, khr);
+    if (!real) return VK_ERROR_INITIALIZATION_FAILED;
+    if (!ci) return real(device, ci, alloc, rp);
+    Arena a = {0};
+    int fixes = 0;
+    VkRenderPassCreateInfo2 clean = clean_create_info(&a, ci, &fixes);
+    if (fixes && fixes_logged < 5) {
+        fixes_logged++;
+        LOG("vk shim: dropped %d invalid pNext pointer(s) in vkCreateRenderPass2%s", fixes, khr ? "KHR" : "");
+    }
+    VkResult r = real(device, fixes ? &clean : ci, alloc, rp);
+    arena_free(&a);
+    return r;
+}
+
+EXPORT VKAPI_ATTR VkResult VKAPI_CALL vkCreateRenderPass2(VkDevice device, const VkRenderPassCreateInfo2 *ci,
+                                                          const VkAllocationCallbacks *alloc, VkRenderPass *rp) {
+    pthread_once(&once, init);
+    return create_render_pass2(device, ci, alloc, rp, 0);
+}
+
+static VKAPI_ATTR VkResult VKAPI_CALL create_render_pass2_khr(VkDevice device, const VkRenderPassCreateInfo2 *ci,
+                                                             const VkAllocationCallbacks *alloc, VkRenderPass *rp) {
+    return create_render_pass2(device, ci, alloc, rp, 1);
+}
+
+static PFN_vkVoidFunction wrap(const char *name) {
+    if (!strcmp(name, "vkCreateRenderPass2")) return (PFN_vkVoidFunction)vkCreateRenderPass2;
+    if (!strcmp(name, "vkCreateRenderPass2KHR")) return (PFN_vkVoidFunction)create_render_pass2_khr;
+    return NULL;
+}
+
+EXPORT VKAPI_ATTR PFN_vkVoidFunction VKAPI_CALL vkGetDeviceProcAddr(VkDevice device, const char *name) {
+    pthread_once(&once, init);
+    if (!real_gdpa || !name) return NULL;
+    PFN_vkVoidFunction fn = real_gdpa(device, name);
+    PFN_vkVoidFunction w = fn ? wrap(name) : NULL;
+    if (!w) return fn;
+    int khr = name[strlen(name) - 1] == 'R';
+    pthread_mutex_lock(&dev_lock);
+    int slot = -1;
+    for (int i = 0; i < MAX_DEVICES; i++) {
+        if (devices[i].device == device) { slot = i; break; }
+        if (slot < 0 && !devices[i].device) slot = i;
+    }
+    if (slot >= 0) {
+        devices[slot].device = device;
+        if (khr) devices[slot].rp2khr = (PFN_vkCreateRenderPass2)fn; else devices[slot].rp2 = (PFN_vkCreateRenderPass2)fn;
+    }
+    pthread_mutex_unlock(&dev_lock);
+    return w;
+}
+
+EXPORT VKAPI_ATTR PFN_vkVoidFunction VKAPI_CALL vkGetInstanceProcAddr(VkInstance instance, const char *name) {
+    pthread_once(&once, init);
+    if (!real_gipa || !name) return NULL;
+    if (!strcmp(name, "vkGetDeviceProcAddr")) return (PFN_vkVoidFunction)vkGetDeviceProcAddr;
+    if (!strcmp(name, "vkGetInstanceProcAddr")) return (PFN_vkVoidFunction)vkGetInstanceProcAddr;
+    PFN_vkVoidFunction fn = real_gipa(instance, name);
+    PFN_vkVoidFunction w = fn ? wrap(name) : NULL;
+    if (!w) return fn;
+    if (!strcmp(name, "vkCreateRenderPass2KHR")) fallback_rp2khr = (PFN_vkCreateRenderPass2)fn;
+    return w;
+}
@@ -0,0 +1,189 @@
+/* fp_vrsettings.exe — read/write SteamVR settings through OpenVR's IVRSettings (Windows x64, run on the PC).
+ *
+ * SteamVR keeps its settings in memory and rewrites steamvr.vrsettings on exit, so editing the file while SteamVR runs
+ * is lost. This helper connects as a utility application (no rendering, no hardware), which works whether SteamVR is
+ * running or not, and changes settings the supported way; SteamVR applies and persists them.
+ *
+ *     fp_vrsettings.exe <openvr_api.dll> (get|set) <section> <key> <b|i|f|s> [value] [(get|set) ...]
+ *
+ * Prints one line per operation: "ok <section> <key> <value>" or "error <section> <key> <SteamVR error>".
+ * Exit code 0 when every operation succeeded, 1 on an error, 2 on bad usage / OpenVR init failure.
+ * Freestanding (no CRT, no Windows SDK headers): built by native/build.py with the NDK's clang + lld-link.
+ */
+typedef void *HANDLE;
+typedef unsigned long DWORD;
+typedef int BOOL;
+
+#define WINAPI __attribute__((ms_abi))
+#define IMPORT __declspec(dllimport)
+IMPORT HANDLE WINAPI LoadLibraryA(const char *);
+IMPORT void *WINAPI GetProcAddress(HANDLE, const char *);
+IMPORT char *WINAPI GetCommandLineA(void);
+IMPORT HANDLE WINAPI GetStdHandle(DWORD);
+IMPORT BOOL WINAPI WriteFile(HANDLE, const void *, DWORD, DWORD *, void *);
+IMPORT __attribute__((noreturn)) void WINAPI ExitProcess(unsigned);
+
+#define STD_OUTPUT_HANDLE ((DWORD)-11)
+#define VRApplication_Utility 4
+int _fltused = 1; /* MSVC ABI marker the compiler emits for float code (normally from the CRT) */
+
+/* openvr_capi.h: struct VR_IVRSettings_FnTable (IVRSettings_003) */
+typedef int EVRSettingsError;
+typedef struct {
+    char *(*GetSettingsErrorNameFromEnum)(EVRSettingsError);
+    void (*SetBool)(const char *, const char *, int, EVRSettingsError *);
+    void (*SetInt32)(const char *, const char *, int, EVRSettingsError *);
+    void (*SetFloat)(const char *, const char *, float, EVRSettingsError *);
+    void (*SetString)(const char *, const char *, const char *, EVRSettingsError *);
+    int (*GetBool)(const char *, const char *, EVRSettingsError *);
+    int (*GetInt32)(const char *, const char *, EVRSettingsError *);
+    float (*GetFloat)(const char *, const char *, EVRSettingsError *);
+    void (*GetString)(const char *, const char *, char *, unsigned, EVRSettingsError *);
+    void (*RemoveSection)(const char *, EVRSettingsError *);
+    void (*RemoveKeyInSection)(const char *, const char *, EVRSettingsError *);
+} SettingsFnTable;
+
+typedef unsigned (*PFN_InitInternal2)(int *, int, const char *);
+typedef void (*PFN_ShutdownInternal)(void);
+typedef void *(*PFN_GetGenericInterface)(const char *, int *);
+
+static void out(const char *s) {
+    DWORD n = 0, len = 0;
+    while (s[len]) len++;
+    WriteFile(GetStdHandle(STD_OUTPUT_HANDLE), s, len, &n, 0);
+}
+
+static void out_int(long long v) {
+    char buf[24], *p = buf + sizeof buf;
+    int neg = v < 0;
+    unsigned long long u = neg ? (unsigned long long)-v : (unsigned long long)v;
+    *--p = 0;
+    do *--p = (char)('0' + u % 10); while (u /= 10);
+    if (neg) *--p = '-';
+    out(p);
+}
+
+static void out_float(float f) {  /* 3 decimals is plenty for refresh rates / scales */
+    long long milli = (long long)(f * 1000.0f + (f < 0 ? -0.5f : 0.5f));
+    if (milli < 0) { out("-"); milli = -milli; }
+    out_int(milli / 1000);
+    char frac[5] = {'.', (char)('0' + milli / 100 % 10), (char)('0' + milli / 10 % 10), (char)('0' + milli % 10), 0};
+    out(frac);
+}
+
+static long long parse_int(const char *s) {
+    long long v = 0;
+    int neg = *s == '-';
+    if (neg || *s == '+') s++;
+    while (*s >= '0' && *s <= '9') v = v * 10 + (*s++ - '0');
+    return neg ? -v : v;
+}
+
+static float parse_float(const char *s) {
+    int neg = *s == '-';
+    if (neg || *s == '+') s++;
+    float v = 0, scale = 1;
+    while (*s >= '0' && *s <= '9') v = v * 10 + (float)(*s++ - '0');
+    if (*s == '.')
+        for (s++; *s >= '0' && *s <= '9'; s++) v += (float)(*s - '0') * (scale /= 10);
+    return neg ? -v : v;
+}
+
+/* Split the command line in place into argv (double quotes group; no escapes needed for our arguments). */
+static int split(char *p, char **argv, int max) {
+    int n = 0;
+    while (*p && n < max) {
+        while (*p == ' ' || *p == '\t') p++;
+        if (!*p) break;
+        if (*p == '"') {
+            argv[n++] = ++p;
+            while (*p && *p != '"') p++;
+        } else {
+            argv[n++] = p;
+            while (*p && *p != ' ' && *p != '\t') p++;
+        }
+        if (*p) *p++ = 0;
+    }
+    return n;
+}
+
+static int streq(const char *a, const char *b) {
+    while (*a && *a == *b) a++, b++;
+    return *a == *b;
+}
+
+void start(void) {
+    static char *argv[128];
+    int argc = split(GetCommandLineA(), argv, 128);
+    if (argc < 6) {
+        out("usage: fp_vrsettings.exe <openvr_api.dll> (get|set) <section> <key> <b|i|f|s> [value] ...\n");
+        ExitProcess(2);
+    }
+    HANDLE lib = LoadLibraryA(argv[1]);
+    PFN_InitInternal2 init = lib ? (PFN_InitInternal2)GetProcAddress(lib, "VR_InitInternal2") : 0;
+    PFN_ShutdownInternal shutdown = lib ? (PFN_ShutdownInternal)GetProcAddress(lib, "VR_ShutdownInternal") : 0;
+    PFN_GetGenericInterface iface = lib ? (PFN_GetGenericInterface)GetProcAddress(lib, "VR_GetGenericInterface") : 0;
+    if (!init || !shutdown || !iface) {
+        out("error could not load openvr_api.dll\n");
+        ExitProcess(2);
+    }
+    int err = 0;
+    init(&err, VRApplication_Utility, 0);
+    if (err) {
+        out("error VR_Init failed: ");
+        out_int(err);
+        out("\n");
+        ExitProcess(2);
+    }
+    SettingsFnTable *s = (SettingsFnTable *)iface("FnTable:IVRSettings_003", &err);
+    if (!s || err) {
+        out("error no IVRSettings_003\n");
+        shutdown();
+        ExitProcess(2);
+    }
+    int failed = 0;
+    for (int i = 2; i + 3 < argc;) {
+        const char *op = argv[i], *section = argv[i + 1], *key = argv[i + 2], *type = argv[i + 3];
+        int set = streq(op, "set");
+        if (set && i + 4 >= argc) { out("error missing value\n"); failed = 1; break; }
+        const char *value = set ? argv[i + 4] : 0;
+        i += set ? 5 : 4;
+        EVRSettingsError e = 0;
+        char buf[512];
+        buf[0] = 0;
+        if (set) {
+            if (type[0] == 'b') s->SetBool(section, key, streq(value, "true") || streq(value, "1"), &e);
+            else if (type[0] == 'i') s->SetInt32(section, key, (int)parse_int(value), &e);
+            else if (type[0] == 'f') s->SetFloat(section, key, parse_float(value), &e);
+            else s->SetString(section, key, value, &e);
+        }
+        /* read back (also the result of "get") */
+        EVRSettingsError ge = 0;
+        long long iv = 0;
+        float fv = 0;
+        if (type[0] == 'b') iv = s->GetBool(section, key, &ge);
+        else if (type[0] == 'i') iv = s->GetInt32(section, key, &ge);
+        else if (type[0] == 'f') fv = s->GetFloat(section, key, &ge);
+        else s->GetString(section, key, buf, sizeof buf, &ge);
+        EVRSettingsError report = e ? e : ge;
+        out(report ? "error " : "ok ");
+        out(section);
+        out(" ");
+        out(key);
+        out(" ");
+        if (report) {
+            const char *name = s->GetSettingsErrorNameFromEnum(report);
+            out(name ? name : "?");
+            if (set || report != 5 /* UnsetSettingHasNoDefault: "get" of an unset key */) failed = 1;
+        } else if (type[0] == 'f') {
+            out_float(fv);
+        } else if (type[0] == 's') {
+            out(buf);
+        } else {
+            out_int(iv);
+        }
+        out("\n");
+    }
+    shutdown();
+    ExitProcess(failed);
+}
@@ -0,0 +1,11 @@
+{
+    "file_format_version": "1.0.0",
+    "api_layer": {
+        "name": "XR_APILAYER_FRAMEPORT_timefix",
+        "library_path": "./libxr_frameport_timefix.so",
+        "api_version": "1.0",
+        "implementation_version": "1",
+        "description": "FramePort: XR_KHR_convert_timespec_time emulation for Proton games on the Steam Frame",
+        "instance_extensions": [{"name": "XR_KHR_convert_timespec_time", "extension_version": "1"}]
+    }
+}
@@ -0,0 +1,7 @@
+/* Minimal <time.h> for the freestanding timefix layer (aarch64 Linux: time_t and long are 64-bit). The layer links
+ * against nothing at build time; clock_gettime resolves to the process's libc when the loader dlopens it. */
+#pragma once
+typedef long time_t;
+struct timespec { time_t tv_sec; long tv_nsec; };
+#define CLOCK_MONOTONIC 1
+int clock_gettime(int clock_id, struct timespec *ts);
@@ -0,0 +1,157 @@
+/* FramePort timefix: an OpenXR API layer for Windows PC VR games running under Proton on the Steam Frame.
+ *
+ * Proton's wineopenxr implements XR_KHR_win32_convert_performance_counter_time (required by Revive's OpenXR backend)
+ * on top of the host's XR_KHR_convert_timespec_time, but the Frame runtime returns XR_ERROR_FUNCTION_UNSUPPORTED for
+ * xrConvertTimespecTimeToTimeKHR / xrConvertTimeToTimespecTimeKHR. This layer supplies them with the same emulation
+ * the FrameBridge adapter uses for Quest games: XrTime = CLOCK_MONOTONIC + offset, where the offset is measured at
+ * every xrWaitFrame (predictedDisplayTime - predictedDisplayPeriod - now). The runtime's own functions are preferred
+ * whenever they work. The layer also advertises XR_KHR_convert_timespec_time (manifest) and removes it from
+ * xrCreateInstance if the runtime rejects it.
+ *
+ * OpenXR version fallback: the Frame's SteamVR runtime rejects apiVersion 1.1 with XR_ERROR_API_VERSION_UNSUPPORTED
+ * (checked 2026-09-29; 1.0 works), which is what Proton 11's VR helper requests, so VR never started for Proton games
+ * (flat window / "Unable to load LibOVRRT DLL" under Revive). The layer retries such a create as a 1.0 app.
+ *
+ * Enabled per game by FramePort's Proton launcher: XR_API_LAYER_PATH=<game>/xrlayer,
+ * XR_ENABLE_API_LAYERS=XR_APILAYER_FRAMEPORT_timefix. Built freestanding (see ../build.py).
+ */
+#define XR_USE_TIMESPEC 1
+#include <time.h>
+#include <openxr/openxr.h>
+#include <openxr/openxr_platform.h>
+#include <openxr/openxr_loader_negotiation.h>
+
+#define EXPORT __attribute__((visibility("default")))
+#define LAYER_NAME "XR_APILAYER_FRAMEPORT_timefix"
+#define TIMESPEC_EXT "XR_KHR_convert_timespec_time"
+#define MAX_EXTS 256
+
+static PFN_xrGetInstanceProcAddr next_gipa;
+static PFN_xrConvertTimespecTimeToTimeKHR runtime_timespec_to_time;
+static PFN_xrConvertTimeToTimespecTimeKHR runtime_time_to_timespec;
+static PFN_xrWaitFrame runtime_wait_frame;
+static volatile long long time_offset;
+static volatile int calibrated;
+
+static int str_eq(const char *a, const char *b) {
+    if (!a || !b) return 0;
+    while (*a && *a == *b) { ++a; ++b; }
+    return *a == *b;
+}
+
+static long long mono_ns(void) {
+    struct timespec now;
+    clock_gettime(CLOCK_MONOTONIC, &now);
+    return (long long)now.tv_sec * 1000000000ll + now.tv_nsec;
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL emu_timespec_to_time(XrInstance instance, const struct timespec *ts, XrTime *time) {
+    if (runtime_timespec_to_time) {
+        XrResult r = runtime_timespec_to_time(instance, ts, time);
+        if (r != XR_ERROR_FUNCTION_UNSUPPORTED) return r;
+    }
+    if (!ts || !time) return XR_ERROR_VALIDATION_FAILURE;
+    *time = (XrTime)((long long)ts->tv_sec * 1000000000ll + ts->tv_nsec + (calibrated ? time_offset : 0));
+    return XR_SUCCESS;
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL emu_time_to_timespec(XrInstance instance, XrTime time, struct timespec *ts) {
+    if (runtime_time_to_timespec) {
+        XrResult r = runtime_time_to_timespec(instance, time, ts);
+        if (r != XR_ERROR_FUNCTION_UNSUPPORTED) return r;
+    }
+    if (!ts) return XR_ERROR_VALIDATION_FAILURE;
+    long long mono = (long long)time - (calibrated ? time_offset : 0);
+    ts->tv_sec = (time_t)(mono / 1000000000ll);
+    ts->tv_nsec = (long)(mono % 1000000000ll);
+    return XR_SUCCESS;
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL layer_wait_frame(XrSession session, const XrFrameWaitInfo *info, XrFrameState *state) {
+    if (!runtime_wait_frame) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    XrResult r = runtime_wait_frame(session, info, state);
+    if (XR_SUCCEEDED(r) && state && state->predictedDisplayTime) {
+        // predictedDisplayTime is about one display period ahead of "now"
+        time_offset = (long long)(state->predictedDisplayTime - state->predictedDisplayPeriod) - mono_ns();
+        calibrated = 1;
+    }
+    return r;
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL layer_get_instance_proc_addr(XrInstance instance, const char *name,
+                                                                   PFN_xrVoidFunction *function) {
+    if (!function || !name) return XR_ERROR_VALIDATION_FAILURE;
+    if (!next_gipa) return XR_ERROR_HANDLE_INVALID;
+    if (str_eq(name, "xrConvertTimespecTimeToTimeKHR") || str_eq(name, "xrConvertTimeToTimespecTimeKHR")) {
+        PFN_xrVoidFunction real = 0;
+        if (instance == XR_NULL_HANDLE) return XR_ERROR_HANDLE_INVALID;
+        if (XR_FAILED(next_gipa(instance, name, &real))) real = 0;
+        if (str_eq(name, "xrConvertTimespecTimeToTimeKHR")) {
+            runtime_timespec_to_time = (PFN_xrConvertTimespecTimeToTimeKHR)real;
+            *function = (PFN_xrVoidFunction)emu_timespec_to_time;
+        } else {
+            runtime_time_to_timespec = (PFN_xrConvertTimeToTimespecTimeKHR)real;
+            *function = (PFN_xrVoidFunction)emu_time_to_timespec;
+        }
+        return XR_SUCCESS;
+    }
+    if (str_eq(name, "xrWaitFrame") && instance != XR_NULL_HANDLE) {
+        XrResult r = next_gipa(instance, name, (PFN_xrVoidFunction *)&runtime_wait_frame);
+        if (XR_FAILED(r)) return r;
+        *function = (PFN_xrVoidFunction)layer_wait_frame;
+        return XR_SUCCESS;
+    }
+    return next_gipa(instance, name, function);
+}
+
+static XrResult create_stripped(XrApiLayerNextInfo *next, const XrInstanceCreateInfo *info,
+                                const XrApiLayerCreateInfo *chained, XrInstance *instance) {
+    XrResult r = next->nextCreateApiLayerInstance(info, chained, instance);
+    if (r != XR_ERROR_EXTENSION_NOT_PRESENT) return r;
+    // The runtime doesn't know XR_KHR_convert_timespec_time: we provide it, so don't pass it down.
+    const char *exts[MAX_EXTS];
+    uint32_t n = 0, dropped = 0;
+    for (uint32_t i = 0; i < info->enabledExtensionCount && n < MAX_EXTS; ++i) {
+        if (str_eq(info->enabledExtensionNames[i], TIMESPEC_EXT)) { ++dropped; continue; }
+        exts[n++] = info->enabledExtensionNames[i];
+    }
+    if (!dropped) return r;
+    XrInstanceCreateInfo stripped = *info;
+    stripped.enabledExtensionCount = n;
+    stripped.enabledExtensionNames = exts;
+    return next->nextCreateApiLayerInstance(&stripped, chained, instance);
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL layer_create_instance(const XrInstanceCreateInfo *info,
+                                                            const XrApiLayerCreateInfo *layer_info, XrInstance *instance) {
+    if (!layer_info || !layer_info->nextInfo || !info) return XR_ERROR_INITIALIZATION_FAILED;
+    XrApiLayerNextInfo *next = layer_info->nextInfo;
+    next_gipa = next->nextGetInstanceProcAddr;
+    XrApiLayerCreateInfo chained = *layer_info;
+    chained.nextInfo = next->next;
+    XrResult r = create_stripped(next, info, &chained, instance);
+    if (r != XR_ERROR_API_VERSION_UNSUPPORTED || XR_VERSION_MAJOR(info->applicationInfo.apiVersion) != 1 ||
+        XR_VERSION_MINOR(info->applicationInfo.apiVersion) == 0)
+        return r;
+    // The Frame's SteamVR runtime only accepts OpenXR 1.0, but Proton 11's VR helper (and newer apps) ask for 1.1:
+    // retry as a 1.0 app (1.1 core functions the runtime lacks are simply not returned by xrGetInstanceProcAddr).
+    XrInstanceCreateInfo v10 = *info;
+    v10.applicationInfo.apiVersion = XR_MAKE_VERSION(1, 0, 0);
+    return create_stripped(next, &v10, &chained, instance);
+}
+
+EXPORT XRAPI_ATTR XrResult XRAPI_CALL xrNegotiateLoaderApiLayerInterface(const XrNegotiateLoaderInfo *loader_info,
+                                                                         const char *layer_name,
+                                                                         XrNegotiateApiLayerRequest *request) {
+    if (!loader_info || !request || loader_info->structType != XR_LOADER_INTERFACE_STRUCT_LOADER_INFO ||
+        request->structType != XR_LOADER_INTERFACE_STRUCT_API_LAYER_REQUEST ||
+        loader_info->minInterfaceVersion > XR_CURRENT_LOADER_API_LAYER_VERSION ||
+        loader_info->maxInterfaceVersion < XR_CURRENT_LOADER_API_LAYER_VERSION)
+        return XR_ERROR_INITIALIZATION_FAILED;
+    if (layer_name && !str_eq(layer_name, LAYER_NAME)) return XR_ERROR_INITIALIZATION_FAILED;
+    request->layerInterfaceVersion = XR_CURRENT_LOADER_API_LAYER_VERSION;
+    request->layerApiVersion = XR_CURRENT_API_VERSION;
+    request->getInstanceProcAddr = layer_get_instance_proc_addr;
+    request->createApiLayerInstance = layer_create_instance;
+    return XR_SUCCESS;
+}
@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// FrameBridge extension shim: lets engine plugins reach OpenXR functions that FrameBridge emulates but overport's
+// dispatcher (libopenxr_loader.so) doesn't know. overport answers xrGetInstanceProcAddr from a fixed table and returns
+// "Unknown proc addr" for anything else (e.g. the XR_FB_render_model functions), so the adapter underneath never sees
+// the request.
+//
+// Meta's OVRPlugin finds xrGetInstanceProcAddr with dlopen("libopenxr_loader.so") + dlsym, so FramePort points that
+// string in libOVRPlugin.so at this library instead (patches/frame/adapter.py). Names the adapter emulates are served
+// by the adapter (framebridge_extension_proc); everything else goes to overport's xrGetInstanceProcAddr unchanged.
+#include <openxr/openxr.h>
+#include <android/log.h>
+#include <dlfcn.h>
+#include <pthread.h>
+#include <stddef.h>
+
+#define TAG "FrameBridge"
+#define EXPORT __attribute__((visibility("default")))
+
+typedef PFN_xrVoidFunction (*PFN_extension_proc)(const char *name);
+
+static PFN_xrGetInstanceProcAddr overport_gipa;
+static pthread_once_t once = PTHREAD_ONCE_INIT;
+
+static void resolve_overport(void) {
+    void *h = dlopen("libopenxr_loader.so", RTLD_NOW | RTLD_NOLOAD);
+    if (!h) h = dlopen("libopenxr_loader.so", RTLD_NOW);
+    if (h) overport_gipa = (PFN_xrGetInstanceProcAddr)dlsym(h, "xrGetInstanceProcAddr");
+    __android_log_print(ANDROID_LOG_INFO, TAG, "extension shim: overport xrGetInstanceProcAddr %s",
+                        overport_gipa ? "OK" : "MISSING");
+}
+
+static PFN_xrVoidFunction adapter_proc(const char *name) {
+    static PFN_extension_proc fn;
+    if (!fn) {
+        // Loaded by overport's dispatcher once an instance exists; NOLOAD so the shim never loads it by itself.
+        void *h = dlopen("libopenxr_loader_generic.so", RTLD_NOW | RTLD_NOLOAD);
+        if (h) fn = (PFN_extension_proc)dlsym(h, "framebridge_extension_proc");
+        if (!fn) return NULL;
+    }
+    return fn(name);
+}
+
+EXPORT XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const char *name,
+                                                            PFN_xrVoidFunction *function) {
+    pthread_once(&once, resolve_overport);
+    if (name && function && instance != XR_NULL_HANDLE) {
+        PFN_xrVoidFunction emulated = adapter_proc(name);
+        if (emulated) {
+            __android_log_print(ANDROID_LOG_INFO, TAG, "extension shim: %s -> FrameBridge", name);
+            *function = emulated;
+            return XR_SUCCESS;
+        }
+    }
+    if (!overport_gipa) return XR_ERROR_INITIALIZATION_FAILED;
+    return overport_gipa(instance, name, function);
+}
@@ -1,6 +1,6 @@
 [project]
 name = "frameport"
-version = "0.1.0"
+dynamic = ["version"]
 description = "Port Meta Quest standalone games to the Valve Steam Frame (Lepton): suggested patches, automated validation, one-click install."
 readme = "README.md"
 license = { text = "GPL-3.0-only" }
@@ -31,6 +31,9 @@ frameport-gui = "frameport.ui.app:main"
 requires = ["hatchling"]
 build-backend = "hatchling.build"

+[tool.hatch.version]
+path = "src/frameport/_version.py"  # the single source of the version
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/frameport"]

@@ -45,6 +48,7 @@ testpaths = ["tests"]
 markers = [
    "device: needs a reachable Steam Frame (FRAMEPORT_FRAME=user@host)",
    "games: needs the local game dumps (FRAMEPORT_GAMES=<downloads dir>)",
+    "native: compiles native code with the NDK from native/build.py (FRAMEPORT_NATIVE_TESTS=1; slow)",
 ]

 [tool.flet]
@@ -0,0 +1,101 @@
+"""Turn a "Working configuration" issue (.github/ISSUE_TEMPLATE/working-config.yml) into catalog/games/<pkg>.yaml.
+
+Used by .github/workflows/catalog-from-issue.yml after a maintainer labels the issue `catalog-accepted`; can also be
+run by hand:  gh issue view 12 --json body -q .body | python scripts/catalog_from_issue.py --issue 12
+The issue text is untrusted: only the YAML block of the "Recipe" section is read, parsed with yaml.safe_load, reduced
+to known catalog fields and checked (package id, status, types) before anything is written.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+from frameport.recommend.catalog import CatalogEntry, to_yaml  # noqa: E402
+
+PKG_RE = re.compile(r"^(rift\.[a-z0-9_]{1,80}|[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z0-9_]+){1,8})$")
+STATUSES = {"works", "issues", "unsupported", "unknown"}
+LIST_FIELDS = {"overport_extra", "overport_remove", "alt_overport", "frame", "frame_remove", "pcvr", "pcvr_remove"}
+DICT_FIELDS = {"adapter", "device_files", "lepton_env", "proton_env", "verified"}
+ID_RE = re.compile(r"^[A-Za-z0-9_.\-]{1,80}$")
+
+
+class Invalid(ValueError):
+    pass
+
+
+def section(body: str, heading: str) -> str:
+    m = re.search(r"^###\s+" + re.escape(heading) + r"\s*$(.*?)(?=^###\s|\Z)", body, re.M | re.S)
+    if not m:
+        raise Invalid(f"no '{heading}' section")
+    return m.group(1).strip()
+
+
+def recipe_from_body(body: str) -> dict:
+    text = section(body, "Recipe")
+    m = re.search(r"```(?:ya?ml)?\s*\n(.*?)```", text, re.S)
+    raw = m.group(1) if m else text
+    try:
+        d = yaml.safe_load(raw)
+    except yaml.YAMLError as exc:
+        raise Invalid(f"recipe isn't valid YAML: {exc}") from None
+    if not isinstance(d, dict):
+        raise Invalid("recipe must be a YAML mapping")
+    return d
+
+
+def validate(d: dict) -> CatalogEntry:
+    pkg = d.get("package")
+    if not isinstance(pkg, str) or not PKG_RE.match(pkg):
+        raise Invalid(f"bad package id {pkg!r}")
+    if not isinstance(d.get("title"), str) or not d["title"].strip():
+        raise Invalid("missing title")
+    if d.get("status", "unknown") not in STATUSES:
+        raise Invalid(f"bad status {d.get('status')!r}")
+    unknown = sorted(set(d) - set(CatalogEntry.__dataclass_fields__) - {"origin"})
+    if unknown:
+        raise Invalid(f"unknown fields: {', '.join(unknown)}")
+    for k in LIST_FIELDS & set(d):
+        if not isinstance(d[k], list) or not all(isinstance(x, str) and ID_RE.match(x) for x in d[k]):
+            raise Invalid(f"{k} must be a list of patch ids")
+    for k in DICT_FIELDS & set(d):
+        if not isinstance(d[k], dict):
+            raise Invalid(f"{k} must be a mapping")
+    for k in ("device_files",):
+        for path in (d.get(k) or {}):
+            if not isinstance(path, str) or path.startswith("/") or ".." in Path(path).parts:
+                raise Invalid(f"{k}: bad path {path!r}")
+    d = {k: v for k, v in d.items() if k != "origin"}
+    return CatalogEntry.from_dict(d, "bundled")
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("body", nargs="?", help="file with the issue body (default: stdin)")
+    ap.add_argument("--issue", type=int, help="issue number (recorded in verified.issue)")
+    ap.add_argument("--out", type=Path, default=ROOT / "catalog" / "games")
+    a = ap.parse_args(argv)
+    body = Path(a.body).read_text(encoding="utf-8") if a.body else sys.stdin.read()
+    try:
+        entry = validate(recipe_from_body(body))
+    except Invalid as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    if a.issue:
+        entry.verified = {**entry.verified, "issue": a.issue}
+    path = a.out / f"{entry.package}.yaml"
+    existed = path.exists()
+    path.write_text(to_yaml(entry), encoding="utf-8")
+    print(f"{'updated' if existed else 'added'} {path.relative_to(ROOT) if path.is_relative_to(ROOT) else path}")
+    print(f"package={entry.package}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Score the patch heuristics against the verified catalog: for every game dump that has a catalog recipe, suggest a
+recipe with the catalog switched off and compare the recipe-relevant choices.
+
+    python scripts/eval_heuristics.py "<folder with game dumps>" [--verbose]
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from frameport.analysis.detect import analyze  # noqa: E402
+from frameport.patches import base  # noqa: E402
+from frameport.recommend import catalog, engine  # noqa: E402
+from frameport.sources import quest_dump  # noqa: E402
+
+
+def signature(recipe) -> dict:
+    """The parts of a recipe that differ between games (defaults/automatic fixes are excluded)."""
+    pats = recipe.patches
+    return {
+        "overport": sorted(p for p in pats if base.get(p).category == "overport" and not base.get(p).default_on),
+        "overport_removed": sorted(p for p in (x.id for x in base.all_patches() if x.category == "overport" and x.default_on)
+                                   if p not in pats),
+        "frame": sorted(p for p in pats if base.get(p).category == "frame" and not base.get(p).default_on),
+        "adapter": {p.split(".", 1)[1]: v.get("value") for p, v in sorted(pats.items()) if p.startswith("adapter.")},
+        "device_files": sorted((pats.get("device.files") or {}).get("files", {})),
+        "alt": sorted(recipe.alt_patches),
+        "use_alt": recipe.use_alt,
+        "status_unsupported": recipe.status == "unsupported",
+    }
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("dumps", type=Path)
+    ap.add_argument("--verbose", action="store_true")
+    args = ap.parse_args()
+    games = quest_dump.scan(args.dumps)
+    total = matched_fields = games_ok = 0
+    misses = []
+    for g in games:
+        a = analyze(g.apk, data_bytes=g.data_bytes())
+        if not catalog.lookup(a.package):
+            continue
+        want = signature(engine.suggest(a, use_catalog=True))
+        want["status_unsupported"] = catalog.lookup(a.package).status == "unsupported" and "32-bit" in catalog.lookup(a.package).notes
+        got = signature(engine.suggest(a, use_catalog=False))
+        diffs = {k: (want[k], got[k]) for k in want if want[k] != got[k]}
+        total += len(want)
+        matched_fields += len(want) - len(diffs)
+        games_ok += not diffs
+        if diffs:
+            misses.append((a.package, diffs))
+        if args.verbose or diffs:
+            print(f"{'OK  ' if not diffs else 'DIFF'} {a.package}")
+            for k, (w, h) in diffs.items():
+                print(f"       {k}: catalog={w}  heuristics={h}")
+    n = games_ok + len(misses)
+    print(f"\n{games_ok}/{n} games reproduced exactly; {matched_fields}/{total} recipe fields match")
+    return 0 if not misses else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -11,7 +11,9 @@ downloads and manages them on first run (Tools page), so bundles stay small and
 from __future__ import annotations

 import argparse
+import os
 import platform
+import re
 import shutil
 import subprocess
 import sys
@@ -22,6 +24,18 @@ DATA = ROOT / "src/frameport/_data"
 TARGET = {"Windows": "windows", "Darwin": "macos", "Linux": "linux"}[platform.system()]


+def version() -> str:
+    text = (ROOT / "src/frameport/_version.py").read_text(encoding="utf-8")
+    return re.search(r'__version__\s*=\s*"([^"]+)"', text).group(1)
+
+
+def check_tag() -> None:
+    """A release build (tag vX.Y.Z) must carry that version, or the app's update check would compare wrongly."""
+    ref = os.environ.get("GITHUB_REF_NAME", "")
+    if os.environ.get("GITHUB_REF_TYPE") == "tag" and ref.startswith("v") and ref[1:] != version():
+        raise SystemExit(f"tag {ref} doesn't match src/frameport/_version.py ({version()}): bump it first")
+
+
 def stage_data():
    shutil.rmtree(DATA, ignore_errors=True)
    for name in ("catalog", "artifacts", "agent", "bootstrap"):
@@ -34,6 +48,8 @@ def main() -> int:
    ap.add_argument("--pyinstaller", action="store_true")
    ap.add_argument("--keep-data", action="store_true", help="leave src/frameport/_data after building")
    args = ap.parse_args()
+    check_tag()
+    print(f"FramePort {version()}")
    stage_data()
    try:
        if args.pyinstaller:
@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Make a screenshot-safe copy of a FramePort data folder (for docs/images):
+
+    python scripts/scrub_library.py <data dir> <new dir> [--sort size]
+
+Copies library.json + artwork/ only (no Frame pairing, SSH key, tools, logs or builds). In the copy every game's
+folder name becomes its store title, every local path becomes D:/Games/<Quest|PC VR>/<title>/..., settings other than
+the Library view are dropped, and install/launch history is removed. Fails if any original path is left.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import sys
+from pathlib import Path
+
+PATHLIKE = re.compile(r"^(/|[A-Za-z]:[\\/]|\\\\)")
+DEVICE = ("/data/", "/sdcard", "/storage/", "/system/", "/vendor/", "/apex/", "/proc/", "/dev/")  # inside the headset
+DROP_KEYS = {"installs", "log_path", "last_played", "played"}
+
+
+def safe(title: str) -> str:
+    return re.sub(r'[<>:"/\\|?*]+', "", title).strip() or "Game"
+
+
+def scrub_game(g: dict) -> dict:
+    title = g.get("title") or g.get("package")
+    base = f"D:/Games/{'PC VR' if g.get('kind') == 'rift' else 'Quest'}/{safe(title)}"
+    originals: set[str] = set()
+
+    def collect(o):
+        if isinstance(o, dict):
+            for v in o.values():
+                collect(v)
+        elif isinstance(o, list):
+            for v in o:
+                collect(v)
+        elif isinstance(o, str) and PATHLIKE.match(o) and not o.startswith(DEVICE):
+            originals.add(o)
+    collect(g)
+    roots = sorted({str(Path(p).parent) for p in originals} | originals, key=len, reverse=True)
+
+    def fix(o, key=""):
+        if isinstance(o, dict):
+            return {k: fix(v, k) for k, v in o.items() if k not in DROP_KEYS}
+        if isinstance(o, list):
+            return [fix(v, key) for v in o]
+        if isinstance(o, str):
+            if PATHLIKE.match(o) and not o.startswith(DEVICE):
+                name = Path(o.replace("\\", "/")).name
+                return base if key in ("origin", "folder", "game_dir", "data_dir", "base") else f"{base}/{name}"
+            for r in roots:
+                if len(r) > 3 and r in o:
+                    o = o.replace(r, base)
+            o = re.sub(r"/(?:mnt|home|Users)/[^)\"]*", "D:/Games", o)  # paths inside messages (e.g. a tool's folder)
+        return o
+    out = fix(g)
+    out["name"] = title
+    return out
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("src", type=Path)
+    ap.add_argument("dest", type=Path)
+    ap.add_argument("--sort", default="size", choices=["name", "recent", "played", "size", "status"])
+    args = ap.parse_args()
+    lib = json.loads((args.src / "library.json").read_text())
+    games = {pkg: scrub_game(g) for pkg, g in lib.get("games", {}).items()}
+    view = {**(lib.get("settings", {}).get("ui.library") or {}), "sort": args.sort, "platform": "all",
+            "where": "all", "status": "all", "tags": []}
+    out = {"games": games, "settings": {"ui.library": view, "migrations": lib.get("settings", {}).get("migrations", [])}}
+    text = json.dumps(out, indent=1)
+    leftovers = [o for o in re.findall(r'"((?:/|[A-Za-z]:\\\\)[^"]*)"', text) if not o.startswith(("D:/Games/",) + DEVICE)]
+    if leftovers:
+        print("not scrubbed:", leftovers[:10], file=sys.stderr)
+        return 1
+    args.dest.mkdir(parents=True, exist_ok=True)
+    (args.dest / "library.json").write_text(text)
+    if (args.src / "artwork").is_dir():
+        shutil.copytree(args.src / "artwork", args.dest / "artwork", dirs_exist_ok=True)
+    print(f"{len(games)} games -> {args.dest}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -25,6 +25,35 @@ PORT = 8557
 ERRORS: list[str] = []


+class FakeTarget:
+    """--fake-frame: a pretend Steam Frame with the library's working Quest builds installed (no network, no device),
+    for documentation screenshots."""
+
+    def __init__(self, count: int = 8):
+        from frameport.frame.connection import parse_target
+
+        self.label = "steamframe"
+        self.target = parse_target("steamos@steamframe.local")
+        works = [g for g in library.games() if g.get("kind") != "rift" and (g.get("build") or {}).get("sha256")
+                 and (g.get("recipe") or {}).get("status") in ("works", "issues")]
+        works.sort(key=lambda g: -(g.get("data_bytes") or 0))
+        self.games = [{"package": g["package"], "kind": "quest", "title": g.get("title"),
+                       "apk_size": (g.get("data_bytes") or 0) + 2**28, "sha256": g["build"]["sha256"],
+                       "recipe": {"patches": (g.get("recipe") or {}).get("patches", [])}} for g in works[:count]]
+
+    def describe(self) -> dict:
+        return {"hostname": "steamframe", "os": "SteamOS", "os_version": "3.8", "build_id": "20260922",
+                "free_bytes": 312 * 2**30, "installed": self.games, "lepton": True,
+                "proton": {"ready": {"display_name": "Proton 11 (ARM64)"}, "openxr": {"name": "SteamVR"}},
+                "kernel_keys": {"keys": 31, "max_keys": 200}}
+
+    def installed(self) -> list[dict]:
+        return self.games
+
+    def close(self) -> None:
+        pass
+
+
 def driver(app: FramePortApp, steps: list[tuple[str, callable]], ready: threading.Event, done_step: list):
    for name, action in steps:
        try:
@@ -41,12 +70,42 @@ def main() -> int:
    ap.add_argument("--out", type=Path, required=True)
    ap.add_argument("--game", default=None)
    ap.add_argument("--frame", default=None, help="steamos@host: also connect and run a launch-test job for --game")
+    ap.add_argument("--no-test", action="store_true", help="with --frame: skip the launch-test job")
+    ap.add_argument("--scale", type=float, default=1.0, help="UI scale to render at (e.g. 1.5)")
+    ap.add_argument("--viewport", default="1280x820", help="browser size, e.g. 2560x1440")
+    ap.add_argument("--update", action="store_true", help="pretend a new FramePort release exists (update UI)")
+    ap.add_argument("--fake-frame", action="store_true", help="pretend a Steam Frame is connected (no device needed)")
+    ap.add_argument("--docs", action="store_true", help="only the screens used in the docs (Library, --game, Frame)")
    args = ap.parse_args()
+    from frameport.ui import theme
+
+    theme.set_scale(args.scale)
+    vw, vh = (int(x) for x in args.viewport.split("x"))
    args.out.mkdir(parents=True, exist_ok=True)
    game = args.game or (library.games()[0]["package"] if library.games() else None)
    steps = [("library", lambda a: a.navigate(0)), ("frame", lambda a: a.navigate(1)), ("tools", lambda a: a.navigate(2))]
    if game:
        steps.insert(1, ("game", lambda a: a.open_game(game)))
+        steps.insert(2, ("game-customize", lambda a: a.open_game(game, advanced=True)))
+        steps += [("share-dialog", lambda a: a.share_config_dialog(game)),
+                  ("report-dialog", lambda a: (a.page.pop_dialog(), a.report_problem_dialog(game)))]
+        # last: the right-click menu stays open over whatever comes next
+        steps.append(("library-menu", lambda a: (a.page.pop_dialog(), a.navigate(0), time.sleep(3),
+                                                 a.library_view.open_menu(game))))
+    if args.docs:
+        steps = [("library", lambda a: a.navigate(0))]
+        if game:
+            steps += [("game", lambda a: a.open_game(game)), ("game-customize", lambda a: a.open_game(game, advanced=True))]
+        steps.append(("frame", lambda a: a.navigate(1)))
+    if args.update:
+        from frameport import updates
+
+        fake = updates.Update(version="9.9.9", tag="v9.9.9", page="https://example.invalid", asset=None, asset_url=None,
+                              sums_url=None, wheel_url=None,
+                              notes="## What's new\n- Self-update test release\n- **Bold** and `code` in notes")
+        steps += [("update-banner", lambda a: (a.updater._set(fake), a.navigate(0))),
+                  ("update-dialog", lambda a: a.updater.show_dialog()),
+                  ("update-settings", lambda a: (a.page.pop_dialog(), a.navigate(2)))]
    if args.frame:
        from frameport.frame.connection import parse_target

@@ -64,12 +123,19 @@ def main() -> int:
            while a.job_running:
                time.sleep(2)

-        steps += [("frame-connected", connect), ("launch-test-job", job)]
+        steps += [("frame-connected", connect), ("library-connected", lambda a: a.navigate(0))]
+        if game:
+            steps.append(("game-connected", lambda a: a.open_game(game)))
+        if not args.no_test:
+            steps.append(("launch-test-job", job))
    ready, done = threading.Event(), []

    def app_main(page: ft.Page):
        try:
            app = FramePortApp(page)
+            if args.fake_frame:
+                app.target = FakeTarget()
+                app.frame_info, app.frame_state = app.target.describe(), "connected"
        except Exception:  # noqa: BLE001
            ERRORS.append("startup: " + traceback.format_exc())
            return
@@ -82,7 +148,7 @@ def main() -> int:
        try:
            with sync_playwright() as p:
                browser = p.chromium.launch(args=["--use-gl=swiftshader", "--enable-unsafe-swiftshader"])
-                page = browser.new_page(viewport={"width": 1280, "height": 820})
+                page = browser.new_page(viewport={"width": vw, "height": vh})
                page.goto(f"http://127.0.0.1:{PORT}", wait_until="networkidle", timeout=120_000)
                shot = 0
                deadline = time.time() + 240 + 8 * len(steps)
@@ -101,7 +167,9 @@ def main() -> int:
        os._exit(1 if ERRORS else 0)

    threading.Thread(target=shooter, daemon=True).start()
-    ft.run(app_main, view=ft.AppView.WEB_BROWSER, port=PORT)
+    from frameport.ui.app import assets_dir
+
+    ft.run(app_main, view=ft.AppView.WEB_BROWSER, port=PORT, assets_dir=assets_dir())
    return 1


@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""CI smoke test of FramePort's self-update on this OS, with the archive this job just built:
+
+    python scripts/update_smoke.py FramePort-<os>.<zip|tar.gz>
+
+It unpacks the archive twice (an "installed" copy, plus an older-looking copy of it with a stale marker file), then
+runs the real update path: frameport.updates._extract (ditto on macOS) + the real swap script (PowerShell on Windows,
+/bin/sh elsewhere), without relaunching. It checks the installed copy now has the new files, and on Windows that the
+signer check sees the same certificate on both copies. Exits non-zero on any failure.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+
+def main() -> int:
+    import logging
+
+    logging.basicConfig(level=logging.INFO)
+    archive = Path(sys.argv[1]).resolve()
+    home = Path(tempfile.mkdtemp(prefix="fp-update-smoke-"))
+    os.environ["FRAMEPORT_HOME"] = str(home / "data")
+    from frameport import updates
+
+    platform = sys.platform
+    new = updates._extract(archive, home / "staged", platform)
+    installed_parent = home / "Programs"
+    installed_parent.mkdir()
+    installed = installed_parent / new.name
+    old = updates._extract(archive, home / "old", platform)
+    shutil.move(str(old), str(installed))
+    stale = installed / ("Contents/stale.txt" if platform == "darwin" else "stale.txt")
+    stale.write_text("from the old version")
+    marker = new / ("Contents/new-version.txt" if platform == "darwin" else "new-version.txt")
+    marker.write_text("new")
+    sub = next(p for p in sorted(marker.parent.iterdir()) if p.is_dir() and not p.is_symlink())
+    nested = sub / "new-version.txt"  # files in existing subfolders must be replaced too (Windows merges folders)
+    nested.write_text("new")
+    if platform == "win32" and os.environ.get("HAS_CERT") == "true":
+        a, b = updates._signer_thumbprint(installed / "FramePort.exe"), updates._signer_thumbprint(new / "FramePort.exe")
+        print(f"signer thumbprints: installed {a} new {b}")
+        assert a and a == b, "signature check failed"
+    script = updates.apply(new, installed, relaunch=False, pid=999999, platform=platform, wait=True)
+    log = (home / "data/logs/update.log").read_text()
+    print(script.read_text()[:400], "...\n--- update.log ---\n" + log)
+    installed_marker = installed / marker.relative_to(new)
+    assert installed_marker.read_text() == "new", "the new files weren't installed"
+    assert (installed / nested.relative_to(new)).read_text() == "new", "a subfolder wasn't updated"
+    assert "installed" in log and "FAILED" not in log, "the update script reported a failure"
+    exe = {"win32": installed / "FramePort.exe", "darwin": installed / "Contents/MacOS"}.get(platform,
+                                                                                         installed / "FramePort")
+    assert exe.exists(), f"{exe} missing after the update"
+    if platform != "win32":  # Windows copies over the old files (the zip has no folder of its own); others swap
+        assert not stale.exists(), "the old version's files are still there"
+    print("update smoke test passed")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -1,3 +1,6 @@
 """FramePort: port Meta Quest standalone games to the Valve Steam Frame."""

-__version__ = "0.1.0"
+from ._version import __version__  # noqa: F401  (single source of the version)
+
+# Where the project lives (Settings → About, problem reports). Change it here if the repo moves.
+REPO_URL = "https://github.com/spoopyghosty0/frameport"
@@ -0,0 +1,2 @@
+# The FramePort version: the single source (pyproject reads it via hatch; CI checks a release tag matches it).
+__version__ = "0.3.2"
@@ -2,6 +2,7 @@
 from __future__ import annotations

 import logging
+import re
 import zipfile
 from pathlib import Path

@@ -22,7 +23,45 @@ def _read_manifest_info(path: Path) -> tuple[str, str, str, str | None]:
    return apk.package, apk.version_name or "", label, apk.get_main_activity()


-def analyze(path: Path, deep: bool = True) -> Analysis:
+def _unreal_version(z: zipfile.ZipFile, lib: str) -> str | None:
+    """'4.20' from the '++UE4+Release-4.20' build string (streamed; engine libs can be >1 GB)."""
+    tail = b""
+    with z.open(lib) as f:
+        while True:
+            chunk = f.read(1 << 24)
+            if not chunk:
+                return None
+            m = re.search(rb"\+\+UE[45]\+Release-([0-9]+\.[0-9]+)", tail + chunk)
+            if m:
+                return m.group(1).decode()
+            tail = chunk[-64:]
+
+
+def _features(manifest: bytes) -> dict[str, bool]:
+    """uses-feature name -> required (android:required defaults to true)."""
+    x = axml.Axml(manifest)
+    names = x.strings()
+    out = {}
+    for el in x.elements():
+        if el.name != "uses-feature":
+            continue
+        name = x.attr_str(el, "name")
+        if not name:
+            continue
+        required = True
+        for a in el.attrs:
+            if a.name < len(names) and names[a.name] == "required":
+                required = a.value != 0
+        out[name] = required
+    return out
+
+
+# OpenXR composition-layer extensions the Frame runtime lacks (see docs/FRAME_RUNTIME.md).
+LAYER_EXTENSIONS = ("XR_KHR_composition_layer_cylinder", "XR_KHR_composition_layer_equirect",
+                    "XR_KHR_composition_layer_equirect2", "XR_KHR_composition_layer_cube")
+
+
+def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Analysis:
    path = Path(path)
    with zipfile.ZipFile(path) as z:
        names = z.namelist()
@@ -39,12 +78,15 @@ def analyze(path: Path, deep: bool = True) -> Analysis:
                    info = z.getinfo(prefix + lib)
                    if info.file_size < 400 * 2**20:
                        lib_bytes[lib] = z.read(info)
+        engine_lib = next((prefix + n for n in ("libUE4.so", "libUnreal.so") if prefix and prefix + n in names), None)
+        unreal_version = _unreal_version(z, engine_lib) if deep and engine_lib else None
        boot = z.read("assets/bin/Data/boot.config").decode("utf-8", "replace") if "assets/bin/Data/boot.config" in names else ""
        ggm = z.read(UNITY_GGM) if deep and UNITY_GGM in names else None

    package, version, label, activity = _read_manifest_info(path)
    libset = set(libs)
-    engine = "Unreal" if libset & {"libUE4.so", "libUnreal.so"} else "Unity" if "libunity.so" in libset else "Other"
+    engine = ("Unreal" if libset & {"libUE4.so", "libUnreal.so"} else "Unity" if "libunity.so" in libset
+              else "CryEngine" if "libCrySystem.so" in libset else "Other")
    has_openxr, has_vrapi = "libopenxr_loader.so" in libset, "libvrapi.so" in libset
    xr = "OpenXR+VrApi" if has_openxr and has_vrapi else "OpenXR" if has_openxr else "VrApi" if has_vrapi else "?"
    is_overport = "libopenxr_loader_generic.so" in libset or "liboverport.config.so" in libset
@@ -62,12 +104,15 @@ def analyze(path: Path, deep: bool = True) -> Analysis:
        graphics = "GLES or unknown (no Vulkan declaration)"

    uses_glad = False
-    oculus_os = False
+    oculus_os_refs = []
+    layer_exts = set()
    for name, data in lib_bytes.items():
        if not elf.is_elf(data):
            continue
        if b"com/oculus/os/AnalyticsEvent" in data:
-            oculus_os = True
+            oculus_os_refs.append(name)
+        if name != "libOVRPlugin.so":  # OVRPlugin lists every layer extension; only the game's own requests count
+            layer_exts |= {ext for ext in LAYER_EXTENSIONS if ext.encode() + b"\0" in data}
        if name not in ("libvrapi.so", "libOVRPlugin.so") and b"GLAD_GL_" in data and "eglGetProcAddress" in elf.dyn_symbols(data, False):
            uses_glad = True

@@ -81,6 +126,8 @@ def analyze(path: Path, deep: bool = True) -> Analysis:
            msaa_levels = 0

    cats = axml.categories(manifest)
+    features = _features(manifest)
+    used_perms, _ = axml.used_and_declared_permissions(manifest)
    return Analysis(
        package=package,
        version=version,
@@ -96,10 +143,22 @@ def analyze(path: Path, deep: bool = True) -> Analysis:
        meta_permissions=axml.undeclared_meta_permissions(manifest),
        uses_glad_gl=uses_glad,
        unity_msaa_levels=msaa_levels,
-        oculus_os_classes=oculus_os,
+        oculus_os_classes=bool(oculus_os_refs),
        is_overport_output=is_overport,
        debuggable=bool(axml.Axml(manifest).get_bool("application", "debuggable")),
-        extra={"missing_ovr_symbols": sorted(missing_ovr_symbols(lib_bytes)), "size": path.stat().st_size},
+        extra={
+            "frame_patched": "libframe_settings.so" in libset,  # already has FramePort's FrameBridge adapter
+            "missing_ovr_symbols": sorted(missing_ovr_symbols(lib_bytes)), "size": path.stat().st_size,
+            "data_bytes": data_bytes or 0,
+            "features": features,
+            "meta_permissions_used": sorted(p for p in used_perms if p.startswith(("com.oculus.permission.", "horizonos."))),
+            # mixed-reality-only: passthrough required and no guardian (Meta's BOUNDARYLESS_APP)
+            "mr_only": features.get("com.oculus.feature.PASSTHROUGH", False) and "com.oculus.feature.BOUNDARYLESS_APP" in features,
+            "hand_tracking_only": features.get("oculus.software.handtracking", False),
+            "unreal_version": unreal_version,
+            "oculus_os_refs": sorted(oculus_os_refs),
+            "xr_layer_exts": sorted(layer_exts),  # composition-layer extensions the game's own libraries request
+        },
    )


@@ -87,6 +87,25 @@ def text_instructions(data: bytes):
                yield ins[0], ins[2], ins[3]


+def replace_rodata_string(data: bytes, old: str, new: str) -> tuple[bytes, int]:
+    """Replace NUL-terminated `old` with `new` (not longer; NUL-padded) inside .rodata only, in place (nothing moves;
+    .dynstr, e.g. DT_NEEDED names, is untouched). Returns (data, number of replacements)."""
+    if len(new) > len(old):
+        raise ValueError("replacement must not be longer")
+    sec = _elf(data).get_section_by_name(".rodata")
+    if sec is None:
+        return data, 0
+    start, end = sec["sh_offset"], sec["sh_offset"] + sec["sh_size"]
+    needle, repl = old.encode() + b"\0", new.encode().ljust(len(old) + 1, b"\0")
+    buf, count, i = bytearray(data), 0, start
+    while (i := buf.find(needle, i, end)) != -1:
+        if i == start or buf[i - 1] == 0:  # a whole string, not the tail of a longer one
+            buf[i:i + len(needle)] = repl
+            count += 1
+        i += len(needle)
+    return bytes(buf), count
+
+
 def add_needed(data: bytes, library: str) -> bytes:
    """Add a DT_NEEDED entry in front of the existing ones (same effect as `patchelf --add-needed`; being first matters
    for symbol interposition, e.g. the GL shim must precede libEGL).
@@ -0,0 +1,518 @@
+"""Inspect an Oculus Rift (Windows PC VR) game folder: which program starts it, bitness, engine, XR API, graphics API,
+and whether it uses the Oculus Platform SDK (entitlement checks that need the Oculus app).
+
+Game folders come in many shapes (repacks nest the game one or more levels down, next to installers and archives):
+    Stormland/Stormland.exe
+    Asgards Wrath/WindowsNoEditor/WrathGame.exe + …/WrathGame/Binaries/Win64/WrathGame-Win64-Shipping.exe
+    The Climb/bin/win_x64/Climb.exe + The Climb/bin/win_x64-steam/Climb.exe
+One recursive walk (walk()) collects every .exe/.dll; candidates are GUI-subsystem x86/x64 PE files that aren't
+installers or helpers; rank_exes() scores them with human-readable reasons and flags ambiguous cases for the user.
+A tiny PE reader (header, imports, icon resources) is enough; no third-party dependency (Pillow only for icons).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import struct
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ..core.models import Analysis
+
+MACHINES = {0x14C: "x86", 0x8664: "x86_64", 0xAA64: "arm64"}
+GUI_SUBSYSTEM = 2
+SKIP_EXE = re.compile(
+    r"(?i)(crash|unins|setup|install|redist|vc_?redist|dxsetup|prereq|launcher_helper|cefprocess|ueprereq|dotnet|"
+    r"oculus.?platform|easyanticheat|eac_|report|uploader|bssndrpt|agrepack|modinstaller|^cli(-\d+)?\.exe$|"
+    r"^gui(-\d+)?\.exe$|^t(32|64)\.exe$|^w(32|64)\.exe$|updater|patcher|benchmark|helper|touchup|"
+    r"vrmonitor|steamerrorreporter|unitycrashhandler|ue4editor|editor\.exe$)")
+PRUNE_DIRS = {".git", ".venv", "venv", "node_modules", "__pycache__", "site-packages", "_uninstall", "uninstallme",
+              "redist", "_commonredist", "directx", "support", "prereqs", "__installer", "installers", "vcredist",
+              "dotnetfx", "$pluginsdir", "__macosx"}
+MAX_DEPTH = 8
+_OVR_ASCII = (b"LibOVRRT%s_%d.dll", b"LibOVRRT64_1.dll", b"LibOVRRT32_1.dll", b"LibOVRRT%hs_%d.dll",
+              b"OVR_CAPI", b"ovr_Initialize", b"OculusHMD", b"OculusRift")
+# Unreal stores most strings as UTF-16 (TEXT("…")), so look for both encodings
+LIBOVR_MARKERS = _OVR_ASCII + tuple(m.decode().encode("utf-16-le") for m in _OVR_ASCII)
+PLATFORM_DLLS = ("libovrplatform64_1.dll", "libovrplatform32_1.dll")
+# engine DLLs that wrap the Platform SDK (Ready At Dawn's platform services: Lone Echo, Echo Arena)
+PLATFORM_WRAPPERS = ("pnsovr.dll",)
+GRAPHICS = (("d3d12.dll", "D3D12"), ("d3d11.dll", "D3D11"), ("vulkan-1.dll", "Vulkan"), ("opengl32.dll", "OpenGL"))
+AMBIGUITY = 15  # a runner-up within this many points means "ask the user"
+# repacks start their bundled Revive through a proxy DLL next to the exe (Windows loads DLLs from the exe's folder first)
+LOADER_DLLS = ("xinput1_3.dll", "xinput1_4.dll", "xinput9_1_0.dll", "dinput8.dll", "version.dll", "winmm.dll")
+REVIVE_DLLS = ("librevive64.dll", "librevive32.dll", "librevivexr64.dll", "librevivexr32.dll")
+
+
+class PEError(Exception):
+    pass
+
+
+@dataclass
+class PEInfo:
+    machine: str
+    imports: list[str] = field(default_factory=list)  # lower-case DLL names
+    subsystem: int = 0
+    delay_imports: list[str] = field(default_factory=list)  # DLLs loaded on first use (e.g. the Oculus Platform SDK)
+
+
+# ------------------------------------------------------------------------------------------ PE reading
+def _pe_offsets(data: bytes) -> tuple[int, int, int, int, int]:
+    if data[:2] != b"MZ" or len(data) < 0x40:
+        raise PEError("not a PE file")
+    pe = struct.unpack_from("<I", data, 0x3C)[0]
+    if data[pe:pe + 4] != b"PE\0\0":
+        raise PEError("no PE header")
+    machine, nsec, _, _, _, opt_size, _ = struct.unpack_from("<HHIIIHH", data, pe + 4)
+    return pe, machine, nsec, opt_size, pe + 24
+
+
+def pe_header(path: Path) -> PEInfo:
+    """Machine + subsystem from the first 4 KiB (cheap: used to filter candidates)."""
+    with open(path, "rb") as f:
+        data = f.read(4096)
+    try:
+        pe, machine, _, _, opt = _pe_offsets(data)
+        subsystem = struct.unpack_from("<H", data, opt + 68)[0]
+    except (struct.error, PEError, IndexError):
+        raise PEError("not a PE file") from None
+    return PEInfo(MACHINES.get(machine, hex(machine)), [], subsystem)
+
+
+def _sections(data: bytes, opt: int, opt_size: int, nsec: int) -> list[tuple[int, int, int]]:
+    out = []
+    for k in range(nsec):
+        s = opt + opt_size + 40 * k
+        vsize, va, rsize, raw = struct.unpack_from("<IIII", data, s + 8)
+        out.append((va, max(vsize, rsize), raw))
+    return out
+
+
+def _rva_to_off(sections, rva):
+    for va, size, raw in sections:
+        if va <= rva < va + size:
+            return rva - va + raw
+    return None
+
+
+def read_pe(path: Path, limit: int = 256 << 20) -> tuple[PEInfo, bytes]:
+    data = path.read_bytes() if path.stat().st_size <= limit else path.open("rb").read(limit)
+    pe, machine, nsec, opt_size, opt = _pe_offsets(data)
+    magic = struct.unpack_from("<H", data, opt)[0]
+    subsystem = struct.unpack_from("<H", data, opt + 68)[0]
+    dd = opt + (96 if magic == 0x10B else 112)  # data directories (PE32 / PE32+)
+    imp_rva = struct.unpack_from("<I", data, dd + 8)[0] if opt_size >= dd - opt + 16 else 0
+    sections = _sections(data, opt, opt_size, nsec)
+    delay_rva = struct.unpack_from("<I", data, dd + 13 * 8)[0] if opt_size >= dd - opt + 14 * 8 else 0
+
+    def names(table_rva, entry_size, name_at):
+        out = []
+        p = _rva_to_off(sections, table_rva) if table_rva else None
+        while p is not None and p + entry_size <= len(data) and len(out) < 512:
+            name_rva = struct.unpack_from("<I", data, p + name_at)[0]
+            if not name_rva:
+                break
+            q = _rva_to_off(sections, name_rva)
+            if q is not None:
+                end = data.find(b"\0", q, q + 256)
+                out.append(data[q:end].decode("ascii", "replace").lower())
+            p += entry_size
+        return out
+    return PEInfo(MACHINES.get(machine, hex(machine)), names(imp_rva, 20, 12), subsystem,
+                  names(delay_rva, 32, 4)), data
+
+
+def exe_icon(path: Path, max_bytes: int = 64 << 20) -> bytes | None:
+    """The largest icon image in a PE's resources (RT_GROUP_ICON → RT_ICON), as PNG bytes; None if there's none."""
+    try:
+        with open(path, "rb") as f:
+            data = f.read(max_bytes)
+        pe, machine, nsec, opt_size, opt = _pe_offsets(data)
+        magic = struct.unpack_from("<H", data, opt)[0]
+        dd = opt + (96 if magic == 0x10B else 112)
+        res_rva = struct.unpack_from("<I", data, dd + 16)[0]
+        sections = _sections(data, opt, opt_size, nsec)
+        base = _rva_to_off(sections, res_rva) if res_rva else None
+        if base is None:
+            return None
+
+        def entries(off):
+            named, ids = struct.unpack_from("<HH", data, off + 12)
+            for i in range(named + ids):
+                name, target = struct.unpack_from("<II", data, off + 16 + 8 * i)
+                yield name, target
+
+        def leaves(off):  # (id, data offset, size) under a type directory: name → language → data
+            for name, t in entries(off):
+                if not t & 0x80000000:
+                    continue
+                for _, lang in entries(base + (t & 0x7FFFFFFF)):
+                    if lang & 0x80000000:
+                        continue
+                    rva, size = struct.unpack_from("<II", data, base + lang)
+                    o = _rva_to_off(sections, rva)
+                    if o is not None:
+                        yield name & 0x7FFFFFFF, o, size
+        types = {name: t for name, t in entries(base) if t & 0x80000000}
+        if 14 not in types or 3 not in types:
+            return None
+        icons = {i: (o, s) for i, o, s in leaves(base + (types[3] & 0x7FFFFFFF))}
+        best = None
+        for _, o, _ in leaves(base + (types[14] & 0x7FFFFFFF)):
+            count = struct.unpack_from("<H", data, o + 4)[0]
+            for k in range(count):
+                w, h, colors, _, planes, bits, size, icon_id = struct.unpack_from("<BBBBHHIH", data, o + 6 + 14 * k)
+                area = (w or 256) * (h or 256) * max(bits, 1)
+                if icon_id in icons and (best is None or area > best[0]):
+                    best = (area, icon_id, w, h, bits)
+        if not best:
+            return None
+        o, size = icons[best[1]]
+        raw = data[o:o + size]
+        if raw[:4] == b"\x89PNG":
+            return raw
+        # a DIB: wrap it as a one-image .ico and let Pillow decode it
+        w, h, bits = best[2], best[3], best[4]
+        ico = struct.pack("<HHH", 0, 1, 1) + struct.pack("<BBBBHHII", w, h, 0, 0, 1, bits, len(raw), 22) + raw
+        import io
+
+        from PIL import Image
+
+        with Image.open(io.BytesIO(ico)) as im:
+            out = io.BytesIO()
+            im.convert("RGBA").save(out, "PNG")
+            return out.getvalue()
+    except Exception:  # noqa: BLE001 - any malformed resource: no icon
+        return None
+
+
+# ------------------------------------------------------------------------------------------ folder walk
+@dataclass
+class Tree:
+    root: Path
+    exes: list[Path] = field(default_factory=list)  # every .exe (unfiltered)
+    dlls: dict[str, Path] = field(default_factory=dict)  # lower-case name -> first path
+    has_apk: bool = False
+    size: int = 0
+    files: int = 0
+    manifest: dict | None = None
+
+    def child_of(self, p: Path) -> str:
+        rel = p.relative_to(self.root).parts
+        return rel[0] if len(rel) > 1 else "."
+
+
+def walk(root: Path, max_depth: int = MAX_DEPTH) -> Tree:
+    """One pass over a folder: exes, dll names, apk presence, total size (and an Oculus manifest json if present)."""
+    root = Path(root)
+    t = Tree(root)
+    stack = [(root, 0)]
+    while stack:
+        d, depth = stack.pop()
+        try:
+            it = os.scandir(d)
+        except OSError:
+            continue
+        with it:
+            for e in it:
+                try:
+                    if e.is_dir(follow_symlinks=False):
+                        if depth < max_depth and e.name.lower() not in PRUNE_DIRS:
+                            stack.append((Path(e.path), depth + 1))
+                        continue
+                    name = e.name.lower()
+                    t.files += 1
+                    try:
+                        t.size += e.stat(follow_symlinks=False).st_size
+                    except OSError:
+                        pass
+                    if name.endswith(".exe"):
+                        t.exes.append(Path(e.path))
+                    elif name.endswith(".dll"):
+                        t.dlls.setdefault(name, Path(e.path))
+                    elif name.endswith(".apk"):
+                        t.has_apk = True
+                    elif name.endswith(".json") and depth <= 2 and t.manifest is None and e.stat().st_size < 1 << 20:
+                        t.manifest = _manifest(Path(e.path))
+                except OSError:
+                    continue
+    return t
+
+
+def _manifest(path: Path) -> dict | None:
+    """Oculus CoreData manifest (<canonicalName>.json with launchFile)."""
+    try:
+        d = json.loads(path.read_text(encoding="utf-8", errors="replace"))
+    except (OSError, ValueError):
+        return None
+    if isinstance(d, dict) and d.get("launchFile") and (d.get("canonicalName") or d.get("appId")):
+        return d
+    return None
+
+
+def candidates(tree: Tree) -> list[Path]:
+    """Programs that could start the game: not an installer/helper, a Windows GUI program for x86/x64."""
+    out = []
+    for p in tree.exes:
+        if SKIP_EXE.search(p.name):
+            continue
+        try:
+            h = pe_header(p)
+        except (PEError, OSError):
+            continue
+        if h.machine in ("x86", "x86_64") and h.subsystem == GUI_SUBSYSTEM:
+            out.append(p)
+    return out
+
+
+# ------------------------------------------------------------------------------------------ naming
+_TAG_WORDS = r"(?:ARMGDDN|VRP|JF|FFA|Repacks?|Shipping|GOG|CODEX|PLAZA|FitGirl|DODI|ElAmigos|Oculus|Rift|PCVR)"
+
+
+def clean_title(name: str) -> str:
+    """'Asgards Wrath v1.6.0 -ARMGDDN' -> 'Asgards Wrath'; 'Arktika 1 (v1.0.0.7) -VRP' -> 'Arktika 1';
+    'Vader Immortal - Episode II v2.0.2+236948 Shipping' -> 'Vader Immortal - Episode II'."""
+    t = re.sub(r"\[[^\]]*\]", " ", name)  # [FFA Repacks]
+    t = re.sub(r"\((?:[^)]*\d[^)]*|[^)]*" + _TAG_WORDS + r"[^)]*)\)", " ", t, flags=re.I)  # (v1.0.0.7)
+    t = re.sub(r"\s-\s*" + _TAG_WORDS + r"\b.*$", " ", t, flags=re.I)  # -ARMGDDN, -VRP v76
+    t = re.sub(r"\bv\d[\w.+\-]*", " ", t, flags=re.I)  # v1.6.0, v008, v2.0.2+236948
+    t = re.sub(r"(?<![\w.])\d+(?:\.\d+){2,}[\w+\-]*", " ", t)  # 4.15.20, 21.11.08.358012
+    t = re.sub(r"\b" + _TAG_WORDS + r"\b", " ", t, flags=re.I)
+    t = re.sub(r"[_]+", " ", t)
+    t = re.sub(r"\s+", " ", t).strip(" -_.")
+    return t or name.strip()
+
+
+def slug(name: str) -> str:
+    s = re.sub(r"[^A-Za-z0-9]+", "_", name).strip("_").lower() or "game"
+    return ("g" + s) if s[0].isdigit() else s
+
+
+def game_id(folder: Path, manifest: dict | None = None) -> str:
+    base = (manifest or {}).get("canonicalName") or clean_title(folder.name)
+    return "rift." + slug(base)
+
+
+def _norm(s: str) -> str:
+    return re.sub(r"[^a-z0-9]", "", s.lower())
+
+
+# ------------------------------------------------------------------------------------------ ranking
+def rank_exes(folder: Path, cands: list[Path], manifest: dict | None = None,
+              dlls: dict[str, Path] | None = None) -> list[dict]:
+    """Candidates best-first: {path (relative, /), score, reasons, size, machine}."""
+    folder = Path(folder)
+    title = _norm(clean_title(folder.name))
+    launch = (manifest or {}).get("launchFile", "").replace("\\", "/").lower()
+    out = []
+    for p in cands:
+        rel = p.relative_to(folder).as_posix()
+        score, reasons = 0, []
+        stem = p.stem.lower()
+        if launch and rel.lower().endswith(launch):
+            score += 1000
+            reasons.append("named in the Oculus manifest")
+        if stem.endswith("-win64-shipping") or stem.endswith("-win32-shipping"):
+            score += 50
+            reasons.append("Unreal game build")
+        elif (p.parent / "UnityPlayer.dll").exists() or (p.parent / f"{p.stem}_Data").is_dir():
+            score += 50
+            reasons.append("Unity game (next to its data)")
+        if list(p.parent.glob(f"*/Binaries/Win64/{p.stem}-Win64-Shipping.exe")):
+            score -= 30
+            reasons.append("Unreal launcher (starts the real game build)")
+        n = _norm(p.stem.replace("-Win64-Shipping", ""))
+        if n and title and (n in title or title in n or n[:4] == title[:4]):
+            score += 20
+            reasons.append("name matches the game")
+        try:
+            machine = pe_header(p).machine
+        except (PEError, OSError):
+            machine = "?"
+        if machine == "x86_64":
+            score += 5
+            reasons.append("64-bit")
+        try:
+            sib = {x.name.lower() for x in p.parent.iterdir()}
+        except OSError:
+            sib = set()
+        if sib & set(REVIVE_DLLS) and sib & set(LOADER_DLLS):
+            score += 40
+            reasons.append("set up for SteamVR by the repack (bundled Revive + loader)")
+        parts = [x.lower() for x in p.relative_to(folder).parts[:-1]]
+        if any("steam" in x for x in parts):
+            score -= 10
+            reasons.append("Steam build")
+        if any(x in ("win7", "dx11") for x in parts):
+            reasons.append(parts[-1])
+        size = p.stat().st_size
+        score += min(10, size // (40 << 20)) - len(parts)
+        out.append({"path": rel, "score": score, "reasons": reasons, "size": size, "machine": machine})
+    return sorted(out, key=lambda c: (-c["score"], c["path"]))
+
+
+def is_ambiguous(ranked: list[dict]) -> bool:
+    return len(ranked) > 1 and ranked[0]["score"] < 1000 and ranked[1]["score"] >= ranked[0]["score"] - AMBIGUITY
+
+
+def find_exe(folder: Path) -> Path | None:
+    """The best program to start the game (used by callers that only need one)."""
+    tree = walk(folder)
+    ranked = rank_exes(folder, candidates(tree), tree.manifest)
+    return Path(folder) / ranked[0]["path"] if ranked else None
+
+
+# ------------------------------------------------------------------------------------------ analysis
+def fingerprint(folder: Path, exe_rel: str) -> str:
+    p = Path(folder) / exe_rel
+    try:
+        st = p.stat()
+        return f"{exe_rel}:{st.st_size}:{int(st.st_mtime)}"
+    except OSError:
+        return ""
+
+
+def analyze(folder: Path, exe: str | None = None, tree: Tree | None = None) -> Analysis:
+    """exe: a relative path chosen by the user (else the best-ranked candidate)."""
+    folder = Path(folder)
+    tree = tree or walk(folder)
+    manifest = tree.manifest
+    ranked = rank_exes(folder, candidates(tree), manifest, tree.dlls)
+    if exe:
+        chosen = exe
+        confirmed = True
+    elif ranked:
+        chosen = ranked[0]["path"]
+        confirmed = not is_ambiguous(ranked)
+    else:
+        raise PEError(f"no game program found in {folder}")
+    exe_path = folder / chosen
+    info, data = read_pe(exe_path)
+    names = set(tree.dlls)
+    unity = (exe_path.parent / "UnityPlayer.dll").exists() or (exe_path.parent / f"{exe_path.stem}_Data").is_dir() \
+        or "unityplayer.dll" in names
+    unreal = exe_path.name.lower().endswith("-shipping.exe") or "engine" in [x.lower() for x in exe_path.parts]
+    engine = "Unity" if unity else "Unreal" if unreal else "Other"
+    blob = data
+    for extra in ("unityplayer.dll", "ovrplugin.dll"):
+        p = tree.dlls.get(extra)
+        if p:
+            try:
+                with open(p, "rb") as f:
+                    blob += f.read(64 << 20)
+            except OSError:
+                pass
+    # monolithic engines carry the Oculus code in the exe; modular Unreal builds ship it as a plugin DLL
+    # (Engine/Plugins/Runtime/OculusRift/Binaries/Win64/<Game>-OculusRift-Win64-Shipping.dll)
+    libovr = any(m in blob for m in LIBOVR_MARKERS) or \
+        any(x in n for n in names for x in ("ovrplugin", "oculushmd", "libovr", "oculusrift"))
+    openxr = "openxr_loader.dll" in info.imports or "openxr_loader.dll" in names or b"xrCreateInstance" in data
+    # OpenVR/SteamVR: the game ships/links openvr_api. NOTE: an Unreal build carries SteamVR plugin binaries + strings
+    # whether or not it uses them, so this alone does NOT prove the game runs on SteamVR — it only matters for routing
+    # when the game has NO Oculus/LibOVR code (see frame_native below). We ignore the (universal in UE) IVRSystem/
+    # VR_InitInternal string markers for exactly this reason.
+    openvr = any(d in info.imports or d in names for d in ("openvr_api64.dll", "openvr_api32.dll", "openvr_api.dll"))
+    xr = "+".join(n for n, on in (("LibOVR", libovr), ("OpenXR", openxr), ("OpenVR", openvr)) if on) or "?"
+    gfx_imports = set(info.imports)
+    up = exe_path.parent / "UnityPlayer.dll"
+    if up.exists():
+        try:
+            gfx_imports |= set(read_pe(up, 64 << 20)[0].imports)
+        except (PEError, OSError, struct.error):
+            pass
+    graphics = next((g for dll, g in GRAPHICS if dll in gfx_imports), "D3D11 or unknown")
+    # the Oculus Platform SDK (licence check, needs the Oculus app): shipped DLL, (delay-)imported by the exe, or by
+    # a modular Unreal build's OnlineSubsystemOculus plugin DLL
+    platform_imports = set(info.imports + info.delay_imports)
+    for n, p in tree.dlls.items():
+        if "onlinesubsystemoculus" in n:
+            try:
+                sub = read_pe(p, 64 << 20)[0]
+                platform_imports |= set(sub.imports + sub.delay_imports)
+            except (PEError, OSError, struct.error):
+                pass
+    platform_sdk = any(n in names for n in PLATFORM_DLLS + PLATFORM_WRAPPERS) or bool(platform_imports & set(PLATFORM_DLLS)) or \
+        b"ovr_PlatformInitializeWindows" in blob or b"ovr_Entitlement_GetIsViewerEntitled" in blob
+    # how to start it with VR on SteamVR / the Frame (see launch_mode())
+    try:
+        exe_dir = {p.name.lower() for p in exe_path.parent.iterdir()}
+    except OSError:
+        exe_dir = set()
+    loader = sorted(n for n in exe_dir if n in LOADER_DLLS) if exe_dir & set(REVIVE_DLLS) else []
+    mode, args, args_from = launch_mode(folder, chosen, engine, libovr, openxr, openvr, loader)
+    canonical_hint = next((part for part in exe_path.relative_to(folder).parts[:-1]
+                           if re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+){2,}", part)), None)  # Oculus Software dir name
+    title = (manifest or {}).get("displayName") or clean_title(folder.name)
+    return Analysis(
+        package=game_id(folder, manifest), version=str((manifest or {}).get("version") or ""), label=title,
+        abis=[info.machine], engine=engine, xr=xr, graphics=graphics, direct_vrapi=False, libs=sorted(names)[:200],
+        launcher_activity=None, has_info_category=False, meta_permissions=[], uses_glad_gl=False, unity_msaa_levels=0,
+        oculus_os_classes=False, is_overport_output=False, debuggable=False,
+        extra={"kind": "rift", "exe": chosen, "folder": str(folder), "exe_candidates": ranked[:12],
+               "exe_confirmed": confirmed, "fingerprint": fingerprint(folder, chosen),
+               "platform_sdk": platform_sdk, "openxr_native": openxr and not libovr,
+               "openvr_native": openvr and not libovr,
+               # frame_native = confidently runs on the Frame through wineopenxr (SteamVR), no Revive: only when there
+               # is NO Oculus/LibOVR code (pure OpenXR or pure OpenVR). A LibOVR game is treated as Oculus (needs
+               # Revive, PC only) unless a known-good catalog recipe overrides it (e.g. Rick and Morty, verified on
+               # the Frame) — static analysis can't tell which runtime a dual-API Unreal build picks at runtime.
+               # launch: "repack" (bundled Revive, started by its loader DLL: run the exe directly), "native"
+               # (SteamVR/OpenXR: run the exe directly, with launch_args) or "revive" (inject FramePort's Revive)
+               "launch": mode, "loader_dlls": loader, "launch_args": args, "launch_args_from": args_from,
+               "frame_native": mode == "native",
+               "needs_revive": mode == "revive",
+               "vr_found": xr != "?", "data_bytes": tree.size, "files": tree.files,
+               # a LibRevive*.dll anywhere in the folder (see "launch" for whether the game actually starts it)
+               "revive_bundled": any(n in names for n in ("librevive64.dll", "librevive32.dll", "librevivexr64.dll",
+                                                          "librevivexr32.dll")),
+               "oculus_app_id": (manifest or {}).get("appId"),
+               "canonical_name": (manifest or {}).get("canonicalName") or canonical_hint},
+    )
+
+
+def _vd_to_steamvr(args: str) -> str:
+    """Virtual Desktop launcher arguments → the SteamVR/OpenXR equivalent (Unreal's Oculus HMD module → OpenXR)."""
+    return re.sub(r"(?i)(-hmd=)Oculus(XR)?HMD\b", r"\1OpenXR", args).strip()
+
+
+def vd_args(folder: Path, exe_rel: str) -> str | None:
+    """Arguments the repack's Virtual Desktop launcher (VD.bat next to the exe) passes to the game."""
+    try:
+        text = ((folder / exe_rel).parent / "VD.bat").read_text(errors="replace")
+    except OSError:
+        return None
+    m = re.search(r'"?' + re.escape(Path(exe_rel).name) + r'"?[ \t]*([^\r\n]*)', text, re.I)
+    return m.group(1).strip() if m else None
+
+
+def launch_mode(folder: Path, exe_rel: str, engine: str, libovr: bool, openxr: bool, openvr: bool,
+                loader: list[str]) -> tuple[str, str, str]:
+    """(mode, game arguments, where the arguments come from), from the game files alone.
+
+    repack: the exe's folder has a bundled Revive and a proxy DLL (xinput*.dll) that starts it — the repack is
+            already set up for SteamVR; launching it through another Revive breaks it (two Revives; e.g. the Oculus
+            Platform entitlement check then fails). Run the exe directly.
+    native: no Oculus code, or a dual-API build that also ships SteamVR/OpenXR support (Unreal's OpenVR/OpenXR
+            plugin under Engine/Binaries/ThirdParty, Unity's openvr_api plugin): run the exe directly with the
+            SteamVR/OpenXR runtime selected by arguments — the repack's VD.bat arguments with the Oculus module
+            swapped for OpenXR, else Unreal's -hmd= / Unity's -vrmode.
+    revive: Oculus-only (LibOVR/OVRPlugin): FramePort's Revive injector translates it."""
+    if loader:
+        return "repack", "", "the repack's own launcher (bundled Revive)"
+    if not libovr and (openxr or openvr):
+        return "native", "", ""
+    if engine in ("Unreal", "Unity") and (openxr or openvr):
+        vd = vd_args(folder, exe_rel)
+        if vd:
+            return "native", _vd_to_steamvr(vd), "VD.bat (Oculus HMD module → OpenXR)"
+        if engine == "Unity":
+            return "native", "-vrmode OpenVR", "Unity build with SteamVR support"
+        return ("native", "-hmd=OpenXR", "Unreal build with the OpenXR plugin") if openxr else \
+            ("native", "-hmd=SteamVR", "Unreal build with the SteamVR plugin")
+    return "revive", "", ""
+
+
+def is_rift(analysis: Analysis | dict) -> bool:
+    extra = analysis.get("extra", {}) if isinstance(analysis, dict) else analysis.extra
+    return (extra or {}).get("kind") == "rift"
@@ -0,0 +1,147 @@
+"""Store details for the game page (and Steam tags): description, genres, developer/publisher, release date, website
+and screenshots.
+
+Sources (cached 30 days; exact title matches only, like the artwork):
+  - OculusDB (Meta/Oculus store data): long description, genres, publisher, website — found by Quest package or by
+    the Rift app match; covers Quest and Rift games, including Oculus exclusives
+  - the Steam store (games also sold there): short description, genres, developers, publishers, release date and
+    screenshots
+Meta's own store pages refuse automated requests, so Oculus-exclusive games get no screenshots.
+Screenshots are saved as artwork/<pkg>/shot_<n>.jpg; the rest goes into the library entry's `details`.
+"""
+from __future__ import annotations
+
+import html
+import re
+import time
+import urllib.parse
+
+from ..core import cache
+from . import fetch, sources
+
+STEAM_DETAILS = "https://store.steampowered.com/api/appdetails?appids={id}&l=en"
+MAX_SHOTS = 6
+
+
+def _text(s: str | None) -> str:
+    """Store HTML/markdown-ish text → plain paragraphs."""
+    if not s:
+        return ""
+    s = re.sub(r"(?i)<br\s*/?>|</p>|</li>|</h\d>", "\n", s)
+    s = re.sub(r"<[^>]+>", "", s)
+    s = html.unescape(s)
+    s = re.sub(r"[ \t]+", " ", s)
+    return re.sub(r"\n\s*\n+", "\n\n", s).strip()
+
+
+def oculusdb_app(entry: dict) -> dict | None:
+    """The OculusDB record of this game: by Quest package, else by the Rift match."""
+    pkg = entry.get("quest_package") if entry.get("kind") == "rift" else entry["package"]
+    if pkg and "." in pkg and not pkg.startswith("rift."):
+        for r in sources.oculusdb_search(pkg, rift_only=False):
+            if r.get("packageName") == pkg:
+                return r
+    if entry.get("kind") == "rift":
+        extra = (entry.get("analysis") or {}).get("extra") or {}
+        return sources.match_rift(entry.get("title") or "", extra.get("canonical_name"))
+    return None
+
+
+def steam_app(title: str) -> dict | None:
+    hit = sources.match_steam(title)
+    if not hit:
+        return None
+    data = cache.cached_json(f"steamapp-{hit['id']}.json", STEAM_DETAILS.format(id=hit["id"]), max_age=sources.MAX_AGE,
+                             fallback={})
+    d = (data or {}).get(str(hit["id"])) or {}
+    return d.get("data") if d.get("success") else None
+
+
+def fetch_details(entry: dict, screenshots: bool = True) -> dict:
+    """Collect details for a library entry (doesn't store them; see pipeline.fetch_details)."""
+    title = entry.get("title") or entry["package"]
+    out: dict = {"sources": [], "fetched": time.time()}
+    try:
+        app = oculusdb_app(entry)
+    except Exception:  # noqa: BLE001 - offline
+        app = None
+    if app:
+        out["sources"].append("oculusdb")
+        out["description"] = _text(app.get("display_long_description"))
+        out["genres"] = [g for g in app.get("genre_names") or [] if g]
+        if app.get("publisher_name"):
+            out["publisher"] = app["publisher_name"]
+        if app.get("website_url"):
+            out["website"] = app["website_url"]
+        if app.get("id"):
+            out["store_url"] = f"https://www.meta.com/experiences/{app['id']}/"
+    try:
+        st = steam_app(title)
+    except Exception:  # noqa: BLE001
+        st = None
+    if st:
+        out["sources"].append("steam")
+        out["steam_appid"] = st.get("steam_appid")
+        out["short"] = _text(st.get("short_description"))
+        if not out.get("description"):
+            out["description"] = _text(st.get("about_the_game") or st.get("detailed_description"))
+        out["genres"] = list(dict.fromkeys((out.get("genres") or []) +
+                                           [g["description"] for g in st.get("genres") or []]))
+        out.setdefault("developer", ", ".join(st.get("developers") or []) or None)
+        out.setdefault("publisher", ", ".join(st.get("publishers") or []) or None)
+        rd = (st.get("release_date") or {}).get("date")
+        if rd:
+            out["release_date"] = rd
+        if st.get("website"):
+            out.setdefault("website", st["website"])
+        out["store_url_steam"] = f"https://store.steampowered.com/app/{st.get('steam_appid')}/"
+        if screenshots:
+            out["screenshots"] = save_screenshots(entry["package"], [s.get("path_full") for s in
+                                                                     st.get("screenshots") or []])
+    return {k: v for k, v in out.items() if v not in (None, "", [])}
+
+
+def save_screenshots(package: str, urls: list[str]) -> list[str]:
+    d = fetch.artwork_dir(package)
+    saved = []
+    for i, url in enumerate([u for u in urls if u][:MAX_SHOTS], 1):
+        path = d / f"shot_{i}.jpg"
+        if not path.exists():
+            try:
+                r = cache.http_get(url, timeout=30)
+                if r.status_code != 200 or len(r.content) < 1000:
+                    continue
+                path.write_bytes(r.content)
+            except Exception:  # noqa: BLE001
+                continue
+        saved.append(path.name)
+    for old in d.glob("shot_*.jpg"):
+        if old.name not in saved:
+            old.unlink()
+    return saved
+
+
+def screenshot_files(package: str) -> list:
+    return sorted(fetch.artwork_dir(package).glob("shot_*.jpg"), key=lambda p: int(re.sub(r"\D", "", p.stem) or 0))
+
+
+def plain_description(text: str) -> str:
+    """Store descriptions as plain text: OculusDB's carry Markdown and "[media]" placeholders for embedded videos."""
+    import re
+
+    text = re.sub(r"\[media\]", "", text or "")
+    text = re.sub(r"^\s{0,3}#{1,6}\s*", "", text, flags=re.M)        # headings
+    text = re.sub(r"(\*\*|__)(.+?)\1", r"\2", text)                  # bold
+    text = re.sub(r"\[([^\]]+)\]\((https?://[^)]+)\)", r"\1", text)  # links
+    return re.sub(r"\n{3,}", "\n\n", text).strip()
+
+
+def store_links(details: dict) -> list[tuple[str, str]]:
+    out = []
+    if details.get("store_url"):
+        out.append(("Meta store", details["store_url"]))
+    if details.get("store_url_steam"):
+        out.append(("Steam store", details["store_url_steam"]))
+    if details.get("website"):
+        out.append((urllib.parse.urlparse(details["website"]).netloc or "Website", details["website"]))
+    return out
@@ -20,6 +20,7 @@ KINDS = {
    "APP_IMG_LOGO_TRANSPARENT": "logo",
    "APP_IMG_ICON": "icon",
 }
+EXTRA_KINDS = ("square",)  # OculusDB's square cover (Rift games)


 def artwork_dir(package: str) -> Path:
@@ -32,14 +33,17 @@ def _ext(data: bytes) -> str:
    return ".png" if data[:4] == b"\x89PNG" else ".jpg"


-def fetch(package: str, apk: Path | None = None, refresh: bool = False) -> tuple[Path, str | None]:
-    """Returns (folder with <kind>.<ext> files, store display name or None)."""
+def fetch(package: str, apk: Path | None = None, refresh: bool = False,
+          lookup: str | None = None) -> tuple[Path, str | None]:
+    """Returns (folder with <kind>.<ext> files, store display name or None). `lookup` is the package whose store art
+    to use (a Rift game borrows its Quest version's art); Rift ids without one have no store art."""
    out = artwork_dir(package)
    have = {p.stem for p in out.iterdir()}
    title = None
-    if refresh or not {"portrait", "landscape", "hero", "icon"} <= have:
+    lookup = lookup or (None if package.startswith("rift.") else package)
+    if lookup and (refresh or not {"portrait", "landscape", "hero", "icon"} <= have):
        try:
-            data = cache.http_get(API.format(package=package), timeout=30).json()
+            data = cache.http_get(API.format(package=lookup), timeout=30).json()
        except Exception:
            data = {}
        if data.get("status") == "ok":
@@ -81,4 +85,4 @@ def apk_icon(apk: Path) -> bytes | None:


 def files(package: str) -> list[Path]:
-    return sorted(p for p in artwork_dir(package).iterdir() if p.stem in KINDS.values())
+    return sorted(p for p in artwork_dir(package).iterdir() if p.stem in KINDS.values() or p.stem in EXTRA_KINDS)
@@ -0,0 +1,238 @@
+"""Find artwork for games that the Meta art service (by Android package) doesn't cover — Oculus Rift games.
+
+Order (all lookups cached for 30 days; only exact title matches are used, so no wrong art is picked):
+  1. the Quest version's package (catalog, library, or OculusDB's packageName) → the full Meta art set (fetch.fetch)
+  2. OculusDB (community database of the Oculus store): the Rift app's square cover
+  3. the Steam store (games also sold on Steam): portrait, hero, landscape and logo
+  4. the game's own program icon
+"""
+from __future__ import annotations
+
+import re
+import urllib.parse
+from pathlib import Path
+
+from ..core import cache
+from . import fetch
+
+OCULUSDB = "https://oculusdb.rui2015.me"
+STEAM_SEARCH = "https://store.steampowered.com/api/storesearch/?term={term}&cc=us&l=en"
+STEAM_CDN = "https://cdn.cloudflare.steamstatic.com/steam/apps/{id}/{file}"
+STEAM_FILES = {"portrait": "library_600x900.jpg", "hero": "library_hero.jpg", "landscape": "header.jpg",
+               "logo": "logo.png"}
+MAX_AGE = 30 * 86400
+
+
+ROMAN = {"i": "1", "ii": "2", "iii": "3", "iv": "4", "v": "5", "vi": "6", "vii": "7", "viii": "8", "ix": "9", "x": "10"}
+QUEST_SUFFIXES = {"", "unplugged", "quest", "questedition", "forquest", "vr"}
+
+
+def norm(s: str) -> str:
+    """Comparable title: lower-case letters and digits only, roman numerals as digits ('Lone Echo II' = 'Lone Echo 2',
+    "Asgard's Wrath" = 'Asgards Wrath')."""
+    words = re.findall(r"[a-z0-9]+", (s or "").lower().replace("'", ""))
+    return "".join(ROMAN.get(w, w) if i and w in ROMAN else w for i, w in enumerate(words))
+
+
+def search_terms(title: str) -> list[str]:
+    """The title, then shorter forms (OculusDB's search doesn't match "Asgards" to "Asgard's")."""
+    words = re.sub(r"[^\w\s]", " ", title).split()
+    terms = [title]
+    for n in (3, 2, 1):
+        if len(words) > n and len(" ".join(words[:n])) >= 4:
+            terms.append(" ".join(words[:n]))
+    if words and len(words[0]) >= 5 and words[0].lower().endswith("s"):
+        terms.append(words[0][:-1])  # "Asgards" -> "Asgard", "Wilsons" -> "Wilson"
+    return list(dict.fromkeys(terms))
+
+
+def _key(term: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", term.lower())[:80]
+
+
+def oculusdb_search(term: str, rift_only: bool = True) -> list[dict]:
+    q = urllib.parse.quote(term)
+    url = f"{OCULUSDB}/api/v1/search/{q}" + ("?headsets=RIFT" if rift_only else "")
+    res = cache.cached_json(f"oculusdb-{'rift' if rift_only else 'all'}-{_key(term)}.json", url, max_age=MAX_AGE,
+                            fallback=[])
+    return [r for r in res or [] if isinstance(r, dict) and r.get("__OculusDBType", "Application") == "Application"]
+
+
+def steam_search(term: str) -> list[dict]:
+    res = cache.cached_json(f"steamsearch-{_key(term)}.json", STEAM_SEARCH.format(term=urllib.parse.quote(term)),
+                            max_age=MAX_AGE, fallback={})
+    return (res or {}).get("items") or []
+
+
+def match_rift(title: str, canonical: str | None = None) -> dict | None:
+    """The OculusDB Rift app for this game (exact normalized name or canonicalName match)."""
+    want = norm(title)
+    terms = ([canonical.replace("-", " ")] if canonical else []) + search_terms(title)
+    for term in terms:
+        for r in oculusdb_search(term):
+            names = {norm(r.get("appName") or ""), norm(r.get("displayName") or "")}
+            if (canonical and r.get("canonicalName") == canonical) or want in names:
+                return r
+    return None
+
+
+def match_quest(title: str) -> str | None:
+    """Package of the game's Quest version on the Meta store (same name, or the name plus a short suffix such as
+    'Unplugged'), from OculusDB."""
+    want = norm(title)
+    if len(want) < 4:
+        return None
+    for term in search_terms(title)[:2]:
+        for r in oculusdb_search(term, rift_only=False):
+            pkg = r.get("packageName")
+            n = norm(r.get("appName") or r.get("displayName") or "")
+            # same name, or the name plus a platform word ("Robo Recall: Unplugged") — never a sequel/other game
+            if pkg and n.startswith(want) and n[len(want):] in QUEST_SUFFIXES:
+                return pkg
+    return None
+
+
+def match_steam(title: str) -> dict | None:
+    want = norm(title)
+    return next((i for i in steam_search(title) if norm(i.get("name") or "") == want), None)
+
+
+def _save(package: str, kind: str, data: bytes) -> None:
+    if not data or len(data) < 200:
+        return
+    ext = ".png" if data[:4] == b"\x89PNG" else ".webp" if data[8:12] == b"WEBP" else ".jpg"
+    d = fetch.artwork_dir(package)
+    for old in d.glob(f"{kind}.*"):
+        old.unlink()
+    (d / f"{kind}{ext}").write_bytes(data)
+
+
+def _get(url: str) -> bytes | None:
+    try:
+        r = cache.http_get(url, timeout=30)
+        return r.content if r.status_code == 200 else None
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def apply_oculusdb(package: str, app: dict) -> bool:
+    link = app.get("imageLink") or (f"/cdn/images/{app['id']}" if app.get("id") else None)
+    data = _get(OCULUSDB + link) if link else None
+    if data:
+        _save(package, "square", data)
+    return bool(data)
+
+
+def apply_steam(package: str, appid: int | str) -> bool:
+    got = False
+    for kind, file in STEAM_FILES.items():
+        data = _get(STEAM_CDN.format(id=appid, file=file))
+        if data:
+            _save(package, kind, data)
+            got = True
+    return got
+
+
+def has_art(package: str) -> bool:
+    stems = {p.stem for p in fetch.files(package)}
+    return bool(stems & {"portrait", "square", "landscape", "hero"})
+
+
+def fetch_rift(package: str, title: str, canonical: str | None = None, quest_package: str | None = None,
+               exe: Path | None = None) -> dict:
+    """Find and store artwork for a Rift game. Returns what was found: {source, quest_package, oculus_app_id,
+    canonical_name, steam_appid} (only the keys that apply)."""
+    found: dict = {}
+    app = None
+    try:
+        app = match_rift(title, canonical)
+    except Exception:  # noqa: BLE001 - offline: fall through to local sources
+        app = None
+    if app:
+        found.update(oculus_app_id=app.get("id"), canonical_name=app.get("canonicalName"),
+                     title=app.get("displayName") or app.get("appName"))
+    if not quest_package:
+        try:
+            quest_package = match_quest(found.get("title") or title)
+        except Exception:  # noqa: BLE001
+            quest_package = None
+    if quest_package:
+        found["quest_package"] = quest_package
+        fetch.fetch(package, lookup=quest_package)
+        if has_art(package):
+            found["source"] = "meta"
+    if app and not found.get("source") and apply_oculusdb(package, app):
+        found["source"] = "oculusdb"
+    if found.get("source") != "meta":
+        try:
+            st = match_steam(found.get("title") or title)
+        except Exception:  # noqa: BLE001
+            st = None
+        if st and apply_steam(package, st["id"]):
+            found["steam_appid"] = st["id"]
+            found["source"] = found.get("source") or "steam"
+    if not has_art(package) and exe is not None:
+        from ..analysis.rift import exe_icon
+
+        icon = exe_icon(exe)
+        if icon:
+            _save(package, "icon", icon)
+            found["source"] = "icon"
+    return found
+
+
+def search(term: str) -> list[dict]:
+    """Candidates for the artwork picker: [{source, name, preview (URL), id|package}]."""
+    out = []
+    try:
+        for r in oculusdb_search(term, rift_only=False)[:12]:
+            link = r.get("imageLink") or (f"/cdn/images/{r['id']}" if r.get("id") else None)
+            if link:
+                out.append({"source": "Meta (Quest)" if r.get("packageName") else "Oculus Rift",
+                            "name": r.get("displayName") or r.get("appName"), "preview": OCULUSDB + link,
+                            "id": r.get("id"), "package": r.get("packageName"), "app": r})
+    except Exception:  # noqa: BLE001
+        pass
+    try:
+        for i in steam_search(term)[:8]:
+            out.append({"source": "Steam", "name": i.get("name"), "preview": STEAM_CDN.format(id=i["id"],
+                        file="header.jpg"), "id": i["id"]})
+    except Exception:  # noqa: BLE001
+        pass
+    return out
+
+
+ART_STEMS = frozenset(fetch.KINDS.values()) | frozenset(fetch.EXTRA_KINDS)
+
+
+def apply_choice(package: str, choice: dict) -> bool:
+    """Store the artwork of a picker result, replacing the current art. It's downloaded into a staging folder first:
+    when the result yields no cover (dead store image, no art for that package) the current art stays and this
+    returns False. Screenshots and the stored title are kept either way."""
+    import shutil
+
+    tmp = f".pick.{package}"
+    stage = fetch.artwork_dir(tmp)
+    shutil.rmtree(stage, ignore_errors=True)
+    stage = fetch.artwork_dir(tmp)
+    try:
+        if choice["source"] == "Steam":
+            apply_steam(tmp, choice["id"])
+        elif choice.get("package"):
+            fetch.fetch(tmp, lookup=choice["package"], refresh=True)
+            if not has_art(tmp):
+                apply_oculusdb(tmp, choice["app"])
+        else:
+            apply_oculusdb(tmp, choice["app"])
+        if not has_art(tmp):
+            return False
+        d = fetch.artwork_dir(package)
+        for f in d.iterdir():  # the old art and its thumbnails (screenshot thumbnails are t_shot_*)
+            if f.is_file() and (f.stem in ART_STEMS or f.name.startswith("t_") and not f.name.startswith("t_shot_")):
+                f.unlink()
+        for f in stage.iterdir():
+            if f.is_file() and f.stem in ART_STEMS:
+                f.replace(d / f.name)
+        return True
+    finally:
+        shutil.rmtree(stage, ignore_errors=True)
@@ -0,0 +1,129 @@
+"""A complete Steam library art set for a shortcut, composed from whatever artwork a game has.
+
+Steam wants: portrait 600×900 (library grid), landscape 920×430 (recent/horizontal), hero 1920×620 (game page banner),
+logo (transparent, drawn on the hero) and an icon. Store art rarely covers all of them — Rift games from OculusDB only
+have a square cover — so missing shapes are composed: the best source image, fitted and centred over a blurred,
+darkened copy of itself (or a screenshot, for the hero). Results are cached in artwork/<pkg>/steam/.
+"""
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from . import fetch
+
+SIZES = {"portrait": (600, 900), "landscape": (920, 430), "hero": (1920, 620)}
+# preferred sources per Steam shape, best first ("shot" = first screenshot)
+PREFER = {"portrait": ("portrait", "square", "icon", "landscape"),
+          "landscape": ("landscape", "hero", "shot", "square", "portrait"),
+          "hero": ("hero", "shot", "landscape", "square", "portrait"),
+          "icon": ("icon", "square", "portrait")}
+
+
+def _sources(package: str) -> dict[str, Path]:
+    files = {p.stem: p for p in fetch.files(package)}
+    shots = sorted(fetch.artwork_dir(package).glob("shot_*.jpg"))
+    if shots:
+        files["shot"] = shots[0]
+    return files
+
+
+def _fill(im, size):
+    """Scale to cover `size` and centre-crop."""
+    from PIL import Image
+
+    w, h = size
+    s = max(w / im.width, h / im.height)
+    im = im.resize((max(1, round(im.width * s)), max(1, round(im.height * s))), Image.LANCZOS)
+    left, top = (im.width - w) // 2, (im.height - h) // 2
+    return im.crop((left, top, left + w, top + h))
+
+
+def _compose(src: Path, size, exact: bool):
+    """exact: the source already has (about) the right shape → cover-fit; otherwise fit over a blurred backdrop."""
+    from PIL import Image, ImageEnhance, ImageFilter
+
+    with Image.open(src) as im:
+        im = im.convert("RGB")
+        w, h = size
+        if exact:
+            return _fill(im, size)
+        bg = _fill(im, size).filter(ImageFilter.GaussianBlur(radius=max(w, h) // 30))
+        bg = ImageEnhance.Brightness(bg).enhance(0.45)
+        s = min(w / im.width, h / im.height) * 0.94
+        fg = im.resize((max(1, round(im.width * s)), max(1, round(im.height * s))), Image.LANCZOS)
+        bg.paste(fg, ((w - fg.width) // 2, (h - fg.height) // 2))
+        return bg
+
+
+def _ratio_ok(src: Path, size) -> bool:
+    from PIL import Image
+
+    with Image.open(src) as im:
+        r = im.width / im.height
+    target = size[0] / size[1]
+    return abs(r - target) / target < 0.18
+
+
+def steam_set(package: str) -> dict[str, Path]:
+    """{portrait, landscape, hero, logo?, icon?} files ready for Steam (created once per source change)."""
+    src = _sources(package)
+    if not src:
+        return {}
+    out_dir = fetch.artwork_dir(package) / "steam"
+    out_dir.mkdir(exist_ok=True)
+    key = hashlib.sha1("|".join(f"{k}:{p.stat().st_size}:{p.stat().st_mtime_ns}" for k, p in sorted(src.items()))
+                       .encode()).hexdigest()[:8]
+    stamp = out_dir / f".{key}"
+    result: dict[str, Path] = {}
+    if stamp.exists():
+        for p in out_dir.iterdir():
+            if not p.name.startswith("."):
+                result[p.stem] = p
+        return result
+    for p in out_dir.iterdir():
+        p.unlink()
+    for kind, size in SIZES.items():
+        choice = next((k for k in PREFER[kind] if k in src), None)
+        if not choice:
+            continue
+        try:
+            # a screenshot always fills the wide banner; other sources only when their shape is close enough
+            exact = _ratio_ok(src[choice], size) or (kind == "hero" and choice == "shot")
+            img = _compose(src[choice], size, exact)
+            path = out_dir / f"{kind}.jpg"
+            img.save(path, "JPEG", quality=90, optimize=True)
+            result[kind] = path
+        except Exception:  # noqa: BLE001 - unreadable source: skip that shape
+            continue
+    if "logo" in src:
+        result["logo"] = out_dir / f"logo{src['logo'].suffix}"
+        result["logo"].write_bytes(src["logo"].read_bytes())
+    icon = next((src[k] for k in PREFER["icon"] if k in src), None)
+    if icon:
+        try:
+            from PIL import Image
+
+            with Image.open(icon) as im:
+                im = _fill(im.convert("RGBA"), (256, 256))
+                path = out_dir / "icon.png"
+                im.save(path, "PNG")
+                result["icon"] = path
+        except Exception:  # noqa: BLE001
+            pass
+    stamp.write_text("")
+    return result
+
+
+def original_platform(entry: dict) -> str:
+    return "Oculus Rift" if entry.get("kind") == "rift" else "Meta Quest"
+
+
+def steam_tags(entry: dict, where: str = "frame") -> list[str]:
+    """Tags for the Steam shortcut (Steam can group them into collections): how it runs, the game's original platform,
+    genres and the user's own tags."""
+    runs = ("PC VR on Frame" if entry.get("kind") == "rift" else "Quest on Frame") if where == "frame" else \
+        "Rift via Revive"
+    base = [runs, original_platform(entry)]
+    genres = ((entry.get("details") or {}).get("genres") or [])[:4]
+    return list(dict.fromkeys(base + genres + list(entry.get("tags") or [])))
@@ -0,0 +1,84 @@
+"""Small cached thumbnails of the artwork, served to the GUI by URL (the GUI's assets folder is the user data dir).
+
+Full-size store art is 0.3–2 MB per image; sending it as bytes on every render froze the app. Thumbnails are JPEGs named
+after their source's content hash (t_<kind>_<width>_<sha8>.jpg), so the client cache stays correct when art changes.
+"""
+from __future__ import annotations
+
+import hashlib
+import threading
+from pathlib import Path
+
+from ..core.paths import user_data_dir
+from . import fetch
+
+WIDTHS = {"portrait": 400, "square": 400, "landscape": 1280, "hero": 1280, "icon": 96, "logo": 600}
+_locks: dict[str, threading.Lock] = {}
+_guard = threading.Lock()
+
+
+def _lock(key: str) -> threading.Lock:
+    with _guard:
+        return _locks.setdefault(key, threading.Lock())
+
+
+def _digest(path: Path) -> str:
+    st = path.stat()
+    return hashlib.sha1(f"{path.name}:{st.st_size}:{st.st_mtime_ns}".encode()).hexdigest()[:8]
+
+
+def thumb(path: Path, width: int, kind: str | None = None) -> Path | None:
+    """A JPEG (PNG for logos, which need transparency) at most `width` px wide; created once."""
+    kind = kind or path.stem
+    ext = ".png" if kind == "logo" else ".jpg"
+    out = path.parent / f"t_{kind}_{width}_{_digest(path)}{ext}"
+    if out.exists():
+        return out
+    with _lock(str(out)):
+        if out.exists():
+            return out
+        try:
+            from PIL import Image
+
+            with Image.open(path) as im:
+                im.load()
+                if im.width > width:
+                    im = im.resize((width, max(1, round(im.height * width / im.width))), Image.LANCZOS)
+                for old in path.parent.glob(f"t_{kind}_{width}_*{ext}"):
+                    old.unlink(missing_ok=True)
+                tmp = out.with_suffix(out.suffix + ".tmp")
+                if ext == ".png":
+                    im.save(tmp, "PNG", optimize=True)
+                else:
+                    im.convert("RGB").save(tmp, "JPEG", quality=86, optimize=True, progressive=True)
+                tmp.replace(out)
+        except Exception:  # unreadable/odd image: use the original
+            return path
+    return out
+
+
+def pick(package: str, kinds: tuple[str, ...]) -> Path | None:
+    files = {p.stem: p for p in fetch.files(package)}
+    return next((files[k] for k in kinds if k in files), None)
+
+
+def url(package: str, kinds: tuple[str, ...], width: int | None = None) -> str | None:
+    """Asset URL (for ft.Image / DecorationImage src) of the first available kind, as a thumbnail."""
+    src = pick(package, kinds)
+    if not src:
+        return None
+    t = thumb(src, width or WIDTHS.get(src.stem, 600), src.stem)
+    return asset_url(t)
+
+
+def asset_url(path: Path) -> str:
+    return "/" + path.relative_to(user_data_dir()).as_posix()
+
+
+def prewarm(package: str) -> None:
+    """Create the thumbnails the GUI uses (cards, hero, icons) ahead of time (called after fetching art)."""
+    for kinds, width in ((("portrait", "square", "icon"), 400), (("hero", "landscape", "portrait", "square"), 1280),
+                         (("icon", "square", "portrait"), 96)):
+        src = pick(package, kinds)
+        if src:
+            thumb(src, width, src.stem)
@@ -8,7 +8,14 @@
    frameport frame discover | pair | info --frame steamos@frame.local
    frameport install <pkg> --frame steamos@frame.local [--apk-only]
    frameport test <pkg> --frame ...             # headless launch + triage
+    frameport frame proton [--install]           # Proton on the Frame, for Oculus Rift (PC VR) games
+    frameport install rift.<game> --to pc|frame  # Rift games: this PC (Revive + Steam) or the Frame (Proton)
+    frameport pc info                            # Windows Steam / SteamVR / Revive on this PC
    frameport parity --known-good <PATCHED dir>  # rebuild everything and diff against known-good APKs
+    frameport diag collect <pkg>|--all [--no-frame]  # redacted diagnostics zip (attach it to a GitHub issue)
+    frameport diag inspect <zip>                 # re-triage a diagnostics zip (no game files or Frame needed)
+    frameport diag report <pkg>                  # zip + prefilled GitHub problem report
+    frameport share-recipe <pkg> --status works  # prefilled GitHub issue submitting a working recipe
 """
 from __future__ import annotations

@@ -27,11 +34,112 @@ from .patches import base
 app = typer.Typer(add_completion=False, no_args_is_help=True, help="Port Meta Quest games to the Steam Frame.")
 tools_app = typer.Typer(help="Manage the portable toolchain.")
 frame_app = typer.Typer(help="Find and connect to a Steam Frame.")
+pc_app = typer.Typer(help="This PC as a target for Oculus Rift (PC VR) games via Revive.")
+diag_app = typer.Typer(help="Diagnostics bundles and problem reports.")
 app.add_typer(tools_app, name="tools")
 app.add_typer(frame_app, name="frame")
+app.add_typer(pc_app, name="pc")
+app.add_typer(diag_app, name="diag")


-def _target(frame: Optional[str], password: Optional[str] = None):
+def _show_version(value: bool):
+    if value:
+        from . import __version__
+
+        typer.echo(f"FramePort {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _setup(ctx: typer.Context,
+           version: bool = typer.Option(False, "--version", is_eager=True, callback=_show_version,
+                                        help="Show the FramePort version and exit.")):
+    from .core import applog
+
+    applog.setup("cli")
+    if ctx.invoked_subcommand != "update":
+        _update_hint()
+
+
+def _update_hint() -> None:
+    """At most once a day: a one-line note when a newer FramePort release exists. Never waits for the network: it
+    reads what the last check cached and refreshes a stale cache in the background for next time."""
+    import threading
+    import time
+
+    from . import updates
+
+    if updates.checks_disabled():
+        return
+    age = updates.cache_age()
+    if age is None or age > updates.CHECK_EVERY:
+        threading.Thread(target=updates.refresh_cache, daemon=True).start()
+    up = updates.cached_update()
+    today = time.strftime("%Y-%m-%d")
+    if up and library.setting("update.cli_hint") != today:
+        library.set_setting("update.cli_hint", today)
+        typer.echo(f"FramePort {up.version} is available (you have {_version()}): run \"frameport update\"", err=True)
+
+
+def _version() -> str:
+    from . import __version__
+
+    return __version__
+
+
+@app.command("update")
+def update_cmd(check: bool = typer.Option(False, "--check", help="Only say whether a newer version exists."),
+               yes: bool = typer.Option(False, "--yes", "-y", help="Don't ask before updating.")):
+    """Update FramePort to the latest release (the app, a `uv tool`/pip install, or a source checkout)."""
+    import subprocess
+
+    from . import updates
+
+    up = updates.check(force=True)
+    if not up:
+        typer.echo(f"FramePort {_version()} is the latest version.")
+        return
+    typer.echo(f"FramePort {up.version} is available (you have {_version()}). {up.page}")
+    notes = [line for line in up.notes.strip().splitlines()][:25]
+    if notes:
+        typer.echo("\n" + "\n".join("  " + line for line in notes) + "\n")
+    if check:
+        raise typer.Exit(10)  # scripts: 10 = an update is available
+    kind = updates.install_kind()
+    if kind == "source" and updates.source_is_dirty():
+        typer.echo("This source checkout has uncommitted changes: commit or stash them first.", err=True)
+        raise typer.Exit(1)
+    if not yes and not typer.confirm(f"Update now ({kind})?", default=True):
+        raise typer.Exit()
+    if kind == "bundle":
+        rep = printing_reporter()
+        app_dir = updates.prepare(up, rep)
+        updates.apply(app_dir, relaunch=False)
+        typer.echo(f"FramePort {up.version} installs as soon as this command exits.")
+        return
+    cmds = updates.upgrade_commands(up, kind)
+    if kind == "wheel" and sys.platform == "win32":
+        # the running frameport.exe can't be replaced while it runs: finish the upgrade right after this exits
+        line = " && ".join(subprocess.list2cmdline(c) for c in cmds)
+        subprocess.Popen(f'cmd /c "timeout /t 2 /nobreak >nul && {line}"', creationflags=0x00000008 | 0x00000200,
+                         close_fds=True)
+        typer.echo(f"Updating to FramePort {up.version} in the background: run `frameport --version` in a few seconds.")
+        return
+    for cmd in cmds:
+        typer.echo("$ " + " ".join(cmd))
+        if subprocess.call(cmd):
+            typer.echo("Update failed.", err=True)
+            raise typer.Exit(1)
+    typer.echo(f"Updated to FramePort {up.version}.")
+
+
+def _target(frame: Optional[str], password: Optional[str] = None, to: str = "frame"):
+    if to == "pc":
+        from .targets.pc_revive import PcReviveTarget
+
+        return PcReviveTarget()
+    if to != "frame":
+        raise typer.BadParameter("--to must be 'frame' or 'pc'")
    from .frame.connection import parse_target, saved_targets
    from .targets.frame_lepton import FrameLeptonTarget

@@ -69,11 +177,14 @@ def tools_status(check_latest: bool = typer.Option(False, "--latest", help="also


@tools_app.command("install")
-def tools_install(update: bool = typer.Option(False, help="update to the newest versions")):
+def tools_install(update: bool = typer.Option(False, help="update to the newest versions"),
+                  revive: bool = typer.Option(False, help="also install Revive (for Oculus Rift games)")):
    from .tools import overport as ov
    from .tools import toolchain

-    for s in toolchain.ensure_all(update=update):
+    for s in toolchain.ensure_all(update=update, optional=revive):
+        if s.optional and not s.installed:
+            continue
        typer.echo(f"{s.name:10} {s.version}  {s.path}")
    from .patches import overport as op

@@ -110,7 +221,8 @@ def list_games():


@app.command()
-def show(package: str, as_json: bool = typer.Option(False, "--json")):
+def show(package: str, as_json: bool = typer.Option(False, "--json"),
+         all_: bool = typer.Option(False, "--all", help="also list patches that don't apply to this game")):
    [pkg] = _pkgs(package, False)
    g = library.game(pkg)
    if as_json:
@@ -120,10 +232,16 @@ def show(package: str, as_json: bool = typer.Option(False, "--json")):
    typer.echo(f"{g.get('title')}  ({pkg} {a['version']})\n  engine {a['engine']}, XR {a['xr']}, {a['graphics']}, "
               f"ABIs {', '.join(a['abis'])}, direct VrApi: {a['direct_vrapi']}")
    typer.echo(f"  status: {r['status']}  recipe source: {r['source']}  {r['notes']}")
-    for pid, params in r["patches"].items():
-        p = base.get(pid)
-        typer.echo(f"  [x] {pid:36} {p.title}{'  ' + json.dumps(params) if params else ''}"
-                   f"{'  — ' + r['reasons'][pid] if pid in r.get('reasons', {}) else ''}")
+    from .recommend.engine import visible_patches
+
+    shown, hidden = visible_patches(library.analysis_from_dict(a), library.recipe_from_dict(r))
+    for p in (shown + hidden if all_ else shown):
+        on = p.id in r["patches"]
+        params = r["patches"].get(p.id) or {}
+        typer.echo(f"  [{'x' if on else ' '}] {p.id:36} {p.title}{'  ' + json.dumps(params) if params else ''}"
+                   f"{'  — ' + r['reasons'][p.id] if on and p.id in r.get('reasons', {}) else ''}")
+    if hidden and not all_:
+        typer.echo(f"  ({len(hidden)} patches hidden as not relevant for this game; --all to list them)")
    if r.get("alt_patches"):
        typer.echo(f"  alternate build adds: {', '.join(r['alt_patches'])}  (installed: {'alt' if r['use_alt'] else 'primary'})")

@@ -139,7 +257,9 @@ def patches():
@app.command()
 def recipe(package: str, enable: list[str] = typer.Option([], "--enable"), disable: list[str] = typer.Option([], "--disable"),
           set_: list[str] = typer.Option([], "--set", help="adapter setting key=value"),
-           use_alt: Optional[bool] = typer.Option(None, "--use-alt/--no-alt"), reset: bool = False):
+           use_alt: Optional[bool] = typer.Option(None, "--use-alt/--no-alt"), reset: bool = False,
+           as_is: Optional[bool] = typer.Option(None, "--as-is/--patch", help="install unchanged (already patched)"),
+           exe: Optional[str] = typer.Option(None, help="Rift games: the program that starts the game (relative)")):
    """Change a game's patch selection."""
    [pkg] = _pkgs(package, False)
    r = pipeline.reset_recipe(pkg) if reset else library.recipe_from_dict(library.game(pkg)["recipe"])
@@ -154,7 +274,14 @@ def recipe(package: str, enable: list[str] = typer.Option([], "--enable"), disab
        r.patches[f"adapter.{k}"] = {"value": float(v) if "." in v else int(v)}
    if use_alt is not None:
        r.use_alt = use_alt
-    r.source = "user" if (enable or disable or set_ or use_alt is not None) else r.source
+    if as_is is not None:
+        r.as_is = as_is
+        if library.game(pkg).get("kind") == "rift":
+            r.patches.pop("pcvr.revive", None) if as_is else r.patches.setdefault("pcvr.revive", {})
+    if exe:
+        pipeline.set_exe(pkg, exe)
+        r = library.recipe_from_dict(library.game(pkg)["recipe"])
+    r.source = "user" if (enable or disable or set_ or use_alt is not None or as_is is not None) else r.source
    pipeline.set_recipe(pkg, r)
    show(pkg)

@@ -169,7 +296,7 @@ def build(package: Optional[str] = typer.Argument(None), all_: bool = typer.Opti
        rep = printing_reporter(verbose)
        try:
            info = pipeline.build_game(pkg, rep, outdir / pkg if outdir and all_ else outdir)
-            typer.echo(f"{pkg}: {'OK' if info['ok'] else 'CHECKS FAILED'} -> {info['apk']}")
+            typer.echo(f"{pkg}: {'OK' if info['ok'] else 'CHECKS FAILED'} -> {info.get('apk') or 'ready (Rift game)'}")
            if not info["ok"]:
                failed.append(pkg)
        except Exception as exc:  # noqa: BLE001
@@ -182,20 +309,26 @@ def build(package: Optional[str] = typer.Argument(None), all_: bool = typer.Opti
 def install(package: Optional[str] = typer.Argument(None), all_: bool = typer.Option(False, "--all"),
            frame: Optional[str] = typer.Option(None, help="steamos@host"), password: Optional[str] = None,
            apk_only: bool = typer.Option(False, help="reuse game data already on the Frame"),
-            no_library: bool = typer.Option(False, help="don't add to the Steam library now")):
-    target = _target(frame, password)
+            no_library: bool = typer.Option(False, help="don't add to the Steam library now"),
+            to: str = typer.Option("frame", help="frame, or pc (Oculus Rift games only: run on this PC via Revive)"),
+            apk: Optional[Path] = typer.Option(None, help="install this APK instead of the last build (one game; e.g. "
+                                                          "a test build signed with the game's key)")):
+    target = _target(frame, password, to)
    pkgs = _pkgs(package, all_)
+    if apk and len(pkgs) != 1:
+        raise typer.BadParameter("--apk needs exactly one game")
    for pkg in pkgs:
-        pipeline.install_game(pkg, target, printing_reporter(False), apk_only, add_to_library=False)
+        pipeline.install_game(pkg, target, printing_reporter(False), apk_only, add_to_library=False, apk=apk)
    if not no_library:
        target.add_to_library(pkgs, printing_reporter(False))


@app.command()
 def test(package: Optional[str] = typer.Argument(None), all_: bool = typer.Option(False, "--all"),
-         frame: Optional[str] = None, seconds: int = 45):
-    """Headless launch on the Frame + log triage."""
-    target = _target(frame)
+         frame: Optional[str] = None, seconds: int = 45,
+         to: str = typer.Option("frame", help="frame, or pc (Rift games installed on this PC)")):
+    """Headless launch on the Frame (or this PC) + log triage."""
+    target = _target(frame, to=to)
    installed = {g["package"] for g in target.installed()}
    for pkg in _pkgs(package, all_):
        if pkg not in installed:
@@ -278,11 +411,92 @@ def frame_cleanup(frame: Optional[str] = None, keep_rollback: bool = typer.Optio
    typer.echo(f"removed {len(r['removed'])} item(s), freed {r['freed_bytes'] / 2**30:.1f} GiB")


+@frame_app.command("send")
+def frame_send(paths: list[Path] = typer.Argument(..., help="files or folders to send"),
+               to: str = typer.Option("videos", help="destination: videos, downloads, documents, app, app-files"),
+               game: Optional[str] = typer.Option(None, help="package of the game, for --to app / app-files"),
+               folder: str = typer.Option("", help="sub-folder inside the destination"),
+               app: Optional[str] = typer.Option(None, help="package of a player: also add the files to its own folder "
+                                                            "(e.g. 4XVR lists /sdcard/4XPlayer, not Movies)"),
+               frame: Optional[str] = None):
+    """Send files to apps on the Frame. videos/downloads/documents are shared by every Quest game (they appear as
+    /sdcard/Movies, /sdcard/Download, /sdcard/Documents); app/app-files are one game's own storage. Apps find the
+    files by browsing folders (Android's media index doesn't work in Lepton)."""
+    from .install import files
+
+    r = files.send_files(_target(frame).frame, paths, to, game, folder, printing_reporter(), link_app=app)
+    typer.echo(f"sent {r['files']} file(s) ({r['bytes'] / 2**20:.0f} MiB, {r['skipped']} already there); "
+               f"in the app: {r['android']}")
+
+
+@frame_app.command("storage")
+def frame_storage(game: Optional[str] = None, frame: Optional[str] = None):
+    """Where files for Lepton apps go on the Frame (and where the apps see them)."""
+    from .install import files
+
+    for t in files.storage_targets(_target(frame).frame, game):
+        typer.echo(f"{t['id']:10} {t['android']:45} {t['path']}" + ("  (every app)" if t["shared"] else ""))
+
+
@frame_app.command("info")
 def frame_info(frame: Optional[str] = None):
    typer.echo(json.dumps(_target(frame).describe(), indent=1, default=str))


+@frame_app.command("controller-models")
+def frame_controller_models(frame: Optional[str] = None,
+                            convert: bool = typer.Option(False, help="also convert them (cached on the Frame)")):
+    """SteamVR render models on the Frame and which ones serve as Steam Frame controller models (controller_models)."""
+    typer.echo(json.dumps(_target(frame).frame.agent("controller_models", convert=convert), indent=1))
+
+
+@frame_app.command("proton")
+def frame_proton(frame: Optional[str] = None,
+                 install_: bool = typer.Option(False, "--install", help="install it (Steam on the Frame restarts once "
+                                               "and downloads it; waits until done)"),
+                 in_headset: bool = typer.Option(False, help="with --install: only ask Steam (confirm in the headset)"),
+                 test: bool = typer.Option(False, "--test", help="run a Windows program under Proton on the Frame"),
+                 tool: Optional[str] = typer.Option(None, help="compat tool name, e.g. proton-experimental-arm64")):
+    """Proton (ARM64) on the Frame, needed for Oculus Rift (PC VR) games."""
+    t = _target(frame)
+    if test:
+        r = t.proton_selftest(tool)
+        r.pop("log_tail", None)
+        typer.echo(json.dumps(r, indent=1))
+        raise typer.Exit(0 if r.get("ran") else 1)
+    if install_ and in_headset:
+        typer.echo(json.dumps(t.install_proton(False, tool), indent=1))
+        return
+    if install_:
+        from .install.installer import ensure_proton
+
+        ready = ensure_proton(t.frame, printing_reporter(False), tool)
+        typer.echo(f"ready: {ready['display_name']}")
+        return
+    st = t.proton_status(tool)
+    for p in st["tools"]:
+        state = "installed" if p["installed"] and p["require_installed"] else \
+            "needs runtime" if p["installed"] else "not installed"
+        typer.echo(f"{p['name']:28} {p['display_name']:32} {state}")
+    typer.echo(f"ready: {st['ready']['name'] if st.get('ready') else 'no (frameport frame proton --install)'}")
+    typer.echo(f"OpenXR runtime: {(st.get('openxr') or {}).get('name') or 'none'}")
+
+
+# ------------------------------------------------------------------------------------------ pc (Revive)
+@pc_app.command("info")
+def pc_info():
+    typer.echo(json.dumps(_target(None, to="pc").describe(), indent=1, default=str))
+
+
+@pc_app.command("install-revive")
+def pc_install_revive():
+    """Download Revive's latest release and unpack it into FramePort's tools (no installer, no admin rights)."""
+    from .tools import revive
+
+    path = revive.install(lambda f: None)
+    typer.echo(f"Revive {revive.installed_version()} at {path}")
+
+
 # ------------------------------------------------------------------------------------------ parity
@app.command()
 def parity(known_good: Path = typer.Option(..., help="folder of known-good game folders (PATCHED layout)"),
@@ -316,6 +530,130 @@ def parity_device(results: Path = typer.Option(Path("parity-out/parity.json")),
    raise typer.Exit(0 if ok else 1)


+@app.command("uninstall-app")
+def uninstall_app(frame: bool = typer.Option(False, help="also remove FramePort's games and files from the Frame"),
+                  keep_frame_saves: bool = typer.Option(True, help="with --frame: keep game saves on the Frame"),
+                  backup_keys: Optional[Path] = typer.Option(None, help="folder for a zip of the signing keys "
+                                                                          "(default: your Documents folder)"),
+                  backup: bool = typer.Option(True, "--backup/--no-backup", help="back up the signing keys first"),
+                  yes: bool = typer.Option(False, "--yes", "-y", help="don't ask for confirmation")):
+    """Remove everything FramePort created on this PC (and optionally on the Frame). Then delete the app itself."""
+    from . import uninstall as un
+
+    target = _target(None) if frame else None
+    info = target.describe() if target else None
+    pl = un.plan(info)
+    typer.echo("This removes:")
+    for it in pl.items:
+        typer.echo(f"  - {it.what}" + (f"  ({it.path})" if it.path else "") +
+                   (f"  {it.size / 2**30:.1f} GiB" if it.size > 2**28 else ""))
+    dest = (backup_keys or un.default_backup_dir()) if backup else None
+    typer.echo(f"Signing keys: {len(pl.keys)} " + ("(not backed up!)" if dest is None else f"→ backup zip in {dest}"))
+    if not yes and not typer.confirm("Uninstall FramePort?", default=False):
+        raise typer.Exit(1)
+    out = un.run(printing_reporter(False), target.frame if target else None, keep_frame_saves, dest, frame)
+    typer.echo("Done." + (f" Keys backup: {out['backup']}" if out.get("backup") else "") +
+               " Delete the FramePort program folder to finish (or `uv tool uninstall frameport`).")
+
+
+# ------------------------------------------------------------------------------------------ diagnostics / sharing
+def _diag_target(no_frame: bool, frame: Optional[str], to: str):
+    if no_frame:
+        return None
+    try:
+        return _target(frame, to=to)
+    except Exception as exc:  # noqa: BLE001  (offline Frame: PC-side data only)
+        typer.echo(f"({to} not reachable: {exc}; collecting the PC side only)")
+        return None
+
+
+def _open(url: str, browser: bool) -> None:
+    from .core import winhost
+
+    typer.echo(url)
+    if browser and not winhost.open_url(url):
+        typer.echo("(couldn't open a browser: open the link above)")
+
+
+@diag_app.command("collect")
+def diag_collect(package: Optional[str] = typer.Argument(None, help="a game (omit for app-wide logs only)"),
+                 all_: bool = typer.Option(False, "--all"), frame: Optional[str] = None,
+                 no_frame: bool = typer.Option(False, "--no-frame", help="don't contact the Frame"),
+                 to: str = typer.Option("frame", help="where the game is installed: frame or pc"),
+                 out: Optional[Path] = typer.Option(None, help="folder or .zip path (default: Documents)")):
+    """Write a redacted diagnostics zip: logs, recipe, analysis, device info (no game files, no personal data)."""
+    pkgs = _pkgs(package, all_) if (package or all_) else []
+    path = pipeline.collect_diagnostics(pkgs, _diag_target(no_frame, frame, to), printing_reporter(False), out)
+    typer.echo(f"wrote {path}")
+
+
+@diag_app.command("inspect")
+def diag_inspect(bundle: Path, as_json: bool = typer.Option(False, "--json")):
+    """Summarize a diagnostics zip and re-triage its launch logs with this version's signatures."""
+    from .diag import bundle as b
+
+    res = b.read(bundle)
+    if as_json:
+        typer.echo(json.dumps(res, indent=1, default=str))
+        return
+    m = res["manifest"]
+    env = m.get("env", {})
+    typer.echo(f"created {m.get('created')} by FramePort {env.get('app')}; {env.get('os')}; "
+               f"Frame: {(env.get('frame') or {}).get('build_id') or '-'}")
+    for w in m.get("warnings", []):
+        typer.echo(f"  warning: {w}")
+    for pkg, g in res["games"].items():
+        typer.echo(f"\n{pkg} — {g.get('title')} [{g.get('status')}]")
+        last = g.get("last_test") or {}
+        if last:
+            typer.echo(f"  last test: {last.get('state')} ({last.get('verdict')}) furthest: {last.get('milestone')}")
+        t = g.get("triage")
+        if t:
+            typer.echo(f"  re-triage of {g['log']}: {t['verdict']}, furthest: {t['milestone']}")
+            for f in t["findings"]:
+                typer.echo(f"    {f['severity']:7} {f['id']}: {f['diagnosis']}\n            {f['evidence'][:200]}")
+            if t["suggestions"]:
+                typer.echo(f"  suggested patches: {', '.join(t['suggestions'])}")
+
+
+@diag_app.command("report")
+def diag_report(package: Optional[str] = typer.Argument(None), description: str = typer.Option("", "--text"),
+                frame: Optional[str] = None, no_frame: bool = typer.Option(False, "--no-frame"),
+                to: str = typer.Option("frame"), out: Optional[Path] = None,
+                browser: bool = typer.Option(True, "--browser/--no-browser")):
+    """Collect a diagnostics zip and open a prefilled GitHub problem report (attach the zip there)."""
+    from .core import winhost
+
+    pkgs = _pkgs(package, False) if package else []
+    target = _diag_target(no_frame, frame, to)
+    info = None
+    if target is not None:
+        try:
+            info = target.describe()
+        except Exception:  # noqa: BLE001
+            target = None
+    path = pipeline.collect_diagnostics(pkgs, target, printing_reporter(False), out)
+    typer.echo(f"wrote {path} — attach it to the issue")
+    if browser:
+        winhost.open_folder(path, select=True)
+    _open(pipeline.problem_report(pkgs[0] if pkgs else None, description, path, info), browser)
+
+
+@app.command("share-recipe")
+def share_recipe(package: str, status: str = typer.Option("works", help="works or issues"),
+                 notes: str = typer.Option("", help="what you checked in the headset, known issues"),
+                 frame: Optional[str] = typer.Option(None, help="include the Frame's SteamOS build"),
+                 browser: bool = typer.Option(True, "--browser/--no-browser")):
+    """Submit a working configuration: saves it as a known-good recipe and opens a prefilled GitHub issue."""
+    if status not in ("works", "issues"):
+        raise typer.BadParameter("--status must be works or issues")
+    pkg = _pkgs(package, False)[0]
+    info = None
+    if frame:
+        info = _target(frame).describe()
+    _open(pipeline.share_working_config(pkg, status, notes, info), browser)
+
+
 def main():  # pragma: no cover
    app()
Author	SHA1	Message	Date
spoopyghosty0	82c2209b6f	OVRPort 1.2.5, documentation with screenshots, store description cleanup - The overport CLI now comes from Android-XR-Bridge/OVRPort (fallback ovrport/app); its four new patches are described and shown only where they apply; parity classifies the 1.2.5 differences (VR metadata, config version, CLI-added platform compat) as expected: 34/34 at parity. - README rewritten (purpose, getting started, what works, credits, legal), INSTALL tightened, screenshots in docs/images (scripts/scrub_library.py + ui_smoke --docs --fake-frame), Quest2Frame references removed. - Game page: store descriptions without Markdown/[media] markup; themed labels on all switches. - `frameport install --apk` installs a given build (headset A/B tests).	2026-10-02 00:32:14 -04:00
spoopyghosty0	e645ca86d1	FramePort 0.3.1	2026-10-01 23:20:19 -04:00
spoopyghosty0	75c7b2bf20	Updater: run Windows PowerShell 5.1 by full path without pwsh's PSModulePath; log why a signature can't be read	2026-10-01 23:10:50 -04:00
spoopyghosty0	ba68dc76c8	Self-update for the app and the CLI FramePort finds new GitHub releases by itself and updates in one click: sidebar card + Library bar, a dialog with the release notes, "Update and restart" (download, SHA256SUMS check, Windows signer check, swap script, relaunch), optional automatic installs at the next start. CLI: --version, `frameport update [--check] [--yes]` and a once-a-day hint. One version source (_version.py); releases also ship the CLI wheel and "What's new" from the annotated tag; CI runs an update smoke test with each OS's archive.	2026-10-01 22:59:56 -04:00
spoopyghosty0	22205d17a4	One REPO_URL for the project link; project identity and no-trailer rule in CLAUDE.md	2026-10-01 21:53:06 -04:00
spoopyghosty0	2e5fcd9860	360° layers, per-game session fixes, video players, library tools FrameBridge (all new behaviour per game, off by default; hooks installed only when on): - equirect_emul (GLES only): 360° equirect/equirect2 layers, which the Frame runtime lacks, are drawn into one adapter projection layer by a worker thread with a shared EGL context. Each 360° image becomes a cube map only when it changes; the view is drawn early (from the app's xrLocateViews) with the frame's exact views. Write-once 360° picture swapchains are served by the adapter (frees runtime swapchain slots). Learned: the Frame draws quad layers above all projection layers, and doesn't reproject a projection layer from its own pose. - session_fixes: layer_debug diagnostics, stable_local, focus_hold, aim correction, refresh_rate. - Agent v26: link_media (files sent to shared folders also appear in a player's own folder), app media folder detection, launcher creates Android/data/<pkg>/{files,cache}. App: "Add videos" for players, Update all, Rescan folders (only new games), Install anyway for "Can't run" games, launch-test toggle, triage `unless`, generic source hints. Catalog: 4XVR, NEX Player, Deadpool VR (working, owner-confirmed).	2026-10-01 14:19:08 -04:00
spoopyghosty0	428e8ffe05	Quest binary fixes, PC VR launch modes + SteamVR tuning, file sending, GUI scaling Quest (Frame): - frame.swapchain_limit (default on): overport's dispatcher aborted on swapchains > 4096 px (4XVR's 7680x3840 theatre textures); guard raised to 16384. - frame.vk_sanitize (default on, Unreal): Vulkan shim (native/vkshim) that drops invalid render-pass pNext pointers; Lepton's Fossilize layer crashed Deadpool VR on them. - FrameBridge: cylinder layers (curved menus / movie screens) shown as flat quad strips (setting cylinder_strips). Equirect (360°) layers still can't be shown. - Launch tests read Lepton's crash logcat (agent v24); triage signatures for both crashes. - Send files to Lepton apps (frameport frame send/storage, GUI "Send files"): ~/Videos, ~/Downloads, ~/Documents = /sdcard/Movies, Download, Documents in every app. PC VR: - Launch modes from the game files (repack with bundled Revive -> run directly, dual-API builds -> launch args, Oculus-only -> Revive); patches pcvr.repack_launcher, pcvr.launch_args; Platform SDK games routed to the PC. - pcvr.steamvr_tuning (default on): reads SteamVR's session summary (dropped frames + compositor timeouts, fpsVR if installed) and sets per-app refresh rate / motion smoothing via fp_vrsettings.exe (OpenVR IVRSettings). GUI: upload speed / ETA, UI scale (auto from Windows DPI under WSL, Settings -> Appearance), fixed grey box in Problems & feedback.	2026-09-30 21:51:37 -04:00
spoopyghosty0	dfb4fc4ffd	Share working configs and diagnostics bundles via GitHub issues - "Share working config…" (game menu, `frameport share-recipe`): saves the recipe as known-good and opens a prefilled working-config issue form; labelling it `catalog-accepted` runs catalog-from-issue.yml, which validates the YAML (scripts/catalog_from_issue.py) and opens a PR adding catalog/games/<pkg>.yaml - "Collect logs" / "Report a problem…" (game menu, Settings, failure pop-up, `frameport diag collect\|report`): redacted diagnostics zip (app + job logs, library entry, recipe, launch logs + re-triage, APK/ELF/PE listings instead of game files, Frame launcher/settings/Lepton/logcat/XRService logs via agent v21 `collect_diag`) and a prefilled bug-report issue to attach it to; `frameport diag inspect <zip>` re-triages a bundle offline - diag/redact.py scrubs IPs, MACs, host/user names, home dirs, Steam ids, data and dump folders - App log (<data>/logs/app.log) and saved GUI job logs (<data>/logs/jobs/) - catalog.entry_from_library shared by "Save as known-good" and sharing; docs/DIAGNOSTICS.md	2026-09-30 14:14:00 -04:00
spoopyghosty0	fc4aa9c8e5	Steam Frame controller models via XR_FB_render_model (adapter controller_models) Games that ask the runtime for controller models (Meta's runtime controller models) get the Steam Frame controllers instead of Quest Touch ones: - adapter (render_model.c): emulates XR_FB_render_model when the runtime lacks it and serves files/framebridge/controller_{left,right}.glb. Off by default; suggested for games declaring the RENDER_MODEL permission/feature (none of the 34 catalog games do). - agent v20: converts the Frame's own SteamVR render models (frame_controller driver, OBJ+PNG, openxr_grip -> grip space) to glb on the device at install / set_settings; Valve's models never leave the Frame. `frameport frame controller-models` lists what it finds. - xrshim: overport's dispatcher only forwards functions in its own table ("Unknown proc addr"), so OVRPlugin's dlopen("libopenxr_loader.so") string is pointed at libframe_xrshim.so, which serves the emulated functions and forwards everything else to overport. Only added with controller_models=1; other builds differ from known-good only in the adapter binary. Verified on the device with Toy Master: models converted, adapter emulation on, all three render-model functions resolved through FrameBridge; launches match the known-good build. Not yet seen rendering in a game (none requests a model).	2026-09-30 12:58:52 -04:00
spoopyghosty0	1d83eae3ed	libovr_redirect: also place next to OVRPlugin.dll (agent v19) The Oculus SDK's LibOVRRT search differs by engine: monolithic builds (Lone Echo) use the standard DLL search (exe dir), but Unreal's OVRPlugin shim searches its own module dir. set_libovr_redirect now symlinks LibOVRRT{64,32}_1.dll in the exe dir AND next to every OVRPlugin.dll in the game tree. Verified on-device: with the redirect, Lone Echo now loads Revive's runtime and reaches Oculus API init (-3021) instead of "Unable to load LibOVRRT DLL" — the substitution works; the -3021 is the downstream signature/runtime-init stage, which this redirect deliberately does not touch (no signature bypass). 135 tests pass.	2026-09-30 10:38:52 -04:00
spoopyghosty0	c1c33d8482	LibOVRRT LoadLibrary redirect (pcvr.libovr_redirect) — runtime substitution only On the Frame, place Revive's runtime where an Oculus game's SDK looks for it, so the game can load a VR runtime — the filesystem equivalent of Revive's LoadLibrary redirect, without the inline hooking that fails under Proton-arm64 (ARM64EC). - agent v18 set_libovr_redirect: symlinks LibOVRRT{64,32}_1.dll in the exe dir to Revive's LibReviveXR runtime (kept in revive/ so its deps still resolve); only ever creates/removes its own symlink, never a real game-shipped DLL. - patch pcvr.libovr_redirect (requires pcvr.revive, on by default for Oculus Rift games, ignored on PC); installer + deployment.json wiring; migration rift_libovr_redirect for existing entries. This is pure runtime substitution. It does NOT touch the game's Oculus runtime signature check: a build that verifies LibOVRRT's signature still rejects Revive's unsigned runtime (-3021). It only helps builds that don't verify it, and gets the rest from "can't load runtime" (-3001) to the (intact) signature check. 135 tests pass. Not yet demonstrated on-device (Frame was off).	2026-09-30 10:21:52 -04:00
spoopyghosty0	94bc4c479e	PC VR playability (auto SteamVR, OpenVR backend) + honest Frame routing Make PC VR games actually reach VR, and stop mis-claiming Frame support: - PC: auto-start SteamVR on Play/launch (winhost.start_steamvr) — Oculus games ran as a flat window because SteamVR wasn't up; Revive has no runtime to bind to without it. Default PC installs to Revive's OpenVR (SteamVR) backend (pcvr.revive_openvr on) instead of the OpenXR backend that was crashing; the Frame launcher still uses /openxr. Play toast warns if SteamVR can't come up. - Routing: detect OpenVR (openvr_api imports/DLLs, not the universal-in-Unreal IVRSystem/VR_InitInternal strings). frame_native = (openxr or openvr) and not libovr; any LibOVR game is Oculus -> needs Revive -> PC only. The game page says per-game where it runs; installing an Oculus game on the Frame warns first. Rick and Morty runs on the Frame via its catalog recipe. Migration rift_frame_native re-analyzes + re-derives existing entries. Note: Oculus/LibOVR games can't run on the Frame — Revive's hooks don't work under Proton-arm64 (ARM64EC), and FramePort does not defeat the Oculus runtime Authenticode signature check. Those games are PC-only (SteamVR + Revive). Bump to 0.2.0. 133 tests pass.	2026-09-30 09:34:12 -04:00
spoopyghosty0	0cb195ec2c	Oculus Rift / PC VR support, GUI overhaul, artwork and Frame tooling Adds Oculus Rift (PC VR) games alongside Quest: - analysis/rift.py (own PE reader: imports incl. delay-imports, GUI-subsystem filter, exe ranking, icons), sources/rift_dump.py (recursive scan, one game per folder, collections), catalog rift fields + Rick and Morty recipe. - patches/pcvr.py (category "pcvr", shown as patches): Revive (LibOVR->OpenXR, default on for Oculus games), revive_openvr, no_crash_reporter (Unreal), oculus_unreal (OculusHMDConnected helper), xr_timefix (Frame OpenXR layer), proton_*. tools/revive.py (find/install Revive, never replaces the user's). - targets/pc_revive.py (run on this Windows/WSL PC via Revive + local Steam; core/winhost.py helpers) and frame_lepton Proton path; agent handles Proton install, prepare/finalize_pcvr, launch, list_files (AGENT_VERSION 17). - native/oculushmd (fp_oculushmd.exe) and native/xrlayer (Frame OpenXR 1.1->1.0 + timespec-time layer); prebuilt artifacts + SHA256SUMS. Runtime findings (Frame, SteamOS 0.4.2 / Proton 11 arm64): the SteamVR runtime only accepts OpenXR 1.0, so Proton's vrhelper (1.1) needs the compat layer; Oculus/LibOVR games need a VR runtime (Revive on PC with SteamVR, or SteamVR- native builds run directly). Platform-SDK / signature-checked repacks can't run on the Frame; those are flagged, never bypassed. GUI overhaul (ui/): streaming persistent Library with tags/filters/sort, a background job queue + activity panel, per-game page, Frame tab with installed list + file browser, Settings (incl. agent version), Play + launch-test actions, resumable/interruptible installs with up-front interventions, dark theme, help hints, uninstaller (uninstall.py). Faster uploads via a direct link (USB / Frame hotspot) when reachable. Artwork/details from OculusDB + Steam + ovrp, composed Steam art sets and tags, thumbnails served by URL. Docs (PLAYBOOK/FRAME_RUNTIME/ARCHITECTURE/INSTALL/CLAUDE.md), triage signatures, and unit tests throughout (130 pass).	2026-09-30 00:35:19 -04:00
spoopyghosty0	69889f0ad8	Dev environment lives in .venv at the repo root	2026-09-29 12:50:54 -04:00
spoopyghosty0	182b3ad5fb	CLAUDE.md: CI/release/signing notes, Frame operations, GUI testing, project status and preferences	2026-09-29 11:33:24 -04:00
spoopyghosty0	6af0c40ec8	Heuristics for uncatalogued games + hide irrelevant patches - New analysis signals: MR-only (passthrough required + boundaryless), required hand tracking, CryEngine, Unreal version, which libs reference com.oculus.os, data size. - Evidence-based detect() rules (force passthrough, scene emulation, meta permissions, controller passthrough, space warp for heavy OVRPlugin games, nodebug for old UE4 / Unreal Meta XR Audio, oculusos, Unity MSAA, CryEngine VRS config). With the catalog switched off they reproduce 33/34 verified recipes (scripts/eval_heuristics.py); Phantom's no-ForceQuit build stays a runtime (triage) finding. - Patch.applies(): GUI and CLI hide patches that can't matter for a game (engine/XR/graphics), with a show-all toggle; enabled patches are always shown.	2026-09-29 11:25:53 -04:00