FramePort 0.4.0

CLAUDE.md: queue resume verified on the device
Library cards without key= (Flet freezes keyed controls: hovering a card crashed the app with 'Frozen control cannot be updated'); Activity: progress ticks update only the progress controls and the log when it grew, instead of re-diffing the whole panel 5×/s (sluggish UI during installs)
2026-10-06 17:00:43 +02:00 · 2026-10-02 19:33:58 -04:00 · 2026-10-02 19:25:31 -04:00 · 2026-10-02 19:19:21 -04:00 · 2026-10-02 19:12:11 -04:00 · 2026-10-02 18:59:45 -04:00
207 changed files with 16092 additions and 1684 deletions
@@ -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
@@ -1,6 +1,7 @@
 name: build
 on:
  push:
+    branches: [main]
    tags: ["v*"]
  pull_request:
  workflow_dispatch:
@@ -12,10 +13,13 @@ jobs:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.2.0
      - run: uv sync --extra dev
+      - name: Lint
+        run: uv run ruff check .
      - run: uv run pytest -m "not games and not device"

  bundle:
    needs: test
+    if: github.event_name != 'push' || startsWith(github.ref, 'refs/tags/v')  # pushes to main: tests only
    permissions:
      contents: read
      id-token: write      # build provenance attestations (Sigstore)
@@ -31,9 +35,10 @@ jobs:
        include:
          - os: windows-latest
            archive: FramePort-windows-x64.zip
-          - os: macos-latest
+          - os: macos-26  # Apple Silicon + Xcode 26 (macos-15's Xcode 16.4 fails a Flutter plugin; macos-latest
+            # went unassigned on 2026-10-02)
            archive: FramePort-macos-arm64.zip
-          - os: ubuntu-latest
+          - os: ubuntu-22.04  # oldest supported: the bundle needs the build host's GLib/glibc or newer
            archive: FramePort-linux-x64.tar.gz
    runs-on: ${{ matrix.os }}
    steps:
@@ -91,6 +96,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 +117,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 +132,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,11 @@ parity-report.md
 .pytest_cache/
 native/.cache/
 native/**/build/
+# per-machine Claude Code settings (contain home paths)
+.claude/settings.local.json
+
+# maintainer-local notes for Claude Code (accounts, credentials)
+CLAUDE.local.md
+# outputs of `frameport report` / `parity` / ruff
+REPORT.md
+.ruff_cache/
@@ -14,7 +14,14 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    status_row, art_fill, confirm, `update()` = safe update: in Flet 1.0 reading `.page` of an unmounted control
    raises), `jobs.py` (background FIFO job queue, one at a time, cancel via Reporter; no Flet), `views/`
    (library: search/filters/tags/sort as pure tested helpers; game: hero + one-click install, patches under
-    "Customize"; frame: device + readiness + installed, or connect wizard; settings; welcome; activity panel).
+    "Customize"; frame: device + readiness + installed, or connect wizard; files: the Frame's file manager (persistent
+    like the library; locations = Videos/Downloads/Documents from agent `storage_targets`, each installed Quest game's
+    storage, the home folder; SFTP via `install/files.py` list_dir/upload/download/make_dir/rename/delete, all
+    confined to the location by `files.inside`; Lepton's links in a game's storage can't be renamed/deleted; replaced
+    the "Send files" dialog, game menu → "Add videos & files…" = `go("files", pkg)`; multi-select bar (download/
+    delete); drag-and-drop from the OS via the `flet-dropzone` extension (Apache-2.0, Flutter `desktop_drop`), which
+    only a `flet build` bundle contains: `files.dropzone_available()` keeps it out of source runs and the PyInstaller
+    fallback, which would show an unknown control); 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
@@ -22,6 +29,7 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    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
@@ -35,8 +43,9 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
  - **PC VR repacks are pre-patched to run directly** (proven: Rick and Morty, Vader Immortal run when the exe is
    launched directly; Revive breaks them). So Rift games default to `as_is` = install the copy unchanged and launch
    the exe directly (`pcvr.xr_timefix` for the Frame OpenXR-1.1→1.0 fix, `pcvr.no_crash_reporter` for Unreal).
-    **Revive is off by default, opt-in** (`pcvr.revive`, and `pcvr.oculus_unreal`): only for an un-cracked Oculus game
-    that fails at "Initializing OVR session". Those (Lone Echo, Robo Recall, Lies Beneath: crack .7z not extracted /
+    **Revive is only suggested for games with Oculus (LibOVR) code** (`pcvr.revive`, and `pcvr.oculus_unreal`; repacks
+    with a bundled Revive and SteamVR/OpenXR games run directly): needed by an un-cracked Oculus game that fails at
+    "Initializing OVR session". Those (Lone Echo, Robo Recall, Lies Beneath: crack .7z not extracted /
    Platform SDK) hit Revive's Oculus-runtime **signature check** under Proton-arm64 — Revive's LoadLibrary/WinVerifyTrust
    hooks don't install (ARM64EC), and the game's Oculus SDK shim rejects the unsigned Revive runtime (wintrust +
    crypt32 signer "Oculus VR") — so they don't run on the Frame without extracting the repack's crack (which FramePort
@@ -54,7 +63,15 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    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). Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
+    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
@@ -65,7 +82,8 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    package or Rift match) + Steam appdetails (exact title: developer, release date, up to 6 screenshots → artwork
    `shot_N.jpg`). Meta store pages reject scraping, so Oculus exclusives have no screenshots. Genres become automatic
    tags. Steam shortcuts get a complete composed art set (`artwork/steam.py`: 600×900 / 920×430 / 1920×620 / logo /
-    256 icon, blurred-backdrop compositing for square-only covers) and tags: how it runs, the original platform
+    256 icon, blurred-backdrop compositing for square-only covers; no store art (at most the APK icon) → a placeholder
+    set: the name on a colour from the title hash + the APK icon, `steam_set_for`; 2D Android apps get no store lookups) and tags: how it runs, the original platform
    (Meta Quest / Oculus Rift), genres, user tags — merged with tags set in Steam (non-Steam shortcuts can't hold a
    description).
  - Quest/Rift twins stay separate entries, shown and named in Steam "Title (Quest)"/"(Rift)" (`core/titles.py`).
@@ -88,6 +106,8 @@ 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` (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).
@@ -97,10 +117,38 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    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 end to end (2026-10-02): real 0.3.3 bundles on Windows and Linux (Ubuntu 22.04/WSLg) found, staged and
+    installed 0.3.4 ("Install updates automatically" path) and relaunched as 0.3.4 with settings kept. Not yet clicked
+    by hand: the "Update now" button path (same apply(), called from the running app). macOS: CI smoke only.
 - `agent/frameport_agent.py` — runs **on the Frame** (python3 stdlib only), JSON over SSH. Owns the install layout,
  launch.sh template, Steam shortcuts (binary VDF), launch tests. Bump `AGENT_VERSION` when changing it.
 - `bootstrap/bootstrap.sh` — one-time Frame setup served by the pairing server (sshd, app key, avahi service, Lepton).
- `catalog/games/<package>.yaml` — 34 recipes verified 2026-09-28; `catalog/triage.yaml` — log signatures → fixes.
+- `catalog/games/<package>.yaml` — 38 recipes (34 verified 2026-09-28; Deadpool VR, 4XVR, NEX Player and AC Nexus's
+  90 Hz default confirmed later by the owner); `catalog/triage.yaml` — log signatures → fixes.
 - `native/` — sources of the prebuilt binaries in `artifacts/` (adapter, VrApi bridge patches, GL shim, stubs).
  `native/build.py` rebuilds them with NDK r27c (downloaded on demand into `native/.cache`, git-ignored; uses
  `-ffile-prefix-map` so no local paths get embedded; zip symlinks are restored as copies). Users never need the NDK.
@@ -113,9 +161,9 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
 UV_LINK_MODE=copy uv sync --extra dev   # creates/updates ./.venv
 uv run pytest                # unit tests (no device, no game files)
 uv run frameport --help      # CLI;  uv run frameport-gui  for the GUI
-uv run frameport parity --known-good <PATCHED/_known-good-*> --sources "<VR CyberDeck downloads>"
+uv run frameport parity --known-good <PATCHED/_known-good-*> --sources "<folder with the game dumps>"
 ```
-Games/device tests: `pytest -m games` (FRAMEPORT_GAMES=<downloads dir>), `pytest -m device` (FRAMEPORT_FRAME=steamos@host);
+Games tests: `pytest -m games` (FRAMEPORT_GAMES=<downloads dir>); on-device checks are CLI commands (below);
 native layer test: `FRAMEPORT_NATIVE_TESTS=1 pytest -m native` (compiles with the NDK, ~2 min on NTFS).
 Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattributes`).
 - `FRAMEPORT_HOME=<dir>` isolates all app data (tests use it); `FRAMEPORT_JAVA/_OVERPORT_JAR/_APKSIGNER_JAR` override
@@ -123,13 +171,44 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
  artwork, frames.json, the app's SSH key which the dev Frame authorizes).
 - Device checks: `frameport test <pkg>` / `frameport parity-device --results <parity.json> --baseline <launch.txt>
  [--test-only]`; the pre-FramePort baseline is `PATCHED/_known-good-2026-09-28/_frame-state/baseline-launch.txt`.
+- Docs screenshots (`docs/images/`): `python scripts/scrub_library.py ~/.local/share/frameport <dir> --status works,issues` (copies
+  library + artwork only; titles replace folder names, local paths → `D:/Games/...`, sort by size) then
+  `FRAMEPORT_HOME=<dir> python scripts/ui_smoke.py --out <shots> --docs --fake-frame --game <pkg>` (set
+  FRAMEPORT_JAVA/_OVERPORT_JAR/_APKSIGNER_JAR so no tool download toast appears; `--viewport 1280x2600` + crop for the
+  patch list). Check every PNG for paths, IPs, user names and repack/scene names before committing.
+  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>]` and look
+  `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"`.

