FramePort 0.6.0: Type on Frame screenshot in the README; sidebar keyboard icon compact next to the Frame name; docs: the shown app window is listed as Gamescope

Setup without root or password: bootstrap.sh turns Developer Mode on itself (Valve's steamos-devkit-mode helper,
config.vdf set with Steam stopped) and finishes as a user unit, since Desktop Mode is a nested Plasma inside
steam.service (stopping Steam ends it; systemd-run needs the real user bus). Shorter setup command
(curl -fsS <ip>:8765/<code> | bash). Valve's devkit pairing (POST :32000/register, ssh-rsa key, Settings → Developer
→ Pair new host) as a fallback that needs no connection into the PC. Firewall handling: temporary Hyper-V rule on WSL
(one UAC prompt, removed after setup), per-OS hints when nothing reaches the setup server. Flet updates serialized
(a dialog shown during a scan redraw never closed). Setup command survives page redraws. Uninstall: removes Lepton's
overlayfs work dirs (mode 000) and stale shortcuts (agent v31). Tests no longer touch the real data folder. README:
highlights, what the setup changes on the Frame, network and firewalls.

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -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

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

.github/ISSUE_TEMPLATE/working-config.yml

@@ -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

.github/workflows/build.yml

@@ -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**)."
+            echo; cat packaging/release-footer.md; } > "$notes"  # short: the update dialog shows these notes
           gh release delete "$tag" --yes 2>/dev/null || true
           gh release create "$tag" out/* packaging/FramePort-selfsigned.cer --title "FramePort ${tag}" --notes-file "$notes"

.github/workflows/catalog-from-issue.yml

@@ -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 }}."

.gitignore

@@ -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/

CLAUDE.md

@@ -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.
@@ -146,7 +225,28 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
 - **Tracking only works with the headset worn.** SSH/headless launches never reach VISIBLE/FOCUSED and poses have
   flags 0x3. So automated tests prove startup (process alive, instance/session created, frames paced), never visuals.
 
+**Setup / pairing (2026-10-02, verified on the device):** Developer Mode = `"DevModeEnabled"` in
+`~/.local/share/Steam/config/config.vdf` (InstallConfigStore/developer), applied by Valve's
+`/usr/bin/steamos-polkit-helpers/steamos-devkit-mode --enable|--disable` (polkit allow_any: no password; enables/
+disables sshd, xrdp, steamos-devkit-service, debug port forwards; sentinel `/etc/steamos-devkit-enabled`). Steam
+re-asserts the config value at every start and rewrites config.vdf on exit → stop Steam, edit, helper, start.
+**Desktop Mode is a nested Plasma inside steam.service** (own XDG_RUNTIME_DIR `/run/user/1000/nested_plasma` + private
+D-Bus): `systemd-run --user` from Konsole fails ("Failed to connect to user scope bus") unless XDG_RUNTIME_DIR/
+DBUS_SESSION_BUS_ADDRESS point at `/run/user/$UID`, and stopping Steam ends the desktop and everything started in
+it → bootstrap.sh runs the Dev Mode job + Lepton request + `/paired` as a user unit (log `~/.cache/frameport-setup.log`);
+no sudo/password anywhere (verified: naive Frame → connected, password never set). Valve's devkit pairing (fallback,
+PC → Frame only): `POST :32000/register` with an **ssh-rsa** key (`connection.devkit_key`, `frame/devkit.py`) works only
+while Steam is in pairing mode (Settings → Developer → Pair new host), else 403 at once; approve hook waits 30 s.
+The Frame runs firewalld (22 and 32000 open). PC side: the setup server needs inbound TCP 8765–8767 — WSL's Hyper-V
+firewall blocks it silently (`DefaultInboundAction Block`): `pairing.ensure_reachable` adds a temporary rule via one
+UAC prompt, removed when the server stops (flag file in %TEMP%, max 35 min); hints per OS after 45 s without a request
+(`pairing.firewall_hint`). Flet 1.0 patches aren't thread-safe → `app.serialize_flet_updates()` (a dialog shown while a
+scan redraw ran never closed: "dropped a patch for unknown control").
 **Lepton:** needs an activity with category **LAUNCHER** (Quest apps often only have INFO → "APP_ACTIVITY is empty").
+**2D apps:** Lepton runs every app headless (`lepton.headless=true`, only OpenXR output reaches the headset) unless the app folder (`<base>/lepton-app/`) has a `lepton-show-flatscreen` file (liblepton/app_metadata.sh) → Waydroid window on gamescope; agent v28 `set_flatscreen` at finalize for `vr_kind == "none"`. Android 11's navbar covered the
+app's controls → patch `device.hide_navbar` (default on for vr_kind none, migration `flat_hide_navbar`) exports
+`qemu.hw.mainkeys=1` as a second line of `LEPTON_GFXRECON_FP_PROPS` (runtime alternatives failed, see
+docs/FRAME_RUNTIME.md). Verified in the headset 2026-10-02 (2048).
 Lepton = Steam app 3029110 (+ "Lepton Development" 3056000, needs Developer Mode). Per-game env: STEAM_COMPAT_INSTALL_PATH
 /DATA_PATH/SHADER_PATH, SteamAppId. Logs: `<base>/launch.log` and `~/.local/share/Steam/logs/lepton-logcats/steamlaunch-<appid>`.
 Containers are podman `lepton-steamlaunch-<appid>`. Some Unreal games create save dirs without u+rwx → launcher repairs every 2 s.
@@ -218,6 +318,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 +346,117 @@ 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.
+
+**Companion apps / intents (2026-10-03, tested with Stremio + 4XVR):** a second APK can be installed into a running
+Lepton container (`podman exec -i lepton-steamlaunch-<appid> pm install -g -S <size> < apk`) and runs there, VR
+included (4XVR in Stremio's flatscreen container: FrameBridge 72 fps, settings via LEPTON_ENV_FRAMEBRIDGE_CONFIG). But
+Lepton's services.jar (`ActivityStarter.execute`) intercepts **every** `android.intent.action.VIEW` with data (any
+scheme, explicit component or not, no property to disable): it writes `steam://openurl/<uri>` to `/lepton/steam.pipe`
+(= the host Steam client's `~/.steam/steam.pipe`) and starts nothing. So "open in external player" hand-offs (Stremio
+→ 4XVR) can't work inside Lepton; don't retry without Valve changing it. Lepton installs exactly one `*.apk` per app
+folder (two break `get_apk_path`).
+**Text input (2026-10-03, verified in the headset with Stremio VR):** Lepton's Android has no IME (`ime list` empty)
+and runs VR apps headless (`lepton.headless=true`): no Android window has input focus (`dumpsys input` FocusedWindows
+empty), so neither `input text`, a USB keyboard nor Steam's keyboard reach the app. `lepton-show-flatscreen` on a VR
+app keeps VR working (FrameBridge 72 fps) and gives the window focus; Steam's on-screen keyboard then opens for text
+fields. Unity's TMP_InputField on non-Quest Android waits for the system keyboard (`TouchScreenKeyboardShouldBeUsed`)
+and deselects a frame later unless `isKeyboardUsingEvents` (Android: `InPlaceEditing() && m_HideSoftKeyboard`);
+uGUI InputField's LateUpdate keeps the field when `InPlaceEditing()`. Patch `frame.unity_text_input` rewrites them
+(`mov w0,#0|#1; ret`) at Cpp2IL's **Offset** (= file offset; RVA differs by 0x4000 in Stremio's lib), Cpp2IL
+2022.1 pre-release (Unity 6 / metadata v31; Il2CppDumper can't), cached per libil2cpp sha. `/dev/uinput` has an ACL
+for steamos (Steam Input) → agent v33 `_keyboard` uinput keyboard ("Type on Frame") reaches everything with focus.
+Installing a second APK into a container with `pm install` re-runs Lepton's post-install hook on the **main** app
+(`lepton.active_app_id`; moves its files to /data/steam_app) and corrupts it on the next start (fix: touch the APK →
+re-bake); `cmd_real package install` skips the hook.
+**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 + the short `packaging/release-footer.md`; owner: keep release
+notes short — a few "What's new" bullets, nothing long after them).
+Installed apps find the release themselves (self-update), so the notes are what users see in the update dialog.
+- **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 +479,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),

CODE_OF_CONDUCT.md

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

CONTRIBUTING.md

@@ -0,0 +1,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.

README.md

@@ -1,36 +1,103 @@
 # 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:
+[![Release](https://img.shields.io/github/v/release/spoopyghosty0/frameport)](https://github.com/spoopyghosty0/frameport/releases/latest)
+[![Build](https://img.shields.io/github/actions/workflow/status/spoopyghosty0/frameport/build.yml?branch=main)](https://github.com/spoopyghosty0/frameport/actions/workflows/build.yml)
+[![Downloads](https://img.shields.io/github/downloads/spoopyghosty0/frameport/total)](https://github.com/spoopyghosty0/frameport/releases)
+[![License](https://img.shields.io/github/license/spoopyghosty0/frameport)](LICENSE)
+![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-blue)
+![Steam Frame](https://img.shields.io/badge/Steam%20Frame-supported-1b2838?logo=steam&logoColor=white)
 
-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.
+Install games that target the Meta Quest, Android, or general PCVR onto your **Valve Steam Frame**. FramePort handles everything from uploading game files, setting up your Frame, injecting compatibility patches, and adding shortcuts to your Steam library. FramePort aims to be as simple as possible by taking advantage of the fact that the Steam Frame runs on Linux.
 
-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.
+![Library](docs/images/library.png)
 
-## 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`).
+> **Notice:** FramePort explicitly does NOT download, share, or unlock games. You must provide legally obtained game
+> executables. Core features of FramePort simply download and wrap other published tools (see [Built on](#built-on))
+> with patches provided by FramePort adding a hardware compatibility layer. This enables users to use games/apps legally
+> purchased on sites like [SideQuest](https://sidequestvr.com/). 
 
-## 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).
+## Features
 
-## 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.
+- **Painless setup:** one short command on the Frame. No root, no `sudo`, no password.
+  [What it changes](docs/FRAME_SETUP.md).
+- **Type on Frame:** use your computer's keyboard on the Frame: in VR apps, Android apps, Steam and the desktop.
+  [More](#type-on-frame).
+- **One click per game:** convert, patch, sign, upload, add to Steam with artwork, launch test.
+- **Per-game recipes:** a tested catalog plus detection rules; every patch explained in plain words.
+- **FrameBridge:** FramePort's OpenXR adapter emulates what the Frame natively lacks (passthrough, room, controller models,
+  curved and 360° layers); game settings as simple switches.
+- **Beyond Quest:** Android apps as windows, PC VR via Proton or Revive, a Files tab with drag and drop.
+- **Self-updating** releases, redacted diagnostics, one-click problem reports and working-config sharing.
+
+## Quick start
+
+1. [Download](https://github.com/spoopyghosty0/frameport/releases/latest) and unzip the build for Windows, macOS
+   (Apple Silicon) or Linux, then start FramePort.
+2. **Connect the Frame** (once):
+   1. In FramePort click **Steam Frame → Show setup command**. Keep FramePort open; the Frame and your computer must
+      be on the same Wi-Fi.
+   2. On the Frame press the **Steam button → Power → Switch to Desktop**.
+   3. Open the app menu (bottom-left corner), search for **Konsole** and open it.
+   4. Type the command FramePort shows exactly as shown (on-screen keyboard or any USB/Bluetooth keyboard) and press
+      **Enter**. This will run the following [bash setup script](bootstrap/bootstrap.sh).
+   5. After a few seconds the desktop closes by itself and the Frame returns to its normal view; that's expected. If
+      Steam asks to install **Lepton**, confirm it. FramePort shows the Frame as connected within a minute. No
+      password needed.
+3. **Add games → Scan a folder** with your game backups (APK + OBB, or PC VR game folders).
+4. Open a game → **Install on Frame**, then play it from the Frame's Steam library.
+
+Full guide, firewalls and troubleshooting: [docs/INSTALL.md](docs/INSTALL.md).
+
+## Type on Frame
+
+Typing in VR is painful, so FramePort turns your computer's keyboard into a keyboard for the Frame. Open **Type on
+Frame** (keyboard icon on the sidebar's Frame card, the Steam Frame page, or a game's menu), select a text field in
+the headset and type: searches, logins, chat, in any app, in Steam or on the desktop. Paste longer text to type it in
+one go. Nothing to install: FramePort adds a virtual keyboard on the Frame while the window is open, without root.
+
+![Type on Frame](docs/images/type-on-frame.png)
+
+Unity apps whose text fields close the moment you select them on the Frame (no system keyboard there) get a per-game
+fix, so Steam's on-screen keyboard and Type on Frame work in them too.
+[Details](docs/INSTALL.md#typing-on-the-frame).
+
+## Compatibility
+
+If a game has already been tested with FramePort, it will automatically use the optimal game config. Otherwise, FramePort
+will attempt to guess key patches. If you find a new config that works for an app you are testing, please consider submitting it to the community!
+
+## Built on
+
+[OVRPort](https://github.com/Android-XR-Bridge/OVRPort) (Quest → OpenXR, originally
+[ovrport/app](https://github.com/ovrport/app)) · Valve Lepton, Proton and SteamVR ·
+[Revive](https://github.com/LibreVR/Revive) · Mesa (Zink) · [Khronos OpenXR SDK](https://github.com/KhronosGroup/OpenXR-SDK)
+· Eclipse Temurin, Android apksigner and NDK · [Flet](https://flet.dev) · OculusDB and Steam store data.
+What FramePort adds itself: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Documentation
+
+| | |
+|---|---|
+| [INSTALL.md](docs/INSTALL.md) | Install, connect, update, PC VR, files, problem reports |
+| [FRAME_SETUP.md](docs/FRAME_SETUP.md) | What setup changes on the Frame, networks and firewalls, undoing it |
+| [COMPATIBILITY.md](docs/COMPATIBILITY.md) | What runs and how well |
+| [PLAYBOOK.md](docs/PLAYBOOK.md) | Symptoms and fixes per game |
+| [FRAME_RUNTIME.md](docs/FRAME_RUNTIME.md) | Steam Frame runtime facts |
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | How the code is organised |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Code, recipes, translations |
 
 ## Development
-See `CLAUDE.md` (architecture, commands, findings) and `docs/ARCHITECTURE.md`.
+
+```
+uv sync --extra dev
+uv run frameport-gui        # the app
+uv run frameport --help     # command line
+uv run pytest               # tests
+```
+
+## AI Usage Notice
+While I would like to program everything manually, I no longer have much free time for personal projects. As a result I make use of AI tools to make it significantly quicker to debug compatibility issues.
+
+## License
+
+GPL-3.0-only (includes GPL-3.0 code from OVRPort). Not affiliated with Valve or Meta.

SECURITY.md

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

THIRD_PARTY_NOTICES.md

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

artifacts/SHA256SUMS

@@ -1,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

bootstrap/bootstrap.sh

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

catalog/games/cn.vr4p.oculus4xvrplayerov.yaml

@@ -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

catalog/games/com.Armature.SportsScramble.yaml

@@ -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

catalog/games/com.Astrea.Gundam.yaml

@@ -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

catalog/games/com.BithellGames.Arcsmith.yaml

@@ -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

catalog/games/com.BolverkGames.GenotypeGame.yaml

@@ -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

catalog/games/com.DigitalLode.Espire1.yaml

@@ -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

catalog/games/com.DigitalLode.Espire2.yaml

@@ -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

catalog/games/com.FuturLab.PowerWashSimulator.yaml

@@ -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

catalog/games/com.JustAddWater.SniperEliteVR.yaml

@@ -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

catalog/games/com.JustAddWater.SniperEliteVR_EN.yaml

@@ -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

catalog/games/com.Novelab.Demeter.yaml

@@ -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

catalog/games/com.Sanzaru.Wrath2.yaml

@@ -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

catalog/games/com.Solfar.InDeath.yaml

@@ -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

catalog/games/com.TeamPanoptes.SilhouetteVR.yaml

@@ -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

catalog/games/com.Ubisoft.ACNexusVR.yaml

@@ -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)'

catalog/games/com.VRFactory.VRBartender.yaml

@@ -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

catalog/games/com.ViteiBackroom.Powder.yaml

@@ -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

catalog/games/com.YourCompany.RoboRecall.yaml

@@ -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

catalog/games/com.camouflaj.manta.yaml

@@ -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

catalog/games/com.coatsink.nexus.yaml

@@ -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

catalog/games/com.com.spectralgames.Medieval.yaml

@@ -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

catalog/games/com.crytek.climb2.yaml

@@ -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

catalog/games/com.forcefieldxr.timestall.yaml

@@ -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

catalog/games/com.gritGames.Nope.yaml

@@ -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

catalog/games/com.iillusions.bamgame.yaml

@@ -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

catalog/games/com.nDreams.PhantomQuest.yaml

@@ -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

catalog/games/com.nexxr.nexplayer.yaml

@@ -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

catalog/games/com.noghost.thegrandgetaway.yaml

@@ -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

catalog/games/com.sigtrapgames.undercover.yaml

@@ -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

catalog/games/com.stremio.vrone.yaml

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

catalog/games/com.thunderful.legobricktales.yaml

@@ -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

catalog/games/com.twistedpixelgames.PILO.yaml

@@ -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

catalog/games/com.twistedpixelgames.POTW_App.yaml

@@ -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

catalog/games/com.xrgames.hitman3reloaded.yaml

@@ -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

catalog/games/gg.trs.grappa.yaml

@@ -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

catalog/games/rift.rick_and_morty_virtual_rick_ality.yaml

@@ -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

catalog/games/studio.NewFolderGames.ToyMaster.yaml

@@ -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

catalog/games/us.lighthaus.nanocellx.yaml

@@ -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

catalog/games/xyz.muware.hunt.vr.yaml

@@ -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

catalog/triage.yaml

@@ -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)'

docs/ARCHITECTURE.md

@@ -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,49 @@ 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).
+
+## Built on
+
+FramePort is a front end for other projects; most of the functionality comes from them:
+
+| Project | Used for |
+|---|---|
+| [OVRPort](https://github.com/Android-XR-Bridge/OVRPort) (overport, originally [ovrport/app](https://github.com/ovrport/app)) | Converts Quest games to OpenXR: its CLI applies the game patches and supplies the OpenXR loader; FramePort also includes its VrApi→OpenXR adapter |
+| Valve Lepton, Proton and SteamVR | Run Android games, Windows games and OpenXR on the Frame |
+| [Revive](https://github.com/LibreVR/Revive) (LibreVR) | Runs Oculus Rift games on OpenXR / SteamVR |
+| Mesa (Zink) | OpenGL ES on Vulkan on the Frame |
+| [Khronos OpenXR SDK](https://github.com/KhronosGroup/OpenXR-SDK) | OpenXR headers for the native layers |
+| Eclipse Temurin, Android apksigner, Android NDK | Java runtime, APK signing, building the native layers |
+| [Flet](https://flet.dev) | The desktop app |
+| OculusDB, Steam store | Game descriptions, genres and artwork |
+
+FramePort's own parts: game detection and recipes, the Steam Frame OpenXR adapter (FrameBridge) and the other native
+fixes in `native/`, the installer agent that runs on the Frame, and the desktop/command-line app.

docs/COMPATIBILITY.md

@@ -0,0 +1,29 @@
+# Compatibility
+
+The built-in catalog has tested settings for 39 games (27 work, 6 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](images/patches.png)
+
+| Kind of app | On the Steam Frame |
+|---|---|
+| Meta Quest games (APK) | Translated to OpenXR (OVRPort) and patched for the Frame; run in Valve's Android runtime (Lepton) |
+| Other Android VR apps using OpenXR (e.g. Pico builds) | Translated the same way; the other headset's own extensions and store services aren't available |
+| Ordinary Android apps and games (no VR) | Installed unchanged and shown as a flat window in the headset |
+| PC VR games (Windows; OpenXR, SteamVR or Oculus) | Run through Proton on the Frame (experimental), or on a Windows PC with SteamVR and streamed to the Frame; Oculus-only games use Revive |
+| Can't run | 32-bit-only or x86-only APKs, Pico/HTC Wave SDK apps, Android XR apps, and games that check an Oculus licence (they need the Oculus app on a PC) |
+
+Automated launch tests confirm that a game starts; visuals can only be checked in the headset.
+
+![Steam Frame](images/frame.png)
+
+The **Files** tab manages files on the Frame: upload videos, documents, mods or saves from the computer (buttons or
+drag-and-drop), download, rename and delete (one entry or a selection), in the shared folders every game sees or in
+one game's own storage.
+
+![Files](images/files.png)

docs/DIAGNOSTICS.md

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

docs/FRAME_RUNTIME.md

@@ -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).
@@ -84,3 +105,14 @@
 - Processes started from Steam (Konsole, SSH sessions?) share steam.service's cgroup: use `systemd-run --user`.
 - SSH: `sshd` must be enabled (`sudo systemctl enable --now sshd`), which needs a user password (`passwd`).
 - mDNS: avahi-daemon runs by default; hostname `frame` → `frame.local`.
+
+## Text input
+
+- Lepton's Android has no on-screen keyboard (IME) and VR apps run headless, so no Android window has keyboard focus
+  and key presses (Steam's keyboard, USB/Bluetooth keyboards, `input text`) don't reach VR apps. The app folder's
+  `lepton-show-flatscreen` marker shows the window (VR keeps working) and gives it focus; Steam's on-screen keyboard
+  then opens for its text fields (FramePort patch `device.text_input_window`).
+- `/dev/uinput` is writable by the steamos user (ACL for Steam Input): a uinput virtual keyboard works like a real
+  one everywhere (FramePort's "Type on Frame", agent `_keyboard`).
+- Unity text fields close without a system keyboard; see `frame.unity_text_input` in PLAYBOOK.md.
+

docs/FRAME_SETUP.md

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

docs/INSTALL.md

@@ -1,59 +1,178 @@
 # 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
+
+The Frame and the computer must be on the same network.
+
+1. In FramePort open **Steam Frame** and click **Show setup command**.
+2. First time only, on the Frame:
+   1. Press the **Steam button → Power → Switch to Desktop**.
+   2. Open the app menu (bottom-left corner), search for **Konsole** and open it.
+   3. Type the command FramePort shows exactly as shown (on-screen keyboard or any USB/Bluetooth keyboard) and press
+      **Enter**. It looks like `curl -fsS 192.168.1.20:8765/1a2b3c4d | bash`: your computer's address, then a
+      one-time code.
+   4. After a few seconds the desktop closes by itself and the Frame returns to its normal view; that's expected. If
+      Steam asks to install **Lepton** (Valve's Android runtime), confirm it.
+
+   FramePort connects by itself within a minute. No password is needed. The command lets FramePort in and turns on
+   **Developer Mode** (which includes SSH); everything it changes is listed in [FRAME_SETUP.md](FRAME_SETUP.md).
+3. Later starts: a Frame in Developer Mode appears in the list and FramePort connects to it automatically. (If you
+   turn Developer Mode off in Settings → System → Developer, turn it on again there.)
+
+**Without Konsole:** turn on Developer Mode yourself (Settings → System → Developer). The Frame then appears under
+**On your network**. On the Frame open Settings → Developer → **Pair new host**, then click **Connect** in FramePort
+and approve it on the Frame (Valve's own devkit pairing; it only sends this computer's key to the Frame). Install
+Lepton from the Steam Frame page afterwards if it's missing.
+
+### Firewalls
+
+If the setup command only says "timed out", a firewall on your computer blocks the Frame; the setup page
+says which after about 45 seconds. Details per system: [FRAME_SETUP.md](FRAME_SETUP.md#network-and-firewalls).
+
+## 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**).
+
+![Game page](images/game.png)
+
+Each game has **Game settings** in plain words (sharpness, refresh rate, controllers, menus, 360° video, mixed
+reality), showing only what matters for that game. Changes are kept with the game and reach the Frame right away.
+
+![Game settings](images/game-settings.png)
+
+## Typing on the Frame
+
+- **Type on Frame** (Steam Frame page, a game's menu, or the keyboard icon on the sidebar's Frame card): while the
+  window is open, this computer's keyboard works as a keyboard plugged into the Frame. Select a text field in the
+  headset (in an app, Steam or the desktop) and type; Esc and shortcuts go to the Frame too. Paste longer text into
+  the box to type it in one go (US keyboard layout). Click **Done** to disconnect.
+- **Steam's on-screen keyboard** opens for text fields of apps shown as a window (2D apps, and VR apps with
+  **Show the app's Android window**). Steam lists that window as **Gamescope** (the Frame's display compositor);
+  leave it open: it's what receives the typing, the VR view isn't affected.
+- **Unity apps whose text fields close at once** (a caret flashes, nothing can be typed): FramePort suggests
+  **Make Unity text fields work** for them. The first time, it downloads Cpp2IL (a tool that finds the right spot in the
+  game's code, ~17 MB). Games added before this version: open the game's menu → **Analyze again**, then reinstall.
+
+## 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`.

docs/PLAYBOOK.md

@@ -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
@@ -14,11 +14,13 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Symptom | Cause | Fix |
 |---|---|---|
 | Every game suddenly fails to start: `crun: create keyring …: Disk quota exceeded`, `is not a running context` | rootless podman leaked a kernel keyring per launch; 200-key quota exhausted | `keyring = false` in `~/.config/containers/containers.conf` (FramePort agent does it), then reboot the Frame once |
+| A Unity app's text field shows a caret for a moment and loses focus; no keyboard appears (e.g. Stremio VR login) | Unity's TMP_InputField/InputField wait for Android's on-screen keyboard and close themselves without one (Lepton has none); headless VR apps also have no focused Android window, so no key press reaches them | `frame.unity_text_input` (Cpp2IL finds `TouchScreenKeyboardShouldBeUsed`/`isKeyboardUsingEvents`, rewritten to false/true) + `device.text_input_window` (lepton-show-flatscreen: Steam's keyboard and Type on Frame work) |
 | `APP_ACTIVITY is empty`, nothing starts | Manifest has category INFO only; Lepton needs LAUNCHER | `frame.launcher` (automatic) |
 | PC VR game on the Frame shows as a flat window / Revive: `Unable to load LibOVRRT DLL` / `LoaderInstance::CreateInstance chained CreateInstance call failed` | Frame SteamVR runtime rejects OpenXR apiVersion 1.1 (`XR_ERROR_API_VERSION_UNSUPPORTED`), which Proton 11's VR helper requests | `pcvr.xr_timefix` (Frame OpenXR layer, default on): retries xrCreateInstance as 1.0 |
 | Unreal PC VR game on the Frame runs as a flat window although OpenXR works (no `LogHMD` OVRPlugin lines; Unreal logs nothing when it skips the Oculus plugin) / launch.log: `FramePort oculushmd: could not create the OculusHMDConnected event` | UE's OculusHMD (and LibOVR's `ovr_Detect`) only start when the Windows event `OculusHMDConnected` exists and is signalled; on a PC the Oculus service creates it. Revive hooks `OpenEventW` for it, but that relies on Detours patching Wine's (ARM64EC) kernelbase | `pcvr.oculus_unreal` (default for Unreal Rift games; PC VR counterpart of overport's `patch_oculus_unreal`): launch.sh runs the injector through `fp_oculushmd.exe`, which provides the real event until the game exits |
 | PC VR game runs as a flat 2D window (no VR) | SteamVR was not running, so Revive/LibOVR had no runtime to bind to | FramePort now auto-starts SteamVR on Play; make sure your headset/SteamVR come up before the game |
 | PC VR game crashed launching via Steam on the OpenXR backend | Revive's newer OpenXR backend was less reliable | PC now defaults to Revive's OpenVR (SteamVR) backend; reinstall to apply |
+| Oculus PC VR game: `Unable to load LibOVRRT DLL` / `-3001` on the Frame | The game can't find a VR runtime (Revive's LoadLibrary hook doesn't work under Proton-arm64) | `pcvr.libovr_redirect` (default on) symlinks Revive's runtime as `LibOVRRT{64,32}_1.dll` in the exe dir — pure substitution; a build that checks the runtime signature then hits `-3021` (not bypassed) |
 | Oculus Rift game won't run on the Steam Frame | Oculus/LibOVR game: needs Revive, whose hooks don't work under Proton-arm64, and FramePort won't defeat the Oculus runtime signature check | Play it on this PC (SteamVR + Revive). Only OpenVR/OpenXR-native Rift games run on the Frame |
 | Un-cracked Oculus PC VR game: "Initializing OVR session" then exits / signature check on the runtime | Revive's hooks don't install on Proton-arm64; the Oculus shim rejects the unsigned Revive runtime | Not runnable on the Frame without the repack's crack extracted (not done by FramePort); use the PC version |
 | PC VR game: `Failed to initialize Oculus API (-3001)` / `Unable to load LibOVRRT DLL` | Revive's LoadLibrary hook doesn't work under Proton arm64 (ARM64EC kernelbase); the game's LibOVR shim finds no runtime DLL | Symlink `LibOVRRT64_1.dll` → Revive's DLL in the prefix's system32 (manual so far) → then -3021 (runtime signature check; open) |
@@ -34,6 +36,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 +56,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`

docs/STYLE.md

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

native/README.md

@@ -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

native/adapter/frame_adapter.c

@@ -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);
 }

native/adapter/layer_math.h

@@ -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

native/adapter/render_model.c

@@ -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;
+}

native/adapter/session_fixes.c

@@ -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;
+}

native/build.py

@@ -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]()

native/vkshim/vkshim.c

@@ -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;
+}

native/vrsettings/fp_vrsettings.c

@@ -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);
+}

native/xrshim/xrshim.c

@@ -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);
+}

packaging/release-footer.md

@@ -0,0 +1,8 @@
+## Install
+
+- **Windows:** unzip `FramePort-windows-x64.zip`, run `FramePort.exe` (warning → **More info → Run anyway**).
+- **macOS:** unzip `FramePort-macos-arm64.zip`, right-click `FramePort.app` → **Open**.
+- **Linux:** `tar xzf FramePort-linux-x64.tar.gz && ./FramePort/FramePort`.
+
+Full guide: [docs/INSTALL.md](https://github.com/spoopyghosty0/frameport/blob/main/docs/INSTALL.md) · checksums in
+`SHA256SUMS.txt`.

pyproject.toml

@@ -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"]

scripts/catalog_from_issue.py

@@ -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())

scripts/eval_heuristics.py

@@ -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)

scripts/i18n_extract.py

@@ -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())

scripts/package.py

@@ -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,23 +24,52 @@ 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"):
         shutil.copytree(ROOT / name, DATA / name)
+    # the Frame agent is uploaded as source; `flet build` turns every .py into .pyc (issue #2): keep a non-.py copy
+    shutil.copy2(ROOT / "agent/frameport_agent.py", DATA / "agent/frameport_agent.py.txt")
     print(f"staged data in {DATA}")
 
 
+def check_bundle(out: Path) -> None:
+    """The finished bundle must contain the agent's source (the app uploads it to the Frame)."""
+    found = [p for p in out.rglob("frameport_agent.py*") if p.suffix != ".pyc"]
+    if not found:
+        raise SystemExit(f"{out}: the Frame agent's source is missing from the bundle (only compiled?)")
+    print("agent source in bundle:", ", ".join(str(p.relative_to(out)) for p in found))
+
+
 def main() -> int:
     ap = argparse.ArgumentParser()
     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",
@@ -46,7 +77,10 @@ def main() -> int:
             if TARGET == "macos":  # flet's default bundled Python lacks prebuilt cryptography wheels for both Mac archs
                 cmd += ["--python-version", "3.12", "--arch", "arm64"]  # Apple Silicon; x86_64 cross-build fails
         print(" ".join(cmd))
-        return subprocess.call(cmd, cwd=ROOT)
+        rc = subprocess.call(cmd, cwd=ROOT)
+        if rc == 0:
+            check_bundle(ROOT / "dist" if args.pyinstaller else ROOT / "dist" / TARGET)
+        return rc
     finally:
         if not args.keep_data:
             shutil.rmtree(DATA, ignore_errors=True)

scripts/scrub_library.py

@@ -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())

scripts/ui_smoke.py

@@ -25,6 +25,113 @@ 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
+
+
+class FakeKeyboardSession:
+    """--fake-frame: Type on Frame connects at once (nothing is sent anywhere)."""
+
+    def __init__(self, frame):
+        self.closed = False
+
+    def key(self, name, action="down"):
+        return True
+
+    def text(self, text):
+        return ""
+
+    def close(self):
+        self.closed = True
+
+
+def open_type_dialog(app: FramePortApp) -> None:
+    """Type on Frame over the Steam Frame page, with one key 'pressed' so the screenshot shows it working."""
+    from types import SimpleNamespace
+
+    app.navigate(1)
+    time.sleep(1.5)
+    app.type_on_frame()
+    time.sleep(1.5)
+    dialog = [d for d in app.page._dialogs.controls if d.open][-1]
+    listener = dialog.content.controls[1]
+    listener.on_key_down(SimpleNamespace(key="Enter"))
+
+
+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 +140,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 +149,72 @@ 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]]))
+        steps.append(("type-on-frame", open_type_dialog))
+    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 +239,19 @@ 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)
+        from frameport.frame import keyboard
+
+        keyboard.KeyboardSession = FakeKeyboardSession
+        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 +264,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

scripts/update_smoke.py

@@ -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())

src/frameport/__init__.py

@@ -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"

src/frameport/_version.py

@@ -0,0 +1,2 @@
+# The FramePort version: the single source (pyproject reads it via hatch; CI checks a release tag matches it).
+__version__ = "0.6.0"

src/frameport/analysis/detect.py

@@ -13,6 +13,7 @@ from . import elf
 logging.getLogger("pyaxmlparser").setLevel(logging.ERROR)
 
 UNITY_GGM = "assets/bin/Data/globalgamemanagers"
+IL2CPP_METADATA = "assets/bin/Data/Managed/Metadata/global-metadata.dat"
 
 
 def _read_manifest_info(path: Path) -> tuple[str, str, str, str | None]:
@@ -56,6 +57,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,8 +104,10 @@ 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
+        il2cpp_meta = z.read(IL2CPP_METADATA) if deep and IL2CPP_METADATA in names and "libil2cpp.so" in libs else None
 
     package, version, label, activity = _read_manifest_info(path)
     libset = set(libs)
@@ -100,12 +131,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 +153,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,16 +179,53 @@ 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)),
+            # Unity (IL2CPP) text fields: they close at once on the Frame (frame.unity_text_input)
+            "text_fields": unity_text_fields(il2cpp_meta) if il2cpp_meta else [],
+            "unity_version": unity_version(ggm, lib_bytes.get("libunity.so")) if engine == "Unity" else None,
         },
     )
 
 
+def unity_text_fields(metadata: bytes) -> list[str]:
+    """The Unity text field classes an IL2CPP game contains (names from its global-metadata.dat string table)."""
+    out = []
+    if b"\0TMP_InputField\0" in metadata:
+        out.append("TMP_InputField")
+    if b"\0InputField\0" in metadata and b"\0UnityEngine.UI\0" in metadata:  # not the tail of TMP_InputField
+        out.append("InputField")
+    return out
+
+
+UNITY_VERSION = re.compile(rb"(?<![\d.])(\d{4}\.\d+\.\d+[abfpx]\d+)")
+
+
+def unity_version(ggm: bytes | None = None, libunity: bytes | None = None) -> str | None:
+    """Unity version (e.g. 6000.2.7f2): from the header of globalgamemanagers, else the version string libunity.so
+    repeats most (games packed into data.unity3d have no loose globalgamemanagers)."""
+    m = UNITY_VERSION.search(ggm[:512]) if ggm else None
+    if m:
+        return m.group(1).decode()
+    if libunity:
+        from collections import Counter
+
+        found = Counter(x.group(1) for x in UNITY_VERSION.finditer(libunity))
+        if found:
+            return found.most_common(1)[0][0].decode()
+    return None
+
+
 def _uses_feature(manifest: bytes, feature: str) -> bool:
     x = axml.Axml(manifest)
     return any(el.name == "uses-feature" and (x.attr_str(el, "name") or "").startswith(feature) for el in x.elements())
@@ -164,12 +237,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

src/frameport/analysis/elf.py

@@ -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))

src/frameport/analysis/il2cpp.py

@@ -0,0 +1,86 @@
+"""Find methods in an IL2CPP Unity game: Cpp2IL lists every method with its address ([Address(... Offset = "0x...")]
+in its "diffable C#" output with the attribute injector). Offset is the method's position in the libil2cpp.so FILE
+(not the virtual address: those differ, e.g. by 0x4000 in Stremio VR's library), which is what a byte patch needs.
+
+Results are cached per libil2cpp.so (sha256), so a rebuild of the same game doesn't run Cpp2IL again."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import subprocess
+import tempfile
+from pathlib import Path
+
+from ..core.cache import cache_dir
+
+_ADDRESS = re.compile(r'Offset = "0x([0-9A-Fa-f]+)", Length = "0x([0-9A-Fa-f]+)"')
+
+
+def parse_methods(cs_text: str, names: list[str]) -> dict[str, tuple[int, int]]:
+    """{method name: (file offset, length)} for the named methods of one Cpp2IL diffable-C# class file."""
+    lines = cs_text.splitlines()
+    found: dict[str, tuple[int, int]] = {}
+    for i, line in enumerate(lines):
+        for name in names:
+            if name in found or not re.search(rf"\s{re.escape(name)}\s*\(", line) or "Token" in line:
+                continue
+            for back in range(i - 1, max(i - 4, -1), -1):
+                m = _ADDRESS.search(lines[back])
+                if m:
+                    found[name] = (int(m.group(1), 16), int(m.group(2), 16))
+                    break
+    return found
+
+
+def _plain_version(version: str) -> str:
+    """6000.2.7f2 -> 6000.2.7 (what Cpp2IL's --force-unity-version takes)."""
+    m = re.match(r"\d+\.\d+\.\d+", version)
+    return m.group(0) if m else version
+
+
+def _cache_file(lib: bytes) -> Path:
+    return cache_dir() / "il2cpp" / (hashlib.sha256(lib).hexdigest()[:32] + ".json")
+
+
+def find_methods(lib: bytes, metadata: bytes, unity_version: str, wanted: dict[str, list[str]],
+                 cpp2il: Path | None = None, timeout: float = 900) -> dict[str, dict[str, tuple[int, int]]]:
+    """wanted: {class file (relative to Cpp2IL's DiffableCs folder, e.g. "Unity.TextMeshPro/TMPro/TMP_InputField.cs"):
+    [method names]} -> {class file: {method: (file offset, length)}}; classes or methods not in the game are left
+    out."""
+    cache_file = _cache_file(lib)
+    try:
+        cached = json.loads(cache_file.read_text())
+        if all(cls in cached.get("classes", {}) or cls in cached.get("missing", []) for cls in wanted):
+            return {cls: {m: tuple(v) for m, v in cached["classes"][cls].items() if m in names}
+                    for cls, names in wanted.items() if cls in cached.get("classes", {})}
+    except (OSError, ValueError, KeyError):
+        pass
+    if cpp2il is None:
+        from ..tools import cpp2il as tool
+
+        cpp2il = tool.ensure()
+    with tempfile.TemporaryDirectory(prefix="frameport-il2cpp-") as tmp:
+        t = Path(tmp)
+        (t / "libil2cpp.so").write_bytes(lib)
+        (t / "global-metadata.dat").write_bytes(metadata)
+        proc = subprocess.run([str(cpp2il), "--force-binary-path", str(t / "libil2cpp.so"),
+                               "--force-metadata-path", str(t / "global-metadata.dat"),
+                               "--force-unity-version", _plain_version(unity_version),
+                               "--use-processor", "attributeinjector", "--output-as", "diffable-cs",
+                               "--output-to", str(t / "out")], capture_output=True, text=True, errors="replace",
+                              timeout=timeout, cwd=tmp)
+        root = t / "out" / "DiffableCs"
+        if not root.is_dir():
+            raise RuntimeError("Cpp2IL couldn't read this game's code: " + (proc.stdout + proc.stderr)[-400:].strip())
+        out, missing = {}, []
+        for cls, names in wanted.items():
+            f = root / cls
+            if f.exists():
+                out[cls] = parse_methods(f.read_text(encoding="utf-8", errors="replace"), names)
+            else:
+                missing.append(cls)
+    cache_file.parent.mkdir(parents=True, exist_ok=True)
+    cache_file.write_text(json.dumps({"unity_version": unity_version, "missing": missing,
+                                      "classes": {c: {m: list(v) for m, v in ms.items()} for c, ms in out.items()}}))
+    return out

src/frameport/analysis/rift.py

@@ -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"