SteamVR overlay apps on the Frame (agent v75)

Host OpenVR overlays are composited over Lepton (Quest) games on the Frame; Windows overlay apps register through Proton's vrclient. Detect overlay apps (bundled .vrmanifest with is_dashboard_overlay, or OpenVR + IVROverlay + self-registration), patch pcvr.vr_overlay and the Linux entry fields vr_overlay/vr_overlay_autostart, agent register/unregister/launch_vr_overlay (IVRApplications through SteamVR's libopenvr_api.so; manifest with binary_path_linux_arm, the only key the Frame's vrserver reads). Overlay apps skip launch tests and the Linux Steam-parent watchdog and don't count as a running game. Probe sources in native/vroverlay_probe.
Merge remote-tracking branch 'origin/main'
2026-10-11 07:00:54 +02:00 · 2026-10-10 20:01:07 -04:00 · 2026-10-10 19:19:43 -04:00 · 2026-10-10 19:17:23 -04:00 · 2026-10-10 19:17:21 -04:00 · 2026-10-10 19:14:00 -04:00
366 changed files with 40558 additions and 5372 deletions
@@ -1,31 +1,30 @@
-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"]
+name: Game report
+description: 'A game doesn''t run right on the Frame, or FramePort itself misbehaves (FramePort fills this in: "Report a problem…").'
+title: "[Game report] "
+labels: ["game-compatibility"]
 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>`.
+        Please attach the **diagnostics zip** FramePort saved: drag it into the "Diagnostics" box below. It holds logs
+        and device details with personal data removed, and no game files.
  - type: input
    id: game
    attributes:
      label: Game
-      description: Title — package id (version, engine / XR API); empty for app problems
+      description: Title and package name; leave empty for problems with FramePort itself
  - type: textarea
    id: description
    attributes:
      label: What happens?
-      description: What you did, what you expected, what you saw (in the headset, if it started)
+      description: What you did, what you expected and what happened
    validations:
      required: true
  - type: textarea
    id: findings
    attributes:
-      label: Launch test / triage
-      description: Filled in by FramePort from the last launch test
+      label: Launch test
+      description: Filled in by FramePort
  - type: textarea
    id: recipe
    attributes:
@@ -1,32 +1,32 @@
-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] "
+name: Working recipe
+description: 'Share a recipe that works on the Steam Frame (FramePort fills this in: game menu → "Share working recipe…").'
+title: "[Working recipe] "
 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.
+        Thanks! Once a maintainer accepts the recipe, it becomes built-in for everyone. Please don't share game files
+        or links to them.
  - type: input
    id: game
    attributes:
      label: Game
-      description: Title — package id (platform, version, engine / XR API)
+      description: Title and package name (e.g. Lucky's Tale — com.playful.LuckysTale)
    validations:
      required: true
  - type: input
    id: result
    attributes:
      label: Result
-      description: works or issues (+ the last headless launch test)
+      description: works or issues
    validations:
      required: true
  - type: textarea
    id: recipe
    attributes:
      label: Recipe
-      description: The catalog entry (catalog/games/<package>.yaml). Don't edit the package line.
+      description: Filled in by FramePort. Don't edit the package line.
      render: yaml
    validations:
      required: true
@@ -34,16 +34,16 @@ body:
    id: environment
    attributes:
      label: Environment
-      description: FramePort, tool and SteamOS versions
+      description: FramePort and SteamOS versions
  - type: textarea
    id: notes
    attributes:
      label: Notes
-      description: What you checked in the headset, known issues, anything unusual
+      description: What you checked in the headset and any known issues
  - 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).
+        - label: I played the game in the headset with this recipe.
          required: true
@@ -150,6 +150,7 @@ jobs:
    runs-on: ubuntu-latest
    permissions:
      contents: write
+      actions: write  # starts the pages workflow
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.2.0
@@ -159,6 +160,12 @@ jobs:
          merge-multiple: true
      - name: Wheel (CLI install via uv tool / pipx / pip, and its self-update)
        run: uv build --wheel -o out && ls out
+      - name: Videos (docs/media, rendered by the showcase workflow; frameport-<name>.mp4 → FramePort-<name>.mp4)
+        run: |
+          for f in docs/media/frameport-*.mp4; do
+            [ -f "$f" ] || continue
+            n=$(basename "$f" .mp4); cp "$f" "out/FramePort-${n#frameport-}.mp4"
+          done
      - name: Checksums
        run: cd out && sha256sum * > SHA256SUMS.txt && cat SHA256SUMS.txt
      - name: Publish release
@@ -179,6 +186,11 @@ jobs:
            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"
+      - name: Refresh the website's changelog (a release made with github.token starts no other workflow)
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh workflow run pages.yml --ref main

  dev-release:
    # "Run workflow" with dev ticked: replaces the rolling `dev` pre-release (never shown by the automatic update check;
@@ -188,6 +200,7 @@ jobs:
    runs-on: ubuntu-latest
    permissions:
      contents: write
+      actions: write  # starts the pages workflow
    steps:
      - uses: actions/checkout@v7
        with:
@@ -219,3 +232,8 @@ jobs:
          gh release delete dev --yes --cleanup-tag 2>/dev/null || true
          gh release create dev out/* packaging/FramePort-selfsigned.cer --prerelease --target "$GITHUB_SHA" \
            --title "FramePort dev build ${VERSION}" --notes-file "$notes"
+      - name: Refresh the website's changelog (a release made with github.token starts no other workflow)
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh workflow run pages.yml --ref main
@@ -1,5 +1,5 @@
 name: catalog-from-issue
-# A maintainer adds the label `catalog-accepted` to a "Working configuration" issue → this opens a PR adding the
+# A maintainer adds the label `catalog-accepted` to a "Working recipe" 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:
@@ -0,0 +1,72 @@
+# The project page (site/, Astro) on GitHub Pages: https://frameport.app/
+# Rebuilt when the site, the docs it renders, the catalog or the showcase renders change on main, when a release is
+# published, and once a day (contributors, releases and the games board stay fresh). The games board also refreshes
+# itself from the catalog on main in the visitor's browser, so a catalog change shows before the next build.
+# One-time setup: Settings → Pages → Source: GitHub Actions; custom domain frameport.app (kept in the settings, not a
+# CNAME file: GitHub ignores that file for Actions deployments).
+name: pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - 'docs/*.md'
+      - 'catalog/games/**'
+      - 'bootstrap/setup.sh'
+      - 'docs/images/**'
+      - 'docs/media/**'
+      - 'docs/badges/**'
+      - 'src/frameport/ui/icons/**'
+      - '.github/workflows/pages.yml'
+  release:  # the changelog page shows every release (CI's own releases start this through workflow_dispatch)
+    types: [published]
+  schedule:
+    - cron: '17 5 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: site
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: site/package-lock.json
+      - uses: actions/configure-pages@v6
+      - run: sudo apt-get update -qq && sudo apt-get install -y --no-install-recommends ffmpeg  # the video tiles' short previews
+      - run: npm ci
+      - run: npm test
+      - run: npm run build
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # the contributors list (higher API limit)
+          # analytics (Settings → Secrets and variables → Actions → Variables); unset = none on the site
+          PUBLIC_CF_ANALYTICS_TOKEN: ${{ vars.CF_ANALYTICS_TOKEN }}
+          PUBLIC_GA_ID: ${{ vars.GA_MEASUREMENT_ID }}
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5
@@ -0,0 +1,107 @@
+name: showcase
+# Docs screenshots and the videos (the demo tour, the install tutorial, …), rendered from the demo library
+# (docs/showcase/, scripts/showcase/; see docs/SHOWCASE.md). Opens or updates one pull request (branch
+# showcase/update) when a picture really changed; the renders are also kept as a workflow artifact either way.
+on:
+  workflow_dispatch:
+    inputs:
+      videos:
+        description: "Videos to record too: names from docs/showcase/videos (e.g. tour install), all, or empty"
+        type: string
+        default: ""
+  push:
+    branches: [main]
+    paths:
+      - "src/frameport/ui/**"
+      - "src/frameport/locales/**"
+      - "docs/showcase/**"
+      - "scripts/showcase/**"
+
+concurrency:
+  group: showcase-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  render:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 60
+    env:
+      PYTHONUTF8: "1"
+      PYTHONIOENCODING: utf-8
+      TZ: UTC
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # the push's changed files decide whether the video is recorded again
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: ffmpeg and fonts
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg fonts-roboto fonts-noto-color-emoji
+      - run: uv sync --extra dev --python 3.12  # the Python the renders are made with locally
+      - name: Chromium for Playwright
+        run: uv run playwright install --with-deps chromium
+      - name: Store art cache (fetched once from the stores the app uses)
+        uses: actions/cache@v6.1.0
+        with:
+          path: ~/.cache/frameport-showcase
+          key: showcase-art-${{ hashFiles('docs/showcase/demo-library.yaml') }}
+          restore-keys: showcase-art-
+
+      - name: Docs screenshots
+        run: uv run python scripts/showcase/render_docs.py --keep showcase-out/screenshots
+
+      - name: Videos
+        # a push records the videos whose storyboard (docs/showcase/videos/<name>.yaml) changed, or all of them when
+        # the recorder changed (UI tweaks alone don't re-record ~10 MB files); Run workflow records what it's asked
+        env:
+          INPUT_VIDEOS: ${{ inputs.videos }}
+          BEFORE: ${{ github.event.before }}
+        run: |
+          if [ "$GITHUB_EVENT_NAME" = workflow_dispatch ]; then
+            read -ra names <<< "$INPUT_VIDEOS"
+            if [ ${#names[@]} -eq 0 ]; then echo "no videos asked for"; exit 0; fi
+            [ "${names[0]}" = all ] && names=()
+            uv run python scripts/showcase/record_video.py "${names[@]}" --work showcase-out/videos
+          else
+            uv run python scripts/showcase/record_video.py --changed-since "$BEFORE" --work showcase-out/videos
+          fi
+
+      - name: Keep the renders
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: showcase
+          path: |
+            showcase-out/screenshots
+            showcase-out/videos/*/video.json
+            docs/media
+            docs/images/tour-teaser.webp
+          if-no-files-found: ignore
+          retention-days: 14
+
+      - name: What changed
+        id: diff
+        run: |
+          git status --short -- docs/images docs/media
+          if [ -n "$(git status --porcelain -- docs/images docs/media)" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"; fi
+      - name: Pull request
+        if: steps.diff.outputs.changed == 'true' && github.ref == 'refs/heads/main'
+        uses: peter-evans/create-pull-request@v8.1.1
+        with:
+          branch: showcase/update
+          delete-branch: true
+          add-paths: |
+            docs/images/*
+            docs/media/*
+          commit-message: "Docs: update screenshots and videos"
+          title: "Update docs screenshots and videos"
+          body: |
+            Rendered by the `showcase` workflow from the demo library (docs/showcase/demo-library.yaml) with a
+            pretend Frame: only pictures that visibly changed are included. Look them over before merging (the
+            run's `showcase` artifact has every render).
+
+            Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
@@ -20,3 +20,13 @@ CLAUDE.local.md
 REPORT.md
 .ruff_cache/
 .claude/worktrees/
+
+# project page (site/)
+site/node_modules/
+site/dist/
+site/.astro/
+site/public/media/
+site/src/assets/media/
+site/media-hq/
+site/public/s
+site/public/setup.sh
@@ -10,8 +10,20 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
 ## Layout
 - `src/frameport/` — Python package. `pipeline.py` is the API the CLI (`cli.py`) and GUI (`ui/`, Flet 1.0) share.
  - `ui/` — `app.py` shell (sidebar with Frame connection + activity cards, routing, actions, 30 s connection poll),
-    `theme.py` (dark design tokens; change colours/spacing only there), `components.py` (pill, card, callout,
-    status_row, art_fill, confirm, `update()` = safe update: in Flet 1.0 reading `.page` of an unmounted control
+    `theme.py` (design tokens; change colours/spacing only there. Dark-only colour themes (owner: no light mode):
+    built-ins `portal` (default), `portal_oled` (true black) and `original` (the old violet; alias `classic`). Portal =
+    the logo's dichotomy: orange ACCENT = main action + selection, blue SECONDARY = secondary (outlined) buttons,
+    progress, switch tracks, PC; `dual` themes add the blue→orange sidebar edge, two-colour wordmark (`C.wordmark`) and
+    selected-tab fade (`C.portal_gradient`). Installable theme files `<data>/themes/*.json` (docs/THEMES.md: name,
+    base, dual, any subset of `T.TOKENS`; refused if light/unreadable, `T.ThemeError`), Settings → Appearance: cards
+    switch live via `app.restyle()` (rebuilds the shell, drops cached views; setting `ui.theme`), "Install theme
+    file…", "Copy this theme as a file", bin icon removes. Read tokens as `T.NAME` when building — never as a default argument or module-level constant (they
+    keep the import-time theme; module maps refill through `T.on_change`, `tests/test_theme.py` checks defaults)),
+    `glyphs.py` + `icons/` (the logo `logo.svg`/`logo-solid.svg` = a monitor that comes out of a tilted portal as the
+    Frame, and 24 px line glyphs `fp:frame|port|patch|container|test|pc|sync|live|shot|keys|recipe|link`, copied into
+    the assets dir and shown as tinted `ft.Image`s: pass `G.FRAME` … wherever an icon goes, `C.as_icon` / the button
+    helpers handle both kinds; `src/assets/icon.png` = the bundles' app icon), `components.py` (pill, card, callout,
+    checklist, art_fill, confirm, `update()` = safe update: in Flet 1.0 reading `.page` of an unmounted control
    raises), `jobs.py` (background FIFO job queue, one at a time, cancel via Reporter; no Flet), `views/`
    (library: search/filters/tags/sort as pure tested helpers; game: hero + one-click install, patches under
    "Customize"; frame: device + readiness + installed, or connect wizard; files: the Frame's file manager (persistent
@@ -26,7 +38,8 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    launch.sh logs `start/end <unix>` to `<anchor>/plays.log` (upgrade_launchers adds it; Proton launchers exec → start
    only) and shots are matched by time; thumbnails cached in `<data>/screenshots-cache/<frame>/`, shown by asset URL;
    delete leaves screenshots.vdf alone (Steam rewrites it at exit); game menu → "Screenshots" = `go("screenshots",
-    pkg)`); live view (`views/live.py` + `install/livestream.py`: the Frame's built-in SteamVR "headset view" webcam
+    pkg)`; Copy image (card hover button, right-click, viewer) = `core/clipboard.copy_image` (Windows/WSL: PowerShell
+    bitmap + file via %TEMP%, macOS osascript PNG, Linux wl-copy/xclip; Flet's set_image only in web mode)); live view (`views/live.py` + `install/livestream.py`: the Frame's built-in SteamVR "headset view" webcam
    (`steamvr-v4l2cam.service` → v4l2loopback "SteamVR" /dev/video99, see docs/FRAME_RUNTIME.md) + the default
    output's pulse monitor (sound) → `fp_venc` (`native/venc`, own clean-room V4L2 driver of the Frame's iris
    hardware encoder: RGB24→NV12 box downscale with NEON, H.264 CBR, one frame per slot of an even fraction of the
@@ -53,7 +66,36 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    await a FilePicker) must be coroutine functions or go through `page.run_task`: Flet doesn't await a lambda's
    coroutine (the Files row Download button silently did nothing). `ui_smoke.py --fake-frame --gestures` drives real
    mouse drags/right-clicks.
+    Live Frame data comes from one app-owned `app.monitor_hub` (`frame/monitor_hub.py`): subscribers name modules +
+    interval, the hub runs one agent `_monitor` stream (union of modules, fastest interval; per-module collection
+    needs agent v73), reconnects after a lost stream and stops it when nobody subscribes; `_poll` retries an "error".
+    Subscribers: "monitor" (the Monitor tab, everything, only while shown) and "card" = the sidebar's live Frame card
+    (`ui/frame_card.py` helpers: battery ring, "now playing" row with fps + 2-min sparkline → click opens Monitor;
+    games + battery every 5 s, paused while a job's stage is "Upload…", only while connected and setting
+    `ui.live_frame_card` (Settings → Appearance, default on) is on; else the battery comes from the 30 s poll).
+    ui_smoke injects `FakeMonitorSession` as the hub's `session_factory`.
    User tags live in library entries (`tags`), filters in library setting `ui.library`.
+    Easter eggs (`ui/easter.py`, owner's wish; never mentioned in the UI or docs): seven quick clicks on the sidebar
+    logo (the *wordmark's* portal glows + rings, a cover is tossed out of it and falls across the window on a random
+    arc: `toss_path`, `page.overlay` at the computed window position `_wordmark_portal`; the logo's portal in
+    themes without one), the Monitor's fps number has a mood tooltip (above the number, clear of the pointer) and
+    2.5 minutes within 0.5 fps of target (`PERFECT_SECONDS`) make the game card glow and pulse blue/orange for 5 s,
+    the number grow in the portal gradient and the sparkline take it; the "Perfect pacing" pill + line stay until the
+    rate slips (`PerfectPacing.done`, `_show_perfect`, `Sparkline.portal`), holiday badges on the logo that dance on
+    hover and shower the window on click (`HOLIDAY_MOTION`; `SHOWERS`/`shower_plan`: New Year confetti, winter snow,
+    Valentine hearts, Pi digits, clovers, hopping eggs, bouncing pumpkins; `holiday`: Valentine's
+    heart, Pi Day, St Patrick's clover, Easter Sat-Mon egg (computus), April 1 = the logo upside down until hovered,
+    Halloween pumpkin, Dec 31-Jan 1 party popper, else Dec 20-Jan 2 snowflake; on those days the logo's box grows to
+    hold the badge: Flutter only hit-tests inside a control's bounds; `FRAMEPORT_TODAY` pretends a date),
+    Library search "frameport" (logo spins, "That's me!"), Type on Frame "hello" (keys still go to the Frame; a
+    headset peeks up from the window's corner and waves), the battery ring (only the ring, with a glow behind
+    it; not the percentage) empties at once and spins while its bar refills, then pulses, on reaching 100 % plugged (`charged_now`, `ring_pulse`, `ring_glow`), a long upload (>2.5 min, `HOP_AFTER`) makes the transit cover hop, the Live view
+    tab shows a blinking ON AIR sign while streaming
+    (`app.sync_on_air`), install milestones (confetti +
+    message at the 1st/10th/100th *different* game: settings `fun.installed` = game ids, `fun.milestones` = shown;
+    each milestone shows once ever, recorded before it's shown; updates/reinstalls never count; the first use seeds
+    from games already on a Frame and marks passed milestones shown). Setting `ui.easter_eggs` (no UI) turns them
+    off; the showcase demo library has them off (steps hook `easter_eggs` for egg demos). Reduce motion: no animation.
    **Performance rules** (the app froze before): never put image bytes in controls — artwork is served by URL from the
    GUI assets dir (= user data dir; `ft.run(assets_dir=…)`), as thumbnails (`artwork/thumbs.py`, Pillow); the
    library view is persistent, streams cards in batches from a background thread and filters by toggling visibility;
@@ -61,10 +103,31 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    **Never recreate clickable controls on progress ticks** (sidebar, activity tiles): update their properties —
    replacing them 5×/s swallowed clicks (couldn't leave the Library during an upload).
    Labelled switches: `C.switch(label, …)` (Material's default label colour is dark on our dark theme).
+    Cover cards (Library grid + shelf): `library.card_hover`/`hover_motion` (lift, art zoom inside the clipped frame,
+    radial `scrim`, accent-tinted shadow) and `C.CoverButton` (frosted round button, accent under the pointer; Play =
+    blue then orange ring ripple + "Starting on Frame…" pill for STARTING_S; its `.status` layer must sit *below*
+    the button in the Stack, else it takes the clicks); the game page's Play turns into "Starting on …" with a spinner
+    (`GameView._starting`). Reduce motion: no lift/zoom/rings. Filled buttons use a glyph's `-solid` variant
+    (`glyphs.solid`, e.g. `frame-solid.svg`: the outline glyph faded into the orange).
+    Empty states (`C.empty_state(..., features=[(icon, heading, sentence)])`): with features the portal is bigger, a
+    soft portal light (`C.portal_glow`) fills the screen and `C.feature_row` says what the screen will show (the
+    not-connected Files/Screenshots/Live/Type/Monitor tabs and the empty Library); the idle Live view is a framed
+    "screen" with its own Start button + `live_features()`, Type on Frame shows `keyboard_tips()` under the box.
+    Setup checklists (Frame → Ready to play, Settings → Tools / This PC) = `C.checklist([C.Check(ok, title, detail,
+    help, fix=(label, icon, handler), extra=control)])`: ok True/False/"warn"/None (= spinner); the fix button shows
+    inline only while an item isn't ready — wire existing actions only. Motion: `app.body` holds an
+    `ft.AnimatedSwitcher` (`app._show_view`): a new route gets a new wrapper (150 ms fade), a same-route redraw swaps
+    the wrapper's content (no animation; persistent views just remount); the wordmark's portal (`wordmark().data`)
+    pulses once when frame_state turns "connected"; both off with setting `ui.reduce_motion` (Settings → Appearance
+    "Reduce motion", `app.reduce_motion`). Settings has a fixed index column (`settings.SECTIONS` order, Appearance
+    first, Remove FramePort last): entries scroll the section column via `scroll_to(scroll_key=…)` (sections wrapped
+    in Containers with `ft.ScrollKey`), the header stays; `app.settings_view.show_section(key)` (ui_smoke
+    `settings-index`).
    Help hints: wording for non-obvious terms lives in `ui/help.py` (`HELP`); show it with `C.help_icon(key)` or the
-    `help=` argument of `section`/`status_row`/`kv`, tooltips via `C.tip()` (wraps). Game actions for the Library
-    right-click menu (one `ft.ContextMenu` around the grid, filled on right-click) and the game page's "…" menu come
-    from `app.game_actions()`. Picking art (`sources.apply_choice`) downloads into a staging dir and keeps the old
+    `help=` argument of `section`/`kv` (`C.Check` help key), tooltips via `C.tip()` (wraps). Game actions for the Library
+    right-click menu (one `ft.ContextMenu` around the grid, filled on right-click; short: `menus.quick_menu`, key actions
+    + "More actions…" = the game page with its full "…" menu opened from code, `app.open_game_menu`) and the game
+    page's "…" menu (`menus.menu_sections` quick=False, sectioned) come from `app.game_actions()`. Picking art (`sources.apply_choice`) downloads into a staging dir and keeps the old
    art if nothing came back; "Update Steam art on Frame" re-sends the art set to the game's anchor (agent ≥ 12).
    Patch descriptions/reasons describe the general case, naming games only as "e.g. …".
  - Installs: queued/cancelled/failed ones are remembered (library setting `ui.installs`) → Library "Resume" bar;
@@ -79,23 +142,6 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    `launcher` field, else text swap), list_installed `drive`/`drive_missing` (install_state keeps such games
    "installed"). PC: `install/drives.py`, library setting `install.drive` (Frame page → Storage), game menu
    "Move to…" (job kind tool-frame), CLI `frame drives`/`frame move`/`install --dest`. Untested on the device.
-  - **Quest games on this PC via AXRB** (experimental, branch `worktree-pc-android-axrb`, docs/PC_ANDROID.md): the
-    "This PC" target (`PcReviveTarget`) installs APKs through `targets/pc_android.py` + `tools/axrb.py`. AXRB
-    (Android-XR-Bridge/AXRB, Windows: x86_64 Android 16 emulator + libndk_translation + its own OpenXR runtime →
-    `axrb-host-bridge.exe` → SteamVR) is downloaded only on first use (`AXRB-Setup-<v>.exe /S`, SHA256SUMS, per user
-    → `%LOCALAPPDATA%\Programs\axrb-launcher`), never bundled/modified (host code: AXRB Source-Available License).
-    Its runtime setup lives only in AXRB's Electron JS, so FramePort repeats it (pins read from the installed
-    `app.asar` `core/components.json`, AVD `axrb-managed-api36` port 5584, adb `-P 5038`, receipts `ready.json`/
-    `license-acceptance.json`, so AXRB's own launcher shares it). Spike 2026-10-10 (headless): **unconverted APKs
-    abort** (Meta platform loader) → PC build = OVRPort patches + `Patch.on_pc` APK fixes (`base.pc_selection`,
-    `build(pc=True)`, library `build_pc`, `pc_recipe_fingerprint`); Lucky's Tale ran a full OpenXR session in AXRB's
-    runtime; Pinball FX VR crashed in gfxstream vkAllocateMemory (AXRB's layer). SteamVR can't stand in for a headset
-    (null driver: no D3D11 adapter; vrlink without a Frame: no instance) → frames need the owner. Play = Steam
-    shortcut `powershell.exe -File %LOCALAPPDATA%\FramePort\axrb\fp-axrb-run.ps1 -Package …` → AXRB's
-    `run_windows_game.ps1`; all such shortcuts share Exe, so agent v71 `upsert/remove_shortcut(options_key=
-    "-Package <pkg> ")`. AXRB scripts start through WMI (`axrb.spawn_detached`): QEMU/adb inherit any handle, and
-    even /dev/null through WSL interop kept the call hanging; PowerShell 5.1 `*>>` logs are UTF-16 (`read_log`). Triage
-    `kind: axrb`. Full uninstall in AXRB deletes OBB + saves; a signature change needs one.
  - **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).
@@ -203,8 +249,12 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
  - `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:
+    chars; `*_links` = `IssueLinks(form, plain, body)`: body = the Markdown the form writes (`### <label>`, recipe in
+    a ```yaml block; labels checked against the templates), plain = `?title=&body=` link. GitHub #167: some (Flatpak)
+    browsers opened the form with empty fields → `app.open_issue` copies the body to the clipboard and offers "Form
+    empty? Open a plain issue"; keep the templates valid YAML, quote `: ` in descriptions). "Share working config" →
+    `working-config.yml` issue → maintainer label `catalog-accepted` (a plain issue needs `working-config` added by
+    hand) → `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
@@ -218,9 +268,15 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
    signed, `ready.json`); `apply()` writes + starts detached `apply.ps1`/`apply.sh` (wait for pid → Windows: copy over,
    replaced files kept in `updates/<ver>/previous` because the zip has no top folder; macOS/Linux: mv to `.old` + swap,
    rollback, `xattr -dr` quarantine → relaunch; `<data>/logs/update.log`). `ui/updater.py`: background check (10 s,
-    then 6 h), sidebar card (hidden control, toggled), Library bar (`library_bar`), notes dialog (`ft.Markdown`), job
+    then 6 h), sidebar card (hidden control, toggled), Library bar (`library_bar`), changelog dialog, job
    `app-update` that restarts only when no other job is active, `apply_pending_at_start()` in `main()` for
-    "Install updates automatically"; Settings → Updates. CLI: `--version`, `frameport update [--check (exit 10)]
+    "Install updates automatically"; Settings → Updates. Changelog: `updates.fetch_changelog` (releases list,
+    `app-releases.json`, same 6 h cache, offline → cached / []) → `ChangelogEntry` (`whats_new()` keeps only the tag
+    message's "What's new" part: CI's intro, update hint and release-footer.md stripped); `between`/`changelog_for`
+    (installed < v ≤ offered, dev entry only when on/choosing dev, skipped versions included), `recent_history`;
+    the update/dev dialogs show one collapsible section per version (`_changes_column`, newest open); after an update
+    `pending_news` (setting `update.last_seen_version`; first start only records it; offline → retried next start)
+    → Library "was updated" bar → "See what's new…"; Settings → Updates "What's new…" = recent history. CLI: `--version`, `frameport update [--check (exit 10)]
    [--yes]`, once-a-day stderr hint read from the cache only (`refresh_cache()` in a daemon thread writes no
    settings, to avoid read-modify-write races). `scripts/update_smoke.py <archive>` runs the real extract + swap script
    (no relaunch) — CI runs it on all three OS with the archive it just built.
@@ -229,7 +285,17 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
    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).
+- `bootstrap/bootstrap.sh` — one-time Frame setup served by the pairing server (app key, podman fix, Developer Mode, Lepton).
+  `bootstrap/setup.sh` — the setup URL (`curl -fsSL https://frameport.app/s | bash`, copied to the site by
+  `site/scripts/sync-media.mjs`): finds the PC (stdlib mDNS on 5353 for `_frameport-pair._tcp`, which the pairing
+  server announces while open; else the USB address and a /24 scan of `/ping`), `/hello` → the user clicks Allow (4
+  digits on both sides, `ask_digits`) → `/wait` hands over the code → runs bootstrap.sh exactly like the typed line.
+  Checked on the dev Frame 2026-10-10 (mDNS and scan paths) with a stub bootstrap; tests/test_setup_url.py.
+  Auto-pairing (`frame/autopair.py`, `app._start_auto_pair`, setting `frame.auto_pair`, default on; off with
+  FRAMEPORT_HOME/FRAMEPORT_NO_AUTO_PAIR): while no Frame is connected, Frames in Developer Mode (devkit mDNS, else a
+  30 s scan of the /24s for :32000/login-name, deduped by host key) are connected if FramePort's key works, else
+  offered the key via devkit.register every 4 s (refused at once until Pair new host is open; 45 s back-off after an
+  unanswered request). This WSL dev PC never hears the Frame's mDNS (Hyper-V firewall): the scan finds it.
 - `catalog/games/<package>.yaml` (installed apps also fetch these from GitHub `main`, see "Catalog updates") — 38 recipes (34 verified 2026-09-28; Deadpool VR, 4XVR, NEX Player and AC Nexus's
  90 Hz default confirmed later by the owner); `catalog/triage.yaml` — log signatures → fixes.
 - `native/` — sources of the prebuilt binaries in `artifacts/` (adapter, VrApi bridge patches, GL shim, stubs).
@@ -254,12 +320,20 @@ 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
+- Docs screenshots + videos (docs/SHOWCASE.md): never by hand. `uv run python scripts/showcase/render_docs.py`
+  renders `docs/showcase/shots.yaml` into `docs/images/` (every shot twice, kept when both agree; only visibly changed
+  files are rewritten; `--check` for CI) and `scripts/showcase/record_video.py [names] [--draft]` records the
+  storyboards `docs/showcase/videos/<name>.yaml` (tour = FramePort in use + README teaser; install = the install
+  tutorial: instruction cards for the download / the command on the Frame, the rest filmed from a first start) into
+  `docs/media/frameport-<name>.mp4`. Both build the demo library first (`demo_home.py`, profile `demo` or `fresh`:
+  catalog games from `demo-library.yaml` + `demo-analyses.json`, art/details cached in ~/.cache/frameport-showcase, a
+  pretend Frame from `showcase-frame.json`) in a temp FRAMEPORT_HOME: no personal data, refuses the real data dir
+  and placeholder art; discovery is off and the setup command shows placeholders for the address and code. Steps find elements
+  by name through Flutter's semantics tree (`scripts/showcase/web.py`: text, tooltip; the innermost match wins) —
+  give new icon-only controls a tooltip. The `showcase` workflow renders on UI pushes to main (+ the videos whose
+  storyboard changed, or the ones named on dispatch) and opens PR `showcase/update`; releases attach every video as
+  `FramePort-<name>.mp4`. `scripts/scrub_library.py` (the owner's own library) is only for private screenshots now.
+  README rules (owner): says not every game runs (no longer "proof of concept" since 1.0), provides no piracy tools, credits the wrapped
  projects (most functionality is theirs); neutral technical wording; no Quest2Frame mentions anywhere.
 - GUI smoke test: `uv pip install flet-web playwright && playwright install chromium`, then
  `FRAMEPORT_HOME=<test dir> python scripts/ui_smoke.py --out <dir> [--game <pkg>] [--frame steamos@<host>] [--update]` (`--update` = fake release: banner, dialog, Settings → Updates) and look
@@ -324,7 +398,10 @@ The Frame runs firewalld (22 and 32000 open). PC side: the setup server needs in
 firewall blocks it silently (`DefaultInboundAction Block`): `pairing.ensure_reachable` adds a temporary rule via one
 UAC prompt, removed when the server stops (flag file in %TEMP%, max 35 min); hints per OS after 45 s without a request
 (`pairing.firewall_hint`). Flet 1.0 patches aren't thread-safe → `app.serialize_flet_updates()` (a dialog shown while a
-scan redraw ran never closed: "dropped a patch for unknown control").
+scan redraw ran never closed: "dropped a patch for unknown control"); it also makes property writes (Flet's
+`Prop.__set__`) take the same `app.FLET_LOCK`: a property set on a background thread while the loop packed a patch
+changed the control's `_values` mid-iteration ("dictionary changed size during iteration", a sidebar click's page
+change died while the live Frame card took a sample). Anything that serves the app (ui_smoke, showcase) calls it too.
 **Lepton:** needs an activity with category **LAUNCHER** (Quest apps often only have INFO → "APP_ACTIVITY is empty").
 **2D apps:** Lepton runs every app headless (`lepton.headless=true`, only OpenXR output reaches the headset) unless the app folder (`<base>/lepton-app/`) has a `lepton-show-flatscreen` file (liblepton/app_metadata.sh) → Waydroid window on gamescope; agent v28 `set_flatscreen` at finalize for `vr_kind == "none"`. Android 11's navbar covered the
 app's controls → patch `device.hide_navbar` (default on for vr_kind none, migration `flat_hide_navbar`) exports
@@ -635,6 +712,7 @@ FrameBridge `snapshot=N` (`snapshot_gl.c`, GLES): every N s the left-eye image t
 own context and saved as `files/fb_snap_0-7.ppm` (quarter size) — headless launches show a black headset view, this
 shows what the game draws. Vader: Lucasfilm logo (an OBB mp4: video works), then its loading card (portrait + segmented
 bar) that never advances; the async loader thread sleeps and OBB reads stop (~168 MB of a 2.7 GB pak).
+**SteamVR overlay apps (agent v75, 2026-10-10):** host OpenVR overlays (VRApplication_Overlay) are composited over Lepton (Quest) games on the Frame (probe checker seen over 4XVR in the headset view, `native/vroverlay_probe`); Windows ones register through Proton's vrclient too (Temporal Reality's Windows build created its overlays; fpsVR never reaches OpenVR under Proton). Detection `analysis/vroverlay.py` (bundled `.vrmanifest` with `is_dashboard_overlay`, else OpenVR + IVROverlay + self-registration markers, engine Other; Rift fingerprint `RIFT_ANALYSIS`), patch `pcvr.vr_overlay` (param autostart), Linux entry fields `vr_overlay`/`vr_overlay_autostart` (game page switch); agent `register_vr_overlay`/`unregister_vr_overlay`/`launch_vr_overlay` (IVRApplications via ctypes, live; manifest `<anchor>/frameport-overlay.vrmanifest`, the app's own key, binary = launch.sh). **SteamVR on the Frame reads only `binary_path_linux_arm`** (binary_path_linux alone is skipped). Overlay apps: no launch test, no Linux Steam-parent watchdog (`FRAMEPORT_OVERLAY`), not a "running game". A Steam overlay-app shortcut and a game shortcut run together. Autostart at the next SteamVR start: not verified yet. Details: docs/FRAME_RUNTIME.md "Overlay apps".
 **Lepton's logcat mirror dies (agent v67, 2026-10-09):** occasionally launch.log ends with `logcat: Unexpected EOF!` right after the game starts (about 1 launch in 50, Lepton 2.8.14 and 3.0.5): no dashboard auto-hide, no launch-test result. launch.sh's `_logcat_keeper` then reads `podman exec lepton-steamlaunch-<appid> logcat` itself into launch.log (up to 5 restarts while the game runs).
 **Double launch (agent v57, 2026-10-06):** a second Play while Lepton still boots (~10 s with nothing to see) made
 the second Lepton stop the first one's container ("Waiting for steamlaunch-<appid> (PID …) to exit", exit 137
@@ -668,12 +746,46 @@ XR_ERROR_RUNTIME_FAILURE); OVRPlugin ignores that ("CreateSwapchain for eye 0: 0
 ovrp_EndFrame4 (memset). FrameBridge `cube_standin` (default on, `native/adapter/cube_standin.c`) serves a refused cube
 swapchain as one GL cube-map texture in the app's context (GLES only) and drops its layers. Verified headless with
 Budget Cuts Ultimate (2048² sRGB, 12 mips; runs on at ~70 fps); what the cube layer showed is simply missing.
+**Hardware video decoding (PR #96, PR #128 by Lucas-Mathieu, adapted 2026-10-10, agent v71):** `native/hevc` = one
+OMX plugin `OMX.frameport.{avc,hevc,vp9}.decoder` (FFmpeg v4l2m2m on Iris /dev/video-dec0, FFmpeg software decoders as
+fallback inside the component, Vulkan copy for big native surfaces). The connection installs it once per Frame
+(`ensure_video_codec` → agent `video_codec_status`/`install_video_codec`: `~/.local/share/frameport/video-codec/versions/
+<manifest sha>` + `current` symlink). A Frame keeps the same or a newer `revision` (no flip-flop between PCs) → **bump
+`revision` in native/hevc/build.py with every artifact change**; a failed install isn't retried during the connection.
+Per game: only launchers of games whose recipe has `frame.hw_video_decode` (install stage, no APK change; suggested
+from analysis `media_codec`, ANALYSIS_VERSION 8; deployment.json `hw_video_decode`) get the codec line → the Podman
+wrapper (native/hevc/podman.py) mounts the plugin into that container (merged media_codecs.xml in
+$XDG_RUNTIME_DIR/frameport-video). Off for every game: Settings → Installing (library `video.hw_decode` → agent
+`video_codec_switch` = video-codec/disabled); one game: `FRAMEPORT_NO_HW_VIDEO=1 %command%`. `upgrade_launchers`
+converts agent ≤70 launchers (Batman's `<base>/frameport-codec` → keeps the line, folder then removed). Batman: catalog
+ migration `batman_video_patches` (`frame.hw_video_decode` + hidden adapter setting `surface_native`). Iris: 8K
+refused (ENOMEM) while any other decoder session is open; SteamVR's vrlinkrunthread holds one ~12 s at game start →
+refused opens retry until 20 s after the plugin loaded (else 2 s), then software; VP9 7680x3840 never returned a
+picture → VP9 ≤4096x2304; hidden VP9 frames come back as empty capture buffers (bytesused 0, no LAST):
+FFmpeg's wrapper ended the EOS drain at the first one (two-pass VP9 lost its last ~25 frames) → build.py requeues
+them (codec revision 8; drain ends at LAST, or 1 s after a skipped empty buffer; dev Frame 2026-10-10: 600/600 =
+OMX.google.vp9 Y hashes). Rebuilds are deterministic (ext4 + NTFS path
+with spaces, two NDK copies → same; rev 8 141de01f…; PR #128's own sources → its 27a2d749…). Not yet run on the device.
+**Vulkan shader dump (GitHub #140, 2026-10-10):** adapter `vk_shader_dump=1` (Vulkan shim, `native/vkshim/shader_dump.h`;
+applies where vk_sanitize can: Unreal/Other arm64) writes each distinct SPIR-V module once to
+`files/fp_vk_shaders/<size>_<sha256>.spv` (tmp + rename) and one `index.txt` line per vkCreateShaderModule (`<seq> <ms>
+<unix ms> <name> new|known|again|failed`, O_APPEND) to find the module behind a GPU hang. Agent v72 `collect_diag`
+returns `shaders` (newest modules of fp_vk_shaders + fp_spirv, ≤4 MB each, base64) → bundle
+`games/<pkg>/target/shaders/`. Triage `gpu-hang` suggests both dumps; `triage.graphics_api` (FrameBridge's
+xrCreateSwapchain formats: <0x1000 Vulkan, else GL) keeps only the session's API's (`API_ONLY`). Host-tested only.
+Agent v74: a reporter's hang came ~10 s after the last new module, so the culprit wasn't among the newest written →
+with an index naming modules, `shader_dumps` sends every module of the index's **newest session** (after the last
+`# start`), deduplicated, last used first, each ≤4 MB, ≤30 MB in all (`session` = how many it names) + that session's
+index lines; no index (fp_spirv) = the old newest-by-mtime 4 MB. One JSON line (~40 MB base64) over the SSH channel
+is read whole by `Frame.agent` (fine at that size); `_Writer.fit` drops the least recently used modules last, after
+cutting logs, to stay under the 24 MB zip limit.
 **Vivox API 31 (GitHub #101, 2026-10-09):** newer Vivox builds (Green Hell VR) call Android 12 AudioManager
 communication-device methods from `com.vivox.sdk.AudioChangeListener` with no SDK check → NoSuchMethodError on Lepton's
 Android 11. `frame.vivox_audio_route` (analysis `vivox_api31`, ANALYSIS_VERSION 4) makes every such method return at
 once (`Dex.return_early`: return-void / `const/4 v0,0; return v0`; nopping the invoke would leave a move-result the
 verifier rejects). Older Vivox (Eleven Table Tennis, BattleSisters) lacks that code and isn't matched. Verified
 headless: Vivox initialises, 150 s at ~65-70 fps.
+**Steam Input gamepad for 2D apps (GitHub #162, agent v72, 2026-10-10):** Lepton's Android only has the Wayland seat's `wayland_touch/keyboard/pointer`. Steam makes its virtual pad (uinput, `/devices/virtual/input`, 28de:11ff, "Microsoft X-Box 360 pad N", ACL for steamos) only while the Frame's controllers are on (controller.txt "Steam Controller reserving XInput slot 0"; gone when they sleep), also with no game running; steamos-manager's 28de:0000 keys device isn't a pad (no BTN_SOUTH). Lepton's container root (system_server too) = steamos (`keep-id:uid=0`), so a bind-mounted `/dev/input/eventN` opens. Opt-in `device.steam_gamepad` (vr_kind none; suggested for `android.hardware.gamepad`/`LEANBACK_LAUNCHER`, analysis `gamepad`, ANALYSIS_VERSION 9): deployment.json `steam_gamepad` → launcher `GAMEPAD_LINE` (after the codec line: exports FRAMEPORT_GAMEPAD + LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD, puts `agent/bin` first on PATH) → `PODMAN_WRAPPER` (written by ensure_host_fixes; non-`run` calls go straight on; `run` imports the agent's `podman_run_args`; hands on to the next Podman after its own PATH entry with itself removed from PATH, so it chains to the codec wrapper either way round) adds the pads + `Vendor_28de_Product_<pid>.kl` (Xbox 360 layout). Verified headless with a uinput stand-in pad (Stremio's container: EventHub `classes=0x80000141`, our key layout, KeyEvent BUTTON_A dispatched); with Steam's real pad and a game: not yet. Pads made after the start aren't seen until the next one.
 **Multiview programs on flat framebuffers (GitHub #77, Doom3Quest, 2026-10-09, prototype):** Mesa enforces OVR_multiview's
 "program num_views == draw framebuffer views" rule (`draw_validate.c`, the draw is dropped silently); Qualcomm doesn't.
 Doom3Quest compiles every VS with `layout(num_views=2) in;` and draws its HUD/PDA into 2D-texture FBOs → black. Opt-in
@@ -7,133 +7,127 @@
 ![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-blue)
 ![Steam Frame](https://img.shields.io/badge/Steam%20Frame-supported-1b2838?logo=steam&logoColor=white)

-Install games that target the Meta Quest, Android, or general PCVR onto your **Valve Steam Frame**. FramePort handles everything from uploading game files, setting up your Frame, injecting compatibility patches, and adding shortcuts to your Steam library. FramePort aims to be as simple as possible by taking advantage of the fact that the Steam Frame runs on Linux.
+Install Quest games, Android apps, Linux apps and PC VR games on the **Valve Steam Frame**. FramePort sets up the
+Frame, patches each game so it runs there, uploads it and adds it to your Steam library with artwork.

-![Library](docs/images/library.png)
+[![FramePort: library, one-click install, play, monitor](docs/images/tour-teaser.webp)](docs/media/frameport-tour.mp4)

-> **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/). 
+▶ [Watch the full tour](docs/media/frameport-tour.mp4) · New to FramePort? [Watch the install tutorial](docs/media/frameport-install.mp4)
+(about 90 seconds each)
+
+> **Notice:** FramePort doesn't download, share or unlock games. Use games you got legally, for example from
+> [SideQuest](https://sidequestvr.com/). FramePort downloads published open-source tools (see [Built on](#built-on))
+> and adds its own patches so games run on the Frame.
+>
+> Not every game runs on the Frame: recipes are tested by the community, and some games need Meta's services or
+> hardware the Frame lacks.

 ## Features

- **Painless setup:** one short command on the Frame. No root, no `sudo`, no password.
-  [What it changes](docs/FRAME_SETUP.md).
- **Type on Frame:** use your computer's keyboard on the Frame: in VR apps, Android apps, Steam and the desktop.
-  [More](#type-on-frame).
- **One click per game:** convert, patch, sign, upload, add to Steam with artwork, launch test. Artwork that can't be found automatically can be picked from the stores or replaced with your own images.
- **Per-game recipes:** a tested catalog plus detection rules; every patch explained in plain words.
- **FrameBridge:** FramePort's OpenXR adapter emulates what the Frame natively lacks (passthrough, room, controller models,
-  curved and 360° layers); game settings as simple switches.
- **Beyond Quest:** Android apps as windows, PC VR via Proton or Revive, Windows (non-VR) games via Proton, a Files
-  tab with drag and drop.
- **Linux apps:** install Linux apps (AppImage, a folder, or a zip/tar archive) on the Frame with a Steam
-  shortcut; arm64 builds run natively on SteamOS, x86_64 builds through Valve's FEX translator.
- **Install links:** "Install with FrameDrop" buttons on web pages (the one-click protocol of the FrameDrop
-  sideloader) and pasted links open in FramePort, which asks, downloads, adds and installs the build.
- **Screenshots tab:** the screenshots you took in the headset, sorted by game (matched by play time) and day;
-  view them and download them to your computer.
- **Live view tab:** watch what the headset shows, with sound, in a browser window on your computer.
- **Monitor tab:** the running game's frame rate, the Frame's load, temperatures, power and battery live, and its
-  processes, which you can end. [More](#monitor).
- **Self-updating** releases, redacted diagnostics, one-click problem reports and working-config sharing.
+![Library](docs/images/library.png)

-## Quick start
+- **Easy setup:** one line in the Frame's terminal. No root, no password. [What it changes](docs/FRAME_SETUP.md).
+- **One click per game:** patch, upload, add to Steam with artwork and test that it starts.
+- **Recipes:** tested patches and settings for 90+ games; other games get suggested patches, each explained in
+  plain words.
+- **Game settings:** sharpness, refresh rate, controllers, 360° video and mixed reality as simple switches.
+- **More than Quest games:** Android apps in a window, Linux apps, PC VR games and Windows programs.
+- **Install links:** "Install with FramePort" buttons on websites ([frameport.app](https://frameport.app) links) open
+  in FramePort.
+- **Your Frame from your PC:** Type on Frame (your keyboard on the Frame), Files, Screenshots, Live view (what the
+  headset shows, in your browser) and Monitor (frame rate, temperatures, battery, processes).
+- **Updates itself**, and reports problems without personal data.

-1. [Download](https://github.com/spoopyghosty0/frameport/releases/latest) and unzip the build for Windows, macOS
-   (Apple Silicon) or Linux, then start FramePort.
-2. **Connect the Frame** (once):
-   1. In FramePort click **Steam Frame → Show setup command**. Keep FramePort open; the Frame and your computer must
-      be on the same Wi-Fi.
-   2. On the Frame open the **SteamVR dashboard → Launch a program → Desktop**: the Linux desktop opens on a virtual
-      screen.
-   3. Open the app menu (bottom-left corner of that desktop) → **System → Konsole** (or search for Konsole).
-   4. Type the command FramePort shows exactly as shown (on-screen keyboard or any USB/Bluetooth keyboard) and press
-      **Enter**. This will run the following [bash setup script](bootstrap/bootstrap.sh).
-   5. After a few seconds the desktop closes by itself (Steam restarts once); that's expected. If
-      Steam asks to install **Lepton**, confirm it. FramePort shows the Frame as connected within a minute. No
-      password needed.
-3. **Add games → Scan a folder** with your game backups (APK + OBB, or PC VR game folders).
-4. Open a game → **Install on Frame**, then play it from the Frame's Steam library.
-
-Full guide, firewalls and troubleshooting: [docs/INSTALL.md](docs/INSTALL.md). Questions (e.g. how to lay out games
-with OBB files): [docs/FAQ.md](docs/FAQ.md).
-
-## 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** (its own tab in the sidebar), select a text field in the headset and type: searches, logins, chat, in any
-app, in Steam or on the desktop. Paste longer text to type it in one go. Nothing to install: FramePort adds a virtual
-keyboard on the Frame while the tab is open, without root.
-
-![Type on Frame](docs/images/type-on-frame.png)
-
-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).
-
-## Screenshots
-
-Screenshots you take in the headset show up in FramePort's **Screenshots** tab, grouped by day and matched to the game
-you were playing. Open one full size, step through them, and download single shots, a selection or all of them to
-your computer.
-
-![Screenshots](docs/images/screenshots.png)
-
-![Screenshot viewer](docs/images/screenshot-viewer.png)
-
-## Live view
-
-The **Live view** tab streams what the headset shows, with its sound, to your computer: click **Start live view** and
-it opens in your default web browser (full screen with a double-click; click **Sound on** to hear it, as browsers start
-videos muted). Pick 360p to 1080p, or the headset view's full size. The picture comes from SteamVR's built-in headset
-view on the Frame and is encoded there while you watch (about one CPU core), so stop it when you're done. It's black
-while the headset sleeps.
-
-## Monitor
-
-The **Monitor** tab shows what the Frame is doing while it's open: the running game with its frame rate against the
-display's refresh rate, CPU, graphics chip, memory, the hottest temperature with the fan speed, power draw and battery
-time left, each with a 2-minute chart. **Show details** adds every CPU core, all temperature sensors, where the power
-goes and the network. Below, the game's processes (or Steam's, or all of them) with their CPU, GPU and memory use:
-right-click one to end it, or end the whole game. Programs that Steam, SteamVR or the desktop need are marked and ask
-again. The Frame sends the numbers itself (about 1 % of one CPU core) and stops when you leave the tab.
+Details for each: [Install and first steps](docs/INSTALL.md).

 ![Monitor](docs/images/monitor.png)

+![Screenshots](docs/images/screenshots.png)
+
+## Quick start
+
+1. [Download](https://github.com/spoopyghosty0/frameport/releases/latest) the build for Windows, macOS (Apple
+   Silicon) or Linux, unpack it and start FramePort.
+2. In FramePort click **Steam Frame → Start setup**. The Frame and your PC must be on the same Wi-Fi (or use a USB
+   cable).
+3. On the Frame open the **SteamVR dashboard → Launch a program → Desktop**, then the app menu → **System →
+   Konsole**, and run:
+
+   ```
+   curl -fsSL https://frameport.app/s | bash
+   ```
+
+4. Click **Allow** in FramePort when it shows the same 4-digit code as the Frame. Steam restarts once; if it asks to
+   install **Lepton** (Valve's Android runtime), confirm it.
+5. **Add games → Scan a folder…** with your games, open one and click **Install on Frame**. Play it from the Frame's
+   Steam library.
+
+Full guide, firewalls and troubleshooting: [Install and first steps](docs/INSTALL.md). How to lay out game folders:
+[FAQ](docs/FAQ.md).
+
 ## 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!
+Tested games use their recipe (the patches and settings that work for them) automatically; for other games FramePort
+suggests patches. See the [list of tested games](docs/GAMES.md). Got a game working? Share its recipe from the game's
+**…** menu: [how](docs/INSTALL.md#share-a-recipe-or-report-a-problem).

-**[List of tested games](docs/GAMES.md)**
+## Compared with other tools

-**Tested something? Share it.** In FramePort open the game → **…** → **Share working config…** (it fills in the
-recipe for you) or **Report a problem…** (attaches a diagnostics zip with personal data removed). Without the app:
-[share a working config](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml) · [report a problem](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml). Shared configs become built-in recipes for everyone.
+FrameDrop and Valve's own tools install an app as it is. FramePort differs in four ways:
+
+- **Free and open source** (GPL-3.0). FrameDrop is free (donationware) without published source.
+- **Quest games that don't run on the Frame as they are** get converted and patched, with a tested recipe for 90+
+  games. The others install the game unchanged.
+- **Windows, macOS and Linux.** FrameDrop is for Windows.
+- **Wi-Fi or a USB cable**, and no **Pair new host** step.
+
+<details>
+<summary>All differences</summary>
+
+| | **FramePort** | **FrameDrop** | **By hand with Valve's tools** |
+|---|---|---|---|
+| Cost and source code | Free, open source (GPL-3.0) | Free (donationware), source not published | Free, from Valve |
+| Runs on | Windows, macOS, Linux | Windows | Depends on the tool |
+| First connection | One line in the Frame's terminal; it turns on Developer Mode itself. No password | Turn on Developer Mode, then **Pair new host** | Turn on Developer Mode and pair, or use Android's debug tool (adb) |
+| Wireless or cable | Wi-Fi, the Frame's hotspot or a USB cable | Same Wi-Fi network | Wi-Fi, or adb |
+| Quest games that don't run as they are | Converted and patched for the Frame | Installed as they are | Installed as they are |
+| Knows which patches a game needs | Tested recipes for 90+ games, updated without an app update | Not stated | No |
+| In the Steam library | Yes, with artwork and tags | As a "Devkit Game" shortcut | As "Devkit Game: &lt;title&gt;"; not with adb |
+| Android apps, Linux apps, Windows programs | All three; Proton (runs Windows programs) is installed for you | All three; install Proton first | Yes; 2D Android apps need an extra file |
+| PC VR games | On your PC; some also on the Frame | Not supported | Not supported |
+| "Install with …" buttons on websites | Yes ([frameport.app](https://frameport.app) links) | Its own | No |
+| A game doesn't start | A launch test reads the logs and suggests a patch | A log viewer | No help |
+| Use the Frame from your PC | Live view, Monitor, Files, Screenshots, Type on Frame | Not stated | No |
+
+</details>
+
+Other tools as described on their own pages, checked 2026-10-09:
+[FrameDrop about](https://framedropvr.com/about) · [how-to](https://framedropvr.com/how-to) ·
+[Valve: loading games on Steam Frame](https://partner.steamgames.com/doc/steamhardware/steamframe/loadgames).
+Out of date? [Report a problem](https://github.com/spoopyghosty0/frameport/issues/new).

 ## Built on

+Most of the work is done by these projects:
 [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) · [AXRB](https://github.com/Android-XR-Bridge/AXRB) (Quest games on a PC,
-experimental) · Mesa (Zink) · [Khronos OpenXR SDK](https://github.com/KhronosGroup/OpenXR-SDK)
+[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).
+What FramePort adds: [Architecture](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 |
-| [GAMES.md](docs/GAMES.md) | Tested games and how well they run |
-| [PLAYBOOK.md](docs/PLAYBOOK.md) | Symptoms and fixes per game |
-| [FRAME_RUNTIME.md](docs/FRAME_RUNTIME.md) | Steam Frame runtime facts |
-| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | How the code is organised |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | Code, recipes, translations |
+| [Install and first steps](docs/INSTALL.md) | Install, connect, update, PC VR games, files, problem reports |
+| [What the setup changes](docs/FRAME_SETUP.md) | What setup changes on the Frame, networks and firewalls, undoing it |
+| [Compatibility](docs/COMPATIBILITY.md) | What runs and how well |
+| [Tested games](docs/GAMES.md) | Tested games and how well they run |
+| [FAQ](docs/FAQ.md) | Game folders and common questions |
+| [Porting playbook](docs/PLAYBOOK.md) | Symptoms and fixes per game |
+| [Steam Frame runtime reference](docs/FRAME_RUNTIME.md) | Facts about the Frame's runtime |
+| [Architecture](docs/ARCHITECTURE.md) | How the code is organized |
+| [Contributing](CONTRIBUTING.md) | Code, recipes, translations |

 ## Development

@@ -144,8 +138,9 @@ 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.
+## AI usage
+
+I don't have much free time for this project, so I use AI tools to debug compatibility problems faster.

 ## License

@@ -24,8 +24,6 @@ FramePort's own native code (the FrameBridge adapter, GL/Vulkan/OpenXR shims, th
 | 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 |
-| AXRB / Android XR Bridge (official installer, only when a Quest game is installed on this PC; run unmodified) | github.com/Android-XR-Bridge/AXRB releases | mixed: launcher GPL-3.0-or-later, host/clock code AXRB Source-Available License 1.0, other parts MIT (AXRB's `LICENSE`) |
-| Android Emulator, platform-tools, build-tools, Android 16 system image (pinned by AXRB) | dl.google.com Android repository | Android SDK License |

 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.
@@ -2,7 +2,7 @@
 e7554c6343ee2989b0a273ee6230e65c25bfe6499eefd00de19f5f0fee58754f  ./arm64-v8a/libfp_langpack.so
 321da502e0f8f46f0880aad39fe6b84bdef88f925164568814cf704a1b31a577  ./arm64-v8a/libfp_ovrp.so
 40defdaddcda53bd2649eb48076fae1622bfc2bfc88e9e03c94fc8b45af2a4f2  ./arm64-v8a/libfp_ovrtrace.so
-7522a7cfb236e48d3442d418c4820cd37760a9627c6bdef80fb0df82df5fd826  ./arm64-v8a/libfp_vk.so
+e8c0965c188665a4e565e4a3af983ef1866d1cf9225665cc90d8df286bc96ef3  ./arm64-v8a/libfp_vk.so
 383054f8b3b41dde76d062c71856cd3163655e50009c08454bc1793f393ead65  ./arm64-v8a/libfpg.so
 5432674a59d02f411cd853a5dc57e3fa547d1ac518f25bf433fc54c43677177a  ./arm64-v8a/libfpglmv.so
 8a8f6b1da8952cb3933a5b53558424a5fc56043b2527a16bb6dd62a00d2de01a  ./arm64-v8a/libframe_xrshim.so
@@ -13,10 +13,10 @@ aa4dc0020c77e12d41ef6ce80b23ad90c9cb7e882338eddf2261efe8645cf38d  ./arm64-v8a/li
 7943c6825e1c2841e54627f96acbd0754a3c06bb608c47f7aa15007aec2191a5  ./armeabi-v7a/libopenxr_loader_generic.so
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 b634ab5640e258563c536e658cad87080553df6f34f62269a21d554844e58bfe  ./hevc/COPYING.FFmpeg
-c1c2a73e269ff765ce6ed74cd19d37d2258a7499873d799c8ee4799575cd56d3  ./hevc/libstagefrighthw.so
-7d0e0677d1dc414766a966a4ad60642364b60829fa8873b51534b17c8e571870  ./hevc/manifest.json
-e4028fccc30132918160c230958aeac616ac6dbf851e6af0c1fe15517b30f2e6  ./hevc/media_codecs_frameport.xml
-66caeda1938934f5bc76d35261641ccee2020015d9932559943749fabd274088  ./hevc/podman.py.txt
+141de01f0d40b97d4f9a720db5ab8ea442f6aa35db5272048899292884994a1c  ./hevc/libstagefrighthw.so
+4516971bbb2b635e19b14d2d37b9353962876f7de02043e7457327052c1fcbc0  ./hevc/manifest.json
+46c3dcad2c43cc30bea3b3680b362ed84a99c15d60714bbbbb422c80ecf90405  ./hevc/media_codecs_frameport.xml
+529ea35d5d82474afe9e09ad1216d269317f56dd24a05fb100fced52b7b4dbca  ./hevc/podman.py.txt
 1aa733117cf57ccff7cf23f0425dbfd73b0332a3ef1c905ceeca0ccd0449c4e0  ./linux-arm64/XR_APILAYER_FRAMEPORT_timefix.json
 28c2430a02bbd8902c5bfb9562c6fd0e318654f9e05c095bfeb94b0450ab1b07  ./linux-arm64/libxr_frameport_timefix.so
 b10b3a5c10c3339fc63fd9f6cb4d01ea29be11a863d0ebad1389ea69fd471940  ./linux-arm64-bin/fp_venc
@@ -1,11 +1,17 @@
 {
+  "revision": 8,
  "runtime_sha256": "456e912c75cd389abcf6a63bc80e2a53bdc334371d00b200c93680388ae955e2",
  "files": {
-    "libstagefrighthw.so": "c1c2a73e269ff765ce6ed74cd19d37d2258a7499873d799c8ee4799575cd56d3",
-    "podman.py": "a55a7d18a5725d5b1f461999dab35c988b283dc885fc0f7a41d2d762911729de",
-    "media_codecs_frameport.xml": "e4028fccc30132918160c230958aeac616ac6dbf851e6af0c1fe15517b30f2e6",
+    "libstagefrighthw.so": "141de01f0d40b97d4f9a720db5ab8ea442f6aa35db5272048899292884994a1c",
+    "podman.py": "529ea35d5d82474afe9e09ad1216d269317f56dd24a05fb100fced52b7b4dbca",
+    "media_codecs_frameport.xml": "46c3dcad2c43cc30bea3b3680b362ed84a99c15d60714bbbbb422c80ecf90405",
    "COPYING.FFmpeg": "b634ab5640e258563c536e658cad87080553df6f34f62269a21d554844e58bfe"
  },
+  "codecs": [
+    "video/hevc",
+    "video/avc",
+    "video/x-vnd.on2.vp9"
+  ],
  "build": {
    "ndk_revision": "27.2.12479018",
    "ffmpeg_source_sha256": "733984395e0dbbe5c046abda2dc49a5544e7e0e1e2366bba849222ae9e3a03b1"
@@ -10,5 +10,23 @@
            <Limit name="bitrate" range="1-245000000" />
            <Limit name="concurrent-instances" max="1" />
        </MediaCodec>
+        <MediaCodec name="OMX.frameport.avc.decoder" type="video/avc" rank="64">
+            <Limit name="size" min="128x128" max="8192x8192" />
+            <Limit name="alignment" value="2x2" />
+            <Limit name="block-size" value="16x16" />
+            <Limit name="block-count" range="1-138240" />
+            <Limit name="blocks-per-second" range="1-7864320" />
+            <Limit name="bitrate" range="1-245000000" />
+            <Limit name="concurrent-instances" max="1" />
+        </MediaCodec>
+        <MediaCodec name="OMX.frameport.vp9.decoder" type="video/x-vnd.on2.vp9" rank="64">
+            <Limit name="size" min="128x128" max="4096x2304" />
+            <Limit name="alignment" value="2x2" />
+            <Limit name="block-size" value="16x16" />
+            <Limit name="block-count" range="1-36864" />
+            <Limit name="blocks-per-second" range="1-2211840" />
+            <Limit name="bitrate" range="1-245000000" />
+            <Limit name="concurrent-instances" max="1" />
+        </MediaCodec>
    </Decoders>
 </MediaCodecs>
@@ -1,8 +1,9 @@
 #!/usr/bin/python3
-"""Add a per-game codec to Lepton's container, without editing its shared rootfs."""
+"""Add shared codecs to Lepton containers without editing their shared rootfs."""
 import hashlib
 import json
 import os
+import re
 import shutil
 import sys
 from pathlib import Path
@@ -18,11 +19,30 @@ def mounts(directory, config, args):
            name = args[i + 1]
        elif arg.startswith("--name="):
            name = arg.partition("=")[2]
-    if name != f"lepton-steamlaunch-{config['appid']}":
-        return []
-    root = Path(config["lepton"]).resolve().parent / "images" / "rootfs"
+    if config.get("scope") == "shared":
+        # The common launcher supplies these values. Do not intercept arbitrary
+        # Podman containers or depend on a game's package/modified APK.
+        appid = os.environ.get("SteamAppId", "")
+        if not re.fullmatch(r"[0-9]+", appid) or name != f"lepton-steamlaunch-{appid}":
+            return []
+        app = Path(os.environ.get("STEAM_COMPAT_INSTALL_PATH", ""))
+        if app.name != "lepton-app" or not app.is_dir():
+            return []
+        root_arg = None
+        for i, arg in enumerate(args):
+            if arg == "--rootfs" and i + 1 < len(args):
+                root_arg = args[i + 1]
+            elif arg.startswith("--rootfs="):
+                root_arg = arg.partition("=")[2]
+        if not root_arg or not root_arg.endswith(":O"):
+            return []
+        root = Path(root_arg[:-2]).resolve()
+    else:  # old per-game deployments remain compatible during migration
+        if name != f"lepton-steamlaunch-{config['appid']}":
+            return []
+        root = Path(config["lepton"]).resolve().parent / "images" / "rootfs"
    expected_root = str(root) + ":O"
-    if not any(arg == expected_root for arg in args):
+    if not any(arg in (expected_root, "--rootfs=" + expected_root) for arg in args):
        return []
    device = Path("/dev/video-dec0")
    runtime = root / "vendor/lib64/libstagefright_softomx.so"
@@ -36,30 +56,53 @@ def mounts(directory, config, args):
            if target == "/vendor/lib64/libstagefright_softomx.so" and fields.get("source"):
                runtime = Path(fields["source"])
    if upstream_plugin:
-        print("FramePort HEVC: using the runtime's hardware codec plugin", file=sys.stderr)
+        print("FramePort video: using the runtime's hardware codec plugin", file=sys.stderr)
        return []
    if not device.exists() or hashlib.sha256(runtime.read_bytes()).hexdigest() != config["runtime_sha256"]:
-        print("FramePort HEVC: device or runtime ABI differs; retaining the stock codecs", file=sys.stderr)
+        print("FramePort video: device or runtime ABI differs; retaining the stock codecs", file=sys.stderr)
        return []
    xml = ET.parse(root / "vendor/etc/media_codecs.xml")
-    ET.SubElement(xml.getroot(), "Include", href="media_codecs_frameport.xml")
-    merged = directory / "media_codecs.xml"
-    temporary = merged.with_suffix(".tmp")
+    if not any(node.get("href") == "media_codecs_frameport.xml" for node in xml.getroot().findall("Include")):
+        ET.SubElement(xml.getroot(), "Include", href="media_codecs_frameport.xml")
+    # Immutable plugin versions can serve simultaneous app launches and
+    # different Lepton installations. Never share a temporary XML filename.
+    # The version directory stays as the agent verified it: the merged list goes to the user's runtime dir.
+    root_key = hashlib.sha256(str(root).encode()).hexdigest()[:16]
+    merged = merged_dir() / f"media_codecs.{root_key}.xml"
+    temporary = merged.with_suffix(f".{os.getpid()}.tmp")
    xml.write(temporary, encoding="utf-8", xml_declaration=True)
    temporary.replace(merged)
    # Lepton supplies its own /dev tmpfs. A Podman --device node disappears
    # beneath it; a bind mount matches Lepton's existing GPU/sound device setup.
    result = ["--mount", f"type=bind,source={device},destination=/dev/video-dec0,rw"]
-    for source, target in (
-        ("libstagefrighthw.so", "/vendor/lib64/libstagefrighthw.so"),
-        ("media_codecs.xml", "/vendor/etc/media_codecs.xml"),
-        ("media_codecs_frameport.xml", "/vendor/etc/media_codecs_frameport.xml"),
+    for path, target in (
+        (directory / "libstagefrighthw.so", "/vendor/lib64/libstagefrighthw.so"),
+        (merged, "/vendor/etc/media_codecs.xml"),
+        (directory / "media_codecs_frameport.xml", "/vendor/etc/media_codecs_frameport.xml"),
    ):
-        result += ["--mount", f"type=bind,source={directory / source},destination={target},ro"]
-    print("FramePort HEVC: loading the Iris hardware codec plugin for this container", file=sys.stderr)
+        if not path.is_file():
+            raise FileNotFoundError(f"missing video codec mount: {path}")
+        result += ["--mount", f"type=bind,source={path},destination={target},ro"]
+    print("FramePort video: loading the Iris hardware codec plugin for this container", file=sys.stderr)
    return result


+def merged_dir():
+    runtime = os.environ.get("XDG_RUNTIME_DIR", "")
+    base = Path(runtime) if runtime and Path(runtime).is_dir() else Path.home() / ".cache"
+    path = base / "frameport-video"
+    path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    return path
+
+
+def switched_off(directory):
+    """FRAMEPORT_NO_HW_VIDEO=1 (e.g. in a game's Steam launch options) or the Frame-wide switch (FramePort's
+    setting; the agent writes video-codec/disabled) leave every container with Android's stock codecs."""
+    if os.environ.get("FRAMEPORT_NO_HW_VIDEO", "") not in ("", "0"):
+        return True
+    return directory.parent.name == "versions" and (directory.parent.parent / "disabled").exists()
+
+
 def real_podman(directory):
    """Find Podman independently of deployment.json, without recursing into this wrapper."""
    own_bin = (directory / "bin").resolve()
@@ -84,16 +127,18 @@ def main():
    directory = Path(__file__).resolve().parent.parent
    args = sys.argv[1:]
    fallback = real_podman(directory)
+    if switched_off(directory):
+        os.execv(fallback, [fallback, *args])
    try:
        config = json.loads((directory / "deployment.json").read_text())
-        podman = Path(config["podman"]).resolve()
+        podman = Path(config.get("podman", fallback)).resolve()
        if podman.parent == (directory / "bin").resolve() or podman == Path(__file__).resolve():
            raise ValueError("configured Podman points to the codec wrapper")
        extra = mounts(directory, config, args)
        launch_args = [args[0], *extra, *args[1:]] if extra else args
        os.execv(str(podman), [str(podman), *launch_args])
    except Exception as exc:  # a codec/configuration failure must never prevent the stock container from starting
-        print(f"FramePort HEVC: retaining stock codecs: {exc}", file=sys.stderr)
+        print(f"FramePort video: retaining stock codecs: {exc}", file=sys.stderr)
    os.execv(fallback, [fallback, *args])


@@ -30,13 +30,13 @@ user_systemd() {

 say "FramePort setup for $(hostname) ($(. /etc/os-release; echo "$NAME $VERSION_ID"))"

-say "Authorizing the FramePort app's key"
+say "Letting FramePort log in"
 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; }
+[[ "$key" == ssh-ed25519\ * ]] || { echo "Couldn't reach FramePort at $PC_URL. Is it 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 "Configuring podman for Lepton"
+say "Setting up Lepton's containers"
 # 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
@@ -117,7 +117,7 @@ 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."
+    say "Done. FramePort on your PC shows this Frame as connected."
    exit 0
 fi

@@ -126,9 +126,8 @@ 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."
+    echo "Couldn't turn it on. Turn it on in Settings → System → Enable Developer Mode, then run this again."
    exit 1
 fi
-echo "Steam restarts to turn it on. That closes the desktop in a few seconds and the Frame returns to its"
-echo "normal view; setup finishes on its own. If Steam asks to install Lepton, confirm it."
-echo "Then return to FramePort on your PC: the Frame appears as connected within a minute."
+echo "Steam restarts and the desktop closes. Confirm Lepton if asked."
+echo "Then check FramePort on your PC."
@@ -0,0 +1,234 @@
+#!/usr/bin/env bash
+# FramePort setup from the project page: the same for every Frame and every PC, nothing to copy from the PC. Run in
+# the Frame's desktop terminal (SteamVR dashboard -> Launch a program -> Desktop, then System -> Konsole):
+#   curl -fsSL https://frameport.app/s | bash
+# with FramePort open on your PC at Steam Frame -> Connect. Options: --pc <address[:port]> (skip the search).
+#
+# What it does:
+#   1. finds FramePort on your network (it announces itself over mDNS while that page is open; else the USB cable's
+#      address and a quick scan of this network)
+#   2. asks it to set up this Frame: FramePort shows the same 4 digits as this terminal, you click Allow there
+#   3. runs FramePort's setup script from your PC, the one the typed line `curl -fsS <pc>/<code> | bash` runs (it
+#      authorizes the app's key, configures podman, turns on Developer Mode, asks for Lepton)
+# Nothing changes on the Frame before you allow it on the PC.
+set -euo pipefail
+say() { printf '\n\033[1;36m==> %s\033[0m\n' "$*"; }
+PORTS="8765 8766 8767"
+USB_PC=10.86.200.234  # the PC's fixed address on the Frame's USB cable network (Developer Mode only)
+
+PC=""
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --pc) PC=${2:-}; shift 2 ;;
+        --pc=*) PC=${1#--pc=}; shift ;;
+        -h|--help) sed -n '2,13p' "$0" 2>/dev/null || true; exit 0 ;;
+        *) shift ;;
+    esac
+done
+for tool in curl python3; do
+    command -v "$tool" >/dev/null || { echo "This needs $tool, which SteamOS normally has. Run the setup command FramePort shows instead."; exit 1; }
+done
+
+# FramePort PCs, one per line: name<TAB>address:port<TAB>words. Stdlib Python: avahi isn't always answering on the
+# Frame, and its firewall only lets mDNS in on port 5353, so this listens there in the group, like avahi does.
+find_pcs() {
+    python3 - "$PORTS" "$USB_PC" <<'PY'
+import json, socket, struct, sys, time, urllib.request
+from concurrent.futures import ThreadPoolExecutor
+PORTS = [int(p) for p in sys.argv[1].split()]
+USB_PC = sys.argv[2]
+SERVICE = "_frameport-pair._tcp.local"
+
+def qname(name):
+    return b"".join(bytes([len(p)]) + p.encode() for p in name.split(".")) + b"\0"
+
+def read_name(d, off):
+    labels, jumped, end = [], False, off
+    while True:
+        n = d[off]
+        if n == 0:
+            off += 1
+            break
+        if n & 0xC0 == 0xC0:
+            ptr = struct.unpack("!H", d[off:off + 2])[0] & 0x3FFF
+            if not jumped:
+                end = off + 2
+            jumped, off = True, ptr
+            continue
+        labels.append(d[off + 1:off + 1 + n].decode(errors="replace"))
+        off += 1 + n
+    return ".".join(labels), (end if jumped else off)
+
+def mdns(seconds=3.0):
+    found, srv, txt, addr = {}, {}, {}, {}
+    try:
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        if hasattr(socket, "SO_REUSEPORT"):
+            try:
+                s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+            except OSError:
+                pass
+        s.bind(("", 5353))
+        s.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, socket.inet_aton("224.0.0.251") + socket.inet_aton("0.0.0.0"))
+        query = struct.pack("!6H", 0, 0, 1, 0, 0, 0) + qname(SERVICE) + struct.pack("!HH", 12, 1)
+        s.sendto(query, ("224.0.0.251", 5353))
+    except OSError:
+        return []
+    end, again = time.time() + seconds, True
+    while time.time() < end:
+        if again and time.time() > end - seconds / 2:
+            s.sendto(query, ("224.0.0.251", 5353))
+            again = False
+        s.settimeout(max(0.05, min(0.5, end - time.time())))
+        try:
+            d, src = s.recvfrom(9000)
+        except socket.timeout:
+            continue
+        try:
+            _, _, qd, an, ns, ar = struct.unpack("!6H", d[:12])
+            off = 12
+            for _ in range(qd):
+                _, off = read_name(d, off)
+                off += 4
+            for _ in range(an + ns + ar):
+                name, off = read_name(d, off)
+                rtype, _, _, rdlen = struct.unpack("!HHIH", d[off:off + 10])
+                off += 10
+                if rtype == 12 and name.lower() == SERVICE:
+                    found.setdefault(read_name(d, off)[0], src[0])
+                elif rtype == 33:
+                    srv[name] = (read_name(d, off + 6)[0], struct.unpack("!H", d[off + 4:off + 6])[0])
+                elif rtype == 16:
+                    items, p = {}, off
+                    while p < off + rdlen:
+                        n = d[p]
+                        k, _, v = d[p + 1:p + 1 + n].decode(errors="replace").partition("=")
+                        items[k] = v
+                        p += 1 + n
+                    txt[name] = items
+                elif rtype == 1 and rdlen == 4:
+                    addr[name] = socket.inet_ntoa(d[off:off + 4])
+                off += rdlen
+        except (IndexError, struct.error, UnicodeError):
+            continue
+    out = []
+    for inst, src in found.items():
+        target, port = srv.get(inst, ("", PORTS[0]))
+        props = txt.get(inst, {})
+        out.append((props.get("pc") or inst.split(".")[0], f"{addr.get(target) or src}:{port}", props.get("words", "")))
+    return out
+
+def ping(host_port):
+    try:
+        with urllib.request.urlopen(f"http://{host_port}/ping", timeout=1.5) as r:
+            info = json.load(r)
+        return (info.get("pc", host_port), host_port, info.get("words", ""))
+    except Exception:
+        return None
+
+def scan():
+    """This network's /24 (and the USB cable's PC address) for a FramePort setup port."""
+    hosts = [f"{USB_PC}:{p}" for p in PORTS]
+    try:
+        out = __import__("subprocess").run(["ip", "-4", "-o", "addr"], capture_output=True, text=True).stdout
+    except OSError:
+        out = ""
+    for line in out.splitlines():
+        parts = line.split()
+        if len(parts) > 3 and parts[1] not in ("lo",) and "/" in parts[3]:
+            mine = parts[3].split("/")[0]
+            base = mine.rsplit(".", 1)[0]
+            hosts += [f"{base}.{i}:{p}" for i in range(1, 255) if f"{base}.{i}" != mine for p in PORTS[:1]]
+    def open_port(hp):
+        h, p = hp.rsplit(":", 1)
+        try:
+            with socket.create_connection((h, int(p)), timeout=0.4):
+                return hp
+        except OSError:
+            return None
+    with ThreadPoolExecutor(64) as ex:
+        live = [hp for hp in ex.map(open_port, hosts) if hp]
+    return [r for r in map(ping, live) if r]
+
+pcs = mdns()
+if not pcs:
+    pcs = scan()
+seen = set()
+for name, hp, words in pcs:
+    key = (name, words) if words else hp  # one PC on several links (home Wi-Fi and the Frame's hotspot): once
+    if key not in seen:
+        seen.add(key)
+        print(f"{name}\t{hp}\t{words}")
+PY
+}
+
+say "FramePort setup for $(hostname)"
+if [[ -n "$PC" ]]; then
+    [[ "$PC" == *:* ]] || PC="$PC:${PORTS%% *}"
+    WORDS=""
+else
+    echo "Looking for FramePort on your network (in FramePort on your PC: Steam Frame → Start setup)..."
+    mapfile -t pcs < <(find_pcs)
+    if [[ ${#pcs[@]} -eq 0 ]]; then
+        echo
+        echo "FramePort wasn't found. Check that:"
+        echo "  - FramePort is open on your PC, at Steam Frame → Start setup"
+        echo "  - the Frame and the PC are on the same Wi-Fi (or connected with a USB cable)"
+        echo "Or run the setup command FramePort shows there (Use the setup command)."
+        exit 1
+    fi
+    pick=0
+    if [[ ${#pcs[@]} -gt 1 ]]; then
+        echo "More than one FramePort is open on this network:"
+        for i in "${!pcs[@]}"; do
+            IFS=$'\t' read -r name hp words <<<"${pcs[$i]}"
+            echo "  $((i + 1))) $name  ($hp)  $words"
+        done
+        # stdin is this script itself (curl | bash): ask on the terminal; without one, take the first
+        if { exec 3</dev/tty; } 2>/dev/null; then
+            read -r -u 3 -p "Which one? [1-${#pcs[@]}] " n
+            exec 3<&-
+            [[ "$n" =~ ^[0-9]+$ && $n -ge 1 && $n -le ${#pcs[@]} ]] || { echo "No such number."; exit 1; }
+            pick=$((n - 1))
+        else
+            echo "No terminal to ask in: using the first. (Choose with --pc <address:port>.)"
+        fi
+    fi
+    IFS=$'\t' read -r name PC WORDS <<<"${pcs[$pick]}"
+    echo "Found FramePort on $name ($PC)${WORDS:+, PC words: $WORDS}"
+fi
+
+nonce=$(python3 -c 'import secrets; print(secrets.token_hex(12))')
+digits=$(python3 -c 'import hashlib, sys; print(f"{int(hashlib.sha256(sys.argv[1].encode()).hexdigest()[:8], 16) % 10000:04d}")' "$nonce")
+tmp=$(mktemp)
+trap 'rm -f "$tmp"' EXIT
+status=$(curl -sS -o "$tmp" -w '%{http_code}' -G --data-urlencode "host=$(hostname)" --data-urlencode "nonce=$nonce" \
+    "http://$PC/hello") || true
+case $status in
+    200) reply=$(cat "$tmp") ;;
+    429) echo "FramePort at $PC already has several setup requests waiting. Allow or deny them there (requests from"
+         echo "setups that ended go away by themselves within a few minutes), then run this again."; exit 1 ;;
+    000|"") echo "FramePort at $PC didn't answer. Is it still open at Steam Frame → Start setup?"; exit 1 ;;
+    *) echo "FramePort at $PC refused the request (HTTP $status). Run this again, or run the setup command FramePort shows."
+       exit 1 ;;
+esac
+id=$(python3 -c 'import json, sys; print(json.loads(sys.argv[1])["id"])' "$reply")
+WORDS=$(python3 -c 'import json, sys; print(json.loads(sys.argv[1]).get("words", ""))' "$reply")
+
+say "FramePort on your PC asks to set up this Frame"
+printf '   Click Allow there if it shows  \033[1;33m%s\033[0m  (PC: %s)\n' "$digits" "${WORDS:-?}"
+code=""
+for _ in $(seq 12); do  # up to about 20 minutes
+    status=$(curl -sS -o "$tmp" -w '%{http_code}' -m 115 "http://$PC/wait?id=$id" || echo 000)
+    case $status in
+        200) code=$(python3 -c 'import json, sys; print(json.load(open(sys.argv[1]))["code"])' "$tmp"); break ;;
+        202) continue ;;
+        403) echo "Not allowed on the PC. Nothing was changed on this Frame."; exit 1 ;;
+        *) echo "Lost FramePort at $PC (HTTP $status). Run this again, or run the setup command FramePort shows."; exit 1 ;;
+    esac
+done
+[[ -n "$code" ]] || { echo "Not allowed in time. Run this again when you're at your PC."; exit 1; }
+
+say "Allowed. Running the setup from $PC"
+curl -fsS "http://$PC/$code" | bash
@@ -6,10 +6,14 @@ notes: 'Native OpenXR GLES video player. 360 theatres/videos (equirect2 layers,
  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.'
+  scale 0.75; frame.swapchain_limit for its 7680x3840 theatre swapchains. Its hardware decoding mode (Java MediaCodec,
+  Vr4pMediaPlayer; its own FFmpeg is the software path) gets the Frame''s video hardware with frame.hw_video_decode
+  (added 2026-10-09, not yet checked in the headset).'
 tested_version: 2.0.22
 engine: Other
 xr: OpenXR
+frame:
+- frame.hw_video_decode
 adapter:
  equirect_emul: 1
  stable_local: 1
@@ -17,4 +21,6 @@ adapter:
  scale: 0.75
 verified:
  date: '2026-10-01'
+updated: '2026-10-10'
+min_app: 0.12.1
 source_hint: 4XVR Video Player
@@ -0,0 +1,23 @@
+package: com.CortopiaStudios.DTRH
+title: Down the Rabbit Hole
+status: works
+tested_version: 01.04.434
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: ce9e02e9b8fc64dc37bec2bd869d2ed1c4a99f28adffd6b5ec38c87b3cb639f7
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 145
+source_hint: '8430807483680247'
@@ -0,0 +1,22 @@
+package: com.PeanutButton.Retropolis
+title: Retropolis
+status: works
+tested_version: '0.87'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: 4656b980fccd812d8edac15805dcd86c2f44029abdab98c3187699d1fc878f88
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 153
+source_hint: com.PeanutButton.Retropolis
@@ -0,0 +1,22 @@
+package: com.ScytheDevTeam.ContainmentProtocol
+title: Deep Cuts
+status: works
+tested_version: 1.1.3271
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: d8d4bfb0954059c5ed1bcaa0edfb8b18f154ff710049f4808c42cfd8d88ee5a2
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 144
+source_hint: com.ScytheDevTeam.ContainmentProtocol
@@ -0,0 +1,22 @@
+package: com.UNIVRS.Freedom
+title: Freedom
+status: issues
+notes: Volume can't be changed in the game.
+tested_version: 1.0.2950
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: 24662272c4cbe5dc7c4f3c803bdb9dead9661ac3d59bf80cca2e260256acc4bc
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 132
+source_hint: AOT VR
@@ -0,0 +1,22 @@
+package: com.XRGames.ZombielandVR
+title: ZombielandVR
+status: works
+tested_version: 1.7.0
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_text_input
+- frame.vrapi_stub
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: 750067107cd739c80b65516dd1c18219283b2a29b39430bb21ed85d48b9b94ac
+  app: 0.12.1.dev252
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 71
+  issue: 141
+source_hint: ZombielandVR
@@ -1,6 +1,7 @@
 package: com.beatgames.beatsaber.lj369vr
 title: Beat Saber
 status: works
+notes: Purchased DLC isn't detected (ownership comes from Meta's servers).
 tested_version: 1.40.8_7379
 engine: Unity
 xr: OpenXR
@@ -1,6 +1,7 @@
 package: com.beatgames.beatsaber
 title: Beat Saber
 status: works
+notes: Purchased DLC isn't detected (ownership comes from Meta's servers).
 tested_version: 1.40.8_7379
 engine: Unity
 xr: OpenXR
@@ -2,20 +2,25 @@ package: com.camouflaj.manta
 title: 'Batman: Arkham Shadow'
 status: works
 notes: Large data set (~27 GiB) incl. all language packs.
-details: 'Uses Meta XR Audio (Wwise), handled by patch_meta_xr_audio. Includes all language packs (~28 GB). sync_guard
-  (to test, GitHub #102) - a reporter''s game quit to Steam''s waiting screen after the Frame runtime crashed in
-  xrSyncActions (CVRInputLatest::UpdateActionState), the input race Myst had.'
+details: 'Uses Meta XR Audio (Wwise), handled by patch_meta_xr_audio. Cutscenes are 8K HEVC panoramas: frame.hw_video_decode
+  decodes them on the Frame''s hardware, adapter.surface_native shows them in stereo (PRs #96, #128). Includes all
+  language packs (~28 GB). sync_guard (to test, GitHub #102) - a reporter''s game quit to Steam''s waiting screen
+  after the Frame runtime crashed in xrSyncActions (CVRInputLatest::UpdateActionState), the input race Myst had.'
 tested_version: 1.4.1-350961
 engine: Unity
 xr: OpenXR
 overport_extra:
 - patch_disable_space_warp
+frame:
+- frame.hw_video_decode
 adapter:
  sync_guard: 1
+  surface_native: 1
 verified:
  date: '2026-09-28'
  overport_cli: 1.2.3
  overport_runtime: 3.4.3-23204ea
  known_good_sha256: 796d1cab08f614d72c50d9702974c719c0908f5de91183cfe02d1fd5eb09551a
-updated: '2026-10-09'
+updated: '2026-10-10'
+min_app: 0.12.1
 source_hint: Batman- Arkham Shadow
@@ -1,8 +1,8 @@
 package: com.drbeef.doom3quest
 title: Doom3Quest
-status: issues
-notes: 'HUD and PDA show with frame.gl_multiview_fbo (Xandrix1987''s headset test, GitHub 77, no frame-rate drop
-  with the PDA open). Open: the player sometimes switches between walking and running.'
+status: works
+notes: HUD and PDA show with frame.gl_multiview_fbo (Xandrix1987's headset test, GitHub 77, no frame-rate drop with
+  the PDA open). Walking and running can switch when the frame rate drops, which seems to be the game's own behaviour.
 details: Doom3Quest compiles every vertex shader for two views (OVR_multiview) and draws its HUD/PDA into single-view
  framebuffers. Mesa (the Frame's GL) rejects that combination as the spec requires and drops the draw, so they
  stayed black; frame.gl_multiview_fbo draws those passes with a single-view copy of the shader. Xandrix1987's framebuffer.cpp
@@ -0,0 +1,25 @@
+package: com.endspace.quest
+title: End Space
+status: issues
+notes: Controls stop responding after the first mission loads.
+tested_version: 1.0.6.1
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_oculus_check
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: c5eb892311a130686f238e6f61cbdb619324f5c21f8c0641c0fcd49d77369eaf
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 148
+source_hint: com.endspace.quest
@@ -0,0 +1,22 @@
+package: com.forcefieldxr.explorevr
+title: ExploreVR
+status: issues
+notes: The 3D world warps and shifts with head movement (wrong perspective).
+tested_version: 1.2.1
+engine: Unreal
+xr: VrApi
+alt_overport:
+- patch_remove_unreal_force_quit
+frame:
+- frame.nodebug
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: 04576c46a91f4bb851a344c75e022b17a5d2837d054e7323a184b81436cf8019
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 149
+source_hint: com.forcefieldxr.explorevr
@@ -0,0 +1,25 @@
+package: com.fyian.TheThrillOfTheFight
+title: The Thrill Of The Fight
+status: issues
+notes: Right eye doesn't draw the opponent or the referee.
+tested_version: '251113.0'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+- frame.unity_no_overlay_copy
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: af86dfbd6f7d3ab504d1f4f92f4dbc4c0f0cb36e30443b80fa0b91322f481394
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 164
+source_hint: ThrillOfTheFight_Release
@@ -0,0 +1,9 @@
+package: com.golfscope.proputt
+title: GOLF+
+status: unsupported
+notes: Black screen. The game's servers reject the login on this platform (Authentication not supported).
+engine: Unity
+xr: OpenXR
+verified:
+  date: '2026-10-10'
+  issue: 147
@@ -0,0 +1,24 @@
+package: com.harmonixmusic.kata
+title: Audica
+status: works
+tested_version: 1.0.3.4
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_no_msaa
+- frame.unity_oculus_check
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-09'
+  known_good_sha256: bc2c00fe049fd97643a296e622e3a90e08f0bd796ee454b0278525e9d72f8139
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 126
@@ -0,0 +1,21 @@
+package: com.kluge.SynthRiders
+title: SynthRiders
+status: works
+tested_version: 3.6.7a1
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  controller_models: 1
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: fb982ad7617629df50190c98d1de906ac9b41903d782c0ada0087b32fc95a5f1
+  app: 0.12.0
+  overport_cli: 1.2.5
+  issue: 158
+source_hint: com.kluge.SynthRiders
@@ -0,0 +1,21 @@
+package: com.miketeevee.shoresofloci
+title: Shores of Loci
+status: works
+tested_version: '1.2'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: c223a99cc1f1597a477a4677c1390cf744d517bd1e8fa7cf82e20b1baefaba26
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 154
+source_hint: com.miketeevee.shoresofloci
@@ -0,0 +1,21 @@
+package: com.newfoldergames.fruitsalon
+title: Fruit Salon
+status: works
+tested_version: 1.0.2
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: 1c2e6e44e046e1683670a6b0f97e7766fd5edd0c888443910ce3c8e2291a9865
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261006.6173745'
+  agent: 59
+  issue: 165
+source_hint: Fruit Salon
@@ -0,0 +1,23 @@
+package: com.onehamsa.RNXQ
+title: 'Racket: Nx'
+status: works
+tested_version: 2.8.31
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+- frame.unity_gl_shim
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: f78de8051c5808e4244d9fa757050d6c131350112315ad6e01e2b1457f2e2053
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 151
+source_hint: '9030540110323274'
@@ -0,0 +1,23 @@
+package: com.owlchemylabs.vacationsimulator
+title: Vacation Simulator
+status: issues
+notes: Controllers aren't tracked (reported; not yet diagnosed).
+tested_version: 1.3.0.40142
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+  refresh_rate: 90.0
+verified:
+  date: '2026-10-10'
+  known_good_sha256: b02e0a24292a8305ca752fef1884356f0191b53793d356b999cd50bba3fe7a3c
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 163
+source_hint: com.owlchemylabs.vacationsimulator
@@ -0,0 +1,22 @@
+package: com.quaternionsoftware.rcpilottrainer
+title: RC Pilot Trainer
+status: works
+tested_version: 0.7.0.2
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: 1b98f0dea74f058a838ac17299a0e1c67362cb1ecfbc97e4cb2aad3bcbdfb173
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 152
+source_hint: com.quaternionsoftware.rcpilottrainer
@@ -0,0 +1,20 @@
+package: com.rrrgames.CaveCrave
+title: Caves
+status: works
+notes: First cave loads up perfectly, didn't play to unlock other game modes
+tested_version: 1.1.4
+engine: Unity
+xr: OpenXR
+frame:
+- frame.oculusos
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: 9720a9af42590dfdb742f278352583e56f36efbf5d96c56c59ac4b6a615f276e
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 142
+source_hint: com.rrrgames.CaveCrave
@@ -0,0 +1,22 @@
+package: de.erthu.ancientdungeonfull
+title: Ancient_Dungeon
+status: issues
+notes: Multiplayer isn't available (offline).
+tested_version: ea0.1.10.2
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-10'
+  known_good_sha256: 0bcbd6d01d085183df586ee692267341a9ea15d1f52fbc33265601d55c73c2d2
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 143
+source_hint: de.erthu.ancientdungeonfull
@@ -0,0 +1,11 @@
+package: quest.eleven.forfunlabs
+title: Eleven Table Tennis
+status: unsupported
+notes: Stops at the splash screen. The game needs Meta's online services after start, which aren't available on
+  the Frame.
+engine: Unity
+xr: OpenXR
+pcvr_alternative: The PC VR (Rift) version works on the Frame through FramePort.
+verified:
+  date: '2026-10-10'
+  issue: 160
@@ -1,4 +1,4 @@
-# Log signature -> diagnosis -> suggested fix. Matched against the game's launch.log (Lepton logcat mirror).
+# Log signature -> diagnosis -> suggested patches. Matched against the game's launch.log (Lepton logcat mirror).
 # `pattern` is a Python regex (case-sensitive). `suggest` lists patch ids (+ optional params) the UI offers as
 # "apply and rebuild"; an entry `adapter.<key>=<value>` sets that value (else 1). `severity`: fatal (the game can't
 # run) | error | warning | info. `question`: a symptom only the player sees (play sessions, GUI "Last session"): its
@@ -9,87 +9,87 @@ signatures:
  - id: no-launcher
    pattern: 'APP_ACTIVITY is empty'
    severity: fatal
-    diagnosis: Lepton found no activity with category LAUNCHER.
+    diagnosis: 'Nothing starts: Lepton found no entry point in the app (an activity with category LAUNCHER).'
    suggest: [frame.launcher]
  - id: linux-x86-no-fex
    pattern: '(cannot execute binary file: Exec format error|exec format error)'
    severity: fatal
-    diagnosis: An x86_64 Linux program was started directly; the Frame's arm64 CPU needs FEX (x86 translation) for it. Reinstall the app with FramePort 0.12 or newer, which installs FEX and starts the program through it.
+    diagnosis: This x86_64 Linux program was started without the translator it needs. The Frame's arm64 CPU runs it only through FEX; reinstall the app with FramePort 0.12 or newer, which installs FEX and starts the program through it.
    suggest: []
  - id: no-arm64
    pattern: 'INSTALL_FAILED_NO_MATCHING_ABIS'
    severity: fatal
-    diagnosis: 32-bit-only APK. The Steam Frame has no AArch32; this cannot run. Use the PC (Rift) version via Revive.
+    diagnosis: This game is 32-bit only and can't run on the Frame (no AArch32). Use the PC (Rift) version through Revive.
    suggest: []
  - id: android-too-new
    pattern: '(NoClassDefFoundError|ClassNotFoundException|NoSuchMethodError)\b.*(Landroid/window/|android\.window\.|(storeStoreFence|loadLoadFence)\(\)V in class Ljava/lang/invoke/VarHandle)'
    severity: fatal
-    diagnosis: The app calls Android 12/13+ classes (android.window.*, VarHandle fences) that the Frame's Android 11 (API 30) container doesn't have; it needs a newer Android (e.g. minSdk 34 apps). Nothing to patch - it can't run until Valve updates the Frame's Android.
+    diagnosis: The game needs a newer Android than the Frame has, so it can't run yet. It calls Android 12/13+ classes (android.window.*, VarHandle fences) that the Frame's Android 11 (API 30) container lacks (for example minSdk 34 apps); nothing to patch until Valve updates Lepton's Android.
    suggest: []
  - id: web-wrapper
    pattern: '(Creating TwaLauncher for com\.oculus\.browser|NameNotFoundException:? com\.oculus\.browser)'
    severity: fatal
-    diagnosis: The app is a website in an Android wrapper (Trusted Web Activity) that opens Meta's browser (com.oculus.browser), which the Frame doesn't have, so nothing opens. There's no game to port - open the website (TWALauncherActivity's "Using URL" line) in a browser instead.
+    diagnosis: This app is a website, not a game, and it can't open on the Frame. It is a Trusted Web Activity that opens Meta's browser (com.oculus.browser), which the Frame doesn't have; open the website (TWALauncherActivity's "Using URL" line) in a browser instead.
    suggest: []
  - id: unity-render-crash
    pattern: 'CRASH\s*:.*#\d+\s+pc [0-9a-f]+\s+\S*libgallium_dri\.so'
    severity: fatal
-    diagnosis: Unity's render thread crashed inside the Frame's GL driver (Mesa/Zink); the picture freezes or stays grey. Known triggers - an OVROverlay copy (try "Unity - skip OVROverlay layers", e.g. The Room VR), MSAA switched on at runtime, a GPU hang (zink DEVICE LOST).
+    diagnosis: 'The game''s graphics crashed, so the picture freezes or stays gray. Unity''s render thread crashed in the Frame''s GL driver (Mesa/Zink); known triggers are an OVROverlay copy (try "Unity: skip OVROverlay layers", for example The Room VR), MSAA switched on at runtime and a GPU hang (zink DEVICE LOST).'
    suggest: [frame.unity_no_overlay_copy, frame.unity_runtime_msaa_off]
  - id: unreal-msrtt-crash
    pattern: 'fault addr 0x10000 in tid \d+ \((RHIThread|RenderThread)|libgallium_dri\.so \(find_rp_state'
    severity: fatal
-    diagnosis: The game's render thread jumped to address 0x10000 inside the Frame's GL driver (Mesa/Zink) a few seconds after start. Zink looks up a render-pass cache slot past its end when a game renders through multisampled render-to-texture (Unreal's mobile MSAA, e.g. Star Wars Pinball VR). Load the GL shim, which hides that extension.
+    diagnosis: The game's graphics crashed a few seconds after start. Its render thread jumped to address 0x10000 in the Frame's GL driver (Mesa/Zink), which reads past a render-pass cache when a game uses multisampled render-to-texture (Unreal's mobile MSAA, for example Star Wars Pinball VR); the GL shim hides that extension.
    suggest: [frame.unreal_gl_shim, frame.unity_gl_shim]
  - id: pac-unpaired
    pattern: 'ILL_ILLOPN\), fault addr 0x[0-9a-f]+ \(\*pc=0xd50323bf\)'
    severity: fatal
-    diagnosis: The game crashed on a return-address check (autiasp) its code never signed. The Quest's CPU ignores these checks, the Steam Frame's enforces them; some OpenSSL assembly in game engines has such unpaired checks (e.g. Star Wars Pinball VR on its first network connection, thread HttpManager).
+    diagnosis: The game crashed on a CPU check the Quest ignores but the Frame enforces. Its code checks a return address (autiasp) it never signed; some OpenSSL assembly in game engines does this (for example Star Wars Pinball VR on its first network connection, thread HttpManager).
    suggest: [frame.pac_hints]
  - id: cube-swapchain-refused
    pattern: 'xrCreateSwapchain \d+x\d+ .*faces=6 .*result=-\d+'
    unless: 'cube_standin: runtime refused'
    severity: fatal
-    diagnosis: The game asked for a cube-map swapchain (e.g. an OVROverlay skybox or loading cube), which the Frame's runtime doesn't have. OVRPlugin goes on without images and crashes in ovrp_EndFrame4 (Unity's render thread SIGSEGV in memset, e.g. Budget Cuts Ultimate). FrameBridge from FramePort 0.12 serves such swapchains itself and drops their cube layers (cube_standin, GLES games) - rebuild and reinstall the game.
+    diagnosis: The game asked for a cube-map swapchain (for example an OVROverlay skybox or loading cube), which the Frame's runtime doesn't have. OVRPlugin goes on without images and crashes in ovrp_EndFrame4 (Unity's render thread SIGSEGV in memset, for example Budget Cuts Ultimate). FrameBridge from FramePort 0.12 serves such swapchains itself and drops their cube layers (cube_standin, GLES games) - rebuild and reinstall the game.
    suggest: [frame.adapter]
    supersedes: [unity-render-crash, native-crash]
  - id: swapchain-rect-invalid
    pattern: 'xrEndFrame failed -25\b'
    severity: fatal
-    diagnosis: The runtime rejects the game's frames because an image rect reaches past its swapchain (by a few pixels on some Frames); the game stops drawing (e.g. stuck at a "Waiting" box). FrameBridge from FramePort 0.11.0 clamps the rects - rebuild and reinstall the game.
+    diagnosis: The runtime rejects the game's frames, so it stops drawing (for example stuck at a "Waiting" box). An image rect reaches a few pixels past its swapchain on some Frames; FrameBridge from FramePort 0.11.0 clamps the rects, so rebuild and reinstall the game.
    suggest: [frame.adapter]
  - id: missing-ovr-symbol
    pattern: '(UnsatisfiedLinkError|cannot locate symbol) .*"?(ovr_[A-Za-z0-9_]+|ovr[A-Z][A-Za-z0-9]*_ToString)'
    severity: fatal
-    diagnosis: The game imports Meta platform functions overport's loader lacks.
+    diagnosis: The game can't load because OVRPort's platform loader lacks Meta platform functions it uses.
    suggest: [frame.ovrstubs, frame.ovrplatformcompat]
  - id: oculus-os-class
    pattern: '(ClassNotFoundException|NoClassDefFoundError).*com[./]oculus[./]os[./](AnalyticsEvent|UnifiedTelemetryLogger)'
    severity: fatal
-    diagnosis: Quest-only telemetry class lookup aborts the app (Meta XR Audio / native telemetry).
+    diagnosis: The game looks up a Quest-only system class and aborts. The lookup comes from Quest telemetry (Meta XR Audio or native code).
    suggest: [frame.metaxr_telemetry, frame.oculusos]
  - id: checkjni-abort
    pattern: 'JNI DETECTED ERROR IN APPLICATION|GetStringUTFChars.*NULL|CheckJNI'
    severity: fatal
-    diagnosis: CheckJNI (on because the app is debuggable) aborts on sloppy JNI usage.
+    diagnosis: Android's debug checks stopped the game. CheckJNI is on because the converted app is debuggable, and it aborts on sloppy JNI use.
    suggest: [frame.nodebug]
  - id: force-quit
    pattern: 'System\.exit|ForceQuit|FAndroidMisc::RequestExit'
    severity: error
-    diagnosis: The game quit itself right after starting (Unreal ForceQuit after a failed platform check).
+    diagnosis: The game quit itself right after starting. Usually Unreal's ForceQuit after a failed Quest platform check; the alternate build leaves it out.
    suggest: [patch_remove_unreal_force_quit]
    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).
+    diagnosis: The Frame rejected the game's image format. GLES games must use sRGB formats without MSAA.
    suggest: [adapter.swapchain_fix]
  - id: zink-shader-fix-mismatch
    pattern: 'shader fix layer: a \d+-byte module differs from fix'
    severity: warning
    diagnosis: The game's OpenGL ES shader fix (zink_shader_fix) no longer matches the shader the Frame's GL driver (Zink)
-      builds - a Frame or Lepton update changed the driver's output - so the shader it fixes (e.g. Vader Immortal's
+      builds - a Frame or Lepton update changed the driver's output - so the shader it fixes (for example Vader Immortal's
      lightspeed jump) may hang the GPU again. Capture the new modules with zink_shader_dump=1 (files/fp_spirv/ in the
      game's storage) and update the fix.
    suggest: [adapter.zink_shader_dump]
@@ -97,85 +97,77 @@ signatures:
    pattern: 'shader fix layer: NOT active'
    severity: warning
    diagnosis: FramePort's shader-fix Vulkan layer couldn't add itself to the game's Vulkan layers (Android's
-      GraphicsEnv functions it uses were not found or behaved differently, e.g. after a Lepton update), so the game's
+      GraphicsEnv functions it uses were not found or behaved differently, for example after a Lepton update), so the game's
      OpenGL ES shader fixes (zink_shader_fix) don't apply.
    suggest: []
  - id: zink-device-lost
    pattern: 'zink.*DEVICE[_ ]LOST|VK_ERROR_DEVICE_LOST'
    severity: fatal
-    diagnosis: The GPU hung (Zink/Mesa). For GLES Unity games MSAA render-to-texture is the usual cause; at one effect
-      only, a shader reading undefined loop counters (e.g. Vader Immortal's lightspeed jump - frame.zink_shader_fix).
+    diagnosis: The GPU hung, so the game froze or closed. For GLES Unity games (Zink/Mesa) MSAA render-to-texture is the usual cause; at one effect only, a shader reading undefined loop counters (for example Vader Immortal's lightspeed jump, patch frame.zink_shader_fix).
    suggest: [frame.unity_no_msaa, frame.unity_runtime_msaa_off]
  - id: gpu-hang
    pattern: 'kernel: .*(?i:hangcheck|gpu fault|msm_drm.*(hang|recover)|kgsl.*(hang|fault)|adreno.*(hang|fault))'
    severity: fatal
    diagnosis: The Frame's GPU hung while the game ran (the kernel reset it; the game froze or closed). Usually one
-      shader or effect the Frame's driver can't handle (e.g. Vader Immortal's lightspeed jump). FramePort can't fix
-      that on its own; capture the game's shaders (OpenGL ES games) and send a problem report with diagnostics, so a
-      shader fix can be added for this game.
-    suggest: [adapter.zink_shader_dump]
+      shader or effect the Frame's driver can't handle (for example Vader Immortal's lightspeed jump, a VR4 cutscene).
+      FramePort can't fix that on its own; capture the game's shaders (the shader dump), play to the hang once more and
+      send a problem report with diagnostics, so a shader fix can be added for this game.
+    # triage keeps only the dump for the graphics API the session used (FrameBridge's swapchain formats)
+    suggest: [adapter.vk_shader_dump, adapter.zink_shader_dump]
    report: true
  - id: space-warp-used
    pattern: 'xrCreateSwapchain \d+x\d+ format=(97|129) '
    unless: 'per-game: hide_space_warp=1'
    severity: info
    diagnosis: The game uses Meta's space warp (it renders half of its frames plus motion vectors, and the runtime makes
-      up the rest). On the Frame that can make textures flicker, jump or smear while you move (e.g. Into The Radius 2,
+      up the rest). On the Frame that can make textures flicker, jump or smear while you move (for example Into The Radius 2,
      Metro Awakening). Turning it off makes the game render every frame itself.
    question: Did textures flicker, jump or smear while you moved?
    suggest: [adapter.hide_space_warp]
  - id: unity-runtime-msaa
    pattern: 'recommended MSAA level is [248]\. Switching to the recommended level'
    severity: info
-    diagnosis: The game's OVRManager turns MSAA on at runtime (QualitySettings can't keep it off). On GLES this can
-      hang the Frame's GPU or restart the headset; if it does, keep it off in the game's code.
+    diagnosis: The game turns MSAA on at runtime, which can hang the Frame's GPU. Its OVRManager does this past QualitySettings; if the game hangs or the Frame restarts, keep it off in the game's code.
    suggest: [frame.unity_runtime_msaa_off]
  - id: runtime-input-crash
    pattern: 'vrclient\.so[^\n]*(UpdateActionStateInternal|sxr_xrSyncActions)'
    severity: fatal
-    diagnosis: The Frame's runtime crashed in its controller-input code (xrSyncActions), typically right after the game
-      got focus. sync_guard serialises input syncs and pauses them briefly after focus returns.
+    diagnosis: The Frame's runtime crashed in its controller code, usually right after the game got focus. sync_guard runs input syncs (xrSyncActions) one at a time and pauses them briefly after focus returns.
    suggest: [adapter.sync_guard]
  - id: focus-dip-teleport
    pattern: 'OnVRPresence[^\n]*Teleport'
    severity: warning
-    diagnosis: The game moves the player when the headset reports presence again, which the Frame's brief focus dips
-      trigger (the view jumps). focus_hold hides dips under 600 ms.
+    diagnosis: The view jumps because the game moves the player after the Frame's brief focus dips. The game reacts to the headset reporting presence again; focus_hold hides short dips.
    suggest: [adapter.focus_hold]
  - id: unity-vr-device-none
    pattern: 'NewtonVR.*(not setup properly|no headset found)|Loaded VR device: None|XR: Oculus could not be loaded'
    severity: fatal
-    diagnosis: Unity didn't start its Oculus VR device (older Unity checks for Meta's system apps first), so the game
-      runs as a hidden 2D app.
+    diagnosis: Unity didn't start VR, so the game runs as a hidden 2D app. Older Unity checks for Meta's system apps before it starts its Oculus VR device.
    suggest: [frame.unity_oculus_check]
  - id: unity-frame-not-begun
    pattern: 'frame loop shim: frame \d+: the last waited frame wasn.t begun'
    severity: info
-    diagnosis: Unity skipped beginning a frame (typically while it activates a scene); FramePort's frame wait didn't
-      wait for that frame instead of blocking the game. A few at each scene load are normal.
+    diagnosis: Unity skipped beginning a frame, and FramePort's frame wait moved on instead of blocking the game. This happens while a scene loads; a few at each scene load are normal.
    suggest: []
  - id: sdl-no-clipboard
    pattern: 'ClipboardManager\.addPrimaryClipChangedListener|SDLClipboardHandler\.<init>'
    severity: fatal
-    diagnosis: An SDL app (SDL2 / LÖVE) crashed at start because Lepton's Android has no clipboard service.
+    diagnosis: The app crashed at start because the Frame's Android has no clipboard. SDL apps (SDL2 / LÖVE) need Android's clipboard service, which Lepton lacks.
    suggest: [frame.sdl_clipboard]
  - id: controller-profile-rejected
    pattern: 'PATH_UNSUPPORTED.*xrSuggestInteractionProfileBindings|xrSuggestInteractionProfileBindings.*(-48|PATH_UNSUPPORTED)'
    severity: info
-    diagnosis: The runtime rejected controller bindings for a profile it doesn't know (Meta's Touch Plus/Pro). Usually
-      harmless (Meta's OVRPlugin suggests plain Touch too); a game that suggests only these gets them again as Touch
-      (profile_remap, on by default; log "controller profile ... -> oculus/touch_controller").
+    diagnosis: 'Usually harmless: the runtime rejected bindings for controllers it doesn''t know (Meta''s Touch Plus/Pro). OVRPlugin games suggest plain Touch too; a game that suggests only these gets them again as Touch (profile_remap, on by default; log "controller profile ... -> oculus/touch_controller").'
    suggest: []
  - id: input-call-failed
    pattern: 'input_diag: unsupported: (xrStringToPath|xrCreateAction|xrAttachSessionActionSets|xrSyncActions) ->'
    severity: warning
-    diagnosis: The runtime refused one of the game's controller-input calls (logged by input_diag; the line names the
-      call, the result and the argument), so controls set up through it don't work.
+    diagnosis: 'Some controls may not work: the runtime refused one of the game''s controller-input calls. input_diag logged it; the line names the call, the result and the argument.'
    suggest: []
  - id: gl-shader-failed
    pattern: 'GLShim\s*: SHADER COMPILE FAILED|#extension directive is not allowed in the middle|could not implicitly convert operands'
    severity: error
-    diagnosis: Shaders written for Quest drivers fail on Mesa (GLSL strictness).
+    diagnosis: The game's shaders don't compile on the Frame, so parts of the picture are missing. Shaders written for Quest drivers fail on Mesa's stricter GLSL.
    suggest: [frame.gl_shim]
  - id: gl-multiview-twin-failed
    pattern: 'GLMV\s*: twin of program \d+(: stage| failed)'
@@ -187,216 +179,207 @@ signatures:
  - id: vrapi-unsupported-layer
    pattern: 'OVRPortVrApi.*Unsupported VrApi layer type (\d+)'
    severity: error
-    diagnosis: The game submits a VrApi layer type the bridge can't show; whole frames are dropped (black screen).
+    diagnosis: The screen stays black because the game submits a layer the VrApi bridge can't show. Whole frames with that VrApi layer type are dropped.
    suggest: []
  - id: graphics-requirements-missing
    pattern: '(XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING|Failed to create XR session: -50\b|xrCreateSession[^\n]*-50\b)'
    severity: fatal
-    diagnosis: The game creates its OpenXR session without asking for the graphics requirements first; Meta's runtime
-      allows that, the Frame's doesn't (e.g. Lambda1VR). Current FrameBridge builds ask on the game's behalf and retry -
-      rebuild the game.
+    diagnosis: The game can't start VR on the Frame; rebuild it with the current FramePort. It creates its OpenXR session without asking for the graphics requirements first, which Meta's runtime allows and the Frame's doesn't (for example Lambda1VR); current FrameBridge builds ask on the game's behalf and retry.
    suggest: [frame.adapter]
    supersedes: [native-crash]
  - id: avatar-driver-missing
    pattern: 'OVRAvatar-Loader: DisplayErrorAndExit'
    severity: fatal
-    diagnosis: Meta's avatar library can't find its driver (it needs Meta's Horizon app) and stops the game (e.g.
-      BlazeRush). Replace it with a do-nothing library; the game runs without Meta avatars.
+    diagnosis: Meta's avatar library stopped the game because it needs Meta's Horizon app. A do-nothing stand-in lets the game run without Meta avatars (for example BlazeRush).
    suggest: [frame.avatar_stub]
    supersedes: [native-crash, java-crash]
  - id: vrapi-symbol-missing
    pattern: 'cannot locate symbol "vrapi_\w+"'
    severity: fatal
-    diagnosis: The game needs a VrApi function its libvrapi.so doesn't have (e.g. BlazeRush before the bridge gained
-      vrapi_PollEvent). Rebuild with the current FramePort; if it persists, report the function name.
+    diagnosis: The game needs a VrApi function the VrApi bridge doesn't have. Rebuild with the current FramePort; if it persists, report the function name (for example BlazeRush before the bridge gained vrapi_PollEvent).
    suggest: []
    supersedes: [native-crash, java-crash, dlopen-failed]
  - id: vrapi-before-init
    pattern: 'VrApiLoader: vrapi_\w+ was called before vrapi_Initialize'
    severity: fatal
-    diagnosis: Meta's VrApi loader stopped the game. Its OVRPlugin runs on OpenXR but still calls a VrApi function
-      without starting VrApi (e.g. Jurassic World Aftermath); the VrApi bridge can't stand in for this loader.
+    diagnosis: Meta's VrApi loader stopped the game. Its OVRPlugin runs on OpenXR but still calls a VrApi function without starting VrApi (for example Jurassic World Aftermath); the VrApi bridge can't stand in for this loader.
    suggest: [frame.vrapi_stub]
    supersedes: [direct-vrapi, native-crash]
  - id: direct-vrapi
    pattern: '(?<!called before )vrapi_Initialize|VrApi.*not supported|libvrapi\.so.*(not found|failed)'
    severity: warning
-    diagnosis: The engine talks to VrApi directly; it needs the VrApi bridge.
+    diagnosis: The game uses Meta's VrApi directly and needs the VrApi bridge.
    suggest: [frame.vrapi_bridge]
  - id: passthrough-missing
    pattern: 'XR_FB_passthrough.*(not supported|UNSUPPORTED|missing)|XR_ERROR_EXTENSION_NOT_PRESENT.*passthrough'
    severity: error
-    diagnosis: The game needs Meta passthrough; the adapter emulates it.
+    diagnosis: The game needs Meta passthrough (the camera view), which the Frame lacks; 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.
+    diagnosis: The game shows Quest controllers (or none) because the Frame doesn't provide controller models. It asks for them through XR_FB_render_model; the adapter can serve the Frame's own controller models 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).
+    diagnosis: Frame controller models are on, but the converted models are missing from the game's files. 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
    # not OVRPlugin's routine "Unavailable OpenXR extension: XR_FB_scene" (printed by every OVRPlugin game)
    pattern: '(?<!Unavailable OpenXR extension: )XR_FB_scene|XR_FB_spatial_entity.*(not supported|UNSUPPORTED)|xrQuerySpacesFB'
    severity: warning
-    diagnosis: The game uses the Meta scene (room) API; enable the adapter's guardian-based room emulation.
+    diagnosis: The game wants Meta's room data (scene API), which the Frame lacks. The adapter can emulate a room from the guardian bounds.
    suggest: [adapter.scene_emul]
  - id: time-conversion
    pattern: 'xrConvert(Timespec)?Time(ToTimespec)?Time(KHR)?.*(-12|FUNCTION_UNSUPPORTED)'
    severity: warning
-    diagnosis: Runtime lacks timespec time conversion (emulated by the current adapter build).
+    diagnosis: The Frame's runtime lacks timespec time conversion; the current adapter build emulates it.
    suggest: [frame.adapter]
  - id: unreal-vulkan-driver-crash
    pattern: '#00 pc [^\n]*/vulkan\.freedreno\.so[\s\S]{0,3000}?lib(Unreal|UE4)\.so'
    severity: fatal
-    diagnosis: The Frame's Vulkan driver crashed on a call from Unreal. Unreal 5 passes things Quest's driver ignores - a depth resolve in a subpass without a depth attachment (fixed by the Vulkan shim), image barriers and image views for a missing image when it expects fragment density maps (foveation) from the headset (e.g. Metro Awakening).
+    diagnosis: 'The Frame''s Vulkan driver crashed on a call from Unreal. Unreal 5 passes things Quest''s driver ignores: a depth resolve in a subpass without a depth attachment (handled by the Vulkan shim), and image barriers and views for a missing image when it expects fragment density maps (foveation) from the headset (for example Metro Awakening).'
    suggest: [frame.vk_sanitize, adapter.vk_spec_fixes, adapter.vk_hide_fdm]
    supersedes: [native-crash]
  - id: unreal-fdm-missing
    pattern: 'vk shim: left out \d+ image barrier\(s\) without an image \(first: layout \d+ -> 1000218000'
    unless: 'vk shim: fragment density map extensions hidden'
    severity: warning
-    diagnosis: Unreal expects fragment density maps (foveation) from the headset, which the Frame doesn't provide; its image views for them crash the Frame's driver a few seconds later (e.g. Metro Awakening).
+    diagnosis: 'The game will likely crash a few seconds in: Unreal expects foveation data the Frame doesn''t provide. Its image views for the missing fragment density maps crash the Frame''s driver (for example Metro Awakening).'
    suggest: [adapter.vk_hide_fdm]
  - id: fossilize-renderpass
    pattern: '#0\d pc [^\n]*libVkLayer_fossilize\.so[\s\S]{0,4000}?FVulkanRenderPass::FVulkanRenderPass'
    severity: fatal
-    diagnosis: Lepton's Fossilize layer crashed while recording a render pass (the engine leaves an attachment reference's pNext uninitialized).
+    diagnosis: A Vulkan layer in Lepton (Fossilize) crashed while the game set up its graphics. The engine leaves an attachment reference's pNext uninitialized, and Fossilize follows it while recording a render pass.
    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.
+    diagnosis: The game's 360° pictures (for example a video player's theater or 360° videos) are missing because the Frame's runtime can't show equirect layers. GLES games can get them back through the adapter.
    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.
+    diagnosis: The 360° layer emulation switched itself off for this session, so 360° pictures are missing. No shared GLES context, or drawing failed; 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).
+    diagnosis: The game crashed creating a very large image (over 4096 px, for example in video players). OVRPort's OpenXR dispatcher aborts on such swapchains.
    suggest: [frame.swapchain_limit]
    supersedes: [native-crash]
  - id: ovr-microphone-crash
    pattern: 'ovr_Microphone_GetOutputBufferMaxSize\+'
    severity: fatal
-    diagnosis: The game asked OVRPort's Meta platform library for the microphone buffer size before starting the
-      microphone, and the library read the not-yet-opened audio stream (SIGSEGV in libaaudio.so, e.g. Unreal's Oculus
-      voice chat a few seconds after the logo).
+    diagnosis: The game crashed while setting up the microphone (for example Unreal's Oculus voice chat a few seconds after the logo). It asks OVRPort's Meta platform library for the microphone buffer size before starting the microphone, and the library reads the not-yet-opened audio stream (SIGSEGV in libaaudio.so).
    suggest: [frame.ovr_microphone]
    supersedes: [native-crash]
  - id: slz-vulkan-hook-crash
    pattern: 'SLZ Graphics plugin loading![\s\S]{0,20000}?E CRASH   : .*pc  0000000000000000'
    severity: fatal
-    diagnosis: Stress Level Zero's graphics plugin (libSLZQuestNative.so) hooks Unity's Vulkan start-up and calls an invalid function there on the Frame (e.g. BONELAB 1.2974); the game crashes or hangs before its first frame.
+    diagnosis: The game's own graphics plugin crashes or hangs it before the first frame (for example BONELAB 1.2974). Stress Level Zero's plugin (libSLZQuestNative.so) hooks Unity's Vulkan start-up and calls an invalid function there on the Frame.
    suggest: [frame.slz_vulkan_hooks]
    supersedes: [java-crash, native-crash]
  - id: vivox-api31
    pattern: 'NoSuchMethodError: No virtual method \w*CommunicationDevice\w*\(.*Landroid/media/AudioManager'
    severity: fatal
-    diagnosis: The game's Vivox voice-chat SDK calls Android 12 audio-routing methods (AudioManager communication devices) without checking the Android version; Lepton runs Android 11, so the app crashes (e.g. Green Hell VR). The patch makes Vivox's audio-route check return early (voice chat keeps the default route).
+    diagnosis: The game's Vivox voice-chat SDK calls Android 12 audio-routing methods (AudioManager communication devices) without checking the Android version; Lepton runs Android 11, so the app crashes (for example Green Hell VR). The patch makes Vivox's audio-route check return early (voice chat keeps the default route).
    suggest: [frame.vivox_audio_route]
    supersedes: [java-crash]
  - id: native-crash
    pattern: 'Fatal signal (\d+) \(SIG[A-Z]+\)'
    severity: fatal
-    diagnosis: Native crash. See the backtrace (#00 pc ...) for the library.
+    diagnosis: The game crashed. The backtrace (#00 pc ...) names the library.
    suggest: []
  - id: java-crash
    pattern: 'FATAL EXCEPTION'
    severity: fatal
-    diagnosis: Java crash. See "Caused by".
+    diagnosis: The game's Java code crashed. See "Caused by" in the log.
    suggest: []
  - id: dlopen-failed
    pattern: 'dlopen failed: (.*)'
    severity: info
-    diagnosis: A native library failed to load. Usually an optional probe (libOVRMrcLib, libovraudio32, …); it only
-      matters when a crash or UnsatisfiedLinkError abort follows.
+    diagnosis: 'Usually harmless: a native library failed to load. Often an optional probe (libOVRMrcLib, libovraudio32, …); it only matters when a crash or UnsatisfiedLinkError follows.'
    suggest: []
  - id: keyring-quota
    pattern: 'create keyring .*Disk quota exceeded'
    severity: fatal
-    diagnosis: The Frame ran out of kernel keys (rootless podman leaks one session keyring per container start). The
-      FramePort agent sets keyring=false in ~/.config/containers/containers.conf; reboot the Frame to free the leaked keys.
+    diagnosis: 'Games can''t start until the Frame restarts: it ran out of kernel keys. Rootless podman leaks one session keyring per container start; the FramePort agent sets keyring=false in ~/.config/containers/containers.conf, and a reboot frees the leaked keys.'
    suggest: []
  - id: container-not-started
    pattern: "is not a running context|OCI runtime error"
    unless: 'Boot complete!'  # Lepton 3.x prints the error while its container is still starting, then boots fine
    severity: fatal
-    diagnosis: The Lepton container failed to start (see the error above it in launch.log).
+    diagnosis: The game's Android container (Lepton) failed to start. See the error above it in launch.log.
+    suggest: []
+  - id: unity-data-missing
+    pattern: 'Unable to open archive file|is corrupted! Remove it and launch unity again|Failed to read data for the AssetBundle'
+    severity: fatal
+    diagnosis: The game can't read its own data files (OBB/data folder) - they are incomplete or from another version of the game than the APK. Copy the whole data folder again from the same install as the APK, add the game again and reinstall.
    suggest: []
  - id: permission-denied-save
    pattern: 'Permission denied.*(Android/data|/sdcard)|EACCES.*Android/data'
    severity: warning
-    diagnosis: The game created folders it can't write (saves break). The FramePort launcher repairs permissions every 2 s.
+    diagnosis: The game can't write some of its folders, so saves may break. The FramePort launcher repairs permissions every 2 s.
    suggest: []
  # ---- PC VR (Oculus Rift games under Revive; on the Frame under Proton). kind: pcvr = only for those logs
  - id: proton-missing-runtime
    kind: pcvr
    pattern: 'needs Steam app \d+ \(runtime\)|_v2-entry-point: (No such file|not found)'
    severity: fatal
-    diagnosis: The Steam Linux Runtime that Proton needs isn't installed on the Frame.
+    diagnosis: Proton can't start because the Steam Linux Runtime it needs isn't installed on the Frame.
    suggest: []
  - id: revive-inject-failed
    kind: pcvr
    pattern: 'Failed to create process'
    severity: fatal
-    diagnosis: Revive's injector could not start the game (wrong exe path, or a 32-bit/64-bit mismatch).
+    diagnosis: 'Revive couldn''t start the game: wrong exe path, or a 32-bit/64-bit mismatch.'
    suggest: []
  - id: oculus-hmd-event
    kind: pcvr
    pattern: 'FramePort oculushmd: could not (create the OculusHMDConnected event|start the command)'
    severity: error
-    diagnosis: FramePort's Oculus detection helper couldn't provide the OculusHMDConnected event (or couldn't start the game). Unreal's Oculus plugin then skips VR silently and the game runs as a flat window.
+    diagnosis: The game runs as a flat window because FramePort's Oculus detection helper failed. It couldn't provide the OculusHMDConnected event (or couldn't start the game), so Unreal's Oculus plugin skips VR silently.
    suggest: [pcvr.oculus_unreal, pcvr.proton_log]
  - id: openxr-no-runtime
    kind: pcvr
    # (not the loader's 'xrCreateInstance failed': Proton's own OpenXR probe fails once and retries on the Frame)
    pattern: 'XR_ERROR_RUNTIME_(UNAVAILABLE|FAILURE)|No OpenXR runtime|OpenXR runtime (is )?not (found|available)|failed to (create|initialize) (the )?OpenXR'
    severity: fatal
-    diagnosis: No OpenXR runtime reached the game. On a PC start SteamVR (or set it as the OpenXR runtime); on the Frame Proton couldn't bridge to the Frame runtime.
+    diagnosis: No VR runtime reached the game. On a PC, start SteamVR (or set it as the OpenXR runtime); on the Frame, Proton couldn't bridge to the Frame's runtime.
    suggest: []
  - id: openxr-missing-ext
    kind: pcvr
    pattern: 'XR_ERROR_EXTENSION_NOT_PRESENT|XR_KHR_D3D11_enable.*(not|unsupported)'
    severity: fatal
-    diagnosis: The OpenXR runtime lacks an extension Revive requires (XR_KHR_D3D11_enable / win32 time conversion).
+    diagnosis: The VR runtime lacks a feature Revive needs (XR_KHR_D3D11_enable or win32 time conversion).
    suggest: [pcvr.xr_timefix, pcvr.revive_openvr]
  - id: openxr-api-version
    kind: pcvr
    pattern: 'LoaderInstance::CreateInstance chained CreateInstance call failed|XR_ERROR_API_VERSION_UNSUPPORTED|Unable to load LibOVRRT DLL'
    severity: fatal
-    diagnosis: Proton's VR setup couldn't create an OpenXR instance (the Frame's SteamVR runtime only accepts OpenXR 1.0 apps; Proton asks for 1.1), so the game got no VR — a flat window, or Revive fails with "Unable to load LibOVRRT DLL".
+    diagnosis: The game got no VR, so it runs as a flat window or Revive fails. Proton asks for OpenXR 1.1 but the Frame's SteamVR runtime only accepts 1.0 apps (Revive then reports "Unable to load LibOVRRT DLL").
    suggest: [pcvr.xr_timefix]
  - id: openxr-time-conversion
    kind: pcvr
    pattern: 'xrConvert(TimespecTimeToTime|TimeToTimespecTime)KHR failed|XR_KHR_convert_timespec_time not available'
    severity: error
-    diagnosis: The OpenXR runtime refused time conversion, which Proton needs for Windows games' performance-counter times.
+    diagnosis: The VR runtime refused a time conversion that Proton needs for Windows games' performance-counter times.
    suggest: [pcvr.xr_timefix]
  - id: delayload-missing
    kind: pcvr
    pattern: '[Ee]xception:? 0xc06d007e|code=c06d007e'
    severity: fatal
-    diagnosis: A DLL the game loads on demand is missing (Windows delay-load error). For Oculus Store games this is usually LibOVRPlatform64_1.dll, the Oculus Platform SDK that the Oculus app installs for the licence check; FramePort doesn't replace it, so such games need the Oculus app (PC mode).
+    diagnosis: A DLL the game needs is missing, so it closes at once. For Oculus Store games this is usually LibOVRPlatform64_1.dll, the Oculus Platform SDK that the Oculus app installs for the license check; FramePort doesn't replace it, so such games need the Oculus app (PC mode).
    suggest: []
    supersedes: [unreal-crash, wine-crash]  # the crash is this missing DLL; don't send the user after other fixes
  - id: oculus-entitlement
    kind: pcvr
    pattern: '(?i)entitlement (check )?fail|ovr_PlatformInitialize.*(fail|error)|ovrPlatformInitialize_(NotEntitled|Uninitialized|PreLoaded|FileInvalid|SignatureInvalid|UnableToVerify)'
    severity: fatal
-    diagnosis: The Oculus Platform SDK entitlement check failed. The game needs the Oculus app running with a license you own (PC mode only).
+    diagnosis: The game's Oculus license check failed. It needs the Oculus app running with a license you own (PC mode only).
    suggest: []
  - id: vcruntime-missing
    kind: pcvr
@@ -408,13 +391,13 @@ signatures:
    kind: pcvr
    pattern: 'DXVK: .*(DEVICE_LOST|Device lost)|VK_ERROR_DEVICE_LOST'
    severity: fatal
-    diagnosis: The GPU driver lost the device while running the game (D3D through DXVK on freedreno).
+    diagnosis: The GPU stopped responding while running the game (D3D through DXVK on freedreno).
    suggest: [pcvr.proton_log]
  - id: unreal-crash
    kind: pcvr
    pattern: 'CrashReportClient|UE4CC-Windows|UECC-Windows|Fatal error!|Unhandled Exception: EXCEPTION'
    severity: fatal
-    diagnosis: The game crashed (Unreal's crash reporter started). See the game log and crash summary in the log. Common causes are that no VR runtime reached the game (Revive off) or a GPU or driver problem under Proton.
+    diagnosis: The game crashed (Unreal's crash reporter started). Common causes are that no VR runtime reached the game (Revive off) or a GPU or driver problem under Proton; see the game log and crash summary in the log.
    suggest: [pcvr.revive, pcvr.proton_log, pcvr.no_crash_reporter]
  - id: unity-vr-init
    kind: pcvr
@@ -433,61 +416,33 @@ signatures:
    kind: pcvr
    pattern: 'Unhandled exception: page fault|wine: Unhandled|Backtrace:'
    severity: error
-    diagnosis: The game crashed under Wine/Proton (set the Proton debug log and check steam-<appid>.log).
+    diagnosis: The game crashed under Wine/Proton. Turn on the Proton debug log and check steam-<appid>.log.
    suggest: [pcvr.proton_log]

  - id: save-folder-permission
    pattern: "(We don't have write permission to|UnauthorizedAccessException: Access to the path \"/(sdcard|storage/emulated/0)/Android/data/)"
    severity: error
-    diagnosis: The game can't write to a folder it created in its storage (e.g. SUPERHOT's cloud/data, mode 1700, which
-      makes it quit at start). FramePort's launcher (agent 41 or newer) gives such folders owner and group write
-      permission before and during every launch (agent 41 or newer; else reinstall the game). A folder the game creates
-      and checks in the same moment on its very first start can't be repaired in time, so start the game again.
+    diagnosis: The game can't write to a folder it created, so it may quit at start (for example SUPERHOT's cloud/data, mode 1700). FramePort's launcher (agent 41 or newer) gives such folders owner and group write permission before and during every launch; reinstall the game to get the new launcher. A folder the game creates and checks in the same moment on its very first start can't be repaired in time, so start the game again.
    suggest: []
  - id: surface-swapchain-emulated
    pattern: 'surface_emul: emulated Android surface swapchain'
    severity: info
-    diagnosis: The game plays a video on a panel through an Android Surface (XR_KHR_android_surface_swapchain), which the
-      Frame's runtime refuses; FrameBridge emulates it (surface_emul) and copies each video frame into the panel.
+    diagnosis: The game plays video on a panel through an Android Surface, which FrameBridge emulates. The Frame's runtime refuses XR_KHR_android_surface_swapchain; surface_emul copies each video frame into the panel.
    suggest: []
  - id: surface-swapchain-failed
    pattern: 'surface_emul: (setup failed|upload failed|EGL context failed|Vulkan upload path unavailable)'
    severity: warning
-    diagnosis: FrameBridge couldn't emulate an Android video panel (XR_KHR_android_surface_swapchain); the panel stays
-      empty, and a game waiting for its intro video may stay black (e.g. I Am Monkey's intro).
+    diagnosis: A video panel stays empty, and a game waiting for its intro video may stay black (for example I Am Monkey's intro). FrameBridge couldn't emulate the Android video panel (XR_KHR_android_surface_swapchain).
    suggest: []
-  # ---- Quest games on this PC (AXRB, docs/PC_ANDROID.md): AXRB's host.err/session.json + guest log
-  - id: axrb-no-headset
-    kind: axrb
-    pattern: 'failed to find D3D11 adapter requested by OpenXR runtime|xrCreateInstance failed: XR_ERROR_RUNTIME_FAILURE'
-    severity: fatal
-    diagnosis: The PC's OpenXR runtime (SteamVR) has no headset to show the game on, so AXRB's bridge couldn't open its VR session. Connect the headset (Steam Link / cable) and let SteamVR show it before starting the game.
-    suggest: []
-  - id: axrb-host-not-ready
-    kind: axrb
-    pattern: 'Host pose server did not become ready|Host failed to start'
-    severity: fatal
-    diagnosis: AXRB's Windows bridge (axrb-host-bridge.exe) didn't start, so the game was never launched. Its reason is in host.err (diagnostics); a missing headset is the usual one.
-    suggest: []
-    report: true
-  - id: axrb-gfxstream-crash
-    kind: axrb
-    pattern: 'vulkan\.ranchu\.so \(gfxstream::vk::'
-    severity: fatal
-    diagnosis: The game crashed inside the Android emulator's Vulkan driver (gfxstream), reached through AXRB's runtime layer (e.g. Pinball FX VR at its first Vulkan allocations). That's AXRB's GPU path, not FramePort's build - report it to AXRB with the diagnostics.
-    suggest: []
-    report: true
-  - id: axrb-translation-crash
-    kind: axrb
-    pattern: 'libndk_translation\.so \(berberis::|DEBUG\s*:.*#00 pc \S+\s+/system/lib64/libndk_translation\.so'
-    severity: fatal
-    diagnosis: The game crashed in Android's ARM translation (libndk_translation), which runs Quest games' arm64 code on the PC's x86 CPU (known for some Unity games, AXRB issue #9). Nothing to patch in the game; AXRB plans another translator.
+  - id: hw-video-decoder-busy
+    pattern: 'Iris \S+ unavailable; keeping Android|Iris \S+ initialization failed \(-1[26]\); using software'
+    severity: info
+    diagnosis: FramePort's hardware video decoder (frame.hw_video_decode) couldn't open a session, because other
+      decoder sessions held the hardware (Steam's own hardware video decoding, SteamVR's link while a game starts);
+      the video was decoded in software instead, which is slow for 4K/8K. Turn off hardware video decoding in Steam's
+      settings, restart Steam, then start the game again.
    suggest: []
 milestones:  # progress markers, in order; the furthest one reached is reported
-  - {id: axrb-host, kind: axrb, pattern: 'AXRB TCP: listening', label: AXRB bridge started}
-  - {id: axrb-runtime, kind: axrb, pattern: 'AXRB\.PoseClient|Got runtime: package: com\.axrb\.openxrruntime', label: AXRB's OpenXR runtime loaded}
-  - {id: axrb-instance, kind: axrb, pattern: 'xrCreateInstance\(\) succeeded|LoaderInstance::CreateInstance succeeded', label: OpenXR instance created}
-  - {id: axrb-frames, kind: axrb, pattern: 'AXRB\.Perf end-frame', label: Submitting frames}
  - {id: pcvr-launch, kind: pcvr, pattern: 'FramePort: launching|Launched injector with', label: Launcher started}
  - {id: pcvr-oculus-hmd, kind: pcvr, pattern: 'FramePort oculushmd: OculusHMDConnected event ready', label: Oculus headset event provided}
  - {id: pcvr-inject, kind: pcvr, pattern: 'Succesfully injected|Successfully injected', label: Revive injected into the game}
@@ -1,20 +1,6 @@
 # Architecture

-```
-            ┌──────── UI (Flet, ui/: app shell + views/) ─────┐   ┌── CLI (cli.py) ──┐
-            └───────────────────────┬─────────────────────────┘   └────────┬─────────┘
-                                    ▼                                      ▼
-                          pipeline.py  (add → suggest → build → install → test)
-      ┌──────────────┬──────────────┼───────────────┬───────────────┬──────────────┐
-  sources/      analysis/      recommend/        build.py        targets/       validate/
-  quest_dump    detect, elf    catalog, engine   overport →      base.Target    static, device,
-  rift_dump     stubgen, rift  (+ catalog/*.yaml) patches(apk) →  frame_lepton   triage (+triage.yaml)
-                                                  apk/sign        pc_revive
-                                    │                │                 │
-                              patches/ registry   tools/ toolchain   frame/ ssh, discovery, pairing
-                              overport, frame/*,  (JRE, overport,    install/installer ──► agent (on Frame)
-                              settings            apksigner)
-```
+![FramePort's modules: the desktop app and the CLI drive pipeline.py (add, suggest, build, install, launch test), which uses sources/, analysis/, recommend/, build.py, targets/ and validate/; builds use patches/ and tools/; targets reach the agent on the Steam Frame through frame/ and install/ over SSH](images/architecture.svg)

 ## Data flow for one game
 1. **Source** (`sources/quest_dump.py`): folder with an APK and optional `<package>/` or `obb/` data.
@@ -23,7 +9,7 @@
 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 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.
+   `ApkWorkspace` → apksigner (with the package's own keystore) → static validation. Optional alternate build (for example
   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,
@@ -33,7 +19,7 @@
   `triage.py` (milestones + signatures → suggested patches) → UI offers "apply suggestions and rebuild".

 ## Extending
- **New fix**: `patches/frame/<name>.py` with a `Patch` subclass (`detect`, `apply`, optional `validate`), plus a
+- **New patch**: `patches/frame/<name>.py` with a `Patch` subclass (`detect`, `apply`, optional `validate`), plus a
  signature in `catalog/triage.yaml` and a PLAYBOOK row. Stages: `overport` | `apk` | `install`.
 - **Upstream fixed a bug we work around**: register an `UpstreamFix` (`patches/upstream.py`) in the workaround's
  module: a probe that finds the fix in OVRPort's output (True / False / None = can't tell). Each build runs the probes
@@ -65,21 +51,19 @@ apart. "Build" = `pipeline.prepare_rift` (checks + Revive). Revive is a portable
  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.
-```
+![Self-update in four steps: check() asks GitHub for the latest release, install_kind() tells a bundle from a source checkout or a wheel, prepare() downloads and verifies the release, apply() swaps it in and restarts](images/self-update.svg)
+
+- `check()`: GitHub releases/latest, cached 6 h → `Update(version, notes = the release body incl. "What's new" from
+  the annotated tag, the asset for this OS, sums, wheel)`.
+- `install_kind()`: **bundle** = the running exe sits in FramePort.exe's folder / FramePort.app / FramePort/FramePort;
+  **source** = a git checkout (`git pull --ff-only` + `uv sync`); **wheel** = uv tool / pipx / pip (reinstalls the
+  release's wheel).
+- `prepare()` (bundle): `<data>/updates/<ver>/`: download → SHA256SUMS.txt check → extract to `staged/` (ditto on
+  macOS) → layout check → on Windows the same Authenticode signer as the running exe → `ready.json`.
+- `apply()`: writes `<data>/updates/apply.{ps1,sh}` and 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 it relaunches FramePort. 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
@@ -106,4 +90,4 @@ FramePort is a front end for other projects; most of the functionality comes fro
 | 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.
+patches in `native/`, the installer agent that runs on the Frame, and the desktop/command-line app.
@@ -1,30 +1,21 @@
 # Compatibility

-The built-in catalog has tested settings for games, each marked as working, working with known issues, or not
-running on the Frame: see the [list of tested games](GAMES.md) (recipes in [catalog/games](../catalog/games)).
-Other games get suggested patches from detection rules; each suggestion states its reason, and every patch can be
-switched on or off under **Customize**: described in plain words, with **Show technical details** for the exact
-effect of each patch.
+FramePort's catalog has a tested recipe (the patches and settings that work) for many games, each marked as working,
+working with issues or not running: see the [list of tested games](GAMES.md). Other games get suggested patches,
+each with its reason. Every patch can be switched on or off under **Customize** on the game's page.

-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.
+Got a game working? [Share its recipe](INSTALL.md#share-a-recipe-or-report-a-problem).

 ![Patches](images/patches.png)

-| Kind of app | On the Steam Frame |
+| Kind of game | 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) |
+| Quest games | Converted to OpenXR (the VR standard the Frame uses) by OVRPort and patched; they run in Lepton, Valve's Android runtime |
+| Other Android VR apps using OpenXR (for example Pico builds) | Converted the same way; the other headset's own features and store services aren't available |
+| Android apps without VR | Installed unchanged and shown as a window in the headset |
+| PC VR games | On the Frame through Proton (experimental), or on your PC and streamed to the Frame: see [PC VR games](INSTALL.md#pc-vr-games) |
+| Can't run | 32-bit-only or x86-only Android apps, apps for Pico's or HTC's own VR system, Android XR apps, and games that check their license through the Oculus app |

-Automated launch tests confirm that a game starts; visuals can only be checked in the headset.
+Automatic launch tests show that a game starts; only the headset shows whether it looks right.

 ![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)
@@ -1,14 +1,14 @@
-# Diagnostics bundles and shared recipes
+# Diagnostics and problem reports

 Two ways users feed results back, both without a GitHub token:

- **Share working config** (game menu, `frameport share-recipe <pkg>`): saves the recipe as a user catalog entry and
+- **Share working recipe…** (game menu, `frameport share-recipe <pkg>`): saves the recipe as a user catalog entry and
  opens a prefilled issue from `.github/ISSUE_TEMPLATE/working-config.yml`. A maintainer checks it and adds the label
  `catalog-accepted`. Then `.github/workflows/catalog-from-issue.yml` runs `scripts/catalog_from_issue.py`, which reads
  only the YAML block, validates it, and writes `catalog/games/<pkg>.yaml`, and the workflow opens a PR.
  - 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
+- **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.
@@ -40,8 +40,19 @@ games/<pkg>/target/          from the Frame (or the PC): launch.sh, settings.con
                             ReviveInjector.txt / steam-<appid>.log / game-log-N.txt (PC VR), files.json (+ missing)
                             (game-log-N.txt: Unreal Saved/Logs + crash summaries, Unity Player.log / Player-prev.log /
                             output_log.txt + crash error.log from the Proton prefix, agent v67)
+games/<pkg>/target/shaders/  shader dumps (agent v72), when the game wrote any:
+    fp_vk_shaders/           adapter vk_shader_dump=1 (Vulkan shim): <size>_<sha256>.spv + index.txt
+    fp_spirv/                adapter zink_shader_dump=1 (OpenGL ES, shader-fix layer under Zink): <size>_<sha256>.spv
 ```
-Each log keeps at most its last 4 MB (2 MB per file from the Frame).
+Each log keeps at most its last 4 MB (2 MB per file from the Frame). Shader dumps, SPIR-V unchanged (compiled game
+shaders, not redacted): Vulkan (agent v74) every module the game's newest run (the last `# start` in `index.txt`)
+created, last used first, each up to 4 MB and up to 30 MB in all, with that run's index lines, so a module created
+well before a GPU hang comes along too (if the zip would pass 24 MB, the least recently used ones are left out
+after the logs were cut); OpenGL ES (no index): the newest modules (by time written) up to 4 MB.
+`index.txt` (Vulkan) lists every vkCreateShaderModule as
+`<seq> <ms since the first module> <unix ms> <size>_<sha256>.spv new|known|again|failed`; match the unix time with
+the kernel's `hangcheck detected gpu lockup` line (this-boot-kernel.txt). All modules stay in the game's storage on
+the Frame (`Android/data/<pkg>/files/fp_vk_shaders/`, Files tab → the game's storage).

 ## Redaction
 `diag/redact.py` runs on every file and on the issue text.
@@ -49,14 +60,14 @@ Each log keeps at most its last 4 MB (2 MB per file from the Frame).
  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
+  email 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`.
+2. Match the findings and log lines against `docs/PLAYBOOK.md` (symptom → cause → 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.
@@ -1,11 +1,11 @@
 # FAQ

-## How should I lay out a game that has OBB files (an APK plus a data folder)?
+## How should I lay out a game that has OBB files?

-Give every game its own folder, put the APK in it, and put the game's data next to the APK in a folder named
-after the game's **package name** (the name the `.obb` files contain, e.g. `com.Armature.VR4`):
+Some Quest games come as an APK (the app file) plus `.obb` files (the game's data). Give every game its own folder,
+put the APK in it and put the data in a folder named after the game's **package name** (for example `com.Armature.VR4`):

-```
+```tree
 Games/                                  ← scan this folder (Add games → Scan a folder)
 ├── Resident Evil 4/                    ← one folder per game (any name)
 │   ├── VR4.apk                         ← the APK (any file name)
@@ -16,16 +16,12 @@ Games/                                  ← scan this folder (Add games → Scan
    └── com.beatgames.beatsaber.apk     ← games without OBBs: just the APK
 ```

- **Data folder name:** the package name (`com.Armature.VR4` above), or `obb`. FramePort uses the first of the two
-  that exists and isn't empty.
- **Everything in that folder is copied** to the game's `Android/obb/<package>/` on the Frame, subfolders included.
-  So games that ship raw data files instead of `.obb` files work the same way.
- **One game per folder.** Several APKs in one folder count as one game; FramePort uses the first and keeps the others
-  as alternates.
+- **Data folder name:** the package name (`com.Armature.VR4` above) or `obb`.
+- **Everything in that folder is copied** to the Steam Frame, subfolders included, so other data files work too.
+- **One game per folder.** Several APKs in one folder count as one game.
 - **Scanning:** pick the folder that contains the game folders (`Games/` above) to add them all, or one game's folder
  to add just that game. FramePort looks up to 5 levels deep.
- **A single game:** Add games → Add an APK file… works with a lone APK too. Its data is found when the data folder sits next
-  to the APK, named as above.
+- **A single game:** **Add games → Add an APK…** also finds the data folder next to the APK.

-Not sure of the package name? Look at the OBB file names: `main.<version>.<package name>.obb`. Or add the APK
-first: the game's page shows the package name under **Details**.
+Not sure of the package name? It's in the OBB file names (`main.<version>.<package name>.obb`), and the game's page
+shows it under **Details**.
@@ -1,5 +1,20 @@
 # Steam Frame runtime reference (SteamOS 0.3.0, build 20260922)

+## Setup from the project page (checked 2026-10-10, dev Frame, SteamOS build 20260922)
+
+- Factory Frames have no browser; Steam's taskbar **+** offers Chromium as a Flatpak (`org.chromium.Chromium`,
+  flathub is configured as a system remote). It is the default handler for https links once installed.
+- Desktop Mode has `curl`, `wget`, `python3` 3.12, `konsole`, `kdialog`, `xdg-open`, `avahi-browse`, `systemd-run`;
+  no `wl-copy`/`xclip`.
+- avahi-daemon runs, but `avahi-browse` from an SSH session fails ("Daemon not running": no system D-Bus access
+  there). A stdlib-Python mDNS query works when it listens on port 5353 in the 224.0.0.251 group (like avahi):
+  replies to a random source port are dropped by the Frame's firewall. `bootstrap/setup.sh` does exactly that.
+- The Frame reaches the PC's port 8765 over the home Wi-Fi without any firewall change on the PC side here (WSL in
+  mirrored mode with the earlier FramePort rule state). The PC is also visible through the Frame's hotspot
+  (`wlanap`, 10.35.78.x): the script lists one PC once, by name and words.
+- Dolphin's "executable scripts" setting is the default (ask); `.sh` files open with a `bash.desktop` handler that
+  runs them in a terminal. Not used by the setup (a pasted line is simpler and needs no download prompt).
+
 ## Lepton (Android container)
 - Steam app **3029110 "Lepton"** (runtime) and **3056000 "Lepton Development"** (needs Developer Mode). The binary
  is `<Steam library>/steamapps/common/Lepton/lepton`; FramePort finds it via the appmanifests.
@@ -64,7 +79,7 @@
  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).
+- Environment blend: ALPHA_BLEND available (grayscale passthrough cameras).
 - Reference spaces: STAGE bounds are reported as 1×1 m.
 - Display 72 Hz by default in tests. Head pose is only tracked while the headset is worn; otherwise flags 0x3 and
  the session stays below FOCUSED.
@@ -99,7 +114,7 @@
  `/fex-compat-tool %verb% --`, **no** require_tool_appid: it does not use the Steam Linux Runtime. fex-compat-tool
  (Python) runs `<FEX-Emu>/usr/bin/FEX` with RootFS `/usr/share/guestos/fex-mesa` (part of the SteamOS image: an
  x86 Arch-style root with glibc 2.41, Mesa, graphics_provider.json for x86_64 + i386), emulates x86_64 and i386
-  (emulator.json), honours `STEAM_FEX_TSOENABLED`, `STEAM_FEX_MULTIBLOCK`, `STEAM_COMPAT_FEX_CONFIG`, sets
+  (emulator.json), honors `STEAM_FEX_TSOENABLED`, `STEAM_FEX_MULTIBLOCK`, `STEAM_COMPAT_FEX_CONFIG`, sets
  `tu_override_uncached_as_cache_coherent=true` and logs to `/tmp/fex-compat-tool-<pid>.log`. It **exits 1 ("No compat
  data path?") without `STEAM_COMPAT_DATA_PATH`** (keeps Config.json/AppConfig/Server/Telemetry in `<it>/fex-emu/`):
  the Linux launcher exports `<base>/compatdata`. Version seen: FEX-2607-76-g37265b1. ldd can't read x86 programs,
@@ -127,7 +142,7 @@
  create as 1.0; enabled by `XR_ENABLE_API_LAYERS` from launch.sh. Proton's Steam Linux Runtime container drops
  `XR_API_LAYER_PATH` (it keeps `XR_ENABLE_API_LAYERS`), so the agent registers the layer as an explicit layer in
  `~/.local/share/openxr/1/api_layers/explicit.d/` (home is shared into the container) with an absolute library path.
- Oculus Store builds that delay-load `LibOVRPlatform64_1.dll` (Platform SDK, e.g. Lies Beneath) crash with
+- Oculus Store builds that delay-load `LibOVRPlatform64_1.dll` (Platform SDK, for example Lies Beneath) crash with
  `0xc06d007e` (delay-load module not found): that DLL comes with the Oculus app, which the Frame doesn't have. (No Oculus runtime DLLs or
  registry keys are needed: Revive's LibOVRRT hook works once OpenXR does.)
 - Unreal's Oculus plugin (and LibOVR's `ovr_Detect`) first checks for the Windows event `OculusHMDConnected` (created
@@ -163,17 +178,59 @@
  sha256, no `.picked`); folder apps get it on the PC at add time (`analysis/linux.find_icon`). Not yet seen in
  Desktop Mode on the device.

+## Overlay apps (SteamVR / OpenVR overlays, checked 2026-10-10 on the dev Frame, SteamOS 0.4.5)
+OpenVR overlay applications (`VRApplication_Overlay`: fpsVR, wrist watches, ...) work on the Frame itself, also
+over Quest games.
+- The Frame's host SteamVR (`/opt/steamvr/bin/linuxarm64`, always running in the VR session) serves `IVROverlay`
+  010-028 / `IVRApplications_007` to native Linux arm64 clients through its own `libopenvr_api.so` (ctypes is
+  enough: `native/vroverlay_probe/vroverlay_probe.py`). Overlay apps connect from SSH; vrserver logs
+  `New Connect message from … (VRApplication_Overlay)`, `vrcmd --overlays` (`/opt/steamvr/bin/linuxarm64/vrcmd`,
+  LD_LIBRARY_PATH=that dir) lists them `visible`, Steam's VR UI logs `[Overlays] Created: <key>` and loads a
+  dashboard overlay's thumbnail.
+- **Composited over Lepton (Quest) games**: with 4XVR running headless (FrameBridge 72 fps), the probe's head-locked
+  overlay appeared in the headset view (`/dev/video99`, see "Video of the headset view") on top of 4XVR's theatre.
+  The Android SteamVR runtime inside Lepton submits to the same host compositor, which draws host overlays on top.
+- Seeing pixels without a worn headset: the compositor pauses in standby (headset view = black) and fades to a
+  solid colour without tracking. For a few seconds after setting `power/pauseCompositorOnStandby` and
+  `steamvr/forceFadeOnBadTracking` to false (IVRSettings; neither key is in the user's steamvr.vrsettings, so
+  `RemoveKeyInSection` restores the default) the headset view shows the real composition (2 fps grabs: frames 7-10
+  of 16 had the picture, the rest the fade colour). Restore both keys afterwards.
+- **Windows overlay apps under Proton (ARM64)**: Temporal Reality's Windows build (Python/pyopenvr, x64) under
+  Proton 11 (SteamGameId set, FramePort's timefix layer) created its overlays on the Frame's SteamVR (`vrcmd
+  --overlays`: `temporalreality.watch`, `.settings` dashboard + 512x512 thumbnail), so Proton's vrclient bridges
+  `VRApplication_Overlay` too. Not seen as pixels (that watch only shows on a tracked left controller). fpsVR (.NET,
+  wine-mono) ran 60 s under Proton (SteamAPI ok: "Game process added: AppID 908520") but never loaded
+  openvr_api.dll and quit by itself (presumably it waits for a Windows SteamVR process). A freestanding CRT-less x64
+  exe (`native/vroverlay_probe/fp_vroverlay_probe.c`) died at its first kernel32 call (`c000001d` in the x64
+  emulation thunk); a normal MSVC/MinGW build should be used for Windows probes.
+- **Registration** (what SteamVR honours on the Frame): `IVRApplications::AddApplicationManifest(path, false)` from
+  a utility client, live; the path is kept in `~/.config/openvr/config/appconfig.json` `manifest_paths`.
+  `SetApplicationAutoLaunch` is accepted (GetApplicationAutoLaunch → true; vrserver has
+  `CAppInfoManager::StartAutolaunchOverlays`) but wasn't written to `steamvr.vrsettings` right away; whether it
+  starts the app at the next SteamVR start is **not yet verified**. The linuxarm64 vrserver only reads
+  **`binary_path_linux_arm`**: a manifest with `binary_path_linux` alone is skipped ("must specify binary_path for
+  launch_type binary. Skipping"; Steam's own steamapps.vrmanifest entries are skipped the same way), so an app's
+  own Linux manifest/`--install` that only writes binary_path_linux can't be launched by SteamVR on the Frame.
+  `LaunchApplication(key)` then starts the binary (Temporal Reality's launch.sh: process up, overlays created).
+- A Steam shortcut of an overlay app and a game shortcut run at the same time (Temporal Reality, then 4XVR, both
+  through `steam://rungameid`: both "Game process added", both kept running).
+- FramePort (agent v75): `register_vr_overlay` writes `<anchor>/frameport-overlay.vrmanifest` (the app's own key,
+  name and image from its bundled manifest, binary = launch.sh in `binary_path_linux_arm` + `binary_path_linux`,
+  absolute paths) and registers it; `unregister_vr_overlay`, uninstall and purge remove it; `ensure_host_fixes`
+  registers ones SteamVR missed (it wasn't running). Overlay apps skip launch tests, the Linux launcher's
+  Steam-parent watchdog (`FRAMEPORT_OVERLAY=1`) and don't count as a running game.
+
 ## Video of the headset view (surveyed 2026-10-05; used by the Live view tab)
 - `steamvr-v4l2cam.service` (user unit, part of gamescope-session.target, `Restart=always`) runs SteamVR's
  `/opt/steamvr/bin/linuxarm64/v4l2cam --output=99`: it reads the compositor's "Headset View" (IVRHeadsetView) and
  writes it to a v4l2loopback webcam named **"SteamVR"** (`/dev/video99`, 1920x1080 RGB24, advertised 30 fps, frames
  arrive at the display rate). Nothing on the Frame reads it by default; idle it costs nothing, read ~0.2 core.
  It shows what the wearer sees (SteamVR home, Steam's panels; a game's layers are expected but not yet seen in it).
-  Black and ~1 fps (one frame per ~1.0 s) while the headset sleeps (standby): a 30 fps stream then repeats each
+  Black and ~1 fps (one frame per ~1.0 s) while the Frame sleeps (standby): a 30 fps stream then repeats each
  frame in bursts, which looks like a stall in a player. Its size follows SteamVR's headset view (v4l2cam has no size
  option), so the live view only scales down (360p/480p/720p/1080p) or sends it as is ("full").
 - Sound: `pactl get-default-sink` (`alsa_loopback_device.stereo.alsa_output.platform-sound.HiFi__Speaker__sink`) and its
-  `.monitor` source carry what the headset plays; the Frame's ffmpeg has the `pulse` input and `aac`. Timestamps: pulse
+  `.monitor` source carry what the Frame plays; the Frame's ffmpeg has the `pulse` input and `aac`. Timestamps: pulse
  uses the wall clock, v4l2 CLOCK_MONOTONIC → `-ts mono2abs` on the v4l2 input. Don't force
  `-use_wallclock_as_timestamps` on the pulse input: it stamped bursts of AAC packets with one time.
 - Steam's own game recording / Remote Play / broadcast capture the **gamescope** PipeWire node (`CDesktopCapturePipeWire:
@@ -200,11 +257,11 @@
    Baseline..Constrained High, levels up to 6.0.
  - The `steamos` user can open it (group video).
  - The panel's current refresh rate can be read without privileges through DRM: `/dev/dri/card0` is mode 0666, and
-    GETCRTC reports e.g. `2*2160x2160_96` (clock 1402720 kHz / 4448 × 3285 = 96 Hz) even while the headset sleeps.
+    GETCRTC reports for example `2*2160x2160_96` (clock 1402720 kHz / 4448 × 3285 = 96 Hz) even while the Frame sleeps.
    The panel offers 72/80/90/96/108/120/144 Hz.
  - `/dev/video99` (v4l2loopback) has `max_buffers=2`: a reader asking for more gets 2.
  - Mid-stream keyframe requests (FORCE_KEY_FRAME) take effect on the next frame, and the GOP restarts from there.
-  - Measured 2026-10-07 with the headset asleep (still picture):
+  - Measured 2026-10-07 with the Frame asleep (still picture):
    - `fp_venc` alone at 32/36 fps: 1% of a core at 1080p, 2.5% at 720p.
    - Live view end to end: `fp_venc` 2.6% + ffmpeg 8.4% (AAC encoding + muxing).
  - Conversion cost per new picture (self-test, NEON, 2026-10-07):
@@ -265,7 +322,7 @@ All readable by the steamos user without root; the agent reads them directly (no
 | Power | hwmon `max34417_*` `power{1-4}_{label,input}` (µW) | `vph` = whole system (~3.6 W idle), `gfx` = GPU, `apc0/1/2` = CPU clusters, `nsp1/2` = NPU; each read is an I2C transfer (~0.7 ms wall), so only these are read |
 | Battery | `power_supply/max1720x_bat_7-36` | `current_now` (µA, negative = draining) × `voltage_now` (µV) = watts; `time_to_empty_now`/`time_to_full_now` (s), `cycle_count`, `health`, `temp` (0.1 °C) |
 | Game fps | `<base>/launch.log` lines `FrameBridge: pacing: N fps …` (every ~5 s) | Quest games only; SteamVR writes PC VR frame stats only as an end-of-session summary in `vrcompositor.txt` |
-| Game container | conmon `-n lepton-steamlaunch-<appid>`; its child's `/proc/<pid>/cgroup` → `cpu.stat`, `memory.current` | The container's ~90 Android processes show as uid 1000 on the host and can be signalled (4XVR, 2026-10-07); Android names them after the package's last 15 characters (`lus4xvrplayerov`), the full name is in `cmdline` |
+| Game container | conmon `-n lepton-steamlaunch-<appid>`; its child's `/proc/<pid>/cgroup` → `cpu.stat`, `memory.current` | The container's ~90 Android processes show as uid 1000 on the host and can be signaled (4XVR, 2026-10-07); Android names them after the package's last 15 characters (`lus4xvrplayerov`), the full name is in `cmdline` |

 Cost: a naive sample (fds of ~520 processes scanned) took 43 ms CPU. With kernel threads skipped after their first
 sighting, command lines checked once per process, render fds cached (rescanned every 60 s, every 4 s for busy young
@@ -1,53 +1,65 @@
-# Frame setup: what changes, networks, undoing it
+# What the setup changes

-For the steps themselves see [INSTALL.md](INSTALL.md#connecting-the-steam-frame).
+For the setup steps see [Install and first steps](INSTALL.md#connecting-the-steam-frame). This page lists what the
+setup changes on the Steam Frame, how to undo it and what your network needs.

-## What the setup changes
+## Changes on the Frame

-The setup command runs [`bootstrap/bootstrap.sh`](../bootstrap/bootstrap.sh), served by the app over your
-local network. Everything it changes:
+The setup runs [`bootstrap/bootstrap.sh`](../bootstrap/bootstrap.sh), which FramePort sends from your PC. 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. |
+| Turns on **Developer Mode** if it's off. Steam restarts once, which closes the desktop; the rest finishes on its own (log: `~/.cache/frameport-setup.log`). | `"DevModeEnabled" "1"` in `~/.local/share/Steam/config/config.vdf` (old copy kept as `config.vdf.before-frameport`), then Valve's own Developer Mode helper. | Settings → System → **Enable Developer Mode** off. |
+| Lets FramePort log in. | One line ending in `frameport` in `~/.ssh/authorized_keys`. | Delete that line. |
+| Stops game starts from failing after about 200 launches (a limit in podman, the tool Lepton runs games with). | `[containers]` / `keyring = false` in `~/.config/containers/containers.conf`. | Remove those lines. |
+| Asks Steam to install **Lepton** (Valve's Android runtime) 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.
+Valve's Developer Mode helper is the same one the Settings switch uses. It turns on remote login (SSH), the service
+that makes the Frame findable on your network, remote desktop, debugging and crash dumps; turning Developer Mode off
+turns them all off 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.
+The script runs as your user: no root, no `sudo`, no password. Nothing else on the system changes. It also leaves two
+files: `~/.cache/frameport-setup.sh` (the part that finishes 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/`;
+If Developer Mode can't be turned on automatically, the script asks you to turn it on in Settings → System →
+**Enable Developer Mode** and run the setup line again.
+
+**Later, FramePort adds** (as your user):
+- its 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).
+  and Valve's ARM64 Proton with its Steam Linux Runtime (Steam downloads them and 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.
+folder, the OpenXR layer and the setup files. Developer Mode, the login line, the podman setting, Lepton and Proton
+stay: undo them as shown above.

 ## 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:
+The setup is the only time the Frame connects to your PC. It downloads the setup script from FramePort on TCP port
+8765 (8766 or 8767 if taken), only while the setup page is open and for at most 30 minutes. Everything else goes
+from your PC to the Frame.

- **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.
+How the setup line finds your PC:
+
+1. FramePort announces itself on your network while the setup page is open (with your PC's name and two words, never
+   the code). If nothing answers, the setup line tries the USB cable's address and then scans the Frame's network.
+2. Both sides show the same 4 digits. Nothing happens until you click **Allow** in FramePort.
+3. FramePort then hands over the one-time code, and the Frame downloads the same setup script as the setup command.
+
+The setup line's script is [bootstrap/setup.sh](../bootstrap/setup.sh). If the setup just says "timed out", the
+setup page shows what is likely blocking it after about 45 seconds:
+
+- **Windows:** allow FramePort when Windows asks. On a network Windows treats as **Public** it stays blocked; set
+  your home network to Private in Windows' network settings.
 - **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.
+- **WSL** (FramePort's Linux version on Windows): Windows blocks connections into WSL without asking. FramePort
+  adds a temporary firewall rule (one admin prompt) and removes it when setup is done or after 35 minutes. WSL must
+  share Windows' network: `networkingMode=mirrored` under `[wsl2]` in `%UserProfile%\.wslconfig`, then
+  `wsl --shutdown`.
+- Or skip the setup line and use **Pair new host** (see [Install and first steps](INSTALL.md#connecting-the-steam-frame)):
+  it needs no connection into your PC.
@@ -1,7 +1,7 @@
 # Tested games

-Games tested on the Steam Frame with FramePort's recipes. Games not listed here may work too: FramePort suggests patches for them, and a working config can be shared from the app (**Share working config…**).
-Tested a game? [Share a working config](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml) or [report a problem](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml) (in the app: the game's **…** menu does both and fills in the details).
+Games tested on the Steam Frame with FramePort. Games not listed may work too: FramePort suggests patches for them. Got one working? [Share its recipe](INSTALL.md#share-a-recipe-or-report-a-problem).
+
 Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.

 | Game | Platform | Status | Notes |
@@ -11,6 +11,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | AgeOfJoy | Quest | ✅ Works |  |
 | AllInOneSports | Quest | ✅ Works |  |
 | Asgard's Wrath 2 | Quest | ✅ Works |  |
+| Audica | Quest | ✅ Works |  |
 | BAM | Quest | ✅ Works |  |
 | BARTENDER VR SIMULATOR | Quest | ✅ Works |  |
 | Batman: Arkham Shadow | Quest | ✅ Works |  |
@@ -18,15 +19,23 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | BattleSisters | Quest | ✅ Works |  |
 | Beat Saber | Quest | ✅ Works |  |
 | Beat Saber | Quest | ✅ Works |  |
+| Beat Saber | PC VR | ✅ Works |  |
 | Beat Saber (co-existence build) | Quest | ✅ Works |  |
 | Blade & Sorcery: Nomad | Quest | ✅ Works |  |
 | BodyCombat | Quest | ✅ Works |  |
 | BONELAB | Quest | ✅ Works |  |
 | Carve Snowboarding | Quest | ✅ Works |  |
+| Caves | Quest | ✅ Works |  |
+| Clockwork | Quest | ✅ Works |  |
 | Cook-Out | Quest | ✅ Works |  |
 | Creed | Quest | ✅ Works |  |
+| cubism | Quest | ✅ Works |  |
+| Deep Cuts | Quest | ✅ Works |  |
 | Demeter | Quest | ✅ Works |  |
 | Dinosaur Island | Quest | ✅ Works |  |
+| Doom3Quest | Quest | ✅ Works |  |
+| Down the Rabbit Hole | Quest | ✅ Works |  |
+| Eleven: Table Tennis VR | PC VR | ✅ Works |  |
 | Espire 2 | Quest | ✅ Works |  |
 | Genotype | Quest | ✅ Works |  |
 | GORN2 | Quest | ✅ Works |  |
@@ -54,15 +63,20 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | palazzo_santacruz | Quest | ✅ Works |  |
 | Path of the Warrior | Quest | ✅ Works |  |
 | Pistol Whip | Quest | ✅ Works |  |
+| Pistol Whip | PC VR | ✅ Works |  |
 | Please Don't Touch Anything | Quest | ✅ Works |  |
 | PowerWash Simulator VR | Quest | ✅ Works |  |
 | QuestCraft | Quest | ✅ Works |  |
+| Racket: Nx | Quest | ✅ Works |  |
+| RC Pilot Trainer | Quest | ✅ Works |  |
 | Retronika | Quest | ✅ Works |  |
+| Retropolis | Quest | ✅ Works |  |
 | Richie's Plank Experience | Quest | ✅ Works |  |
 | Rick and Morty: Virtual Rick-ality | PC VR | ✅ Works |  |
 | Riven | Quest | ✅ Works |  |
 | Robo Recall | Quest | ✅ Works |  |
 | RUINSMAGUS | Quest | ✅ Works |  |
+| Shores of Loci | Quest | ✅ Works |  |
 | Sniper Elite VR | Quest | ✅ Works |  |
 | Sniper Elite VR: Winter Warrior | Quest | ✅ Works |  |
 | Space Pirate Trainer Quest | Quest | ✅ Works |  |
@@ -70,6 +84,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Stremio | Quest | ✅ Works |  |
 | SUPERHOT VR | PC VR | ✅ Works |  |
 | SUPERHOT VR | Quest | ✅ Works |  |
+| SynthRiders | Quest | ✅ Works |  |
 | TetrisEffect | Quest | ✅ Works |  |
 | The Boys VR | Quest | ✅ Works |  |
 | The Climb 2 | Quest | ✅ Works |  |
@@ -79,16 +94,22 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Toy Master | Quest | ✅ Works |  |
 | Under Cover | Quest | ✅ Works |  |
 | Vader Immortal: Episode I | Quest | ✅ Works |  |
+| Vader Immortal: Episode II | Quest | ✅ Works |  |
+| Vader Immortal: Episode III | Quest | ✅ Works |  |
 | VR HOT Quest | Quest | ✅ Works |  |
 | VR4 | Quest | ✅ Works |  |
 | Walkabout Mini Golf | Quest | ✅ Works |  |
 | Wallace & Gromit in The Grand Getaway | Quest | ✅ Works |  |
 | Waltz of the Wizard: Extended Edition | Quest | ✅ Works |  |
 | Wander | Quest | ✅ Works |  |
+| ZombielandVR | Quest | ✅ Works |  |
+| Ancient_Dungeon | Quest | ⚠️ Works with issues | Multiplayer isn't available (offline). |
 | Arcsmith | Quest | ⚠️ Works with issues | Right eye distorts during movement (unresolved; swap, tracking, Valve layers, depth and pacing ruled out). |
 | Assassin's Creed Nexus | Quest | ⚠️ Works with issues | Some launch warning text is still upside down; the rest of the UI is fixed by flip emulation. |
 | Does it Stack? | Quest | ⚠️ Works with issues | Mixed reality mode does not work (works on Demeo), everything else seems to be OK |
-| Doom3Quest | Quest | ⚠️ Works with issues | PDA shows black screen. |
+| End Space | Quest | ⚠️ Works with issues | Controls stop responding after the first mission loads. |
+| ExploreVR | Quest | ⚠️ Works with issues | The 3D world warps and shifts with head movement (wrong perspective). |
+| Freedom | Quest | ⚠️ Works with issues | Volume can't be changed in the game. |
 | Myst | Quest | ⚠️ Works with issues | Minor graphical glitches on some objects. |
 | Phantom: Covert Ops | Quest | ⚠️ Works with issues | DLC/store button crashes (no Meta store). |
 | Pinball FX VR | Quest | ⚠️ Works with issues | Plays; mixed reality mode not working yet. |
@@ -97,7 +118,9 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Time Stall | Quest | ⚠️ Works with issues | Both eyes distort during movement (unresolved). |
 | WiiCompiled VR | Quest | ⚠️ Works with issues | To add a game: in FramePort's Files tab, upload your .wcgame file to this game's storage, folder Android/data/org.wiicompiled.quest/files/WiiCompiledOpenXRVR… |
 | BlazeRush | Quest | ❌ Doesn't run | Starts and reaches the menu room, but the room shows no controllers and ignores all input (it all reaches the game); no fix yet. |
+| Eleven Table Tennis | Quest | ❌ Doesn't run | Stops at the splash screen. |
 | Espire 1: VR Operative (Quest Edition) | Quest | ❌ Doesn't run | Mesa GL driver crash during texture upload. |
+| GOLF+ | Quest | ❌ Doesn't run | Black screen. |
 | HITMAN 3 VR: Reloaded | Quest | ❌ Doesn't run | Vulkan driver crash (freedreno), even without Valve layers. |
 | Journey of the Gods | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |
 | Roblox | Quest | ❌ Doesn't run | Crashes on its first VR frame on the Frame. |
@@ -1,292 +1,263 @@
-# Installing FramePort
+# Install and first steps

-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).
+▶ **[Watch the install tutorial](media/frameport-install.mp4)** (about 90 seconds): from the download to the first
+game on the Steam Frame.

-| Computer | Archive | Start |
+[![The install tutorial](media/frameport-install.jpg)](media/frameport-install.mp4)
+
+Download the file for your PC from the [latest release](https://github.com/spoopyghosty0/frameport/releases/latest)
+and unpack it anywhere. No installer or admin rights are needed.
+
+| Your PC | Download | Start |
 |---|---|---|
 | Windows 10/11 (x64) | `FramePort-windows-x64.zip` | `FramePort.exe` |
 | macOS (Apple Silicon) | `FramePort-macos-arm64.zip` | `FramePort.app` |
-| Linux (x64, GTK 3; Ubuntu 22.04 or newer) | `FramePort-linux-x64.tar.gz` | `FramePort/FramePort` |
-| Linux (ARM64, GTK 3; Ubuntu 22.04 or newer) | `FramePort-linux-arm64.tar.gz` | `FramePort/FramePort` |
-| Command line only (Python 3.11+) | `frameport-<version>-py3-none-any.whl` | `frameport --help` |
+| Linux (x64, Ubuntu 22.04 or newer) | `FramePort-linux-x64.tar.gz` | `FramePort/FramePort` |
+| Linux (ARM64, Ubuntu 22.04 or newer) | `FramePort-linux-arm64.tar.gz` | `FramePort/FramePort` |

-The command-line version installs from the wheel's release link with `uv tool install <link>` (or pipx / pip).
+On first start FramePort downloads the tools it uses (Settings → Tools shows them).

 ## First launch

-The builds are signed with a free self-signed certificate (Windows) and an ad-hoc signature (macOS), so the first
-start shows a warning:
+FramePort isn't signed with a paid certificate, so the first start shows a warning:

- **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` (ARM64: `FramePort-linux-arm64.tar.gz`).
+- **Windows:** "Windows protected your PC" → **More info** → **Run anyway**.
+- **macOS:** right-click `FramePort.app` → **Open** → **Open** (once).
+- **Linux:** `tar xzf FramePort-linux-x64.tar.gz && ./FramePort/FramePort`.

 ## Connecting the Steam Frame

-The Frame and the computer must be on the same network.
+The Frame and your PC must be on the same network (or connected with a [USB cable](#with-a-usb-cable)).

-1. In FramePort open **Steam Frame** and click **Show setup command**.
-2. First time only, on the Frame:
-   1. Open the **SteamVR dashboard → Launch a program → Desktop**: the Linux desktop opens on a virtual screen.
-   2. Open the app menu (bottom-left corner of that desktop) → **System → Konsole** (or search for Konsole).
-   3. Type the command FramePort shows exactly as shown (on-screen keyboard or any USB/Bluetooth keyboard) and press
-      **Enter**. It looks like `curl -fsS 192.168.1.20:8765/1a2b3c4d | bash`: your computer's address, then a
-      one-time code.
-   4. After a few seconds the desktop closes by itself (Steam restarts once); that's expected. If
-      Steam asks to install **Lepton** (Valve's Android runtime), confirm it.
+1. In FramePort open **Steam Frame** and click **Start setup**. Keep that page open.
+2. On the Frame, first time only:
+   1. Open the **SteamVR dashboard → Launch a program → Desktop**. The Frame's desktop opens.
+   2. Open the app menu (bottom left) → **System → Konsole**, the Frame's terminal.
+   3. Type this setup line and press **Enter** (on-screen keyboard or any USB or Bluetooth keyboard):

-   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.)
+      ```
+      curl -fsSL https://frameport.app/s | bash
+      ```

-**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.
+      No keyboard? Open [the setup page](https://frameport.app/setup/) in Chromium on the Frame,
+      tap **Copy** and paste it into Konsole.
+   4. Konsole shows a 4-digit code. When FramePort shows the same code, click **Allow**. Nothing changes on the Frame
+      before that.
+   5. Steam restarts once and the desktop closes. If Steam asks to install **Lepton** (Valve's Android runtime),
+      confirm it.
+
+FramePort connects within a minute. No password is needed. The setup turns on **Developer Mode**;
+[What the setup changes](FRAME_SETUP.md) lists everything.
+
+Later, FramePort connects to the Frame by itself. If you turn Developer Mode off (Settings → System → **Enable
+Developer Mode**), turn it on again there.
+
+**Setup command:** if your network blocks FramePort's search, click **Use the setup command**. It shows a line with
+your PC's address and a one-time code, for example `curl -fsS 192.168.1.20:8765/1a2b3c4d | bash`. Run it in Konsole instead.
+
+**Without Konsole:** turn on Developer Mode yourself (Settings → System → **Enable Developer Mode**), then open
+Settings → Developer → **Pair new host** on the Frame. FramePort finds the Frame and asks to connect; approve it in the
+headset. Install Lepton from FramePort's Steam Frame page afterwards if it's missing.

 ### With a USB cable

-For networks that block the setup (guest Wi-Fi, firewalls, discovery not working), and for faster uploads:
+A cable works on networks that block the setup, and uploads are faster (about 37 MB/s, three times typical Wi-Fi).

-1. On the Frame, turn on **Developer Mode** (Settings → System → Developer Mode). The Frame's USB network only exists
-   in Developer Mode.
-2. Connect the Frame's USB-C port to the computer.
-3. In FramePort: **Steam Frame → Set up with a USB cable**. FramePort detects the cable and shows the setup command,
-   which reaches the computer over the cable. Already set up? It connects over the cable right away.
+1. On the Frame, turn on Developer Mode (Settings → System → **Enable Developer Mode**). The cable only works in
+   Developer Mode.
+2. Connect the Frame's USB-C port to your PC. No driver is needed.
+3. In FramePort click **Steam Frame → Set up with a USB cable** and follow the steps.

-The cable needs no driver on Windows 10/11, macOS or Linux, and the computer gets an address from the Frame
-automatically. Uploads use the cable whenever it's plugged in (about 37 MB/s, ~3× typical Wi-Fi), even when FramePort
-connected over Wi-Fi. Unplug it any time: FramePort finds the Frame on Wi-Fi again by itself.
+Uploads use the cable whenever it's plugged in. Unplug it any time: FramePort finds the Frame on Wi-Fi again.

 ### 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).
+If the setup only says "timed out", a firewall on your PC blocks the Frame. After about 45 seconds the setup page
+says which. Details: [Network and firewalls](FRAME_SETUP.md#network-and-firewalls).

 ## Running FramePort on the Frame (experimental)

-FramePort can run on the Steam Frame itself, without a PC: in **Desktop Mode**, download
-`FramePort-linux-arm64.tar.gz`, unpack it (`tar xzf FramePort-linux-arm64.tar.gz`) and start `FramePort/FramePort`.
-Turn on **Developer Mode** first (Steam → Settings → System); FramePort then manages "This Frame" directly, with
-no pairing. Games are added to the Steam library when you go back to **Gaming Mode** (Steam has to restart for it,
-which would end Desktop Mode). This is new: please report anything odd with **Report a problem**.
+FramePort can run on the Frame itself, without a PC:
+
+1. Turn on Developer Mode (Settings → System → **Enable Developer Mode**).
+2. In Desktop Mode, download `FramePort-linux-arm64.tar.gz`, unpack it (`tar xzf FramePort-linux-arm64.tar.gz`) and
+   start `FramePort/FramePort`.
+
+Games appear in the Steam library when you go back to Gaming Mode. Please report anything odd with **Report a
+problem…**.

 ## Installing games

- **Install on Frame** on a game's page (or select several in the Library and install them together). Installs run
-  one after another in the background; **Activity** shows the current one at the top.
- **Update all** reinstalls every game whose build changed (e.g. after a FramePort update). Questions that need an
-  answer (e.g. Oculus games that can't run on the Frame) are asked once, for all games.
- If the Frame goes to sleep, turns off or leaves the Wi-Fi, the queue **waits** and continues once it's back; uploads
-  pick up where they stopped. While installs run, FramePort keeps the Frame from going to sleep. Before a large batch
-  it checks the Frame has enough free space.
- **microSD card / other drives:** the **Steam Frame** page's **Storage** section lists the Frame's drives and sets
-  where new games go (**Install new games to**). Games go into a `FramePort` folder on the card. To move a game that's
-  installed already, right-click it → **Move to…** (the game must be closed; saves, settings and the Steam entry stay).
-  A game on the card only starts while the card is inserted (FramePort then says "SD Card not inserted"). Cards
-  formatted as FAT, exFAT or NTFS can't hold games: format the card in SteamOS first.
- Your own game files are never changed. The converted copy is temporary: it's removed once the game is on the Frame
-  (Settings → Installing: keep them, or remove all now).
- **Game settings…** (game menu or the Steam Frame page): sharpness, refresh rate, controllers, menus, 360° video and
-  mixed-reality options in plain words, only those that matter for the game. Changes are kept with the game and,
-  when it's installed, used the next time it starts.
- Ordinary Android apps (no VR) are installed unchanged and shown as a flat window in the headset. Android's
-  back/home/recents buttons are hidden by default (patch **Hide Android's navigation bar**). If FramePort guesses
-  wrong (a phone app shows nothing in the headset, or a VR app opens as a flat window), choose **VR** or **Flat
-  window** under **Show as VR or as a flat window** in the game's **Customize** section, then **Update on Frame**.
- **Add games → Add a Windows program (.exe)…** adds a single Windows program; the Frame runs it through Proton (as a
-  window unless it is a VR game). A program sitting in Downloads, the home folder or a drive root is copied on its
-  own first, so the install doesn't upload everything next to it.
- In the packaged app you can also **drag files onto the Library**: APKs, Linux apps (AppImage, `.zip`/`.tar.gz`),
-  Windows programs (`.exe`), folders, or a FrameDrop manifest (`.json`).
-
-### Install links ("Install with FrameDrop" buttons)
-
-Some developers put an **Install with FrameDrop** button on their site (the one-click protocol of the FrameDrop
-sideloader, documented at framedropvr.com/docs). FramePort understands the same links:
-
- **Clicking a button** opens FramePort (or the window that's already open) on Windows and Linux. FramePort shows
-  the title, the files, their size and whether a checksum is given, and asks before it downloads anything. Then it
-  downloads the build, adds it to your library and starts the usual install on the Frame. If no Frame is connected,
-  the game is added now and installs once the Frame is back.
- **Add games → Install from a link…** takes the button's address (right-click → Copy link), a `framedrop://` or
-  `frameport://` link, a manifest (`.json`) or a direct link to an APK, a Linux build or a Windows program. Use it on
-  macOS, where web pages can't hand links to FramePort yet.
- **Settings → Install links** has one switch for `framedrop://` links (the buttons) and one for FramePort's own
-  `frameport://` links. Both are on by default. If FrameDrop is installed too and already opens `framedrop://`
-  links, FramePort leaves them to it; **Use FramePort for these links** takes them over (turn the switch off to give
-  them back).
- **For developers:** a FrameDrop manifest works as it is
-  (`{"schema": "framedrop.install/v1", "name": "…", "files": [{"url": "https://…", "sha256": "…"}]}`). FramePort
-  also reads an optional `"frameport": {"description": "…", "icon": "https://….png"}` object (FrameDrop ignores
-  it): the install question then shows the icon and description, and they become the game's icon and "About this
-  game" text when no store has them. Without a manifest (a bare file link) FramePort guesses the title from the
-  file name and replaces it with the app's own name once it's downloaded.
- Only `https://` links to public servers are used (plain `http://` only on this PC, for testing); links with a
-  user name or password, or pointing into your local network, are refused. Only install from sites you trust.
-
 ![Game page](images/game.png)

-Each game has **Game settings** in plain words (sharpness, refresh rate, controllers, menus, 360° video, mixed
-reality), showing only what matters for that game. Changes are kept with the game and reach the Frame right away.
+- **Install on Frame** on a game's page, or select several games in the Library and install them together. Installs
+  run in the background; **Activity** shows the current one.
+- **Update all** updates every game whose build changed, for example after a FramePort update.
+- If the Frame sleeps or leaves the Wi-Fi, installs wait and continue when it's back. While installs run, the Frame
+  stays awake.
+- Your own game files are never changed. The patched copy is deleted once the game is on the Frame (Settings →
+  Installing).
+- In the downloaded app you can also **drag files onto the Library**: games, Linux apps, Windows programs or folders.
+
+**Game settings…** (in the game's menu) shows the settings that matter for that game in plain words: sharpness,
+refresh rate, controllers, menus, 360° video and mixed reality. Changes are used the next time the game starts.

 ![Game settings](images/game-settings.png)

+### microSD cards and other drives
+
+- The **Steam Frame** page's **Storage** section sets where new games go (**Install new games to**).
+- To move an installed game, right-click it → **Move to…**. The game must be closed; saves and the Steam entry stay.
+- A game on a card only starts while the card is inserted.
+- Cards formatted as FAT, exFAT or NTFS can't hold games: format the card in SteamOS first.
+
+### Android apps and Windows programs
+
+- Android apps without VR are installed unchanged and shown as a window in the headset. If one shows nothing (or a
+  VR app opens as a window), open **Customize** on the game's page, set **Show as VR or as a flat window** and click
+  **Update on Frame**.
+- **Add games → Add a Windows program…** adds a single Windows program. The Frame runs it as a window through Proton
+  (Valve's tool for running Windows programs).
+
+### Install links ("Install with FramePort" buttons)
+
+Some websites have an **Install with FramePort** button (a `https://frameport.app/install?…` link):
+
+- **Click a button** on Windows or Linux: FramePort opens, shows what it would download and asks first. Then it adds
+  the game and installs it on the Frame.
+- **Add games → Add from a link…** takes a button's address (right-click → Copy link) or a direct download link. Use
+  it on macOS, where buttons can't open FramePort yet.
+- **Settings → Install links** turns the buttons on or off.
+- Only `https://` links to public servers are used. Only install from sites you trust.
+
+Website owners: see [Install button](INSTALL_BUTTON.md).
+
 ## Typing on the Frame

- **Type on Frame** (its own tab in the sidebar; also on the Steam Frame page and in a game's menu): while the tab is
-  open, this computer's keyboard works as a keyboard plugged into the Frame. Select a text field in the headset (in
-  an app, Steam or the desktop) and type; Esc and shortcuts go to the Frame too. Paste longer text into the box to
-  type it in one go (US keyboard layout). Opening another tab disconnects the keyboard.
- **Steam's on-screen keyboard** opens for text fields of apps shown as a window (2D apps, and VR apps with
-  **Show the app's Android window**). Steam lists that window as **Gamescope** (the Frame's display compositor);
-  leave it open: it's what receives the typing, the VR view isn't affected.
- **Unity apps whose text fields close at once** (a caret flashes, nothing can be typed): FramePort suggests
-  **Make Unity text fields work** for them. The first time, it downloads Cpp2IL (a tool that finds the right spot in the
-  game's code, ~17 MB). Games added before this version: open the game's menu → **Analyze again**, then reinstall.
+- **Type on Frame** (in the sidebar): while this tab is open, your PC's keyboard types on the Frame. Select a text
+  field in the headset and type, or paste longer text into the box.
+- **Steam's on-screen keyboard** works in apps shown as a window. Steam lists that window as **Gamescope**: leave it
+  open.
+- **Unity games whose text fields close at once:** FramePort suggests the patch **Make Unity text fields work**.
+  Games added before this patch existed: open the game's menu → **Analyze again**, then reinstall.

-## Watching the Frame (Monitor)
+![Type on Frame](images/type-on-frame.png)

- **Monitor** (its own tab in the sidebar) shows live what the Frame is doing while the tab is open: the running game
-  with its frame rate (Quest games), CPU, graphics chip, memory, the hottest temperature with the fan speed, power
-  draw and battery time left, each with a 2-minute chart. **Show details** adds every CPU core, all temperature
-  sensors, where the power goes and the network.
- **Processes**: **Game** (default) lists the running game's processes, **Steam & SteamVR** and **All** show more.
-  Right-click a process (or use **⋯**) to end it, force-kill it or end its whole game; **End game** on the game card
-  closes the game the way Steam's Exit game does. A lock marks programs whose end would close Steam, SteamVR or the
-  desktop: FramePort asks again before ending those.
- The numbers come every second (or every 2/5 s) and cost the Frame about 1 % of one CPU core; nothing keeps
-  running on the Frame after you leave the tab.
+## Watching the Frame
+
+- **Monitor** (in the sidebar) shows the running game's frame rate, CPU, graphics, memory, temperature, power and
+  battery, each with a 2-minute chart. **Show details** shows more.
+- Under **Processes**, right-click a process to end it. **End game** closes the game like Steam's Exit game. A lock
+  marks programs Steam or the desktop needs; FramePort asks again before ending those.
+- **Live view** streams what the headset shows, with sound, to your browser. It uses about one CPU core of the Frame,
+  so stop it when you're done.
+- **Screenshots** shows the screenshots you took in the headset, sorted by game and day, to view or download.

 ## Updating

-**Game configs** (the tested recipes in the catalog) update by themselves: FramePort checks GitHub every 6 hours for
-newly confirmed or fixed configs and uses them without a FramePort update; a game whose recipe changed then shows
-**Update on Frame**. Configs that need a newer FramePort are skipped until you update. Settings → Data shows the last
-check (**Check now**) and turns this off.
+FramePort checks for a new version at start and every 6 hours. When there is one, the Library shows **Update now**:
+FramePort downloads it, checks it, restarts and keeps your games and settings. **Later** skips that version.

-
-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.
-
-**Dev builds:** when you're asked to test a fix before it's released, use Settings → Updates → **Install the latest
-dev build…**. It shows what to test, then installs like an update (same checks). Dev builds are less tested; the next
-release is offered to you as a normal update.
-
-Command line: `frameport update` (`--check` only checks, exit code 10 = update available; `--yes` doesn't ask).
-`FRAMEPORT_NO_UPDATE_CHECK=1` turns all checks off.
+- Settings → **Updates** turns the check off or turns on **Install updates automatically**.
+- **Recipes** (the tested patches and settings for each game) update by themselves. A game whose recipe changed shows
+  **Update on Frame**.
+- **Dev builds:** if you're asked to test a change before its release, use Settings → Updates → **Install the latest
+  dev build…**. The next release then arrives as a normal update.

 ## 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.
+PC VR games are Windows VR games. Scan a folder of them (one folder per game) or use **Add games → Add a PC game
+folder…**. FramePort asks which program starts the game if it finds more than one.

- **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.
+- **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.
+- **Play on the Frame (experimental):** on the Steam Frame page, install *PC VR games (Proton)*, then click **Install
+  on Frame** on the game's page.
+- **Oculus games** (made for Meta's Rift headset) need Revive, which FramePort downloads. Games that check their
+  license through the Oculus app only run on your PC.

-**Windows games without VR:** **Add games → Add one game folder…** with the game's folder (pick the program that
-starts it if asked). FramePort installs it on the Frame and Proton runs it as a window, like Steam's own Windows games;
-it shows up in the Frame's Steam library tagged "Windows game on Frame". Whether a game runs depends on Proton on ARM
-(x86 games run through emulation).
+**Windows games without VR:** use **Add games → Add a PC game folder…** too. The Frame runs them as a window through
+Proton, like Steam's own Windows games. Whether a game runs depends on Proton.

 ## Linux apps

-The Frame runs SteamOS on an arm64 CPU, so native Linux apps built for **aarch64/arm64** run on it directly (no
-Android container, no Proton). **Add games → Add a Linux app…** takes an AppImage or a `.zip`/`.tar.gz`/
-`.tar.xz` archive; **Add a Linux app folder…** takes an unpacked app. FramePort finds the program that starts it (the
-game page's **Change…** picks another one) and whether it's a VR (OpenXR) app. **Install on Frame** uploads it
-unchanged and adds it to the Frame's Steam library, tagged "Linux app on Frame"; Play, launch tests and Uninstall
-work like for other games.
+**Add games → Add a Linux app…** takes an AppImage (a single-file Linux app) or a `.zip`/`.tar.gz`/`.tar.xz`
+archive; **Add a Linux app folder…** takes an unpacked app. **Install on Frame** uploads it unchanged and adds it to
+the Steam library.

- **x86_64 builds** run through **FEX**, Valve's x86 translator, with the x86 system libraries SteamOS ships for it
-  (the way Steam on the Frame runs x86 Linux games). The first install of one installs FEX on the Frame (Steam
-  restarts once and downloads it, a few MB). They run slower than arm64 builds: when an app offers both, FramePort picks the arm64 one. The game
-  page shows which CPU a build is for.
- The app must bring the libraries SteamOS doesn't have (checked for arm64 builds; x86_64 builds use FEX's x86
-  system, which has glibc and Mesa, and aren't checked ahead). If some are missing, the install reports them and the game
-  page lists them: look for a build that includes them.
- **Desktop Mode:** Linux apps also appear in Desktop Mode's application menu and as an icon on its desktop. Some
-  apps work better there, with a mouse and keyboard, than in Gaming Mode (where Steam Input turns the controllers into
-  a gamepad). Switch it off per app on the game page (**Desktop Mode**).
- From the command line: `frameport add-linux <AppImage, folder or archive> [--exe <program>]`.
+- Apps built for **arm64** (the Frame's processor) run directly. Apps built for **x86_64** (most PCs) run through FEX,
+  a translator Steam installs on the Frame the first time; they run slower. The game page shows which kind you have.
+- If the app needs libraries the Frame doesn't have, the game page lists them: look for a build that includes them.
+- Linux apps also appear in **Desktop Mode**'s app menu. Turn this off on the game
+  page (**Desktop Mode**).
+- **SteamVR overlay apps** (a wrist watch, a performance display: programs that draw over games instead of being
+  one) are registered with the Frame's SteamVR, which shows them over whatever you play, Quest and PC VR games
+  alike. FramePort recognises them by the `.vrmanifest` file they ship. By default SteamVR starts them by itself
+  (**SteamVR overlay → Start with SteamVR** on the game page); otherwise start the app from your library before the
+  game. Windows overlay apps get the patch **SteamVR overlay app (Frame)**.

-## Files on the Frame (videos, documents, mods, saves)
+## Files on the Frame

-The **Files** tab manages files on the Frame over the same connection as installs; no other transfer app is needed.
-Pick a location, browse folders, and use **Upload files** / **Upload folder**, **New folder**, or the download, rename
-and delete buttons on each entry. Right-click an entry (or the empty space) for the same actions in a menu. Tick
-several entries (or the box above the list for all), or click and drag across them, to download or delete them
-together; a right-click on one of them then acts on all. The **Screenshots** tab and the **Library** work the same
-way: right-click for a menu, drag across cards to select several. In the downloaded app you can also drag files and folders from Explorer / Finder / your file manager onto
-the list to upload them into the open folder. Uploads and downloads run in the Activity panel, resume after an interruption and
-skip files that are already there.
+The **Files** tab copies files between your PC and the Frame: videos, documents, mods and saves.

- **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**).
+![Files](images/files.png)

-Command line: `frameport frame send <files> --dest videos` (`frameport frame storage` lists the destinations).
+- Use **Upload files**, **Upload folder** and **New folder**; right-click an entry to download, rename or delete
+  it. Drag across entries to select several.
+- In the downloaded app you can drag files from your PC onto the list.
+- **Videos**, **Downloads** and **Documents** are shared by every Quest game (inside the game: `/sdcard/Movies`,
+  `/sdcard/Download`, `/sdcard/Documents`).
+- **Game storage** holds each game's own files. A game's menu → **Add videos and files…** opens it.

-## Sharing a working game, reporting a problem
+## Share a recipe or report 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>`.
+- **Share working recipe…** (in the game's menu) opens a GitHub issue with the game's recipe filled in. Accepted
+  recipes become built-in for everyone. Untested games ask how they run after you install or test them.
+- **Report a problem…** (in the game's menu, or Settings → Problems and feedback) saves a diagnostics zip with
+  personal data removed and opens a GitHub issue to attach it to.

-## Command line
-
-Everything the app does is also a `frameport` command (in a source checkout: `uv run frameport`); `frameport --help`
-and `frameport <command> --help` describe every option. The main ones:
-
-| Command | What it does |
-|---|---|
-| `scan <folder>` / `list` / `show <game>` | add games, list the library, show a game's analysis and patches |
-| `add-linux <path>` | add a Linux app, arm64 or x86_64 (AppImage, folder or archive) |
-| `recipe <game> --enable/--disable <patch>` | change a game's patches (`patches` lists them all) |
-| `build <game>` / `install <game>` / `test <game>` | build, install on the Frame (`--to pc` for PC VR on this PC), launch test |
-| `frame discover` / `frame connect` / `frame info` | find, pair with and describe the Frame |
-| `frame send` / `frame storage` / `frame cleanup` | copy files to the Frame, show where they go, free space |
-| `frame drives` / `frame move <game> --to <drive>` / `install --dest <drive>` | the Frame's drives (microSD), move a game, install to a drive |
-| `tools status` / `tools install` | the tools FramePort downloads |
-| `open-link "<link>"` | install from an "Install with FrameDrop" button's address or a manifest/APK/zip link (`--yes`, `--no-install`) |
-| `diag report <game>` / `share-recipe <game>` | report a problem / share a working recipe |
-| `update` | update FramePort |
-
-Exit codes: 0 done, 1 something failed, 2 wrong usage, 10 (`update --check`) a newer version exists. Errors are
-one line on stderr; `FRAMEPORT_DEBUG=1` shows the full traceback.
+Without the app: [share a recipe](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml)
+· [report a problem](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml).

 ## Uninstalling

-Settings → **Uninstall FramePort…** (or `frameport uninstall-app`) removes its data folder, the Steam shortcuts it
-added on this computer and, optionally, its games on the Frame (saves can be kept). It first saves your signing keys
-to Documents: game updates must be signed with the same key. Then delete the program folder.
+Settings → **Uninstall FramePort…** removes FramePort's data and, if you choose, its games on the Frame (saves can be
+kept). It first saves your signing keys to Documents: you need them to update your games later. Then delete the
+FramePort folder.

 ## Verify a download

-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:
+`SHA256SUMS.txt` in each release lists the files' checksums: `sha256sum -c SHA256SUMS.txt`. Each file also has a
+GitHub build attestation (proof that GitHub built it from this repository):
+`gh attestation verify FramePort-windows-x64.zip -R spoopyghosty0/frameport`.
+
+Windows: to show FramePort as the publisher, import `FramePort-selfsigned.cer` (attached to each release) into
+*Trusted Root Certification Authorities* (Current User). The certificate can only sign code; remove it with
+`certmgr.msc`. Its 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`.
+
+## For power users: the command line
+
+The **command-line version** (Python 3.11 or newer) installs from the release's
+`frameport-<version>-py3-none-any.whl` with `uv tool install <link>` (or pipx or pip).
+
+Everything the app does is also a `frameport` command; `frameport --help` and `frameport <command> --help` list every
+option. The main ones:
+
+| Command | What it does |
+|---|---|
+| `scan <folder>` / `list` / `show <game>` | add games, list the library, show a game's patches |
+| `add-linux <path> [--exe <program>]` | add a Linux app (AppImage, folder or archive) |
+| `recipe <game> --enable/--disable <patch>` | change a game's patches (`patches` lists them all) |
+| `build <game>` / `install <game>` / `test <game>` | build, install on the Frame (`--to pc` for this PC), launch test |
+| `frame discover` / `frame connect` / `frame info` | find, connect to and describe the Frame |
+| `frame send <files> --dest videos` / `frame storage` / `frame cleanup` | copy files to the Frame, list where they can go, free space |
+| `frame drives` / `frame move <game> --to <drive>` / `install --dest <drive>` | list the Frame's drives, move a game, install to a drive |
+| `tools status` / `tools install` | the tools FramePort downloads |
+| `open-link "<link>"` | install from an install button's address or a download link (`--yes`, `--no-install`) |
+| `diag report <game>` / `share-recipe <game>` | report a problem / share a working recipe |
+| `update` | update FramePort (`--check` only checks: exit code 10 = update available) |
+| `uninstall-app` | uninstall FramePort |
+
+Exit codes: 0 done, 1 failed, 2 wrong usage. `FRAMEPORT_DEBUG=1` shows full error details;
+`FRAMEPORT_NO_UPDATE_CHECK=1` turns update checks off.
@@ -0,0 +1,105 @@
+# Install button
+
+A button for web pages and READMEs that opens a game straight in FramePort. Clicking it hands FramePort an install
+link; FramePort shows what it would download and asks before it does anything (see
+[Install links](INSTALL.md#install-links-install-with-frameport-buttons)).
+
+<p>
+  <img src="badges/install-with-frameport-animated.svg" alt="Install with FramePort" width="216" height="60">
+</p>
+
+## Files
+
+All files are in [`docs/badges/`](badges/). Each SVG is self-contained (no external fonts or images), 216 × 60.
+
+| File | Use it for |
+|---|---|
+| [`install-with-frameport.svg`](badges/install-with-frameport.svg) | Everywhere. No motion. |
+| [`install-with-frameport-animated.svg`](badges/install-with-frameport-animated.svg) | GitHub READMEs and other pages that only allow images. The glow plays by itself every 6 seconds. |
+| [`install-with-frameport-hover.svg`](badges/install-with-frameport-hover.svg) | Websites where you can paste HTML. It glows while the pointer is on it, but only when its SVG code is in the page itself (see below). |
+| [`install-with-frameport@2x.png`](badges/install-with-frameport@2x.png) | Places without SVG support (some forums, email). 432 × 120; show it at 216 × 60. |
+
+Both animated versions stop moving for visitors who turn on reduced motion in their system settings.
+
+## The link
+
+The button links to FramePort's install page, which names either a manifest or one file:
+
+```
+https://frameport.app/install?manifest=<URL-encoded https address of a manifest .json>
+https://frameport.app/install?url=<URL-encoded https address of an .apk, a Linux build (.zip, .tar.*, .AppImage) or a Windows .exe>
+```
+
+The page shows what the link installs, opens FramePort with the matching `frameport://` link and, when FramePort
+isn't installed, offers the download. Pages that only target people who already have FramePort can link to the
+`frameport://` form directly:
+
+```
+frameport://install?manifest=<URL-encoded https address of a manifest .json>
+frameport://install?url=<URL-encoded https address of an .apk, a Linux build (.zip, .tar.*, .AppImage) or a Windows .exe>
+```
+
+The manifest:
+
+```json
+{
+  "schema": "framedrop.install/v1",
+  "name": "My Game",
+  "files": [{ "url": "https://example.com/my-game.apk", "sha256": "<64 hex digits>" }],
+  "frameport": { "description": "One sentence about the game.", "icon": "https://example.com/icon.png" }
+}
+```
+
+`name` becomes the game's title in Steam. `sha256` is optional but recommended: FramePort checks the download
+against it. The `frameport` object is optional; its icon and description are shown in the
+install question. Only public `https://` addresses are accepted.
+
+To build a link from Python: `frameport.deeplink.make_link(manifest_url="https://…/my-game.json")`.
+
+## On a website
+
+Image version (any page):
+
+```html
+<a href="frameport://install?manifest=https%3A%2F%2Fexample.com%2Fmy-game.json">
+  <img src="install-with-frameport.svg" alt="Install with FramePort" width="216" height="60">
+</a>
+```
+
+Hover version: paste the contents of `install-with-frameport-hover.svg` inside the link instead of the `<img>`, and
+give the link an accessible name:
+
+```html
+<a href="frameport://install?manifest=https%3A%2F%2Fexample.com%2Fmy-game.json" aria-label="Install with FramePort">
+  <svg …>…</svg>  <!-- the whole file -->
+</a>
+```
+
+Host the files yourself, or load them from jsDelivr, which serves them with the right content type:
+`https://cdn.jsdelivr.net/gh/spoopyghosty0/frameport@main/docs/badges/install-with-frameport.svg` (replace `main`
+with a release tag such as `v1.0.0` to pin a version; jsDelivr caches `@main` for up to 12 hours).
+
+## In a GitHub README
+
+GitHub removes links that don't start with `https://` or `http://` from READMEs, so a `frameport://` link there is
+not clickable. Use the `https://frameport.app/install?…` link:
+
+```markdown
+[![Install with FramePort](https://cdn.jsdelivr.net/gh/spoopyghosty0/frameport@main/docs/badges/install-with-frameport-animated.svg)](https://frameport.app/install?manifest=https%3A%2F%2Fexample.com%2Fmy-game.json)
+```
+
+Use the animated or still SVG: GitHub shows SVGs as images, so the hover version doesn't react there.
+
+## If a visitor doesn't have FramePort
+
+The `https://frameport.app/install?…` link handles this: its page offers the download and a second try. A bare
+`frameport://` link does nothing visible (or shows the browser's "no app for this link" message) when FramePort
+isn't installed; put a line next to such a button, for example "Needs [FramePort](https://frameport.app)". On macOS, web pages can't hand links to FramePort yet: users paste the link into Add games →
+Add from a link….
+
+## Usage rules
+
+- Keep the alt text "Install with FramePort".
+- Don't recolor, stretch, crop or redraw the button, and don't show it smaller than 40 px tall.
+- Leave some space around it (at least 8 px) so it doesn't touch other buttons.
+- It works on light and dark pages as it is; there is no light version.
@@ -1,80 +0,0 @@
-# Quest games on this PC (AXRB)
-
-FramePort's PC target ("This PC") already runs Oculus Rift games through Revive. For Quest/Android games it uses
-**AXRB** (Android XR Bridge, github.com/Android-XR-Bridge/AXRB): an Android 16 emulator (x86_64 Google APIs image,
-WHPX) that runs arm64 games through Android's ARM translation (`libndk_translation`), with AXRB's own OpenXR runtime
-inside Android and a Windows host process (`axrb-host-bridge.exe`) that opens a real OpenXR session on the PC's
-runtime (SteamVR, Virtual Desktop, ...). FramePort only drives it: it downloads AXRB's official release when a user
-first installs a Quest game on the PC, never bundles or modifies it (AXRB's host/clock code is under the AXRB
-Source-Available License 1.0, which allows running it and interoperating through its public interfaces).
-
-Status: **experimental**. AXRB is young (v1.0.4, 2026-10-06) and many games still fail in it; Steam Frame
-controllers don't work in AXRB yet (AXRB issue #20).
-
-## Spike results (2026-10-10, Windows 11 26200, i7-14700K, RTX 4080 SUPER, 64 GB; headless)
-
-| Step | Result |
-|---|---|
-| AXRB install | `AXRB-Setup-<v>.exe /S` (electron-builder one-click NSIS, per user, no UAC) → `%LOCALAPPDATA%\Programs\axrb-launcher`, 462 MB. Release assets: Setup exe + `SHA256SUMS-<v>-setup.txt` + source zip (no portable zip since 1.0.4). |
-| Runtime setup | Not scriptable through AXRB (it lives in the Electron launcher's JS), so FramePort reproduces it: 4 pinned `dl.google.com` zips from AXRB's `core/components.json` (emulator 36.5.11, platform-tools r37.0.1, build-tools 36.1, `sys-img/google_apis/x86_64-36_r07`), hash-checked, into `%LOCALAPPDATA%\AXRB Runtime\sdk`, AVD `axrb-managed-api36` written as AXRB writes it, `ready.json` / `license-acceptance.json` receipts so AXRB's own launcher sees the same runtime as set up. 2.4 GB download, ~3 min on a fast line; 26 GB on disk after one 7 GB game. |
-| Emulator boot | AXRB's `scripts\emulator\windows_android_emulator.ps1 -Action Start` (headless QEMU, AXRB clock adapter + GPU layer). First cold boot ~6 min (TSC-corrected clock cold-boots every time). ABIs `x86_64,arm64-v8a`. QEMU (`Start-Process`) and the adb server inherit the caller's handles: a pipe, a file through WSL interop, even `/dev/null` through interop (its relay stays open) all left the FramePort call hanging after the script had ended → FramePort starts AXRB scripts through WMI (`Win32_Process.Create`, hidden, nothing inherited), polls the PID and reads an `FP_EXIT <code>` line from the log. Windows PowerShell 5.1's `*>>` writes UTF-16. |
-| AXRB runtime | `adb install --no-incremental --force-queryable -r axrb-openxr-runtime-debug.apk` (0.3 s); found by the OpenXR loader through the system runtime broker. |
-| Data | `adb push` of OBB/pak files: 25-35 MB/s (7.2 GB Pinball FX VR in 5.5 min). A full uninstall (or a signature change: `INSTALL_FAILED_UPDATE_INCOMPATIBLE`) deletes the OBB folder and the saves → FramePort's stable per-game keys matter here too. |
-| **Original APK** (Pinball FX VR) | No launcher activity (Meta's VR category only), started explicitly: **SIGABRT 0.3 s after loading Meta's `libovrplatformloader.so`**. Unconverted Quest APKs don't run. |
-| **OVRPort-only build** (Lucky's Tale, Unity 2019 GLES) | OVRPort's loader → AXRB runtime → instance + session, frames submitted (2 s each without a host: the image send times out), no crash in 40 s. |
-| **OVRPort-only build** (Pinball FX VR, UE5 Vulkan) | OVRPlugin pre-init OK (AXRB reports "Oculus 67.522.0"), then exits (ForceQuit) / with the no-ForceQuit build SIGSEGV in `gfxstream vkAllocateMemory` called from AXRB's runtime Vulkan layer. Not decided headless (no host attached, see below). |
-| Host bridge | Needs an OpenXR runtime with a D3D11 adapter. Headless options all failed: SteamVR's null driver (`failed to find D3D11 adapter requested by OpenXR runtime`), `vrlink` without a headset (`xrCreateInstance` -2), Meta XR Simulator (binary download needs a Meta developer login). → frames-to-SteamVR need a real headset. |
-
-**Build decision: FramePort hands AXRB an OVRPort-only build** (the recipe's OVRPort patches, no Steam Frame fixes,
-signed with the game's FramePort key). The original APK crashes; FramePort's Frame fixes (FrameBridge adapter, Lepton
-and Frame-runtime workarounds) target the Frame. The recipe's alternate (no-ForceQuit) build is used when the recipe
-says so.
-
-### FramePort end to end (same day, headless, this branch)
-
-`frameport install com.playful.LuckysTale --to pc --no-library` (isolated `FRAMEPORT_HOME`): PC build (19 patches:
-OVRPort's + `frame.ovrplatformcompat`/`frame.ovrstubs`/`frame.swapchain_limit`; static checks pass without the
-FrameBridge check) → AXRB found, requirements met → emulator → AXRB runtime → `adb install` → 3.7 GB OBB in ~95 s
-(39 MB/s) → `deployment.json` + launcher script. `frameport test com.playful.LuckysTale --to pc`: launcher → AXRB run
-script → host bridge → triage `axrb-no-headset` (expected without a headset). The Steam shortcut write (needs a Steam
-restart) is unit-tested only.
-
-## How FramePort drives AXRB
-
- `tools/axrb.py`: find (env `FRAMEPORT_AXRB_DIR` > installed AXRB) / install (Setup exe, SHA256SUMS checked, `/S`) /
-  runtime setup (above) / requirements (WHPX via AXRB's `check_windows.ps1`, ≥ 12 GB RAM, x64).
- Environment for every AXRB script (the installed build sets none of it itself): `AXRB_DATA_HOME=<Runtime>\output`,
-  `ANDROID_AVD_HOME=<Runtime>\avd`, `ANDROID_USER_HOME=<Runtime>\android`, `ANDROID_HOME`/`ANDROID_SDK_ROOT=<Runtime>\sdk`,
-  `ANDROID_ADB_SERVER_PORT=5038`, `ADB_USB_LEGACY=1`, `ADB_LOCAL_TRANSPORT_MAX_PORT=5683`, AXRB's embedded Python
-  (`resources\runtime\tools\python`) first on PATH; arguments `-Sdk <Runtime>\sdk -Avd axrb-managed-api36 -Port 5584`.
- Install: start the emulator if needed (and stop it again if FramePort started it), install the AXRB runtime APK,
-  `adb install -r` the build, push OBB/data to `/sdcard/Android/obb|data/<pkg>/`, record `<data>/pc/<pkg>/deployment.json`
-  (`kind: "android"`).
- Play: a Steam shortcut runs FramePort's small launcher script (`%LOCALAPPDATA%\FramePort\axrb\fp-axrb-run.ps1`),
-  which sets the environment above and calls AXRB's `scripts\run\run_windows_game.ps1` (boots the emulator when
-  needed and then owns it, registers a SteamVR app identity, starts the host bridge, `am start`, waits; exit codes
-  0 ok, 1 error, 3 game lost, 4 host lost; `logs\game\session.json`, `host.err`).
- Logs for diagnostics: `<Runtime>\output\logs\game\{host.log,host.err,session.json,guest.log}`,
-  `logs\emulator\emulator.std{out,err}.log`.
-
-## Headset results (2026-10-10, Steam Frame streaming to the PC through Steam Link / vrlink, 96 Hz)
-
-AXRB's bridge opened a SteamVR session on the Frame each time (session state up to FOCUSED, both hands active), started
-through FramePort's launcher with the emulator booted by AXRB's run script (~1 min), and shut down cleanly.
-
- **Lucky's Tale (Unity, GLES): black.** GLES games go through AXRB's raw image path (eye readback → TCP), sized
-  by SteamVR's recommended resolution: 3412×3412 per eye at the owner's 250 % supersampling = 93 MB per frame,
-  ~10 s per frame; at a lowered resolution 2644×2644 = 56 MB, 6.6 s per frame (~8.5 MB/s). Not fixable from
-  FramePort (AXRB has no maximum-extent setting, only AXRB_MIN_EYE_EXTENT); even ~1000² would be ~1 fps.
-  AXRB's zero-copy GPU path covers Vulkan games only.
- **Pinball FX VR (UE5, Vulkan): crash 4 s after start**, the same gfxstream `vkAllocateMemory` SIGSEGV from AXRB's
-  runtime layer as headless (so not a headless artefact). AXRB's side.
-
-Not reached: sound, controllers. Next candidates: a Vulkan game AXRB reports playable (Deadpool VR, Batman: Arkham
-Shadow); an AXRB issue for the Pinball crash.
-
-## Open (needs the owner + a headset)
-
- A game in the headset through SteamVR (picture, audio, controllers; Steam Frame controllers: AXRB #20).
- Pinball FX VR's Vulkan crash with the host attached (AXRB's demo game: likely an AXRB/emulator issue if it repeats).
- Play from the PC's Steam library (shortcut → launcher script → AXRB).
@@ -1,6 +1,6 @@
-# Porting playbook: symptom → cause → fix
+# Porting playbook

-Everything here was hit while porting Quest and Rift games to the Steam Frame (Sept–Oct 2026; 38 catalog recipes). The machine-readable
+Everything here was hit while porting Quest and Rift games to the Steam Frame (September–October 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
@@ -8,13 +8,13 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 2. `frameport build <pkg>` → all static checks must pass (32-bit-only → stop, it can't run).
 3. `frameport install <pkg>` → `frameport test <pkg>`: want **RUNNING** + "Submitting frames" at ~72 fps.
 4. Put the headset on and look. Headless tests can't judge visuals (no FOCUSED state without the headset worn).
-5. Fix by symptom below, rebuild, repeat. When it's good: **Save as known-good** (GUI) / add a catalog YAML.
+5. Fix by symptom below, rebuild, repeat. When it's good: **Save as known-good** (GUI) or add a catalog YAML.

 ## Startup failures (visible in launch.log)
 | Symptom | Cause | Fix |
 |---|---|---|
-| A launch test suggests a fix (e.g. triage `sdl-no-clipboard` → `frame.sdl_clipboard`) but the game page doesn't show it / lists it as not applicable; or a game added long ago lacks warnings newer ones get (Android version, web wrapper, missing OBB) (GitHub #104, Dramatic Shape) | the library entry was analysed by an older FramePort: the analysis field the patch reads (`sdl_java`, `min_sdk`, `web_wrapper`, `expects_obb`, …) is missing, so `applies()` is false | entries whose `analysis.extra.analysis_version` is below `detect.ANALYSIS_VERSION` are analysed again at the GUI's start (background) and before a build (`pipeline.refresh_analyses`); by hand: game menu → "Analyze again", then Update on Frame. An unreadable APK is marked `analysis_failed` (retried after the next version bump). Adding an analysis field: bump `ANALYSIS_VERSION` |
-| One eye (usually the right) shimmers or jitters in the 3D view while menus and panels look steady; pacing is clean (GitHub #69, e.g. RTCWQuest, Moss) | Valve's eye-tracked foveation layer (`VALVE_fdm_injection`) moves its low-density regions with each eye's gaze, and the right eye's gaze filter restarts often (`CEyePoseUKF R: Large dt … Bootstrapped` in `~/.local/share/Steam/logs/eyetracking.txt`) | Customize → "Eye-tracked foveation (Valve)" (`device.foveation`): **Fixed** (`FDM_DEBUG=disable_offsets`, keeps the GPU saving) or **Off** (`VK_INSTANCE_LAYERS=""`); catalog field `foveation:` |
+| A launch test suggests a patch (for example triage `sdl-no-clipboard` → `frame.sdl_clipboard`) but the game page doesn't show it / lists it as not applicable; or a game added long ago lacks warnings newer ones get (Android version, web wrapper, missing OBB) (GitHub #104, Dramatic Shape) | the library entry was analyzed by an older FramePort: the analysis field the patch reads (`sdl_java`, `min_sdk`, `web_wrapper`, `expects_obb`, …) is missing, so `applies()` is false | entries whose `analysis.extra.analysis_version` is below `detect.ANALYSIS_VERSION` are analyzed again at the GUI's start (background) and before a build (`pipeline.refresh_analyses`); by hand: game menu → "Analyze again", then Update on Frame. An unreadable APK is marked `analysis_failed` (retried after the next version bump). Adding an analysis field: bump `ANALYSIS_VERSION` |
+| One eye (usually the right) shimmers or jitters in the 3D view while menus and panels look steady; pacing is clean (GitHub #69, for example RTCWQuest, Moss) | Valve's eye-tracked foveation layer (`VALVE_fdm_injection`) moves its low-density regions with each eye's gaze, and the right eye's gaze filter restarts often (`CEyePoseUKF R: Large dt … Bootstrapped` in `~/.local/share/Steam/logs/eyetracking.txt`) | Customize → "Eye-tracked foveation (Valve)" (`device.foveation`): **Fixed** (`FDM_DEBUG=disable_offsets`, keeps the GPU saving) or **Off** (`VK_INSTANCE_LAYERS=""`); catalog field `foveation:` |
 | A Unity OpenXR game closes right after the OpenXR instance is created: `F VrApiLoader: vrapi_SetPropertyInt was called before vrapi_Initialize()!`, SIGABRT on UnityMain (GitHub #62, Jurassic World Aftermath) | the APK still ships Meta's VrApi loader; OVRPlugin (1.89, on OpenXR) calls it without starting VrApi and Meta's loader aborts. The VrApi bridge can't replace it (39 of the loader's 114 functions: OVRPlugin wouldn't link) | `frame.vrapi_stub` (same exports, each returns 0); triage `vrapi-before-init` |
 | A VrApi game exits at once: `UnsatisfiedLinkError … dlopen failed: cannot locate symbol "vrapi_PollEvent"` (GitHub #57, BlazeRush) | the engine imports a VrApi function the VrApi bridge didn't implement | the bridge has `vrapi_PollEvent`, `RecenterPose`, `SetDisplayRefreshRate`, `GetSystemPropertyFloatArray` (rebuild the game); the static check "VrApi functions resolvable" names any other missing one; triage `vrapi-symbol-missing` |
 | A Team Beef port (Lambda1VR, RTCWQuest, …) exits at once: `UnsatisfiedLinkError: dlopen failed: library "libopenxr_loader_valve.so" not found` (GitHub #59) | TBXR loads `openxr_loader_<Build.MANUFACTURER>` (Lepton: valve) and takes the Meta path only when `strstr(OPENXR_HMD, "meta")` matches, else Pico's | `frame.tbxr_vendor` (empty `libopenxr_loader_valve.so` + the "meta" literal → "alve"). Game data (`xash/`, …) goes to /sdcard: upload it with the Files tab to the game's storage. Black eyes with `TBXR: Incomplete frame buffer object: GL_FRAMEBUFFER_INCOMPLETE_MULTISAMPLE`: TBXR always uses multisampled render-to-texture (even `--msaa 1`); `frame.tbxr_vendor` links the GL shim, which hands it single-sampled versions (log `GL shim: multisampled render-to-texture … drawn single-sampled`) |
@@ -22,33 +22,34 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | `cannot locate symbol "ovrPeerConnectionState_ToString"` (or another `ovr<Enum>_ToString`) at start (BlazeRush, GitHub #57) | OVRPort's platform loader lacks several Platform SDK enum helpers | `frame.ovrstubs` now stubs them too; `*_ToString` stubs return "" (not NULL) |
 | Exits right after the OpenXR instance is created: `Failed to create XR session: -50` (`XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING`, Lambda1VR) | the game skips `xrGet*GraphicsRequirementsKHR`; Meta's runtime tolerates it, SteamVR's doesn't. Lambda1VR's TBXR doesn't even enable `XR_KHR_opengl_es_enable` (only `XR_EXT_local_floor`) | FrameBridge adds `XR_KHR_opengl_es_enable` when an app enables no graphics API extension, asks for the requirements on the game's behalf and retries xrCreateSession once (logs `added XR_KHR_opengl_es_enable …`, `the app skipped …; asked for it`; every launch logs the final extension list `xrCreateInstance with N extension(s)`); triage `graphics-requirements-missing`. Verified headless: Lambda1VR runs at 72 fps |
 | Exits at start: `OVRAvatar-Loader: DisplayErrorAndExit: Failed to launch SystemActivities` after `ovrAvatar_Initialize: Failed to load AvatarSDK driver` (BlazeRush, GitHub #57) | Meta's avatar loader needs Horizon; it then tries Meta's error screen and aborts | `frame.avatar_stub` (same exports, do nothing); triage `avatar-driver-missing`. Games that ship the library but don't start avatars at launch (Lucky's Tale, BattleSisters, Arcsmith) don't need it |
-| Frame freezes or the game is killed (OOM) on the first controller vibration (e.g. Lucky's Tale's save slots, BattleSisters, Sniper Elite VR's tutorial grab: memory grows ~1 GB/s until the kill) | OVRPort runtimes up to 3.4.3-23204ea read the haptic envelope's duration (ns) as seconds and allocate gigabytes of samples (GitHub #9, ovrport/app#73); also reached from Unity's legacy `ovrp_SetControllerHaptics`; perf page faults all in `libopenxr_loader.so` `xrApplyHapticFeedback` | `adapter.haptic_fix` (envelope → one plain vibration in `native/xrshim`; PCM vibrations (`XrHapticPcmVibrationFB`) are converted the same way). Fixed in runtime 3.4.3-aa54c3f: builds made with it leave the workaround out by themselves (log "not needed: adapter.haptic_fix", `frameport show` "last build left out"); rebuild an older build to switch |
+| Frame freezes or the game is killed (OOM) on the first controller vibration (for example Lucky's Tale's save slots, BattleSisters, Sniper Elite VR's tutorial grab: memory grows ~1 GB/s until the kill) | OVRPort runtimes up to 3.4.3-23204ea read the haptic envelope's duration (ns) as seconds and allocate gigabytes of samples (GitHub #9, ovrport/app#73); also reached from Unity's legacy `ovrp_SetControllerHaptics`; perf page faults all in `libopenxr_loader.so` `xrApplyHapticFeedback` | `adapter.haptic_fix` (envelope → one plain vibration in `native/xrshim`; PCM vibrations (`XrHapticPcmVibrationFB`) are converted the same way). Fixed in runtime 3.4.3-aa54c3f: builds made with it leave the workaround out by themselves (log "not needed: adapter.haptic_fix", `frameport show` "last build left out"); rebuild an older build to switch |
 | Controller vibrations much stronger than on a Quest (The Boys VR, Jurassic World, BONELAB, …) | OVRPlugin games send amplitude envelopes; `haptic_fix` turned each into one vibration at the envelope's *peak* for its whole duration (a short fading pulse became a long full-strength buzz) | `haptic_fix` now uses the envelope's RMS; Game settings → "Vibration strength" (`haptic_scale`, 0-1) scales every vibration in FrameBridge; launch.log shows the first requests (`haptic: …`). OVRPlugin stops a vibration with amplitude 0 (2 s duration): FrameBridge turns that into xrStopHapticFeedback (without it the last buzz ran its full 2 s) |
 | Play or a launch test fails at once: `Game files missing at <path> (storage not mounted?)` in launch.log, or "… files are on a drive that isn't inserted" (GitHub #90) | the game was installed or moved to a microSD card (`<mount>/FramePort/<pkg>`) that isn't inserted or mounted now | insert the card; or move the game back (game menu → Move to…, `frameport frame move <pkg> --to internal`) once the card is back. `frameport frame drives` shows what the agent sees (exFAT/NTFS cards are refused: format in SteamOS) |
 | A Linux app started from Desktop Mode's menu closes after ~2 s, or opens on the wrong display (GitHub #84) | its launcher predates agent v63: the "Steam parent gone" watchdog ended it when Plasma's launcher exited, and it took gamescope's DISPLAY from Steam | connect FramePort once (agent v63's `upgrade_launchers` adds the `FRAMEPORT_DESKTOP` checks; the menu entry runs `env FRAMEPORT_DESKTOP=1 <anchor>/launch.sh`). Game Mode controller problems in such apps are Steam Input's (a separate issue) |
 | A Linux app (AppImage) shows no/FramePort's placeholder icon in Desktop Mode or Steam (GitHub #99) | before agent v64 only FramePort's art set's icon was used, and a lone AppImage has no store art | connect FramePort once (agent v64 copies the app's `.DirIcon` / `.desktop` `Icon=` to `<anchor>/artwork/app-icon.*` and refreshes the menu entry); reinstall to also get it into the library + Steam shortcut. Still the placeholder: check `<base>/app/squashfs-root/.DirIcon` and the `.desktop` file's `Icon=` (an icon outside the app folder or only an XPM isn't used); a chosen icon (`artwork/.icon-source` = `custom`) always wins |
+| An overlay app (fpsVR, a wrist watch) installed on the Frame never appears, or SteamVR doesn't start it | not registered with the Frame's SteamVR, or registered with a manifest SteamVR skips: on the Frame vrserver reads only `binary_path_linux_arm` (vrserver.txt: "must specify binary_path for launch_type binary. Skipping") | `pcvr.vr_overlay` (Windows) / a Linux app with a bundled `.vrmanifest` (`is_dashboard_overlay`): agent v75 `register_vr_overlay` (check `vrcmd --overlays`, `~/.config/openvr/config/appconfig.json` manifest_paths); the app's own `--install` writes binary_path_linux only. fpsVR under Proton never loads OpenVR (quits after 60 s): unsupported for now |
 | 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) |
+| A Unity app's text field shows a caret for a moment and loses focus; no keyboard appears (for example Stremio VR login) | Unity's TMP_InputField/InputField wait for Android's on-screen keyboard and close themselves without one (Lepton has none); headless VR apps also have no focused Android window, so no key press reaches them | `frame.unity_text_input` (Cpp2IL finds `TouchScreenKeyboardShouldBeUsed`/`isKeyboardUsingEvents`, rewritten to false/true) + `device.text_input_window` (lepton-show-flatscreen: Steam's keyboard and Type on Frame work) |
 | Play gives Steam's "Game configuration unavailable"; Steam's console_log: `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` | this Frame's Steam never loaded FramePort's shortcuts.vdf entry (it treats the id as a store app); cause unknown (GitHub #21/#30) | automatic since agent v43: Play registers the game through Steam's devkit interface ("Devkit Game: …", `devkit_register`) and starts that; uninstall removes it. Agent v58: a devkit entry Steam forgot after a restart is added again live on Play (no NOT_IN_LIBRARY → no Steam restart), and installs/art updates of devkit games only copy art (no Steam restart, GitHub #41) |
 | Steam's Exit game leaves the game running (container `lepton-steamlaunch-<appid>` still up) | Steam stopped only its `reaper`; launch.sh and Lepton (setsid) never got a signal (GitHub #36) | agent v44: launch.sh's 2 s loop ends the game when its parent is gone (`upgrade_launchers` adds it to existing launchers); by hand: `podman kill lepton-steamlaunch-<appid>` |
-| Black screen at start while audio/ExoPlayer runs; log `xrEndFrame: dropped N unusable layer(s)`, a quad layer with swapchain 0x0 (e.g. I Am Monkey's intro video) | The game plays video into an Android-surface swapchain (XR_KHR_android_surface_swapchain); the Frame's runtime lists the extension but returns FUNCTION_UNSUPPORTED | adapter `surface_emul` (default on): FrameBridge gives the player a SurfaceTexture-backed Surface and copies each frame into an ordinary swapchain (log `surface_emul: …`) |
-| The game quits right after start: `Something failed to initialize. Quitting!` / `We don't have write permission to …/files/cloud/data` (e.g. SUPERHOT) | The game created a save folder with mode 1700; inside Lepton the app writes through the folder's group | launch.sh `fix_perms` adds owner + group write to every folder in the game's storage (agent 41); reinstall to get the new launcher |
-| The whole Frame slows to a halt, then the game is killed (`Out of memory: Killed process … anon-rss:10+ GB`), e.g. Lucky's Tale | The game's own memory grows ~1 GB/s on Unity's `Loading.PreloadManager` thread (perf page-fault profile); not the flat window, not the text-input patches | none yet: mark unsupported; profile with `perf record -p <pid> -e page-faults --call-graph fp` (works as steamos, `perf_event_paranoid` 2) |
+| Black screen at start while audio/ExoPlayer runs; log `xrEndFrame: dropped N unusable layer(s)`, a quad layer with swapchain 0x0 (for example I Am Monkey's intro video) | The game plays video into an Android-surface swapchain (XR_KHR_android_surface_swapchain); the Frame's runtime lists the extension but returns FUNCTION_UNSUPPORTED | adapter `surface_emul` (default on): FrameBridge gives the player a SurfaceTexture-backed Surface and copies each frame into an ordinary swapchain (log `surface_emul: …`) |
+| The game quits right after start: `Something failed to initialize. Quitting!` / `We don't have write permission to …/files/cloud/data` (for example SUPERHOT) | The game created a save folder with mode 1700; inside Lepton the app writes through the folder's group | launch.sh `fix_perms` adds owner + group write to every folder in the game's storage (agent 41); reinstall to get the new launcher |
+| The whole Frame slows to a halt, then the game is killed (`Out of memory: Killed process … anon-rss:10+ GB`), for example Lucky's Tale | The game's own memory grows ~1 GB/s on Unity's `Loading.PreloadManager` thread (perf page-fault profile); not the flat window, not the text-input patches | none yet: mark unsupported; profile with `perf record -p <pid> -e page-faults --call-graph fp` (works as steamos, `perf_event_paranoid` 2) |
 | A Linux app exits at once: `cannot execute binary file: Exec format error` in launch.log | an x86_64 program started directly (installed before FramePort ran x86 builds through FEX, or by hand) | reinstall it: x86_64 Linux apps install FEX on the Frame and start through it (agent v61, `kind: linux_x86`; FEX also needs `STEAM_COMPAT_DATA_PATH`: "No compat data path?" in launch.log = an agent v60 launcher, reinstall); triage `linux-x86-no-fex`. Prefer an arm64 build when the app offers one |
 | `APP_ACTIVITY is empty`, nothing starts | Manifest has category INFO only; Lepton needs LAUNCHER | `frame.launcher` (automatic) |
 | PC VR game on the Frame shows as a flat window / Revive: `Unable to load LibOVRRT DLL` / `LoaderInstance::CreateInstance chained CreateInstance call failed` | Frame SteamVR runtime rejects OpenXR apiVersion 1.1 (`XR_ERROR_API_VERSION_UNSUPPORTED`), which Proton 11's VR helper requests | `pcvr.xr_timefix` (Frame OpenXR layer, default on): retries xrCreateInstance as 1.0 |
-| Unreal PC VR game on the Frame runs as a flat window although OpenXR works (no `LogHMD` OVRPlugin lines; Unreal logs nothing when it skips the Oculus plugin) / launch.log: `FramePort oculushmd: could not create the OculusHMDConnected event` | UE's OculusHMD (and LibOVR's `ovr_Detect`) only start when the Windows event `OculusHMDConnected` exists and is signalled; on a PC the Oculus service creates it. Revive hooks `OpenEventW` for it, but that relies on Detours patching Wine's (ARM64EC) kernelbase | `pcvr.oculus_unreal` (default for Unreal Rift games; PC VR counterpart of overport's `patch_oculus_unreal`): launch.sh runs the injector through `fp_oculushmd.exe`, which provides the real event until the game exits |
-| 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 |
+| 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 signaled; 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 SteamVR comes 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 |
+| Oculus Rift game won't run on the Frame | Oculus/LibOVR game: needs Revive, whose hooks don't work under Proton-arm64, and FramePort won't defeat the Oculus runtime signature check | Play it on this PC (SteamVR + Revive). Only OpenVR/OpenXR-native Rift games run on the Frame |
 | Un-cracked Oculus PC VR game: "Initializing OVR session" then exits / signature check on the runtime | Revive's hooks don't install on Proton-arm64; the Oculus shim rejects the unsigned Revive runtime | Not runnable on the Frame without the repack's crack extracted (not done by FramePort); use the PC version |
 | PC VR game: `Failed to initialize Oculus API (-3001)` / `Unable to load LibOVRRT DLL` | Revive's LoadLibrary hook doesn't work under Proton arm64 (ARM64EC kernelbase); the game's LibOVR shim finds no runtime DLL | Symlink `LibOVRRT64_1.dll` → Revive's DLL in the prefix's system32 (manual so far) → then -3021 (runtime signature check; open) |
 | Uploads to the Frame are slow (~15 MB/s) | PC and Frame both on Wi-Fi through the home router | Connect the PC to the Frame's own hotspot (or a USB cable): FramePort uses the direct link automatically (~80-100 MB/s); job log line "Transfer link" |
 | PC VR game exits right away: `Unhandled Exception: 0xc06d007e` (after `FOnlineSubsystemOculus::InitWithWindowsPlatform`) | Delay-loaded `LibOVRPlatform64_1.dll` (Oculus Platform SDK, installed with the Oculus app) is missing | None on the Frame (entitlement check; FramePort doesn't replace it). PC mode with the Oculus app |
-| Unity PC VR game (Oculus + SteamVR build: `OVRPlugin.dll` and `openvr_api.dll` in `<Name>_Data/Plugins`) opens a window and quits after ~20 s; no VR Vulkan instance after the game's DXVK device in launch.log; Unity log (`unity log … Player.log`, agent v67): `OpenVR failed initialization` / `Initialization of device … failed` | Unity's built-in VR tries its SDKs in list order (Oculus first) unless `-vrmode` picks one; a catalog recipe verified with another build of the game (e.g. SUPERHOT VR's OpenXR build, GitHub #105) used to drop the build's own arguments | `pcvr.launch_args` = `-vrmode OpenVR` (detected for such builds; kept when the catalog's `xr` differs from the build's). A game's Electron launcher next to it (SHVR.exe) is ranked below the game |
+| Unity PC VR game (Oculus + SteamVR build: `OVRPlugin.dll` and `openvr_api.dll` in `<Name>_Data/Plugins`) opens a window and quits after ~20 s; no VR Vulkan instance after the game's DXVK device in launch.log; Unity log (`unity log … Player.log`, agent v67): `OpenVR failed initialization` / `Initialization of device … failed` | Unity's built-in VR tries its SDKs in list order (Oculus first) unless `-vrmode` picks one; a catalog recipe verified with another build of the game (for example SUPERHOT VR's OpenXR build, GitHub #105) used to drop the build's own arguments | `pcvr.launch_args` = `-vrmode OpenVR` (detected for such builds; kept when the catalog's `xr` differs from the build's). A game's Electron launcher next to it (SHVR.exe) is ranked below the game |
 | Unreal PC VR game opens the crash reporter instead of closing | UE starts CrashReportClient.exe on a crash | `pcvr.no_crash_reporter` (default for Unreal Rift games): `-nocrashreports` + CrashReportClient.exe renamed `.disabled` in the Frame copy |
-| A backup's game was added without its data (library `data_dir` null, `data_bytes` 0) although the folder has .obb files | The OBBs sit in a layout the scan didn't know: `<game>/obb/<package>/`, `Android/obb/<package>/`, or SideQuest-style `<game>/apk/x.apk` + `<game>/obb/<package>/` | `sources/quest_dump.find_data_dir` finds a `<package>` folder with .obb files ≤3 levels below the APK's folder or ≤2 below its parent (skipping neighbouring folders with APKs: other games); an `apk`/`apks` folder counts as part of its game folder. Add the folder again (Analyze again doesn't look for data) |
+| A backup's game was added without its data (library `data_dir` null, `data_bytes` 0) although the folder has .obb files | The OBBs sit in a layout the scan didn't know: `<game>/obb/<package>/`, `Android/obb/<package>/`, or SideQuest-style `<game>/apk/x.apk` + `<game>/obb/<package>/` | `sources/quest_dump.find_data_dir` finds a `<package>` folder with .obb files ≤3 levels below the APK's folder or ≤2 below its parent (skipping neighboring folders with APKs: other games); an `apk`/`apks` folder counts as part of its game folder. Add the folder again (Analyze again doesn't look for data) |
 | Game hangs at start / never loads although its .obb files are right there: next to the APK, in an `obb` folder beside an `apk` folder inside a `<package>` folder, or a SideQuest backup (`<timestamp>_<versionCode>.apk`) (GitHub #85, #91) | No folder named after the package, so the folder-layout checks found nothing and no OBB was uploaded | `quest_dump.find_data` then looks for the files by name, `(main\|patch).<versionCode>.<package>.obb` (any case), in the APK's folder, its parent and up to 3 levels below each (folders with their own APKs are other games); prefers the folder and files of the APK's own versionCode, else the newest older, else any version. When that folder also holds other things (the APK itself, other games' OBBs), the library entry gets `data_files` and only those files are uploaded, counted and deleted with the game. Add the folder again |
 | Unreal game: `JNI_OnLoad` (OVRPlugin), then silence: no OpenXR instance, no crash, no frames (GitHub #85 TRIANGLE STRATEGY; launch-test finding `missing-obb`) | Installed without its OBB: the manifest says `com.epicgames.ue4.GameActivity.bHasOBBFiles` = true (UE5: `com.epicgames.unreal.…`) but the library has no data folder (`data_dir` null, `data_bytes` 0) | Put the .obb files in a `<package>` (or `obb/`) folder next to the APK, add the folder again, reinstall. Analysis `extra.expects_obb`; the game page, the install question and `frameport scan`/`install` warn; launch tests that sent no frames get the `missing-obb` finding from the library (the game logs nothing). Unity split-binary builds count too (`extra.unity_split`, `analysis/unity_split.py`): an XR-plugin build (Oculus XR Plugin / Unity OpenXR library) without `assets/bin/Data/UnitySubsystems/` in the APK, or BuildSettings listing more scenes than the APK has `levelN` files (globalgamemanagers loose or read from the head of data.unity3d); exact on the 48 Unity APKs of the dumps (13 split, 17 full games; OBBs of full builds are asset bundles or sound banks) |
 | `INSTALL_FAILED_NO_MATCHING_ABIS` | 32-bit-only APK; Frame has no AArch32 | None. PC/Rift version via Revive |
@@ -56,74 +57,78 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Nothing opens; `TWALauncherActivity: Using URL from Manifest (https://…)`, `Creating TwaLauncher for com.oculus.browser`, `NameNotFoundException: com.oculus.browser` (GitHub #86 Mahjong Table VR, triage `web-wrapper`) | The APK is a Trusted Web Activity (Bubblewrap / Meta's PWA packaging): a website that opens in Meta's browser, which Lepton doesn't have | None: open the URL in a browser. Analysis `extra.web_wrapper` (manifest meta-data `android.support.customtabs.trusted.DEFAULT_URL`, resolved through resources.arsc, or androidbrowserhelper's LauncherActivity) → a warning with the URL (not unsupported: the manifest alone never decides) |
 | `UnsatisfiedLinkError` / `cannot locate symbol "ovr_…"` | overport's platform loader lacks Meta platform functions | `frame.ovrstubs` (automatic, generated stubs) |
 | missing `ovrMessageType_ToString` | same, but the game needs a real string | `frame.ovrplatformcompat` (automatic) |
-| The game stays in its built-in language or waits at start although its OBB / files hold language packs (`<tag>.lang`, e.g. `de.lang`) | overport's platform loader answers `ovr_LanguagePack_GetCurrent/SetCurrent` with request id 0, so the game never gets the pack's path | `frame.langpacks` (opt-in, experimental, shown for games whose data has `*.lang`; `native/langpack`, build it with `python native/build.py --only langpack`). Default pack: the one the game applies, else env `FRAMEPORT_LANGPACK=<tag>`, else the only pack; search path override `FRAMEPORT_LANGPACK_DIRS`. Unreal games (Deadpool VR) grey out a pack whose asset `Metadata` differs from the game's version string: the patch writes the APK's versionName as Metadata (env `FRAMEPORT_LANGPACK_META` overrides) and reports the pack under the `/storage/emulated/0/Android/obb/<pkg>/` spelling of its path; with `/sdcard/…` the text switched but the dialogue stayed silent (verified in the headset with Deadpool VR) |
+| The game stays in its built-in language or waits at start although its OBB / files hold language packs (`<tag>.lang`, for example `de.lang`) | overport's platform loader answers `ovr_LanguagePack_GetCurrent/SetCurrent` with request id 0, so the game never gets the pack's path | `frame.langpacks` (opt-in, experimental, shown for games whose data has `*.lang`; `native/langpack`, build it with `python native/build.py --only langpack`). Default pack: the one the game applies, else env `FRAMEPORT_LANGPACK=<tag>`, else the only pack; search path override `FRAMEPORT_LANGPACK_DIRS`. Unreal games (Deadpool VR) gray out a pack whose asset `Metadata` differs from the game's version string: the patch writes the APK's versionName as Metadata (env `FRAMEPORT_LANGPACK_META` overrides) and reports the pack under the `/storage/emulated/0/Android/obb/<pkg>/` spelling of its path; with `/sdcard/…` the text switched but the dialogue stayed silent (verified in the headset with Deadpool VR) |
 | `ClassNotFoundException com.oculus.os.AnalyticsEvent` → abort | Quest telemetry lookup in Meta XR Audio (Unreal build) or native code | `frame.metaxr_telemetry` + `frame.oculusos` (automatic) |
 | `JNI DETECTED ERROR`, `GetStringUTFChars … NULL` | CheckJNI is on because overport marks the app debuggable | `frame.nodebug` |
 | Unreal game quits a few seconds after start (`System.exit`) | ForceQuit after a failed Quest platform check | alternate build with `patch_remove_unreal_force_quit` (`use_alt`) |
-| Unreal game crashes a few seconds after the logo with no backtrace (Unreal's own signal handler hides it: logcat-crash.log empty, Zygote `exited due to signal 11`); the crashing thread is `GameThread`, pc in `libaaudio.so`, lr `libovrplatformloader.so (ovr_Microphone_GetOutputBufferMaxSize+0x10)`; the last platform call is `ovr_Microphone_Create` (e.g. The Walking Dead: Saints & Sinners Ch. 2) | OVRPort's platform loader opens the microphone's AAudio stream only in `ovr_Microphone_Start`, but `GetOutputBufferMaxSize` reads that stream unchecked; Unreal's Oculus voice asks for the size right after `Create` | `frame.ovr_microphone` (NULL check rewritten in place; size 0 until the microphone starts). OVRPort runtime 3.4.3-aa54c3f has the check itself: builds made with it leave the patch out (log "not needed: frame.ovr_microphone", `patches/upstream.py`) |
+| Unreal game crashes a few seconds after the logo with no backtrace (Unreal's own signal handler hides it: logcat-crash.log empty, Zygote `exited due to signal 11`); the crashing thread is `GameThread`, pc in `libaaudio.so`, lr `libovrplatformloader.so (ovr_Microphone_GetOutputBufferMaxSize+0x10)`; the last platform call is `ovr_Microphone_Create` (for example The Walking Dead: Saints & Sinners Ch. 2) | OVRPort's platform loader opens the microphone's AAudio stream only in `ovr_Microphone_Start`, but `GetOutputBufferMaxSize` reads that stream unchecked; Unreal's Oculus voice asks for the size right after `Create` | `frame.ovr_microphone` (NULL check rewritten in place; size 0 until the microphone starts). OVRPort runtime 3.4.3-aa54c3f has the check itself: builds made with it leave the patch out (log "not needed: frame.ovr_microphone", `patches/upstream.py`) |
 | `xrCreateSwapchain` -26 / format unsupported (GLES) | Frame takes only sRGB formats, no MSAA | adapter `swapchain_fix` (default on) |
-| Frames rejected, "Waiting…" forever | a layer uses a failed swapchain or an extension that isn't enabled (e.g. equirect2) | adapter `layer_fix` (default on) |
+| Frames rejected, "Waiting…" forever | a layer uses a failed swapchain or an extension that isn't enabled (for example 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) |
+| 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`), for example 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 theater textures | `frame.swapchain_limit` (default on; guard → 16384 px; triage `swapchain-size-abort`), for example 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 (theaters, 360° videos): `adapter.equirect_emul` (GLES only, per game) |
+| 360° theater / 360° video black or missing (for example 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` (for example 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 (for example 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 | game page "Add videos" / game menu "Add videos and files" (Videos + the app's own folder, hard links) or `frameport frame send <files> --app <pkg>` |
+| One eye gray 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 (for example 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 recenters 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`; patches: `adapter.stable_local` (new LOCAL spaces line up with the first) / `adapter.focus_hold` (on by default: hides dips up to `focus_hold_ms` once the game has been focused for a second; 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 stutters although fps is steady | video frame rate doesn't divide the refresh rate (30 fps at 72 Hz) | `adapter.refresh_rate` (for example 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 (for example 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 | adapter `focus_hold` (on by default; an earlier global debounce made AC Nexus stay black and was removed) |
 | Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | upload in the Files tab (Videos = /sdcard/Movies) and browse folders in the app |
 | Batman: Arkham Shadow closes during smoke-bomb effects; later input-tree corruption | Meta XR Audio Wwise deletes queued metadata still referenced by the current audio frame, then writes through the stale pointer | FrameBridge automatically retires metadata after current-frame references disappear, for the verified AArch64 SDK build only; see [AUDIO_METADATA.md](AUDIO_METADATA.md) |
-| Game stays on a loading or "Waiting" box although it reached FOCUSED; log `FrameBridge: xrEndFrame failed -25` then no more `pacing:` lines (e.g. PowerWash Simulator on some Frames, GitHub #39) | The eye image rect ends a few pixels past its swapchain (Unity rounds the swapchain width, the runtime's recommended size differs per Frame); SteamVR rejects every frame with XR_ERROR_SWAPCHAIN_RECT_INVALID | FrameBridge clamps every projection/quad image rect to its swapchain (`rect_clamp`, default on since 0.11.0; log `rect_clamp: view N image rect clamped`): rebuild + reinstall the game |
-| Unity game (OVRPlugin, GLES) crashes ~10 s in: `FrameBridge: xrCreateSwapchain … faces=6 … result=-2`, OVRPlugin `CreateSwapchain for eye 0: 0x0, 0 stages`, then render-thread SIGSEGV in memset ← libOVRPlugin ← `ovrp_EndFrame4` (libgallium/ANR follow; e.g. Budget Cuts Ultimate, GitHub #107); triage `cube-swapchain-refused` | The game shows a cube-map layer (OVROverlay cubemap); the Frame's runtime has no cube layers and refuses cube swapchains (XR_ERROR_RUNTIME_FAILURE); OVRPlugin doesn't check and writes into the image list it never got | FrameBridge `cube_standin` (default on): a refused cube swapchain is served as a GL cube map in the game's context and its layers are dropped (log `cube_standin: runtime refused …`): rebuild + reinstall. GLES only; a Vulkan game keeps the error |
+| Game stays on a loading or "Waiting" box although it reached FOCUSED; log `FrameBridge: xrEndFrame failed -25` then no more `pacing:` lines (for example PowerWash Simulator on some Frames, GitHub #39) | The eye image rect ends a few pixels past its swapchain (Unity rounds the swapchain width, the runtime's recommended size differs per Frame); SteamVR rejects every frame with XR_ERROR_SWAPCHAIN_RECT_INVALID | FrameBridge clamps every projection/quad image rect to its swapchain (`rect_clamp`, default on since 0.11.0; log `rect_clamp: view N image rect clamped`): rebuild + reinstall the game |
+| Unity game (OVRPlugin, GLES) crashes ~10 s in: `FrameBridge: xrCreateSwapchain … faces=6 … result=-2`, OVRPlugin `CreateSwapchain for eye 0: 0x0, 0 stages`, then render-thread SIGSEGV in memset ← libOVRPlugin ← `ovrp_EndFrame4` (libgallium/ANR follow; for example Budget Cuts Ultimate, GitHub #107); triage `cube-swapchain-refused` | The game shows a cube-map layer (OVROverlay cubemap); the Frame's runtime has no cube layers and refuses cube swapchains (XR_ERROR_RUNTIME_FAILURE); OVRPlugin doesn't check and writes into the image list it never got | FrameBridge `cube_standin` (default on): a refused cube swapchain is served as a GL cube map in the game's context and its layers are dropped (log `cube_standin: runtime refused …`): rebuild + reinstall. GLES only; a Vulkan game keeps the error |
 | Game (Unity, GLES) freezes, `zink: DEVICE LOST` | multisampled render-to-texture hangs the GPU | `frame.unity_no_msaa`; if it persists: unfixable → PC version |
 | Unreal GLES game crashes ~3 s after start: `Fatal signal 11 … fault addr 0x10000 in tid … (RHIThread)`, `#01 … libgallium_dri.so` (GitHub #83 Star Wars Pinball VR, triage `unreal-msrtt-crash`) | Unreal's mobile MSAA renders through multisampled render-to-texture; Zink's `find_rp_state` then indexes `rendering_state_cache[6]` one past its end (sample count ≥ 32) and calls a junk hash function (0x10000). Mesa bug (no bounds check) | `frame.unreal_gl_shim` (GL shim with `gl_hide_msrtt`, multiview kept for Unreal: Unreal 4.25 only enables multiview with GL_OVR_multiview, GL_OVR_multiview2 **and** GL_OVR_multiview_multisampled_render_to_texture, so the shim keeps the last one visible for Unreal and maps glFramebufferTextureMultisampleMultiviewOVR to the single-sampled glFramebufferTextureMultiviewOVR; log `multiview multisampled render-to-texture (N samples) drawn single-sampled`) |
-| Crash with `SIGILL (ILL_ILLOPN)` and `*pc=0xd50323bf` (autiasp), e.g. on Unreal's HttpManager thread (GitHub #83 Star Wars Pinball VR, triage `pac-unpaired`) | The engine's OpenSSL ARMv8 assembly has autiasp without a matching paciasp (libUE4.so: 38 paciasp, 40 autiasp; Poly1305 NEON). Quest CPUs treat PAC hints as NOPs, the Frame's CPU checks them | `frame.pac_hints`: in a library with unpaired counts every paciasp/autiasp becomes a NOP (in place) |
+| Crash with `SIGILL (ILL_ILLOPN)` and `*pc=0xd50323bf` (autiasp), for example on Unreal's HttpManager thread (GitHub #83 Star Wars Pinball VR, triage `pac-unpaired`) | The engine's OpenSSL ARMv8 assembly has autiasp without a matching paciasp (libUE4.so: 38 paciasp, 40 autiasp; Poly1305 NEON). Quest CPUs treat PAC hints as NOPs, the Frame's CPU checks them | `frame.pac_hints`: in a library with unpaired counts every paciasp/autiasp becomes a NOP (in place) |
 | launch.log ends with `logcat: Unexpected EOF!` right after `Waiting for app …`; the game runs, but Steam's "Resume game" menu isn't closed and the launch test shows nothing (Vader Immortal on Lepton 3.0.5, Under Cover on 2.8.14; about 1 launch in 50) | Lepton's logcat mirror died | Agent v67 `_logcat_keeper` (started by launch.sh, added to older launchers by `upgrade_launchers`) reads the container's logcat itself (`podman exec lepton-steamlaunch-<appid> logcat -v threadtime -T 2000`) and appends it to launch.log; log `<base>/logcat-keeper.log` |
 | A game no longer starts after a reinstall that was launch-tested right away: logcat `Zip: EOCD not found, …/base.apk is not zip` / `Failed to parse …base.apk`, no `Start proc` for the game (VR HOT, 2026-10-09) | The launch test's 45 s ran from the launcher, but the first start after an APK change spends ~1–2 min booting Lepton and installing the app: stopping the container mid-install left a broken installed copy | Agent v68: the test window counts from Lepton's `Waiting for app` (at most 240 s extra for boot + install). Repair a broken one: `touch <base>/lepton-app/game.apk` (Lepton re-installs it on the next start) |
-| Unreal game (OVRPlugin) never starts VR: launch.log has `OVRPlugin: JNI_OnLoad` but never `CompositorOpenXR::PreInitialize`, no OpenXR session, then a crash a few seconds in (e.g. Star Wars Pinball VR, UE 4.25: null pointer in `FSceneRenderer::GetMultiViewSceneColor`, GitHub #83) | Unreal's Oculus module looks up every `ovrp_*` function of the OVRPlugin it was built against (`InitializeOculusPluginWrapper`, all ANDed); OVRPort's OpenXR OVRPlugin lacks a few old ones (UE 4.25 / OVRPlugin 1.44: `ovrp_GetPTWNear`), so the wrapper fails and OculusHMD is never pre-initialised | `frame.unreal_ovrp_entrypoints` (suggested when analysis `unreal_ovrp_lookups` name functions the shipped OVRPlugin lacks): generated `libfp_ovrpstubs.so` (DT_NEEDED of libOVRPlugin.so; dlsym on the plugin's handle searches its dependencies) with a stand-in per missing name returning ovrpFailure (-1000); build note lists the names |
-| Only the Android home screen shows; the log has Unity's VR device as `None` (e.g. Accounting+, Unity 2017) | Unity 2017–2018 built-in Oculus support starts VR only when `com.oculus.systemactivities` is installed; Lepton has no Meta system apps, so Unity falls back to non-VR | `frame.unity_oculus_check`: that package name in libunity.so → `android`, plus `native/ovrpshim` (libfp_ovrp.so): Unity 2017's legacy frame loop (`ovrp_Update2`/`ovrp_BeginFrame`) never calls `ovrp_WaitToBeginFrame`, so without the shim no `xrWaitFrame` happens, `CompositorOpenXR::Update … outside of frame bounds` floods the log and the dashboard freezes. With it: log `ovrp frame loop shim: waited for frame N`, ~71 fps. Accounting+ then stops at "press any button" although its OVRInput gets clean input (`INPUT_PROBE` in the patch logs connected controllers/buttons/input focus per call) — unresolved |
-| Black flat window, then a GPU hang: kernel `hangcheck detected gpu lockup` (offending task the game), `zink: DEVICE LOST`, Unity render-thread crash; `outside of frame bounds` thousands of times a second (e.g. BattleSisters, Unity 2019.4) | Unity 2019 on its built-in VR (no `libOculusXRPlugin.so`) uses the same legacy frame loop as Unity 2017: no `xrWaitFrame`, the render thread floods the GPU | `frame.unity_oculus_check` adds the ovrpshim frame wait for these too (revision 2) |
-| Unity built-in VR game (with `frame.unity_oculus_check`) freezes at a scene switch: the log stops after `Boot: Activating Scene: …`, the process stays alive, every thread sleeps (e.g. Sniper Elite VR, Unity 2019.4) | The shim's `xrWaitFrame` blocks until the previously waited frame is begun; Unity skipped beginning it at the scene switch and its render thread then waited for the main thread (gdb: UnityMain in vrclient `CSxrSession::StartNextFrame` ← `ovrp_WaitToBeginFrame` ← `fpov_Update2`). OVRPlugin also only begins the frame index it waited for | `frame.unity_oculus_check` revision 5: libunity.so's `ovrp_BeginFrame`/`ovrp_EndFrame` go through the shim, which waits ≤ 50 ms for the last waited frame to begin, else skips the wait (log `the last waited frame wasn't begun`), and gives a begin/end of another index the waited one |
-| Unity built-in VR game: the hands/weapons trail the controllers by centimetres when moving (headset fine, 72 fps), e.g. Sniper Elite VR | Unity's physics-step `ovrp_Update2` (prediction 0) makes OVRPlugin locate the nodes at the monotonic clock's "now", the XrTime base on a Quest but 0.05–0.9 s behind the Frame's XrTime; the runtime extrapolates backwards and the render-step reads after it get those poses too. A larger prediction is capped by OVRPlugin (~0.07 s) | `frame.unity_oculus_check` revision 5 holds the physics-step update back: both steps read the render update's display-time poses |
-| OVRPlugin game: the hands lag behind the controllers (also with `ovrp_hold_physics` on or off; rendering fine), e.g. BattleSisters | OVRPlugin passes its monotonic-clock "now" on as the OpenXR time (OVRPort's dispatcher converts XR_KHR_convert_timespec_time 1:1: the Frame's runtime lacks it, and FrameBridge's emulation is never asked), but the Frame's XrTime runs ahead of CLOCK_MONOTONIC (2.56 s on SteamOS 0.4.5): with `pose_debug=1` the hand spaces show `time - predicted display time -2564 ms`; BattleSisters also asks for its head at XrTime 0.1 s every frame | `adapter.pose_time_fix` (FrameBridge, suggested for Unity built-in OVRPlugin games): a located time nearer the monotonic clock than XrTime's "now" is moved by the clock offset measured at xrWaitFrame, one more than 0.5 s before the display time goes to "now" (log `pose_time_fix: …`; `pose_debug=1` counts both per 5 s). Once a build has this FrameBridge it is toggled in settings.conf (no rebuild) The offset is the largest of the last ~2 s of xrWaitFrame samples (hitches made single samples dip by up to 2.5 s and pushed fixed times into the future); far-past requests get the frame's display time. Headless survey of 54 games (2026-10-09): no head/view request on the monotonic clock in any other game; UE4 OVRPlugin 1.89 games (Robo Recall, Vader, Phantom, Time Stall) and The Room VR ask for head/views at XrTime ≈ 0 every frame, which works today; hands only show in the headset. Suggested for Unity built-in Oculus games only. A time equal (±1 ms) to one of the last 6 predicted display times is never moved, and monotonic times are only told apart when the clocks are more than 4 display periods apart and the time is clearly nearer the monotonic "now" (GitHub #49: on a Frame with XrTime only ~68 ms ahead, a display-time request after a hitch was moved +67.7 ms) |
-| Unreal game stuck on a loading image after the intro, frames keep coming (72 fps), no crash (e.g. Vader Immortal) | suspect: a Meta Platform SDK request no message ever answers | diagnostics: `frame.ovr_trace` (opt-in) logs every `ovr_*` call, the answers `ovr_PopMessage` returns and every 10 s the unanswered requests (`fp_ovrtrace` in launch.log). Never fake an entitlement answer |
-| Own-engine game crashes in `libVkLayer_fossilize.so` (Fossilize's recording thread, e.g. Roblox) | same as Deadpool VR: uninitialised pointers in what Fossilize records | `frame.vk_sanitize` now also covers own-engine libraries that load `libvulkan.so` by name |
-| Crash right after the game gets focus, in `vrclient.so … UpdateActionStateInternal` / `sxr_xrSyncActions` (e.g. Myst) | a race in the Frame runtime's input code on the first sync after focus (not every launch) | adapter `sync_guard` (input syncs one at a time with event polling, paused 250 ms after FOCUSED) |
-| View jumps sideways / game pauses or freezes for a moment every few seconds (e.g. Blade & Sorcery, BattleGlide) | the Frame drops focus for ~0.5 s (FOCUSED→VISIBLE→SYNCHRONIZED); games pause or re-align the player (`OnVRPresence … Teleport`) | adapter `focus_hold` |
-| SDL / LÖVE app crashes at start: `NullPointerException … ClipboardManager.addPrimaryClipChangedListener` in `SDLClipboardHandler.<init>` (e.g. Dramatic Shape) | Lepton's Android has no clipboard service (`service check clipboard`: not found) | `frame.sdl_clipboard` (that call → nops in classes.dex, in place, `apk/dex.py`); reproduced and verified with LÖVE for Android 11.5 |
-| Game crashes at start: `java.lang.NoSuchMethodError: No virtual method getAvailableCommunicationDevices()… in class Landroid/media/AudioManager` at `com.vivox.sdk.AudioChangeListener.checkAudioRouteAndApplyChanges` (e.g. Green Hell VR, GitHub #101); triage `vivox-api31` | Newer Vivox (voice chat) builds call Android 12 audio-routing methods without a version check; Lepton is Android 11. Older Vivox builds (Eleven Table Tennis, BattleSisters) don't have that code | `frame.vivox_audio_route` (suggested by analysis `vivox_api31`): every AudioChangeListener method that calls one of them returns at once (`Dex.return_early`: return-void / `const/4 v0, 0; return v0`, in place); voice chat keeps the default audio route |
-| Controllers do nothing (e.g. stuck on a setup screen); log: `xrSuggestInteractionProfileBindings … XR_ERROR_PATH_UNSUPPORTED` | the game only suggests bindings for Meta's newer profiles (Touch Plus / Touch Pro); the Frame's Android runtime knows `oculus/touch_controller`, not those | adapter `profile_remap` (default on): the bindings are suggested again for Touch (log: `controller profile … -> oculus/touch_controller`) |
-| Some buttons do nothing or the wrong thing (e.g. a Quest game's X/Y on the Frame's left controller) | the game binds only Quest Touch and SteamVR maps Touch onto the Frame controllers with its own remap (Touch left X/Y land on the d-pad, right X and Y repeat B), or the runtime rejected a profile or an input call | turn on adapter `input_diag` (diagnostics, off by default; `frameport settings <pkg> input_diag=1`) and look for `input_diag:` lines: `bindings: <profile> accepted` or `unsupported: interaction profile <profile> -> <result>` with the rejected paths, `bindings: /user/hand/<hand> uses <profile>`, `unsupported: function <name>`, `unsupported: xrCreateAction -> <result> (<action>)` |
-| Unity game hangs or the whole Frame restarts (e.g. in a menu); log: `The current MSAA level is 0, but the recommended MSAA level is 4. Switching to the recommended level.` (e.g. Lucky's Tale) | Meta's OVRManager (`useRecommendedMSAALevel`) turns 4x MSAA on at runtime, past QualitySettings; multisampled render-to-texture on GLES/Zink hangs the GPU | `frame.unity_runtime_msaa_off` (Cpp2IL: `OVRDisplay.get_recommendedMSAALevel` → 0) |
-| Unity game: one eye shows only effects or grey, the other is fine (e.g. I Am Cat, Oculus XR Plugin on GLES) | the game's single-pass multiview rendering goes wrong for array slice 1 (the adapter submits both slices correctly) | `frame.unity_multipass` (Cpp2IL: `OculusSettings.GetStereoRenderingMode` → MultiPass); `swap_eyes=1` tells whether the game or the adapter is at fault |
+| Unreal game (OVRPlugin) never starts VR: launch.log has `OVRPlugin: JNI_OnLoad` but never `CompositorOpenXR::PreInitialize`, no OpenXR session, then a crash a few seconds in (for example Star Wars Pinball VR, UE 4.25: null pointer in `FSceneRenderer::GetMultiViewSceneColor`, GitHub #83) | Unreal's Oculus module looks up every `ovrp_*` function of the OVRPlugin it was built against (`InitializeOculusPluginWrapper`, all ANDed); OVRPort's OpenXR OVRPlugin lacks a few old ones (UE 4.25 / OVRPlugin 1.44: `ovrp_GetPTWNear`), so the wrapper fails and OculusHMD is never pre-initialized | `frame.unreal_ovrp_entrypoints` (suggested when analysis `unreal_ovrp_lookups` name functions the shipped OVRPlugin lacks): generated `libfp_ovrpstubs.so` (DT_NEEDED of libOVRPlugin.so; dlsym on the plugin's handle searches its dependencies) with a stand-in per missing name returning ovrpFailure (-1000); build note lists the names |
+| Only the Android home screen shows; the log has Unity's VR device as `None` (for example Accounting+, Unity 2017) | Unity 2017–2018 built-in Oculus support starts VR only when `com.oculus.systemactivities` is installed; Lepton has no Meta system apps, so Unity falls back to non-VR | `frame.unity_oculus_check`: that package name in libunity.so → `android`, plus `native/ovrpshim` (libfp_ovrp.so): Unity 2017's legacy frame loop (`ovrp_Update2`/`ovrp_BeginFrame`) never calls `ovrp_WaitToBeginFrame`, so without the shim no `xrWaitFrame` happens, `CompositorOpenXR::Update … outside of frame bounds` floods the log and the dashboard freezes. With it: log `ovrp frame loop shim: waited for frame N`, ~71 fps. Accounting+ then stops at "press any button" although its OVRInput gets clean input (`INPUT_PROBE` in the patch logs connected controllers/buttons/input focus per call) — unresolved |
+| Stuck on the loading screen or quits at start; `Unable to open archive file`, `is corrupted! Remove it and launch unity again` or `Failed to read data for the AssetBundle` in launch.log (for example Batman, GitHub #155) | The game's data folder (OBB) is incomplete or from another version than the APK | Copy the whole data folder again from the same install as the APK, add the game again, reinstall (triage `unity-data-missing`) |
+| Black flat window, then a GPU hang: kernel `hangcheck detected gpu lockup` (offending task the game), `zink: DEVICE LOST`, Unity render-thread crash; `outside of frame bounds` thousands of times a second (for example BattleSisters, Unity 2019.4) | Unity 2019 on its built-in VR (no `libOculusXRPlugin.so`) uses the same legacy frame loop as Unity 2017: no `xrWaitFrame`, the render thread floods the GPU | `frame.unity_oculus_check` adds the ovrpshim frame wait for these too (revision 2) |
+| Unity built-in VR game (with `frame.unity_oculus_check`) freezes at a scene switch: the log stops after `Boot: Activating Scene: …`, the process stays alive, every thread sleeps (for example Sniper Elite VR, Unity 2019.4) | The shim's `xrWaitFrame` blocks until the previously waited frame is begun; Unity skipped beginning it at the scene switch and its render thread then waited for the main thread (gdb: UnityMain in vrclient `CSxrSession::StartNextFrame` ← `ovrp_WaitToBeginFrame` ← `fpov_Update2`). OVRPlugin also only begins the frame index it waited for | `frame.unity_oculus_check` revision 5: libunity.so's `ovrp_BeginFrame`/`ovrp_EndFrame` go through the shim, which waits ≤ 50 ms for the last waited frame to begin, else skips the wait (log `the last waited frame wasn't begun`), and gives a begin/end of another index the waited one |
+| Unity built-in VR game: the hands/weapons trail the controllers by centimetres when moving (headset fine, 72 fps), for example Sniper Elite VR | Unity's physics-step `ovrp_Update2` (prediction 0) makes OVRPlugin locate the nodes at the monotonic clock's "now", the XrTime base on a Quest but 0.05–0.9 s behind the Frame's XrTime; the runtime extrapolates backwards and the render-step reads after it get those poses too. A larger prediction is capped by OVRPlugin (~0.07 s) | `frame.unity_oculus_check` revision 5 holds the physics-step update back: both steps read the render update's display-time poses |
+| OVRPlugin game: the hands lag behind the controllers (also with `ovrp_hold_physics` on or off; rendering fine), for example BattleSisters | OVRPlugin passes its monotonic-clock "now" on as the OpenXR time (OVRPort's dispatcher converts XR_KHR_convert_timespec_time 1:1: the Frame's runtime lacks it, and FrameBridge's emulation is never asked), but the Frame's XrTime runs ahead of CLOCK_MONOTONIC (2.56 s on SteamOS 0.4.5): with `pose_debug=1` the hand spaces show `time - predicted display time -2564 ms`; BattleSisters also asks for its head at XrTime 0.1 s every frame | `adapter.pose_time_fix` (FrameBridge, suggested for Unity built-in OVRPlugin games): a located time nearer the monotonic clock than XrTime's "now" is moved by the clock offset measured at xrWaitFrame, one more than 0.5 s before the display time goes to "now" (log `pose_time_fix: …`; `pose_debug=1` counts both per 5 s). Once a build has this FrameBridge it is toggled in settings.conf (no rebuild) The offset is the largest of the last ~2 s of xrWaitFrame samples (hitches made single samples dip by up to 2.5 s and pushed fixed times into the future); far-past requests get the frame's display time. Headless survey of 54 games (2026-10-09): no head/view request on the monotonic clock in any other game; UE4 OVRPlugin 1.89 games (Robo Recall, Vader, Phantom, Time Stall) and The Room VR ask for head/views at XrTime ≈ 0 every frame, which works today; hands only show in the headset. Suggested for Unity built-in Oculus games only. A time equal (±1 ms) to one of the last 6 predicted display times is never moved, and monotonic times are only told apart when the clocks are more than 4 display periods apart and the time is clearly nearer the monotonic "now" (GitHub #49: on a Frame with XrTime only ~68 ms ahead, a display-time request after a hitch was moved +67.7 ms) |
+| Unreal game stuck on a loading image after the intro, frames keep coming (72 fps), no crash (for example Vader Immortal) | suspect: a Meta Platform SDK request no message ever answers | diagnostics: `frame.ovr_trace` (opt-in) logs every `ovr_*` call, the answers `ovr_PopMessage` returns and every 10 s the unanswered requests (`fp_ovrtrace` in launch.log). Never fake an entitlement answer |
+| Own-engine game crashes in `libVkLayer_fossilize.so` (Fossilize's recording thread, for example Roblox) | same as Deadpool VR: uninitialised pointers in what Fossilize records | `frame.vk_sanitize` now also covers own-engine libraries that load `libvulkan.so` by name |
+| Crash right after the game gets focus, in `vrclient.so … UpdateActionStateInternal` / `sxr_xrSyncActions` (for example Myst) | a race in the Frame runtime's input code on the first sync after focus (not every launch) | adapter `sync_guard` (input syncs one at a time with event polling, paused 250 ms after FOCUSED) |
+| View jumps sideways / game pauses or freezes for a moment every few seconds (for example Blade & Sorcery, BattleGlide) | the Frame drops focus for ~0.5 s (FOCUSED→VISIBLE→SYNCHRONIZED); games pause or re-align the player (`OnVRPresence … Teleport`) | adapter `focus_hold` |
+| SDL / LÖVE app crashes at start: `NullPointerException … ClipboardManager.addPrimaryClipChangedListener` in `SDLClipboardHandler.<init>` (for example Dramatic Shape) | Lepton's Android has no clipboard service (`service check clipboard`: not found) | `frame.sdl_clipboard` (that call → nops in classes.dex, in place, `apk/dex.py`); reproduced and verified with LÖVE for Android 11.5 |
+| Game crashes at start: `java.lang.NoSuchMethodError: No virtual method getAvailableCommunicationDevices()… in class Landroid/media/AudioManager` at `com.vivox.sdk.AudioChangeListener.checkAudioRouteAndApplyChanges` (for example Green Hell VR, GitHub #101); triage `vivox-api31` | Newer Vivox (voice chat) builds call Android 12 audio-routing methods without a version check; Lepton is Android 11. Older Vivox builds (Eleven Table Tennis, BattleSisters) don't have that code | `frame.vivox_audio_route` (suggested by analysis `vivox_api31`): every AudioChangeListener method that calls one of them returns at once (`Dex.return_early`: return-void / `const/4 v0, 0; return v0`, in place); voice chat keeps the default audio route |
+| Controllers do nothing (for example stuck on a setup screen); log: `xrSuggestInteractionProfileBindings … XR_ERROR_PATH_UNSUPPORTED` | the game only suggests bindings for Meta's newer profiles (Touch Plus / Touch Pro); the Frame's Android runtime knows `oculus/touch_controller`, not those | adapter `profile_remap` (default on): the bindings are suggested again for Touch (log: `controller profile … -> oculus/touch_controller`) |
+| Some buttons do nothing or the wrong thing (for example a Quest game's X/Y on the Frame's left controller) | the game binds only Quest Touch and SteamVR maps Touch onto the Frame controllers with its own remap (Touch left X/Y land on the d-pad, right X and Y repeat B), or the runtime rejected a profile or an input call | turn on adapter `input_diag` (diagnostics, off by default; `frameport settings <pkg> input_diag=1`) and look for `input_diag:` lines: `bindings: <profile> accepted` or `unsupported: interaction profile <profile> -> <result>` with the rejected paths, `bindings: /user/hand/<hand> uses <profile>`, `unsupported: function <name>`, `unsupported: xrCreateAction -> <result> (<action>)` |
+| Unity game hangs or the whole Frame restarts (for example in a menu); log: `The current MSAA level is 0, but the recommended MSAA level is 4. Switching to the recommended level.` (for example Lucky's Tale) | Meta's OVRManager (`useRecommendedMSAALevel`) turns 4x MSAA on at runtime, past QualitySettings; multisampled render-to-texture on GLES/Zink hangs the GPU | `frame.unity_runtime_msaa_off` (Cpp2IL: `OVRDisplay.get_recommendedMSAALevel` → 0) |
+| Unity game: one eye shows only effects or gray, the other is fine (for example I Am Cat, Oculus XR Plugin on GLES) | the game's single-pass multiview rendering goes wrong for array slice 1 (the adapter submits both slices correctly) | `frame.unity_multipass` (Cpp2IL: `OculusSettings.GetStereoRenderingMode` → MultiPass); `swap_eyes=1` tells whether the game or the adapter is at fault |
 | Setup/intro loops every launch (Espire 2) | save folders created without write permission | launcher repairs permissions every 2 s (built in) |
 | VrApi bridge: never enters VR | Frame reaches FOCUSED later than Quest; tracking only when worn | bridge waits 30 s; test in the headset |
-| Unreal game (ILMxLAB, e.g. Vader Immortal) plays its intro, then stays on its loading card (portrait + progress bar) at 72 fps and ignores input (GitHub #49) | the menu waits for `UVRUtils::GetQuestShaderPrecompilePercent()` to reach 100 %; the precompile only starts when `IsRunningOnSantaCruz()` (a Quest), the other branch returns 0.0 | `frame.unreal_quest_precompile` (non-Quest branch returns 1.0; found by Klownicle); suggested when the engine exports that function (analysis `unreal_quest_gates`) |
+| Unreal game (ILMxLAB, for example Vader Immortal) plays its intro, then stays on its loading card (portrait + progress bar) at 72 fps and ignores input (GitHub #49) | the menu waits for `UVRUtils::GetQuestShaderPrecompilePercent()` to reach 100 %; the precompile only starts when `IsRunningOnSantaCruz()` (a Quest), the other branch returns 0.0 | `frame.unreal_quest_precompile` (non-Quest branch returns 1.0; found by Klownicle); suggested when the engine exports that function (analysis `unreal_quest_gates`) |
+| Video in a game or player stutters, falls behind or drops to a few fps (4K/8K, for example a video player's 360° video, Batman's cutscenes); `OMX.google.*` / `c2.android.*` decoders in the log | Lepton's Android has only software decoders | `frame.hw_video_decode` (suggested when the APK uses MediaCodec/ExoPlayer/VLC; no APK change, reinstall): `OMX.frameport.{avc,hevc,vp9}.decoder` on the Frame's Iris hardware (H.264 High, HEVC Main, VP9 profile 0 up to 4096x2304; 8-bit; up to 8192 px), mounted into this game's container only (log `Iris hardware video/… decoder active`; launch.log `FramePort video: loading the Iris hardware codec plugin`). `Iris … unavailable` / `initialization failed (-12)` (triage `hw-video-decoder-busy`): another decoder holds the hardware, usually Steam's own hardware video decoding: turn it off in Steam, restart Steam. Video broken with it: Settings → Installing → Hardware video decoding off (all games) or `FRAMEPORT_NO_HW_VIDEO=1 %command%` (one game) |

 ## Picture problems (headset on)
 | Symptom | Cause | Fix |
 |---|---|---|
-| Found after playing: the game page's "Last session" (or `frameport session <pkg>`) lists a finding (agent v70 `session_log`: the newest `plays.log` session's launch.log, ≤4 MB, + its crash logcat + kernel GPU lines) | launch tests never reach FOCUSED or gameplay; the same `catalog/triage.yaml` signatures (sync_guard, pac_hints, unreal_gl_shim, vk_spec_fixes, …) now also run on real sessions, plus the frame-rate and focus-dip findings below | "Try this fix" (FrameBridge settings: written on the Frame at once via `set_settings`, used from the next start) / "Rebuild with this fix" (APK patches); launch-test sessions (`test <unix>` in plays.log) are skipped |
+| Found after playing: the game page's "Last session" (or `frameport session <pkg>`) lists a finding (agent v70 `session_log`: the newest `plays.log` session's launch.log, ≤4 MB, + its crash logcat + kernel GPU lines) | launch tests never reach FOCUSED or gameplay; the same `catalog/triage.yaml` signatures (sync_guard, pac_hints, unreal_gl_shim, vk_spec_fixes, …) now also run on real sessions, plus the frame-rate and focus-dip findings below | "Try this setting" (FrameBridge settings: written on the Frame at once via `set_settings`, used from the next start) / "Rebuild with this patch" (APK patches); launch-test sessions (`test <unix>` in plays.log) are skipped |
 | Textures flicker, jump or smear while moving in an OVRPlugin game that renders space-warp swapchains (`xrCreateSwapchain 376x376 format=97` / `format=129`; triage `space-warp-used`, info + question) | Application SpaceWarp: half the frames plus motion vectors; the Frame's reprojection of them misbehaves (Into The Radius 2, Metro Awakening) | adapter `hide_space_warp=1`; offered as "Did textures flicker…?" after a play session, never applied on its own |
-| The game froze or closed and the kernel log has `hangcheck` / GPU fault / `msm_drm … recover` lines during the session (triage `gpu-hang`, play sessions only) | a shader or effect hangs the Frame's GPU (e.g. Vader Immortal's lightspeed jump) | capture the shaders (`adapter.zink_shader_dump=1`, GLES) and send a problem report; the maintainer adds a `zink_shader_fix` / `vk_shader_fix` catalog entry. `zink-device-lost` keeps its MSAA suggestions |
+| The game froze or closed and the kernel log has `hangcheck` / GPU fault / `msm_drm … recover` lines during the session (triage `gpu-hang`, play sessions only) | a shader or effect hangs the Frame's GPU (for example Vader Immortal's lightspeed jump) | capture the shaders (`adapter.vk_shader_dump=1` Vulkan, `adapter.zink_shader_dump=1` OpenGL ES: triage keeps the one matching the session's swapchain formats), play to the hang again and send a problem report (diagnostics carry the newest dumped modules); the maintainer adds a `vk_shader_fix` / `zink_shader_fix` catalog entry. `zink-device-lost` keeps its MSAA suggestions |
 | The game keeps pausing or recentring for a moment while worn (session finding `focus-dips`: ≥3 `focus: back after N ms` lines longer than the game's focus_hold_ms, up to 5 s) | the Frame's wear sensor flickers "HMD off"; FrameBridge logs every runtime focus loss/return (always, before focus_hold) | `adapter.focus_hold_ms=<longest dip + 250 ms, in 500 ms steps, ≤5000>` (or `adapter.focus_hold=1` when off) |
 | Judder or smearing on head turns; FrameBridge pacing below the display rate (session finding `slow-frames`: >30 % of the 5 s windows under 90 % of the nearest refresh rate ≥ the session's 90th-percentile fps, after the first two windows, ≥1 min) | the game renders below the refresh rate; the runtime reprojects | `adapter.scale=<current × 0.85>` first, then `frame.unity_runtime_msaa_off` (Unity) / `adapter.hide_space_warp` (Unreal 5 + OVRPlugin) |
-| Unreal game (ILMxLAB, e.g. Vader Immortal): controllers track but grip/trigger do nothing, grabbing never works (Unreal's own input values move, the game's stay 0) | `URPOCKeyMapManagerComponent` picks the Quest or the Gear VR key set by `IsRunningOnSantaCruz()`; on the Frame it takes Gear VR, empty in a Quest build | `frame.unreal_quest_keymap` (the Oculus case keeps the Quest set, for action and axis mappings; found by Klownicle, GitHub #49) |
-| The hands' thumbs never move when you touch the thumbstick or buttons (Unreal `ThumbUp` stays 1, e.g. Vader Immortal) | OVRPlugin reports thumb proximity from XR_FB_touch_controller_proximity, which the Frame's runtime lacks; OVRPort's loader offers it anyway and the proximity actions never get a binding | adapter `proximity_emul=1` (thumb proximity from the touch inputs: thumbstick, face buttons, thumb rest; 2 = also the index finger from trigger touch); log `proximity_emul: finger proximity bound to touch`. **For UE4 Oculus games this didn't animate the thumbs** (Vader, GitHub #49): use `frame.unreal_thumb_touch` (found by Klownicle): `OculusInput::FOculusInput::SendControllerEvents` computes ThumbUp from NearTouches (masks 0x2/0x8); the patch makes it read Touches (the slot 4 bytes before) with masks 0x0f00 (X/Y/stick/thumb rest) / 0x000f (A/B/stick/thumb rest), keeping the inversion; three instructions, matched exactly (build note `OculusInput ThumbUp: from the capacitive touches`). Matches Vader Immortal Ep. I, Robo Recall, Phantom: Covert Ops, Time Stall, Star Wars: Tales from the Galaxy's Edge; newer UE4 builds (e.g. Asgard's Wrath 2, RE4, In Death) compile it differently (shared mask registers) and aren't matched |
-| OpenGL ES game: the GPU hangs at one effect (freeze/exit, compositor watchdog, e.g. Vader Immortal's lightspeed jump) | a shader (as Zink compiles it) reads loop counters/accumulators before setting them | capture the SPIR-V (adapter `zink_shader_dump=1` writes every module to `files/fp_spirv/`, or a GPU capture), then a `zink_shader_fix` entry (same format as `vk_shader_fix`) + `frame.zink_shader_fix` (Vulkan layer under Zink, activated through GraphicsEnv's debug layer list); log `shader fix layer: fixed shader module N`; triage `zink-shader-fix-mismatch` when a Frame update changed the driver's output |
+| Unreal game (ILMxLAB, for example Vader Immortal): controllers track but grip/trigger do nothing, grabbing never works (Unreal's own input values move, the game's stay 0) | `URPOCKeyMapManagerComponent` picks the Quest or the Gear VR key set by `IsRunningOnSantaCruz()`; on the Frame it takes Gear VR, empty in a Quest build | `frame.unreal_quest_keymap` (the Oculus case keeps the Quest set, for action and axis mappings; found by Klownicle, GitHub #49) |
+| The hands' thumbs never move when you touch the thumbstick or buttons (Unreal `ThumbUp` stays 1, for example Vader Immortal) | OVRPlugin reports thumb proximity from XR_FB_touch_controller_proximity, which the Frame's runtime lacks; OVRPort's loader offers it anyway and the proximity actions never get a binding | adapter `proximity_emul=1` (thumb proximity from the touch inputs: thumbstick, face buttons, thumb rest; 2 = also the index finger from trigger touch); log `proximity_emul: finger proximity bound to touch`. **For UE4 Oculus games this didn't animate the thumbs** (Vader, GitHub #49): use `frame.unreal_thumb_touch` (found by Klownicle): `OculusInput::FOculusInput::SendControllerEvents` computes ThumbUp from NearTouches (masks 0x2/0x8); the patch makes it read Touches (the slot 4 bytes before) with masks 0x0f00 (X/Y/stick/thumb rest) / 0x000f (A/B/stick/thumb rest), keeping the inversion; three instructions, matched exactly (build note `OculusInput ThumbUp: from the capacitive touches`). Matches Vader Immortal Ep. I, Robo Recall, Phantom: Covert Ops, Time Stall, Star Wars: Tales from the Galaxy's Edge; newer UE4 builds (for example Asgard's Wrath 2, RE4, In Death) compile it differently (shared mask registers) and aren't matched |
+| Vulkan game (Unreal / own engine with the Vulkan shim): the GPU hangs at one effect or cutscene (kernel `hangcheck detected gpu lockup`, freeze/exit; for example a VR4 cutscene, GitHub #140) | a SPIR-V shader reads a loop counter/accumulator before setting it (VR4's campaign shader, GitHub #10) | adapter `vk_shader_dump=1` (`frame.vk_sanitize`'s shim; log `vk shim: dumping SPIR-V modules to …`) writes every distinct module once to `files/fp_vk_shaders/<size>_<sha256>.spv` + `index.txt` (`<seq> <ms> <unix ms> <name> new\|known\|again`); play to the hang, collect diagnostics (`target/shaders/fp_vk_shaders/`, newest 4 MB) and take the modules first created (`new`) shortly before the kernel's hangcheck time; disassemble (`spirv-dis`), find the variable read before its first store, write a `vk_shader_fix` (`<size>:<sha256>:<byte offset>:<words>` = inserted OpStores; log `vk shim: fixed shader module`); switch the dump off again |
+| OpenGL ES game: the GPU hangs at one effect (freeze/exit, compositor watchdog, for example Vader Immortal's lightspeed jump) | a shader (as Zink compiles it) reads loop counters/accumulators before setting them | capture the SPIR-V (adapter `zink_shader_dump=1` writes every module to `files/fp_spirv/`, or a GPU capture), then a `zink_shader_fix` entry (same format as `vk_shader_fix`) + `frame.zink_shader_fix` (Vulkan layer under Zink, activated through GraphicsEnv's debug layer list); log `shader fix layer: fixed shader module N`; triage `zink-shader-fix-mismatch` when a Frame update changed the driver's output |
 | 2D Android app: Steam says it's running but nothing shows | Lepton runs apps headless unless the app folder has `lepton-show-flatscreen` | FramePort adds it for apps without VR (agent v28+); reinstall apps installed before |
 | A phone/tablet app shows nothing in the headset, or a VR app opens as a flat window | FramePort's VR/2D guess (`vr_kind`) is wrong for this app | patch `device.display_mode` → **Flat window** or **VR** (Customize → "Show as VR or as a flat window"), then Update on Frame |
-| "Install with FrameDrop" button opens FrameDrop (or nothing) instead of FramePort | another program owns `framedrop://`, or the switch is off, or macOS (Flet can't receive links there) | Settings → Install links → **Use FramePort for these links**; else Add games → Install from a link… (paste the button's address) |
+| An install button opens another program (or nothing) instead of FramePort | another program owns the link type, or the switch is off, or macOS (Flet can't receive links there) | Settings → Install links → **Use FramePort for these links**; else Add games → Install from a link… (paste the button's address) |
+| 2D Android game ignores the controllers: they only move a pointer, an SDL game keeps its touch controls ("no controller attached"); Android's log lists only `wayland_touch`/`wayland_keyboard`/`wayland_pointer` (GitHub #162, Skate 3) | Lepton's Android gets keyboard, pointer and touch from the Wayland seat only: no gamepad device | patch `device.steam_gamepad` (2D apps; suggested when the manifest declares `android.hardware.gamepad` or `LEANBACK_LAUNCHER`; no APK change, reinstall): the launcher puts FramePort's Podman wrapper (`~/.local/share/frameport/agent/bin/podman`) first on PATH, which bind-mounts Steam Input's virtual pads (uinput, 28de, "Microsoft X-Box 360 pad N") at `/dev/input/eventN` plus an Xbox 360 key layout, and exports `LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD=1`. Check: launch.log `FramePort gamepad: Steam Input virtual gamepads for this container: event5 (…)` ("none" = Steam had no pad when the game started: Steam only makes it while the controllers are on), `podman exec lepton-steamlaunch-<appid> dumpsys input` lists the pad. Steam Input must be on for the shortcut. A pad Steam makes after the start (controllers woke later, reconnect) isn't seen until the next start. Off for one start: `FRAMEPORT_NO_GAMEPAD=1 %command%` |
 | 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) |
-| Own GLES engine (OpenXR, not VrApi): eye view fine, but HUD / menu / PDA panels black (e.g. Doom3Quest, GitHub #77; no error in the log) | every shader declares `layout(num_views=2) in;`, also the ones drawn into the engine's single-layer offscreen framebuffers (2D textures/renderbuffers); OVR_multiview makes such draws INVALID_OPERATION and Mesa drops them (`draw_validate.c`), Quest's driver doesn't | `frame.gl_multiview_fbo` (opt-in, experimental: `libfpglmv.so` interposes GLES and draws those cases with a single-view twin of the program; logs `GLMV: twin built: program N -> M`, per-5-s `single-view draws` counters; `gl_mv_debug=1` adds glGetError checks; triage `gl-multiview-twin-failed`). Alternative: the game's own fix (two-layer multiview pool, Xandrix's patch in #77) |
+| Only some draws visible (for example controllers) + `glGetError 0x502` | multiview shaders used on single-view FBOs | GL shim `gl_hide_multiview=1` (default) |
+| Own GLES engine (OpenXR, not VrApi): eye view fine, but HUD / menu / PDA panels black (for example Doom3Quest, GitHub #77; no error in the log) | every shader declares `layout(num_views=2) in;`, also the ones drawn into the engine's single-layer offscreen framebuffers (2D textures/renderbuffers); OVR_multiview makes such draws INVALID_OPERATION and Mesa drops them (`draw_validate.c`), Quest's driver doesn't | `frame.gl_multiview_fbo` (opt-in, experimental: `libfpglmv.so` interposes GLES and draws those cases with a single-view twin of the program; logs `GLMV: twin built: program N -> M`, per-5-s `single-view draws` counters; `gl_mv_debug=1` adds glGetError checks; triage `gl-multiview-twin-failed`). Alternative: the game's own fix (two-layer multiview pool, Xandrix's patch in #77) |
 | 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 |
@@ -132,9 +137,9 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | MR game stuck waiting for room data (Demeter) | no Meta scene API | adapter `scene_emul=1` (+ `frame.meta_permissions`) |
 | Hand-tracking game janky (Silhouette) | Frame synthesizes hands from controllers | `controller_fix=0` passes hands through; not really fixable |
 | Eye distortion while moving (Arcsmith, Time Stall) | unknown (not eye swap, tracking, Valve layers, depth or pacing) | unresolved |
-| One eye grey / only effects (I Am Cat, Unity Oculus XR Plugin on GLES) | the game's multiview pass draws array slice 1 wrong on Zink | `frame.unity_multipass` (also rewrites the getter's inlined read in `OculusLoader.Initialize`; check for two `array=1` eye swapchains) |
+| One eye gray / only effects (I Am Cat, Unity Oculus XR Plugin on GLES) | the game's multiview pass draws array slice 1 wrong on Zink | `frame.unity_multipass` (also rewrites the getter's inlined read in `OculusLoader.Initialize`; check for two `array=1` eye swapchains) |
 | View vibrates even when holding still after `frame.unity_multipass` (I Am Cat) | poses/times are consistent, but two passes on Zink make every frame one period late, and the game clamps its physics step to 10 ms | not fixed (scale 0.8 didn't help); next ideas: fix multiview instead, or the game's fixed timestep |
-| Game freezes / pauses for 0.5-2 s now and then, no flicker (e.g. Blade & Sorcery, Lucky's Tale) | the headset's wear sensor flickers off while worn (`logs/eyetracking.txt` `HMD off, stopping eye tracking` … `HMD on`), the Frame turns it into a focus loss and Quest games that pause on focus loss pause | adapter `focus_hold` (on by default since 2026-10-05, dips up to `focus_hold_ms` = 5000 ms are hidden; longer ones still pause) |
+| Game freezes / pauses for 0.5-2 s now and then, no flicker (for example Blade & Sorcery, Lucky's Tale) | the headset's wear sensor flickers off while worn (`logs/eyetracking.txt` `HMD off, stopping eye tracking` … `HMD on`), the Frame turns it into a focus loss and Quest games that pause on focus loss pause | adapter `focus_hold` (on by default since 2026-10-05, dips up to `focus_hold_ms` = 5000 ms are hidden; longer ones still pause) |
 | Minor glitches on some objects (Myst, Unreal Vulkan) | unknown; not application space warp (turning it off changed nothing and ran worse) | unresolved |
 | Unity game crashes or hangs right as Vulkan starts, after `SLZ Graphics plugin loading!` and OVRPlugin's pre-init `xrDestroyInstance`: SIGSEGV with pc 0 (or pc == fault address in an unloaded library), x16/x23 in `libSLZQuestNative.so` (BONELAB 1.2974) | Stress Level Zero's graphics plugin hooks Unity's Vulkan start-up (IUnityGraphicsVulkanV2 interception: vkCreateInstance/vkCreateDevice) and vkCreateSampler; its vkCreateInstance wrapper calls an invalid pointer on the Frame | `frame.slz_vulkan_hooks` (its two registrations become no-ops; Unity starts Vulkan itself; ~35 s of shader prewarming without its pipeline cache) |
 | Unity game shows a picture but the player body is frozen: no head tracking, the controllers stay on the model, no buttons, although OpenXR input works (BONELAB 1.2068, Oculus XR Plugin) | OVRPlugin reports the headset as not worn (`ovrp_GetUserPresent2` → 0) a few seconds after start, and the game's rig only follows a present user (Marrow `XRHMD.IsUserPresent` = Unity's HMD `UserPresence`) | `frame.unity_user_presence` (the Oculus XR Plugin's lookup → `libfp_ovrp.so`, reports present; log `user presence: OVRPlugin 0 …`) |
@@ -203,16 +208,16 @@ or the Rift version through Revive (Journey of the Gods, Shadow Point). The cata

 ## Oculus Rift (PC VR) games
 Scan a folder with Rift game dumps (Windows game folders) like Quest dumps; they get ids `rift.<slug>` and the
-"PC VR (Revive / Proton)" patch group. Two ways to run them:
+"PC VR (Proton and Revive)" patch group. Two ways to run them:
 - **This PC** (`--to pc`, GUI "Install on this PC"): a non-Steam shortcut in the local Windows Steam runs
  `ReviveInjector.exe /openxr "<game.exe>"` (FramePort's portable Revive; on WSL copied to
  `%LOCALAPPDATA%\FramePort`). Play on the Frame by streaming from SteamVR.
- **The Frame** (GUI "Install on Frame (Proton)"): game + Revive are uploaded to `~/Applications/quest-frame/rift.*`,
-  and launch.sh runs them with the Frame's ARM64 Proton (Frame → Install Proton first). Experimental.
+- **The Frame** (GUI "Install on Frame"): game + Revive are uploaded to `~/Applications/quest-frame/rift.*`,
+  and launch.sh runs them with the Frame's ARM64 Proton (install it first: Frame page → PC VR games (Proton) → Install…). Experimental.

 | Symptom | Cause | Fix |
 |---|---|---|
-| "Proton isn't installed on the Frame yet" | ARM64 Proton / Steam Linux Runtime 4 (arm64) not downloaded | Frame → Install Proton (confirm in the headset) or "Install without confirming" (`frameport frame proton --install --unattended`) |
+| "Proton isn't installed on the Frame yet" | ARM64 Proton / Steam Linux Runtime 4 (arm64) not downloaded | Frame page → PC VR games (Proton) → Install… (`frameport frame proton --install`; `--in-headset` only asks Steam, confirm in the headset) |
 | Game quits at once; `ovrPlatformInitialize_NotEntitled` / entitlement failed | Oculus Platform SDK entitlement check (FramePort flags these: "Uses the Oculus Platform SDK") | PC mode with the Oculus app installed and a license you own. FramePort doesn't bypass entitlement checks |
 | `Failed to create process` in ReviveInjector.txt | wrong exe, or 32/64-bit mismatch | check the detected exe on the game page; rescan |
 | `XR_ERROR_RUNTIME_UNAVAILABLE` / no OpenXR runtime (PC) | SteamVR not running / not the OpenXR runtime | start SteamVR, set it as OpenXR runtime; or `pcvr.revive_openvr` |
@@ -220,14 +225,3 @@ Scan a folder with Rift game dumps (Windows game folders) like Quest dumps; they
 | Proton game hangs at start in a headless/SSH launch; log `no driver could be loaded` / `explorer process failed to start` | no display session (DISPLAY/GAMESCOPE_WAYLAND_DISPLAY) | the Proton launch.sh takes them from the running Steam (built in) |
 | Unreal game starts (window created) then `CrashReportClient` runs | the game crashed under Proton; often no VR runtime reached it (Revive off) | keep `pcvr.revive` on (repacks' bundled LibRevive64.dll isn't loaded by itself); read the game log + crash summary in the launch log |
 | `VK_ERROR_DEVICE_LOST` under DXVK | freedreno GPU hang | `pcvr.proton_log` to capture; PC mode |
-
-## Quest games on this PC (AXRB, `docs/PC_ANDROID.md`)
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| Unconverted Quest APK in AXRB: no launcher activity, SIGABRT ~0.3 s after `libovrplatformloader.so` loads | Meta's platform loader aborts outside a Quest | FramePort always gives AXRB its OVRPort build (the PC build: OVRPort + `on_pc` APK fixes, no Steam Frame fixes) |
-| `axrb-no-headset`: host.err `failed to find D3D11 adapter requested by OpenXR runtime` / `xrCreateInstance failed: XR_ERROR_RUNTIME_FAILURE` | SteamVR has no headset (null driver: no D3D11 adapter; vrlink with no Frame connected: no instance) | connect the headset and let SteamVR show it first; headless checks can only go as far as the guest log (`am start`, logcat) |
-| `axrb-gfxstream-crash`: SIGSEGV in `vulkan.ranchu.so (gfxstream::vk::ResourceTracker::on_vkAllocateMemory)` from `libVkLayer_AXRB_runtime.so` (Pinball FX VR, UE5 Vulkan, headless) | the emulator's Vulkan path through AXRB's runtime layer | report to AXRB with diagnostics (`axrb/*` logs); recheck with the host attached |
-| `axrb-translation-crash`: crash in `libndk_translation.so (berberis::…)` | Android's ARM translation (AXRB issue #9, some Unity games) | nothing to patch; wait for AXRB's other translator |
-| Reinstall fails `INSTALL_FAILED_UPDATE_INCOMPATIBLE`, or the game data must be copied again | a copy signed with another key was installed in AXRB (e.g. by AXRB's own launcher); a full uninstall deletes the OBB folder and saves | uninstall it in AXRB first; FramePort keeps one key per game, so its own updates keep data |
-| A FramePort call that runs an AXRB script never returns although the script ended (emulator already up) | QEMU (`Start-Process`) and the adb server inherit the caller's handles; through WSL interop even a file or /dev/null keeps the relay open | `axrb.spawn_detached` starts the script through WMI (`Win32_Process.Create`, nothing inherited) and polls its PID; exit code from the log's `FP_EXIT` line |
@@ -0,0 +1,152 @@
+# Screenshots and videos
+
+The pictures in the docs and the videos are rendered by scripts, never taken by hand. The scripts show the real
+FramePort GUI with a demo library and a pretend Steam Frame, drive it the way a person would, and film or photograph
+it:
+
+| What | Source | Output |
+|---|---|---|
+| Docs screenshots | `docs/showcase/shots.yaml` | `docs/images/*.png` |
+| Demo tour (about 95 s) | `docs/showcase/videos/tour.yaml` | `docs/media/frameport-tour.mp4` (+ `.jpg` poster), `docs/images/tour-teaser.webp` (README) |
+| Install tutorial (about 90 s) | `docs/showcase/videos/install.yaml` | `docs/media/frameport-install.mp4` (+ `.jpg` poster) |
+
+Nothing comes from anyone's own library. The demo library (`docs/showcase/demo-library.yaml`) lists real catalog
+games, so recipes and patches are the ones FramePort really uses. Their technical analysis (`demo-analyses.json`:
+engine, VR API, libraries, sizes) was exported from real APK analyses without any paths. Art, in-game screenshots
+and store details come from the same public sources the app uses and are cached in `~/.cache/frameport-showcase`.
+The renderer refuses to run in FramePort's own data folder, scans the demo data for home paths and IP addresses
+first, and stops when a store didn't send art (placeholders never reach the docs; `--allow-missing-art` overrides
+that). Frame discovery is switched off during a render (no real device on your network can appear), and the setup
+command shows placeholders for the address and code (each PC has its own), never this computer's.
+
+## Running it
+
+You need the dev extras, Chromium for Playwright and ffmpeg:
+
+```
+UV_LINK_MODE=copy uv sync --extra dev
+uv run playwright install chromium        # once
+uv run python scripts/showcase/render_docs.py               # all screenshots → docs/images (changed ones only)
+uv run python scripts/showcase/render_docs.py --only game,monitor --out /tmp/shots
+uv run python scripts/showcase/record_video.py install --draft   # quick 720p check of a storyboard edit
+uv run python scripts/showcase/record_video.py              # every video → docs/media (+ the README teaser)
+uv run python scripts/showcase/record_video.py tour install # some
+```
+
+Every screenshot is rendered twice, each in a fresh window, and kept only when both agree (the headless GPU now and
+then draws a glyph wrong); a third render settles a disagreement, and `--fast` renders once for trying out an edit.
+A shot whose steps fail is tried again and never written. A screenshot is rewritten only when it visibly changed
+(`render_docs.changed`: anti-aliasing noise doesn't count), so running it twice changes nothing. `--check` writes
+nothing and exits 1 when a docs image is out of date.
+
+For videos, `--names` prints what can be clicked after each scene and `SHOWCASE_DEBUG=1` prints every step with its
+start time (which step waited); `--draft --scenes a,b` records only some scenes. A video is encoded at the best
+quality that fits its `budget_mb` (12 by default), a teaser at 4 MB.
+
+## Videos
+
+One storyboard per video in `docs/showcase/videos/<name>.yaml`; adding a file adds a video (CI and releases pick it
+up by itself). The output must be `docs/media/frameport-<name>.mp4`: releases attach it as `FramePort-<name>.mp4`.
+
+```yaml
+output: docs/media/frameport-install.mp4
+teaser: docs/images/tour-teaser.webp     # optional: a looping WebP from the scenes' `teaser` parts
+budget_mb: 12
+poster_at: 9                             # the poster frame, seconds after the title card
+start:
+  profile: fresh          # demo = FramePort in use (games installed, BONELAB running); fresh = its first start
+  frame: disconnected     # connected (default) or disconnected
+  route: welcome          # the page filming starts on (default library)
+  stream: live            # the monitor stream: live (default) or frozen
+setup:                    # steps before filming starts (a failure stops the recording)
+  - hook: {name: first_run, args: ["D:/Games", 1.4]}
+vars: {game: com.playful.LuckysTale}     # ${game} in any step
+title: {heading: Installing FramePort, line: …, seconds: 3.4}
+end: {heading: You're set, line: …, footer: github.com/spoopyghosty0/frameport, seconds: 4}
+scenes:
+  - name: connect                        # a filmed scene
+    caption: ["Connect your Steam Frame", "Once: FramePort shows a command to run on the Frame"]
+    teaser: [0.6, 4.0]                   # optional: this part goes into the teaser
+    hold: 1.5                            # seconds of filming after the last step (default 0.6)
+    steps: [...]
+  - name: on-the-frame                   # an instruction card: for what happens outside FramePort
+    seconds: 10
+    card:
+      eyebrow: "Step 3 · On the Frame, first time only"
+      heading: Run the setup command
+      steps: ["In the SteamVR dashboard: **Launch a program** → **Desktop**", …]   # **bold** = a button or menu
+      code: "curl -fsS <your-PC-address>:8765/<one-time-code> | bash"
+      note: "Your address and code differ."
+```
+
+Filmed scenes are one continuous session: each starts where the last one left off. Cards are rendered at the end
+and slotted in, with crossfades between everything. The `fresh` profile starts FramePort as on a new computer: an
+empty library, the welcome screen and a Frame that isn't set up. Its games wait for the pretend folder scan.
+
+## Writing steps
+
+Shots and scenes use one step language (`scripts/showcase/steps.py`). A step is a one-key mapping:
+
+```yaml
+- go: monitor                                  # a sidebar route
+- nav: "Monitor"                               # click that tab (checked: the page really changed)
+- open_game: ${game}                           # or {package: …, advanced: true}
+- call: {fn: settings_dialog, args: ["${game}"]}   # any app method
+- hover: "Batman: Arkham Shadow"               # the pointer: by name…
+- click: {name: "Lucky's Tale", dy: 0.35}      # …offset inside the element (fraction of its size, or px)
+- click: "Install on Frame"                    # right_click, double_click, drag: [from, …, to]
+- type: "ri"                                   # press: Escape
+- wait_for: "BONELAB · 2026-10-04 21:50"
+- wait: 1.2
+- hook: {name: held_install, args: ["${new_game}"]}   # the pretend Frame's scripted events
+```
+
+Elements are found by name through Flutter's accessibility tree: their visible text, a tooltip or a semantics
+label. Exact names win over prefixes, and buttons and cards win over plain text. When several match, the innermost
+one wins (a list carries the text of its rows; the row is meant). Icon-only buttons need a tooltip to be found,
+which also helps screen readers. The pointer moves on eased, slightly curved paths and is drawn into the picture,
+with a ring on every click. To open a game from a cover card, click its title (`dy: 0.35`): the card's middle is its
+Play/Install button.
+
+Hooks (`steps.HOOKS`) cover what a real Frame would do:
+- `fake_install`: an install through the real job queue with every real stage name and a launch test that passes.
+- `held_install`: an install that stops mid-upload, for screenshots of the progress.
+- `connect` and `disconnect`
+- `first_run`: a first start. The welcome screen's tool download is a pretend one, and "Scan a folder…" scans a
+  folder at once (the native folder picker can't be scripted).
+- `pairing_done`: the Frame ran the setup command, so FramePort connects.
+- `live_stream`: a test picture through the real relay.
+- `monitor_details`, `type_tab`, `select_files` and `settings_section`.
+
+In a video, clicking Install runs the scripted install, and the game is then installed on the pretend Frame.
+
+Pictures must not change from one run to the next:
+- Screenshot and file dates are fixed.
+- The Monitor's stream stops after its two-minute history.
+- The pointer leaves the page before a still picture is taken.
+- Each shot gets a fresh window and browser.
+- A picture is taken once the page has stopped changing.
+
+Live data, such as the live view's relay port and data rate, doesn't belong in a docs screenshot.
+
+## How it runs on GitHub
+
+The `showcase` workflow (`.github/workflows/showcase.yml`):
+1. **When it runs:** on pushes to `main` that touch the UI, its translations or the showcase files, and on
+   **Run workflow**.
+2. **What it renders:** the screenshots every time. Videos when their storyboard changed (all of them when the
+   scripts changed), or the ones named on a manual run (`all`, or e.g. `tour install`). UI tweaks alone don't
+   re-commit 10 MB videos.
+3. **What happens next:** every render is uploaded as the run's `showcase` artifact. When a picture changed, the
+   workflow opens or updates the pull request on branch `showcase/update`, which you review and merge.
+
+Releases attach every committed video as `FramePort-<name>.mp4`.
+
+## Gallery
+
+These are renders the README doesn't show (yet):
+
+| | |
+|---|---|
+| ![Installing](images/install-progress.png) | ![Live view](images/live-view.png) |
+| ![Appearance](images/appearance.png) | ![Game page](images/game.png) |
@@ -1,26 +1,43 @@
-# Writing style for FramePort's interface
+# Writing style for FramePort

-Short rules so every screen, help text and doc sounds the same. Code style is enforced by `ruff`.
+Short rules so every screen, help text, doc and web page 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.
+  physical device you wear ("put the headset on"). Buttons say "… on Frame" ("Install on Frame").
+- **Quest game** for Meta Quest apps, **Android app** for ordinary Android apps, **Linux app** for Linux programs,
+  **PC VR game** for Windows VR games (never "PCVR"). Say Oculus or Rift only for games that use Oculus's own SDK.
+  **Game** when the kind doesn't matter; **APK** only when the file itself matters.
 - **Patch** for anything in a game's patch list (never "fix" for the same thing). **Recipe** for a game's chosen
-  patches and settings.
+  patches and settings (never "config"); say what it is the first time a page uses it.
 - 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.
+- **Set up** = the one-time setup of a Frame; **connect** = linking FramePort to it. **Pair** only in Valve's own
+  **Pair new host**. The **setup line** is the fixed `curl -fsSL https://frameport.app/s | bash`; the
+  **setup command** is the one with this PC's address and a one-time code. FramePort's button is **Allow**.
+- **Konsole** is the Frame's terminal. The way there is "SteamVR dashboard → Launch a program → Desktop, then app
+  menu → System → Konsole": say it in full once per page, then just "Konsole".
+- **This PC** / **your PC**, not "computer". **Unpack** a download (zip and tar.gz alike), not "unzip".
+- One label per thing everywhere: **Docs**, **Report a problem**, **Download FramePort**.

 ## 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.
+- Sentences end with a period, including tooltips and help texts; labels and headings don't (also on the website).
 - "and", not "&", in text. An em dash (—) for asides, a middle dot (·) between short facts.
+- No Oxford comma ("Windows, macOS and Linux"). Straight apostrophes and quotes in source.
 - Sizes in GiB/MiB (`i18n.fmt_size`), dates as YYYY-MM-DD HH:MM (`i18n.fmt_datetime`).
- US spelling (customize, analyze, color).
+- US spelling (customize, analyze, color, license).
 - Plain, technical wording: say what happens ("Steam restarts once"), no marketing adjectives.

+## Length
+Short beats complete: say what the user does or gets; leave out how it works unless they need it to act.
+- Buttons: four words at most. Tooltips: one short sentence.
+- Dialog text: two short sentences. Help texts: three sentences at most (about 200 characters).
+- Doc paragraphs: three sentences at most; steps as numbered lists.
+- Explain a technical term in a few words where a reader first meets it, or leave it out.
+- Say a thing once and link to it elsewhere.
+
 ## 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.
@@ -9,12 +9,15 @@ assets.

 ## Scope and installation

-FrameBridge enables the internal native-video path only for this package's
-arm64 APK. It bundles a private hardware codec, its checksum manifest, and a
-Podman wrapper in that APK. The agent verifies and extracts those files into
-the game's own directory. The launcher places this wrapper on its child PATH.
-Only the matching game's container receives the read-only plugin/XML mounts
-and Iris decoder device. Shared Lepton files and original MP4/OBB assets are
+FrameBridge enables the native-video path through the recipe-only adapter
+setting `surface_native` (Batman's catalog recipe; a one-time library migration,
+`batman_video_patches`, adds it and `frame.hw_video_decode` to existing Batman
+recipes). Hardware decoding is deployed independently into FramePort's shared,
+versioned codec store, without embedding decoder assets; games that have
+`frame.hw_video_decode` in their recipe get the launcher line that places the
+shared wrapper on the launcher's child PATH. Matching containers
+receive read-only plugin/XML mounts and the Iris decoder device. Shared Lepton
+files and original MP4/OBB assets are
 never replaced, transcoded, resized, or rewritten.

 The native projection, view recording and Vulkan-enable hooks are gated by
@@ -34,23 +37,24 @@ If the driver's session limit is exhausted, Android can fall back to software
 decoding; that preserves functionality but not full-resolution performance.
 FramePort does not change Steam's global hardware-decoding settings.

-Other packages and arm32 APKs do not receive the native-video setting or these
-codec assets. Rebuilding an older unrelated APK removes the previously bundled
-codec files, and installing an APK without its manifest disables its old wrapper.
-MP4 presence alone is not evidence of compatible surface/overlay semantics.
+Other games don't get `surface_native`. The decoder is separate from that
+setting, and runs in Lepton's arm64 media service. Rebuilding an older APK
+removes the previously bundled codec files; launcher migration replaces
+Batman's old per-game wrapper with the shared one. MP4 presence alone is not
+evidence of compatible surface/overlay semantics.

-Package-specific patch revisions use the existing Update on Frame state without
-adding UI controls or wording. The shared adapter revision is unchanged; only
-Batman is marked outdated for this repair. Older builds without recorded recipe
-fingerprints are handled with the same package scope.
+The recipe change marks Batman's installed build "Update on Frame"; the shared
+adapter revision is unchanged, so other games stay installed as they are.

 ## Decode and render path

 `native/hevc/frameport_hevc.cpp` exposes `OMX.frameport.hevc.decoder` through the
 tested SoftOMX ABI, using FFmpeg's LGPL Iris V4L2 hardware decoder wrapper.
 Native surface clients receive full-resolution YUV hardware buffers with fences.
-Persistent workers copy disjoint NV12 row bands into Android buffers without
-CPU color conversion. Input timestamps, EOS, dynamic dimensions, seek and flush
+Compatible large native surfaces use fenced Vulkan transfers between imported
+decoder and Android DMA buffers, retaining the decoded frame until GPU completion.
+Other surfaces retain parallel NV12 row copies without CPU color conversion.
+Input timestamps, EOS, dynamic dimensions, seek and flush
 are preserved.

 An AImageReader retains the decoder's actual image. The surface worker samples
@@ -0,0 +1,61 @@
+# Themes
+
+FramePort comes with three color themes, all dark:
+
+| Theme | Look |
+|---|---|
+| **Portal** (default) | The logo's two portals: orange for actions and the current selection, blue for secondary actions, progress and the PC side. |
+| **Portal (OLED)** | Portal on true black, for OLED screens. |
+| **Original** | FramePort's first look, with a violet accent. |
+
+Switch in **Settings → Appearance**. The change applies at once.
+
+## Your own theme
+
+A theme is a small JSON file. To make one:
+
+1. In **Settings → Appearance**, pick the theme closest to what you want and click **Copy this theme as a file**.
+2. Paste it into a text editor and save it as `something.json`.
+3. Change the name and the colors you want different. You can delete every color you keep: missing colors come
+   from the `base` theme.
+4. Back in **Settings → Appearance**, click **Install theme file…** and choose the file. FramePort checks it,
+   switches to it and keeps a copy in its data folder (`themes/`), so you can delete the original.
+
+To remove an installed theme, click the bin icon on its card.
+
+### Format
+
+```json
+{
+  "name": "Ember & Ice",
+  "base": "portal",
+  "dual": true,
+  "colors": {
+    "ACCENT": "#FF5A36",
+    "SECONDARY": "#5CE1E6"
+  }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `name` | Shown on the theme's card (up to 40 characters). |
+| `base` | The built-in theme that fills in every color the file leaves out: `portal` (default), `portal_oled` or `original`. |
+| `dual` | `true`: two-color touches like Portal's (blue-to-orange sidebar edge, two-color "FramePort", the selected tab's fade, blue secondary buttons). `false`: one accent, like Original. Default: the base's. |
+| `colors` | Any of the colors below, as `#RRGGBB` or `#RGB`. Names may be upper or lower case. |
+
+| Color | Used for |
+|---|---|
+| `BG` | Window background |
+| `SIDEBAR` | Sidebar and activity panel |
+| `SURFACE`, `SURFACE_2`, `SURFACE_3` | Cards; raised and hovered parts; inputs and chips |
+| `BORDER`, `BORDER_STRONG` | Outlines |
+| `TEXT`, `TEXT_2`, `TEXT_3` | Main text; secondary text; captions and disabled text |
+| `ACCENT`, `ACCENT_SOFT`, `ON_ACCENT` | Main buttons and the current selection; its tint; text on it |
+| `SECONDARY`, `SECONDARY_SOFT` | Secondary buttons, progress, switch tracks; its tint |
+| `OK`, `WARN`, `ERROR`, `INFO` | Status: works, needs attention, failed, information |
+| `PC` | PC VR games and "on this PC" |
+
+FramePort refuses a theme file it can't show well, and says why: a light window background (FramePort is dark only),
+text that's hard to read on cards, an unknown color name or a value that isn't a color. An example is in
+[`themes/example-theme.json`](themes/example-theme.json).
@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="216" height="60" viewBox="0 0 216 60" role="img" aria-label="Install with FramePort"><title>Install with FramePort</title><style>.fp-wb,.fp-wo{transform-box:view-box}
+.fp-wb{transform-origin:0 0;animation:fp-wb 6s ease-in-out infinite}
+.fp-wo{transform-origin:216px 0;animation:fp-wo 6s ease-in-out infinite}
+.fp-core{animation:fp-core 6s ease-in-out infinite}
+@keyframes fp-wb{0%,10%,100%{opacity:.45;transform:scaleX(1)}32%{opacity:1;transform:scaleX(1.5)}54%{opacity:.3;transform:scaleX(1)}}
+@keyframes fp-core{0%,28%,100%{opacity:0}42%{opacity:1}60%{opacity:0}}
+@keyframes fp-wo{0%,38%,100%{opacity:.6;transform:scaleX(1)}60%{opacity:1;transform:scaleX(1.4)}84%{opacity:.6;transform:scaleX(1)}}
+@media (prefers-reduced-motion:reduce){.fp-wb,.fp-wo,.fp-core{animation:none!important}}</style><defs>
+  <linearGradient id="fab" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".46"/><stop offset=".55" stop-color="#3AA8FF" stop-opacity="0"/></linearGradient>
+  <linearGradient id="fao" x1="0" y1="0" x2="1" y2="0"><stop offset=".45" stop-color="#FF8A1F" stop-opacity="0"/><stop offset="1" stop-color="#FF8A1F" stop-opacity=".34"/></linearGradient>
+  <radialGradient id="far" gradientUnits="userSpaceOnUse" cx="122" cy="39" r="46" gradientTransform="translate(122 39) scale(1 .62) translate(-122 -39)"><stop offset="0" stop-color="#FFE2BD" stop-opacity=".42"/><stop offset=".25" stop-color="#FF8A1F" stop-opacity=".2"/><stop offset=".6" stop-color="#3AA8FF" stop-opacity=".08"/><stop offset="1" stop-color="#3AA8FF" stop-opacity="0"/></radialGradient>
+  <clipPath id="fac"><rect x="1" y="1" width="214" height="58" rx="11.5"/></clipPath></defs>
+  <rect x=".5" y=".5" width="215" height="59" rx="12" fill="#0D0E12" stroke="#2A2D37"/>
+  <g clip-path="url(#fac)"><rect class="fp-wb" x="1" y="1" width="214" height="58" fill="url(#fab)" opacity=".45"/><rect class="fp-wo" x="1" y="1" width="214" height="58" fill="url(#fao)" opacity=".6"/><rect class="fp-core" x="1" y="1" width="214" height="58" fill="url(#far)" opacity="0"/></g>
+  <g transform="translate(10 10) scale(0.625)">
+  <defs><linearGradient id="fal0" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".18"/><stop offset=".5" stop-color="#3AA8FF" stop-opacity="0"/><stop offset=".5" stop-color="#FF8A1F" stop-opacity="0"/><stop offset="1" stop-color="#FF8A1F" stop-opacity=".18"/></linearGradient>
+  <linearGradient id="fal1" gradientUnits="userSpaceOnUse" x1="26" y1="0" x2="38" y2="0"><stop offset=".3" stop-color="#3AA8FF"/><stop offset=".7" stop-color="#FF8A1F"/></linearGradient>
+  <clipPath id="fal2"><polygon points="-30,-30 49.145,-30 8.855,94 -30,94"/></clipPath><clipPath id="fal3"><polygon points="55.145,-30 94,-30 94,94 14.855,94"/></clipPath></defs>
+  <rect width="64" height="64" rx="15" fill="#101218"/><rect width="64" height="64" rx="15" fill="url(#fal0)"/>
+  <g clip-path="url(#fal2)"><path d="M34 15H9a3 3 0 0 0-3 3v20a3 3 0 0 0 3 3h25z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"/><rect class="fp-scr" x="10.5" y="19.5" width="24" height="17" rx="1" fill="#3AA8FF" fill-opacity="0.35"/><path d="M18 41v6M11 47h14" stroke="#ECEDF3" stroke-width="3" stroke-linecap="round"/></g>
+  <g clip-path="url(#fal3)"><path d="M56.5 31.5H58.5" stroke="#ECEDF3" stroke-width="3.4" stroke-linecap="round"/><path d="M22 21h27a8 8 0 0 1 8 8v5a8 8 0 0 1-8 8H48.65a3 3 0 0 1-2.6-1.5l-1-1.7a.9.9 0 0 0-1.6 0l-1 1.7a3 3 0 0 1-2.6 1.5H22z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"/><g class="fp-lens"><ellipse cx="39.5" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"/><ellipse cx="49" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"/></g></g>
+  <g transform="rotate(18 32 32)"><g class="fp-ptl"><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="#08090C" stroke="#08090C" stroke-width="5.8"/><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="none" stroke="url(#fal1)" stroke-opacity=".25" stroke-width="6.46" class="fp-halo"/><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="url(#fal1)" fill-opacity="0.14" stroke="url(#fal1)" stroke-width="3.4"/></g></g></g>
+  <text x="60" y="25" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="9.5" font-weight="600" letter-spacing="1.4" fill="#A7ABB7">INSTALL WITH</text>
+  <text x="60" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#FF8A1F" textLength="53.1" lengthAdjust="spacingAndGlyphs">Frame</text>
+  <g transform="translate(115.25999999999999 29.36) scale(0.8035714285714286)"><g class="fp-ptl"><defs><linearGradient id="fawr" gradientUnits="userSpaceOnUse" x1="2" y1="0" x2="14" y2="0"><stop offset=".3" stop-color="#FF8A1F"/><stop offset=".7" stop-color="#3AA8FF"/></linearGradient></defs>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="none" stroke="url(#fawr)" stroke-opacity=".35" stroke-width="5" class="fp-halo"/>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="#0D0E12" stroke="url(#fawr)" stroke-width="2.6"/></g></g>
+  <text x="130.27714285714285" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#3AA8FF" textLength="36.9" lengthAdjust="spacingAndGlyphs">Port</text></svg>
@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="216" height="60" viewBox="0 0 216 60" role="img" aria-label="Install with FramePort"><title>Install with FramePort</title><style>.fp-wb,.fp-wo{transform-box:view-box;transition:opacity .5s ease,transform .7s cubic-bezier(.2,.8,.2,1)}
+.fp-wb{transform-origin:0 0}.fp-wo{transform-origin:216px 0}
+.fp-core{transition:opacity .6s ease}
+svg:hover .fp-wb{opacity:1;transform:scaleX(1.4)}svg:hover .fp-wo{opacity:1;transform:scaleX(1.3)}
+svg:hover .fp-core{opacity:1}
+@media (prefers-reduced-motion:reduce){.fp-wb,.fp-wo,.fp-core{transition:none!important}}</style><defs>
+  <linearGradient id="fhb" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".46"></stop><stop offset=".55" stop-color="#3AA8FF" stop-opacity="0"></stop></linearGradient>
+  <linearGradient id="fho" x1="0" y1="0" x2="1" y2="0"><stop offset=".45" stop-color="#FF8A1F" stop-opacity="0"></stop><stop offset="1" stop-color="#FF8A1F" stop-opacity=".34"></stop></linearGradient>
+  <radialGradient id="fhr" gradientUnits="userSpaceOnUse" cx="122" cy="39" r="46" gradientTransform="translate(122 39) scale(1 .62) translate(-122 -39)"><stop offset="0" stop-color="#FFE2BD" stop-opacity=".42"></stop><stop offset=".25" stop-color="#FF8A1F" stop-opacity=".2"></stop><stop offset=".6" stop-color="#3AA8FF" stop-opacity=".08"></stop><stop offset="1" stop-color="#3AA8FF" stop-opacity="0"></stop></radialGradient>
+  <clipPath id="fhc"><rect x="1" y="1" width="214" height="58" rx="11.5"></rect></clipPath></defs>
+  <rect x=".5" y=".5" width="215" height="59" rx="12" fill="#0D0E12" stroke="#2A2D37"></rect>
+  <g clip-path="url(#fhc)"><rect class="fp-wb" x="1" y="1" width="214" height="58" fill="url(#fhb)" opacity=".45"></rect><rect class="fp-wo" x="1" y="1" width="214" height="58" fill="url(#fho)" opacity=".6"></rect><rect class="fp-core" x="1" y="1" width="214" height="58" fill="url(#fhr)" opacity="0"></rect></g>
+  <g transform="translate(10 10) scale(0.625)">
+  <defs><linearGradient id="fhl0" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".18"></stop><stop offset=".5" stop-color="#3AA8FF" stop-opacity="0"></stop><stop offset=".5" stop-color="#FF8A1F" stop-opacity="0"></stop><stop offset="1" stop-color="#FF8A1F" stop-opacity=".18"></stop></linearGradient>
+  <linearGradient id="fhl1" gradientUnits="userSpaceOnUse" x1="26" y1="0" x2="38" y2="0"><stop offset=".3" stop-color="#3AA8FF"></stop><stop offset=".7" stop-color="#FF8A1F"></stop></linearGradient>
+  <clipPath id="fhl2"><polygon points="-30,-30 49.145,-30 8.855,94 -30,94"></polygon></clipPath><clipPath id="fhl3"><polygon points="55.145,-30 94,-30 94,94 14.855,94"></polygon></clipPath></defs>
+  <rect width="64" height="64" rx="15" fill="#101218"></rect><rect width="64" height="64" rx="15" fill="url(#fhl0)"></rect>
+  <g clip-path="url(#fhl2)"><path d="M34 15H9a3 3 0 0 0-3 3v20a3 3 0 0 0 3 3h25z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"></path><rect class="fp-scr" x="10.5" y="19.5" width="24" height="17" rx="1" fill="#3AA8FF" fill-opacity="0.35"></rect><path d="M18 41v6M11 47h14" stroke="#ECEDF3" stroke-width="3" stroke-linecap="round"></path></g>
+  <g clip-path="url(#fhl3)"><path d="M56.5 31.5H58.5" stroke="#ECEDF3" stroke-width="3.4" stroke-linecap="round"></path><path d="M22 21h27a8 8 0 0 1 8 8v5a8 8 0 0 1-8 8H48.65a3 3 0 0 1-2.6-1.5l-1-1.7a.9.9 0 0 0-1.6 0l-1 1.7a3 3 0 0 1-2.6 1.5H22z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"></path><g class="fp-lens"><ellipse cx="39.5" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"></ellipse><ellipse cx="49" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"></ellipse></g></g>
+  <g transform="rotate(18 32 32)"><g class="fp-ptl"><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="#08090C" stroke="#08090C" stroke-width="5.8"></ellipse><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="none" stroke="url(#fhl1)" stroke-opacity=".25" stroke-width="6.46" class="fp-halo"></ellipse><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="url(#fhl1)" fill-opacity="0.14" stroke="url(#fhl1)" stroke-width="3.4"></ellipse></g></g></g>
+  <text x="60" y="25" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="9.5" font-weight="600" letter-spacing="1.4" fill="#A7ABB7">INSTALL WITH</text>
+  <text x="60" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#FF8A1F" textLength="53.1" lengthAdjust="spacingAndGlyphs">Frame</text>
+  <g transform="translate(115.25999999999999 29.36) scale(0.8035714285714286)"><g class="fp-ptl"><defs><linearGradient id="fhwr" gradientUnits="userSpaceOnUse" x1="2" y1="0" x2="14" y2="0"><stop offset=".3" stop-color="#FF8A1F"></stop><stop offset=".7" stop-color="#3AA8FF"></stop></linearGradient></defs>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="none" stroke="url(#fhwr)" stroke-opacity=".35" stroke-width="5" class="fp-halo"></ellipse>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="#0D0E12" stroke="url(#fhwr)" stroke-width="2.6"></ellipse></g></g>
+  <text x="130.27714285714285" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#3AA8FF" textLength="36.9" lengthAdjust="spacingAndGlyphs">Port</text></svg>
@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="216" height="60" viewBox="0 0 216 60" role="img" aria-label="Install with FramePort"><title>Install with FramePort</title><defs>
+  <linearGradient id="fsb" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".46"/><stop offset=".55" stop-color="#3AA8FF" stop-opacity="0"/></linearGradient>
+  <linearGradient id="fso" x1="0" y1="0" x2="1" y2="0"><stop offset=".45" stop-color="#FF8A1F" stop-opacity="0"/><stop offset="1" stop-color="#FF8A1F" stop-opacity=".34"/></linearGradient>
+  <radialGradient id="fsr" gradientUnits="userSpaceOnUse" cx="122" cy="39" r="46" gradientTransform="translate(122 39) scale(1 .62) translate(-122 -39)"><stop offset="0" stop-color="#FFE2BD" stop-opacity=".42"/><stop offset=".25" stop-color="#FF8A1F" stop-opacity=".2"/><stop offset=".6" stop-color="#3AA8FF" stop-opacity=".08"/><stop offset="1" stop-color="#3AA8FF" stop-opacity="0"/></radialGradient>
+  <clipPath id="fsc"><rect x="1" y="1" width="214" height="58" rx="11.5"/></clipPath></defs>
+  <rect x=".5" y=".5" width="215" height="59" rx="12" fill="#0D0E12" stroke="#2A2D37"/>
+  <g clip-path="url(#fsc)"><rect class="fp-wb" x="1" y="1" width="214" height="58" fill="url(#fsb)" opacity=".45"/><rect class="fp-wo" x="1" y="1" width="214" height="58" fill="url(#fso)" opacity=".6"/><rect class="fp-core" x="1" y="1" width="214" height="58" fill="url(#fsr)" opacity="0"/></g>
+  <g transform="translate(10 10) scale(0.625)">
+  <defs><linearGradient id="fsl0" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#3AA8FF" stop-opacity=".18"/><stop offset=".5" stop-color="#3AA8FF" stop-opacity="0"/><stop offset=".5" stop-color="#FF8A1F" stop-opacity="0"/><stop offset="1" stop-color="#FF8A1F" stop-opacity=".18"/></linearGradient>
+  <linearGradient id="fsl1" gradientUnits="userSpaceOnUse" x1="26" y1="0" x2="38" y2="0"><stop offset=".3" stop-color="#3AA8FF"/><stop offset=".7" stop-color="#FF8A1F"/></linearGradient>
+  <clipPath id="fsl2"><polygon points="-30,-30 49.145,-30 8.855,94 -30,94"/></clipPath><clipPath id="fsl3"><polygon points="55.145,-30 94,-30 94,94 14.855,94"/></clipPath></defs>
+  <rect width="64" height="64" rx="15" fill="#101218"/><rect width="64" height="64" rx="15" fill="url(#fsl0)"/>
+  <g clip-path="url(#fsl2)"><path d="M34 15H9a3 3 0 0 0-3 3v20a3 3 0 0 0 3 3h25z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"/><rect class="fp-scr" x="10.5" y="19.5" width="24" height="17" rx="1" fill="#3AA8FF" fill-opacity="0.35"/><path d="M18 41v6M11 47h14" stroke="#ECEDF3" stroke-width="3" stroke-linecap="round"/></g>
+  <g clip-path="url(#fsl3)"><path d="M56.5 31.5H58.5" stroke="#ECEDF3" stroke-width="3.4" stroke-linecap="round"/><path d="M22 21h27a8 8 0 0 1 8 8v5a8 8 0 0 1-8 8H48.65a3 3 0 0 1-2.6-1.5l-1-1.7a.9.9 0 0 0-1.6 0l-1 1.7a3 3 0 0 1-2.6 1.5H22z" fill="#101218" stroke="#ECEDF3" stroke-width="3" stroke-linejoin="round"/><g class="fp-lens"><ellipse cx="39.5" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"/><ellipse cx="49" cy="30.5" rx="4.2" ry="3.8" fill="#FF8A1F"/></g></g>
+  <g transform="rotate(18 32 32)"><g class="fp-ptl"><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="#08090C" stroke="#08090C" stroke-width="5.8"/><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="none" stroke="url(#fsl1)" stroke-opacity=".25" stroke-width="6.46" class="fp-halo"/><ellipse cx="32" cy="32" rx="4.5" ry="22" fill="url(#fsl1)" fill-opacity="0.14" stroke="url(#fsl1)" stroke-width="3.4"/></g></g></g>
+  <text x="60" y="25" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="9.5" font-weight="600" letter-spacing="1.4" fill="#A7ABB7">INSTALL WITH</text>
+  <text x="60" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#FF8A1F" textLength="53.1" lengthAdjust="spacingAndGlyphs">Frame</text>
+  <g transform="translate(115.25999999999999 29.36) scale(0.8035714285714286)"><g class="fp-ptl"><defs><linearGradient id="fswr" gradientUnits="userSpaceOnUse" x1="2" y1="0" x2="14" y2="0"><stop offset=".3" stop-color="#FF8A1F"/><stop offset=".7" stop-color="#3AA8FF"/></linearGradient></defs>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="none" stroke="url(#fswr)" stroke-opacity=".35" stroke-width="5" class="fp-halo"/>
+  <ellipse cx="8" cy="14" rx="4.4" ry="10.6" transform="rotate(14 8 14)" fill="#0D0E12" stroke="url(#fswr)" stroke-width="2.6"/></g></g>
+  <text x="130.27714285714285" y="47" font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="18" font-weight="800" fill="#3AA8FF" textLength="36.9" lengthAdjust="spacingAndGlyphs">Port</text></svg>
@@ -0,0 +1,153 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1120 660" width="1120" height="660" role="img" aria-labelledby="t d">
+  <title id="t">FramePort architecture</title>
+  <desc id="d">The desktop app (ui/) and the command line (cli.py) both drive pipeline.py: add, suggest, build, install, test. The pipeline uses sources/, analysis/, recommend/, build.py, targets/ and validate/. Builds use the patches/ registry and the tools/ toolchain; targets reach the Steam Frame through frame/ and install/, which talk to the agent on the Frame over SSH.</desc>
+  <defs>
+    <linearGradient id="portal" x1="0" x2="1" y1="0" y2="0">
+      <stop offset="0" stop-color="#3aa8ff"/>
+      <stop offset="1" stop-color="#ff8a1f"/>
+    </linearGradient>
+    <radialGradient id="glow" cx="0.5" cy="0.25" r="0.75">
+      <stop offset="0" stop-color="#3aa8ff" stop-opacity="0.10"/>
+      <stop offset="0.5" stop-color="#ff8a1f" stop-opacity="0.04"/>
+      <stop offset="1" stop-color="#0d0e12" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="frameglow" cx="0.5" cy="0.5" r="0.6">
+      <stop offset="0" stop-color="#ff8a1f" stop-opacity="0.22"/>
+      <stop offset="1" stop-color="#ff8a1f" stop-opacity="0"/>
+    </radialGradient>
+    <marker id="arrow" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#717583"/>
+    </marker>
+    <marker id="arrow-o" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#ff8a1f"/>
+    </marker>
+    <style>
+      .t { font: 700 16px "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; fill: #edeef2; }
+      .s { font: 400 13px "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; fill: #a7abb7; }
+      .m { font: 500 12.5px ui-monospace, "Cascadia Mono", "SF Mono", Menlo, Consolas, monospace; fill: #a7abb7; }
+      .mt { font: 700 15px ui-monospace, "Cascadia Mono", "SF Mono", Menlo, Consolas, monospace; fill: #edeef2; }
+      .k { font: 600 11px "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; letter-spacing: 0.12em; fill: #717583; }
+      .card { fill: #16181e; stroke: #2a2d37; stroke-width: 1.5; }
+      .pc { fill: #16181e; stroke: #3aa8ff; stroke-opacity: 0.55; stroke-width: 1.5; }
+      .line { stroke: #4a4e5c; stroke-width: 1.8; fill: none; }
+      .chip { fill: #1d1f27; stroke: #393d49; stroke-width: 1; }
+      .ct { font: 600 13px "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; fill: #edeef2; }
+    </style>
+  </defs>
+
+  <rect width="1120" height="660" rx="18" fill="#0d0e12"/>
+  <rect width="1120" height="660" rx="18" fill="url(#glow)"/>
+
+  <!-- entry points -->
+  <text class="k" x="40" y="34">ON YOUR PC</text>
+  <rect class="pc" x="250" y="48" width="300" height="70" rx="12"/>
+  <text class="t" x="400" y="78" text-anchor="middle">Desktop app</text>
+  <text class="m" x="400" y="100" text-anchor="middle">ui/ · Flet · shell + views</text>
+  <rect class="pc" x="590" y="48" width="280" height="70" rx="12"/>
+  <text class="t" x="730" y="78" text-anchor="middle">Command line</text>
+  <text class="m" x="730" y="100" text-anchor="middle">cli.py</text>
+  <path class="line" d="M400 118 V150" marker-end="url(#arrow)"/>
+  <path class="line" d="M730 118 V150" marker-end="url(#arrow)"/>
+
+  <!-- the pipeline -->
+  <rect x="40" y="156" width="1040" height="78" rx="14" fill="#16181e" stroke="url(#portal)" stroke-width="2"/>
+  <text class="mt" x="66" y="190">pipeline.py</text>
+  <text class="s" x="66" y="212">one API for the app and the CLI</text>
+  <g>
+    <rect class="chip" x="352" y="177" width="92" height="36" rx="18"/>
+    <text class="ct" x="398" y="200" text-anchor="middle">add</text>
+    <path class="line" d="M448 195 H480" marker-end="url(#arrow)"/>
+    <rect class="chip" x="486" y="177" width="112" height="36" rx="18"/>
+    <text class="ct" x="542" y="200" text-anchor="middle">suggest</text>
+    <path class="line" d="M602 195 H634" marker-end="url(#arrow)"/>
+    <rect class="chip" x="640" y="177" width="96" height="36" rx="18"/>
+    <text class="ct" x="688" y="200" text-anchor="middle">build</text>
+    <path class="line" d="M740 195 H772" marker-end="url(#arrow)"/>
+    <rect class="chip" x="778" y="177" width="104" height="36" rx="18"/>
+    <text class="ct" x="830" y="200" text-anchor="middle">install</text>
+    <path class="line" d="M886 195 H918" marker-end="url(#arrow)"/>
+    <rect x="924" y="177" width="132" height="36" rx="18" fill="#3a2512" stroke="#ff8a1f" stroke-opacity="0.6"/>
+    <text class="ct" x="990" y="200" text-anchor="middle">launch test</text>
+  </g>
+
+  <!-- connectors to the modules -->
+  <path class="line" d="M120 234 V284" marker-end="url(#arrow)"/>
+  <path class="line" d="M296 234 V284" marker-end="url(#arrow)"/>
+  <path class="line" d="M472 234 V284" marker-end="url(#arrow)"/>
+  <path class="line" d="M648 234 V284" marker-end="url(#arrow)"/>
+  <path class="line" d="M824 234 V284" marker-end="url(#arrow)"/>
+  <path class="line" d="M1000 234 V284" marker-end="url(#arrow)"/>
+
+  <!-- the modules -->
+  <g>
+    <rect class="card" x="40" y="290" width="160" height="128" rx="12"/>
+    <text class="mt" x="58" y="320">sources/</text>
+    <text class="s" x="58" y="342">finds games</text>
+    <text class="m" x="58" y="370">quest_dump</text>
+    <text class="m" x="58" y="390">rift_dump</text>
+
+    <rect class="card" x="216" y="290" width="160" height="128" rx="12"/>
+    <text class="mt" x="234" y="320">analysis/</text>
+    <text class="s" x="234" y="342">reads the game</text>
+    <text class="m" x="234" y="370">detect · elf</text>
+    <text class="m" x="234" y="390">stubgen · rift</text>
+
+    <rect class="card" x="392" y="290" width="160" height="128" rx="12"/>
+    <text class="mt" x="410" y="320">recommend/</text>
+    <text class="s" x="410" y="342">picks the recipe</text>
+    <text class="m" x="410" y="370">catalog · engine</text>
+    <text class="m" x="410" y="390">catalog/*.yaml</text>
+
+    <rect class="card" x="568" y="290" width="160" height="128" rx="12"/>
+    <text class="mt" x="586" y="320">build.py</text>
+    <text class="s" x="586" y="342">makes the build</text>
+    <text class="m" x="586" y="370">OVRPort → patches</text>
+    <text class="m" x="586" y="390">→ apk/sign</text>
+
+    <rect class="card" x="744" y="290" width="160" height="128" rx="12"/>
+    <text class="mt" x="762" y="320">targets/</text>
+    <text class="s" x="762" y="342">where it runs</text>
+    <text class="m" x="762" y="370">frame_lepton</text>
+    <text class="m" x="762" y="390">pc_revive</text>
+
+    <rect class="card" x="920" y="290" width="160" height="128" rx="12"/>
+    <text class="mt" x="938" y="320">validate/</text>
+    <text class="s" x="938" y="342">checks the result</text>
+    <text class="m" x="938" y="370">static · device</text>
+    <text class="m" x="938" y="390">triage.yaml</text>
+  </g>
+
+  <!-- what the build and the targets use -->
+  <path class="line" d="M612 418 V448 H464 V484" marker-end="url(#arrow)"/>
+  <path class="line" d="M648 418 V484" marker-end="url(#arrow)"/>
+  <path class="line" d="M824 418 V484" marker-end="url(#arrow)"/>
+
+  <rect class="card" x="216" y="490" width="336" height="118" rx="12"/>
+  <text class="mt" x="234" y="520">patches/</text>
+  <text class="s" x="234" y="542">the registry: one module per patch</text>
+  <text class="m" x="234" y="570">overport · frame/* · settings</text>
+  <text class="m" x="234" y="590">pcvr · upstream</text>
+
+  <rect class="card" x="568" y="490" width="160" height="118" rx="12"/>
+  <text class="mt" x="586" y="520">tools/</text>
+  <text class="s" x="586" y="542">fetched on demand</text>
+  <text class="m" x="586" y="570">Java · OVRPort</text>
+  <text class="m" x="586" y="590">apksigner · Revive</text>
+
+  <rect class="card" x="744" y="490" width="160" height="118" rx="12"/>
+  <text class="mt" x="762" y="520">frame/</text>
+  <text class="s" x="762" y="542">+ install/installer</text>
+  <text class="m" x="762" y="570">ssh · pairing</text>
+  <text class="m" x="762" y="590">discovery</text>
+
+  <!-- the Steam Frame -->
+  <rect x="926" y="448" width="160" height="196" rx="16" fill="url(#frameglow)" stroke="#ff8a1f" stroke-opacity="0.45" stroke-width="1.5" stroke-dasharray="6 6"/>
+  <text class="k" x="1006" y="470" text-anchor="middle" style="fill:#ff8a1f">STEAM FRAME</text>
+  <path d="M904 549 H932" stroke="#ff8a1f" stroke-width="2" fill="none" marker-end="url(#arrow-o)"/>
+  <text class="m" x="915" y="538" text-anchor="middle" style="fill:#ff8a1f;font-size:10px">SSH</text>
+  <rect x="936" y="490" width="140" height="118" rx="12" fill="#1d150d" stroke="#ff8a1f" stroke-width="1.5"/>
+  <text class="mt" x="952" y="520">agent</text>
+  <text class="s" x="952" y="542">runs on the Frame</text>
+  <text class="m" x="952" y="570">install · Steam</text>
+  <text class="m" x="952" y="590">tests · logs</text>
+</svg>
@@ -0,0 +1,88 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1120 400" width="1120" height="400" role="img" aria-labelledby="t d">
+  <title id="t">How FramePort updates itself</title>
+  <desc id="d">check() asks GitHub for the latest release every 6 hours. install_kind() tells a packaged app from a source checkout or a Python wheel: a checkout runs git pull and uv sync, a wheel is reinstalled. For the packaged app, prepare() downloads the release, checks SHA256SUMS and the Windows signer and unpacks it, then apply() starts a script that waits for FramePort to quit, swaps the folders with a rollback and starts the new version.</desc>
+  <defs>
+    <linearGradient id="portal" x1="0" x2="1" y1="0" y2="0">
+      <stop offset="0" stop-color="#3aa8ff"/>
+      <stop offset="1" stop-color="#ff8a1f"/>
+    </linearGradient>
+    <radialGradient id="glow" cx="0.5" cy="0.2" r="0.8">
+      <stop offset="0" stop-color="#3aa8ff" stop-opacity="0.09"/>
+      <stop offset="0.55" stop-color="#ff8a1f" stop-opacity="0.04"/>
+      <stop offset="1" stop-color="#0d0e12" stop-opacity="0"/>
+    </radialGradient>
+    <marker id="arrow" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#717583"/>
+    </marker>
+    <style>
+      .n { font: 800 30px "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; }
+      .mt { font: 700 16px ui-monospace, "Cascadia Mono", "SF Mono", Menlo, Consolas, monospace; fill: #edeef2; }
+      .s { font: 400 13.5px "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; fill: #a7abb7; }
+      .m { font: 500 12.5px ui-monospace, "Cascadia Mono", "SF Mono", Menlo, Consolas, monospace; fill: #a7abb7; }
+      .lab { font: 600 12px "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; fill: #717583; letter-spacing: .04em; }
+      .card { fill: #16181e; stroke: #2a2d37; stroke-width: 1.5; }
+      .line { stroke: #4a4e5c; stroke-width: 1.8; fill: none; }
+    </style>
+  </defs>
+
+  <rect width="1120" height="400" rx="18" fill="#0d0e12"/>
+  <rect width="1120" height="400" rx="18" fill="url(#glow)"/>
+  <rect x="40" y="36" width="1040" height="3" rx="1.5" fill="url(#portal)" opacity="0.7"/>
+
+  <!-- 1 check -->
+  <rect class="card" x="40" y="62" width="236" height="178" rx="14"/>
+  <text class="n" x="60" y="104" fill="#3aa8ff">1</text>
+  <text class="mt" x="90" y="100">check()</text>
+  <text class="s" x="60" y="134">Asks GitHub for the latest</text>
+  <text class="s" x="60" y="154">release, every 6 hours.</text>
+  <text class="s" x="60" y="182">Skips drafts, pre-releases</text>
+  <text class="s" x="60" y="202">and versions you skipped.</text>
+  <path class="line" d="M276 151 H306" marker-end="url(#arrow)"/>
+
+  <!-- 2 install_kind -->
+  <rect class="card" x="312" y="62" width="236" height="178" rx="14"/>
+  <text class="n" x="332" y="104" fill="#7f9bd6">2</text>
+  <text class="mt" x="362" y="100">install_kind()</text>
+  <text class="s" x="332" y="134">How this copy was installed:</text>
+  <text class="m" x="332" y="164">bundle</text>
+  <text class="s" x="388" y="164">the packaged app</text>
+  <text class="m" x="332" y="190">source</text>
+  <text class="s" x="388" y="190">a git checkout</text>
+  <text class="m" x="332" y="216">wheel</text>
+  <text class="s" x="388" y="216">uv tool, pipx, pip</text>
+  <path class="line" d="M548 151 H604" marker-end="url(#arrow)"/>
+  <text class="lab" x="576" y="141" text-anchor="middle">bundle</text>
+
+  <!-- 3 prepare -->
+  <rect class="card" x="610" y="62" width="226" height="178" rx="14"/>
+  <text class="n" x="630" y="104" fill="#c2905a">3</text>
+  <text class="mt" x="660" y="100">prepare()</text>
+  <text class="s" x="630" y="134">Downloads the release to</text>
+  <text class="m" x="630" y="154">updates/&lt;version&gt;/</text>
+  <text class="s" x="630" y="182">Checks SHA256SUMS and, on</text>
+  <text class="s" x="630" y="202">Windows, the code signer.</text>
+  <text class="s" x="630" y="222">Unpacks; writes ready.json.</text>
+  <path class="line" d="M836 151 H862" marker-end="url(#arrow)"/>
+
+  <!-- 4 apply -->
+  <rect x="868" y="62" width="212" height="178" rx="14" fill="#1d150d" stroke="#ff8a1f" stroke-width="1.5"/>
+  <text class="n" x="888" y="104" fill="#ff8a1f">4</text>
+  <text class="mt" x="918" y="100">apply()</text>
+  <text class="s" x="888" y="134">A script waits for</text>
+  <text class="s" x="888" y="154">FramePort to quit, swaps</text>
+  <text class="s" x="888" y="174">the folders (rolls back on</text>
+  <text class="s" x="888" y="194">failure) and starts the</text>
+  <text class="s" x="888" y="214">new version.</text>
+
+  <!-- the other two ways -->
+  <path class="line" d="M400 240 V282" marker-end="url(#arrow)"/>
+  <path class="line" d="M470 240 V262 H710 V282" marker-end="url(#arrow)"/>
+  <text class="lab" x="400" y="266" text-anchor="end" dx="-8">source</text>
+  <text class="lab" x="600" y="256" text-anchor="middle">wheel</text>
+  <rect class="card" x="240" y="288" width="320" height="74" rx="12"/>
+  <text class="s" x="260" y="318">Source checkout: pulls and syncs</text>
+  <text class="m" x="260" y="342">git pull --ff-only · uv sync</text>
+  <rect class="card" x="584" y="288" width="320" height="74" rx="12"/>
+  <text class="s" x="604" y="318">Wheel: reinstalls the release's wheel</text>
+  <text class="m" x="604" y="342">uv tool · pipx · pip</text>
+</svg>
@@ -0,0 +1,64 @@
+# The demo library for the docs screenshots and the demo tour (built by scripts/showcase/demo_home.py into an
+# isolated FRAMEPORT_HOME; see docs/SHOWCASE.md). Real catalog games, so recipes, patches and store art are the
+# ones FramePort really uses; the technical analysis of each (engine, XR API, libraries, sizes) is in
+# demo-analyses.json, exported from real APK analyses without any paths. Nothing here is anyone's own data.
+#
+# Per game:
+#   frame:   on the pretend Frame: internal | sd | outdated (internal, but an older build: "Update on Frame");
+#            left out = not installed
+#   played:  last played, days before the render (the Library sorts the "On your Frame" shelf by it)
+#   added:   added to the library, days before the render (default 30)
+#   tested:  the last launch test passed (default: when installed)
+#   tags:    user tags (store genres become tags by themselves)
+#   title:   overrides the catalog/store title
+#   art:     pick = the art a user gets from Find artwork's Meta result (when the store's own art is a placeholder)
+
+frame:
+  battery: 82                       # %
+  running: com.StressLevelZero.BONELAB   # the game the Monitor tab and the sidebar's live card show (it needs
+                                         # store screenshots: Take screenshot adds one of it)
+
+games:
+  - package: com.camouflaj.manta
+    frame: internal
+    played: 0.6
+    tags: [Favorites]
+  - package: com.Sanzaru.Wrath2
+    art: pick       # the store's image service has a placeholder cover for it: use the picker's Meta result
+    frame: sd
+    played: 1.2
+    tags: [Favorites]
+  - package: com.twistedpixelgames.PILO
+    frame: internal
+    played: 2.4
+  - package: com.StressLevelZero.BONELAB
+    frame: internal
+    played: 0.05
+  - package: com.vertigogames.ImpactDevelopment
+    frame: outdated
+    played: 4.5
+  - package: com.CyanWorlds.Myst
+    frame: sd
+    played: 6
+  - package: com.playful.LuckysTale
+    frame: internal
+    played: 9
+    tags: [Favorites]
+  - package: com.FuturLab.PowerWashSimulator
+    frame: internal
+    played: 12
+  - package: com.CyanWorlds.Riven
+    added: 2
+  - package: com.FireproofStudios.TheRoomVR
+  - package: com.NewFolderGames.IAmCat
+  - package: com.BithellGames.Arcsmith
+  - package: com.zenstudios.PFXVRQuest
+  - package: com.Ubisoft.ACNexusVR
+  - package: com.Solfar.InDeath
+  - package: com.survios.Creed
+  - package: com.crytek.climb2
+  - package: com.thunderful.legobricktales
+  - package: com.GhostlyBirdGames.BattleGlide
+  - package: cn.vr4p.oculus4xvrplayerov
+  - package: rift.rick_and_morty_virtual_rick_ality
+    added: 5
@@ -0,0 +1,109 @@
+# The docs screenshots: scripts/showcase/render_docs.py renders each into docs/images/<name>.png from the demo
+# library (demo-library.yaml) with a pretend Frame, and rewrites a file only when the picture really changed.
+# Steps: see scripts/showcase/steps.py. Each shot starts in a fresh window (its own app session).
+#
+#   viewport: [w, h]   browser size in px (default below); scale: UI scale (1.0)
+#   crop:     {dialog: true, pad}: the open dialog; {anchor: <name>, left, top, width, height}: a box placed
+#             relative to the top-left corner of the element called <name> (left/top may be negative);
+#             or {x, y, width, height} in page px
+#   docs:     where the image is used (checked by the tests: every image a doc shows has an entry here)
+
+vars:
+  game: com.camouflaj.manta          # installed on the pretend Frame
+  new_game: com.CyanWorlds.Riven     # in the library, not installed yet
+
+defaults:
+  viewport: [1280, 820]
+
+shots:
+  - name: library
+    docs: [README.md]
+    steps:
+      - go: library
+      - wait_for: "On your Frame"
+      - settle: true
+
+  - name: game
+    docs: [docs/INSTALL.md, docs/SHOWCASE.md]
+    viewport: [1280, 1100]
+    steps:
+      - open_game: ${game}
+      - wait_for: "Where it's installed"
+
+  - name: game-settings
+    docs: [docs/INSTALL.md]
+    steps:
+      - open_game: ${game}
+      - call: {fn: settings_dialog, args: ["${game}"]}
+      - wait_for: "Game settings"
+    crop: {dialog: true}
+
+  - name: patches
+    docs: [docs/COMPATIBILITY.md]
+    viewport: [1280, 2600]
+    steps:
+      - open_game: {package: "${game}", advanced: true}
+      - wait_for: "What FramePort will do"
+    crop: {anchor: "What FramePort will do", left: -32, top: -12, width: 1044, height: 820}
+
+  - name: frame
+    docs: [docs/COMPATIBILITY.md]
+    steps:
+      - go: frame
+      - wait_for: "Ready to play"
+
+  - name: files
+    docs: [docs/INSTALL.md]
+    steps:
+      - go: files
+      - wait_for: "Upload files…"
+      - wait: 1.0
+      - hook: {name: select_files, args: [1, 2]}
+
+  - name: screenshots
+    docs: [README.md]
+    steps:
+      - go: screenshots
+      - wait_for: "Take screenshot"
+
+  - name: screenshot-viewer
+    docs: [README.md]
+    steps:
+      - go: screenshots
+      - wait_for: "Take screenshot"
+      - wait: 1.5
+      - call: {fn: screenshots_view.viewer, args: [0]}
+      - wait_for: "Close"
+
+  - name: type-on-frame
+    docs: [docs/INSTALL.md]
+    steps:
+      - hook: type_tab
+      - wait_for: "Keyboard connected"
+
+  - name: monitor
+    docs: [README.md]
+    viewport: [1280, 1150]
+    steps:
+      - go: monitor
+      - wait_for: "Processes"
+
+  # newer screens (docs/SHOWCASE.md's gallery; the README picks what it needs)
+  - name: live-view        # idle: a running stream shows its relay's random port and the data rate (no stable picture)
+    docs: [docs/SHOWCASE.md]
+    steps:
+      - go: live
+      - wait_for: "What the player sees"
+
+  - name: install-progress
+    docs: [docs/SHOWCASE.md]
+    steps:
+      - hook: {name: held_install, args: ["${new_game}"]}
+      - open_game: ${new_game}
+      - wait_for: "Cancel"
+
+  - name: appearance
+    docs: [docs/SHOWCASE.md]
+    steps:
+      - go: settings
+      - wait_for: "Portal (OLED)"
@@ -0,0 +1,147 @@
+# The install tutorial: from the download to the first game on the Steam Frame (docs/INSTALL.md links it; every
+# release attaches it as FramePort-install.mp4). FramePort starts as on a new computer (the "fresh" demo profile:
+# empty library, welcome screen, no Frame set up); what happens outside FramePort (the download, the setup line
+# run on the Frame) is told on instruction cards. Recorded by scripts/showcase/record_video.py; the format is in
+# docs/SHOWCASE.md ("Videos").
+
+output: docs/media/frameport-install.mp4
+budget_mb: 12
+poster_at: 9
+start:
+  profile: fresh           # FramePort's first start
+  frame: disconnected      # the Frame isn't set up yet
+  route: welcome
+setup:
+  - hook: {name: first_run, args: ["D:/Games", 1.4]}   # the tool download and the folder scan, at a watchable pace
+
+vars:
+  game: com.playful.LuckysTale
+
+title:
+  heading: Installing FramePort
+  line: From the download to your first game on the Steam Frame
+  seconds: 3.4
+end:
+  heading: You're set
+  line: Your game is in the Frame's Steam library. More help at frameport.app/docs/install/
+  footer: github.com/spoopyghosty0/frameport
+  seconds: 4.0
+
+scenes:
+  - name: download
+    seconds: 7.5
+    card:
+      eyebrow: "Step 1 · On your PC"
+      heading: Download FramePort
+      steps:
+        - "Open **github.com/spoopyghosty0/frameport** → **Releases** → the latest one"
+        - "Download the file for your PC: **FramePort-windows-x64.zip**, **FramePort-macos-arm64.zip** or **FramePort-linux-x64.tar.gz**"
+        - "Unpack it anywhere. No installer or admin rights needed"
+
+  - name: first-start
+    seconds: 7.5
+    card:
+      eyebrow: "Step 2 · First start"
+      heading: Start FramePort
+      steps:
+        - "**Windows:** open **FramePort.exe**. At “Windows protected your PC” choose **More info** → **Run anyway**"
+        - "**macOS:** right-click **FramePort.app** → **Open** → **Open**"
+        - "**Linux:** run **FramePort/FramePort**"
+      note: "FramePort isn't signed with a paid certificate, so your system asks once."
+
+  - name: welcome
+    caption: ["FramePort gets ready", "It downloads the tools it uses"]
+    hold: 1.0
+    steps:
+      - wait: 1.0
+      - hook: {name: wait_jobs, args: [40]}
+      - wait_for: "Java, OVRPort and apksigner are ready."
+      - wait: 1.0
+
+  - name: connect
+    caption: ["Connect your Steam Frame", "Once: one line on the Frame"]
+    hold: 1.5
+    steps:
+      - click: "Set up the Frame"
+      - wait: 1.6
+      - click: "Start setup"
+      - wait_for: "Waiting for your Frame to ask"
+      - wait: 1.0
+      - hover: "Copy"
+      - wait: 1.4
+
+  - name: on-the-frame
+    seconds: 11
+    card:
+      eyebrow: "Step 3 · On the Frame, first time only"
+      heading: Run the setup line
+      steps:
+        - "In the SteamVR dashboard: **Launch a program** → **Desktop**"
+        - "Open the app menu (bottom left) → **System** → **Konsole**"
+        - "Type the line and press **Enter** (or copy it from **frameport.app/setup** in Chromium)"
+      code: "curl -fsSL https://frameport.app/s | bash"
+      note: "Nothing changes on the Frame until you allow it on the PC."
+
+  - name: allow
+    caption: ["Allow it on your PC", "FramePort shows the same code as the Frame"]
+    hold: 1.2
+    steps:
+      - hook: {name: frame_asks, args: ["4831"]}
+      - wait_for: "steamframe wants to be set up"
+      - wait: 1.4
+      - hover: "Allow"
+      - wait: 0.8
+      - click: "Allow"
+      - wait: 0.8
+
+  - name: frame-setup
+    seconds: 7
+    card:
+      eyebrow: "On the Frame, by itself"
+      heading: The setup finishes on its own
+      steps:
+        - "**Developer Mode** turns on (no password)"
+        - "Steam restarts once and the desktop closes"
+        - "If Steam asks to install **Lepton**, confirm it"
+
+  - name: connected
+    caption: ["Your Frame is connected", "From now on FramePort finds it by itself"]
+    hold: 1.2
+    steps:
+      - hook: {name: pairing_done, args: [1.6]}
+      - wait_for: "Ready to play"
+      - wait: 1.2
+      - hover: "Quest games (Lepton)"
+      - wait: 1.6
+
+  - name: add-games
+    caption: ["Add your games", "Point FramePort at the folder with your games"]
+    hold: 1.0
+    steps:
+      - nav: "Library"
+      - wait: 1.2
+      - click: "Scan a folder…"
+      - hook: {name: wait_jobs, args: [40]}
+      - wait: 1.2
+      - hover: {name: "Lucky's Tale", dy: 0.3}
+      - wait: 1.0
+
+  - name: install
+    caption: ["Install a game", "FramePort patches it and adds it to the Frame's Steam library"]
+    hold: 1.2
+    steps:
+      - click: {name: "Lucky's Tale", dy: 0.35}   # (the title: the card's middle is its Install button)
+      - wait_for: "Where it's installed"           # (the game page: a click that missed fails here)
+      - wait: 1.2
+      - click: "Install on Frame"
+      - wait: 0.6
+      - move: [860, 640]
+      - hook: {name: wait_jobs, args: [45]}
+      - wait: 1.0
+
+  - name: play
+    caption: ["Play", "Start it from FramePort, or from Steam in the headset"]
+    steps:
+      - click: "Play on Frame"
+      - wait: 2.6
+      - park: true
@@ -0,0 +1,134 @@
+# The demo tour: FramePort in use (README teaser, docs/media, every release as FramePort-tour.mp4).
+# Recorded by scripts/showcase/record_video.py; the storyboard format is in docs/SHOWCASE.md ("Videos").
+
+output: docs/media/frameport-tour.mp4
+teaser: docs/images/tour-teaser.webp
+budget_mb: 12
+start:
+  profile: demo           # the library in use: games installed on the pretend Frame, BONELAB running
+  frame: connected
+
+vars:
+  game: com.camouflaj.manta        # installed on the pretend Frame
+  new_game: com.CyanWorlds.Riven   # installed during the tour
+
+title:
+  heading: FramePort
+  line: Quest, Android and PC VR games on the Steam Frame
+  seconds: 3.2
+end:
+  heading: FramePort
+  line: Open source · bring your own games
+  footer: github.com/spoopyghosty0/frameport
+  seconds: 3.6
+
+scenes:
+  - name: library
+    caption: ["Your library, ready for the Frame", "Quest, Android and PC VR games from your own folders"]
+    teaser: [0.8, 3.2]
+    steps:
+      - go: library
+      - wait: 1.2
+      - hover: {name: "Batman: Arkham Shadow", dy: 0.3}
+      - wait: 1.0
+      - hover: {name: "Marvel's Deadpool VR", dy: 0.3}
+      - wait: 0.8
+      - hover: "Assassin's Creed Nexus"
+      - wait: 0.8
+      - hover: "Lucky's Tale"
+      - wait: 0.8
+      - park: true
+      - type: "ri"
+      - wait: 1.6
+
+  - name: game
+    caption: ["Every game gets its own recipe", "Tested patches, or patches suggested for the game"]
+    steps:
+      - click: {name: "Riven", dy: 0.35}   # (the title: the card's middle is its Install button)
+      - wait: 1.8
+      - hover: "Works"
+      - wait: 0.7
+      - scroll: {dy: 420, at: [860, 560]}
+      - wait: 1.2
+      - scroll: {dy: -420, at: [860, 560]}
+      - wait: 0.5
+
+  - name: install
+    caption: ["One click to install", "Patched, uploaded, added to Steam and tested"]
+    teaser: [0.6, 4.0]
+    hold: 1.2
+    steps:
+      - click: "Install on Frame"
+      - wait: 0.6
+      - move: [860, 640]
+      - hook: {name: wait_jobs, args: [45]}
+      - wait: 1.0
+
+  - name: play
+    caption: ["Play from your PC", "Starts the game in the headset through Steam"]
+    teaser: [4.3, 3.2]
+    steps:
+      - nav: "Library"
+      - call: library_view.clear_search
+      - wait: 1.4
+      - hover: {name: "Asgard's Wrath 2", dy: 0.3}
+      - wait: 0.6
+      - hover: {name: "Batman: Arkham Shadow", dy: 0.3}
+      - wait: 0.6
+      - click: {name: "Play on Frame", nth: 0}
+      - wait: 2.6
+      - park: true
+      - wait: 0.4
+
+  - name: monitor
+    caption: ["See what the Frame is doing", "Frame rate, CPU, GPU, temperatures and every process, live"]
+    teaser: [0.5, 2.6]
+    steps:
+      - nav: "Monitor"
+      - wait: 2.4
+      - hover: "Temperature"   # (a tile only: "GPU" is also the process table's sortable column)
+      - wait: 1.0
+      - hover: "Battery"
+      - wait: 1.0
+      - click: "Show details"
+      - wait: 1.8
+      - park: true
+
+  - name: screenshots
+    caption: ["Screenshots from the headset", "Take one from the PC, then view or download them"]
+    steps:
+      - nav: "Screenshots"
+      - wait: 1.6
+      - click: "Take screenshot"
+      - wait_for: "BONELAB · 2026-10-04 21:50"
+      - wait: 0.8
+      - click: "BONELAB · 2026-10-04 21:50"
+      - wait: 2.0
+      - click: "Close"
+      - wait: 0.4
+
+  - name: files
+    caption: ["Files on the Frame", "Upload and download videos, mods and saves"]
+    steps:
+      - nav: "Files"
+      - wait: 1.6
+      - drag: ["Concert 8K 3D.mp4", "Mars landing (VR180).mkv"]
+      - wait: 1.0
+      - right_click: "Earth from orbit (360).mp4"
+      - wait: 1.4
+      - press: Escape
+      - wait: 0.6
+
+  - name: themes
+    caption: ["Make it yours", "Dark themes, including true black for OLED screens"]
+    steps:
+      - nav: "Settings"
+      - wait: 1.4
+      - click: "Portal (OLED)"
+      - wait: 1.4
+      - click: "Original"
+      - wait: 1.4
+      - click: "Portal"
+      - wait: 1.0
+      - nav: "Library"
+      - wait: 1.4
@@ -0,0 +1,13 @@
+{
+  "name": "Ember & Ice",
+  "base": "portal",
+  "dual": true,
+  "colors": {
+    "ACCENT": "#FF5A36",
+    "ACCENT_SOFT": "#3A1710",
+    "SECONDARY": "#5CE1E6",
+    "SECONDARY_SOFT": "#0E3033",
+    "PC": "#5CE1E6",
+    "INFO": "#5CE1E6"
+  }
+}
@@ -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), the
 live view's hardware H.264 encoder fp_venc (linux-arm64-bin, static freestanding executable), and rewrites artifacts/SHA256SUMS. Run `frameport parity` afterwards to see which games change.

-    python native/build.py [--only adapter,bridge,compat,langpack,glshim,eglfmt,glmv,ovrtrace,dex,xrlayer,oculushmd,xrshim,vkshim,zinkfix,ovrpshim,vrsettings,venc] [--ndk PATH]
+    python native/build.py [--only adapter,bridge,compat,langpack,glshim,eglfmt,glmv,ovrtrace,dex,xrlayer,oculushmd,xrshim,vkshim,zinkfix,ovrpshim,vrsettings,venc,vroverlay_probe] [--ndk PATH]
 """
 from __future__ import annotations

@@ -227,6 +227,25 @@ def build_vrsettings(tc: Path):
         f"/out:{out / 'fp_vrsettings.exe'}"])


+VROVERLAY_IMPORTS = VRSETTINGS_IMPORTS + ("Sleep",)
+
+
+def build_vroverlay_probe(tc: Path):
+    """fp_vroverlay_probe.exe (Windows x64 diagnostic, run under Proton on the Frame): does an OpenVR overlay app show
+    up? Not shipped: written to native/.cache/vroverlay_probe/ (opt-in: --only vroverlay_probe)."""
+    src = HERE / "vroverlay_probe"
+    work = CACHE / "vroverlay_probe"
+    work.mkdir(parents=True, exist_ok=True)
+    (work / "kernel32.def").write_text("LIBRARY kernel32.dll\nEXPORTS\n" + "".join(f"    {n}\n" for n in VROVERLAY_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_vroverlay_probe.c", "-o", work / "fp_vroverlay_probe.obj"], cwd=src)
+    run([tc / "bin/lld-link", "/nologo", "/Brepro", "/nodefaultlib", "/entry:start", "/subsystem:console",
+         "/dynamicbase", "/highentropyva", "/nxcompat", work / "fp_vroverlay_probe.obj", work / "kernel32.lib",
+         f"/out:{work / 'fp_vroverlay_probe.exe'}"])
+
+
 def build_bridge(tc: Path):
    src = HERE / "vrapi-bridge"
    inc = openxr_include("bridge")
@@ -384,8 +403,10 @@ def main():
             "oculushmd": lambda: build_oculushmd(tc), "vkshim": lambda: build_vkshim(tc),
             "zinkfix": lambda: build_zinkfix(tc),
             "ovrpshim": lambda: build_ovrpshim(tc),
-             "vrsettings": lambda: build_vrsettings(tc), "venc": lambda: build_venc(tc)}
-    for name in ("adapter", "bridge", "compat", "langpack", "glshim", "eglfmt", "glmv", "ovrtrace", "xrshim", "vkshim", "zinkfix", "ovrpshim", "dex", "xrlayer", "oculushmd", "vrsettings", "venc"):
+             "vrsettings": lambda: build_vrsettings(tc), "venc": lambda: build_venc(tc),
+             "vroverlay_probe": lambda: build_vroverlay_probe(tc)}
+    for name in ("adapter", "bridge", "compat", "langpack", "glshim", "eglfmt", "glmv", "ovrtrace", "xrshim", "vkshim", "zinkfix", "ovrpshim", "dex", "xrlayer", "oculushmd", "vrsettings", "venc",
+                 "vroverlay_probe"):
        if name in parts:
            log(f"build {name}")
            steps[name]()
@@ -1,50 +1,148 @@
-# Hardware HEVC for Lepton
+# Shared hardware video decoding for Lepton

-`frameport_hevc.cpp` implements `OMX.frameport.hevc.decoder` using the Iris
-stateful V4L2 decoder through FFmpeg's LGPL hardware wrapper. The FFmpeg build
-does not contain a software HEVC decoder. Byte-buffer clients receive full-size
+`frameport_hevc.cpp` implements Android OMX decoders for HEVC Main, H.264
+(Constrained) Baseline/Main/(Constrained) High and VP9 Profile 0 using Iris
+stateful V4L2 through FFmpeg. Android reports constrained H.264 streams under
+separate profile values, so they are listed as stock decoders list them.
+These are 8-bit 4:2:0 decoders. Format-aware clients keep Android's existing
+codecs for Main10/HDR and protected content; clients selecting by MIME alone
+must still respect the component's advertised profiles. Other codec types
+retain Android's existing codecs. Applications that explicitly select their
+own software decoder bypass this integration. Byte-buffer clients receive full-size
 planar frames. Native surface clients receive YUV in Android hardware buffers,
-with acquire/release fences. The hardware decoder's NV12 planes are copied to
-the Android buffer in disjoint parallel row bands without CPU colour conversion.
-The same persistent worker pool handles native YUV copies and legacy RGBA
-conversion; all workers finish before the buffer is unlocked or the decoded
+with acquire/release fences. For large hardware-decoded NV12 surfaces (at least
+4096×2048 pixels), compatible linear NV12 buffers are imported into Vulkan
+and copied on the GPU without CPU pixel access or colour conversion. The decoded
+AVFrame remains held until the transfer fence completes, preventing its Iris
+capture buffer from being requeued. Explicit FOREIGN queue-family transfers
+return both buffers to their Android/decoder owners before delivery. Imports are
+cached within a bounded pool and cleared before decoder reconfiguration or flush.
+Unsupported layouts, unavailable Vulkan capabilities and import failures retain
+the parallel CPU copy; a submitted transfer that fails to complete reports an
+OMX error instead of exposing incomplete pixels. This removes the CPU frame copy
+on compatible surfaces but still performs one GPU copy; it is not direct decoding
+into Android's consumer buffers. Small surfaces use disjoint parallel CPU row bands.
+The same persistent worker pool handles native YUV copies, byte-buffer planar
+copies and legacy RGBA conversion (helpers start at panorama sizes); all workers finish before the buffer is unlocked or the decoded
 frame is released. Legacy software surfaces
 retain parallel NEON RGBA conversion. Input timestamps, dynamic dimensions, EOS and
 seek/flush are preserved.

-This uses the tested Lepton Android 11 SoftOMX ABI. FramePort stores the plugin,
-codec XML and a narrow Podman wrapper per game. The launcher adds this wrapper
-to its child process's PATH. Only the matching game's `podman run` gains a
-read-only plugin/XML mount and `/dev/video-dec0`. All other Podman operations
-pass through. Shared Lepton, drivers and original MP4 assets are unchanged.
+This uses the tested Lepton Android 11 SoftOMX ABI. On connection, FramePort
+deploys the plugin, codec XML and Podman wrapper once into the agent's shared
+`~/.local/share/frameport/video-codec/versions/<manifest-sha256>` store.
+Payload checksums are verified before an atomic `current` symlink exposes the
+complete version. Older clients cannot downgrade a newer codec revision.
+A Frame keeps an installed codec of the same or a newer manifest `revision`
+(two PCs with different builds of one revision don't replace each other's), so
+`build.py` bumps the revision with every change. A failed install is not
+retried during the same connection.
+Superseded versions are pruned, keeping the active version and the one it
+replaced (a launch that resolved the previous `current` can still mount it).
+Games opt in through their recipe: the patch `frame.hw_video_decode` (no APK
+change; suggested when the APK decodes video through MediaCodec, ExoPlayer or
+VLC) makes the agent give that game's launcher the line that puts the shared
+wrapper first on Lepton's PATH (`deployment.json` `hw_video_decode`;
+`upgrade_launchers` adds or removes it on existing launchers). Only that game's
+matching `podman run` gains a read-only plugin/XML mount and `/dev/video-dec0`.
+All other Podman operations pass through. FramePort's setting "Hardware video
+decoding" turns it off for every game (`video-codec/disabled`, checked by the
+launcher line and the wrapper at every start); `FRAMEPORT_NO_HW_VIDEO=1` in a
+game's Steam launch options turns it off for that game. Shared Lepton, drivers and original MP4 assets are unchanged.
 Unknown runtime ABIs retain the stock codecs and log why. A future native
 Lepton hardware plugin takes precedence.

 The wrapper resolves a fallback Podman from PATH outside its own directory
-before reading deployment configuration. Missing/malformed configuration,
+before reading deployment configuration. Lepton's Android-only `env -i PATH`
+attach commands use host default paths if their PATH contains no host Podman.
+Missing/malformed configuration,
 recursive executable paths, mount-preparation errors and failed exec calls
 retain the original arguments and launch stock Podman. The agent publishes
-`deployment.json` and codec payloads before atomically exposing `bin/podman`.
+`deployment.json` and codec payloads before exposing the complete version.
+The merged runtime XML is written to `$XDG_RUNTIME_DIR/frameport-video/`
+(never into the verified version directory), named per runtime path, with
+process-local temporary filenames, so concurrent app launches do not overwrite
+each other's staging.

-Packaging is limited to the validated arm64 Batman package (`com.camouflaj.manta`).
-Unrelated games and arm32 APKs do not receive these assets or the native video
-setting. Rebuilding an older unrelated test APK removes its previous codec
-assets, and installation disables its old per-game wrapper. The presence of
-an MP4 alone does not establish compatible video-surface or overlay semantics.
+No package check or MP4 scan selects decoding: the recipe does. Older embedded
+codec assets are removed when an APK is rebuilt, and agent 70's per-game
+`<base>/frameport-codec` folders are removed once the launcher is converted (a
+game that had one, Batman, keeps hardware decoding). The
+codec has no OpenXR calls, camera poses or composition changes. Batman's
+`surface_native` renderer remains package-scoped and separate. Other apps keep
+their existing rendering path; hardware decoding alone does not eliminate
+surface upload/conversion or GPU rendering bottlenecks.

-The plugin probes admission of an 8192x4096 decoder session before advertising
-its component. On the tested SteamOS kernel, another active decoder (including
-Steam's web helper) can cause Iris to reject that session. In that condition it
-leaves Android's stock software decoder available. This fallback preserves
-playback, but does not provide hardware performance. Admission can change after
-the probe; this is not a fix for the kernel's session-accounting defect.
+The plugin enumerates coded formats and probes each at 1920x1080, not Batman's
+8K geometry. Unavailable components are omitted so Android retains its stock
+decoders. Actual-session admission can still fail (including Iris's concurrent
+session-accounting issue: while any other decoder session is open, 8K is
+refused with ENOMEM). SteamVR's link (`vrlinkrunthread`) holds a session for
+about 12 s around every game start, when the plugin loads too (measured on the
+dev Frame, 2026-10-09), so a refused session is retried every 250 ms until 20 s
+after the plugin loaded (later: for 2 s); initialization then falls back to
+FFmpeg software decoding inside the already-selected component. VP9 is limited
+to 4096x2304 (codec list and component; larger VP9 decodes in software): at
+7680x3840 Iris accepted the session but never returned a picture. For every
+VP9 frame that isn't shown (alt-ref/hidden frames split from superframes) Iris
+returns an empty capture buffer (bytesused 0, no LAST flag, time 0). FFmpeg's
+wrapper returned those as pictures and, during the EOS drain, took the first one
+for the end of the stream, losing the pictures still in the driver (two-pass
+VP9 at 4K: 573 of 600 frames, measured 2026-10-10). `build.py` makes the wrapper
+requeue empty non-LAST buffers instead; the drain ends at the LAST buffer, or
+after a skipped empty buffer at one silent second, so a driver that ends a drain
+with an empty unflagged buffer cannot block. This preserves the client's
+buffer/surface contract without requiring the app to retry another codec.
+
+During hardware playback, bounded references to two GOPs of compressed packets
+permit software recovery after a driver-reported damaged picture. Replay drops
+already-presented timestamps, retaining ordered output and EOS. The cache is
+capped at 64 MiB/512 packets; if no usable keyframe remains, ordinary OMX error
+handling applies. After recovery, later seeks flush the software decoder for
+that component until reset. This is a fallback, not a repair to the Iris driver. VP9 seek tests
+on this Frame exercised it. Capture buffers use FFmpeg's general-purpose budget
+of 20 at ordinary sizes, which avoids the stall observed with the earlier
+four-buffer H.264 configuration. At panorama sizes the budget follows the
+standards' reference-picture bound plus four (10 at 8K HEVC/H.264, 13 for VP9),
+instead of holding about 1 GB of 8K capture memory. Only hardware-reported
+damage triggers recovery; software decoders conceal damage themselves and their
+pictures are output, as Android's stock decoders do.
+A seek after the stream has fully drained (replay or loop after EOS) restarts
+the open hardware session in place with `V4L2_DEC_CMD_START`, keeping its
+buffers; this works for all three codecs. The component checks the restart
+result through a read-only FFmpeg option. A failed restart closes that session
+and continues in software, rather than waiting indefinitely for hardware
+output. A seek during playback reopens the
+hardware session: on the tested Iris kernel, stopping and restarting a running
+session's queues failed the driver's session admission ("current session not
+supported", -12) and left buffers unreturned (videobuf2 kernel warnings), so it
+is not used. On the same kernel, reopening VP9 after a seek produced a damaged
+capture picture and a kernel fault in `lookup_swap_cgroup_id` during unmap, so
+VP9 switches to software on a seek during playback rather than reopening that
+hardware session; H.264 and HEVC retain hardware decoding after seeking.
+This compatibility guard is independent of app/package identity.
+
+Android CODECCONFIG parameter sets are prepended to the first H.264/HEVC
+hardware access unit because FFmpeg's V4L2 wrapper does not submit extradata
+to the driver. Parameter sets sent again mid-stream without a flush (streaming
+apps, restarted encoders) replace the stored configuration and are submitted
+in-band before the next access unit, rather than failing the session. Complete-frame parsers identify keyframes for bounded recovery,
+including ACodec clients that omit the OMX input SYNCFRAME flag.

 On the tested headset, disabling **hardware video decoding in Steam's interface**
 and restarting Steam removed that conflicting session. This setting does not
 disable the game's Iris decoder. It is a SteamOS-driver workaround, not a kernel
 fix; FramePort does not silently change the global Steam setting.

-The native surface renderer and stereo composition are documented in
+Signalled bitstream colour (primaries, transfer, matrix, range) is reported to
+ACodec as Android's stock decoders do, so the surface dataspace can follow it;
+container values take precedence. Legacy RGBA conversion uses the resulting
+matrix, BT.709 for unsignalled HD (Android's convention), and full-range BT.601
+or BT.709 where signalled. A full-range BT.709 table matches the pinned Arm64
+libyuv ABI. Both hardware NV12 and software planar conversions produce RGBA
+channel order; native YUV output retains its original planes and dataspace.
+
+Batman's native surface renderer and stereo composition are documented in
 [Surface video playback](../../docs/SURFACE_VIDEO.md). The original decoded
 panorama is retained; projected eye views are generated on the GPU.

@@ -54,13 +152,21 @@ Build on Linux/WSL with Android NDK r27c and the tested Lepton rootfs:
 python native/hevc/build.py --ndk /path/to/android-ndk-r27c --lepton-root /path/to/Lepton/images/rootfs
 ```

+Paths with spaces work: the builder links the repo, the NDK and the rootfs into
+a space-free temp dir and compiles through those link paths (FFmpeg's configure
+splits `--extra-cflags` on whitespace); with `-no-canonical-prefixes` clang keeps
+the link path too, so the prefix maps give the same bytes wherever the real
+folders are. Each build starts from freshly extracted FFmpeg sources.
+
 The build requires Linux x86-64, Python 3.12+, Make, Perl, and a working host C
 compiler with libc development headers (FFmpeg builds host tools). The NDK
 revision is checked against `27.2.12479018`. Previous FFmpeg objects and install
 output are discarded. Both FFmpeg and the plugin use that NDK's compiler and
 linker. A private copy of its libc++ headers uses Android's platform `__1`
 namespace; `-nostdinc++` prevents mixing these with the NDK's `__ndk1` headers.
-The build does not edit the NDK or ship a second libc++.
+The build uses libc++'s verbose-abort customization hook to avoid a newer NDK
+abort symbol absent from Android 11's platform runtime. It does not edit the NDK
+or ship a second libc++.

 Compiler file-prefix maps cover source, NDK and runtime paths. FFmpeg's
 generated configuration string is normalized separately because it embeds
@@ -72,13 +178,34 @@ clean shutdown in an isolated headset container.

 AOSP headers in `platform/` come from `android-11.0.0_r48` and retain their
 original license notices. `fetch_headers.py` records the upstream paths.
-The builder downloads unmodified FFmpeg 7.1.1 source from
+The builder downloads the pinned FFmpeg 7.1.1 archive from
 https://ffmpeg.org/releases/ffmpeg-7.1.1.tar.xz and verifies SHA256
 `733984395e0dbbe5c046abda2dc49a5544e7e0e1e2366bba849222ae9e3a03b1`.
-Its LGPL build configuration is recorded in `build.py` and the license is
-included in the APK/per-game codec directory as `COPYING.FFmpeg`.
+`build.py` applies explicit wrapper changes: VP9 V4L2 uses the same
+`vp9_superframe_split` input filter as the software decoder, empty non-LAST
+capture buffers (hidden VP9 frames) are requeued rather than output or taken
+for the end of a drain, and the V4L2
+decoder gains a flush callback that restarts a drained decoder in place
+(`V4L2_DEC_CMD_START` with both queues still streaming). Its read-only
+`frameport_flush_error` option reports failed or premature restarts to the
+component, because `avcodec_flush_buffers` itself has no return value.
+Without it a restart after EOS could only close and reopen the hardware
+session. `v4l2_export.c.inc` adds a capture-buffer export interface inside FFmpeg,
+so the component does not access FFmpeg's private buffer structures. The caller
+must retain the AVFrame until GPU work completes. Its LGPL build
+configuration and those source changes are recorded in the builder. The license
+is included in the shared version directory as `COPYING.FFmpeg`.

 `omx_decode_probe.cpp` and `media_codec_probe.cpp` exercise decoder selection,
 original-size output, timestamps, flush/seek, EOS and teardown on the headset.
+The OMX probe's `restartfail` mode uses the fault shim in
+`tests/fixtures/src/video_codec_faults.c` to reject a drained-session restart;
+`software_rgba` exercises software fallback and legacy surface conversion
+together. `color_probe.cpp` compares both platform NEON conversion paths with
+the full-range BT.709 equations, including channel order and extreme values.
+The OMX probe's `native` mode hashes original-size Android YUV buffers and checks
+GPU submissions and replayed pixels. `native_cpu` disables Vulkan initialization;
+`native_importfail` rejects memory imports. Both verify fallback preserves the
+same surface contract and pixels without GPU submissions.
 The native surface fixtures cover buffer ownership, GPU projection and
 composition. See the surface documentation for validation and limitations.
@@ -11,6 +11,7 @@ import os
 import shutil
 import subprocess
 import tarfile
+import tempfile
 import urllib.request
 from pathlib import Path

@@ -19,10 +20,98 @@ ARTIFACTS = HERE.parents[1] / "artifacts/hevc"
 FFMPEG_SHA = "733984395e0dbbe5c046abda2dc49a5544e7e0e1e2366bba849222ae9e3a03b1"
 RUNTIME_SHA = "456e912c75cd389abcf6a63bc80e2a53bdc334371d00b200c93680388ae955e2"
 NDK_REVISION = "27.2.12479018"
+FLUSH_SOURCE = r"""static void v4l2_flush(AVCodecContext *avctx)
+{
+    V4L2m2mPriv *priv = avctx->priv_data;
+    V4L2m2mContext *s = priv->context;
+    struct v4l2_decoder_cmd cmd = { .cmd = V4L2_DEC_CMD_START };
+
+    av_packet_unref(&s->buf_pkt);
+    priv->frameport_flush_error = 0;
+    /* Only a drained decoder restarts in place: it has returned every picture
+     * and is stopped until V4L2_DEC_CMD_START (both queues keep streaming).
+     * Restarting a running decoder's queues failed Iris session admission and
+     * left its buffers unreturned (kernel warnings): callers reopen instead. */
+    if (!s->draining || !s->capture.done) {
+        priv->frameport_flush_error = AVERROR(EINVAL);
+        av_log(avctx, AV_LOG_WARNING, "flush before the drain completed; reopen the decoder\n");
+        return;
+    }
+    if (ioctl(s->fd, VIDIOC_DECODER_CMD, &cmd) < 0) {
+        priv->frameport_flush_error = AVERROR(errno);
+        av_log(avctx, AV_LOG_ERROR, "V4L2_DEC_CMD_START after drain: %s\n", av_err2str(priv->frameport_flush_error));
+        return;
+    }
+    s->draining = 0;
+    s->output.done = s->capture.done = 0;
+}
+"""


-def run(args, **kwargs):
-    subprocess.run([str(a) for a in args], check=True, **kwargs)
+# Iris returns an empty capture buffer (bytesused 0, no LAST flag) for every
+# VP9 frame that isn't shown (alt-ref/hidden frames split from superframes).
+# FFmpeg's wrapper took any empty buffer during a drain for the end of the
+# stream, so the pictures still in the driver after EOS were lost (two-pass VP9:
+# 573 of 600), and outside a drain it returned them as pictures without content.
+# Requeue them instead; the drain still ends at the LAST buffer (or EPIPE), and
+# after a skipped empty buffer a silent second ends it too, so a driver that
+# ends a drain with an empty buffer and no LAST flag cannot block the caller.
+EMPTY_DECLARE = "        .fd = ctx_to_m2mctx(ctx)->fd,\n    };\n    int i, ret;\n"
+EMPTY_POLL = """    for (;;) {
+        ret = poll(&pfd, 1, timeout);
+        if (ret > 0)
+            break;
+        if (errno == EINTR)
+            continue;
+        return NULL;
+    }
+"""
+EMPTY_DRAIN = """        if (ctx_to_m2mctx(ctx)->draining && !V4L2_TYPE_IS_OUTPUT(ctx->type)) {
+            int bytesused"""
+EMPTY_SKIP = """        if (!V4L2_TYPE_IS_OUTPUT(ctx->type) && ctx->buffers && buf.index < ctx->num_buffers &&
+            !(V4L2_TYPE_IS_MULTIPLANAR(buf.type) ? buf.m.planes[0].bytesused : buf.bytesused) &&
+            !(buf.flags & (V4L2_BUF_FLAG_LAST | V4L2_BUF_FLAG_ERROR))) {
+            /* an empty picture that doesn't end the stream (Iris: a hidden VP9 frame) */
+            if (ff_v4l2_buffer_enqueue(&ctx->buffers[buf.index]) < 0) {
+                ctx->done = 1;
+                return NULL;
+            }
+            skipped_empty = 1;
+            goto start;
+        }
+
+"""
+
+
+def skip_empty_pictures(context_text: str) -> str:
+    """libavcodec/v4l2_context.c with empty non-LAST capture buffers requeued (see EMPTY_SKIP)."""
+    if any(context_text.count(text) != 1 for text in (EMPTY_DECLARE, EMPTY_POLL, EMPTY_DRAIN)):
+        raise RuntimeError("unexpected FFmpeg V4L2 context source")
+    return (context_text
+        .replace(EMPTY_DECLARE, EMPTY_DECLARE.replace("int i, ret;", "int i, ret, skipped_empty = 0;"))
+        .replace(EMPTY_POLL, EMPTY_POLL.replace(
+            "        ret = poll(&pfd, 1, timeout);\n        if (ret > 0)\n            break;\n",
+            "        ret = poll(&pfd, 1, skipped_empty && ctx_to_m2mctx(ctx)->draining &&\n"
+            "                   (timeout < 0 || timeout > 1000) ? 1000 : timeout);\n"
+            "        if (ret > 0)\n            break;\n"
+            "        if (!ret && skipped_empty && ctx_to_m2mctx(ctx)->draining) {\n"
+            "            ctx->done = 1;\n            return NULL;\n        }\n"))
+        .replace(EMPTY_DRAIN, EMPTY_SKIP + EMPTY_DRAIN))
+
+
+def run(args, cwd=None, env=None):
+    # PWD keeps the shell's (and FFmpeg configure's) idea of the directory on the space-free link path
+    env = dict(env or os.environ, **({"PWD": str(cwd)} if cwd else {}))
+    subprocess.run([str(a) for a in args], check=True, cwd=cwd, env=env)
+
+
+def space_free(links: Path, name: str, target: Path) -> Path:
+    """FFmpeg's configure splits --extra-cflags on whitespace, so a repo/NDK/rootfs path with spaces breaks the
+    build. Build through unresolved symlinks in a space-free temp dir; the prefix maps name these link paths, so the
+    output is the same bytes wherever the real folders are."""
+    link = links / name
+    link.symlink_to(target, target_is_directory=True)
+    return link


 def main():
@@ -38,28 +127,79 @@ def main():
    if not (ndk / "bin/clang++").exists():
        parser.error("use the Linux NDK r27c (Windows: run this builder inside WSL)")
    runtime = args.lepton_root.resolve()
+    with tempfile.TemporaryDirectory(prefix="fp-hevc-") as tmp:
+        links = Path(tmp)
+        if any(c.isspace() for c in str(links)):
+            parser.error(f"temp dir {links} has spaces: set TMPDIR to a folder without spaces")
+        build(parser, space_free(links, "repo", HERE.parents[1]), space_free(links, "ndk", ndk_root),
+              space_free(links, "rootfs", runtime))
+
+
+def build(parser, repo: Path, ndk_root: Path, runtime: Path):
+    here = repo / HERE.relative_to(HERE.parents[1])
+    artifacts = repo / ARTIFACTS.relative_to(HERE.parents[1])
+    ndk = ndk_root / "toolchains/llvm/prebuilt/linux-x86_64"
    if hashlib.sha256((runtime / "vendor/lib64/libstagefright_softomx.so").read_bytes()).hexdigest() != RUNTIME_SHA:
        parser.error("unverified SoftOMX ABI; validate and update the fingerprint before rebuilding")
-    cache = HERE.parent / ".cache/hevc"
+    cache = here.parent / ".cache/hevc"
    cache.mkdir(parents=True, exist_ok=True)
    archive = cache / "ffmpeg-7.1.1.tar.xz"
    if not archive.exists():
        urllib.request.urlretrieve("https://ffmpeg.org/releases/ffmpeg-7.1.1.tar.xz", archive)
    if hashlib.sha256(archive.read_bytes()).hexdigest() != FFMPEG_SHA:
        raise RuntimeError("FFmpeg source checksum mismatch")
-    with tarfile.open(archive) as tar:
-        tar.extractall(cache, filter="data")
    source = cache / "ffmpeg-7.1.1"
    install = cache / "ffmpeg-install"
    # Discard previous objects/configuration so a host compiler or changed
-    # configure flags cannot silently survive a rebuild.
-    if (source / "config.mak").exists():
-        run(["make", "distclean"], cwd=source)
-    if install.exists():
-        shutil.rmtree(install)
+    # configure flags cannot silently survive a rebuild (a distclean keyed on
+    # config.mak never ran: FFmpeg 7 keeps it in ffbuild/), and start from
+    # unpatched sources (the edits below are applied once).
+    for old in (source, install):
+        if old.exists():
+            shutil.rmtree(old)
+    with tarfile.open(archive) as tar:
+        tar.extractall(cache, filter="data")
+    # Unlike FFmpeg's software VP9 decoder, its V4L2 wrapper does not split
+    # packed VP9 superframes. Iris requires the same individual-frame input.
+    decoder_source = source / "libavcodec/v4l2_m2m_dec.c"
+    decoder_text = decoder_source.read_text()
+    original_vp9 = 'M2MDEC(vp9,   "VP9",   AV_CODEC_ID_VP9,        NULL);'
+    if decoder_text.count(original_vp9) != 1:
+        raise RuntimeError("unexpected FFmpeg VP9 wrapper source")
+    decoder_text = decoder_text.replace(original_vp9, 'M2MDEC(vp9, "VP9", AV_CODEC_ID_VP9, "vp9_superframe_split");')
+    # The wrapper has no flush callback, so restarting after EOS (replay, loop)
+    # could only close and reopen the hardware session. Add the stateful
+    # decoder's restart after a completed drain (V4L2_DEC_CMD_START).
+    close_fn = "static av_cold int v4l2_decode_close(AVCodecContext *avctx)\n"
+    close_cb = "        .close          = v4l2_decode_close, \\\n"
+    if decoder_text.count(close_fn) != 1 or decoder_text.count(close_cb) != 1:
+        raise RuntimeError("unexpected FFmpeg V4L2 decoder source")
+    decoder_text = decoder_text.replace(close_fn, FLUSH_SOURCE + "\n" + close_fn).replace(
+        close_cb, close_cb + "        .flush          = v4l2_flush, \\\n")
+    decoder_source.write_text(decoder_text)
+    # avcodec_flush_buffers has no return value. Expose restart status through
+    # an AVOption rather than having the OMX component inspect private structs.
+    private_header = source / "libavcodec/v4l2_m2m.h"
+    private_text = private_header.read_text()
+    field = "    int num_capture_buffers;\n} V4L2m2mPriv;"
+    option_end = "    { NULL},\n};"
+    if private_text.count(field) != 1 or decoder_text.count(option_end) != 1:
+        raise RuntimeError("unexpected FFmpeg V4L2 private options source")
+    private_header.write_text(private_text.replace(field, "    int num_capture_buffers;\n"
+                                                  "    int frameport_flush_error;\n} V4L2m2mPriv;"))
+    decoder_source.write_text(decoder_text.replace(option_end,
+        '    { "frameport_flush_error", "Last drained-session restart error",\n'
+        '        OFFSET(frameport_flush_error), AV_OPT_TYPE_INT, {.i64 = 0}, INT_MIN, 0,\n'
+        '        FLAGS | AV_OPT_FLAG_READONLY },\n' + option_end))
+    context_source = source / "libavcodec/v4l2_context.c"
+    context_source.write_text(skip_empty_pictures(context_source.read_text()))
+    buffers_source = source / "libavcodec/v4l2_buffers.c"
+    buffers_source.write_text(buffers_source.read_text() + (here / "v4l2_export.c.inc").read_text())
    env = dict(os.environ, PATH=str(ndk / "bin") + os.pathsep + os.environ["PATH"])
-    prefix_maps = [f"-ffile-prefix-map={HERE.parents[1]}=.", f"-ffile-prefix-map={ndk_root}=android-ndk-r27c",
-                   f"-ffile-prefix-map={runtime}=lepton-rootfs"]
+    prefix_maps = [f"-ffile-prefix-map={repo}=.", f"-ffile-prefix-map={ndk_root}=android-ndk-r27c",
+                   f"-ffile-prefix-map={runtime}=lepton-rootfs",
+                   # clang otherwise resolves its own path (through the link) and embeds its real include dir
+                   "-no-canonical-prefixes"]
    run([
        source / "configure", f"--prefix={install}", "--target-os=android", "--arch=aarch64",
        "--enable-cross-compile", "--cc=aarch64-linux-android30-clang", "--cxx=aarch64-linux-android30-clang++",
@@ -68,8 +208,9 @@ def main():
        "--extra-cxxflags=" + " ".join(prefix_maps),
        "--disable-everything", "--disable-autodetect", "--enable-v4l2-m2m", "--disable-programs",
        "--disable-doc", "--enable-pic", "--enable-static", "--disable-shared",
-        "--enable-decoder=hevc_v4l2m2m", "--enable-parser=hevc", "--enable-bsf=hevc_mp4toannexb",
-        "--enable-demuxer=mov", "--enable-protocol=file", "--enable-avcodec", "--enable-avformat",
+        "--enable-decoder=hevc_v4l2m2m,h264_v4l2m2m,vp9_v4l2m2m,hevc,h264,vp9",
+        "--enable-parser=hevc,h264,vp9", "--enable-bsf=hevc_mp4toannexb,h264_mp4toannexb,vp9_superframe_split",
+        "--enable-demuxer=mov,matroska", "--enable-protocol=file", "--enable-avcodec", "--enable-avformat",
        "--enable-avutil", "--disable-avdevice", "--disable-avfilter", "--disable-swscale",
        "--disable-swresample", "--disable-postproc",
    ], cwd=source, env=env)
@@ -78,10 +219,10 @@ def main():
    # generated string too, retaining the options without host paths.
    config = source / "config.h"
    text = config.read_text()
-    for path, replacement in ((ndk_root, "android-ndk-r27c"), (runtime, "lepton-rootfs"), (HERE.parents[1], ".")):
+    for path, replacement in ((ndk_root, "android-ndk-r27c"), (runtime, "lepton-rootfs"), (repo, ".")):
        text = text.replace(str(path), replacement)
    config.write_text(text)
-    run(["make", "-j4"], cwd=source, env=env)
+    run(["make", f"-j{os.cpu_count() or 4}"], cwd=source, env=env)
    run(["make", "install"], cwd=source, env=env)
    # Use the platform libc++ namespace. Do not change the NDK's own headers or
    # distribute another libc++, which would create a conflicting private ABI.
@@ -89,29 +230,32 @@ def main():
    shutil.copytree(ndk / "sysroot/usr/include/c++/v1", cpp, dirs_exist_ok=True)
    site = cpp / "__config_site"
    site.write_text(site.read_text().replace("_LIBCPP_ABI_NAMESPACE __ndk1", "_LIBCPP_ABI_NAMESPACE __1"))
-    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    artifacts.mkdir(parents=True, exist_ok=True)
    run([
        ndk / "bin/aarch64-linux-android30-clang++", "-std=gnu++17", "-O3", "-fPIC", "-shared",
        *prefix_maps,
        "-fno-rtti", "-fno-exceptions", "-nostdlib++", "-nostdinc++", "-Wall", "-Wextra", "-Werror",
-        "-Wno-unused-private-field", "-isystem", cpp, "-I", HERE / "platform",
-        "-I", HERE / "platform/media/openmax", "-I", install / "include", HERE / "frameport_hevc.cpp",
+        "-D_LIBCPP_VERBOSE_ABORT(...)=__builtin_abort()",
+        "-Wno-unused-private-field", "-isystem", cpp, "-I", here / "platform",
+        "-I", here / "platform/media/openmax", "-I", install / "include", here / "frameport_hevc.cpp",
        "-L", install / "lib", "-lavcodec", "-lavutil", "-L", runtime / "vendor/lib64",
        "-L", runtime / "system/lib64", "-lstagefright_softomx", "-lstagefright_foundation", "-lutils",
-        "-llog", "-lnativewindow", "-lyuv", "-l:libc++.so", "-lm", "-ldl", "-Wl,--no-undefined",
+        "-llog", "-lnativewindow", "-lyuv", "-lvulkan", "-l:libc++.so", "-lm", "-ldl", "-Wl,--no-undefined",
        "-Wl,-z,max-page-size=16384",
-        "-Wl,-soname,libstagefrighthw.so", "-o", ARTIFACTS / "libstagefrighthw.so",
+        "-Wl,-soname,libstagefrighthw.so", "-o", artifacts / "libstagefrighthw.so",
    ], env=env)
    for name in ("podman.py", "media_codecs_frameport.xml"):
-        shutil.copyfile(HERE / name, ARTIFACTS / (name + ".txt" if name == "podman.py" else name))
-    shutil.copyfile(source / "COPYING.LGPLv2.1", ARTIFACTS / "COPYING.FFmpeg")
+        shutil.copyfile(here / name, artifacts / (name + ".txt" if name == "podman.py" else name))
+    shutil.copyfile(source / "COPYING.LGPLv2.1", artifacts / "COPYING.FFmpeg")
    files = {}
    for name in ("libstagefrighthw.so", "podman.py", "media_codecs_frameport.xml", "COPYING.FFmpeg"):
-        path = ARTIFACTS / (name + ".txt" if name == "podman.py" else name)
+        path = artifacts / (name + ".txt" if name == "podman.py" else name)
        files[name] = hashlib.sha256(path.read_bytes()).hexdigest()
-    manifest = {"runtime_sha256": RUNTIME_SHA, "files": files,
+    # bump the revision with every change: a Frame keeps an installed codec of the same or a newer revision
+    manifest = {"revision": 8, "runtime_sha256": RUNTIME_SHA, "files": files,
+                "codecs": ["video/hevc", "video/avc", "video/x-vnd.on2.vp9"],
                "build": {"ndk_revision": NDK_REVISION, "ffmpeg_source_sha256": FFMPEG_SHA}}
-    (ARTIFACTS / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n")
+    (artifacts / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n")


 if __name__ == "__main__":
@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Compare the actual platform NEON row functions with the full-range BT.709
+// equations, including shadows/highlights and RGBA channel order in both paths.
+#include "yuv_color.h"
+#include <cassert>
+#include <cstdio>
+#include <cmath>
+#include <cstring>
+#include <initializer_list>
+extern "C" {
+void NV21ToARGBRow_Any_NEON(const uint8_t*,const uint8_t*,uint8_t*,const YuvConstants*,int);
+void I422ToARGBRow_Any_NEON(const uint8_t*,const uint8_t*,const uint8_t*,uint8_t*,const YuvConstants*,int);
+}
+static int clipped(double v) {int n=(int)std::lround(v);return n<0?0:n>255?255:n;}
+int main() {
+    unsigned checked=0;
+    for(unsigned width : {2u,8u,18u})
+    for(int y : {0,8,16,64,128,235,247,255})
+    for(int u : {16,64,128,192,240})
+    for(int v : {16,64,128,192,240}) {
+        uint8_t yy[32],uu[16],vv[16],uv[32],nv[128],planar[128];
+        memset(yy,y,sizeof yy);memset(uu,u,sizeof uu);memset(vv,v,sizeof vv);
+        for(unsigned i=0;i<width/2;i++){uv[2*i]=u;uv[2*i+1]=v;}
+        NV21ToARGBRow_Any_NEON(yy,uv,nv,&frameport_full709_rgba,width);
+        I422ToARGBRow_Any_NEON(yy,vv,uu,planar,&frameport_full709_rgba,width);
+        int expected[]={clipped(y+1.5748*(v-128)),clipped(y-0.187324*(u-128)-0.468124*(v-128)),
+                        clipped(y+1.8556*(u-128)),255};
+        for(unsigned x=0;x<width;x++)for(unsigned c=0;c<4;c++) {
+            assert(nv[4*x+c]==planar[4*x+c]);
+            assert(std::abs((int)nv[4*x+c]-expected[c])<=2);
+            if(u==128 && v==128 && c<3)assert(nv[4*x+c]==y);
+        }
+        checked++;
+    }
+    printf("PASS: %u full-range BT.709 colour/width combinations, planar and NV12 RGBA\n",checked);
+}
@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Import linear decoder/Android DMA buffers. Ownership returns to the foreign
+// producer/consumer before the completed fence permits either buffer to move.
+#pragma once
+#include <vulkan/vulkan.h>
+#include <unistd.h>
+#include <sys/stat.h>
+#include <cstdio>
+#include <cstring>
+#include <vector>
+class FramePortDmaCopy {
+    VkInstance instance=VK_NULL_HANDLE;
+    VkPhysicalDevice physical=VK_NULL_HANDLE;
+    VkDevice device=VK_NULL_HANDLE;
+    VkQueue queue=VK_NULL_HANDLE;
+    VkCommandPool pool=VK_NULL_HANDLE;
+    VkCommandBuffer command=VK_NULL_HANDLE;
+    VkFence completed=VK_NULL_HANDLE;
+    uint32_t family=0;
+    PFN_vkGetMemoryFdPropertiesKHR properties=nullptr;
+    struct Buffer {VkBuffer buffer=VK_NULL_HANDLE;VkDeviceMemory memory=VK_NULL_HANDLE;};
+    struct Entry {dev_t device;ino_t inode;VkBufferUsageFlags usage;Buffer imported;};
+    std::vector<Entry> cache;
+    bool attempted=false,ready=false,unsafe=false;
+    template<class T>static T info(VkStructureType type){T value={};value.sType=type;return value;}
+    bool check(VkResult r,const char *where){if(r!=VK_SUCCESS)ALOGW("GPU video %s: %d",where,r);return r==VK_SUCCESS;}
+    bool import(int fd,VkBufferUsageFlags usage,Buffer &out) {
+        struct stat st={};if(fstat(fd,&st)||st.st_size<=0)return false;
+        auto query=info<VkPhysicalDeviceExternalBufferInfo>(VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_BUFFER_INFO);
+        query.usage=usage;query.handleType=VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT;
+        auto caps=info<VkExternalBufferProperties>(VK_STRUCTURE_TYPE_EXTERNAL_BUFFER_PROPERTIES);
+        vkGetPhysicalDeviceExternalBufferProperties(physical,&query,&caps);
+        if(!(caps.externalMemoryProperties.externalMemoryFeatures&VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT))return false;
+        auto external=info<VkExternalMemoryBufferCreateInfo>(VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO);
+        external.handleTypes=query.handleType;
+        auto create=info<VkBufferCreateInfo>(VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO);create.pNext=&external;
+        create.size=st.st_size;create.usage=usage;create.sharingMode=VK_SHARING_MODE_EXCLUSIVE;
+        if(!check(vkCreateBuffer(device,&create,nullptr,&out.buffer),"create buffer"))return false;
+        VkMemoryRequirements needs;vkGetBufferMemoryRequirements(device,out.buffer,&needs);
+        auto fdprops=info<VkMemoryFdPropertiesKHR>(VK_STRUCTURE_TYPE_MEMORY_FD_PROPERTIES_KHR);
+        if(!check(properties(device,query.handleType,fd,&fdprops),"fd properties"))return false;
+        uint32_t bits=needs.memoryTypeBits&fdprops.memoryTypeBits;
+        if(!bits || needs.size>(VkDeviceSize)st.st_size){ALOGW("GPU import layout mismatch: size %llu/%lld bits %#x",
+            (unsigned long long)needs.size,(long long)st.st_size,bits);return false;}
+        auto imported=info<VkImportMemoryFdInfoKHR>(VK_STRUCTURE_TYPE_IMPORT_MEMORY_FD_INFO_KHR);
+        imported.handleType=query.handleType;imported.fd=dup(fd);if(imported.fd<0)return false;
+        auto dedicated=info<VkMemoryDedicatedAllocateInfo>(VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO);
+        dedicated.buffer=out.buffer;
+        if(caps.externalMemoryProperties.externalMemoryFeatures&VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT)imported.pNext=&dedicated;
+        auto allocate=info<VkMemoryAllocateInfo>(VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO);allocate.pNext=&imported;
+        allocate.allocationSize=st.st_size;allocate.memoryTypeIndex=__builtin_ctz(bits);
+        if(!check(vkAllocateMemory(device,&allocate,nullptr,&out.memory),"import memory")){close(imported.fd);return false;}
+        return check(vkBindBufferMemory(device,out.buffer,out.memory,0),"bind buffer");
+    }
+    void release(Buffer &b){if(b.buffer)vkDestroyBuffer(device,b.buffer,nullptr);if(b.memory)vkFreeMemory(device,b.memory,nullptr);b={};}
+    bool cached(int fd,VkBufferUsageFlags usage,Buffer &out){
+        struct stat st={};if(fstat(fd,&st))return false;
+        for(auto &e:cache)if(e.device==st.st_dev&&e.inode==st.st_ino&&e.usage==usage){out=e.imported;return true;}
+        Buffer b;bool ok=import(fd,usage,b);if(!ok){release(b);return false;}
+        cache.push_back({st.st_dev,st.st_ino,usage,b});out=b;return true;
+    }
+public:
+    void clearBuffers(){if(device){vkDeviceWaitIdle(device);for(auto &e:cache)release(e.imported);cache.clear();}}
+    bool available(){if(!attempted){attempted=true;ready=init();}return ready;}
+    bool failedAfterSubmit()const{return unsafe;}
+    bool init(){
+        auto app=info<VkApplicationInfo>(VK_STRUCTURE_TYPE_APPLICATION_INFO);app.apiVersion=VK_API_VERSION_1_1;
+        auto create=info<VkInstanceCreateInfo>(VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO);create.pApplicationInfo=&app;
+        if(!check(vkCreateInstance(&create,nullptr,&instance),"create instance"))return false;
+        uint32_t n=0;vkEnumeratePhysicalDevices(instance,&n,nullptr);if(!n)return false;
+        std::vector<VkPhysicalDevice> devices(n);vkEnumeratePhysicalDevices(instance,&n,devices.data());physical=devices[0];
+        VkPhysicalDeviceProperties p;vkGetPhysicalDeviceProperties(physical,&p);
+        if(p.apiVersion<VK_API_VERSION_1_1)return false;
+        vkEnumerateDeviceExtensionProperties(physical,nullptr,&n,nullptr);std::vector<VkExtensionProperties> extensions(n);
+        vkEnumerateDeviceExtensionProperties(physical,nullptr,&n,extensions.data());
+        const char *required[]={VK_KHR_EXTERNAL_MEMORY_FD_EXTENSION_NAME,VK_EXT_EXTERNAL_MEMORY_DMA_BUF_EXTENSION_NAME,VK_EXT_QUEUE_FAMILY_FOREIGN_EXTENSION_NAME};
+        for(auto wanted:required){bool found=false;for(auto &e:extensions)if(!strcmp(e.extensionName,wanted))found=true;
+            if(!found)return false;}
+        vkGetPhysicalDeviceQueueFamilyProperties(physical,&n,nullptr);std::vector<VkQueueFamilyProperties> families(n);
+        vkGetPhysicalDeviceQueueFamilyProperties(physical,&n,families.data());
+        family=n;for(uint32_t i=0;i<n;i++)if(families[i].queueFlags&VK_QUEUE_TRANSFER_BIT){family=i;break;}
+        if(family==n)return false;
+        float priority=1;auto q=info<VkDeviceQueueCreateInfo>(VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO);
+        q.queueFamilyIndex=family;q.queueCount=1;q.pQueuePriorities=&priority;
+        auto d=info<VkDeviceCreateInfo>(VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO);d.queueCreateInfoCount=1;d.pQueueCreateInfos=&q;
+        d.enabledExtensionCount=3;d.ppEnabledExtensionNames=required;
+        if(!check(vkCreateDevice(physical,&d,nullptr,&device),"create device"))return false;
+        vkGetDeviceQueue(device,family,0,&queue);
+        properties=(PFN_vkGetMemoryFdPropertiesKHR)vkGetDeviceProcAddr(device,"vkGetMemoryFdPropertiesKHR");if(!properties)return false;
+        auto cp=info<VkCommandPoolCreateInfo>(VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO);cp.queueFamilyIndex=family;
+        cp.flags=VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT;
+        if(!check(vkCreateCommandPool(device,&cp,nullptr,&pool),"create pool"))return false;
+        auto a=info<VkCommandBufferAllocateInfo>(VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO);
+        a.commandPool=pool;a.level=VK_COMMAND_BUFFER_LEVEL_PRIMARY;a.commandBufferCount=1;
+        auto f=info<VkFenceCreateInfo>(VK_STRUCTURE_TYPE_FENCE_CREATE_INFO);
+        return check(vkAllocateCommandBuffers(device,&a,&command),"allocate command buffer")&&
+            check(vkCreateFence(device,&f,nullptr,&completed),"create fence");
+    }
+    bool copy(int source,int dest,const VkBufferCopy *regions,unsigned count){
+        unsafe=false;
+        struct stat s={},d={};
+        if(!count||fstat(source,&s)||fstat(dest,&d))return false;
+        for(unsigned i=0;i<count;i++)if(!regions[i].size||(regions[i].size&3)||
+            (regions[i].srcOffset&3)||(regions[i].dstOffset&3)||regions[i].srcOffset>(VkDeviceSize)s.st_size||
+            regions[i].dstOffset>(VkDeviceSize)d.st_size||regions[i].size>(VkDeviceSize)s.st_size-regions[i].srcOffset||
+            regions[i].size>(VkDeviceSize)d.st_size-regions[i].dstOffset)return false;
+        // Make room for the pair before resolving either handle. Evicting
+        // while importing the destination could destroy the source handle.
+        if(cache.size()>30)clearBuffers();
+        Buffer buffers[2];bool ok=cached(source,VK_BUFFER_USAGE_TRANSFER_SRC_BIT,buffers[0])&&
+            cached(dest,VK_BUFFER_USAGE_TRANSFER_DST_BIT,buffers[1]);
+        VkCommandBuffer cmd=command;VkFence fence=completed;
+        if(ok)ok=check(vkResetCommandBuffer(cmd,0),"reset command buffer")&&check(vkResetFences(device,1,&fence),"reset fence");
+        if(ok){
+            auto b=info<VkCommandBufferBeginInfo>(VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO);b.flags=VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT;
+            ok=check(vkBeginCommandBuffer(cmd,&b),"begin command buffer");
+            VkBufferMemoryBarrier barriers[2]={};
+            for(unsigned i=0;i<2;i++){
+                barriers[i].sType=VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER;barriers[i].dstAccessMask=i?VK_ACCESS_TRANSFER_WRITE_BIT:VK_ACCESS_TRANSFER_READ_BIT;
+                barriers[i].srcQueueFamilyIndex=VK_QUEUE_FAMILY_FOREIGN_EXT;barriers[i].dstQueueFamilyIndex=family;
+                barriers[i].buffer=buffers[i].buffer;barriers[i].size=VK_WHOLE_SIZE;
+            }
+            vkCmdPipelineBarrier(cmd,VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT,VK_PIPELINE_STAGE_TRANSFER_BIT,0,0,nullptr,2,barriers,0,nullptr);
+            vkCmdCopyBuffer(cmd,buffers[0].buffer,buffers[1].buffer,count,regions);
+            for(auto &barrier:barriers){barrier.srcAccessMask=barrier.dstAccessMask;barrier.dstAccessMask=0;
+                barrier.srcQueueFamilyIndex=family;barrier.dstQueueFamilyIndex=VK_QUEUE_FAMILY_FOREIGN_EXT;}
+            vkCmdPipelineBarrier(cmd,VK_PIPELINE_STAGE_TRANSFER_BIT,VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,0,0,nullptr,2,barriers,0,nullptr);
+            ok=ok&&check(vkEndCommandBuffer(cmd),"end command buffer");
+        }
+        if(ok){auto s=info<VkSubmitInfo>(VK_STRUCTURE_TYPE_SUBMIT_INFO);s.commandBufferCount=1;s.pCommandBuffers=&cmd;
+            ok=check(vkQueueSubmit(queue,1,&s,fence),"submit");
+            if(ok){ok=check(vkWaitForFences(device,1,&fence,VK_TRUE,10000000000ull),"wait fence");unsafe=!ok;}}
+        if(!ok&&device)vkDeviceWaitIdle(device);
+        return ok;
+    }
+    ~FramePortDmaCopy(){if(device){vkDeviceWaitIdle(device);for(auto &e:cache)release(e.imported);
+        if(completed)vkDestroyFence(device,completed,nullptr);if(pool)vkDestroyCommandPool(device,pool,nullptr);
+        vkDestroyDevice(device,nullptr);}if(instance)vkDestroyInstance(instance,nullptr);}
+};
@@ -1,11 +1,12 @@
 // SPDX-License-Identifier: GPL-3.0-only
-// Android OMX integration for the Iris stateful V4L2 HEVC decoder. FFmpeg is
-// built with only its hardware wrapper; this component never transcodes video.
-#define LOG_TAG "FramePortHEVC"
+// Android OMX integration for Iris stateful V4L2 video decoding. No OpenXR
+// layer/pose manipulation, asset rewriting or package-specific behaviour.
+#define LOG_TAG "FramePortVideo"
 #include <media/stagefright/omx/SoftVideoDecoderOMXComponent.h>
 #include <media/hardware/OMXPluginBase.h>
 #include <media/openmax/OMX_IndexExt.h>
 #include <media/hardware/HardwareAPI.h>
+#include <media/stagefright/foundation/ColorUtils.h>
 #include <android/hardware_buffer.h>
 #include <unistd.h>
 #include <fcntl.h>
@@ -17,20 +18,55 @@
 #include <cerrno>
 #include <pthread.h>
 #include <time.h>
+#include <poll.h>
 #include "yuv_copy.h"
+#include "yuv_color.h"
 extern "C" {
 #include <libavcodec/avcodec.h>
 #include <libavutil/opt.h>
-struct YuvConstants;
 extern const YuvConstants kYvuH709Constants, kYvuI601Constants;
+extern const YuvConstants kYvuJPEGConstants;
 void NV21ToARGBRow_Any_NEON(const uint8_t*,const uint8_t*,uint8_t*,const YuvConstants*,int);
+void I422ToARGBRow_Any_NEON(const uint8_t*,const uint8_t*,const uint8_t*,uint8_t*,const YuvConstants*,int);
 AHardwareBuffer *ANativeWindowBuffer_getHardwareBuffer(ANativeWindowBuffer*);
+const native_handle_t *AHardwareBuffer_getNativeHandle(const AHardwareBuffer*);
+int frameport_v4l2_export_frame(const AVFrame*);
 }
+#include "dma_copy.h"

 namespace android {
-static const CodecProfileLevel profiles[]={{OMX_VIDEO_HEVCProfileMain,OMX_VIDEO_HEVCMainTierLevel62}};
+static const CodecProfileLevel hevc_profiles[]={{OMX_VIDEO_HEVCProfileMain,OMX_VIDEO_HEVCMainTierLevel62}};
+// Android reports constrained AVC streams under their own profile values;
+// stock decoders list them so format-aware clients can match them.
+static const CodecProfileLevel avc_profiles[]={
+    {(OMX_U32)OMX_VIDEO_AVCProfileConstrainedBaseline,OMX_VIDEO_AVCLevel62},
+    {OMX_VIDEO_AVCProfileBaseline,OMX_VIDEO_AVCLevel62},
+    {(OMX_U32)OMX_VIDEO_AVCProfileConstrainedHigh,OMX_VIDEO_AVCLevel62},
+    {OMX_VIDEO_AVCProfileMain,OMX_VIDEO_AVCLevel62},
+    {OMX_VIDEO_AVCProfileHigh,OMX_VIDEO_AVCLevel62}};
+static const CodecProfileLevel vp9_profiles[]={{OMX_VIDEO_VP9Profile0,OMX_VIDEO_VP9Level62}};
+struct DecoderKind {
+    const char *name,*role,*mime,*hardware,*software;
+    OMX_VIDEO_CODINGTYPE coding;
+    uint32_t fourcc;
+    const CodecProfileLevel *profiles;
+    unsigned profile_count;
+    // What Iris returns pictures for on the Frame: VP9 at 7680x3840 opened but
+    // never returned one (2026-10-09), so larger VP9 decodes in software.
+    unsigned max_width,max_height;
+};
+static const DecoderKind kinds[]={
+    {"OMX.frameport.hevc.decoder","video_decoder.hevc","video/hevc","hevc_v4l2m2m","hevc",
+        OMX_VIDEO_CodingHEVC,V4L2_PIX_FMT_HEVC,hevc_profiles,1,8192,8192},
+    {"OMX.frameport.avc.decoder","video_decoder.avc","video/avc","h264_v4l2m2m","h264",
+        OMX_VIDEO_CodingAVC,V4L2_PIX_FMT_H264,avc_profiles,5,8192,8192},
+    {"OMX.frameport.vp9.decoder","video_decoder.vp9","video/x-vnd.on2.vp9","vp9_v4l2m2m","vp9",
+        OMX_VIDEO_CodingVP9,V4L2_PIX_FMT_VP9,vp9_profiles,1,4096,2304}};
+static constexpr unsigned kind_count=sizeof(kinds)/sizeof(kinds[0]);
+// When the media service loaded the plugin (= the container's start).
+static int64_t plugin_loaded_ns=0;
 class ColorWorkers {
-    struct Worker {ColorWorkers *owner;unsigned band;pthread_t thread;};
+    struct Worker {ColorWorkers *owner;unsigned band,seen;pthread_t thread;};
    Worker workers[3];unsigned count=0,generation=0,complete=0;
    bool started=false,stopping=false;
    pthread_mutex_t mutex=PTHREAD_MUTEX_INITIALIZER;
@@ -40,6 +76,24 @@ class ColorWorkers {
    FramePortYuvPlane planes[3]={};bool native_yuv=false;
    void rows(unsigned band) {
        unsigned bands=count+1;
+        if(frame->format==AV_PIX_FMT_YUV420P || frame->format==AV_PIX_FMT_YUVJ420P){
+            unsigned begin=(frame->height/2)*band/bands,end=(frame->height/2)*(band+1)/bands;
+            if(native_yuv){
+                for(unsigned plane=0;plane<3;plane++){
+                    unsigned first=plane?begin:2*begin,last=plane?end:2*end,width=plane?frame->width/2:frame->width;
+                    for(unsigned row=first;row<last;row++){
+                        const uint8_t *src=frame->data[plane]+row*frame->linesize[plane];
+                        uint8_t *dst=planes[plane].data+row*planes[plane].row_stride;
+                        if(planes[plane].pixel_stride==1)memcpy(dst,src,width);
+                        else for(unsigned x=0;x<width;x++)dst[x*planes[plane].pixel_stride]=src[x];
+                    }
+                }
+            }else for(unsigned row=2*begin;row<2*end;row++)
+                I422ToARGBRow_Any_NEON(frame->data[0]+row*frame->linesize[0],
+                    frame->data[2]+(row/2)*frame->linesize[2],frame->data[1]+(row/2)*frame->linesize[1],
+                    output+row*stride*4,matrix,frame->width);
+            return;
+        }
        if(native_yuv){
            frameport_yuv_copy_band(frame->data[0],frame->data[1],frame->width,frame->height,
                frame->linesize[0],frame->linesize[1],planes,band,bands);return;
@@ -50,7 +104,7 @@ class ColorWorkers {
                frame->data[1]+(row/2)*frame->linesize[1],output+row*stride*4,matrix,frame->width);
    }
    static void *thread(void *arg) {
-        auto &worker=*static_cast<Worker*>(arg);auto &pool=*worker.owner;unsigned seen=0;
+        auto &worker=*static_cast<Worker*>(arg);auto &pool=*worker.owner;unsigned seen=worker.seen;
        pthread_mutex_lock(&pool.mutex);
        for(;;) {
            while(!pool.stopping && seen==pool.generation)pthread_cond_wait(&pool.work,&pool.mutex);
@@ -65,14 +119,17 @@ class ColorWorkers {
 public:
    void convert(AVFrame *source,uint8_t *destination,size_t pitch,const YuvConstants *constants,
        const AHardwareBuffer_Planes *native=nullptr) {
-        if(!started) {
+        // Start helpers when a large picture first appears, including after
+        // an adaptive stream begins at a lower resolution.
+        if(!started && source->width*source->height>=4096*2048) {
            started=true;
-            if(source->width*source->height>=4096*2048)
-                for(unsigned i=0;i<3;i++) {
-                    workers[i]={this,i+1,{}};
-                    if(pthread_create(&workers[i].thread,nullptr,thread,&workers[i]))break;
-                    count++;
-                }
+            for(unsigned i=0;i<3;i++) {
+                // Only this thread advances the generation, so a helper
+                // created now waits for the next picture, never a stale one.
+                workers[i]={this,i+1,generation,{}};
+                if(pthread_create(&workers[i].thread,nullptr,thread,&workers[i]))break;
+                count++;
+            }
        }
        pthread_mutex_lock(&mutex);
        frame=source;output=destination;stride=pitch;matrix=constants;complete=0;generation++;
@@ -91,32 +148,110 @@ public:
        pthread_cond_destroy(&work);pthread_cond_destroy(&done);pthread_mutex_destroy(&mutex);
    }
 };
-class FramePortHEVC final : public SoftVideoDecoderOMXComponent {
+class FramePortVideo final : public SoftVideoDecoderOMXComponent {
+    const DecoderKind &kind;
    ColorWorkers color;
+    FramePortDmaCopy gpu;
+    bool gpu_allowed=true;
    AVCodecContext *codec=nullptr;
+    AVCodecParserContext *parser=nullptr;
    AVFrame *frame=av_frame_alloc();
    uint8_t *config=nullptr;
    size_t config_size=0;
    bool failed=false,held=false,drained=false,replace_config=false,surface=false;
    bool native_enabled=false,metadata=false;
+    bool hardware_active=false,prefer_software=false,eos_submitted=false,replay_eos=false;
+    bool prepend_config=false;
+    Vector<AVPacket*> history;
+    size_t history_bytes=0;
+    ssize_t replay_next=-1;
+    int64_t last_output_pts=AV_NOPTS_VALUE,discard_until=AV_NOPTS_VALUE;
    static constexpr OMX_INDEXTYPE native_index=(OMX_INDEXTYPE)0x7f010001;
    static constexpr OMX_INDEXTYPE metadata_index=(OMX_INDEXTYPE)0x7f010002;
    static constexpr OMX_INDEXTYPE usage_index=(OMX_INDEXTYPE)0x7f010003;
    int64_t eos_pts=0;
    static int64_t clockNs() {timespec ts;clock_gettime(CLOCK_MONOTONIC,&ts);return ts.tv_sec*1000000000ll+ts.tv_nsec;}
    int64_t stats_start=0, stats_lock=0, stats_convert=0, stats_unlock=0;
-    unsigned stats_frames=0;
+    unsigned stats_frames=0,stats_gpu=0;
+    bool gpuCopy(AHardwareBuffer *hardware,const AHardwareBuffer_Planes &planes) {
+        if(planes.planes[1].pixelStride!=2 || planes.planes[2].pixelStride!=2 ||
+            planes.planes[1].rowStride!=planes.planes[2].rowStride ||
+            (uintptr_t)planes.planes[2].data!=(uintptr_t)planes.planes[1].data+1 ||
+            (uintptr_t)planes.planes[1].data<(uintptr_t)planes.planes[0].data)return false;
+        const auto *handle=AHardwareBuffer_getNativeHandle(hardware);
+        // CrOS gralloc includes duplicate plane fds and a metadata fd. The
+        // first fd holds the linear pixels; copy() bounds-checks both planes.
+        if(!handle || handle->numFds<1)return false;
+        int source=frameport_v4l2_export_frame(frame);if(source<0)return false;
+        uint64_t src_uv=(uintptr_t)frame->data[1]-(uintptr_t)frame->data[0];
+        uint64_t dst_uv=(uintptr_t)planes.planes[1].data-(uintptr_t)planes.planes[0].data;
+        std::vector<VkBufferCopy> regions;
+        auto append=[&](VkDeviceSize src,VkDeviceSize dst,VkDeviceSize bytes){
+            if(!regions.empty() && regions.back().srcOffset+regions.back().size==src &&
+                regions.back().dstOffset+regions.back().size==dst)regions.back().size+=bytes;
+            else regions.push_back({src,dst,bytes});
+        };
+        for(int row=0;row<frame->height;row++)
+            append((uint64_t)row*frame->linesize[0],(uint64_t)row*planes.planes[0].rowStride,frame->width);
+        for(int row=0;row<frame->height/2;row++)
+            append(src_uv+(uint64_t)row*frame->linesize[1],dst_uv+(uint64_t)row*planes.planes[1].rowStride,frame->width);
+        bool result=gpu.copy(source,handle->data[0],regions.data(),regions.size());close(source);return result;
+    }
+    void clearHistory() {
+        for(size_t i=0;i<history.size();i++){AVPacket *packet=history[i];av_packet_free(&packet);}
+        history.clear();history_bytes=0;replay_next=-1;
+    }
+    void rememberInput(const AVPacket *packet) {
+        if(!hardware_active)return;
+        if(packet->flags&AV_PKT_FLAG_KEY){
+            // Keep the preceding GOP too: the new keyframe can be submitted
+            // before older reordered pictures have finished coming out.
+            ssize_t previous=-1;
+            for(size_t i=0;i<history.size();i++)if(history[i]->flags&AV_PKT_FLAG_KEY)previous=i;
+            if(previous>0){
+                for(ssize_t i=0;i<previous;i++){
+                    AVPacket *old=history[i];history_bytes-=old->size;av_packet_free(&old);
+                }
+                history.removeItemsAt(0,previous);
+            }
+        }
+        // References to compressed input, not copies of decoded panoramas.
+        // Bound memory for unusually long GOPs or malformed streams.
+        if(history_bytes+(size_t)packet->size>64*1024*1024 || history.size()>=512)clearHistory();
+        if(history.empty() && !(packet->flags&AV_PKT_FLAG_KEY))return;
+        AVPacket *copy=av_packet_clone(packet);
+        if(!copy)return;
+        if(history.add(copy)<0){av_packet_free(&copy);return;}
+        history_bytes+=copy->size;
+    }
+    bool annexB() const {
+        // H.264/HEVC parameter sets with start codes can go in-band. VP9's
+        // configuration is container metadata, never bitstream data.
+        return kind.coding!=OMX_VIDEO_CodingVP9 && config_size>=4 && !config[0] && !config[1] &&
+            (config[2]==1 || (!config[2] && config[3]==1));
+    }
    void fail(int result,const char *operation) {
        char message[128];av_strerror(result,message,sizeof(message));
        ALOGE("%s failed: %s",operation,message);
        failed=true;notify(OMX_EventError,OMX_ErrorHardware,0,nullptr);
    }
-    bool openDecoder() {
-        if(codec)return true;
-        const AVCodec *hardware=avcodec_find_decoder_by_name("hevc_v4l2m2m");
-        if(!hardware || !frame){fail(AVERROR(ENOMEM),"decoder allocation");return false;}
-        codec=avcodec_alloc_context3(hardware);
-        if(!codec){fail(AVERROR(ENOMEM),"codec context");return false;}
+    static unsigned captureBuffers(const DecoderKind &kind,uint64_t pixels) {
+        // FFmpeg's general-purpose capture budget (20) suits ordinary sizes.
+        // Reference pictures shrink as pictures grow (HEVC level 6.x DPB
+        // limits; H.264 level 6.2 allows fewer), so 20 panorama-sized buffers
+        // would hold about 1 GB at 8K. VP9 can keep 8 references at any size.
+        // Unknown sizes keep the full budget.
+        const uint64_t max_luma=35651584;
+        unsigned references=pixels<=max_luma/4?16:pixels<=max_luma/2?12:pixels<=max_luma*3/4?8:6;
+        if(kind.coding==OMX_VIDEO_CodingVP9 && references<9)references=9;
+        // Room for the picture being decoded, one held for output and queueing.
+        return references+4<20?references+4:20;
+    }
+    int openCodec(const char *name,bool hardware) {
+        const AVCodec *implementation=avcodec_find_decoder_by_name(name);
+        if(!implementation || !frame)return AVERROR(ENOMEM);
+        codec=avcodec_alloc_context3(implementation);
+        if(!codec)return AVERROR(ENOMEM);
        const auto &input=editPortInfo(kInputPortIndex)->mDef.format.video;
        codec->width=codec->coded_width=input.nFrameWidth;
        codec->height=codec->coded_height=input.nFrameHeight;
@@ -124,15 +259,67 @@ class FramePortHEVC final : public SoftVideoDecoderOMXComponent {
        codec->pix_fmt=AV_PIX_FMT_NV12;
        if(config_size) {
            codec->extradata=(uint8_t*)av_mallocz(config_size+AV_INPUT_BUFFER_PADDING_SIZE);
-            if(!codec->extradata){fail(AVERROR(ENOMEM),"codec configuration");return false;}
+            if(!codec->extradata)return AVERROR(ENOMEM);
            memcpy(codec->extradata,config,config_size);codec->extradata_size=(int)config_size;
        }
        AVDictionary *options=nullptr;
-        av_dict_set(&options,"num_output_buffers","2",0);
-        av_dict_set(&options,"num_capture_buffers","4",0);
-        int result=avcodec_open2(codec,hardware,&options);av_dict_free(&options);
-        if(result<0){fail(result,"Iris hardware initialization");return false;}
-        ALOGI("Iris hardware HEVC decoder active: %dx%d",codec->coded_width,codec->coded_height);
+        if(hardware){
+            av_dict_set(&options,"num_output_buffers","2",0);
+            // Leave room for reference/reordered pictures: a four-buffer
+            // budget stalled a valid H.264 stream on Iris.
+            av_dict_set_int(&options,"num_capture_buffers",
+                captureBuffers(kind,(uint64_t)input.nFrameWidth*input.nFrameHeight),0);
+        }else{codec->thread_count=4;codec->thread_type=FF_THREAD_FRAME|FF_THREAD_SLICE;}
+        int result=avcodec_open2(codec,implementation,&options);av_dict_free(&options);
+        return result;
+    }
+    bool openDecoder() {
+        if(codec)return true;
+        const auto &size=editPortInfo(kInputPortIndex)->mDef.format.video;
+        int result=AVERROR(ENODEV);
+        if(size.nFrameWidth>kind.max_width || size.nFrameHeight>kind.max_height)
+            ALOGW("%s %ux%u is above what Iris decodes (%ux%u); using software decoding",kind.mime,
+                (unsigned)size.nFrameWidth,(unsigned)size.nFrameHeight,kind.max_width,kind.max_height);
+        else if(!prefer_software)for(int64_t start=clockNs(),attempt=0;;attempt++) {
+            result=openCodec(kind.hardware,true);
+            if(result>=0 || (result!=AVERROR(ENOMEM) && result!=AVERROR(EBUSY)))break;
+            // The driver refuses a session that doesn't fit next to the open
+            // ones (8K while any other is open). SteamVR's link holds one for
+            // about 12 s around every game start, when the plugin loads too:
+            // wait for it then (an 8K panorama in software is a slideshow),
+            // otherwise 2 s, before continuing in software.
+            int64_t now=clockNs();
+            if(now-start>=2000000000ll && now-plugin_loaded_ns>=20000000000ll)break;
+            if(!attempt)ALOGW("Iris %s busy (%ux%u); waiting for capacity",kind.mime,(unsigned)size.nFrameWidth,
+                    (unsigned)size.nFrameHeight);
+            gpu.clearBuffers();avcodec_free_context(&codec);usleep(250000);
+        }
+        hardware_active=result>=0;
+        if(result<0){
+            // Availability can change after enumeration (another app/Steam
+            // opens Iris). Native MediaCodec clients do not all retry a stock
+            // component, so retain playback within this selected component.
+            if(prefer_software)ALOGI("%s: continuing in software for this session",kind.mime);
+            else ALOGW("Iris %s initialization failed (%d); using software decoding",kind.mime,result);
+            gpu.clearBuffers();avcodec_free_context(&codec);
+            result=openCodec(kind.software,false);
+            if(result<0){gpu.clearBuffers();avcodec_free_context(&codec);fail(result,"software fallback initialization");return false;}
+        }else ALOGI("Iris hardware %s decoder active: %dx%d",kind.mime,codec->coded_width,codec->coded_height);
+        prepend_config=hardware_active && annexB();
+        parser=av_parser_init(codec->codec_id);
+        if(parser)parser->flags|=PARSER_FLAG_COMPLETE_FRAMES;
+        return true;
+    }
+    bool recoverHardware(const char *operation) {
+        if(!hardware_active || history.empty() || !(history[0]->flags&AV_PKT_FLAG_KEY)){
+            fail(AVERROR_INVALIDDATA,operation);return false;
+        }
+        ALOGW("Iris %s failed during %s; replaying %zu compressed packets in software, last pts=%lld",kind.mime,operation,history.size(),(long long)last_output_pts);
+        av_frame_unref(frame);held=false;av_parser_close(parser);parser=nullptr;gpu.clearBuffers();avcodec_free_context(&codec);
+        hardware_active=false;prefer_software=true;
+        int result=openCodec(kind.software,false);
+        if(result<0){fail(result,"software recovery initialization");return false;}
+        replay_next=0;replay_eos=eos_submitted;eos_submitted=false;discard_until=last_output_pts;
        return true;
    }
    void consumeInput(BufferInfo *info) {
@@ -141,7 +328,36 @@ class FramePortHEVC final : public SoftVideoDecoderOMXComponent {
        header->nOffset=0;header->nFilledLen=0;info->mOwnedByUs=false;
        notifyEmptyBufferDone(header);
    }
+    void reportBitstreamColor() {
+        // Like Android's stock decoders, pass signalled colour information
+        // to ACodec, which uses it for the surface dataspace. Container
+        // values still take precedence (getColorAspectPreference).
+        if(frame->color_primaries==AVCOL_PRI_UNSPECIFIED && frame->color_trc==AVCOL_TRC_UNSPECIFIED &&
+            frame->colorspace==AVCOL_SPC_UNSPECIFIED && frame->color_range==AVCOL_RANGE_UNSPECIFIED)return;
+        // FFmpeg's colour enums use the ISO/IEC 23091-2 code points.
+        ColorAspects aspects;
+        ColorUtils::convertIsoColorAspectsToCodecAspects(frame->color_primaries,frame->color_trc,
+            frame->colorspace,frame->color_range==AVCOL_RANGE_JPEG,aspects);
+        if(colorAspectsDiffer(aspects,mBitstreamColorAspects)){
+            ALOGI("%s bitstream colour: primaries %d, transfer %d, matrix %d, range %d",kind.mime,
+                frame->color_primaries,frame->color_trc,frame->colorspace,frame->color_range);
+            mBitstreamColorAspects=aspects;handleColorAspectsChange();
+        }
+    }
+    const YuvConstants *rgbaMatrix() {
+        ColorAspects aspects;
+        {Mutex::Autolock lock(mColorAspectsLock);aspects=mFinalColorAspects;}
+        // Unsignalled HD video is conventionally BT.709, as Android assumes.
+        bool bt709=aspects.mMatrixCoeffs==ColorAspects::MatrixBT709_5 ||
+            (aspects.mMatrixCoeffs==ColorAspects::MatrixUnspecified && (frame->width>=1280 || frame->height>=720));
+        if(aspects.mRange==ColorAspects::RangeFull)return bt709?&frameport_full709_rgba:&kYvuJPEGConstants;
+        return bt709?&kYvuH709Constants:&kYvuI601Constants;
+    }
    bool outputFrame() {
+        // Hardware errors are recovered in software. Software decoders
+        // conceal damage themselves; output their picture as stock decoders do.
+        if(frame->decode_error_flags && hardware_active)return recoverHardware("decoded picture");
+        reportBitstreamColor();
        bool reset=false;
        handlePortSettingsChange(&reset,frame->width,frame->height,
            native_enabled?(OMX_COLOR_FORMATTYPE)AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_420:
@@ -153,7 +369,8 @@ class FramePortHEVC final : public SoftVideoDecoderOMXComponent {
        BufferInfo *info=*queue.begin();OMX_BUFFERHEADERTYPE *header=info->mHeader;
        size_t stride=outputBufferWidth(),height=outputBufferHeight();
        size_t bytes=native_enabled?sizeof(VideoNativeMetadata):surface?stride*height*4:stride*height*3/2;
-        if(bytes>header->nAllocLen || frame->format!=AV_PIX_FMT_NV12 ||
+        bool planar=frame->format==AV_PIX_FMT_YUV420P || frame->format==AV_PIX_FMT_YUVJ420P;
+        if(bytes>header->nAllocLen || (frame->format!=AV_PIX_FMT_NV12 && !planar) ||
           frame->width<1 || frame->height<1 || (frame->width&1) || (frame->height&1) ||
           (size_t)frame->width>stride || (size_t)frame->height>height) {
            fail(AVERROR(EINVAL),"output buffer format");return false;
@@ -163,11 +380,11 @@ class FramePortHEVC final : public SoftVideoDecoderOMXComponent {
        // Lepton's slow scalar RGB565 renderer.
        if(surface || native_enabled) {
            int64_t before=clockNs(),locked=before,converted=before;
-            const YuvConstants *matrix=mDefaultColorAspects.mMatrixCoeffs==ColorAspects::MatrixBT709_5
-                ?&kYvuH709Constants:&kYvuI601Constants;
+            const YuvConstants *matrix=native_enabled?nullptr:rgbaMatrix();
            uint8_t *destination=header->pBuffer;
            AHardwareBuffer *hardware=nullptr;VideoNativeMetadata *native=nullptr;
            AHardwareBuffer_Planes planes={};
+            bool used_gpu=false;
            if(native_enabled) {
                native=reinterpret_cast<VideoNativeMetadata*>(header->pBuffer);
                if(!metadata || native->eType!=kMetadataBufferTypeANWBuffer || !native->pBuffer) {
@@ -194,40 +411,61 @@ class FramePortHEVC final : public SoftVideoDecoderOMXComponent {
                    AHardwareBuffer_unlock(hardware,&native->nFenceFd);
                    fail(AVERROR(EINVAL),"native YUV planes");return false;
                }
+                locked=clockNs();
+                if(gpu_allowed && hardware_active && !planar && !(frame->width&3) &&
+                    (uint64_t)frame->width*frame->height>=4096*2048 && gpu.available()) {
+                    if(AHardwareBuffer_unlock(hardware,&native->nFenceFd)){
+                        fail(AVERROR(EIO),"native layout unlock");return false;
+                    }
+                    if(native->nFenceFd>=0){
+                        pollfd fence={native->nFenceFd,POLLIN,0};int waited;
+                        do{waited=poll(&fence,1,10000);}while(waited<0 && errno==EINTR);
+                        close(native->nFenceFd);native->nFenceFd=-1;
+                        if(waited<=0 || !(fence.revents&POLLIN)){fail(AVERROR(EIO),"native layout fence");return false;}
+                    }
+                    used_gpu=gpuCopy(hardware,planes);
+                    if(!used_gpu){
+                        gpu_allowed=false;
+                        if(gpu.failedAfterSubmit()){fail(AVERROR(EIO),"GPU video transfer");return false;}
+                        if(AHardwareBuffer_lockPlanes(hardware,AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN,-1,nullptr,&planes)){
+                            fail(AVERROR(EIO),"native CPU fallback lock");return false;
+                        }
+                        ALOGW("GPU video buffer sharing unavailable; retaining CPU copy");
+                    }
+                }
            }
-            locked=clockNs();
-            if(native_enabled)color.convert(frame,nullptr,0,nullptr,&planes);
-            else color.convert(frame,destination,stride,matrix);
+            if(!native_enabled)locked=clockNs();
+            if(native_enabled && !used_gpu)color.convert(frame,nullptr,0,nullptr,&planes);
+            else if(!native_enabled)color.convert(frame,destination,stride,matrix);
            converted=clockNs();
-            if(hardware && AHardwareBuffer_unlock(hardware,&native->nFenceFd)) {
+            if(hardware && !used_gpu && AHardwareBuffer_unlock(hardware,&native->nFenceFd)) {
                fail(AVERROR(EIO),"native output unlock");return false;
            }
            int64_t after=clockNs();
            stats_lock+=locked-before;stats_convert+=converted-locked;stats_unlock+=after-converted;
            if(!stats_start)stats_start=before;
            stats_frames++;
+            if(used_gpu)stats_gpu++;
            if(after-stats_start>=5000000000ll) {
-                ALOGI("output %.1f fps, native=%d, lock %.2f ms, copy/convert %.2f ms, unlock %.2f ms, pts=%lld",
-                    stats_frames*1e9/(after-stats_start),native_enabled,
+                ALOGI("output %.1f fps, native=%d, gpu=%u/%u, lock %.2f ms, copy/convert %.2f ms, unlock %.2f ms, pts=%lld",
+                    stats_frames*1e9/(after-stats_start),native_enabled,stats_gpu,stats_frames,
                    stats_lock/(1e6*stats_frames),stats_convert/(1e6*stats_frames),stats_unlock/(1e6*stats_frames),
                    (long long)frame->pts);
-                stats_start=after;stats_frames=0;stats_lock=stats_convert=stats_unlock=0;
+                stats_start=after;stats_frames=stats_gpu=0;stats_lock=stats_convert=stats_unlock=0;
            }
        } else {
+            // Byte buffers hold planar YUV; the same worker bands copy the
+            // planes (in parallel for panorama sizes).
            uint8_t *y=header->pBuffer,*u=y+stride*height,*v=u+stride*height/4;
-            for(int row=0;row<frame->height;row++)
-                memcpy(y+row*stride,frame->data[0]+row*frame->linesize[0],frame->width);
-            for(int row=0;row<frame->height/2;row++) {
-                const uint8_t *src=frame->data[1]+row*frame->linesize[1];
-                uint8_t *du=u+row*(stride/2),*dv=v+row*(stride/2);int x=0;
-                for(;x+16<=frame->width/2;x+=16) {
-                    uint8x16x2_t pair=vld2q_u8(src+2*x);vst1q_u8(du+x,pair.val[0]);vst1q_u8(dv+x,pair.val[1]);
-                }
-                for(;x<frame->width/2;x++){du[x]=src[2*x];dv[x]=src[2*x+1];}
-            }
+            AHardwareBuffer_Planes planes={};planes.planeCount=3;
+            planes.planes[0]={y,1,(uint32_t)stride};
+            planes.planes[1]={u,1,(uint32_t)(stride/2)};
+            planes.planes[2]={v,1,(uint32_t)(stride/2)};
+            color.convert(frame,nullptr,0,nullptr,&planes);
        }
        header->nOffset=0;header->nFilledLen=(OMX_U32)bytes;
        header->nTimeStamp=frame->pts==AV_NOPTS_VALUE?frame->best_effort_timestamp:frame->pts;
+        last_output_pts=header->nTimeStamp;
        header->nFlags=OMX_BUFFERFLAG_ENDOFFRAME;
        queue.erase(queue.begin());info->mOwnedByUs=false;notifyFillBufferDone(header);
        av_frame_unref(frame);held=false;return true;
@@ -301,14 +539,34 @@ protected:
            if(held){if(!outputFrame())return;continue;}
            if(codec) {
                int result=avcodec_receive_frame(codec,frame);
-                if(result==0){held=true;continue;}
+                if(result==0){
+                    int64_t pts=frame->pts==AV_NOPTS_VALUE?frame->best_effort_timestamp:frame->pts;
+                    if(discard_until!=AV_NOPTS_VALUE && pts!=AV_NOPTS_VALUE && pts<=discard_until){av_frame_unref(frame);continue;}
+                    discard_until=AV_NOPTS_VALUE;held=true;continue;
+                }
                if(result==AVERROR_EOF) {
                    BufferInfo *info=*outputs.begin();auto *header=info->mHeader;
                    header->nOffset=0;header->nFilledLen=0;header->nTimeStamp=eos_pts;
                    header->nFlags=OMX_BUFFERFLAG_EOS;outputs.erase(outputs.begin());
                    info->mOwnedByUs=false;notifyFillBufferDone(header);drained=true;return;
                }
-                if(result!=AVERROR(EAGAIN)){fail(result,"hardware frame retrieval");return;}
+                if(result!=AVERROR(EAGAIN)){
+                    if(hardware_active && recoverHardware("frame retrieval"))continue;
+                    if(!failed)fail(result,"frame retrieval");return;
+                }
+            }
+            if(replay_next>=0){
+                if((size_t)replay_next<history.size()){
+                    int result=avcodec_send_packet(codec,history[replay_next]);
+                    if(result<0){fail(result,"software recovery packet");return;}
+                    replay_next++;continue;
+                }
+                clearHistory();
+                if(replay_eos){
+                    int result=avcodec_send_packet(codec,nullptr);
+                    if(result<0){fail(result,"software recovery drain");return;}
+                    replay_eos=false;eos_submitted=true;continue;
+                }
            }
            if(inputs.empty())return;
            BufferInfo *info=*inputs.begin();auto *header=info->mHeader;
@@ -317,8 +575,8 @@ protected:
            }
            if(header->nFlags&OMX_BUFFERFLAG_CODECCONFIG) {
                if(replace_config){av_freep(&config);config_size=0;replace_config=false;}
-                if(codec || config_size+header->nFilledLen>1024*1024) {
-                    fail(AVERROR(EINVAL),"late or oversized codec configuration");return;
+                if(config_size+header->nFilledLen>1024*1024) {
+                    fail(AVERROR(EINVAL),"oversized codec configuration");return;
                }
                if(header->nFilledLen) {
                    void *grown=av_realloc(config,config_size+header->nFilledLen);
@@ -327,97 +585,170 @@ protected:
                    memcpy(config+config_size,header->pBuffer+header->nOffset,header->nFilledLen);
                    config_size+=header->nFilledLen;
                }
+                // Streaming apps and restarted encoders can send parameter
+                // sets again mid-stream. Stock decoders accept them; submit
+                // them in-band before the next access unit.
+                if(codec)prepend_config=annexB();
                consumeInput(info);continue;
            }
            if(!openDecoder())return;
            if(header->nFilledLen) {
                AVPacket *packet=av_packet_alloc();
                if(!packet){fail(AVERROR(ENOMEM),"input packet");return;}
-                int result=av_new_packet(packet,(int)header->nFilledLen);
+                // Android delivers parameter sets in separate CODECCONFIG
+                // buffers. V4L2 expects Annex B parameter sets in its input
+                // stream; FFmpeg's V4L2 wrapper does not submit extradata.
+                size_t prefix=prepend_config?config_size:0;
+                int result=av_new_packet(packet,(int)(prefix+header->nFilledLen));
                if(result>=0) {
-                    memcpy(packet->data,header->pBuffer+header->nOffset,header->nFilledLen);
+                    if(prefix)memcpy(packet->data,config,prefix);
+                    memcpy(packet->data+prefix,header->pBuffer+header->nOffset,header->nFilledLen);
                    packet->pts=packet->dts=header->nTimeStamp;
                    if(header->nFlags&OMX_BUFFERFLAG_SYNCFRAME)packet->flags|=AV_PKT_FLAG_KEY;
+                    // ACodec does not preserve MediaCodec's KEY_FRAME flag
+                    // on decoder input. Parse complete access units so driver
+                    // recovery also works for ordinary Android clients.
+                    if(parser){
+                        uint8_t *parsed=nullptr;int parsed_size=0;
+                        av_parser_parse2(parser,codec,&parsed,&parsed_size,packet->data,packet->size,
+                            packet->pts,packet->dts,AV_NOPTS_VALUE);
+                        if(parser->key_frame==1)packet->flags|=AV_PKT_FLAG_KEY;
+                    }
                    result=avcodec_send_packet(codec,packet);
+                    if(result>=0){prepend_config=false;rememberInput(packet);}
                }
                av_packet_free(&packet);
                if(result==AVERROR(EAGAIN))return;
-                if(result<0){fail(result,"hardware packet submission");return;}
+                if(result<0){
+                    if(hardware_active && recoverHardware("packet submission"))continue;
+                    if(!failed)fail(result,"packet submission");return;
+                }
                header->nFilledLen=0;
            }
            if(header->nFlags&OMX_BUFFERFLAG_EOS) {
                eos_pts=header->nTimeStamp;
                int result=avcodec_send_packet(codec,nullptr);
                if(result==AVERROR(EAGAIN))return;
-                if(result<0){fail(result,"hardware stream drain");return;}
+                if(result<0){fail(result,"stream drain");return;}
+                eos_submitted=true;
            }
+            replace_config=true;  // a later configuration replaces this one
            consumeInput(info);
        }
    }
    void onPortFlushCompleted(OMX_U32 port) override {
        if(port==kInputPortIndex) {
-            // A fresh hardware session avoids relying on partially drained
-            // firmware state when ExoPlayer seeks or starts another clip.
-            avcodec_free_context(&codec);av_frame_unref(frame);
+            gpu.clearBuffers();
+            // Release the held picture first (its V4L2 buffer returns to the driver).
+            av_frame_unref(frame);av_parser_close(parser);parser=nullptr;clearHistory();
+            // Software decoders flush in place. A hardware session restarts in
+            // place only after a completed drain (replay/loop after EOS):
+            // restarting a running Iris session's queues failed its admission
+            // check and left buffers unreturned, so other seeks reopen it.
+            bool usable=codec && !failed && (!hardware_active || drained);
+            eos_submitted=false;replay_eos=false;
+            last_output_pts=discard_until=AV_NOPTS_VALUE;
            held=false;drained=false;failed=false;replace_config=true;
+            if(usable) {
+                // Keeps the buffers and the Iris session (no reallocation).
+                avcodec_flush_buffers(codec);
+                int64_t restart_error=0;
+                if(hardware_active && (av_opt_get_int(codec->priv_data,"frameport_flush_error",0,&restart_error)<0 ||
+                    restart_error<0)) {
+                    ALOGW("Iris %s replay restart failed (%lld); continuing in software",kind.mime,(long long)restart_error);
+                    gpu.clearBuffers();avcodec_free_context(&codec);hardware_active=false;prefer_software=true;
+                } else {
+                    parser=av_parser_init(codec->codec_id);
+                    if(parser)parser->flags|=PARSER_FLAG_COMPLETE_FRAMES;
+                    prepend_config=annexB();
+                }
+            } else {
+                if(hardware_active && kind.coding==OMX_VIDEO_CodingVP9){
+                    // Reopening Iris VP9 sessions after a seek damaged pictures and
+                    // faulted the kernel on this Frame: continue in software.
+                    prefer_software=true;
+                    ALOGW("VP9 seek: continuing in software rather than reopening Iris");
+                }
+                gpu.clearBuffers();avcodec_free_context(&codec);hardware_active=false;
+            }
        }
    }
    void onReset() override {
-        avcodec_free_context(&codec);av_frame_unref(frame);av_freep(&config);config_size=0;
+        gpu_allowed=true;
+        av_frame_unref(frame);av_parser_close(parser);parser=nullptr;gpu.clearBuffers();avcodec_free_context(&codec);av_freep(&config);config_size=0;clearHistory();
+        hardware_active=false;prefer_software=false;eos_submitted=false;replay_eos=false;
+        last_output_pts=discard_until=AV_NOPTS_VALUE;
        held=false;drained=false;failed=false;replace_config=false;
        SoftVideoDecoderOMXComponent::onReset();
        surface=false;native_enabled=false;metadata=false;mOutputFormat=OMX_COLOR_FormatYUV420Planar;
        updatePortDefinitions(true,false);
    }
-    ~FramePortHEVC() override {av_frame_free(&frame);avcodec_free_context(&codec);av_freep(&config);}
+    ~FramePortVideo() override {av_frame_free(&frame);av_parser_close(parser);gpu.clearBuffers();avcodec_free_context(&codec);av_freep(&config);clearHistory();}
 public:
-    FramePortHEVC(const char *name,const OMX_CALLBACKTYPE *callbacks,OMX_PTR appData,OMX_COMPONENTTYPE **component)
-        :SoftVideoDecoderOMXComponent(name,"video_decoder.hevc",OMX_VIDEO_CodingHEVC,
-            profiles,1,320,240,callbacks,appData,component) {
-        initPorts(8,2*1024*1024,4,"video/hevc",1);
+    FramePortVideo(const DecoderKind &type,const OMX_CALLBACKTYPE *callbacks,OMX_PTR appData,OMX_COMPONENTTYPE **component)
+        :SoftVideoDecoderOMXComponent(type.name,type.role,type.coding,
+            type.profiles,type.profile_count,320,240,callbacks,appData,component),kind(type) {
+        initPorts(8,2*1024*1024,4,type.mime,1);
    }
 };
 class FramePortOMXPlugin final : public OMXPluginBase {
-    bool available;
-    static bool probeCapacity() {
-        // Some SteamOS Iris builds count the new session's geometry for every
-        // open session. A concurrent Steam UI decoder can therefore reject 8K.
-        // Retain the stock HEVC codec if the driver's admission check fails.
+    bool available[kind_count]={};
+    static bool probeCapacity(const DecoderKind &kind) {
+        // Check each coded format separately, at ordinary video geometry.
+        // A rejected 8K session must not hide hardware from a 1080p app.
        int fd=open("/dev/video-dec0",O_RDWR|O_NONBLOCK);
        if(fd<0)return false;
+        bool supported=false;
+        for(unsigned i=0;;i++){
+            v4l2_fmtdesc desc={};desc.index=i;desc.type=V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE;
+            if(ioctl(fd,VIDIOC_ENUM_FMT,&desc)<0)break;
+            if(desc.pixelformat==kind.fourcc)supported=true;
+        }
+        if(!supported){close(fd);return false;}
        v4l2_format format={};format.type=V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE;
-        format.fmt.pix_mp.width=8192;format.fmt.pix_mp.height=4096;
-        format.fmt.pix_mp.pixelformat=V4L2_PIX_FMT_HEVC;format.fmt.pix_mp.num_planes=1;
-        bool ok=ioctl(fd,VIDIOC_S_FMT,&format)==0;
+        format.fmt.pix_mp.width=1920;format.fmt.pix_mp.height=1080;
+        format.fmt.pix_mp.pixelformat=kind.fourcc;format.fmt.pix_mp.num_planes=1;
+        bool ok=ioctl(fd,VIDIOC_S_FMT,&format)==0 && format.fmt.pix_mp.pixelformat==kind.fourcc;
        format.type=V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;format.fmt.pix_mp.pixelformat=V4L2_PIX_FMT_NV12;
-        if(ok)ok=ioctl(fd,VIDIOC_S_FMT,&format)==0;
+        if(ok)ok=ioctl(fd,VIDIOC_S_FMT,&format)==0 && format.fmt.pix_mp.pixelformat==V4L2_PIX_FMT_NV12;
        v4l2_requestbuffers buffers={};buffers.count=2;
        buffers.type=V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE;buffers.memory=V4L2_MEMORY_MMAP;
        if(ok)ok=ioctl(fd,VIDIOC_REQBUFS,&buffers)==0;
        close(fd);return ok;
    }
 public:
-    FramePortOMXPlugin():available(probeCapacity()) {
-        if(!available)ALOGW("Iris 8K admission unavailable; keeping Android's stock HEVC decoder");
+    FramePortOMXPlugin() {
+        timespec now;clock_gettime(CLOCK_MONOTONIC,&now);plugin_loaded_ns=now.tv_sec*1000000000ll+now.tv_nsec;
+        for(unsigned i=0;i<kind_count;i++){
+            available[i]=probeCapacity(kinds[i]);
+            if(!available[i])ALOGW("Iris %s unavailable; keeping Android's stock decoder",kinds[i].mime);
+        }
    }
    OMX_ERRORTYPE makeComponentInstance(const char *name,const OMX_CALLBACKTYPE *callbacks,
        OMX_PTR appData,OMX_COMPONENTTYPE **component) override {
-        if(!available || strcmp(name,"OMX.frameport.hevc.decoder"))return OMX_ErrorInvalidComponentName;
-        auto *decoder=new FramePortHEVC(name,callbacks,appData,component);
-        decoder->incStrong(this);return decoder->initCheck();
+        for(unsigned i=0;i<kind_count;i++)if(available[i] && !strcmp(name,kinds[i].name)){
+            auto *decoder=new FramePortVideo(kinds[i],callbacks,appData,component);
+            decoder->incStrong(this);return decoder->initCheck();
+        }
+        return OMX_ErrorInvalidComponentName;
    }
    OMX_ERRORTYPE destroyComponentInstance(OMX_COMPONENTTYPE *component) override {
        auto *decoder=static_cast<SoftOMXComponent*>(component->pComponentPrivate);
        decoder->prepareForDestruction();decoder->decStrong(this);return OMX_ErrorNone;
    }
    OMX_ERRORTYPE enumerateComponents(OMX_STRING name,size_t size,OMX_U32 index) override {
-        if(index || !available)return OMX_ErrorNoMore;
-        if(size<sizeof("OMX.frameport.hevc.decoder"))return OMX_ErrorBadParameter;
-        strcpy(name,"OMX.frameport.hevc.decoder");return OMX_ErrorNone;
+        for(unsigned i=0;i<kind_count;i++)if(available[i]){
+            if(index){--index;continue;}
+            if(size<=strlen(kinds[i].name))return OMX_ErrorBadParameter;
+            strcpy(name,kinds[i].name);return OMX_ErrorNone;
+        }
+        return OMX_ErrorNoMore;
    }
    OMX_ERRORTYPE getRolesOfComponent(const char *name,Vector<String8> *roles) override {
-        if(!available || strcmp(name,"OMX.frameport.hevc.decoder"))return OMX_ErrorInvalidComponentName;
-        roles->clear();roles->push(String8("video_decoder.hevc"));return OMX_ErrorNone;
+        for(unsigned i=0;i<kind_count;i++)if(available[i] && !strcmp(name,kinds[i].name)){
+            roles->clear();roles->push(String8(kinds[i].role));return OMX_ErrorNone;
+        }
+        return OMX_ErrorInvalidComponentName;
    }
 };
 }
@@ -15,25 +15,32 @@ int main(int argc,char **argv){
 bool fallback=argc>2 && !strcmp(argv[2],"fallback");
 assert(argc>=2);int fd=open(argv[1],O_RDONLY);assert(fd>=0);struct stat st;assert(!fstat(fd,&st));
 auto *extractor=AMediaExtractor_new();assert(AMediaExtractor_setDataSourceFd(extractor,fd,0,st.st_size)==AMEDIA_OK);
- AMediaFormat *format=nullptr;int width=0,height=0;
+ AMediaFormat *format=nullptr;int width=0,height=0;const char *video_mime=nullptr;
 for(size_t i=0;i<AMediaExtractor_getTrackCount(extractor);i++){
  auto *candidate=AMediaExtractor_getTrackFormat(extractor,i);const char *mime=nullptr;
-  if(AMediaFormat_getString(candidate,AMEDIAFORMAT_KEY_MIME,&mime)&&!strcmp(mime,"video/hevc")){
-   format=candidate;assert(AMediaExtractor_selectTrack(extractor,i)==AMEDIA_OK);break;
+  if(AMediaFormat_getString(candidate,AMEDIAFORMAT_KEY_MIME,&mime)&&
+     (!strcmp(mime,"video/hevc") || !strcmp(mime,"video/avc") || !strcmp(mime,"video/x-vnd.on2.vp9"))){
+   format=candidate;video_mime=mime;assert(AMediaExtractor_selectTrack(extractor,i)==AMEDIA_OK);break;
  }AMediaFormat_delete(candidate);
 }assert(format);
 assert(AMediaFormat_getInt32(format,AMEDIAFORMAT_KEY_WIDTH,&width));assert(AMediaFormat_getInt32(format,AMEDIAFORMAT_KEY_HEIGHT,&height));
- auto *codec=AMediaCodec_createDecoderByType("video/hevc");assert(codec);char *name=nullptr;
+ const char *expected=!strcmp(video_mime,"video/hevc")?"OMX.frameport.hevc.decoder":
+   !strcmp(video_mime,"video/avc")?"OMX.frameport.avc.decoder":"OMX.frameport.vp9.decoder";
+ const char *stock=!strcmp(video_mime,"video/hevc")?"OMX.google.hevc.decoder":
+   !strcmp(video_mime,"video/avc")?"OMX.google.h264.decoder":"OMX.google.vp9.decoder";
+ auto *codec=AMediaCodec_createDecoderByType(video_mime);assert(codec);char *name=nullptr;
 assert(AMediaCodec_getName(codec,&name)==AMEDIA_OK);printf("Selected codec: %s\n",name);fflush(stdout);
 if(argc>2 && !strcmp(argv[2],"query")){
-  assert(!strcmp(name,"OMX.frameport.hevc.decoder") || !strcmp(name,"OMX.google.hevc.decoder"));
+  assert(!strcmp(name,expected) || !strcmp(name,stock));
  AMediaCodec_releaseName(codec,name);AMediaCodec_delete(codec);
  AMediaFormat_delete(format);AMediaExtractor_delete(extractor);close(fd);
  puts("PASS default HEVC selection");return 0;
 }
- assert(!strcmp(name,fallback?"OMX.google.hevc.decoder":"OMX.frameport.hevc.decoder"));AMediaCodec_releaseName(codec,name);
+ assert(!strcmp(name,fallback?stock:expected));AMediaCodec_releaseName(codec,name);
 AImageReader *reader=nullptr;ANativeWindow *window=nullptr;
- if(argc>2){assert(AImageReader_newWithUsage(width,height,AIMAGE_FORMAT_PRIVATE,AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE,3,&reader)==AMEDIA_OK);assert(AImageReader_getWindow(reader,&window)==AMEDIA_OK);}
+ if(argc>2){assert(AImageReader_newWithUsage(width,height,AIMAGE_FORMAT_PRIVATE,AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE,3,&reader)==AMEDIA_OK);assert(AImageReader_getWindow(reader,&window)==AMEDIA_OK);AMediaFormat_setInt32(format,"allow-frame-drop",0);}
+ printf("Input format: %s\n",AMediaFormat_toString(format));
+ const char *keys[]={"csd-0","csd-1"};for(const char *key:keys){void *p=nullptr;size_t n=0;if(AMediaFormat_getBuffer(format,key,&p,&n)){auto *b=(unsigned char*)p;printf("%s: %zu bytes %02x %02x %02x %02x\n",key,n,b[0],b[1],b[2],b[3]);}}
 assert(AMediaCodec_configure(codec,format,window,nullptr,0)==AMEDIA_OK);assert(AMediaCodec_start(codec)==AMEDIA_OK);
 for(unsigned phase=0;phase<2;phase++){
 unsigned goal=fallback?(phase?2:6):(phase?120:600),sent=0,received=0,images=0;bool input_eos=false,output_eos=false;double start=now();
@@ -42,13 +49,23 @@ int main(int argc,char **argv){
   size_t capacity=0;auto *data=AMediaCodec_getInputBuffer(codec,id,&capacity);assert(data);
   if(sent==goal){assert(AMediaCodec_queueInputBuffer(codec,id,0,0,sent*1000000/60,AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM)==AMEDIA_OK);input_eos=true;}
   else {ssize_t size=AMediaExtractor_readSampleData(extractor,data,capacity);assert(size>0);int64_t pts=AMediaExtractor_getSampleTime(extractor);
+    if(sent<2)printf("Input packet: %zd bytes %02x %02x %02x %02x\n",size,data[0],data[1],data[2],data[3]);
    assert(AMediaCodec_queueInputBuffer(codec,id,0,size,pts,AMediaExtractor_getSampleFlags(extractor)&1?AMEDIACODEC_BUFFER_FLAG_KEY_FRAME:0)==AMEDIA_OK);
    assert(AMediaExtractor_advance(extractor));sent++;
   }
  }}
  AMediaCodecBufferInfo info={};ssize_t id=AMediaCodec_dequeueOutputBuffer(codec,&info,1000);
-  if(id>=0){if(info.size)received++;output_eos=info.flags&AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM;
+  if(id>=0){if(received<2 || (info.flags&AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM))printf("Buffer id=%zd size=%d flags=%u pts=%lld\n",id,info.size,info.flags,(long long)info.presentationTimeUs);if(info.size)received++;output_eos=info.flags&AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM;
   assert(AMediaCodec_releaseOutputBuffer(codec,id,window!=nullptr)==AMEDIA_OK);
+   // Surface delivery is asynchronous. Drain each rendered picture before
+   // submitting another, so this unpaced fixture does not test frame dropping.
+   if(reader && info.size){double deadline=now()+1;unsigned before=images;
+    do{AImage *image=nullptr;if(AImageReader_acquireNextImage(reader,&image)==AMEDIA_OK){
+     int32_t w=0,h=0;assert(AImage_getWidth(image,&w)==AMEDIA_OK && AImage_getHeight(image,&h)==AMEDIA_OK);
+     assert(w==width && h==height);images++;AImage_delete(image);
+    }else usleep(100);}while(images==before && now()<deadline);
+    assert(images>before);
+   }
  }else if(id==AMEDIACODEC_INFO_OUTPUT_FORMAT_CHANGED){auto *out=AMediaCodec_getOutputFormat(codec);printf("Output: %s\n",AMediaFormat_toString(out));AMediaFormat_delete(out);fflush(stdout);}
  if(reader){AImage *image=nullptr;while(AImageReader_acquireNextImage(reader,&image)==AMEDIA_OK){images++;AImage_delete(image);}}
 }
@@ -10,5 +10,23 @@
            <Limit name="bitrate" range="1-245000000" />
            <Limit name="concurrent-instances" max="1" />
        </MediaCodec>
+        <MediaCodec name="OMX.frameport.avc.decoder" type="video/avc" rank="64">
+            <Limit name="size" min="128x128" max="8192x8192" />
+            <Limit name="alignment" value="2x2" />
+            <Limit name="block-size" value="16x16" />
+            <Limit name="block-count" range="1-138240" />
+            <Limit name="blocks-per-second" range="1-7864320" />
+            <Limit name="bitrate" range="1-245000000" />
+            <Limit name="concurrent-instances" max="1" />
+        </MediaCodec>
+        <MediaCodec name="OMX.frameport.vp9.decoder" type="video/x-vnd.on2.vp9" rank="64">
+            <Limit name="size" min="128x128" max="4096x2304" />
+            <Limit name="alignment" value="2x2" />
+            <Limit name="block-size" value="16x16" />
+            <Limit name="block-count" range="1-36864" />
+            <Limit name="blocks-per-second" range="1-2211840" />
+            <Limit name="bitrate" range="1-245000000" />
+            <Limit name="concurrent-instances" max="1" />
+        </MediaCodec>
    </Decoders>
 </MediaCodecs>
@@ -1,6 +1,8 @@
 // Exercises the actual Android OMX component, including port renegotiation,
 // output conversion, timestamps and normal state/buffer lifetimes.
 #include <media/hardware/OMXPluginBase.h>
+#include <media/hardware/HardwareAPI.h>
+#include <media/stagefright/foundation/ColorUtils.h>
 #include <media/openmax/OMX_Component.h>
 #include <media/openmax/OMX_IndexExt.h>
 #include <utils/String8.h>
@@ -10,6 +12,12 @@
 #include <cstring>
 #include <cassert>
 #include <cstdlib>
+#include <unistd.h>
+#include <android/hardware_buffer.h>
+#include <cutils/native_handle.h>
+#include <sys/stat.h>
+extern "C" const native_handle_t *AHardwareBuffer_getNativeHandle(const AHardwareBuffer*);
+namespace android { ANativeWindowBuffer *AHardwareBuffer_to_ANativeWindowBuffer(AHardwareBuffer*); }
 extern "C" {
 #include <libavformat/avformat.h>
 #include <libavcodec/bsf.h>
@@ -25,11 +33,18 @@ struct Test {
    unsigned state=OMX_StateLoaded,port_event=0;
    OMX_COMMANDTYPE port_command=OMX_CommandStateSet;
    int64_t last_pts=-1;
+    uint64_t first_hash=0;
+    uint64_t pictures[120]={};
+    bool replay=false;
+    bool native=false;
+    unsigned width=0,height=0;
+    AHardwareBuffer *hardware[16]={};
 };
 static OMX_ERRORTYPE event(OMX_HANDLETYPE,OMX_PTR data,OMX_EVENTTYPE type,OMX_U32 a,OMX_U32 b,OMX_PTR) {
    auto &t=*(Test*)data;pthread_mutex_lock(&t.lock);
    if(type==OMX_EventError){fprintf(stderr,"OMX error: %x %x\n",a,b);t.error=true;}
-    if(type==OMX_EventPortSettingsChanged && a==1)t.resize=true;
+    // As ACodec: only definition changes reallocate; crop/colour are updates.
+    if(type==OMX_EventPortSettingsChanged && a==1 && (b==0 || b==OMX_IndexParamPortDefinition))t.resize=true;
    if(type==OMX_EventCmdComplete) {
        if(a==OMX_CommandStateSet)t.state=b;
        else {t.port_event=b==OMX_ALL?2:b+1;t.port_command=(OMX_COMMANDTYPE)a;}
@@ -43,8 +58,42 @@ static OMX_ERRORTYPE empty(OMX_HANDLETYPE,OMX_PTR data,OMX_BUFFERHEADERTYPE *hea
 static OMX_ERRORTYPE fill(OMX_HANDLETYPE,OMX_PTR data,OMX_BUFFERHEADERTYPE *header) {
    auto &t=*(Test*)data;pthread_mutex_lock(&t.lock);assert(t.out_count<64);
    if(header->nFilledLen) {
+        AHardwareBuffer_Planes planes={};AHardwareBuffer *hardware=nullptr;
+        if(t.native){
+            auto *meta=reinterpret_cast<android::VideoNativeMetadata*>(header->pBuffer);
+            for(auto *b:t.hardware)if(b && android::AHardwareBuffer_to_ANativeWindowBuffer(b)==meta->pBuffer)hardware=b;
+            assert(hardware);
+            assert(AHardwareBuffer_lockPlanes(hardware,AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN,meta->nFenceFd,nullptr,&planes)==0);
+            if(meta->nFenceFd>=0)close(meta->nFenceFd);meta->nFenceFd=-1;
+        }
+        auto byte=[&](unsigned i)->uint8_t{
+            if(!t.native)return header->pBuffer[i];
+            unsigned y=t.width*t.height,plane=i<y?0:i<y+y/4?1:2;
+            unsigned index=plane?i-y-(plane==2?y/4:0):i,width=plane?t.width/2:t.width;
+            return ((uint8_t*)planes.planes[plane].data)[(index/width)*planes.planes[plane].rowStride+
+                (index%width)*planes.planes[plane].pixelStride];
+        };
+        if(t.frames<120){
+            uint64_t hash=1469598103934665603ull;
+            unsigned pixel_bytes=t.native?t.width*t.height*3/2:header->nFilledLen;
+            unsigned step=pixel_bytes/1024;if(!step)step=1;
+            for(unsigned i=0;i<pixel_bytes;i+=step){hash^=byte(i);hash*=1099511628211ull;}
+            if(t.replay && t.pictures[t.frames]!=hash){
+                fprintf(stderr,"Picture %u changed after seek/recovery\n",t.frames);t.error=true;
+            }
+            t.pictures[t.frames]=hash;
+        }
+        if(!t.frames){
+            uint64_t hash=1469598103934665603ull;
+            unsigned pixel_bytes=t.native?t.width*t.height*3/2:header->nFilledLen;
+            for(unsigned i=0;i<pixel_bytes;i++){hash^=byte(i);hash*=1099511628211ull;}
+            printf("First-picture hash: %016llx\n",(unsigned long long)hash);fflush(stdout);
+            if(t.first_hash && t.first_hash!=hash){fprintf(stderr,"Seek did not reproduce the first picture\n");t.error=true;}
+            t.first_hash=hash;
+        }
        if(header->nTimeStamp<t.last_pts){fprintf(stderr,"PTS went backwards\n");t.error=true;}
        t.last_pts=header->nTimeStamp;t.frames++;
+        if(hardware)assert(AHardwareBuffer_unlock(hardware,nullptr)==0);
    }
    if(header->nFlags&OMX_BUFFERFLAG_EOS)t.eos=true;
    t.output_free[t.out_count++]=header;
@@ -65,6 +114,22 @@ static void allocate(Test &t,unsigned port,OMX_BUFFERHEADERTYPE **headers,unsign
    count=def.nBufferCountActual;assert(count<=16);
    printf("Allocate port %u: %ux%u, %u buffers x %u bytes\n",port,def.format.video.nFrameWidth,def.format.video.nFrameHeight,count,def.nBufferSize);fflush(stdout);
    for(unsigned i=0;i<count;i++)assert(t.component->AllocateBuffer(t.component,&headers[i],port,nullptr,def.nBufferSize)==OMX_ErrorNone);
+    if(port==1 && t.native){
+        t.width=def.format.video.nFrameWidth;t.height=def.format.video.nFrameHeight;
+        for(unsigned i=0;i<count;i++){
+            AHardwareBuffer_Desc d={};d.width=t.width;d.height=t.height;d.layers=1;d.format=AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_420;
+            d.usage=AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN|AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN|AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE;
+            assert(AHardwareBuffer_allocate(&d,&t.hardware[i])==0);
+            if(!i){auto *handle=AHardwareBuffer_getNativeHandle(t.hardware[i]);
+                printf("Native buffer handles: %d\n",handle->numFds);
+                for(int fd=0;fd<handle->numFds;fd++){struct stat st={};assert(fstat(handle->data[fd],&st)==0);
+                    printf("  fd %d: device=%llu inode=%llu bytes=%lld\n",fd,(unsigned long long)st.st_dev,
+                        (unsigned long long)st.st_ino,(long long)st.st_size);}fflush(stdout);}
+            auto *meta=reinterpret_cast<android::VideoNativeMetadata*>(headers[i]->pBuffer);
+            meta->eType=android::kMetadataBufferTypeANWBuffer;meta->pBuffer=android::AHardwareBuffer_to_ANativeWindowBuffer(t.hardware[i]);
+            meta->nFenceFd=-1;
+        }
+    }
 }
 static void queue_output(Test &t) {
    for(;;) {
@@ -76,21 +141,66 @@ static void queue_output(Test &t) {
    }
 }
 int main(int argc,char **argv) {
-    assert(argc==2 || argc==3);void *lib=dlopen("/probe/libstagefrighthw.so",RTLD_NOW);
+    alarm(60);
+    assert(argc==2 || argc==3);const char *path=getenv("FRAMEPORT_PROBE_CODEC");
+    void *lib=dlopen(path?path:"/probe/libstagefrighthw.so",RTLD_NOW);
    if(!lib){fprintf(stderr,"%s\n",dlerror());return 1;}
    auto factory=(android::OMXPluginBase*(*)())dlsym(lib,"createOMXPlugin");assert(factory);
    auto *plugin=factory();Test t;OMX_CALLBACKTYPE callbacks={event,empty,fill};
-    assert(plugin->makeComponentInstance("OMX.frameport.hevc.decoder",&callbacks,&t,&t.component)==OMX_ErrorNone);
-    if(argc==3) {
-        auto mode=parameter<OMX_PARAM_U32TYPE>(1);
-        assert(t.component->GetParameter(t.component,(OMX_INDEXTYPE)OMX_IndexParamVideoAndroidRequiresSwRenderer,&mode)==OMX_ErrorNone);
-        assert(mode.nU32==1);
+    t.native=argc==3 && (!strcmp(argv[2],"native") || !strcmp(argv[2],"native_cpu") || !strcmp(argv[2],"native_importfail"));
+    if(t.native && !strcmp(argv[2],"native_cpu")){
+        auto deny=(void(*)())dlsym(RTLD_DEFAULT,"frameport_probe_deny_gpu");assert(deny);deny();
+    }
+    if(t.native && !strcmp(argv[2],"native_importfail")){
+        auto deny=(void(*)())dlsym(RTLD_DEFAULT,"frameport_probe_deny_gpu_import");assert(deny);deny();
+    }
+    if(argc==3 && (!strcmp(argv[2],"software") || !strcmp(argv[2],"software_rgba"))){
+        auto deny=(void(*)())dlsym(RTLD_DEFAULT,"frameport_probe_deny_device");assert(deny);deny();
+    }
+    if(argc==3 && !strcmp(argv[2],"recover")){
+        auto corrupt=(void(*)())dlsym(RTLD_DEFAULT,"frameport_probe_corrupt_picture");assert(corrupt);corrupt();
+    }
+    if(argc==3 && !strcmp(argv[2],"restartfail")){
+        auto deny=(void(*)())dlsym(RTLD_DEFAULT,"frameport_probe_deny_restart");assert(deny);deny();
    }
    AVFormatContext *format=nullptr;assert(avformat_open_input(&format,argv[1],nullptr,nullptr)>=0);
    unsigned video=0;while(video<format->nb_streams && format->streams[video]->codecpar->codec_type!=AVMEDIA_TYPE_VIDEO)video++;
    assert(video<format->nb_streams);auto *stream=format->streams[video];
-    AVBSFContext *bsf=nullptr;assert(av_bsf_alloc(av_bsf_get_by_name("hevc_mp4toannexb"),&bsf)>=0);
-    assert(avcodec_parameters_copy(bsf->par_in,stream->codecpar)>=0);bsf->time_base_in=stream->time_base;assert(av_bsf_init(bsf)>=0);
+    const char *name=nullptr,*filter=nullptr;
+    switch(stream->codecpar->codec_id){
+        case AV_CODEC_ID_HEVC:name="OMX.frameport.hevc.decoder";filter="hevc_mp4toannexb";break;
+        case AV_CODEC_ID_H264:name="OMX.frameport.avc.decoder";filter="h264_mp4toannexb";break;
+        case AV_CODEC_ID_VP9:name="OMX.frameport.vp9.decoder";break;
+        default:assert(false);
+    }
+    printf("Testing %s\n",name);fflush(stdout);
+    assert(plugin->makeComponentInstance(name,&callbacks,&t,&t.component)==OMX_ErrorNone);
+    if(t.native)for(const char *name:{"OMX.google.android.index.enableAndroidNativeBuffers","OMX.google.android.index.storeANWBufferInMetadata"}){
+        OMX_INDEXTYPE index;assert(t.component->GetExtensionIndex(t.component,(char*)name,&index)==OMX_ErrorNone);
+        auto mode=parameter<android::EnableAndroidNativeBuffersParams>(1);mode.enable=OMX_TRUE;
+        assert(t.component->SetParameter(t.component,index,&mode)==OMX_ErrorNone);
+    }
+    // ACodec supplies the container's colour metadata before decoding. Use the
+    // same contract so full-range fixtures exercise the intended conversion.
+    auto *par=stream->codecpar;
+    if(par->color_primaries!=AVCOL_PRI_UNSPECIFIED || par->color_trc!=AVCOL_TRC_UNSPECIFIED ||
+        par->color_space!=AVCOL_SPC_UNSPECIFIED || par->color_range!=AVCOL_RANGE_UNSPECIFIED) {
+        OMX_INDEXTYPE index;
+        char extension[]="OMX.google.android.index.describeColorAspects";
+        assert(t.component->GetExtensionIndex(t.component,extension,&index)==OMX_ErrorNone);
+        auto aspects=parameter<android::DescribeColorAspectsParams>(1);
+        android::ColorUtils::convertIsoColorAspectsToCodecAspects(par->color_primaries,par->color_trc,
+            par->color_space,par->color_range==AVCOL_RANGE_JPEG,aspects.sAspects);
+        assert(t.component->SetConfig(t.component,index,&aspects)==OMX_ErrorNone);
+    }
+    if(argc==3 && (!strcmp(argv[2],"rgba") || !strcmp(argv[2],"software_rgba"))) {
+        auto mode=parameter<OMX_PARAM_U32TYPE>(1);
+        assert(t.component->GetParameter(t.component,(OMX_INDEXTYPE)OMX_IndexParamVideoAndroidRequiresSwRenderer,&mode)==OMX_ErrorNone);
+        assert(mode.nU32==1);
+    }
+    AVBSFContext *bsf=nullptr;
+    if(filter){assert(av_bsf_alloc(av_bsf_get_by_name(filter),&bsf)>=0);
+        assert(avcodec_parameters_copy(bsf->par_in,stream->codecpar)>=0);bsf->time_base_in=stream->time_base;assert(av_bsf_init(bsf)>=0);}
    auto input_def=parameter<OMX_PARAM_PORTDEFINITIONTYPE>(0);
    assert(t.component->GetParameter(t.component,OMX_IndexParamPortDefinition,&input_def)==OMX_ErrorNone);
    input_def.format.video.nFrameWidth=stream->codecpar->width;input_def.format.video.nFrameHeight=stream->codecpar->height;
@@ -102,9 +212,11 @@ int main(int argc,char **argv) {
    for(unsigned i=0;i<output_count;i++)t.output_free[t.out_count++]=outputs[i];
    assert(t.component->SendCommand(t.component,OMX_CommandStateSet,OMX_StateExecuting,nullptr)==OMX_ErrorNone);wait_state(t,OMX_StateExecuting);
    AVPacket *packet=av_packet_alloc();
+    // midseek: seek mid-playback (no EOS first), as players usually do.
+    bool midseek=argc==3 && !strcmp(argv[2],"midseek");
    for(unsigned phase=0;phase<2;phase++) {
-    bool sent_config=false,sent_eos=false;unsigned submitted=0;
-    unsigned goal=phase?120:600;
+    bool sent_config=false,sent_eos=false,resent_config=false;unsigned submitted=0;
+    unsigned goal=phase?120:midseek?300:600;
    int64_t start=av_gettime_relative();
    for(;;) {
        queue_output(t);
@@ -114,47 +226,61 @@ int main(int argc,char **argv) {
        bool resized=t.resize;t.resize=false;bool finished=t.eos;
        pthread_mutex_unlock(&t.lock);
        if(finished)break;
+        if(midseek && !phase && submitted>=goal) {
+            pthread_mutex_lock(&t.lock);bool enough=t.frames>=200;pthread_mutex_unlock(&t.lock);
+            if(enough)break;
+            usleep(1000);
+        }
        if(resized) {
            assert(t.component->SendCommand(t.component,OMX_CommandPortDisable,1,nullptr)==OMX_ErrorNone);
            pthread_mutex_lock(&t.lock);while(t.out_count<output_count && !t.error)pthread_cond_wait(&t.changed,&t.lock);assert(!t.error);t.out_count=0;pthread_mutex_unlock(&t.lock);
            for(unsigned i=0;i<output_count;i++)assert(t.component->FreeBuffer(t.component,1,outputs[i])==OMX_ErrorNone);
+            if(t.native)for(auto &b:t.hardware)if(b){AHardwareBuffer_release(b);b=nullptr;}
            wait_port(t,OMX_CommandPortDisable);
            assert(t.component->SendCommand(t.component,OMX_CommandPortEnable,1,nullptr)==OMX_ErrorNone);
            allocate(t,1,outputs,output_count);wait_port(t,OMX_CommandPortEnable);
            pthread_mutex_lock(&t.lock);for(unsigned i=0;i<output_count;i++)t.output_free[t.out_count++]=outputs[i];pthread_mutex_unlock(&t.lock);
            continue;
        }
-        if(sent_eos)continue;
+        if(sent_eos || (midseek && !phase && submitted>=goal))continue;
        pthread_mutex_lock(&t.lock);
        auto *header=t.in_count?t.input_free[--t.in_count]:nullptr;pthread_mutex_unlock(&t.lock);
        if(!header)continue;
        header->nOffset=0;header->nFilledLen=0;header->nTimeStamp=0;header->nFlags=0;
-        if(!sent_config) {
-            assert((unsigned)bsf->par_out->extradata_size<=header->nAllocLen);
-            memcpy(header->pBuffer,bsf->par_out->extradata,bsf->par_out->extradata_size);
-            header->nFilledLen=bsf->par_out->extradata_size;header->nFlags=OMX_BUFFERFLAG_CODECCONFIG;sent_config=true;
+        // midconfig: parameter sets sent again mid-stream without a flush.
+        bool midconfig=argc==3 && !strcmp(argv[2],"midconfig") && !phase && submitted==300 && !resent_config;
+        if(!sent_config || midconfig) {
+            const auto *params=bsf?bsf->par_out:stream->codecpar;
+            if(midconfig){resent_config=true;puts("Resending codec configuration mid-stream.");fflush(stdout);}
+            assert((unsigned)params->extradata_size<=header->nAllocLen);
+            if(params->extradata_size)memcpy(header->pBuffer,params->extradata,params->extradata_size);
+            header->nFilledLen=params->extradata_size;header->nFlags=OMX_BUFFERFLAG_CODECCONFIG;sent_config=true;
        } else if(submitted>=goal) {
            header->nFlags=OMX_BUFFERFLAG_EOS;header->nTimeStamp=goal*1000000/60;sent_eos=true;
        } else {
            int result;
            do{result=av_read_frame(format,packet);assert(result>=0);if(packet->stream_index!=(int)video)av_packet_unref(packet);}while(packet->stream_index!=(int)video);
-            assert(av_bsf_send_packet(bsf,packet)>=0);assert(av_bsf_receive_packet(bsf,packet)>=0);
+            if(bsf){assert(av_bsf_send_packet(bsf,packet)>=0);assert(av_bsf_receive_packet(bsf,packet)>=0);}
            av_packet_rescale_ts(packet,stream->time_base,AVRational{1,1000000});
            assert((unsigned)packet->size<=header->nAllocLen);memcpy(header->pBuffer,packet->data,packet->size);header->nFilledLen=packet->size;
            header->nTimeStamp=packet->pts;header->nFlags=OMX_BUFFERFLAG_ENDOFFRAME;
-            if(packet->flags&AV_PKT_FLAG_KEY)header->nFlags|=OMX_BUFFERFLAG_SYNCFRAME;
+            // Recovery runs model ACodec decoder input, which omits SYNCFRAME.
+            if((packet->flags&AV_PKT_FLAG_KEY) && !(argc==3 && !strcmp(argv[2],"recover")))
+                header->nFlags|=OMX_BUFFERFLAG_SYNCFRAME;
+            if(submitted<2){printf("Input phase %u: pts=%lld key=%d bytes=%d\n",phase,(long long)packet->pts,
+                !!(packet->flags&AV_PKT_FLAG_KEY),packet->size);fflush(stdout);}
            av_packet_unref(packet);submitted++;
        }
        assert(t.component->EmptyThisBuffer(t.component,header)==OMX_ErrorNone);
    }
    double seconds=(av_gettime_relative()-start)/1000000.0;
-    printf("OMX hardware + full-size planar delivery: %u frames in %.3fs = %.1ffps\n",t.frames,seconds,t.frames/seconds);fflush(stdout);
-    assert(t.frames==goal);
+    printf("OMX decode + full-size delivery: %u frames in %.3fs = %.1ffps\n",t.frames,seconds,t.frames/seconds);fflush(stdout);
+    assert(midseek && !phase?t.frames>=200:t.frames==goal);
    if(!phase) {
        assert(t.component->SendCommand(t.component,OMX_CommandFlush,OMX_ALL,nullptr)==OMX_ErrorNone);
        wait_port(t,OMX_CommandFlush);
-        assert(av_seek_frame(format,video,0,AVSEEK_FLAG_BACKWARD)>=0);av_bsf_flush(bsf);
-        pthread_mutex_lock(&t.lock);t.eos=false;t.frames=0;t.last_pts=-1;pthread_mutex_unlock(&t.lock);
+        assert(av_seek_frame(format,video,0,AVSEEK_FLAG_BACKWARD)>=0);if(bsf)av_bsf_flush(bsf);
+        pthread_mutex_lock(&t.lock);t.eos=false;t.frames=0;t.last_pts=-1;t.replay=true;pthread_mutex_unlock(&t.lock);
        puts("Replaying after a complete OMX flush and seek to the beginning.");
    }
    }
@@ -162,7 +288,10 @@ int main(int argc,char **argv) {
    assert(t.component->SendCommand(t.component,OMX_CommandStateSet,OMX_StateLoaded,nullptr)==OMX_ErrorNone);
    for(unsigned i=0;i<input_count;i++)assert(t.component->FreeBuffer(t.component,0,inputs[i])==OMX_ErrorNone);
    for(unsigned i=0;i<output_count;i++)assert(t.component->FreeBuffer(t.component,1,outputs[i])==OMX_ErrorNone);
+    if(t.native)for(auto &b:t.hardware)if(b){AHardwareBuffer_release(b);b=nullptr;}
    wait_state(t,OMX_StateLoaded);assert(plugin->destroyComponentInstance(t.component)==OMX_ErrorNone);
    delete plugin;dlclose(lib);av_packet_free(&packet);av_bsf_free(&bsf);avformat_close_input(&format);
-    puts("PASS: hardware OMX decode, planar frames, ordered timestamps, EOS and shutdown.");
+    if(t.native){auto count=(unsigned(*)())dlsym(RTLD_DEFAULT,"frameport_probe_gpu_submissions");assert(count);
+        printf("GPU submissions: %u\n",count());assert(!strcmp(argv[2],"native")?count()>0:count()==0);}
+    puts("PASS: OMX decode, ordered timestamps, EOS, seek and shutdown.");
 }
@@ -1,8 +1,9 @@
 #!/usr/bin/python3
-"""Add a per-game codec to Lepton's container, without editing its shared rootfs."""
+"""Add shared codecs to Lepton containers without editing their shared rootfs."""
 import hashlib
 import json
 import os
+import re
 import shutil
 import sys
 from pathlib import Path
@@ -18,11 +19,30 @@ def mounts(directory, config, args):
            name = args[i + 1]
        elif arg.startswith("--name="):
            name = arg.partition("=")[2]
-    if name != f"lepton-steamlaunch-{config['appid']}":
-        return []
-    root = Path(config["lepton"]).resolve().parent / "images" / "rootfs"
+    if config.get("scope") == "shared":
+        # The common launcher supplies these values. Do not intercept arbitrary
+        # Podman containers or depend on a game's package/modified APK.
+        appid = os.environ.get("SteamAppId", "")
+        if not re.fullmatch(r"[0-9]+", appid) or name != f"lepton-steamlaunch-{appid}":
+            return []
+        app = Path(os.environ.get("STEAM_COMPAT_INSTALL_PATH", ""))
+        if app.name != "lepton-app" or not app.is_dir():
+            return []
+        root_arg = None
+        for i, arg in enumerate(args):
+            if arg == "--rootfs" and i + 1 < len(args):
+                root_arg = args[i + 1]
+            elif arg.startswith("--rootfs="):
+                root_arg = arg.partition("=")[2]
+        if not root_arg or not root_arg.endswith(":O"):
+            return []
+        root = Path(root_arg[:-2]).resolve()
+    else:  # old per-game deployments remain compatible during migration
+        if name != f"lepton-steamlaunch-{config['appid']}":
+            return []
+        root = Path(config["lepton"]).resolve().parent / "images" / "rootfs"
    expected_root = str(root) + ":O"
-    if not any(arg == expected_root for arg in args):
+    if not any(arg in (expected_root, "--rootfs=" + expected_root) for arg in args):
        return []
    device = Path("/dev/video-dec0")
    runtime = root / "vendor/lib64/libstagefright_softomx.so"
@@ -36,30 +56,53 @@ def mounts(directory, config, args):
            if target == "/vendor/lib64/libstagefright_softomx.so" and fields.get("source"):
                runtime = Path(fields["source"])
    if upstream_plugin:
-        print("FramePort HEVC: using the runtime's hardware codec plugin", file=sys.stderr)
+        print("FramePort video: using the runtime's hardware codec plugin", file=sys.stderr)
        return []
    if not device.exists() or hashlib.sha256(runtime.read_bytes()).hexdigest() != config["runtime_sha256"]:
-        print("FramePort HEVC: device or runtime ABI differs; retaining the stock codecs", file=sys.stderr)
+        print("FramePort video: device or runtime ABI differs; retaining the stock codecs", file=sys.stderr)
        return []
    xml = ET.parse(root / "vendor/etc/media_codecs.xml")
-    ET.SubElement(xml.getroot(), "Include", href="media_codecs_frameport.xml")
-    merged = directory / "media_codecs.xml"
-    temporary = merged.with_suffix(".tmp")
+    if not any(node.get("href") == "media_codecs_frameport.xml" for node in xml.getroot().findall("Include")):
+        ET.SubElement(xml.getroot(), "Include", href="media_codecs_frameport.xml")
+    # Immutable plugin versions can serve simultaneous app launches and
+    # different Lepton installations. Never share a temporary XML filename.
+    # The version directory stays as the agent verified it: the merged list goes to the user's runtime dir.
+    root_key = hashlib.sha256(str(root).encode()).hexdigest()[:16]
+    merged = merged_dir() / f"media_codecs.{root_key}.xml"
+    temporary = merged.with_suffix(f".{os.getpid()}.tmp")
    xml.write(temporary, encoding="utf-8", xml_declaration=True)
    temporary.replace(merged)
    # Lepton supplies its own /dev tmpfs. A Podman --device node disappears
    # beneath it; a bind mount matches Lepton's existing GPU/sound device setup.
    result = ["--mount", f"type=bind,source={device},destination=/dev/video-dec0,rw"]
-    for source, target in (
-        ("libstagefrighthw.so", "/vendor/lib64/libstagefrighthw.so"),
-        ("media_codecs.xml", "/vendor/etc/media_codecs.xml"),
-        ("media_codecs_frameport.xml", "/vendor/etc/media_codecs_frameport.xml"),
+    for path, target in (
+        (directory / "libstagefrighthw.so", "/vendor/lib64/libstagefrighthw.so"),
+        (merged, "/vendor/etc/media_codecs.xml"),
+        (directory / "media_codecs_frameport.xml", "/vendor/etc/media_codecs_frameport.xml"),
    ):
-        result += ["--mount", f"type=bind,source={directory / source},destination={target},ro"]
-    print("FramePort HEVC: loading the Iris hardware codec plugin for this container", file=sys.stderr)
+        if not path.is_file():
+            raise FileNotFoundError(f"missing video codec mount: {path}")
+        result += ["--mount", f"type=bind,source={path},destination={target},ro"]
+    print("FramePort video: loading the Iris hardware codec plugin for this container", file=sys.stderr)
    return result


+def merged_dir():
+    runtime = os.environ.get("XDG_RUNTIME_DIR", "")
+    base = Path(runtime) if runtime and Path(runtime).is_dir() else Path.home() / ".cache"
+    path = base / "frameport-video"
+    path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    return path
+
+
+def switched_off(directory):
+    """FRAMEPORT_NO_HW_VIDEO=1 (e.g. in a game's Steam launch options) or the Frame-wide switch (FramePort's
+    setting; the agent writes video-codec/disabled) leave every container with Android's stock codecs."""
+    if os.environ.get("FRAMEPORT_NO_HW_VIDEO", "") not in ("", "0"):
+        return True
+    return directory.parent.name == "versions" and (directory.parent.parent / "disabled").exists()
+
+
 def real_podman(directory):
    """Find Podman independently of deployment.json, without recursing into this wrapper."""
    own_bin = (directory / "bin").resolve()
@@ -84,16 +127,18 @@ def main():
    directory = Path(__file__).resolve().parent.parent
    args = sys.argv[1:]
    fallback = real_podman(directory)
+    if switched_off(directory):
+        os.execv(fallback, [fallback, *args])
    try:
        config = json.loads((directory / "deployment.json").read_text())
-        podman = Path(config["podman"]).resolve()
+        podman = Path(config.get("podman", fallback)).resolve()
        if podman.parent == (directory / "bin").resolve() or podman == Path(__file__).resolve():
            raise ValueError("configured Podman points to the codec wrapper")
        extra = mounts(directory, config, args)
        launch_args = [args[0], *extra, *args[1:]] if extra else args
        os.execv(str(podman), [str(podman), *launch_args])
    except Exception as exc:  # a codec/configuration failure must never prevent the stock container from starting
-        print(f"FramePort HEVC: retaining stock codecs: {exc}", file=sys.stderr)
+        print(f"FramePort video: retaining stock codecs: {exc}", file=sys.stderr)
    os.execv(fallback, [fallback, *args])


@@ -0,0 +1,21 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/* Explicit interface; caller holds the AVFrame until GPU work
+ * completes, so the driver's capture buffer cannot be requeued meanwhile. */
+int frameport_v4l2_export_frame(const AVFrame *frame);
+int frameport_v4l2_export_frame(const AVFrame *frame)
+{
+    V4L2Buffer *buf;
+    struct v4l2_exportbuffer exp = {0};
+    if (!frame || frame->format != AV_PIX_FMT_NV12 || !frame->buf[0])
+        return AVERROR(EINVAL);
+    buf = av_buffer_get_opaque(frame->buf[0]);
+    if (!buf || buf->num_planes != 1 || buf->context->type != V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE ||
+        buf->plane_info[0].mm_addr != frame->buf[0]->data || frame->data[0] != frame->buf[0]->data)
+        return AVERROR(EINVAL);
+    exp.type = buf->buf.type;
+    exp.index = buf->buf.index;
+    exp.flags = O_CLOEXEC | O_RDWR;
+    if (ioctl(buf_to_m2mctx(buf)->fd, VIDIOC_EXPBUF, &exp) < 0)
+        return AVERROR(errno);
+    return exp.fd;
+}