+## Round-2 polish (2026-10-02)
+- `errors.py`: `explain(exc)` (plain sentence for GUI + CLI), `is_connection_error`. Install/test jobs for the Frame
+  (`Job.needs_frame`) that lose the connection go back to the queue front and the queue pauses (`jobs.paused`);
+  `app._poll` retries every 10 s and resumes (owner-verified on the device 2026-10-02: the queue resumed after the
+  connection was lost). Wake lock: agent v30 `keep_awake` (systemd-inhibit idle:sleep, idle-only
+  fallback because polkit `inhibit-block-sleep` is auth_admin for non-local sessions), held while Frame jobs exist.
+- **Already converted inputs** (`analysis.is_overport_output`, e.g. the owner's library points at `PATCHED/` copies)
+  are not converted again: a second OVRPort run replaced libovrplatformloader.so and dropped its DT_NEEDED on
+  libovrstubs.so (Wallace & Gromit / Espire 2 crashed: cannot locate symbol ovr_…). Alt builds come from the saved
+  `<pkg>.alt-noforcequit.apk`, else one OVRPort run (frame.ovrstubs relinks). `missing_ovr_symbols` only counts
+  linked stub/compat libs. Converted copies in `output/` are removed after a Frame install (`build.keep_copies`).
+- Art: `.picked` marker = user's pick, automatic fetches never overwrite it and only fill missing kinds; a Meta
+  result's picture is the OculusDB image shown in the picker (the ovrp image service served "dogfooding" placeholder
+  covers for some packages, e.g. Asgard's Wrath 2). `steam_art_stale` → game page reminder. No store art → generated
+  `cover.jpg`/`banner.jpg` (APK icon via `fetch.apk_icon`).
+- Game settings dialog (`ui/views/adapter_dialog.py`, metadata `patches/settings.UI`); plain patch summaries
+  (`patches/summaries.py`, `Patch.summary`, "Show technical details" = setting `ui.patch_details`); share nudge
+  (`views/game.should_ask_to_share`); saving a recipe keeps its status (was always "works").
+
 ## Hard-won facts (don't re-learn these)
 **Frame runtime (SteamOS 0.3.0, build 20260922):**
 - No AArch32: 32-bit-only APKs fail with `INSTALL_FAILED_NO_MATCHING_ABIS`. Unfixable; point to Rift + Revive.
@@ -147,6 +226,10 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
  flags 0x3. So automated tests prove startup (process alive, instance/session created, frames paced), never visuals.

 **Lepton:** needs an activity with category **LAUNCHER** (Quest apps often only have INFO → "APP_ACTIVITY is empty").
+**2D apps:** Lepton runs every app headless (`lepton.headless=true`, only OpenXR output reaches the headset) unless the app folder (`<base>/lepton-app/`) has a `lepton-show-flatscreen` file (liblepton/app_metadata.sh) → Waydroid window on gamescope; agent v28 `set_flatscreen` at finalize for `vr_kind == "none"`. Android 11's navbar covered the
+app's controls → patch `device.hide_navbar` (default on for vr_kind none, migration `flat_hide_navbar`) exports
+`qemu.hw.mainkeys=1` as a second line of `LEPTON_GFXRECON_FP_PROPS` (runtime alternatives failed, see
+docs/FRAME_RUNTIME.md). Verified in the headset 2026-10-02 (2048).
 Lepton = Steam app 3029110 (+ "Lepton Development" 3056000, needs Developer Mode). Per-game env: STEAM_COMPAT_INSTALL_PATH
 /DATA_PATH/SHADER_PATH, SteamAppId. Logs: `<base>/launch.log` and `~/.local/share/Steam/logs/lepton-logcats/steamlaunch-<appid>`.
 Containers are podman `lepton-steamlaunch-<appid>`. Some Unreal games create save dirs without u+rwx → launcher repairs every 2 s.
@@ -218,6 +301,22 @@ 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.
+Headset results (2026-10-02, `PATCHED/_test-ovrport-1.2.5/TESTING.md`): OVRPort's own VrApi translator fails on the
+Frame (Climb 2: requests VkFormat 37 → crash; POTW: no GLES path, missing `vrapi_GetTextureSwapChainHandle`) → keep
+`frame.vrapi_bridge`; those two changes are upstream candidates. 1.2.5 builds (its platform compat, new permissions)
+work. AC Nexus: `patch_ac_nexus_no_appsw_90` is the catalog default (owner preferred 90 Hz); `STRICT` patches are only
+taken from a catalog recipe where `applies()` holds (the AC Nexus ones need build MAIN.450412.207706.final, else the
+whole overport run fails).

 **Patching gotchas:**
 - UnityPy re-serialization breaks scene loading → patch QualitySettings ints in place.
@@ -230,27 +329,95 @@ 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). Files: `install/files.py`, `frameport frame send|storage`, GUI Files tab (formerly Frame → Send files).
+**SteamVR per-app settings (2026-09-30):** editing steamvr.vrsettings while SteamVR runs is lost; the web API (127.0.0.1:27062 /app/setsettings) needs `x-steamvr-secret`. `native/vrsettings` = `fp_vrsettings.exe` (freestanding, OpenVR `FnTable:IVRSettings_003` as a Utility app, loads SteamVR's bin/win64/openvr_api.dll) sets them live and SteamVR persists them: section `steam.app.<shortcut appid>`, keys `preferredRefreshRate` (float) and `motionSmoothingOverride` (0 global, 1 on, 2 off, 3 always). Steam Link (vrlink) lists the Frame's rates 72/80/90/96/108/120/144 in vrserver.txt and follows the per-app preference ("host preferred N Hz"; whether the key is honoured is unverified in-headset yet). Judder metric: vrcompositor.txt session summary dropped + "Timed out. N total" (Stormland: 0 dropped but 313 timeouts in 2 min); fpsVR (`%LOCALAPPDATA%\fpsVR\*.json`, 0.1 ms histograms) gives p99 CPU/GPU ms. `pcvr.steamvr_tuning` (default on, PC only) applies on Play: highest rate whose budget ≥ p99×1.05, at least one step down, smoothing on.
+
 **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, CI, GitHub
+Maintainer-only notes (accounts, credentials, key locations) live in the git-ignored `CLAUDE.local.md`.
 Public repo `github.com/spoopyghosty0/frameport` (branch `main`). Push a `v*` tag → CI (`.github/workflows/build.yml`)
 tests, builds Windows x64 / macOS arm64 / Linux x64 bundles, signs, attests and publishes a GitHub Release
-(`FramePort-*.zip/.tar.gz`, `SHA256SUMS.txt`, `FramePort-selfsigned.cer`, notes from `docs/INSTALL.md`). v0.1.0 exists.
+(`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
+  `WINDOWS_CODESIGN_PFX` (base64) + `WINDOWS_CODESIGN_PASSWORD`. The private key is never committed (its
+  location is in `CLAUDE.local.md`). macOS is ad-hoc signed only (Gatekeeper
  needs right-click → Open; notarization would need the paid Apple program). Users still see SmartScreen unless they
  import the .cer into Trusted Root.
 - CI gotchas: `flet build` needs `--yes --no-rich-output` (it prompts to install Flutter; rich output crashes the
  Windows console) plus PYTHONUTF8; macOS builds need `--python-version 3.12 --arch arm64` (cryptography has no wheels
  for flet's default Python / x86_64 cross-build), with a PyInstaller fallback step; `astral-sh/setup-uv` has no
  floating major tags after v7 → pin the exact version; force-moving a tag starts duplicate runs (cancel one).
- `gh` is a local install at `~/.local/bin/gh` (logged in as spoopyghosty0 with `workflow` scope; token in
-  `~/.config/gh/hosts.yml`). Commit as `spoopyghosty0 <336754034+spoopyghosty0@users.noreply.github.com>` (set in the repo config).
+- macOS runner (2026-10-02): `macos-latest` jobs went unassigned (cancelled after 15 min, no steps); `macos-15`'s Xcode
+  16.4 fails a Flutter plugin (`NWPath has no member`); `macos-26` (Xcode 26) builds with `flet build`. The PyInstaller
+  fallback (`package.py --pyinstaller`) passes `--yes` so a failed `flet build`'s folder doesn't stop it at a prompt.
+- Windows PowerShell calls from Python (`updates._powershell()`): use `%SystemRoot%\System32\WindowsPowerShell\v1.0\
+  powershell.exe` with `PSModulePath` removed from the environment — started under PowerShell 7 (CI's default shell,
+  or a user's pwsh terminal) it couldn't run Get-AuthenticodeSignature (v0.3.0's Windows update smoke failed on it).
+  `v0.3.0` is a tag without a release (that failed build); the updater shipped first in v0.3.1.
+- **Never start PowerShell with `DETACHED_PROCESS` from the packaged app**: it exits 0 without running anything (found
+  in the 0.3.1→0.3.2 end-to-end test: the app quit, nothing updated). `updates.spawn_hidden` = CREATE_NEW_CONSOLE +
+  hidden window; `apply()` waits until the script has logged that it runs and raises otherwise (the app then stays
+  open). Windows installs of 0.3.1/0.3.2 can't update themselves: they need one manual download.
+- The Linux bundle is built on ubuntu-22.04: a 24.04-built Flutter bundle needs GLib 2.80 (`undefined symbol:
+  g_once_init_enter_pointer` on 22.04).
 - **The repo is public: never commit personal data** — the Frame's IP address, the Steam user id, the owner's email,
  local home paths (native builds use `-ffile-prefix-map`). History was rewritten once to remove them.

@@ -273,13 +440,16 @@ GLAD/GLES); Unreal → alternate no-ForceQuit build. Score changes with
 - Reinstalls keep one rollback copy (`<base>/previous-game.apk`, `settings.conf.previous`); `frameport frame cleanup`
  removes them (and `--path ~/X` extra folders under home).

-## Project status (2026-09-29)
+## Project status (2026-10-02)
+Self-update, the Files tab, OVRPort 1.2.5, non-Quest Android apps (vr_kind) and GUI localisation (tr(), 0.3.x) are
+in; see the sections above. Earlier state (2026-09-29):
 34 Quest games ported; the owner confirmed in the headset that all FramePort-rebuilt games work: 23 work, 5 work with
 issues (Arcsmith/Time Stall eye distortion, AC Nexus some flipped launch text, Phantom DLC button, Silhouette hands),
 6 can't run (Sniper Elite VR, Espire 1, HITMAN, and the 32-bit Journey of the Gods / Shadow Point / Sports Scramble).
-Parity: all 34 rebuilt from the dumps match the known-good builds (`docs/parity-report.md`) and were reinstalled +
+Parity: all 34 rebuilt from the dumps match the known-good builds (`docs/parity-report.md`, generated locally and
+git-ignored; 34/34 again with OVRPort 1.2.5 on 2026-10-02) and were reinstalled +
 launch-tested with 0 regressions (`docs/parity-device-report.md`). `PATCHED/` holds exactly the installed builds.
-Owner preferences: manual installs (no FrameDrop, no Quest2Frame app), Python + Flet, dynamic data over hardcoding,
+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),
@@ -0,0 +1,8 @@
+# Code of conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+In short: be respectful and constructive, assume good faith, and keep discussions about the project. Harassment and
+personal attacks aren't tolerated.
+
+Report unacceptable behaviour privately through a GitHub security advisory on this repository (it reaches the
+maintainer only). Reports are handled confidentially.
@@ -0,0 +1,46 @@
+# Contributing
+
+Thanks for helping. The quickest contributions:
+
+- **A game works on the Frame?** In FramePort: the game's menu → **Share working config…** opens a prefilled issue
+  with its recipe. Accepted configs become built-in recipes.
+- **Something doesn't work?** The game's menu → **Report a problem…** saves a diagnostics zip (personal data
+  removed) and opens a prefilled issue to attach it to.
+
+## Development
+```
+uv sync --extra dev          # Python 3.11+, uv (https://docs.astral.sh/uv/)
+uv run frameport-gui         # the app
+uv run frameport --help      # the command line
+uv run pytest                # tests (no headset or game files needed)
+uv run ruff check .          # lint
+```
+- Code and architecture: `CLAUDE.md`, `docs/ARCHITECTURE.md`; per-game symptoms and fixes: `docs/PLAYBOOK.md`.
+- Interface wording: `docs/STYLE.md`. GUI texts go through `tr()`; after changing them run
+  `python scripts/i18n_extract.py`.
+- Translations: see [Translating FramePort](#translating-frameport) below.
+- New fixes are patch modules (`src/frameport/patches/`), with a triage signature (`catalog/triage.yaml`), a PLAYBOOK
+  row and a unit test.
+- Native binaries in `artifacts/` are rebuilt with `python native/build.py` (downloads the NDK).
+
+## Translating FramePort
+The app's texts (screens, help, patch and setting descriptions) can be translated; the command line, logs and
+diagnostics stay English. No programming needed:
+
+1. Copy `src/frameport/locales/template.json` to `src/frameport/locales/<code>.json`, where `<code>` is the language
+   code (`de`, `fr`, `pt`, `ja`, …).
+2. Add `"_language": "<the language's own name>"` (e.g. `"Deutsch"`); it's shown in Settings → Language.
+3. Fill in the values. Each key is the English text; leave a value empty to keep the English text. Plural entries
+   have a list value: `["<one>", "<other>"]`. Keep `{placeholders}` such as `{title}` or `{n}` exactly as they are,
+   and keep `…`, `·` and line breaks where the English has them.
+4. Try it: `uv run frameport-gui`, choose the language in Settings → Language, restart FramePort.
+5. Open a pull request with the file. When the English texts change, `python scripts/i18n_extract.py` refreshes the
+   template; new texts then show in English until they're translated.
+
+Wording rules for English (and a guide for tone) are in `docs/STYLE.md`.
+
+## Ground rules
+- Use only games you own. Contributions that help bypass DRM, licence or entitlement checks, or that add game files,
+  are not accepted.
+- Never commit personal data (IP addresses, user names, home paths, Steam IDs).
+- By contributing you agree to license your work under GPL-3.0-only.
@@ -1,36 +1,130 @@
 # 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, other Android apps and 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 game backups: Android/Quest games (APK + OBB) or PC VR
+   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. Several installs queue up; if the Frame goes to sleep or
+   drops off the Wi-Fi, the queue waits and continues where it stopped (FramePort keeps the Frame awake meanwhile).
+   Your game files are never changed: the converted copy is temporary.
+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)
+
+Each game has **Game settings** in plain words (sharpness, refresh rate, controllers, menus, 360° video, mixed
+reality), showing only what matters for that game. Changes are kept with the game and reach the Frame right away.
+
+![Game settings](docs/images/game-settings.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**: described in plain words, with **Show technical details** for the exact
+effect of each patch.
+
+Tried an untested game? Its page asks how it runs; **Share working config…** opens a prefilled GitHub issue so your
+recipe can join the built-in catalog for everyone.
+
+![Patches](docs/images/patches.png)
+
+| Kind of app | On the Steam Frame |
+|---|---|
+| Meta Quest games (APK) | Translated to OpenXR (OVRPort) and patched for the Frame; run in Valve's Android runtime (Lepton) |
+| Other Android VR apps using OpenXR (e.g. Pico builds) | Translated the same way; the other headset's own extensions and store services aren't available |
+| Ordinary Android apps and games (no VR) | Installed unchanged and shown as a flat window in the headset |
+| PC VR games (Windows; OpenXR, SteamVR or Oculus) | Run through Proton on the Frame (experimental), or on a Windows PC with SteamVR and streamed to the Frame; Oculus-only games use Revive |
+| Can't run | 32-bit-only or x86-only APKs, Pico/HTC Wave SDK apps, Android XR apps, and games that check an Oculus licence (they need the Oculus app on a PC) |
+
+Automated launch tests confirm that a game starts; visuals can only be checked in the headset.
+
+![Steam Frame](docs/images/frame.png)
+
+The **Files** tab manages files on the Frame: upload videos, documents, mods or saves from the computer (buttons or
+drag-and-drop), download, rename and delete (one entry or a selection), in the shared folders every game sees or in
+one game's own storage.
+
+![Files](docs/images/files.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.
+- [CONTRIBUTING.md](CONTRIBUTING.md): contributing code, recipes and translations.

 ## 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.
@@ -0,0 +1,8 @@
+# Security
+
+FramePort talks to your Steam Frame over SSH with its own key and runs a small agent there; it also downloads tools
+and its own updates (checked against the release's SHA-256 sums and, on Windows, its signature).
+
+To report a vulnerability, please open a GitHub security advisory for this repository (Security → Report a
+vulnerability) instead of a public issue. Include the FramePort version (`frameport --version`) and how to reproduce
+it. Fixes are released as normal updates; FramePort offers them automatically.
@@ -0,0 +1,27 @@
+# Third-party notices
+
+FramePort is GPL-3.0-only (see `LICENSE`). It includes or downloads the following third-party work.
+
+## Included in this repository / the release bundles
+| Component | Where | License |
+|---|---|---|
+| OVRPort VrApi → OpenXR adapter (`native/vrapi`, github.com/Android-XR-Bridge/OVRPort), with FramePort's changes | `native/vrapi-bridge/`, `artifacts/arm64-v8a/libvrapi.so` | GPL-3.0 (`native/vrapi-bridge/LICENSE.upstream`) |
+| OVRPort platform compatibility library (`native/platform`) | `native/platformcompat/`, `artifacts/arm64-v8a/libovrplatformcompat.so` | GPL-3.0; Meta Platform SDK headers under the Meta Platform Technologies SDK License (`native/platformcompat/licenses/OCULUS-PLATFORM-SDK.txt`) |
+| Khronos OpenXR SDK headers | used to build the native layers | Apache-2.0 / MIT (`native/vrapi-bridge/licenses/OPENXR-SDK.txt`) |
+| Android NDK runtime (statically linked libc++) | native Android libraries | Apache-2.0 with LLVM exception, plus legacy notices (`native/vrapi-bridge/licenses/ANDROID-NDK.txt`) |
+| Flet and Flutter (desktop app runtime) | release bundles | Apache-2.0 / BSD-3-Clause |
+| flet-dropzone / desktop_drop (drag-and-drop) | release bundles | Apache-2.0 / MIT |
+| Python packages (paramiko, zeroconf, psutil, pyelftools, capstone, UnityPy, PyYAML, requests, typer, pyaxmlparser, Pillow, cryptography, …) | release bundles | their own licenses (see each package's metadata) |
+
+FramePort's own native code (the FrameBridge adapter, GL/Vulkan/OpenXR shims, the Windows helpers) is GPL-3.0-only.
+
+## Downloaded at run time (not redistributed)
+| Tool | Source | License |
+|---|---|---|
+| OVRPort / overport CLI | github.com/Android-XR-Bridge/OVRPort releases (fallback github.com/ovrport/app) | GPL-3.0 |
+| Eclipse Temurin JRE | api.adoptium.net | GPL-2.0 with Classpath Exception |
+| apksigner (Android build-tools) | dl.google.com Android repository | Apache-2.0 |
+| Revive (portable copy, only if Revive isn't installed) | github.com/LibreVR/Revive releases | GPL-3.0 |
+
+Valve's Lepton, Proton and SteamVR, and Meta's software, are used on your devices as installed by Steam / Meta;
+FramePort doesn't distribute them.
@@ -5,7 +5,8 @@ The PC app uploads this file to ~/.local/share/frameport/agent/ and calls:
    python3 frameport_agent.py <command>        (JSON arguments on stdin, one JSON object on stdout)

 Commands: info, prepare, finalize, shortcuts, shortcut_status, launch_test, stop, set_settings, uninstall,
-          install_lepton, list_installed, proton_status, install_proton, prepare_pcvr, finalize_pcvr.
+          install_lepton, list_installed, proton_status, install_proton, prepare_pcvr, finalize_pcvr,
+          controller_models.

 Install layout (one Lepton container per game; same as the manual installs from 2026-09):
    ~/Applications/quest-frame/<pkg>/            anchor: launch.sh, deployment.json, artwork/ (always internal storage)
@@ -32,7 +33,7 @@ import sys
 import time
 import zlib

-AGENT_VERSION = 17
+AGENT_VERSION = 30
 HOME = os.path.expanduser("~")
 STEAM = os.path.join(HOME, ".local/share/Steam")
 ANCHORS = os.path.join(HOME, "Applications/quest-frame")
@@ -93,7 +94,8 @@ def find_app(name_regex):

 def lepton_path():
    app = find_app(r"Lepton")
-    candidates = ([os.path.join(app["dir"], "lepton")] if app else []) + [os.path.join(STEAM, "steamapps/common/Lepton/lepton")]
+    candidates = (([os.path.join(app["dir"], "lepton")] if app else [])
+                  + [os.path.join(STEAM, "steamapps/common/Lepton/lepton")])
    for c in candidates:
        if os.access(c, os.X_OK):
            return c, app
@@ -113,7 +115,7 @@ def find_app_id(appid):
        state = re.search(r'"StateFlags"\s+"(\d+)"', text)
        d = os.path.join(lib, "common", installdir[1]) if installdir else None
        num = {k: int(m[1]) for k in ("BytesDownloaded", "BytesToDownload", "SizeOnDisk")
-               for m in [re.search(r'"%s"\s+"(\d+)"' % k, text)] if m}
+               for m in [re.search(rf'"{k}"\s+"(\d+)"', text)] if m}
        return {"appid": str(appid), "name": name[1] if name else "", "dir": d, "state": int(state[1]) if state else 0,
                "complete": bool(state and int(state[1]) & 4 and d and os.path.isdir(d)),
                "downloaded": num.get("BytesDownloaded", 0), "to_download": num.get("BytesToDownload", 0)}
@@ -231,7 +233,7 @@ def tool_manifest(tool_dir):
        return {}
    out = {}
    for k in ("commandline", "require_tool_appid", "version"):
-        m = re.search(r'"%s"\s+"((?:[^"\\]|\\.)*)"' % k, text)
+        m = re.search(rf'"{k}"\s+"((?:[^"\\]|\\.)*)"', text)
        if m:
            out[k] = m[1].replace('\\"', '"')
    if "require_tool_appid" in out:
@@ -465,7 +467,7 @@ def cmd_xr_layer_test(args):
        try:
            p = run([sys.executable, os.path.abspath(__file__), "_xr_probe", json.dumps({"loader": loader})],
                    env=env, timeout=60)
-            line = next((l for l in reversed(p.stdout.splitlines()) if l.startswith("{")), None)
+            line = next((ln for ln in reversed(p.stdout.splitlines()) if ln.startswith("{")), None)
            results[name] = json.loads(line) if line else {"error": (p.stderr or p.stdout)[-800:]}
        except subprocess.TimeoutExpired:
            results[name] = {"error": "timed out"}
@@ -576,9 +578,11 @@ def ensure_host_fixes():
    if not re.search(r"^\s*keyring\s*=", text, re.M):
        note = "# FramePort: stop rootless podman leaking a kernel keyring per container start (Lepton launches)\n"
        if re.search(r"^\[containers\]\s*$", text, re.M):
-            text = re.sub(r"^\[containers\]\s*$", "[containers]\n" + note + "keyring = false", text, count=1, flags=re.M)
+            text = re.sub(r"^\[containers\]\s*$", "[containers]\n" + note + "keyring = false", text, count=1,
+                          flags=re.M)
        else:
-            text = text + ("\n" if text and not text.endswith("\n") else "") + "[containers]\n" + note + "keyring = false\n"
+            sep = "\n" if text and not text.endswith("\n") else ""
+            text = text + sep + "[containers]\n" + note + "keyring = false\n"
        os.makedirs(os.path.dirname(CONTAINERS_CONF), exist_ok=True)
        with open(CONTAINERS_CONF, "w") as f:
            f.write(text)
@@ -632,7 +636,7 @@ def cmd_install_lepton(args):
            "hint": "Enable Developer Mode, then confirm the install in Steam (or launch 'Lepton Development' once)."}


-# ------------------------------------------------------------------------------------------ Steam shortcuts (binary VDF)
+# ------------------------------------------------------------------------------------- Steam shortcuts (binary VDF)
 TYPE_MAP, TYPE_STRING, TYPE_INT, TYPE_END = 0, 1, 2, 8


@@ -710,7 +714,7 @@ def upsert_shortcut(vdf_path, exe, title, start_dir, icon="", tag="Quest on Fram
                 LaunchOptions=launch_options, IsHidden=0, AllowDesktopConfig=1, AllowOverlay=1, OpenVR=1, Devkit=0,
                 DevkitGameID="", DevkitOverrideAppID=0, FlatpakAppID="")
    if data:
-        shutil.copy2(vdf_path, f"{vdf_path}.backup-{time.strftime('%Y%m%d-%H%M%S')}")
+        backup_vdf(vdf_path)
    os.makedirs(os.path.dirname(vdf_path), exist_ok=True)
    tmp = vdf_path + ".tmp"
    with open(tmp, "wb") as f:
@@ -725,22 +729,48 @@ def prune_shortcuts(vdf_path, title, keep_exe, tag):
    removed appids."""
    if not os.path.exists(vdf_path):
        return []
+    tags = (tag,) if isinstance(tag, str) else tuple(tag)  # one tag, or several (current + earlier names)
    root = vdf_decode(open(vdf_path, "rb").read())
    sc = root.get("shortcuts", {})
-    removed = [v.get("appid") for v in sc.values() if isinstance(v, dict) and v.get("appname") == title
-               and v.get("Exe") != keep_exe and tag in (v.get("tags") or {}).values()]
+
+    def stale(v):
+        return (isinstance(v, dict) and v.get("appname") == title and v.get("Exe") != keep_exe
+                and any(t in (v.get("tags") or {}).values() for t in tags))
+    removed = [v.get("appid") for v in sc.values() if stale(v)]
    if not removed:
        return []
-    keep = [v for v in sc.values() if not (isinstance(v, dict) and v.get("appname") == title
-            and v.get("Exe") != keep_exe and tag in (v.get("tags") or {}).values())]
+    keep = [v for v in sc.values() if not stale(v)]
    root["shortcuts"] = {str(i): v for i, v in enumerate(keep)}
-    shutil.copy2(vdf_path, f"{vdf_path}.backup-{time.strftime('%Y%m%d-%H%M%S')}")
+    backup_vdf(vdf_path)
    with open(vdf_path + ".tmp", "wb") as f:
        f.write(vdf_encode(root))
    os.replace(vdf_path + ".tmp", vdf_path)
    return removed


+VDF_BACKUPS = 5
+
+
+def backup_vdf(vdf_path):
+    """Keep a copy before changing shortcuts.vdf (the last VDF_BACKUPS are kept)."""
+    shutil.copy2(vdf_path, f"{vdf_path}.backup-{time.strftime('%Y%m%d-%H%M%S')}")
+    for old in sorted(glob.glob(f"{vdf_path}.backup-*"))[:-VDF_BACKUPS]:
+        try:
+            os.remove(old)
+        except OSError:
+            pass
+
+
+def grid_files(grid, appid):
+    """A shortcut's grid artwork (<appid>p.jpg, <appid>_hero.png, …): exact names, never another appid that merely
+    starts with the same digits."""
+    pat = re.compile(rf"^{re.escape(str(appid))}(p|_hero|_logo|_icon)?\.[A-Za-z0-9]+$")
+    try:
+        return [os.path.join(grid, n) for n in os.listdir(grid) if pat.match(n)]
+    except OSError:
+        return []
+
+
 def remove_shortcut(vdf_path, exe):
    if not os.path.exists(vdf_path):
        return False
@@ -750,7 +780,7 @@ def remove_shortcut(vdf_path, exe):
    if len(keep) == len(sc):
        return False
    root["shortcuts"] = {str(i): v for i, v in enumerate(keep)}
-    shutil.copy2(vdf_path, f"{vdf_path}.backup-{time.strftime('%Y%m%d-%H%M%S')}")
+    backup_vdf(vdf_path)
    with open(vdf_path + ".tmp", "wb") as f:
        f.write(vdf_encode(root))
    os.replace(vdf_path + ".tmp", vdf_path)
@@ -765,13 +795,15 @@ def cmd_shortcuts(args):
    rewritten, so the work runs in a detached systemd unit (terminals/SSH sessions started from Steam live in
    steam.service's cgroup and would be killed with it). Poll shortcut_status for the result."""
    packages = [check_pkg(p) for p in args.get("packages", [])]
-    if not packages:
+    remove = [r for r in args.get("remove", [])
+              if isinstance(r, dict) and str(r.get("exe", "")).startswith('"' + ANCHORS)]
+    if not packages and not remove:
        return {"started": False}
    os.makedirs(os.path.dirname(STATUS_FILE), exist_ok=True)
    with open(STATUS_FILE, "w") as f:
        json.dump({"state": "running", "packages": packages, "started": time.time()}, f)
    unit = f"frameport-shortcuts-{int(time.time())}"
-    payload = json.dumps({"packages": packages, "restart": args.get("restart", True)})
+    payload = json.dumps({"packages": packages, "remove": remove, "restart": args.get("restart", True)})
    run(["systemd-run", "--user", "--collect", "--quiet", f"--unit={unit}", "--setenv=HOME=" + HOME,
         sys.executable, os.path.abspath(__file__), "_shortcuts_worker", payload])
    return {"started": True, "unit": unit}
@@ -791,6 +823,14 @@ def shortcuts_worker(payload):
            raise AgentError("Steam did not close; library not modified") from None
        grid = os.path.join(os.path.dirname(vdf), "grid")
        os.makedirs(grid, exist_ok=True)
+        for r in args.get("remove", []):  # uninstalled games
+            try:
+                if remove_shortcut(vdf, r["exe"]):
+                    result.setdefault("removed", []).append(r["exe"])
+                for art in grid_files(grid, r.get("appid") or ""):
+                    os.remove(art)
+            except Exception as exc:  # noqa: BLE001
+                result["errors"].append(f"{r.get('exe')}: {exc}")
        for pkg in args["packages"]:
            try:
                anchor = os.path.join(ANCHORS, pkg)
@@ -879,6 +919,109 @@ def cmd_launch(args):
    return {"package": pkg, "gameid": gid, "title": dep.get("title")}


+LEPTON_LINK = re.compile(r'ln -s "\$\{HOME\}/([^"/]+)" "\$\{TARGET_PATH\}/([^"/]+)"')
+SHARED_DEFAULT = (("Documents", "Documents"), ("Downloads", "Download"), ("Videos", "Movies"))
+
+
+def lepton_shared_folders():
+    """(home folder, Android folder) pairs Lepton links into every app's storage (read from Lepton's mounting.sh;
+    it only links folders that exist when an app starts)."""
+    lepton, _app = lepton_path()
+    text = ""
+    if lepton:
+        try:
+            text = open(os.path.join(os.path.dirname(lepton), "liblepton", "mounting.sh"), errors="replace").read()
+        except OSError:
+            pass
+    pairs = LEPTON_LINK.findall(text)
+    return pairs or list(SHARED_DEFAULT)
+
+
+# Folders Android itself creates in every app's /sdcard; anything else at the top level was made by the app.
+ANDROID_STORAGE_DIRS = {"alarms", "android", "audiobooks", "dcim", "documents", "download", "movies", "music",
+                        "notifications", "pictures", "podcasts", "recordings", "ringtones", "screenshots"}
+
+
+def app_media_dirs(ext):
+    """The app's own top-level folders in its /sdcard (e.g. 4XVR's 4XPlayer, which its "Internal Storage" list shows
+    instead of /sdcard/Movies): real folders only (not Lepton's links to the shared folders), not hidden."""
+    try:
+        names = sorted(os.listdir(ext))
+    except OSError:
+        return []
+    return [n for n in names if not n.startswith(".") and n.lower() not in ANDROID_STORAGE_DIRS
+            and os.path.isdir(os.path.join(ext, n)) and not os.path.islink(os.path.join(ext, n))]
+
+
+def lepton_external(pkg):
+    dep = deployment(pkg)
+    if not dep or dep.get("kind") == "pcvr":
+        raise AgentError(f"{pkg} is not an installed Quest (Lepton) game")
+    return os.path.join(dep["base"], "lepton-data", "external")
+
+
+def cmd_storage_targets(args):
+    """Where files for Lepton apps go: shared folders (seen by every app, e.g. ~/Videos = /sdcard/Movies) and, with a
+    package, that app's own storage (/sdcard) and its files folder. Creates missing shared folders (Lepton links only
+    existing ones). Android's media index doesn't work in Lepton, so apps must browse folders to find files."""
+    out = []
+    for home_name, android in lepton_shared_folders():
+        path = os.path.join(HOME, home_name)
+        os.makedirs(path, exist_ok=True)
+        out.append({"id": home_name.lower(), "path": path, "android": "/sdcard/" + android, "shared": True})
+    pkg = args.get("package")
+    if pkg:
+        pkg = check_pkg(pkg)
+        ext = lepton_external(pkg)
+        files = os.path.join(ext, "Android", "data", pkg, "files")
+        os.makedirs(files, exist_ok=True)
+        out.append({"id": "app", "path": ext, "android": "/sdcard", "shared": False})
+        out.append({"id": "app-files", "path": files, "android": f"/sdcard/Android/data/{pkg}/files", "shared": False})
+        for i, name in enumerate(app_media_dirs(ext)):  # the app's own folders (e.g. a video player's library)
+            out.append({"id": "app-media" if i == 0 else f"app-media:{name}", "path": os.path.join(ext, name),
+                        "android": f"/sdcard/{name}", "shared": False, "folder": name})
+    return {"targets": out}
+
+
+def cmd_link_media(args):
+    """Make files from the shared folders (e.g. ~/Videos) appear in an app's own folder too, as hard links (no copy,
+    no extra space). For players that list their own folder rather than /sdcard/Movies (4XVR: 4XPlayer). args:
+    package, files (paths under ~/Videos, ~/Downloads, ~/Documents), folder (optional; default: the app's first own
+    folder, see app_media_dirs). Returns {folder, android, linked, existing, missing}; folder None when the app has no
+    own folder (it then finds the files in the shared folders)."""
+    pkg = check_pkg(args["package"])
+    ext = lepton_external(pkg)
+    folder = args.get("folder") or next(iter(app_media_dirs(ext)), None)
+    if not folder:
+        return {"folder": None, "android": None, "linked": [], "existing": [], "missing": []}
+    if "/" in folder or folder in (".", ".."):
+        raise AgentError(f"bad folder {folder!r}")
+    dest = os.path.join(ext, folder)
+    os.makedirs(dest, exist_ok=True)
+    shared = [os.path.realpath(os.path.join(HOME, h)) for h, _a in lepton_shared_folders()]
+    linked, existing, missing = [], [], []
+    for path in args.get("files") or []:
+        real = os.path.realpath(path)
+        if not any(real == s or real.startswith(s + os.sep) for s in shared):
+            raise AgentError(f"{path} is not in a shared folder ({', '.join(shared)})")
+        if not os.path.isfile(real):
+            missing.append(path)
+            continue
+        target = os.path.join(dest, os.path.basename(real))
+        if os.path.exists(target):
+            if os.path.samefile(target, real):
+                existing.append(os.path.basename(real))
+                continue
+            os.remove(target)  # an older file of the same name: show the one just sent
+        try:
+            os.link(real, target)
+        except OSError:
+            shutil.copy2(real, target)  # different file system (not the case with Lepton's layout)
+        linked.append(os.path.basename(real))
+    return {"folder": folder, "android": f"/sdcard/{folder}", "linked": linked, "existing": existing,
+            "missing": missing}
+
+
 def cmd_list_files(args):
    """Every file of an installed game on the Frame, for the PC's file browser: {roots: [{name, path, files:
    [[rel, size], ...]}], missing: [[rel, expected size, actual size or None], ...], truncated}. Roots are the install
@@ -946,21 +1089,28 @@ def cmd_prepare(args):
    want_sha = args.get("apk_sha256")
    same_apk = bool(want_sha and os.path.exists(apk) and os.path.getsize(apk) == args.get("apk_size")
                    and sha256_file(apk) == want_sha)
-    st = os.statvfs(base if os.path.exists(base) else os.path.dirname(base) if os.path.exists(os.path.dirname(base)) else HOME)
+    st = os.statvfs(base if os.path.exists(base)
+                    else os.path.dirname(base) if os.path.exists(os.path.dirname(base)) else HOME)
    lepton, _ = lepton_path()
    return {"package": pkg, "base": base, "anchor": anchor, "appid": appid, "incoming": incoming,
            "installed": bool(dep), "same_apk": same_apk, "existing_obb": existing,
            "free_bytes": st.f_bavail * st.f_frsize, "lepton": lepton}


-LAUNCH_SH = r"""#!/usr/bin/env bash
+LAUNCH_SH = (r"""#!/usr/bin/env bash
 # Steam Frame launcher for {title} ({pkg}). Generated by FramePort.
 set -euo pipefail
 app_dir={base_q}
 [[ -d "$app_dir/lepton-app" ]] || {{ echo "Game files missing at $app_dir (storage not mounted?)" >&2; exit 1; }}
 # Some games (Unreal cloud saves) create folders without write/search permission inside Lepton,
 # which silently breaks saving. Repair them before and during every launch.
-fix_perms() {{ find "$app_dir/lepton-data/external" -type d ! -perm -u+rwx -exec chmod u+rwx {{}} + 2>/dev/null || true; }}
+fix_perms() {{ find "$app_dir/lepton-data/external" -type d ! -perm -u+rwx -exec chmod u+rwx {{}} + 2>/dev/null ||"""
+r""" true; }}
+# Android can't create an app's external files/cache folders inside Lepton ("Invalid mkdirs path ... not a known app
+# path"): getExternalCacheDir() then returns nothing, which breaks e.g. Whirligig's video player cache. Create them"""
+r""" here.
+mkdir -p "$app_dir/lepton-data/external/Android/data/{pkg}/files" """
+r""""$app_dir/lepton-data/external/Android/data/{pkg}/cache" 2>/dev/null || true
 fix_perms
 ( while sleep 2 && kill -0 $$ 2>/dev/null; do fix_perms; done ) & permfix=$!
 export SteamAppId={appid}
@@ -986,11 +1136,12 @@ trap 'exit 143' TERM
 setsid {lepton_q} start >"$app_dir/launch.log" 2>&1 &
 child=$!
 wait "$child"
-"""
+""")


 def write_launcher(anchor, base, pkg, title, appid, lepton, env):
-    extra = "".join(f"export {k}={shlex.quote(str(v))}\n" for k, v in (env or {}).items() if re.fullmatch(r"[A-Z_][A-Z0-9_]*", k))
+    extra = "".join(f"export {k}={shlex.quote(str(v))}\n" for k, v in (env or {}).items()
+                    if re.fullmatch(r"[A-Z_][A-Z0-9_]*", k))
    text = LAUNCH_SH.format(title=title.replace("\n", " "), pkg=pkg, base_q=shlex.quote(base), appid=appid,
                            lepton_q=shlex.quote(lepton), extra_env=extra)
    path = os.path.join(anchor, "launch.sh")
@@ -1004,6 +1155,16 @@ def data_files_dir(base, pkg):
    return os.path.join(base, "lepton-data/external/Android/data", pkg, "files")


+def set_flatscreen(app_dir, on):
+    """Lepton shows an app as a flat (2D) window only when its app folder holds this marker
+    (liblepton/app_metadata.sh); otherwise the app runs headless and only OpenXR output reaches the headset."""
+    marker = os.path.join(app_dir, "lepton-show-flatscreen")
+    if on:
+        open(marker, "a").close()
+    elif os.path.exists(marker):
+        os.remove(marker)
+
+
 def cmd_finalize(args):
    """Move uploaded files into place, write launcher/settings/config files/deployment.json. Keeps saves."""
    pkg = check_pkg(args["package"])
@@ -1017,6 +1178,19 @@ def cmd_finalize(args):
    os.makedirs(os.path.join(app, "obb"), exist_ok=True)
    os.makedirs(anchor, exist_ok=True)
    new_apk = os.path.join(incoming, "game.apk")
+    inc_obb = os.path.join(incoming, "obb")
+    expected = args.get("obb_manifest")  # rel path -> size
+    if expected:  # check the data as it will be after the move, before replacing anything (a failure keeps the old)
+        have = {}
+        for top in (os.path.join(app, "obb"), inc_obb):
+            for root, _, files in os.walk(top):
+                for name in files:
+                    if not name.endswith(".part"):
+                        p = os.path.join(root, name)
+                        have[os.path.relpath(p, top)] = os.path.getsize(p)
+        bad = [k for k, v in expected.items() if have.get(k) != v]
+        if bad:
+            raise AgentError(f"{len(bad)} data file(s) missing or incomplete, e.g. {bad[0]}")
    if os.path.exists(new_apk):
        if args.get("apk_sha256") and sha256_file(new_apk) != args["apk_sha256"]:
            raise AgentError("uploaded APK checksum mismatch (transfer corrupted?)")
@@ -1027,7 +1201,6 @@ def cmd_finalize(args):
    elif not os.path.exists(os.path.join(app, "game.apk")):
        raise AgentError("no APK uploaded and none installed")
    moved = 0
-    inc_obb = os.path.join(incoming, "obb")
    for root, _, files in os.walk(inc_obb):
        for name in files:
            if name.endswith(".part"):
@@ -1037,17 +1210,9 @@ def cmd_finalize(args):
            os.makedirs(os.path.dirname(dst), exist_ok=True)
            os.replace(src, dst)
            moved += 1
-    expected = args.get("obb_manifest")  # rel path -> size
-    if expected:
-        have = {}
-        for root, _, files in os.walk(os.path.join(app, "obb")):
-            for name in files:
-                p = os.path.join(root, name)
-                have[os.path.relpath(p, os.path.join(app, "obb"))] = os.path.getsize(p)
-        bad = [k for k, v in expected.items() if have.get(k) != v]
-        if bad:
-            raise AgentError(f"{len(bad)} data file(s) missing or incomplete, e.g. {bad[0]}")
    shutil.rmtree(incoming, ignore_errors=True)
+    if "flatscreen" in args:  # older clients don't send it: leave the marker as it is
+        set_flatscreen(app, args["flatscreen"])
    # settings: settings.conf (read by the adapter via LEPTON_ENV_FRAMEBRIDGE_CONFIG) + framebridge.conf copy
    files_dir = data_files_dir(base, pkg)
    os.makedirs(files_dir, exist_ok=True)
@@ -1069,6 +1234,7 @@ def cmd_finalize(args):
        os.makedirs(os.path.dirname(target), exist_ok=True)
        with open(target, "w") as f:
            f.write(content)
+    models = install_controller_models(files_dir, str(settings.get("controller_models", 0)) not in ("0", "0.0"))
    write_launcher(anchor, base, pkg, title, appid, lepton, args.get("env"))
    art_in = os.path.join(base, "incoming-artwork")
    if os.path.isdir(art_in):
@@ -1080,7 +1246,307 @@ def cmd_finalize(args):
           "agent_version": AGENT_VERSION, "time": time.time()}
    with open(os.path.join(anchor, "deployment.json"), "w") as f:
        json.dump(dep, f, indent=2)
-    return {"ok": True, "base": base, "appid": appid, "moved_data_files": moved}
+    return {"ok": True, "base": base, "appid": appid, "moved_data_files": moved, "controller_models": models}
+
+
+# --------------------------------------------------------------- Steam Frame controller models (XR_FB_render_model)
+# The FrameBridge adapter (setting controller_models=1) serves these to games that ask the runtime for controller
+# models.
+# They are converted here, on the Frame, from the SteamVR render models the Frame already has (OBJ + PNG) into glTF
+# binaries, so Valve's models never leave the device.
+MODELS_CACHE = os.path.join(HOME, ".local/share/frameport/controller-models")
+FRAME_MODEL_RE = re.compile(r"frame", re.I)
+SKIP_COMPONENTS = ("status", "led", "scroll_wheel_touch")
+
+
+def steamvr_roots():
+    roots = []
+    rt = openxr_runtime()
+    if rt and rt.get("path"):
+        roots.append(os.path.dirname(rt["path"]))
+    roots += [os.path.join(lib, "steamapps/common/SteamVR") for lib in steam_libraries()]
+    roots += ["/opt/steamvr", os.path.join(STEAM, "steamapps/common/SteamVR")]
+    out = []
+    for r in roots:
+        r = os.path.realpath(r)
+        if os.path.isdir(r) and r not in out:
+            out.append(r)
+    return out
+
+
+def render_model_dirs(roots=None):
+    """name -> directory of every SteamVR render model (a folder with .obj files)."""
+    found = {}
+    for root in roots if roots is not None else steamvr_roots():
+        for pattern in ("resources/rendermodels/*", "drivers/*/resources/rendermodels/*"):
+            for d in sorted(glob.glob(os.path.join(root, pattern))):
+                if os.path.isdir(d) and glob.glob(os.path.join(d, "*.obj")):
+                    found.setdefault(os.path.basename(d), d)
+    return found
+
+
+def model_side(name):
+    n = name.lower()
+    for side in ("left", "right"):
+        if side in n:
+            return side
+    for side in ("left", "right"):  # e.g. controller_l / controller-r
+        if re.search(rf"(^|[_\-. ]){side[0]}([_\-. ]|$)", n):
+            return side
+    return None
+
+
+def pick_controller_models(dirs, pattern=FRAME_MODEL_RE):
+    """{'left': dir, 'right': dir} for the Steam Frame controllers (names matching `pattern`), or {}."""
+    best = {}
+    for name, d in dirs.items():
+        side = model_side(name)
+        if not side or not pattern.search(name):
+            continue
+        score = ("controller" in name.lower()) * 10 - len(name)
+        if side not in best or score > best[side][0]:
+            best[side] = (score, d)
+    return {s: d for s, (_, d) in best.items()} if len(best) == 2 else {}
+
+
+def _rotation_xyz(deg):
+    """3x3 rotation for SteamVR's rotate_xyz (degrees; applied about X, then Y, then Z)."""
+    import math
+    rx, ry, rz = (math.radians(float(v)) for v in (list(deg) + [0, 0, 0])[:3])
+    cx, sx, cy, sy, cz, sz = math.cos(rx), math.sin(rx), math.cos(ry), math.sin(ry), math.cos(rz), math.sin(rz)
+    X = [[1, 0, 0], [0, cx, -sx], [0, sx, cx]]
+    Y = [[cy, 0, sy], [0, 1, 0], [-sy, 0, cy]]
+    Z = [[cz, -sz, 0], [sz, cz, 0], [0, 0, 1]]
+    mul = lambda a, b: [[sum(a[i][k] * b[k][j] for k in range(3)) for j in range(3)] for i in range(3)]
+    return mul(Z, mul(Y, X))
+
+
+def model_description(model_dir):
+    """(obj files, grip transform or None) from the model's JSON (components) or the folder's .obj files."""
+    name = os.path.basename(model_dir)
+    desc = {}
+    for cand in (os.path.join(model_dir, name + ".json"), *sorted(glob.glob(os.path.join(model_dir, "*.json")))):
+        try:
+            desc = json.load(open(cand))
+            if isinstance(desc, dict) and "components" in desc:
+                break
+        except (OSError, ValueError):
+            desc = {}
+    objs, grip = [], None
+    for cname, comp in (desc.get("components") or {}).items():
+        if not isinstance(comp, dict):
+            continue
+        if cname == "openxr_grip" and isinstance(comp.get("component_local"), dict):
+            local = comp["component_local"]
+            grip = (list(local.get("origin") or [0, 0, 0]), _rotation_xyz(local.get("rotate_xyz") or [0, 0, 0]))
+        fn = comp.get("filename")
+        hidden = (comp.get("visibility") or {}).get("default") is False  # e.g. status LEDs
+        if fn and not hidden and not any(s in cname.lower() for s in SKIP_COMPONENTS):
+            p = os.path.join(model_dir, fn)
+            if os.path.exists(p):
+                objs.append(p)
+    if not objs:
+        whole = os.path.join(model_dir, name + ".obj")
+        objs = [whole] if os.path.exists(whole) else sorted(glob.glob(os.path.join(model_dir, "*.obj")))
+    return objs, grip
+
+
+def parse_mtl(path):
+    """material name -> texture file (map_Kd)."""
+    out, cur = {}, None
+    try:
+        for line in open(path, errors="replace"):
+            parts = line.strip().split(None, 1)
+            if not parts:
+                continue
+            if parts[0] == "newmtl" and len(parts) > 1:
+                cur = parts[1].strip()
+            elif parts[0] == "map_Kd" and cur and len(parts) > 1:
+                out[cur] = os.path.join(os.path.dirname(path), parts[1].strip().split()[-1])
+    except OSError:
+        pass
+    return out
+
+
+def parse_obj(path):
+    """-> list of (texture path or None, positions, normals, uvs, triangles as (v, vt, vn) index triples)."""
+    pos, nrm, uv = [], [], []
+    groups = {}  # texture -> list of corner triples
+    mats, tex = {}, None
+    for line in open(path, errors="replace"):
+        parts = line.split()
+        if not parts:
+            continue
+        tag = parts[0]
+        if tag == "v":
+            pos.append(tuple(float(x) for x in parts[1:4]))
+        elif tag == "vn":
+            nrm.append(tuple(float(x) for x in parts[1:4]))
+        elif tag == "vt":
+            uv.append((float(parts[1]), float(parts[2]) if len(parts) > 2 else 0.0))
+        elif tag == "mtllib":
+            mats.update(parse_mtl(os.path.join(os.path.dirname(path), " ".join(parts[1:]))))
+        elif tag == "usemtl":
+            tex = mats.get(" ".join(parts[1:]))
+        elif tag == "f":
+            corners = []
+            for c in parts[1:]:
+                idx = (c.split("/") + ["", ""])[:3]
+                ref = []
+                for i, n in zip(idx, (len(pos), len(uv), len(nrm)), strict=True):
+                    ref.append(None if not i else (int(i) - 1 if int(i) > 0 else n + int(i)))
+                corners.append(tuple(ref))
+            for i in range(1, len(corners) - 1):  # fan triangulation
+                groups.setdefault(tex, []).extend((corners[0], corners[i], corners[i + 1]))
+    return pos, nrm, uv, groups
+
+
+def controller_glb(model_dir):
+    """glTF binary (one mesh, one primitive per texture, PNG/JPEG textures, in the controller's OpenXR grip space
+    when the model defines openxr_grip) for a SteamVR render model folder."""
+    objs, grip = model_description(model_dir)
+    if not objs:
+        raise AgentError(f"no .obj files in {model_dir}")
+    # texture -> (positions, normals, uvs, indices), vertices de-duplicated per corner triple
+    prims = {}
+    for obj in objs:
+        pos, nrm, uv, groups = parse_obj(obj)
+        for tex, corners in groups.items():
+            if tex and os.path.splitext(tex)[1].lower() not in (".png", ".jpg", ".jpeg"):
+                tex = None
+            p = prims.setdefault(tex, {"pos": [], "nrm": [], "uv": [], "idx": [], "map": {}})
+            for c in corners:
+                key = (obj, c)
+                if key not in p["map"]:
+                    p["map"][key] = len(p["pos"])
+                    v = pos[c[0]]
+                    n = nrm[c[2]] if c[2] is not None and c[2] < len(nrm) else (0.0, 0.0, 1.0)
+                    t = uv[c[1]] if c[1] is not None and c[1] < len(uv) else (0.0, 0.0)
+                    if grip:  # raw device space -> grip space: R^T (v - origin)
+                        o, r = grip
+                        d = [v[k] - float(o[k]) for k in range(3)]
+                        v = tuple(sum(r[k][j] * d[k] for k in range(3)) for j in range(3))
+                        n = tuple(sum(r[k][j] * n[k] for k in range(3)) for j in range(3))
+                    p["pos"].append(v)
+                    p["nrm"].append(n)
+                    p["uv"].append((t[0], 1.0 - t[1]))  # OBJ origin bottom-left, glTF top-left
+                p["idx"].append(p["map"][key])
+    blob = bytearray()
+    views, accessors, images, textures, materials, primitives = [], [], [], [], [], []
+
+    def add_view(data, target=None):
+        while len(blob) % 4:
+            blob.append(0)
+        view = {"buffer": 0, "byteOffset": len(blob), "byteLength": len(data)}
+        if target:
+            view["target"] = target
+        blob.extend(data)
+        views.append(view)
+        return len(views) - 1
+
+    def add_accessor(values, width, ctype, kind, target, minmax=False):
+        fmt = {5126: "f", 5125: "I"}[ctype]
+        flat = [x for v in values for x in (v if width > 1 else (v,))]
+        acc = {"bufferView": add_view(struct.pack(f"<{len(flat)}{fmt}", *flat), target), "componentType": ctype,
+               "count": len(values), "type": kind}
+        if minmax:
+            acc["min"] = [min(v[k] for v in values) for k in range(width)]
+            acc["max"] = [max(v[k] for v in values) for k in range(width)]
+        accessors.append(acc)
+        return len(accessors) - 1
+
+    for tex, p in prims.items():
+        if not p["idx"]:
+            continue
+        attrs = {"POSITION": add_accessor(p["pos"], 3, 5126, "VEC3", 34962, minmax=True),
+                 "NORMAL": add_accessor(p["nrm"], 3, 5126, "VEC3", 34962),
+                 "TEXCOORD_0": add_accessor(p["uv"], 2, 5126, "VEC2", 34962)}
+        indices = add_accessor(p["idx"], 1, 5125, "SCALAR", 34963)
+        mat = {"pbrMetallicRoughness": {"metallicFactor": 0.0, "roughnessFactor": 0.8}}
+        if tex and os.path.exists(tex):
+            mime = "image/png" if tex.lower().endswith(".png") else "image/jpeg"
+            images.append({"bufferView": add_view(open(tex, "rb").read()), "mimeType": mime})
+            textures.append({"source": len(images) - 1})
+            mat["pbrMetallicRoughness"]["baseColorTexture"] = {"index": len(textures) - 1}
+        else:
+            mat["pbrMetallicRoughness"]["baseColorFactor"] = [0.1, 0.1, 0.1, 1.0]
+        materials.append(mat)
+        primitives.append({"attributes": attrs, "indices": indices, "material": len(materials) - 1})
+    if not primitives:
+        raise AgentError(f"no triangles in {model_dir}")
+    while len(blob) % 4:
+        blob.append(0)
+    gltf = {"asset": {"version": "2.0", "generator": "FramePort agent"}, "scene": 0, "scenes": [{"nodes": [0]}],
+            "nodes": [{"name": os.path.basename(model_dir), "mesh": 0}],
+            "meshes": [{"primitives": primitives}], "materials": materials, "accessors": accessors,
+            "bufferViews": views, "buffers": [{"byteLength": len(blob)}]}
+    if images:
+        gltf.update(images=images, textures=textures, samplers=[{}])
+        for t in textures:
+            t["sampler"] = 0
+    js = json.dumps(gltf, separators=(",", ":")).encode()
+    js += b" " * (-len(js) % 4)
+    total = 12 + 8 + len(js) + 8 + len(blob)
+    return (struct.pack("<III", 0x46546C67, 2, total) + struct.pack("<I4s", len(js), b"JSON") + js
+            + struct.pack("<I4s", len(blob), b"BIN\x00") + bytes(blob))
+
+
+def _tree_stamp(d):
+    h = hashlib.sha256()
+    for p in sorted(glob.glob(os.path.join(d, "*"))):
+        st = os.stat(p)
+        h.update(f"{os.path.basename(p)}:{st.st_size}:{int(st.st_mtime)}\n".encode())
+    return h.hexdigest()[:16]
+
+
+def frame_controller_models():
+    """Converted (cached) glb paths for the Frame controllers: {'left': path, 'right': path, 'sources': {...}}."""
+    picked = pick_controller_models(render_model_dirs())
+    if not picked:
+        raise AgentError("no Steam Frame controller render models found in SteamVR (looked in: "
+                         + ", ".join(steamvr_roots() or ["no SteamVR install"]) + ")")
+    os.makedirs(MODELS_CACHE, exist_ok=True)
+    out = {"sources": picked}
+    for side, d in picked.items():
+        cached = os.path.join(MODELS_CACHE, f"{os.path.basename(d)}-{_tree_stamp(d)}.glb")
+        if not os.path.exists(cached):
+            data = controller_glb(d)
+            with open(cached + ".tmp", "wb") as f:
+                f.write(data)
+            os.replace(cached + ".tmp", cached)
+        out[side] = cached
+    return out
+
+
+def install_controller_models(files_dir, enabled):
+    """Put (or remove) framebridge/controller_{left,right}.glb in a game's files dir. Never fails the install."""
+    target = os.path.join(files_dir, "framebridge")
+    if not enabled:
+        for side in ("left", "right"):
+            p = os.path.join(target, f"controller_{side}.glb")
+            if os.path.exists(p):
+                os.remove(p)
+        return None
+    try:
+        models = frame_controller_models()
+    except (AgentError, OSError, ValueError, IndexError) as e:
+        return {"ok": False, "error": str(e)}
+    os.makedirs(target, exist_ok=True)
+    for side in ("left", "right"):
+        shutil.copyfile(models[side], os.path.join(target, f"controller_{side}.glb"))
+    return {"ok": True, "sources": models["sources"]}
+
+
+def cmd_controller_models(args):
+    """Diagnostics: SteamVR roots, every render model found, and which ones are used as the Frame controllers."""
+    dirs = render_model_dirs()
+    result = {"roots": steamvr_roots(), "render_models": dirs, "picked": pick_controller_models(dirs)}
+    if args.get("convert"):
+        try:
+            result["converted"] = frame_controller_models()
+        except (AgentError, OSError, ValueError, IndexError) as e:
+            result["error"] = str(e)
+    return result


 # ------------------------------------------------------------------------------------------ PC VR (Rift) under Proton
@@ -1171,7 +1637,8 @@ def windows_path(path):


 XR_LAYER = "XR_APILAYER_FRAMEPORT_timefix"
-XR_LAYER_ENV = (f'# FramePort OpenXR layer: OpenXR 1.1 -> 1.0 fallback for the Frame runtime (+ timespec time emulation)\n'
+XR_LAYER_ENV = (f'# FramePort OpenXR layer: OpenXR 1.1 -> 1.0 fallback for the Frame runtime'
+                f' (+ timespec time emulation)\n'
                f'export XR_API_LAYER_PATH="$base/xrlayer${{XR_API_LAYER_PATH:+:$XR_API_LAYER_PATH}}"\n'
                f'export XR_ENABLE_API_LAYERS="{XR_LAYER}${{XR_ENABLE_API_LAYERS:+:$XR_ENABLE_API_LAYERS}}"\n')

@@ -1218,7 +1685,7 @@ def write_proton_launcher(anchor, base, pkg, title, appid, tool, exe_rel, revive
        argv = prefix + [injector, "/openxr", windows_path(exe)]
    else:
        argv = prefix + [exe]
-    argv += [a for a in game_args or () if re.fullmatch(r"-[A-Za-z0-9_=.:-]+", a)]
+    argv += [a for a in game_args or () if re.fullmatch(r"[A-Za-z0-9_=.:/+-]+", a)]  # e.g. -hmd=OpenXR, -vrmode OpenVR
    extra = "".join(f"export {k}={shlex.quote(str(v))}\n" for k, v in (env or {}).items()
                    if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", k))
    workdir = os.path.dirname(exe_rel)
@@ -1248,6 +1715,41 @@ def set_crash_reporter(base, enabled):
                os.replace(p, p[:-len(".disabled")])


+def set_libovr_redirect(base, exe_rel, enabled, bundled=False):
+    """LoadLibrary redirect (pure runtime substitution): put LibOVRRT{64,32}_1.dll in the game's own DLL search dir as
+    a symlink to Revive's LibReviveXR runtime, so the game's Oculus SDK finds a runtime to load. The symlink keeps the
+    DLL in the revive/ folder, so its sibling dependencies still resolve. This does NOT touch the game's runtime
+    signature check — a build that verifies the Oculus signature of LibOVRRT will still reject Revive's (unsigned)
+    runtime; this only helps builds that don't verify it. We only ever create/remove our own symlink, never a real
+    DLL the game shipped. Removed when disabled."""
+    game = os.path.join(base, "game")
+    exe_dir = os.path.dirname(os.path.join(game, exe_rel))
+    # the runtime: FramePort's Revive (revive/LibReviveXR*), or with bundled=True the repack's own LibRevive*.dll
+    # next to the exe (a repack set up for SteamVR, whose Windows loader hook doesn't take effect under Proton)
+    runtimes = {bits: (os.path.join(exe_dir, f"LibRevive{bits}.dll") if bundled else
+                       os.path.join(base, "revive", f"LibReviveXR{bits}.dll")) for bits in ("64", "32")}
+    # where the Oculus SDK looks for LibOVRRT: the game exe's dir (monolithic engines carry the shim in the exe) AND
+    # next to every OVRPlugin.dll (Unreal's shim searches its own module dir).
+    dirs = {os.path.dirname(os.path.join(game, exe_rel))}
+    for root, _, files in os.walk(game):
+        for n in files:
+            if n.lower() == "ovrplugin.dll":
+                dirs.add(root)
+    for d in dirs:
+        for bits, target in runtimes.items():
+            link = os.path.join(d, f"LibOVRRT{bits}_1.dll")
+            ours = os.path.islink(link) and os.path.basename(os.path.realpath(link)).lower().startswith("librevive")
+            if ours and os.path.realpath(link) != os.path.realpath(target):
+                os.remove(link)  # switched between FramePort's and the bundled Revive
+            if enabled and os.path.isfile(target):
+                if os.path.islink(link) or not os.path.exists(link):  # never clobber a real game-shipped DLL
+                    if os.path.lexists(link):
+                        os.remove(link)
+                    os.symlink(target, link)
+            elif ours:
+                os.remove(link)
+
+
 def cmd_finalize_pcvr(args):
    """Move uploaded game/Revive files into place, delete files the new version no longer has, write the Proton
    launcher and deployment.json. The Proton prefix (saves) is kept."""
@@ -1298,6 +1800,7 @@ def cmd_finalize_pcvr(args):
    if oculus_hmd and not os.path.isfile(os.path.join(base, "helpers", OCULUS_HMD_HELPER)):
        raise AgentError(f"{OCULUS_HMD_HELPER} missing")
    set_crash_reporter(base, enabled=not args.get("no_crash_reporter"))
+    set_libovr_redirect(base, exe_rel, enabled=bool(args.get("libovr_redirect")), bundled=not revive)
    write_proton_launcher(anchor, base, pkg, title, appid, tool, exe_rel, revive, args.get("env"), xr_layer,
                          args.get("game_args") or [], oculus_hmd)
    art_in = os.path.join(base, "incoming-artwork")
@@ -1307,7 +1810,9 @@ def cmd_finalize_pcvr(args):
    dep = {"package": pkg, "kind": "pcvr", "appid": int(appid), "base": base, "title": title, "exe": exe_rel,
           "tags": args.get("tags") or [],
           "sha256": args.get("exe_sha256"), "revive": revive, "revive_version": args.get("revive_version"),
-           "proton": tool["name"], "xr_layer": xr_layer, "oculus_hmd": oculus_hmd, "recipe": args.get("recipe"),
+           "proton": tool["name"], "xr_layer": xr_layer, "oculus_hmd": oculus_hmd,
+           "libovr_redirect": bool(args.get("libovr_redirect")),
+           "recipe": args.get("recipe"),
           "installed_by": "frameport",
           "files": {t: manifests.get(t) or {} for t in PCVR_TREES},
           "agent_version": AGENT_VERSION, "time": time.time()}
@@ -1316,6 +1821,29 @@ def cmd_finalize_pcvr(args):
    return {"ok": True, "base": base, "appid": appid, "moved_files": moved, "proton": tool["name"]}


+AWAKE_UNIT = "frameport-awake"
+
+
+def cmd_keep_awake(args):
+    """Keep the Frame from going idle/asleep while FramePort installs games (on=False ends it). An inhibitor lock held
+    by a `sleep` in its own user unit, so it outlives this SSH command and ends by itself after `minutes` if FramePort
+    disappears. Blocking sleep needs a local session (polkit inhibit-block-sleep: auth_admin_keep for others), so
+    when logind refuses it, idle alone is blocked (allowed for any user)."""
+    run(["systemctl", "--user", "stop", f"{AWAKE_UNIT}.service"])
+    run(["systemctl", "--user", "reset-failed", f"{AWAKE_UNIT}.service"])
+    if not args.get("on", True):
+        return {"awake": False}
+    seconds = int(min(max(float(args.get("minutes", 60)), 1), 240) * 60)
+    for what in ("idle:sleep", "idle"):
+        run(["systemd-run", "--user", "--collect", "--quiet", f"--unit={AWAKE_UNIT}", "systemd-inhibit",
+             f"--what={what}", "--who=FramePort", "--why=Installing games", "--mode=block", "sleep", str(seconds)])
+        time.sleep(0.7)  # a refused lock ends the unit right away
+        if run(["systemctl", "--user", "is-active", f"{AWAKE_UNIT}.service"]).stdout.strip() == "active":
+            return {"awake": True, "what": what, "seconds": seconds}
+        run(["systemctl", "--user", "reset-failed", f"{AWAKE_UNIT}.service"])
+    return {"awake": False}
+
+
 def cmd_set_settings(args):
    pkg = check_pkg(args["package"])
    dep = deployment(pkg) or {}
@@ -1340,7 +1868,8 @@ def cmd_set_settings(args):
    os.makedirs(files_dir, exist_ok=True)
    with open(os.path.join(files_dir, "framebridge.conf"), "w") as f:
        f.write(text)
-    return {"settings": current}
+    models = install_controller_models(files_dir, current.get("controller_models", "0") not in ("0", "0.0"))
+    return {"settings": current, "controller_models": models}


 def cmd_uninstall(args):
@@ -1364,11 +1893,10 @@ def cmd_uninstall(args):
    if not keep_data:
        shutil.rmtree(base, ignore_errors=True)
    anchor = os.path.join(ANCHORS, pkg)
-    users = steam_users()
    removed_sc = False
-    if len(users) == 1 and args.get("remove_shortcut"):
-        removed_sc = remove_shortcut(os.path.join(STEAM, "userdata", users[0], "config/shortcuts.vdf"),
-                                     f'"{anchor}/launch.sh"')  # takes effect after the next Steam restart
+    if args.get("remove_shortcut") and len(steam_users()) == 1:
+        # Steam keeps its own copy of shortcuts.vdf and writes it back: change it only with Steam closed (worker)
+        removed_sc = cmd_shortcuts({"remove": [{"exe": f'"{anchor}/launch.sh"', "appid": dep.get("appid")}]})["started"]
    if not keep_data or base != anchor:
        shutil.rmtree(anchor, ignore_errors=True)
    else:  # saves live next to the launcher (Quest games): keep them, drop what marks the game as installed
@@ -1421,7 +1949,7 @@ def game_logs(base, since=0.0):
        raw = open(ctx, "rb").read().decode("utf-8", "replace")
        fields = []
        for tag in ("ErrorMessage", "CrashType", "EngineVersion", "CallStack", "SourceContext"):
-            m = re.search(r"<%s>(.*?)</%s>" % (tag, tag), raw, re.S)
+            m = re.search(rf"<{tag}>(.*?)</{tag}>", raw, re.S)
            if m and m.group(1).strip():
                fields.append(f"{tag}: {m.group(1).strip()[:3000]}")
        out.append(f"===== crash {os.path.relpath(os.path.dirname(ctx), base)} (UE4CC)\n" + "\n".join(fields))
@@ -1465,10 +1993,20 @@ def cmd_launch_test(args):
            state = "NEVER_STARTED"
            break
    elapsed = round(time.time() - start)
+    if state == "EXITED":  # Lepton dumps the container's logcat buffers (crash backtraces) after "Exited!"
+        until = time.time() + 15
+        while time.time() < until and "Dumping logcat" not in (open(log, errors="replace").read()
+                                                                if os.path.exists(log) else ""):
+            time.sleep(1)
+        time.sleep(2)
    run(["systemctl", "--user", "stop", unit])
    run(["podman", "kill", f"lepton-steamlaunch-{appid}"])
    time.sleep(3)
-    return {"state": state, "elapsed": elapsed, "log": log, "log_size": os.path.getsize(log) if os.path.exists(log) else 0,
+    crash = os.path.join(STEAM, "logs", "lepton-logcats", f"steamlaunch-{appid}", "logcat-crash.log")
+    fresh = os.path.exists(crash) and os.path.getmtime(crash) >= start - 1 and os.path.getsize(crash) > 0
+    return {"state": state, "elapsed": elapsed, "log": log,
+            "log_size": os.path.getsize(log) if os.path.exists(log) else 0,
+            "crash_log": crash if fresh else None,
            "kernel_keys_before": keys, "kernel_keys_after": key_usage()}


@@ -1516,6 +2054,90 @@ def launch_test_pcvr(dep, anchor, log, seconds):
            "kind": "pcvr", "game_process": bool(game_seen)}


+def _tail(path, max_bytes):
+    try:
+        size = os.path.getsize(path)
+        with open(path, "rb") as f:
+            if size > max_bytes:
+                f.seek(size - max_bytes)
+            data = f.read()
+        text = data.decode("utf-8", "replace")
+        return (f"[... first {size - max_bytes} bytes cut ...]\n" if size > max_bytes else "") + text
+    except OSError:
+        return None
+
+
+def cmd_collect_diag(args):
+    """Everything useful for debugging without the game or the PC app: host runtime facts and, with a package, the
+    game's launcher, settings, deployment, logs (launch, Lepton logcat, Proton/Revive/Unreal) and its file listing.
+    Returns {"host": {...}, "files": {name: text}, "listing": ...}; the PC redacts and zips it."""
+    max_bytes = int(args.get("max_bytes", 2 << 20))
+    files, host = {}, {}
+    host["openxr_runtime"] = openxr_runtime()
+    layers = os.path.join(HOME, ".local/share/openxr/1/api_layers/explicit.d")
+    host["openxr_layers"] = sorted(os.listdir(layers)) if os.path.isdir(layers) else []
+    host["kernel_keys"] = key_usage()
+    host["containers_conf"] = _tail(CONTAINERS_CONF, 20000)
+    host["podman"] = run(["podman", "ps", "-a", "--filter", "name=lepton", "--format",
+                          "{{.Names}} {{.Status}}"]).stdout[-20000:]
+    host["steam_running"] = run(["pgrep", "-x", "steam"]).returncode == 0
+    host["uptime"] = _tail("/proc/uptime", 200)
+    host["installed"] = [{k: g.get(k) for k in ("package", "title", "kind", "appid", "version", "agent_version")}
+                         for g in cmd_list_installed({})["games"]]
+    out = {"agent_version": AGENT_VERSION, "host": host, "files": files}
+    pkg = args.get("package")
+    if not pkg:
+        # the OpenXR runtime's own log (XRService-<date>_<time>.log): the newest one
+        xr = [p for p in glob.glob(os.path.join(STEAM, "logs/XRService-*.log")) +
+              glob.glob(os.path.join(STEAM, "logs/XRService-*/XRService-*.log")) if os.path.isfile(p)]
+        for p in sorted(xr, key=os.path.getmtime, reverse=True)[:1]:
+            files[os.path.basename(p)] = _tail(p, max_bytes)
+        return out
+    pkg = check_pkg(pkg)
+    dep = deployment(pkg)
+    anchor = os.path.join(ANCHORS, pkg)
+    if not dep:
+        out["installed"] = False
+        return out
+    out["installed"] = True
+    base, appid = dep["base"], dep.get("appid")
+    dep = dict(dep)
+    dep.pop("files", None)  # the install manifest is large; `listing` below has the real files
+    files["deployment.json"] = json.dumps(dep, indent=1)
+    for name, path in (("launch.sh", os.path.join(anchor, "launch.sh")),
+                       ("settings.conf", os.path.join(base, "settings.conf")),
+                       ("launch.log", os.path.join(base, "launch.log")),
+                       ("launch-test.log", os.path.join(base, "launch-test.log"))):
+        text = _tail(path, max_bytes)
+        if text is not None:
+            files[name] = text
+    for rel in PCVR_LOGS + (f"steam-{appid}.log",):
+        text = _tail(os.path.join(base, rel), max_bytes)
+        if text is not None:
+            files[os.path.basename(rel)] = text
+    if dep.get("kind") == "pcvr":
+        for i, part in enumerate(game_logs(base)):
+            files[f"game-log-{i}.txt"] = part[-max_bytes:]
+    logs = os.path.join(STEAM, "logs")
+    text = _tail(os.path.join(logs, f"lepton-steamlaunch-{appid}.log"), max_bytes)  # Lepton's launcher log
+    if text is not None:
+        files[f"lepton-steamlaunch-{appid}.log"] = text
+    logcats = os.path.join(logs, "lepton-logcats")
+    # the container's logcat buffers: lepton-logcats/steamlaunch-<appid>/logcat-{main,crash,system,kernel,radio}.log
+    order = ("main", "crash", "system", "kernel", "radio")
+    cands = [p for p in glob.glob(os.path.join(logcats, f"steamlaunch-{appid}", "*")) if os.path.isfile(p)]
+    for p in sorted(cands, key=lambda p: next((i for i, k in enumerate(order) if k in os.path.basename(p)), 9)):
+        name = os.path.basename(p)
+        files[name if name.startswith("logcat") else "logcat-" + name] = _tail(p, max_bytes)
+    try:
+        listing = cmd_list_files({"package": pkg, "limit": 20000})
+        out["listing"] = {"missing": listing["missing"], "truncated": listing["truncated"],
+                          "roots": [{"name": r["name"], "files": r["files"]} for r in listing["roots"]]}
+    except AgentError:
+        pass
+    return out
+
+
 AGENT_HOME = os.path.join(HOME, ".local/share/frameport")


@@ -1557,7 +2179,7 @@ def purge_worker(payload):
                try:
                    if remove_shortcut(vdf, f'"{os.path.join(ANCHORS, d["package"])}/launch.sh"'):
                        result["removed"].append(f"Steam shortcut: {d.get('title')}")
-                    for art in glob.glob(os.path.join(grid, f"{d['appid']}*")):
+                    for art in grid_files(grid, d["appid"]):
                        os.remove(art)
                except Exception as exc:  # noqa: BLE001
                    result["errors"].append(f"{d.get('title')}: {exc}")
@@ -1621,10 +2243,13 @@ def cmd_cleanup(args):
                removed.append(p)
    for extra in args.get("paths", []):
        p = os.path.realpath(os.path.expanduser(extra))
-        if not p.startswith(HOME + os.sep) or p.startswith(ANCHORS) or p == os.path.join(HOME, ".local"):
+        first = os.path.relpath(p, HOME).split(os.sep)[0] if p.startswith(HOME + os.sep) else ""
+        if not first or first.startswith(".") or p == ANCHORS or p.startswith(ANCHORS + os.sep):
+            # only ordinary folders in the home folder: never dot folders (.ssh, .steam, .local, .config…)
            raise AgentError(f"refusing to remove {extra}")
        if os.path.exists(p):
-            freed += sum(os.path.getsize(os.path.join(r, f)) for r, _, fs in os.walk(p) for f in fs) if os.path.isdir(p) else os.path.getsize(p)
+            freed += (sum(os.path.getsize(os.path.join(r, f)) for r, _, fs in os.walk(p) for f in fs)
+                      if os.path.isdir(p) else os.path.getsize(p))
            shutil.rmtree(p, ignore_errors=True) if os.path.isdir(p) else os.remove(p)
            removed.append(p)
    return {"removed": removed, "freed_bytes": freed}
@@ -1,9 +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,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
@@ -9,8 +9,11 @@ notes: Some launch warning text is still upside down; the rest of the UI is fixe
  may not work.
 details: Ubisoft online login may not work. Data folder holds raw assets (start0..2, .climb, bundles), not .obb
  files; install to obb as-is.
+overport_extra:
+- patch_ac_nexus_no_appsw_90
 verified:
  date: '2026-09-28'
  overport_cli: 1.2.3
  overport_runtime: 3.4.3-23204ea
  known_good_sha256: 89644a12bf8df956fa3d3a9a40540ba9e1fb62f63494714a05c9f05984383ac8
+  no_appsw_90: '2026-10-02, OVRPort 1.2.5 (owner: 90 Hz felt better than 72 Hz; same known issues)'
@@ -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,7 +1,7 @@
 package: com.crytek.climb2
 title: The Climb 2
 tested_version: '2.2'
-source_hint: The Climb 2 v974+2.2
+source_hint: The Climb 2
 engine: CryEngine
 xr: VrApi
 status: works
@@ -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
@@ -2,7 +2,7 @@ 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 v2288226
+source_hint: 'Rick and Morty - Virtual Rick-ality'
 engine: Unity
 xr: OpenVR
 status: works
@@ -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,15 +1,19 @@
 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
-notes: Needed Oculus OS telemetry class stubs.
+notes: Needs Oculus OS telemetry class stubs and the no-ForceQuit build (the normal build quits right after
+  starting).
 verified:
-  date: '2026-09-28'
+  date: '2026-10-02'  # owner-confirmed with the no-ForceQuit build
  overport_cli: 1.2.3
  overport_runtime: 3.4.3-23204ea
  known_good_sha256: 31469d50b8ee292597291db7cc3bc3eca8e851f533cd92bba0d64214893580cc
 frame:
 - frame.oculusos
+alt_overport:
+- patch_remove_unreal_force_quit
+use_alt: true
@@ -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
@@ -156,6 +194,7 @@ signatures:
    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)'
@@ -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,
@@ -55,10 +56,31 @@ apart. "Build" = `pipeline.prepare_rift` (checks + Revive). Revive is a portable
  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 `native/build.sh`, commit the new artifacts + SHA256SUMS,
+- **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.
@@ -14,6 +14,19 @@
  `keyring = false` in `~/.config/containers/containers.conf`; a reboot clears already-leaked keys.
 - Picks the activity with category LAUNCHER (`APP_ACTIVITY`). Game data is visible at `/sdcard/Android/{obb,data}/<pkg>`.
 - 64-bit only (no AArch32).
+- `<install>/lepton-shaders/` holds Mesa's shader cache (Lepton sets `mesa.shader.cache.dir=/data/shaders`):
+  `foz_cache.foz` + `foz_cache_idx.foz` per graphics driver (Turnip Vulkan, zink GL), typically 4–6 files and 7–19 MB
+  per game, 2D apps included. It speeds up later starts; deleting it only costs one slower start.
+- **2D apps** (verified 2026-10-02 with an open-source 2048 game): Lepton runs every app headless
+  (`lepton.headless=true`; only OpenXR output reaches the headset) unless the app folder (`STEAM_COMPAT_INSTALL_PATH`)
+  contains a file `lepton-show-flatscreen` (`liblepton/app_metadata.sh`): then Android (11, Waydroid) gets a Wayland
+  window shown as a flat panel in the headset. FramePort creates the file for Android apps without VR. Android's
+  back/home/recents bar is drawn over the app's own controls; `qemu.hw.mainkeys=1` removes it, but it's only read at
+  boot and Lepton has no setting for extra properties, so patch `device.hide_navbar` (default on for apps without
+  VR) passes it as a second line of a
+  `LEPTON_GFXRECON_*` value (Lepton copies those into the boot properties unescaped). Runtime alternatives didn't
+  work on Android 11: `policy_control` is gone, `cmd statusbar send-disable-flag home recents` has no `back` and
+  moves the back button onto the app's controls, the `sysui_nav_bar` layout and disabling SystemUI had no effect.

 ## OpenXR runtime (as seen by games through overport's loader)
 - Instance extensions present include KHR_android_create_instance (must be enabled; the adapter adds it),
@@ -22,8 +35,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).
@@ -1,59 +1,138 @@
 # 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; Ubuntu 22.04 or newer) | `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`.

-## Oculus Rift (PC VR) games
-Scan a folder of Rift games (one folder per game; the game may sit a few levels down, next to installers and archives)
-the same way as Quest dumps, or use **Add games → Add one game folder…**. FramePort finds the program that starts
-each game; when it isn't sure (e.g. an Oculus and a Steam build side by side) it asks you. It also fetches artwork, descriptions, genres and
-(for games also sold on Steam) screenshots, and gives each Steam library entry full artwork plus tags for how it
-runs, its original platform (Meta Quest / Oculus Rift) and its genres. If your copies are already patched, switch on **Already patched** on the game page:
-Quest APKs are installed unchanged, Rift games start without Revive. If you installed Revive
-yourself (official installer), FramePort uses that one; otherwise it downloads its own portable copy (Tools shows which;
-nothing is installed system-wide).
- **Play from this PC:** needs Windows with Steam and SteamVR. "Install on this PC" adds the game to your Steam
-  library (Steam closes and reopens once); stream it to the Frame with Steam Link / SteamVR.
- **Play on the Frame (experimental):** Frame → "Install Proton" (confirm the download in the headset), then "Install
-  on Frame (Proton)" on the game page.
- Games that use the Oculus Platform SDK (FramePort shows a note) check your Oculus license: they need the Oculus app
-  installed on the PC with a license you own, so they can't run on the headset.
+## 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.
+
+## Installing games
+
+- **Install on Frame** on a game's page (or select several in the Library and install them together). Installs run
+  one after another in the background; **Activity** shows the current one at the top.
+- **Update all** reinstalls every game whose build changed (e.g. after a FramePort update). Questions that need an
+  answer (e.g. Oculus games that can't run on the Frame) are asked once, for all games.
+- If the Frame goes to sleep, turns off or leaves the Wi-Fi, the queue **waits** and continues once it's back; uploads
+  pick up where they stopped. While installs run, FramePort keeps the Frame from going to sleep. Before a large batch
+  it checks the Frame has enough free space.
+- Your own game files are never changed. The converted copy is temporary: it's removed once the game is on the Frame
+  (Settings → Installing: keep them, or remove all now).
+- **Game settings…** (game menu or the Steam Frame page): sharpness, refresh rate, controllers, menus, 360° video and
+  mixed-reality options in plain words, only those that matter for the game. Changes are kept with the game and,
+  when it's installed, used the next time it starts.
+- Ordinary Android apps (no VR) are installed unchanged and shown as a flat window in the headset. Android's
+  back/home/recents buttons are hidden by default (patch **Hide Android's navigation bar**).
+
+## 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.
+
+## PC VR games
+
+PC VR games are Windows VR games (OpenXR, SteamVR or Oculus). Scan a folder of them (one folder per game) or use
+**Add games → Add one game folder…**. FramePort finds the game's program and asks when there is more than one
+candidate. **Already patched** on a game page installs a copy unchanged. Oculus-only games need Revive: FramePort uses
+an installed Revive, or downloads a portable copy.
+
+- **Play from this PC:** Windows with Steam and SteamVR. **Install on this PC** adds the game to Steam; stream it to the
+  Frame with Steam Link. If a game can't keep up with the refresh rate, FramePort lowers the rate and enables motion
+  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.
+
+## Files on the Frame (videos, documents, mods, saves)
+
+The **Files** tab manages files on the Frame over the same connection as installs; no other transfer app is needed.
+Pick a location, browse folders, and use **Upload files** / **Upload folder**, **New folder**, or the download, rename
+and delete buttons on each entry. Tick several entries (or the box above the list for all) to download or delete them
+together. In the downloaded app you can also drag files and folders from Explorer / Finder / your file manager onto
+the list to upload them into the open folder. Uploads and downloads run in the Activity panel, resume after an interruption and
+skip files that are already there.
+
+- **Videos**, **Downloads** and **Documents** appear inside every Quest game as `/sdcard/Movies`, `/sdcard/Download`
+  and `/sdcard/Documents`. Apps find files by browsing folders; Android's media index doesn't work on the Frame.
+- Under **Game storage**, each installed game has its own `/sdcard` (mods, saves). A game's menu → **Add videos and
+  files…** opens it. Video players that list only their own folder (e.g. 4XVR's "Internal Storage" = `4XPlayer`) find
+  videos uploaded into that folder.
+- **Home folder** shows everything in the Frame's home folder (hidden files with **Show hidden files**).
+
+Command line: `frameport frame send <files> --dest videos` (`frameport frame storage` lists the destinations).
+
+## Sharing a working game, reporting a problem
+
+- **Share working config…** (game menu): opens a prefilled GitHub issue with the game's patches and settings. Accepted
+  configs become built-in recipes. Untested games ask on their page once they've been installed or tested: **It
+  works**, **It has issues** or **It doesn't run**.
+- **Report a problem…** (game menu, or Settings → Problems and feedback): saves a diagnostics zip to Documents (logs,
+  recipe, device details; IP addresses, user names, home folders and Steam ids replaced) and opens a prefilled GitHub
+  issue to attach it to. Command line: `frameport diag report <game>`, `frameport share-recipe <game>`.
+
+## Command line
+
+Everything the app does is also a `frameport` command (in a source checkout: `uv run frameport`); `frameport --help`
+and `frameport <command> --help` describe every option. The main ones:
+
+| Command | What it does |
+|---|---|
+| `scan <folder>` / `list` / `show <game>` | add games, list the library, show a game's analysis and patches |
+| `recipe <game> --enable/--disable <patch>` | change a game's patches (`patches` lists them all) |
+| `build <game>` / `install <game>` / `test <game>` | build, install on the Frame (`--to pc` for PC VR on this PC), launch test |
+| `frame discover` / `frame connect` / `frame info` | find, pair with and describe the Frame |
+| `frame send` / `frame storage` / `frame cleanup` | copy files to the Frame, show where they go, free space |
+| `tools status` / `tools install` | the tools FramePort downloads |
+| `diag report <game>` / `share-recipe <game>` | report a problem / share a working recipe |
+| `update` | update FramePort |
+
+Exit codes: 0 done, 1 something failed, 2 wrong usage, 10 (`update --check`) a newer version exists. Errors are
+one line on stderr; `FRAMEPORT_DEBUG=1` shows the full traceback.

 ## Uninstalling
-Settings → **Uninstall FramePort…** (or `frameport uninstall-app`) removes everything FramePort created: its data
-folder (tools, library, artwork, cache, builds), the Steam shortcuts it added on this PC and, optionally, its games and
-files on the Frame (saves can be kept). It first saves a zip of your signing keys to Documents (game updates must be
-signed with the same key). Then delete the FramePort program folder.
+
+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
@@ -19,6 +19,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | 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) |
@@ -34,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 | upload in the Files tab (Videos = /sdcard/Movies) and browse folders in the app |
 | Game (Unity, GLES) freezes, `zink: DEVICE LOST` | multisampled render-to-texture hangs the GPU | `frame.unity_no_msaa`; if it persists: unfixable → PC version |
 | 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 |
@@ -41,17 +55,23 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 ## Picture problems (headset on)
 | Symptom | Cause | Fix |
 |---|---|---|
+| 2D Android app: Steam says it's running but nothing shows | Lepton runs apps headless unless the app folder has `lepton-show-flatscreen` | FramePort adds it for apps without VR (agent v28+); reinstall apps installed before |
+| 2D Android app: back/home/recents buttons cover the app's own buttons | Android's navigation bar | patch `device.hide_navbar` (on by default for apps without VR) sets `qemu.hw.mainkeys=1`; reinstall to apply |
 | Black screen, audio works, GLES engine with direct VrApi | Mesa rejects Quest-style GLSL | `frame.gl_shim` (logs `GLShim: SHADER COMPILE FAILED` + source lines) |
 | Black screen, audio works, log `Unsupported VrApi layer type N` | bridge drops frames containing that layer | extend the bridge (cylinder=3 is converted to a quad already) |
 | Only some draws visible (e.g. controllers) + `glGetError 0x502` | multiview shaders used on single-view FBOs | GL shim `gl_hide_multiview=1` (default) |
 | 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`
@@ -0,0 +1,28 @@
+# Writing style for FramePort's interface
+
+Short rules so every screen, help text and doc sounds the same. Code style is enforced by `ruff`.
+
+## Words
+- **Steam Frame** on first mention in a screen or document, **the Frame** after that. **Headset** only for the
+  physical device you wear ("put the headset on").
+- **Quest game** for Meta Quest apps, **Android app** for ordinary Android apps, **PC VR game** for Windows VR games.
+  Say Oculus or Rift only for games that use Oculus's own SDK.
+- **Patch** for anything in a game's patch list (never "fix" for the same thing). **Recipe** for a game's chosen
+  patches and settings.
+- Tools by their names: OVRPort, Revive, Proton, Lepton, SteamVR.
+- **Install** (first time), **Update** (a newer build), **Reinstall** (the same build again); **Play** starts a game.
+
+## Form
+- Buttons and headings in sentence case ("Add games", "Report a problem…"); one label per action everywhere.
+- "…" at the end of a label when the action asks for more input (a dialog, a file picker).
+- Sentences end with a period, including tooltips and help texts; labels don't.
+- "and", not "&", in text. An em dash (—) for asides, a middle dot (·) between short facts.
+- Sizes in GiB/MiB (`i18n.fmt_size`), dates as YYYY-MM-DD HH:MM (`i18n.fmt_datetime`).
+- US spelling (customize, analyze, color).
+- Plain, technical wording: say what happens ("Steam restarts once"), no marketing adjectives.
+
+## Translations
+- Every text the GUI shows goes through `tr("…")` or `tr_n("…", "…", n)` (see `src/frameport/i18n.py`); use
+  templates with `.format()`, never f-strings inside `tr()`, and never decide anything from a displayed text.
+- After changing texts run `python scripts/i18n_extract.py` (a test checks the template is current).
+- CLI output, logs, diagnostics, catalog notes and launch-test diagnoses stay English.
@@ -7,12 +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;
+}
@@ -10,7 +10,7 @@ timefix OpenXR layer for Proton games (linux-arm64, glibc; the NDK's clang build
 OculusHMDConnected helper for Rift games under Proton (win-x64 PE; the NDK's clang + lld-link, no Windows SDK), and
 rewrites artifacts/SHA256SUMS. Run `frameport parity` afterwards to see which games change.

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

@@ -138,8 +138,8 @@ 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)


@@ -181,6 +181,26 @@ def build_oculushmd(tc: Path, out: Path | None = None, defines=()):
         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")
@@ -210,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:
@@ -254,7 +291,7 @@ def write_sums():

 def main():
    ap = argparse.ArgumentParser()
-    ap.add_argument("--only", default="adapter,bridge,compat,glshim,dex,xrlayer,oculushmd")
+    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(","))
@@ -262,9 +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, "xrlayer": lambda: build_xrlayer(tc),
-             "oculushmd": lambda: build_oculushmd(tc)}
-    for name in ("adapter", "bridge", "compat", "glshim", "dex", "xrlayer", "oculushmd"):
+             "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,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,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,13 +1,27 @@
 [project]
 name = "frameport"
-version = "0.2.0"
-description = "Port Meta Quest standalone games to the Valve Steam Frame (Lepton): suggested patches, automated validation, one-click install."
+dynamic = ["version"]
+description = "Run Meta Quest, Android and PC VR games on the Valve Steam Frame: per-game patches, validation and one-click install."
 readme = "README.md"
-license = { text = "GPL-3.0-only" }
+license = "GPL-3.0-only"
+license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]
+authors = [{ name = "spoopyghosty0" }]
+keywords = ["steam-frame", "vr", "openxr", "meta-quest", "android", "lepton", "proton", "revive"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: X11 Applications",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Games/Entertainment",
+]
 requires-python = ">=3.11"
 dependencies = [
    "flet>=1.0",
    "flet-desktop>=1.0",
+    "flet-dropzone>=0.4.0",  # drag-and-drop uploads in the Files tab (packaged app only; Apache-2.0)
    "paramiko>=3.4",
    "zeroconf>=0.132",
    "psutil>=5.9",
@@ -20,17 +34,25 @@ dependencies = [
    "pyaxmlparser>=0.3.31",
 ]

+[project.urls]
+Homepage = "https://github.com/spoopyghosty0/frameport"
+Issues = "https://github.com/spoopyghosty0/frameport/issues"
+Releases = "https://github.com/spoopyghosty0/frameport/releases"
+
 [project.optional-dependencies]
-dev = ["pytest>=8", "flet-web>=1.0", "flet-cli>=1.0", "playwright>=1.40"]
+dev = ["pytest>=8", "pytest-timeout>=2.3", "ruff>=0.6", "flet-web>=1.0", "flet-cli>=1.0", "playwright>=1.40"]

 [project.scripts]
-frameport = "frameport.cli:app"
+frameport = "frameport.cli:main"
 frameport-gui = "frameport.ui.app:main"

 [build-system]
 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"]

@@ -42,8 +64,8 @@ packages = ["src/frameport"]

 [tool.pytest.ini_options]
 testpaths = ["tests"]
+timeout = 120
 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)",
 ]
@@ -56,3 +78,19 @@ company = "FramePort"
 [tool.flet.app]
 path = "src"
 module = "main"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+extend-exclude = ["native", "src/frameport/_data"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+ignore = [
+    "E731",  # lambdas assigned to names: used for small Flet callbacks
+    "B008",  # function calls in defaults: Typer options
+    "UP007", "UP045",  # Optional[...] in Typer signatures (Typer reads the annotations)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["frameport"]
@@ -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())
@@ -23,7 +23,8 @@ def signature(recipe) -> dict:
    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)
+        "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.")},
@@ -47,7 +48,8 @@ def main() -> int:
        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
+        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)
@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Collect every translatable text into src/frameport/locales/template.json (see src/frameport/i18n.py).
+
+    python scripts/i18n_extract.py          # rewrite the template
+    python scripts/i18n_extract.py --check  # exit 1 if the template is out of date (CI / tests)
+
+Sources: tr("…") and tr_n("…", "…", n) calls in src/frameport (literal arguments), the GUI help texts, and every
+patch's title and description. A translation file (locales/<language>.json) copies the template and fills in the
+values: a string for tr() texts, a list [one, other] for tr_n() texts.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src" / "frameport"
+TEMPLATE = SRC / "locales" / "template.json"
+sys.path.insert(0, str(ROOT / "src"))
+
+
+def from_code() -> tuple[dict, list[str]]:
+    """(texts, problems): tr()/tr_n() literals, and calls whose text isn't a literal (can't be extracted)."""
+    texts: dict = {}
+    problems = []
+    for path in sorted(SRC.rglob("*.py")):
+        if path.name == "i18n.py" and path.parent == SRC:
+            continue
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+        for node in ast.walk(tree):
+            if not (isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id in ("tr", "tr_n")):
+                continue
+            args = node.args[:1] if node.func.id == "tr" else node.args[:2]
+            if all(isinstance(a, ast.Constant) and isinstance(a.value, str) for a in args) and args:
+                if node.func.id == "tr":
+                    texts.setdefault(args[0].value, "")
+                else:
+                    texts[args[0].value] = ["", ""]
+            elif any(isinstance(a, ast.JoinedStr) for a in args):
+                problems.append(f"{path.relative_to(ROOT)}:{node.lineno}: f-string inside {node.func.id}() "
+                                "(use a template and .format())")
+    return texts, problems
+
+
+def from_data() -> dict:
+    """Help texts and patch titles/descriptions (defined as data, translated where they're shown)."""
+    from frameport.patches import base
+    from frameport.patches.settings import GROUPS, UI
+    from frameport.ui.help import HELP
+
+    texts = {dict.__getitem__(HELP, k): "" for k in HELP}
+    for p in base.all_patches():
+        for t in (p.title, p.description, p.summary):
+            if t:
+                texts[t] = ""
+    for _, title in GROUPS:  # the Game settings dialog
+        texts[title] = ""
+    for ui in UI.values():
+        for t in (ui.get("label"), ui.get("help")):
+            if t:
+                texts[t] = ""
+        if ui["control"][0] == "choice":
+            for _, label in ui["control"][1]:
+                if any(c.isalpha() for c in label):
+                    texts[label] = ""
+    return texts
+
+
+def build() -> tuple[dict, list[str]]:
+    code, problems = from_code()
+    texts = {**from_data(), **code}
+    return dict(sorted(texts.items(), key=lambda kv: kv[0].lower())), problems
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--check", action="store_true", help="only check that the template is up to date")
+    args = ap.parse_args()
+    texts, problems = build()
+    for p in problems:
+        print(p, file=sys.stderr)
+    text = json.dumps(texts, ensure_ascii=False, indent=1) + "\n"
+    if args.check:
+        current = TEMPLATE.read_text(encoding="utf-8") if TEMPLATE.exists() else ""
+        if current != text:
+            print("locales/template.json is out of date: run python scripts/i18n_extract.py", file=sys.stderr)
+            return 1
+        return 1 if problems else 0
+    TEMPLATE.parent.mkdir(parents=True, exist_ok=True)
+    TEMPLATE.write_text(text, encoding="utf-8")
+    print(f"{len(texts)} texts -> {TEMPLATE.relative_to(ROOT)}")
+    return 1 if problems else 0
+
+
+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,11 +48,18 @@ 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:
+            sep = ";" if TARGET == "windows" else ":"
+            # --yes: a failed flet build's folder doesn't stop it
            cmd = ["flet", "pack", str(ROOT / "src/main.py"), "--name", "FramePort", "--product-name", "FramePort",
-                   "--add-data", f"{DATA}{';' if TARGET == 'windows' else ':'}frameport/_data", "--distpath", str(ROOT / "dist")]
+                   "--add-data", f"{DATA}{sep}frameport/_data",
+                   # translations (data files PyInstaller doesn't pick up from the imports)
+                   "--add-data", f"{ROOT / 'src/frameport/locales'}{sep}frameport/locales",
+                   "--distpath", str(ROOT / "dist"), "--yes"]
        else:
            # --yes: install the Flutter SDK etc. without prompting; --no-rich-output: plain logs (CI, Windows consoles)
            cmd = ["flet", "build", TARGET, str(ROOT), "--project", "FramePort", "--product", "FramePort",
@@ -0,0 +1,94 @@
+#!/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] [--status works,issues]
+
+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"])
+    ap.add_argument("--status", default="", help="keep only games with these recipe statuses, e.g. works,issues")
+    args = ap.parse_args()
+    lib = json.loads((args.src / "library.json").read_text())
+    keep = {x for x in args.status.split(",") if x}
+    games = {pkg: scrub_game(g) for pkg, g in lib.get("games", {}).items()
+             if not keep or (g.get("recipe") or {}).get("status", "unknown") in keep}
+    view = {**(lib.get("settings", {}).get("ui.library") or {}), "sort": args.sort, "platform": "all",
+            "where": "all", "status": "all", "tags": []}
+    migrations = lib.get("settings", {}).get("migrations", [])
+    out = {"games": games, "settings": {"ui.library": view, "migrations": 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,84 @@ PORT = 8557
 ERRORS: list[str] = []


+class FakeFS:
+    """--fake-frame's file system for the Files tab: a temp folder with sample files, served like SFTP."""
+
+    def __init__(self):
+        import tempfile
+
+        self.home = tempfile.mkdtemp(prefix="fp-fake-frame-")
+        samples = {"Videos": ["Earth from orbit (360).mp4", "Mars landing (VR180).mkv", "Concert 8K 3D.mp4"],
+                   "Downloads": ["Mods/", "readme.txt"], "Documents": ["Saves/", "Notes.pdf"]}
+        sizes = {".mp4": 2_400_000_000, ".mkv": 1_100_000_000}
+        for folder, names in samples.items():
+            base = os.path.join(self.home, folder)
+            os.makedirs(os.path.join(base, "Trips"), exist_ok=True)
+            for n in names:
+                if n.endswith("/"):
+                    os.makedirs(os.path.join(base, n), exist_ok=True)
+                else:
+                    with open(os.path.join(base, n), "wb") as f:
+                        f.truncate(sizes.get(os.path.splitext(n)[1], 48_000))  # sparse: no real disk use
+
+    def agent(self, command, **args):
+        if command == "storage_targets":
+            return {"targets": [{"id": n.lower(), "path": os.path.join(self.home, n), "android": a, "shared": True}
+                                for n, a in (("Videos", "/sdcard/Movies"), ("Downloads", "/sdcard/Download"),
+                                             ("Documents", "/sdcard/Documents"))]}
+        raise RuntimeError(f"fake Frame: {command} not available")
+
+    @property
+    def sftp(self):
+        import paramiko
+
+        class SFTP:
+            def listdir_attr(self, path):
+                out = []
+                for name in sorted(os.listdir(path)):
+                    a = paramiko.SFTPAttributes.from_stat(os.lstat(os.path.join(path, name)))
+                    a.filename = name
+                    out.append(a)
+                return out
+
+            def stat(self, path):
+                return paramiko.SFTPAttributes.from_stat(os.stat(path))
+        return SFTP()
+
+
+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.frame = FakeFS()
+        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
+
+
+STEP_SECONDS = 4  # per screen (the screenshot is taken ~3 s in)
+
+
 def driver(app: FramePortApp, steps: list[tuple[str, callable]], ready: threading.Event, done_step: list):
    for name, action in steps:
        try:
@@ -33,7 +111,7 @@ def driver(app: FramePortApp, steps: list[tuple[str, callable]], ready: threadin
            ERRORS.append(f"{name}: {traceback.format_exc()}")
        done_step.append(name)
        ready.set()
-        time.sleep(4)
+        time.sleep(STEP_SECONDS)


 def main() -> int:
@@ -42,15 +120,71 @@ def main() -> int:
    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("--hover", default=None, help="x,y: move the mouse there before the Library screenshot")
+    ap.add_argument("--install-questions", nargs="+", metavar="PKG", default=None,
+                    help="open the install questions for these games, then click each dialog's main button twice "
+                         "(a double click must not duplicate dialogs); nothing is installed")
+    ap.add_argument("--docs", action="store_true", help="only the screens used in the docs (Library, --game, Frame)")
    args = ap.parse_args()
+    global STEP_SECONDS
+    if args.hover:
+        STEP_SECONDS = 7
+    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))]
+    steps = [("library", lambda a: a.navigate(0)), ("frame", lambda a: a.navigate(1)),
+             ("files", lambda a: a.go("files")), ("tools", lambda a: a.go("settings"))]
    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.navigate(0), time.sleep(3), a.library_view.open_menu(game))))
+        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)))
+        steps.append(("files", lambda a: a.go("files")))
+        steps.append(("files-select", lambda a: [a.files_view._toggle(e.path, True)
+                                                 for e in a.files_view.entries[1:3]]))
+    if args.install_questions:
+        queued: list[str] = []
+
+        def open_questions(a):
+            a._submit_install = lambda p, to: queued.append(p)
+            a.install_many(args.install_questions, "frame")
+
+        def double_click(a):
+            dialogs = [d for d in a.page._dialogs.controls if d.open]
+            print(f"open dialogs: {len(dialogs)}", flush=True)
+            button = dialogs[-1].actions[-1]
+            button.on_click(None)
+            button.on_click(None)
+
+        def report(a):
+            print(f"open dialogs: {len([d for d in a.page._dialogs.controls if d.open])}, queued: {queued}", flush=True)
+        steps = [("library", lambda a: a.navigate(0)), ("questions", open_questions),
+                 ("after-1st-double", double_click), ("after-2nd-double", double_click), ("end", report)]
+    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.go("settings")))]
    if args.frame:
        from frameport.frame.connection import parse_target

@@ -75,9 +209,16 @@ def main() -> int:
            steps.append(("launch-test-job", job))
    ready, done = threading.Event(), []

+    if args.fake_frame:  # never reach a real Frame (start-up auto-connect, discovery, the 30 s poll)
+        FramePortApp.connect = lambda self, *a, **k: None
+        FramePortApp.refresh_frame = lambda self, *a, **k: None
+
    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
@@ -90,15 +231,20 @@ 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)
                while len(done) < len(steps) and time.time() < deadline:
                    if ready.wait(1):
                        ready.clear()
+                        name = done[-1]
                        time.sleep(3)  # let Flutter paint
-                        page.screenshot(path=str(args.out / f"{shot:02d}-{done[-1]}.png"))
+                        if args.hover and name == "library":
+                            hx, hy = (float(v) for v in args.hover.split(","))
+                            page.mouse.move(hx, hy)
+                            time.sleep(1.5)
+                        page.screenshot(path=str(args.out / f"{shot:02d}-{name}.png"))
                        shot += 1
                browser.close()
        except Exception:  # noqa: BLE001
@@ -0,0 +1,74 @@
+#!/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
+import time
+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 = updates._signer_thumbprint(installed / "FramePort.exe")
+        b = updates._signer_thumbprint(new / "FramePort.exe")
+        print(f"signer thumbprints: installed {a} new {b}")
+        assert a and a == b, "signature check failed"
+    # the same launch as the app (detached; apply() checks the script started), then wait for it to finish
+    script = updates.apply(new, installed, relaunch=False, pid=999999, platform=platform)
+    log_file = home / "data/logs/update.log"
+    for _ in range(240):
+        log = log_file.read_text() if log_file.exists() else ""
+        if "not relaunching" in log:
+            break
+        time.sleep(0.5)
+    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.4.0"
@@ -56,6 +56,34 @@ def _features(manifest: bytes) -> dict[str, bool]:
    return out


+def vr_kind(libs: set[str], manifest_strings: list[str]) -> str:
+    """What kind of Android app this is, for choosing how to port it:
+    quest       Meta Quest app (VrApi / OVRPlugin / Meta's OpenXR loader + Oculus manifest entries): OVRPort
+    openxr      another headset's OpenXR app (Pico, Khronos loader): OVRPort's loader + the Frame adapter
+    android_xr  Android XR (Jetpack XR / spatial) app: needs system services Lepton doesn't have
+    pico_sdk    Pico's pre-OpenXR SDK, wave: HTC Vive Wave SDK: no OpenXR path, can't run
+    none        an ordinary (2D) Android app or game: installed without the VR translation"""
+    text = " ".join(manifest_strings)
+    meta = (libs & {"libvrapi.so", "libOVRPlugin.so", "libovrplatformloader.so"}
+            or "com.oculus." in text or "oculus.software." in text or "horizonos." in text)
+    if meta:
+        return "quest"
+    if any(lib.startswith("libwvr") for lib in libs) or "com.htc.vr" in text:
+        return "wave"
+    if "libopenxr_loader.so" in libs or "org.khronos.openxr" in text:
+        return "openxr"
+    if libs & {"libPvr_UnitySDK.so", "libpxr_api.so", "libPxr_api.so", "libPvrSDK.so"} or "pvr.app.type" in text:
+        return "pico_sdk"
+    if "android.software.xr" in text or "androidx.xr" in text or "com.google.android.xr" in text:
+        return "android_xr"
+    return "none"
+
+
+# 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:
@@ -75,7 +103,8 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
                        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 ""
+        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)
@@ -100,12 +129,16 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana

    uses_glad = 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_refs.append(name)
-        if name not in ("libvrapi.so", "libOVRPlugin.so") and b"GLAD_GL_" in data and "eglGetProcAddress" in elf.dyn_symbols(data, False):
+        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

    msaa_levels = 0
@@ -118,6 +151,7 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
            msaa_levels = 0

    cats = axml.categories(manifest)
+    manifest_strings = axml.Axml(manifest).strings()
    features = _features(manifest)
    used_perms, _ = axml.used_and_declared_permissions(manifest)
    return Analysis(
@@ -143,12 +177,18 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
            "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."))),
+            "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,
+            "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
+            "vr_kind": vr_kind(libset, manifest_strings),
+            # the base of a split APK set (Play "app bundle" installs): the code/libraries live in split APKs
+            "split_apk": bool({"isSplitRequired", "requiredSplitTypes"} & set(manifest_strings)),
        },
    )

@@ -164,12 +204,14 @@ def missing_ovr_symbols(lib_bytes: dict[str, bytes]) -> set[str]:
    if not loader or not elf.is_elf(loader):
        return set()
    exported = set(elf.dyn_symbols(loader, True))
+    linked = set(elf.needed(loader))
    for extra in ("libovrplatformcompat.so", "libovrstubs.so"):
-        if extra in lib_bytes:
+        if extra in lib_bytes and extra in linked:  # only counts when the loader loads it (a lone file doesn't help)
            exported |= elf.dyn_symbols(lib_bytes[extra], True)
    wanted = set()
    for name, data in lib_bytes.items():
-        if name.startswith(("libovrplatformloader", "libopenxr_loader", "libframe_settings", "libfrda")) or not elf.is_elf(data):
+        if (name.startswith(("libovrplatformloader", "libopenxr_loader", "libframe_settings", "libfrda"))
+                or not elf.is_elf(data)):
            continue
        wanted |= {s for s in elf.dyn_symbols(data, False) if s.startswith(("ovr_", "ovrMessageType_"))}
    return wanted - exported
@@ -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).
@@ -200,7 +219,7 @@ def add_needed(data: bytes, library: str) -> bytes:
        table[note_i] = new_load
    # PT_LOAD entries must stay sorted by vaddr (bionic); the new one has the highest vaddr.
    load_slots = [i for i, p in enumerate(table) if p["type"] == PT_LOAD]
-    for i, p in zip(load_slots, sorted((table[i] for i in load_slots), key=lambda p: p["vaddr"])):
+    for i, p in zip(load_slots, sorted((table[i] for i in load_slots), key=lambda p: p["vaddr"]), strict=True):
        table[i] = p

    buf += b"\0" * (file_end - len(buf))
@@ -40,6 +40,10 @@ PLATFORM_DLLS = ("libovrplatform64_1.dll", "libovrplatform32_1.dll")
 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):
@@ -264,18 +268,22 @@ def candidates(tree: Tree) -> list[Path]:


 # ------------------------------------------------------------------------------------------ naming
-_TAG_WORDS = r"(?:ARMGDDN|VRP|JF|FFA|Repacks?|Shipping|GOG|CODEX|PLAZA|FitGirl|DODI|ElAmigos|Oculus|Rift|PCVR)"
+# words that describe a build rather than the game (neutral; release tags are removed by their form, not by name)
+_BUILD_WORDS = r"(?:Shipping|GOG|Oculus|Rift|PCVR|Repacks?|Release)"
+# a release tag at the end: " -TAG", " -TAG v76", " -[TAG Repacks]" (a space before the dash and none after it, so
+# subtitles like " - Episode II" and hyphenated words like "Rick-ality" stay)
+_TRAILING_TAG = r"\s-(?=[\[A-Za-z0-9])(?:\[[^\]]*\]|[A-Za-z0-9]{2,12}\b)(?:\s+v\d+)?.*$"


 def clean_title(name: str) -> str:
-    """'Asgards Wrath v1.6.0 -ARMGDDN' -> 'Asgards Wrath'; 'Arktika 1 (v1.0.0.7) -VRP' -> 'Arktika 1';
+    """'Asgards Wrath v1.6.0 -TAG' -> 'Asgards Wrath'; 'Arktika 1 (v1.0.0.7) -TAG' -> '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(_TRAILING_TAG, " ", name)
+    t = re.sub(r"\[[^\]]*\]", " ", t)  # [TAG Repacks]
+    t = re.sub(r"\((?:[^)]*\d[^)]*|[^)]*\b" + _BUILD_WORDS + r"\b[^)]*)\)", " ", t, flags=re.I)  # (v1.0.0.7)
    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"\b" + _BUILD_WORDS + r"\b", " ", t, flags=re.I)
    t = re.sub(r"[_]+", " ", t)
    t = re.sub(r"\s+", " ", t).strip(" -_.")
    return t or name.strip()
@@ -330,6 +338,13 @@ def rank_exes(folder: Path, cands: list[Path], manifest: dict | None = None,
        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
@@ -346,13 +361,6 @@ 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
@@ -422,8 +430,16 @@ def analyze(folder: Path, exe: str | None = None, tree: Tree | None = None) -> A
                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
+    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)
@@ -440,11 +456,13 @@ def analyze(folder: Path, exe: str | None = None, tree: Tree | None = None) -> A
               # 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.
-               "frame_native": (openxr or openvr) and not libovr,
-               "needs_revive": libovr,
+               # 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,
-               # repacks ship a LibRevive64.dll for their own (Virtual Desktop) setup; nothing loads it on its own, so
-               # this is informational only — the game still needs FramePort's Revive for LibOVR → OpenXR
+               # 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"),
@@ -452,6 +470,48 @@ def analyze(folder: Path, exe: str | None = None, tree: Tree | None = None) -> A
    )


+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"
@@ -1,6 +1,6 @@
 """Generate a tiny Android shared library whose exported functions all `return 0` (no compiler needed).

-Used for Meta platform functions (ovr_*) that overport's platform loader lacks: without them the game fails with
+Used for Meta platform functions (ovr_*) that OVRPort's platform loader lacks: without them the game fails with
 UnsatisfiedLinkError / dlopen errors. The layout follows what bionic requires: section headers present (.dynsym,
 .dynstr, .hash, .text, .dynamic, .shstrtab), PT_LOAD segments 16 KiB aligned, PT_DYNAMIC matching the .dynamic
 section, DT_HASH, DT_SONAME and PT_GNU_STACK non-executable.
@@ -6,8 +6,8 @@ file stays byte-identical, which keeps diffs against known-good builds meaningfu
 from __future__ import annotations

 import struct
+from collections.abc import Iterator
 from dataclasses import dataclass
-from typing import Iterator

 RES_XML = 0x0003
 RES_STRING_POOL = 0x0001
@@ -252,7 +252,8 @@ def define_meta_permissions(manifest: bytes) -> tuple[bytes, list[str]] | None:
        start = struct.pack("<HHIII", RES_XML_START_ELEMENT, 16, 56, 0, 0xFFFFFFFF)
        start += struct.pack("<IIHHHHHH", 0xFFFFFFFF, perm_el, 20, 20, 1, 0, 0, 0)
        start += struct.pack("<IIIHBBI", android_ns, name_attr, value, 8, 0, TYPE_STRING, value)
-        end = struct.pack("<HHIII", RES_XML_END_ELEMENT, 16, 24, 0, 0xFFFFFFFF) + struct.pack("<II", 0xFFFFFFFF, perm_el)
+        end = (struct.pack("<HHIII", RES_XML_END_ELEMENT, 16, 24, 0, 0xFFFFFFFF)
+               + struct.pack("<II", 0xFFFFFFFF, perm_el))
        chunks += start + end
    manifest_el = next(el for el in x.elements() if el.name == "manifest")
    insert_at = manifest_el.offset + manifest_el.size
@@ -1,6 +1,6 @@
 """Signing (apksigner via the managed JRE) and alignment checks.

-overport creates one keystore per package (password "password", alias "key"). The same key must sign every later
+OVRPort creates one keystore per package (password "password", alias "key"). The same key must sign every later
 build of that package, or Android refuses the update and saves are lost on reinstall.
 """
 from __future__ import annotations
@@ -24,11 +24,30 @@ def _apksigner() -> str:
    return str(jar)


+def ensure_keystore(package: str) -> Path:
+    """The package's signing key. OVRPort creates it on its first patch; apps built without OVRPort (ordinary
+    Android apps) get one made here with the same layout (password "password", alias "key")."""
+    ks = overport_tool.keystore(package)
+    if ks.exists():
+        return ks
+    java = toolchain.java_path()
+    keytool = java.with_name("keytool.exe" if java and java.name.endswith(".exe") else "keytool") if java else None
+    if not keytool or not keytool.exists():
+        raise RuntimeError(f"no signing key for {package} and no keytool to create one (run `frameport tools install`)")
+    import subprocess
+
+    p = subprocess.run([str(keytool), "-genkeypair", "-keystore", str(ks), "-storetype", "JKS", "-storepass", KS_PASS,
+                        "-keypass", KS_PASS, "-alias", KS_ALIAS, "-keyalg", "RSA", "-keysize", "2048",
+                        "-validity", "10000", "-dname", f"CN={package}, O=FramePort"],
+                       capture_output=True, text=True, timeout=120)
+    if p.returncode or not ks.exists():
+        raise RuntimeError("couldn't create a signing key: " + (p.stdout + p.stderr)[-500:])
+    return ks
+
+
 def sign(unsigned: Path, final: Path, package: str) -> None:
    """Align (4 bytes; .so to 16 KiB pages) and sign v1+v2+v3. apksigner performs the alignment itself."""
-    ks = overport_tool.keystore(package)
-    if not ks.exists():
-        raise RuntimeError(f"no signing key for {package} at {ks} (overport creates it on first patch)")
+    ks = ensure_keystore(package)
    final.unlink(missing_ok=True)
    p = toolchain.run_java([
        "-jar", _apksigner(), "sign", "--ks", str(ks), "--ks-pass", f"pass:{KS_PASS}", "--ks-key-alias", KS_ALIAS,
@@ -55,7 +74,8 @@ def cert_digest(apk: Path) -> str | None:


 def alignment_problems(apk: Path) -> list[str]:
-    """Stored entries must be 4-byte aligned; stored .so files page (16 KiB) aligned (what zipalign -c -P 16 4 checks)."""
+    """Stored entries must be 4-byte aligned; stored .so files page (16 KiB) aligned (what zipalign -c -P 16 4
+    checks)."""
    bad = []
    with open(apk, "rb") as f, zipfile.ZipFile(apk) as z:
        for info in z.infolist():
@@ -18,7 +18,8 @@ class ApkWorkspace:
        self.add: dict[str, bytes] = {}
        self.rename: dict[str, str] = {}  # old name -> new name (content unchanged unless replaced)
        self.remove: set[str] = set()
-        abi = next((a for a in ("arm64-v8a", "armeabi-v7a") if any(n.startswith(f"lib/{a}/") for n in self.infos)), None)
+        abi = next((a for a in ("arm64-v8a", "armeabi-v7a")
+                    if any(n.startswith(f"lib/{a}/") for n in self.infos)), None)
        self.abi = abi
        self.libdir = f"lib/{abi}/" if abi else ""

@@ -89,7 +90,8 @@ class ApkWorkspace:
                if name in self.replace:
                    dst.writestr(zi, self.replace[name])
                else:
-                    with self._zip.open(info) as fin, dst.open(zi, "w", force_zip64=info.file_size > 0x7FFFFFFF) as fout:
+                    with (self._zip.open(info) as fin,
+                          dst.open(zi, "w", force_zip64=info.file_size > 0x7FFFFFFF) as fout):
                        shutil.copyfileobj(fin, fout, 1 << 22)
            for name, data in self.add.items():
                zi = zipfile.ZipInfo(name, date_time=(2020, 1, 1, 0, 0, 0))
@@ -61,6 +61,8 @@ 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()}
+    if ((entry.get("analysis") or {}).get("extra") or {}).get("vr_kind") == "none":
+        return out  # an Android app without VR isn't on a VR store; a title match would be another product
    try:
        app = oculusdb_app(entry)
    except Exception:  # noqa: BLE001 - offline
@@ -125,6 +127,17 @@ 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"):
@@ -1,6 +1,6 @@
 """Store artwork for the Steam library (portrait/landscape/hero/logo/icon).

-Fetched live from overport's image service (Meta store art by package name), cached per package. Falls back to
+Fetched live from OVRPort's image service (Meta store art by package name), cached per package. Falls back to
 the APK's launcher icon when the store has nothing (e.g. sideload-only titles).
 """
 from __future__ import annotations
@@ -20,7 +20,9 @@ KINDS = {
    "APP_IMG_LOGO_TRANSPARENT": "logo",
    "APP_IMG_ICON": "icon",
 }
-EXTRA_KINDS = ("square",)  # OculusDB's square cover (Rift games)
+# OculusDB's square cover (Rift games); FramePort's own cover/banner (no store art)
+EXTRA_KINDS = ("square", "cover", "banner")
+PICKED = ".picked"  # marker: the art in this folder was chosen by the user (Find artwork); automatic fetches skip it


 def artwork_dir(package: str) -> Path:
@@ -36,12 +38,18 @@ def _ext(data: bytes) -> str:
 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."""
+    to use (a Rift game borrows its Quest version's art); Rift ids without one have no store art.
+    Without `refresh` it only fills in missing kinds and never touches art the user picked (PICKED marker): a pick
+    often lacks a kind (Steam has no icon, OculusDB only a square cover), and re-fetching the store art for that
+    replaced the pick at the next install."""
    out = artwork_dir(package)
+    if refresh:
+        (out / PICKED).unlink(missing_ok=True)
    have = {p.stem for p in out.iterdir()}
    title = None
    lookup = lookup or (None if package.startswith("rift.") else package)
-    if lookup and (refresh or not {"portrait", "landscape", "hero", "icon"} <= have):
+    picked = (out / PICKED).exists()
+    if lookup and not picked and (refresh or not {"portrait", "landscape", "hero", "icon"} <= have):
        try:
            data = cache.http_get(API.format(package=lookup), timeout=30).json()
        except Exception:
@@ -52,6 +60,8 @@ def fetch(package: str, apk: Path | None = None, refresh: bool = False,
                kind = KINDS.get(img.get("image_type"))
                if not kind:
                    continue
+                if not refresh and kind in have:
+                    continue  # keep what's there; only fill gaps
                raw = base64.b64decode(img["uri"])
                for old in out.glob(f"{kind}.*"):
                    old.unlink()
@@ -67,21 +77,43 @@ def fetch(package: str, apk: Path | None = None, refresh: bool = False,
    return out, title


-def apk_icon(apk: Path) -> bytes | None:
-    """Largest PNG launcher icon inside the APK (mipmap/drawable)."""
+def apk_icon(apk: Path | str | None) -> bytes | None:
+    """The app's launcher icon from the APK as PNG bytes: the icon the manifest names (pyaxmlparser), else the
+    largest ic_launcher bitmap. None for vector/adaptive-only icons (no bitmap to use)."""
+    if not apk or not Path(apk).is_file():
+        return None
+    import io
+
+    from PIL import Image
+
+    dens = ("xxxhdpi", "xxhdpi", "xhdpi", "hdpi", "mdpi")
    try:
        with zipfile.ZipFile(apk) as z:
-            cands = [i for i in z.infolist() if i.filename.startswith("res/") and "ic_launcher" in i.filename
-                     and i.filename.endswith((".png", ".webp"))]
-            if not cands:
-                cands = [i for i in z.infolist() if i.filename.startswith("res/mipmap") and i.filename.endswith(".png")]
-            if not cands:
-                return None
-            best = max(cands, key=lambda i: i.file_size)
-            data = z.read(best)
-            return data if data[:4] == b"\x89PNG" else None
-    except (zipfile.BadZipFile, OSError):
+            listed = set(z.namelist())
+            names = []
+            try:
+                from pyaxmlparser import APK
+
+                named = APK(str(apk)).get_app_icon()
+                if named:
+                    names.append(named)
+            except Exception:  # noqa: BLE001 - unreadable resources: fall back to the usual file names
+                pass
+            names += sorted((n for n in listed if n.startswith("res/") and "ic_launcher" in n
+                             and n.endswith((".png", ".webp")) and "foreground" not in n and "background" not in n),
+                            key=lambda n: next((i for i, d in enumerate(dens) if d in n), len(dens)))
+            for n in names:
+                if n not in listed or not n.endswith((".png", ".webp")):
+                    continue
+                with Image.open(io.BytesIO(z.read(n))) as im:
+                    if im.width < 48:
+                        continue
+                    out = io.BytesIO()
+                    im.convert("RGBA").save(out, "PNG")
+                    return out.getvalue()
+    except (zipfile.BadZipFile, OSError, ValueError):
        return None
+    return None


 def files(package: str) -> list[Path]:
@@ -139,10 +139,18 @@ def has_art(package: str) -> bool:


 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)."""
+               exe: Path | None = None, oculus: bool = True) -> dict:
+    """Find and store artwork for a PC VR game. Returns what was found: {source, quest_package, oculus_app_id,
+    canonical_name, steam_appid} (only the keys that apply). oculus=False (no Oculus code: a SteamVR/OpenXR game):
+    Steam is asked first, the Oculus store only if Steam has nothing."""
    found: dict = {}
+    if not oculus:
+        try:
+            st = match_steam(title)
+        except Exception:  # noqa: BLE001 - offline
+            st = None
+        if st and apply_steam(package, st["id"]):
+            return {"steam_appid": st["id"], "source": "steam"}
    app = None
    try:
        app = match_rift(title, canonical)
@@ -219,9 +227,15 @@ def apply_choice(package: str, choice: dict) -> bool:
        if choice["source"] == "Steam":
            apply_steam(tmp, choice["id"])
        elif choice.get("package"):
+            # the picture the picker showed (OculusDB) is the cover; the store service by package adds the logo
+            # and icon. Its covers can differ from the picked picture (e.g. a "dogfooding" placeholder), so they're
+            # dropped when the picked picture arrived: the Steam shapes are composed from it instead.
+            picked = apply_oculusdb(tmp, choice["app"]) if choice.get("app") else False
            fetch.fetch(tmp, lookup=choice["package"], refresh=True)
-            if not has_art(tmp):
-                apply_oculusdb(tmp, choice["app"])
+            if picked:
+                for f in stage.iterdir():
+                    if f.stem in ("portrait", "landscape", "hero"):
+                        f.unlink()
        else:
            apply_oculusdb(tmp, choice["app"])
        if not has_art(tmp):
@@ -233,6 +247,7 @@ def apply_choice(package: str, choice: dict) -> bool:
        for f in stage.iterdir():
            if f.is_file() and f.stem in ART_STEMS:
                f.replace(d / f.name)
+        (d / fetch.PICKED).write_text(choice.get("source", ""), encoding="utf-8")  # keep it through installs
        return True
    finally:
        shutil.rmtree(stage, ignore_errors=True)