Full charge: one pulse after the ring refills

Full charge: the ring empties at once, then spins while it refills
Full charge: the battery ring spins while its bar drains and refills, then pulses
2026-10-15 09:01:31 +02:00 · 2026-10-09 16:18:55 -04:00 · 2026-10-09 16:15:03 -04:00 · 2026-10-09 16:10:20 -04:00 · 2026-10-09 15:59:02 -04:00 · 2026-10-09 15:04:35 -04:00
155 changed files with 14874 additions and 1055 deletions
@@ -159,6 +159,12 @@ jobs:
          merge-multiple: true
      - name: Wheel (CLI install via uv tool / pipx / pip, and its self-update)
        run: uv build --wheel -o out && ls out
+      - name: Videos (docs/media, rendered by the showcase workflow; frameport-<name>.mp4 → FramePort-<name>.mp4)
+        run: |
+          for f in docs/media/frameport-*.mp4; do
+            [ -f "$f" ] || continue
+            n=$(basename "$f" .mp4); cp "$f" "out/FramePort-${n#frameport-}.mp4"
+          done
      - name: Checksums
        run: cd out && sha256sum * > SHA256SUMS.txt && cat SHA256SUMS.txt
      - name: Publish release
@@ -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 }}
@@ -38,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
@@ -67,13 +68,34 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    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 v63), reconnects after a lost stream and stops it when nobody subscribes; `_poll` retries an "error".
+    needs agent v65), reconnects after a lost stream and stops it when nobody subscribes; `_poll` retries an "error".
    Subscribers: "monitor" (the Monitor tab, everything, only while shown) and "card" = the sidebar's live Frame card
    (`ui/frame_card.py` helpers: battery ring, "now playing" row with fps + 2-min sparkline → click opens Monitor;
    games + battery every 5 s, paused while a job's stage is "Upload…", only while connected and setting
    `ui.live_frame_card` (Settings → Appearance, default on) is on; else the battery comes from the 30 s poll).
    ui_smoke injects `FakeMonitorSession` as the hub's `session_factory`.
    User tags live in library entries (`tags`), filters in library setting `ui.library`.
+    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;
@@ -81,6 +103,16 @@ 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
@@ -102,6 +134,14 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    uploads are interruptible (Cancel checked per MiB) and resumable (big files via SFTP `.part` append, small files
    streamed in tar batches; the agent counts files already in `incoming/`). Multi-select in the Library queues
    installs after asking every needed question up front. Failures end in one pop-up (Resume / Uninstall / log).
+  - Other drives (GitHub #90, agent v63): anchors stay in ~/Applications/quest-frame, a game's files may live in
+    `<mount>/FramePort/<pkg>` (`deployment.json` base). Agent `drives` (/proc/mounts, /run/media + Steam library
+    drives; vfat/exfat/ntfs/read-only refused), prepare*/finalize_linux `dest` (unmounted = error, never a fallback;
+    installed games keep their base), `move` (detached systemd-run + `move_status`; cp -a under podman unshare,
+    count+bytes check, symlink retarget, launch.sh: Quest app_dir line / Linux+PC VR rewritten from the record's
+    `launcher` field, else text swap), list_installed `drive`/`drive_missing` (install_state keeps such games
+    "installed"). PC: `install/drives.py`, library setting `install.drive` (Frame page → Storage), game menu
+    "Move to…" (job kind tool-frame), CLI `frame drives`/`frame move`/`install --dest`. Untested on the device.
  - **PC VR repacks are pre-patched to run directly** (proven: Rick and Morty, Vader Immortal run when the exe is
    launched directly; Revive breaks them). So Rift games default to `as_is` = install the copy unchanged and launch
    the exe directly (`pcvr.xr_timefix` for the Frame OpenXR-1.1→1.0 fix, `pcvr.no_crash_reporter` for Unreal).
@@ -162,6 +202,11 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
    OpenXR, source) instead of recipe/patches, `C.missing_libraries` callout (Frame deployment, else last install);
    no Analyze/Rebuild/recipe/share/Game settings actions, Frame only; platform "Linux" badge + library filter; Steam
    tags "Linux app on Frame"/"Linux"; `_follow_catalog` skips them; local files of a lone AppImage = the file only.
+    Desktop Mode entries (GitHub #84, agent v63): finalize_linux writes `frameport-<slug>.desktop` to
+    ~/.local/share/applications (+ ~/Desktop if it exists; `X-FramePort-Package` marks ours), launch.sh with
+    `FRAMEPORT_DESKTOP=1` skips the Steam-parent watchdog and Steam's display; ensure_host_fixes refreshes entries
+    (older installs, stale ones removed), uninstall/purge remove them. Per app: library entry field `desktop_entry`
+    (default on; patches don't apply to Linux apps) → game page switch → agent `desktop_entry`. Untested on device.
  - Quest/Rift twins stay separate entries, shown and named in Steam "Title (Quest)"/"(Rift)" (`core/titles.py`).
  - `Recipe.as_is` = install unchanged (pre-patched libraries): `pipeline.prepare_as_is`; auto for APKs that already
    contain FrameBridge (`frame_patched`). For Rift it changes nothing (the dump is never modified; the Frame copy
@@ -177,6 +222,10 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
  - `patches/` — **the unit of modularity**. `base.py` (Patch interface, registry), `overport.py` (overport CLI patch ids,
    discovered dynamically via `overport patches`), `frame/*.py` (one module per Frame fix), `settings.py` (FrameBridge
    adapter keys + device files as patches). Add a patch = add a module that calls `register(...)`.
+    `upstream.py`: upstream fixes that replace a workaround per build (a probe finds the fix in OVRPort's output →
+    the build leaves the workaround out, `build.superseded`; recipes unchanged). Registered: `ovrport.haptic_envelope`
+    (→ `adapter.haptic_fix`, `frame/haptic_envelope.py`) and `ovrport.microphone_stream` (→ `frame.ovr_microphone`),
+    both fixed in OVRPort runtime 3.4.3-aa54c3f (ovrport/app#73; haptics owner-verified with Lucky's Tale 2026-10-07).
  - `analysis/` — APK/ELF inspection (`detect.py`), `elf.py` (pyelftools reads; own DT_NEEDED writer), `stubgen.py`
    (generates the ovr_* stub .so without a compiler).
  - `apk/` — `axml.py` (binary manifest editor), `workspace.py` (staged zip edits), `sign.py` (apksigner; it aligns too).
@@ -211,9 +260,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.
@@ -247,11 +302,19 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
  artwork, frames.json, the app's SSH key which the dev Frame authorizes).
 - Device checks: `frameport test <pkg>` / `frameport parity-device --results <parity.json> --baseline <launch.txt>
  [--test-only]`; the pre-FramePort baseline is `PATCHED/_known-good-2026-09-28/_frame-state/baseline-launch.txt`.
- Docs screenshots (`docs/images/`): `python scripts/scrub_library.py ~/.local/share/frameport <dir> --status works,issues` (copies
-  library + artwork only; titles replace folder names, local paths → `D:/Games/...`, sort by size) then
-  `FRAMEPORT_HOME=<dir> python scripts/ui_smoke.py --out <shots> --docs --fake-frame --game <pkg>` (set
-  FRAMEPORT_JAVA/_OVERPORT_JAR/_APKSIGNER_JAR so no tool download toast appears; `--viewport 1280x2600` + crop for the
-  patch list). Check every PNG for paths, IPs, user names and repack/scene names before committing.
+- Docs screenshots + videos (docs/SHOWCASE.md): never by hand. `uv run python scripts/showcase/render_docs.py`
+  renders `docs/showcase/shots.yaml` into `docs/images/` (every shot twice, kept when both agree; only visibly changed
+  files are rewritten; `--check` for CI) and `scripts/showcase/record_video.py [names] [--draft]` records the
+  storyboards `docs/showcase/videos/<name>.yaml` (tour = FramePort in use + README teaser; install = the install
+  tutorial: instruction cards for the download / the command on the Frame, the rest filmed from a first start) into
+  `docs/media/frameport-<name>.mp4`. Both build the demo library first (`demo_home.py`, profile `demo` or `fresh`:
+  catalog games from `demo-library.yaml` + `demo-analyses.json`, art/details cached in ~/.cache/frameport-showcase, a
+  pretend Frame from `showcase-frame.json`) in a temp FRAMEPORT_HOME: no personal data, refuses the real data dir
+  and placeholder art; discovery is off and the setup command shows placeholders for the address and code. Steps find elements
+  by name through Flutter's semantics tree (`scripts/showcase/web.py`: text, tooltip; the innermost match wins) —
+  give new icon-only controls a tooltip. The `showcase` workflow renders on UI pushes to main (+ the videos whose
+  storyboard changed, or the ones named on dispatch) and opens PR `showcase/update`; releases attach every video as
+  `FramePort-<name>.mp4`. `scripts/scrub_library.py` (the owner's own library) is only for private screenshots now.
  README rules (owner): states the project is a proof of concept, provides no piracy tools, credits the wrapped
  projects (most functionality is theirs); neutral technical wording; no Quest2Frame mentions anywhere.
 - GUI smoke test: `uv pip install flet-web playwright && playwright install chromium`, then
@@ -317,7 +380,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
@@ -551,7 +617,7 @@ recipe keeps it on). I Am Cat works with issues (judder; scale 0.8 no help). Rob
 libroblox, also with the Vulkan shim). Installs skip the Steam restart when the shortcut is unchanged and wait while a
 game runs (agent v37). New default fixes in FramePort's code reach games already in a library: after every app update
 `library._follow_catalog` re-derives each non-user recipe once (setting `recipes.app_version`; tests switch it off via
-`library.REFRESH_ON_UPDATE`); analysis fields added later still need a re-analysis. Troubleshooting techniques: docs/PLAYBOOK.md "Debugging techniques". Unity `boot.config` "vulkan" substring mislabels GLES games as Vulkan
+`library.REFRESH_ON_UPDATE`). Analysis fields added later: **bump `analysis/detect.ANALYSIS_VERSION`** (stored as `analysis.extra.analysis_version`); older entries whose APK is still there are analysed again at the GUI's start (background thread, not a job: ~8 s per 900 MB APK) and before a build (`pipeline.refresh_analyses`, GitHub #104); only `analysis`/`suggested` change, user recipes stay; an unreadable APK gets `analysis_failed` = the version (not retried until the next bump). Troubleshooting techniques: docs/PLAYBOOK.md "Debugging techniques". Unity `boot.config` "vulkan" substring mislabels GLES games as Vulkan
 (I Am Cat ran GLES); OVRPlugin's "Unavailable OpenXR extension: XR_FB_scene" is routine (no longer triaged).
 **Round 4 (2026-10-04):** XR_KHR_android_surface_swapchain is listed by the Frame's runtime but returns
 FUNCTION_UNSUPPORTED → adapter `surface_emul` (default on, `native/adapter/surface_swapchain.c`): an ordinary runtime
@@ -9,7 +9,10 @@

 Install games that target the Meta Quest, Android, or general PCVR onto your **Valve Steam Frame**. FramePort handles everything from uploading game files, setting up your Frame, injecting compatibility patches, and adding shortcuts to your Steam library. FramePort aims to be as simple as possible by taking advantage of the fact that the Steam Frame runs on Linux.

-![Library](docs/images/library.png)
+[![FramePort: library, one-click install, play, monitor](docs/images/tour-teaser.webp)](docs/media/frameport-tour.mp4)
+
+▶ [Watch the full tour](docs/media/frameport-tour.mp4) · New to FramePort? [Watch the install tutorial](docs/media/frameport-install.mp4)
+(about 90 seconds each, MP4; also attached to every release)

 > **Notice:** FramePort explicitly does NOT download, share, or unlock games. You must provide legally obtained game
 > executables. Core features of FramePort simply download and wrap other published tools (see [Built on](#built-on))
@@ -18,6 +21,8 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V

 ## Features

+![Library](docs/images/library.png)
+
 - **Painless setup:** one short command on the Frame. No root, no `sudo`, no password.
  [What it changes](docs/FRAME_SETUP.md).
 - **Type on Frame:** use your computer's keyboard on the Frame: in VR apps, Android apps, Steam and the desktop.
@@ -1,10 +1,10 @@
 e7554c6343ee2989b0a273ee6230e65c25bfe6499eefd00de19f5f0fee58754f  ./arm64-v8a/libfp_langpack.so
-98a99cefe93079268d9158b23fa8ad5c7ade8e54c0d31526892635625eb3ef04  ./arm64-v8a/libfp_ovrp.so
+321da502e0f8f46f0880aad39fe6b84bdef88f925164568814cf704a1b31a577  ./arm64-v8a/libfp_ovrp.so
 40defdaddcda53bd2649eb48076fae1622bfc2bfc88e9e03c94fc8b45af2a4f2  ./arm64-v8a/libfp_ovrtrace.so
 7522a7cfb236e48d3442d418c4820cd37760a9627c6bdef80fb0df82df5fd826  ./arm64-v8a/libfp_vk.so
 383054f8b3b41dde76d062c71856cd3163655e50009c08454bc1793f393ead65  ./arm64-v8a/libfpg.so
-06c8a17b37cb1513fdfeba87ece457a02097bb22dd0a3a3a8719fb8fea16b52a  ./arm64-v8a/libframe_xrshim.so
-9f5ba793d1804728394a8fe9e83028e13f1bc939b558892e7beb5c3662317259  ./arm64-v8a/libglshim.so
+8a8f6b1da8952cb3933a5b53558424a5fc56043b2527a16bb6dd62a00d2de01a  ./arm64-v8a/libframe_xrshim.so
+fc559dbe0b87eecc3641256837293260cefb7c2ce7b21d808d10edd2a2dba9fc  ./arm64-v8a/libglshim.so
 cc5b493cadefe76ad13fd096d3f8494a140ba593e0e1692db12d284bc548c1cf  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
 aa4dc0020c77e12d41ef6ce80b23ad90c9cb7e882338eddf2261efe8645cf38d  ./arm64-v8a/libvrapi.so
@@ -0,0 +1,19 @@
+package: com.CortopiaStudios.Graves
+title: GORN2
+status: works
+tested_version: 1.10.1
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-07'
+  known_good_sha256: d8a7949edc90c19902eb89f888ad6a350475387d630991767b3097667ad16d4c
+  app: 0.12.0
+  overport_cli: 1.2.5
+  issue: 88
+source_hint: GORN 2
@@ -0,0 +1,21 @@
+package: com.FourPlayersStudio.Retronika
+title: Retronika
+status: works
+tested_version: 3.2.601
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-07'
+  known_good_sha256: 290bfda3969547d5f1ff621ab5a8be9dd322fc9eee6b243c863576d4ff5b4b81
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261006.6173745'
+  agent: 59
+  issue: 97
+source_hint: Retronika
@@ -4,14 +4,25 @@ tested_version: '1.03'
 source_hint: Sniper Elite VR
 engine: Unity
 xr: VrApi
-status: unsupported
-notes: 'GPU hang (zink: DEVICE LOST) even with MSAA off.'
-details: Legacy VrApi via OVRPlugin.
+status: works
+notes: Plays with controllers that follow the hands (owner's headset test, Quest 1 build 35713).
+details: 'Unity 2019.4 on its built-in Oculus VR (no Oculus XR Plugin). Its legacy frame loop never waited for frames
+  (GPU hang, zink: DEVICE LOST) and Unity reported only Go controllers: frame.unity_oculus_check. Its frame wait then
+  deadlocked at the Init scene (Unity skipped beginning a frame) and the physics-step pose update located the
+  controllers in the past (hands lagged): both fixed in that patch (revision 5), switched on for this game by ovrp_begin_gate and ovrp_hold_physics. Grabbing an object in the tutorial
+  vibrates the controller; OVRPort''s envelope conversion then allocated ~1 GB/s until the memory cap ended the game:
+  haptic_fix. The Quest 1 build has no arraysources_assets.hd, which the game loads on the Frame (it detects a Quest
+  2) and then skips the .sd bundle: textures are missing unless the .sd file is also present under the .hd name in the
+  game''s obb folder.'
 frame:
 - frame.unity_no_msaa
+- frame.unity_oculus_check
+adapter:
+  haptic_fix: 1
+  ovrp_begin_gate: 1
+  ovrp_hold_physics: 1
 pcvr_alternative: Sniper Elite VR (Steam PC VR). Winter Warrior (Quest) works on the Frame.
 verified:
-  date: '2026-09-28'
-  overport_cli: 1.2.3
-  overport_runtime: 3.4.3-23204ea
-  known_good_sha256: e80883eb6945e267a375edf0ffd789268686440819add9d4dee9fdbdf466cbe4
+  date: '2026-10-07'
+updated: '2026-10-07'
+min_app: 0.12.1
@@ -1,20 +1,25 @@
 package: com.StressLevelZero.BONELAB
 title: BONELAB
-status: issues
-notes: Build 1.2068 plays (head tracking and controls work with frame.unity_user_presence); the newer build
-  1.2974 crashes at start (Vulkan), no fix yet.
-details: The game runs (72 fps), but its player body stayed frozen - no head tracking, the controllers stuck to the
+status: works
+notes: Builds 1.2068 and 1.2974 play (owner's headset tests). One recipe serves both builds - 1.2068 needs frame.unity_user_presence (head tracking and controls); 1.2974 also needs
+  frame.slz_vulkan_hooks (72 fps after about 35 s of shader prewarming), which changes nothing on 1.2068.
+details: Both builds - the game runs (72 fps), but its player body stayed frozen - no head tracking, the controllers stuck to the
  model, no buttons - although OpenXR input and OVRPlugin's poses were fine. A few seconds after start (when Unity
  switches XR loaders) OVRPlugin reports the worn headset as not worn (ovrp_GetUserPresent2 -> 0), and BONELAB's
  Marrow rig only follows the player while Unity's HMD device reports UserPresence (OpenControllerRig checks
-  XRHMD.IsUserPresent every frame). frame.unity_user_presence reports the headset as worn. Build 1.2974 crashed
-  earlier in vkCreateInstance from the game's own Vulkan hooks (libSLZQuestNative.so); not retested.
-tested_version: 1.2068.34555
+  XRHMD.IsUserPresent every frame). frame.unity_user_presence reports the headset as worn. Build 1.2974 only - it adds Stress
+  Level Zero's graphics plugin (libSLZQuestNative.so), which hooks Unity's Vulkan start-up (vkCreateInstance/
+  vkCreateDevice) and vkCreateSampler; on the Frame its vkCreateInstance wrapper calls an invalid pointer right after
+  OVRPlugin's pre-init instance is destroyed (a jump to 0, into an unloaded library, or a hang). frame.slz_vulkan_hooks
+  switches its two registrations off, so Unity starts Vulkan itself; the plugin's pipeline cache isn't used.
+tested_version: 1.2974.57485
 engine: Unity
 xr: OpenXR
 frame:
 - frame.unity_user_presence
+- frame.slz_vulkan_hooks
 verified:
-  date: '2026-10-06'
-updated: '2026-10-06'
+  date: '2026-10-08'
+updated: '2026-10-08'
 source_hint: BONELAB
+min_app: 0.12.1
@@ -0,0 +1,22 @@
+package: com.ToastVR.RichiesPlankExperience
+title: Richie's Plank Experience
+status: works
+tested_version: 2.3.585
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-07'
+  known_good_sha256: 7eb1366c2398e554624a5d66aefb0c731c64b1b6944bc1726d9187f123c37fb7
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 59
+  issue: 95
+source_hint: apks
@@ -0,0 +1,23 @@
+package: com.VR_HOT.VR_HOT_Quest
+title: VR HOT Quest
+status: works
+tested_version: 0.8.8.1
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  controller_models: 1
+  haptic_fix: 1
+verified:
+  date: '2026-10-08'
+  known_good_sha256: c321606c536eba1673572a9f44fd9e20d2cb5bd9609d536189e6ad7057b9cd67
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 59
+  issue: 98
+source_hint: VR-HOT-Quest-0.8.8.1
@@ -0,0 +1,25 @@
+package: com.YourCompany.SWP_VR
+title: Star Wars Pinball VR
+tested_version: '1.4'
+source_hint: Star Wars Pinball VR
+engine: Unreal
+xr: VrApi
+status: works
+notes: Plays (owner's headset test); one short audio hiccup seen.
+details: 'Unreal 4.25 (GLES) built against OVRPlugin 1.44. Four Frame problems in a row: Zink crashed on Unreal''s
+  multisampled render-to-texture (fault addr 0x10000 on the RHIThread): frame.unreal_gl_shim, which keeps Unreal''s
+  multiview and draws those passes single-sampled; OVRPort''s OVRPlugin lacks ovrp_GetPTWNear, so Unreal''s Oculus
+  module never started VR (then a null pointer in GetMultiViewSceneColor): frame.unreal_ovrp_entrypoints; the engine''s
+  OpenSSL assembly has unpaired return-address checks the Frame''s CPU enforces (SIGILL on the HttpManager thread):
+  frame.pac_hints. Needs its OBB (main.10765).'
+frame:
+- frame.unreal_gl_shim
+- frame.unreal_ovrp_entrypoints
+- frame.pac_hints
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-08'
+  issue: 83
+updated: '2026-10-08'
+min_app: 0.12.1
@@ -0,0 +1,21 @@
+package: com.characterBank.ruinsmagus
+title: RUINSMAGUS
+status: works
+tested_version: 1.2.3
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-07'
+  known_good_sha256: 230e5625fbdfebb47c4d96aeb87f45270e4e6c79a33c08315c90626ab7465fe5
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261006.6173745'
+  agent: 59
+  issue: 89
+source_hint: RUINSMAGUS
@@ -0,0 +1,22 @@
+package: com.cloudheadgames.pistolwhip
+title: Pistol Whip
+status: works
+notes: 120 HZ
+tested_version: 1.6.0.2
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-08'
+  known_good_sha256: ebd97af54c59d59d473c98492c1bb26ce6059b7e59f27a08acfc5ada23d0b774
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261006.6173745'
+  agent: 59
+  issue: 100
+source_hint: Pistol Whip
@@ -0,0 +1,22 @@
+package: com.curif.AgeOfJoy
+title: AgeOfJoy
+status: works
+tested_version: '1.0'
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+- frame.oculusos
+device:
+- device.text_input_window
+adapter:
+  haptic_fix: 1
+verified:
+  date: '2026-10-08'
+  known_good_sha256: 9780e71e417b86290147c67c83755305801d8957909734c717a519034edefdf9
+  app: 0.12.0
+  overport_cli: 1.2.5
+  frame_build: '20261006.6173745'
+  agent: 59
+  issue: 103
+source_hint: AgeOfJoy 05 rc30
@@ -0,0 +1,18 @@
+package: org.timecrisis.quest
+title: Time Crisis VR (Experimental)
+status: works
+notes: Fully playable at 120hz
+tested_version: 0.8.3
+engine: Other
+xr: OpenXR
+frame:
+- frame.sdl_clipboard
+verified:
+  date: '2026-10-06'
+  known_good_sha256: 4e67411a8e9c0b5fbb19ca7908c4222aa5ad1b2d47a8f4b5018b4fe9c2f5324e
+  app: 0.12.0
+  overport_cli: 1.2.3
+  frame_build: '20261005.6135832'
+  agent: 59
+  issue: 80
+source_hint: TimeCrisisVR-v0.8.3-quest
@@ -18,11 +18,31 @@ signatures:
    severity: fatal
    diagnosis: 32-bit-only APK. The Steam Frame has no AArch32; this cannot run. Use the PC (Rift) version via Revive.
    suggest: []
+  - id: android-too-new
+    pattern: '(NoClassDefFoundError|ClassNotFoundException|NoSuchMethodError)\b.*(Landroid/window/|android\.window\.|(storeStoreFence|loadLoadFence)\(\)V in class Ljava/lang/invoke/VarHandle)'
+    severity: fatal
+    diagnosis: The app calls Android 12/13+ classes (android.window.*, VarHandle fences) that the Frame's Android 11 (API 30) container doesn't have; it needs a newer Android (e.g. minSdk 34 apps). Nothing to patch - it can't run until Valve updates the Frame's Android.
+    suggest: []
+  - id: web-wrapper
+    pattern: '(Creating TwaLauncher for com\.oculus\.browser|NameNotFoundException:? com\.oculus\.browser)'
+    severity: fatal
+    diagnosis: The app is a website in an Android wrapper (Trusted Web Activity) that opens Meta's browser (com.oculus.browser), which the Frame doesn't have, so nothing opens. There's no game to port - open the website (TWALauncherActivity's "Using URL" line) in a browser instead.
+    suggest: []
  - id: unity-render-crash
    pattern: 'CRASH\s*:.*#\d+\s+pc [0-9a-f]+\s+\S*libgallium_dri\.so'
    severity: fatal
    diagnosis: Unity's render thread crashed inside the Frame's GL driver (Mesa/Zink); the picture freezes or stays grey. Known triggers - an OVROverlay copy (try "Unity - skip OVROverlay layers", e.g. The Room VR), MSAA switched on at runtime, a GPU hang (zink DEVICE LOST).
    suggest: [frame.unity_no_overlay_copy, frame.unity_runtime_msaa_off]
+  - id: unreal-msrtt-crash
+    pattern: 'fault addr 0x10000 in tid \d+ \((RHIThread|RenderThread)'
+    severity: fatal
+    diagnosis: The game's render thread jumped to address 0x10000 inside the Frame's GL driver (Mesa/Zink) a few seconds after start. Zink looks up a render-pass cache slot past its end when a game renders through multisampled render-to-texture (Unreal's mobile MSAA, e.g. Star Wars Pinball VR). Load the GL shim, which hides that extension.
+    suggest: [frame.unreal_gl_shim, frame.unity_gl_shim]
+  - id: pac-unpaired
+    pattern: 'ILL_ILLOPN\), fault addr 0x[0-9a-f]+ \(\*pc=0xd50323bf\)'
+    severity: fatal
+    diagnosis: The game crashed on a return-address check (autiasp) its code never signed. The Quest's CPU ignores these checks, the Steam Frame's enforces them; some OpenSSL assembly in game engines has such unpaired checks (e.g. Star Wars Pinball VR on its first network connection, thread HttpManager).
+    suggest: [frame.pac_hints]
  - id: swapchain-rect-invalid
    pattern: 'xrEndFrame failed -25\b'
    severity: fatal
@@ -84,6 +104,12 @@ signatures:
    diagnosis: Unity didn't start its Oculus VR device (older Unity checks for Meta's system apps first), so the game
      runs as a hidden 2D app.
    suggest: [frame.unity_oculus_check]
+  - id: unity-frame-not-begun
+    pattern: 'frame loop shim: frame \d+: the last waited frame wasn.t begun'
+    severity: info
+    diagnosis: Unity skipped beginning a frame (typically while it activates a scene); FramePort's frame wait didn't
+      wait for that frame instead of blocking the game. A few at each scene load are normal.
+    suggest: []
  - id: sdl-no-clipboard
    pattern: 'ClipboardManager\.addPrimaryClipChangedListener|SDLClipboardHandler\.<init>'
    severity: fatal
@@ -219,6 +245,12 @@ signatures:
      voice chat a few seconds after the logo).
    suggest: [frame.ovr_microphone]
    supersedes: [native-crash]
+  - id: slz-vulkan-hook-crash
+    pattern: 'SLZ Graphics plugin loading![\s\S]{0,20000}?E CRASH   : .*pc  0000000000000000'
+    severity: fatal
+    diagnosis: Stress Level Zero's graphics plugin (libSLZQuestNative.so) hooks Unity's Vulkan start-up and calls an invalid function there on the Frame (e.g. BONELAB 1.2974); the game crashes or hangs before its first frame.
+    suggest: [frame.slz_vulkan_hooks]
+    supersedes: [java-crash, native-crash]
  - id: native-crash
    pattern: 'Fatal signal (\d+) \(SIG[A-Z]+\)'
    severity: fatal
@@ -35,6 +35,11 @@
 ## Extending
 - **New fix**: `patches/frame/<name>.py` with a `Patch` subclass (`detect`, `apply`, optional `validate`), plus a
  signature in `catalog/triage.yaml` and a PLAYBOOK row. Stages: `overport` | `apk` | `install`.
+- **Upstream fixed a bug we work around**: register an `UpstreamFix` (`patches/upstream.py`) in the workaround's
+  module: a probe that finds the fix in OVRPort's output (True / False / None = can't tell). Each build runs the probes
+  on the converted APK and leaves out the workarounds whose fix is there (log "not needed: …", `build.superseded`,
+  left out of settings.conf at install; game page and `frameport show` say so). The recipe keeps asking for the fix,
+  so builds made with an older runtime keep the workaround. `FRAMEPORT_KEEP_WORKAROUNDS=1` turns it off.
 - **New heuristic**: put it in the patch's `detect()` (and `applies()` for visibility), with the evidence in the
  reason text; check `scripts/eval_heuristics.py` still reproduces the catalog and add a test in
  `tests/test_heuristics.py`.
@@ -28,6 +28,23 @@
  work on Android 11: `policy_control` is gone, `cmd statusbar send-disable-flag home recents` has no `back` and
  moves the back button onto the app's controls, the `sysui_nav_bar` layout and disabling SystemUI had no effect.

+## Where FramePort keeps games (internal storage, microSD)
+- Every game has an **anchor** on internal storage: `~/Applications/quest-frame/<pkg>/` with `launch.sh`,
+  `deployment.json`, `artwork/` and `plays.log`. Steam's shortcut points at the anchor's `launch.sh`, so it never
+  changes when the files move.
+- The game's files (`lepton-app/`, `lepton-data/` = saves, `lepton-shaders/`, `settings.conf`, `launch.log`; PC VR:
+  `game/`, `revive/`, `compatdata/` = Proton prefix; Linux: `app/`) live in `deployment.json["base"]`: the anchor
+  itself on internal storage, or `<mount>/FramePort/<pkg>` on another drive (GitHub #90, agent v63).
+- SteamOS mounts removable drives (microSD) under `/run/media/<user>/<label or uuid>`; the agent's `drives` reads
+  `/proc/mounts` (plus the drives of Steam library folders) and refuses vfat/exfat/ntfs (Lepton's data and Proton
+  prefixes need Unix owners, permissions and symlinks) and read-only mounts. A drive that isn't mounted is an error for
+  new installs (never a silent fallback to internal storage); `list_installed` marks games on it `drive_missing` and
+  their launchers stop with "storage not mounted?".
+- `move` copies with `cp -a` inside `podman unshare` (files Lepton's containers own belong to subordinate user ids),
+  compares file count + bytes, retargets absolute symlinks into the old folder (the LibOVRRT → Revive redirect), points
+  `launch.sh` at the new folder and only then deletes the old copy; on the same filesystem it renames instead.
+  Moving a game whose Lepton data holds absolute paths, or a PC VR prefix, is not yet verified on the device.
+
 ## OpenXR runtime (as seen by games through overport's loader)
 - Instance extensions present include KHR_android_create_instance (must be enabled; the adapter adds it),
  KHR_vulkan_enable(2), KHR_opengl_es_enable, KHR_composition_layer_depth, FB_display_refresh_rate, EXT_hand_tracking
@@ -120,6 +137,24 @@
 - Processes started from Steam (Konsole, SSH sessions?) share steam.service's cgroup: use `systemd-run --user`.
 - SSH: `sshd` must be enabled (`sudo systemctl enable --now sshd`), which needs a user password (`passwd`).
 - mDNS: avahi-daemon runs by default; hostname `frame` → `frame.local`.
+- Desktop Mode menu entries (GitHub #84, agent v63): Linux apps get `~/.local/share/applications/frameport-<slug>.desktop`
+  (+ an executable copy in `~/Desktop` when that folder exists; Plasma starts executable `.desktop` files there
+  without a trust prompt), `Exec=env FRAMEPORT_DESKTOP=1 "<anchor>/launch.sh"`, marked `X-FramePort-Package=<pkg>`.
+  Plasma's launcher exits right after starting the program, so with `FRAMEPORT_DESKTOP=1` the Linux launcher skips
+  its "Steam parent gone → end the app" watchdog and keeps the desktop's DISPLAY/WAYLAND_DISPLAY instead of taking
+  gamescope's from Steam. Not yet tried from the Frame's Desktop Mode.
+- Linux apps' own icons (GitHub #99, agent v64): finalize_linux (and every refresh of the menu entries) copies the
+  app's icon to `<anchor>/artwork/app-icon.{png,svg}`: an AppImage's `squashfs-root/.DirIcon` (usually a symlink),
+  else the `Icon=` of its top-level `.desktop` file (a folder app: the first `.desktop` within 3 levels) looked up
+  next to it, in `(usr/)share/icons/hicolor/*/apps/` and `(usr/)share/pixmaps/`; the biggest PNG ≥128 px, else an
+  SVG, else the biggest PNG. Symlinks are resolved and must stay inside the app folder; absolute and `../` names
+  are ignored. Precedence for the menu entry's `Icon=` and the Steam shortcut's icon: the user's chosen/store icon
+  (`artwork/.icon-source` = `custom`, written by the PC with every art upload) > the app's own (Steam: PNG only) >
+  FramePort's placeholder (`artwork/icon.*`). `StartupWMClass=` is copied from the app's `.desktop` file (Plasma's
+  task bar matches the window to the entry). A PNG ≤1 MiB goes back to the PC (finalize result `app_icon.png`,
+  base64) and becomes the library's icon when the game has none and nothing was picked (`.app-icon` marker = its
+  sha256, no `.picked`); folder apps get it on the PC at add time (`analysis/linux.find_icon`). Not yet seen in
+  Desktop Mode on the device.

 ## Video of the headset view (surveyed 2026-10-05; used by the Live view tab)
 - `steamvr-v4l2cam.service` (user unit, part of gamescope-session.target, `Restart=always`) runs SteamVR's
@@ -8,6 +8,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 |---|---|---|---|
 | 4XVR Video Player | Quest | ✅ Works |  |
 | Accounting+ | Quest | ✅ Works |  |
+| AgeOfJoy | Quest | ✅ Works |  |
 | AllInOneSports | Quest | ✅ Works |  |
 | Asgard's Wrath 2 | Quest | ✅ Works |  |
 | BAM | Quest | ✅ Works |  |
@@ -20,6 +21,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Beat Saber (co-existence build) | Quest | ✅ Works |  |
 | Blade & Sorcery: Nomad | Quest | ✅ Works |  |
 | BodyCombat | Quest | ✅ Works |  |
+| BONELAB | Quest | ✅ Works |  |
 | Carve Snowboarding | Quest | ✅ Works |  |
 | Cook-Out | Quest | ✅ Works |  |
 | Creed | Quest | ✅ Works |  |
@@ -27,6 +29,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Dinosaur Island | Quest | ✅ Works |  |
 | Espire 2 | Quest | ✅ Works |  |
 | Genotype | Quest | ✅ Works |  |
+| GORN2 | Quest | ✅ Works |  |
 | H.U.N.T | Quest | ✅ Works |  |
 | I Am Cat | Quest | ✅ Works |  |
 | I Am Monkey | Quest | ✅ Works |  |
@@ -48,13 +51,19 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | NOPE CHALLENGE | Quest | ✅ Works |  |
 | palazzo_santacruz | Quest | ✅ Works |  |
 | Path of the Warrior | Quest | ✅ Works |  |
+| Pistol Whip | Quest | ✅ Works |  |
 | PowerWash Simulator VR | Quest | ✅ Works |  |
 | QuestCraft | Quest | ✅ Works |  |
+| Retronika | Quest | ✅ Works |  |
+| Richie's Plank Experience | Quest | ✅ Works |  |
 | Rick and Morty: Virtual Rick-ality | PC VR | ✅ Works |  |
 | Riven | Quest | ✅ Works |  |
 | Robo Recall | Quest | ✅ Works |  |
+| RUINSMAGUS | Quest | ✅ Works |  |
+| Sniper Elite VR | Quest | ✅ Works |  |
 | Sniper Elite VR: Winter Warrior | Quest | ✅ Works |  |
 | Space Pirate Trainer Quest | Quest | ✅ Works |  |
+| Star Wars Pinball VR | Quest | ✅ Works |  |
 | Stremio | Quest | ✅ Works |  |
 | SUPERHOT VR | PC VR | ✅ Works |  |
 | SUPERHOT VR | Quest | ✅ Works |  |
@@ -62,15 +71,17 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | The Boys VR | Quest | ✅ Works |  |
 | The Climb 2 | Quest | ✅ Works |  |
 | The Room VR | Quest | ✅ Works |  |
+| Time Crisis VR (Experimental) | Quest | ✅ Works |  |
 | Toy Master | Quest | ✅ Works |  |
 | Under Cover | Quest | ✅ Works |  |
+| VR HOT Quest | Quest | ✅ Works |  |
 | VR4 | Quest | ✅ Works |  |
 | Wallace & Gromit in The Grand Getaway | Quest | ✅ Works |  |
 | Waltz of the Wizard: Extended Edition | Quest | ✅ Works |  |
 | Wander | Quest | ✅ Works |  |
 | 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. |
-| BONELAB | Quest | ⚠️ Works with issues | Build 1.2068 plays (head tracking and controls work with frame.unity_user_presence); the newer build 1.2974 crashes at start (Vulkan), no fix yet. |
+| Doom3Quest | Quest | ⚠️ Works with issues | PDA shows black screen. |
 | Myst | Quest | ⚠️ Works with issues | Minor graphical glitches on some objects. |
 | Phantom: Covert Ops | Quest | ⚠️ Works with issues | DLC/store button crashes (no Meta store). |
 | Pinball FX VR | Quest | ⚠️ Works with issues | Plays; mixed reality mode not working yet. |
@@ -84,5 +95,4 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Journey of the Gods | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |
 | Roblox | Quest | ❌ Doesn't run | Crashes on its first VR frame on the Frame. |
 | Shadow Point | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |
-| Sniper Elite VR | Quest | ❌ Doesn't run | GPU hang (zink: DEVICE LOST) even with MSAA off. |
 | Sports Scramble (Santa Cruz) | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |
@@ -1,5 +1,10 @@
 # Installing FramePort

+▶ **[Watch the install tutorial](media/frameport-install.mp4)** (about 90 seconds, MP4; also attached to every
+release as `FramePort-install.mp4`): from the download to the first game on the Frame.
+
+[![The install tutorial](media/frameport-install.jpg)](media/frameport-install.mp4)
+
 Download the archive for your computer from the [latest release](https://github.com/spoopyghosty0/frameport/releases/latest)
 and extract it anywhere. No installer or admin rights are needed. On first start FramePort downloads its Java
 runtime, the OVRPort CLI and apksigner into its data folder (Settings → Tools shows them).
@@ -85,6 +90,11 @@ which would end Desktop Mode). This is new: please report anything odd with **Re
 - If the Frame goes to sleep, turns off or leaves the Wi-Fi, the queue **waits** and continues once it's back; uploads
  pick up where they stopped. While installs run, FramePort keeps the Frame from going to sleep. Before a large batch
  it checks the Frame has enough free space.
+- **microSD card / other drives:** the **Steam Frame** page's **Storage** section lists the Frame's drives and sets
+  where new games go (**Install new games to**). Games go into a `FramePort` folder on the card. To move a game that's
+  installed already, right-click it → **Move to…** (the game must be closed; saves, settings and the Steam entry stay).
+  A game on the card only starts while the card is inserted (FramePort then says "SD Card not inserted"). Cards
+  formatted as FAT, exFAT or NTFS can't hold games: format the card in SteamOS first.
 - Your own game files are never changed. The converted copy is temporary: it's removed once the game is on the Frame
  (Settings → Installing: keep them, or remove all now).
 - **Game settings…** (game menu or the Steam Frame page): sharpness, refresh rate, controllers, menus, 360° video and
@@ -218,6 +228,9 @@ work like for other games.
 - The app must bring the libraries SteamOS doesn't have (checked for arm64 builds; x86_64 builds use FEX's x86
  system, which has glibc and Mesa, and aren't checked ahead). If some are missing, the install reports them and the game
  page lists them: look for a build that includes them.
+- **Desktop Mode:** Linux apps also appear in Desktop Mode's application menu and as an icon on its desktop. Some
+  apps work better there, with a mouse and keyboard, than in Gaming Mode (where Steam Input turns the controllers into
+  a gamepad). Switch it off per app on the game page (**Desktop Mode**).
 - From the command line: `frameport add-linux <AppImage, folder or archive> [--exe <program>]`.

 ## Files on the Frame (videos, documents, mods, saves)
@@ -262,6 +275,7 @@ and `frameport <command> --help` describe every option. The main ones:
 | `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 |
@@ -13,6 +13,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 ## Startup failures (visible in launch.log)
 | Symptom | Cause | Fix |
 |---|---|---|
+| A launch test suggests a fix (e.g. triage `sdl-no-clipboard` → `frame.sdl_clipboard`) but the game page doesn't show it / lists it as not applicable; or a game added long ago lacks warnings newer ones get (Android version, web wrapper, missing OBB) (GitHub #104, Dramatic Shape) | the library entry was analysed by an older FramePort: the analysis field the patch reads (`sdl_java`, `min_sdk`, `web_wrapper`, `expects_obb`, …) is missing, so `applies()` is false | entries whose `analysis.extra.analysis_version` is below `detect.ANALYSIS_VERSION` are analysed again at the GUI's start (background) and before a build (`pipeline.refresh_analyses`); by hand: game menu → "Analyze again", then Update on Frame. An unreadable APK is marked `analysis_failed` (retried after the next version bump). Adding an analysis field: bump `ANALYSIS_VERSION` |
 | One eye (usually the right) shimmers or jitters in the 3D view while menus and panels look steady; pacing is clean (GitHub #69, e.g. RTCWQuest, Moss) | Valve's eye-tracked foveation layer (`VALVE_fdm_injection`) moves its low-density regions with each eye's gaze, and the right eye's gaze filter restarts often (`CEyePoseUKF R: Large dt … Bootstrapped` in `~/.local/share/Steam/logs/eyetracking.txt`) | Customize → "Eye-tracked foveation (Valve)" (`device.foveation`): **Fixed** (`FDM_DEBUG=disable_offsets`, keeps the GPU saving) or **Off** (`VK_INSTANCE_LAYERS=""`); catalog field `foveation:` |
 | A Unity OpenXR game closes right after the OpenXR instance is created: `F VrApiLoader: vrapi_SetPropertyInt was called before vrapi_Initialize()!`, SIGABRT on UnityMain (GitHub #62, Jurassic World Aftermath) | the APK still ships Meta's VrApi loader; OVRPlugin (1.89, on OpenXR) calls it without starting VrApi and Meta's loader aborts. The VrApi bridge can't replace it (39 of the loader's 114 functions: OVRPlugin wouldn't link) | `frame.vrapi_stub` (same exports, each returns 0); triage `vrapi-before-init` |
 | A VrApi game exits at once: `UnsatisfiedLinkError … dlopen failed: cannot locate symbol "vrapi_PollEvent"` (GitHub #57, BlazeRush) | the engine imports a VrApi function the VrApi bridge didn't implement | the bridge has `vrapi_PollEvent`, `RecenterPose`, `SetDisplayRefreshRate`, `GetSystemPropertyFloatArray` (rebuild the game); the static check "VrApi functions resolvable" names any other missing one; triage `vrapi-symbol-missing` |
@@ -21,7 +22,11 @@ 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 |
 | Controller vibrations much stronger than on a Quest (The Boys VR, Jurassic World, BONELAB, …) | OVRPlugin games send amplitude envelopes; `haptic_fix` turned each into one vibration at the envelope's *peak* for its whole duration (a short fading pulse became a long full-strength buzz) | `haptic_fix` now uses the envelope's RMS; Game settings → "Vibration strength" (`haptic_scale`, 0-1) scales every vibration in FrameBridge; launch.log shows the first requests (`haptic: …`). OVRPlugin stops a vibration with amplitude 0 (2 s duration): FrameBridge turns that into xrStopHapticFeedback (without it the last buzz ran its full 2 s) |
+| Play or a launch test fails at once: `Game files missing at <path> (storage not mounted?)` in launch.log, or "… files are on a drive that isn't inserted" (GitHub #90) | the game was installed or moved to a microSD card (`<mount>/FramePort/<pkg>`) that isn't inserted or mounted now | insert the card; or move the game back (game menu → Move to…, `frameport frame move <pkg> --to internal`) once the card is back. `frameport frame drives` shows what the agent sees (exFAT/NTFS cards are refused: format in SteamOS) |
+| A Linux app started from Desktop Mode's menu closes after ~2 s, or opens on the wrong display (GitHub #84) | its launcher predates agent v63: the "Steam parent gone" watchdog ended it when Plasma's launcher exited, and it took gamescope's DISPLAY from Steam | connect FramePort once (agent v63's `upgrade_launchers` adds the `FRAMEPORT_DESKTOP` checks; the menu entry runs `env FRAMEPORT_DESKTOP=1 <anchor>/launch.sh`). Game Mode controller problems in such apps are Steam Input's (a separate issue) |
+| A Linux app (AppImage) shows no/FramePort's placeholder icon in Desktop Mode or Steam (GitHub #99) | before agent v64 only FramePort's art set's icon was used, and a lone AppImage has no store art | connect FramePort once (agent v64 copies the app's `.DirIcon` / `.desktop` `Icon=` to `<anchor>/artwork/app-icon.*` and refreshes the menu entry); reinstall to also get it into the library + Steam shortcut. Still the placeholder: check `<base>/app/squashfs-root/.DirIcon` and the `.desktop` file's `Icon=` (an icon outside the app folder or only an XPM isn't used); a chosen icon (`artwork/.icon-source` = `custom`) always wins |
 | Every game suddenly fails to start: `crun: create keyring …: Disk quota exceeded`, `is not a running context` | rootless podman leaked a kernel keyring per launch; 200-key quota exhausted | `keyring = false` in `~/.config/containers/containers.conf` (FramePort agent does it), then reboot the Frame once |
 | A Unity app's text field shows a caret for a moment and loses focus; no keyboard appears (e.g. Stremio VR login) | Unity's TMP_InputField/InputField wait for Android's on-screen keyboard and close themselves without one (Lepton has none); headless VR apps also have no focused Android window, so no key press reaches them | `frame.unity_text_input` (Cpp2IL finds `TouchScreenKeyboardShouldBeUsed`/`isKeyboardUsingEvents`, rewritten to false/true) + `device.text_input_window` (lepton-show-flatscreen: Steam's keyboard and Type on Frame work) |
 | Play gives Steam's "Game configuration unavailable"; Steam's console_log: `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` | this Frame's Steam never loaded FramePort's shortcuts.vdf entry (it treats the id as a store app); cause unknown (GitHub #21/#30) | automatic since agent v43: Play registers the game through Steam's devkit interface ("Devkit Game: …", `devkit_register`) and starts that; uninstall removes it. 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) |
@@ -42,14 +47,19 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Uploads to the Frame are slow (~15 MB/s) | PC and Frame both on Wi-Fi through the home router | Connect the PC to the Frame's own hotspot (or a USB cable): FramePort uses the direct link automatically (~80-100 MB/s); job log line "Transfer link" |
 | PC VR game exits right away: `Unhandled Exception: 0xc06d007e` (after `FOnlineSubsystemOculus::InitWithWindowsPlatform`) | Delay-loaded `LibOVRPlatform64_1.dll` (Oculus Platform SDK, installed with the Oculus app) is missing | None on the Frame (entitlement check; FramePort doesn't replace it). PC mode with the Oculus app |
 | Unreal PC VR game opens the crash reporter instead of closing | UE starts CrashReportClient.exe on a crash | `pcvr.no_crash_reporter` (default for Unreal Rift games): `-nocrashreports` + CrashReportClient.exe renamed `.disabled` in the Frame copy |
+| A backup's game was added without its data (library `data_dir` null, `data_bytes` 0) although the folder has .obb files | The OBBs sit in a layout the scan didn't know: `<game>/obb/<package>/`, `Android/obb/<package>/`, or SideQuest-style `<game>/apk/x.apk` + `<game>/obb/<package>/` | `sources/quest_dump.find_data_dir` finds a `<package>` folder with .obb files ≤3 levels below the APK's folder or ≤2 below its parent (skipping neighbouring folders with APKs: other games); an `apk`/`apks` folder counts as part of its game folder. Add the folder again (Analyze again doesn't look for data) |
+| Game hangs at start / never loads although its .obb files are right there: next to the APK, in an `obb` folder beside an `apk` folder inside a `<package>` folder, or a SideQuest backup (`<timestamp>_<versionCode>.apk`) (GitHub #85, #91) | No folder named after the package, so the folder-layout checks found nothing and no OBB was uploaded | `quest_dump.find_data` then looks for the files by name, `(main\|patch).<versionCode>.<package>.obb` (any case), in the APK's folder, its parent and up to 3 levels below each (folders with their own APKs are other games); prefers the folder and files of the APK's own versionCode, else the newest older, else any version. When that folder also holds other things (the APK itself, other games' OBBs), the library entry gets `data_files` and only those files are uploaded, counted and deleted with the game. Add the folder again |
+| Unreal game: `JNI_OnLoad` (OVRPlugin), then silence: no OpenXR instance, no crash, no frames (GitHub #85 TRIANGLE STRATEGY; launch-test finding `missing-obb`) | Installed without its OBB: the manifest says `com.epicgames.ue4.GameActivity.bHasOBBFiles` = true (UE5: `com.epicgames.unreal.…`) but the library has no data folder (`data_dir` null, `data_bytes` 0) | Put the .obb files in a `<package>` (or `obb/`) folder next to the APK, add the folder again, reinstall. Analysis `extra.expects_obb`; the game page, the install question and `frameport scan`/`install` warn; launch tests that sent no frames get the `missing-obb` finding from the library (the game logs nothing). Unity split-binary builds count too (`extra.unity_split`, `analysis/unity_split.py`): an XR-plugin build (Oculus XR Plugin / Unity OpenXR library) without `assets/bin/Data/UnitySubsystems/` in the APK, or BuildSettings listing more scenes than the APK has `levelN` files (globalgamemanagers loose or read from the head of data.unity3d); exact on the 48 Unity APKs of the dumps (13 split, 17 full games; OBBs of full builds are asset bundles or sound banks) |
 | `INSTALL_FAILED_NO_MATCHING_ABIS` | 32-bit-only APK; Frame has no AArch32 | None. PC/Rift version via Revive |
+| Crash at start: `NoClassDefFoundError: … Landroid/window/OnBackInvokedCallback;` or `NoSuchMethodError: No static method storeStoreFence()V in class Ljava/lang/invoke/VarHandle;` (GitHub #71/#72, triage `android-too-new`) | The APK needs Android 13+ (minSdk 33 or more; those were 34) and calls its classes at start; Lepton's Android is 11 (API 30). OVRPort lowers minSdk to 29, so it installs anyway. minSdk ≤ 32 (Quest's Android 12L) is fine: 16 working catalog games declare 32 | None (analysis `extra.min_sdk` > 32 → a warning on the game page/CLI and in the recipe notes; never unsupported from the manifest alone, the launch test's triage decides). Waits for Valve to update Lepton's Android |
+| Nothing opens; `TWALauncherActivity: Using URL from Manifest (https://…)`, `Creating TwaLauncher for com.oculus.browser`, `NameNotFoundException: com.oculus.browser` (GitHub #86 Mahjong Table VR, triage `web-wrapper`) | The APK is a Trusted Web Activity (Bubblewrap / Meta's PWA packaging): a website that opens in Meta's browser, which Lepton doesn't have | None: open the URL in a browser. Analysis `extra.web_wrapper` (manifest meta-data `android.support.customtabs.trusted.DEFAULT_URL`, resolved through resources.arsc, or androidbrowserhelper's LauncherActivity) → a warning with the URL (not unsupported: the manifest alone never decides) |
 | `UnsatisfiedLinkError` / `cannot locate symbol "ovr_…"` | overport's platform loader lacks Meta platform functions | `frame.ovrstubs` (automatic, generated stubs) |
 | missing `ovrMessageType_ToString` | same, but the game needs a real string | `frame.ovrplatformcompat` (automatic) |
 | The game stays in its built-in language or waits at start although its OBB / files hold language packs (`<tag>.lang`, e.g. `de.lang`) | overport's platform loader answers `ovr_LanguagePack_GetCurrent/SetCurrent` with request id 0, so the game never gets the pack's path | `frame.langpacks` (opt-in, experimental, shown for games whose data has `*.lang`; `native/langpack`, build it with `python native/build.py --only langpack`). Default pack: the one the game applies, else env `FRAMEPORT_LANGPACK=<tag>`, else the only pack; search path override `FRAMEPORT_LANGPACK_DIRS`. Unreal games (Deadpool VR) grey out a pack whose asset `Metadata` differs from the game's version string: the patch writes the APK's versionName as Metadata (env `FRAMEPORT_LANGPACK_META` overrides) and reports the pack under the `/storage/emulated/0/Android/obb/<pkg>/` spelling of its path; with `/sdcard/…` the text switched but the dialogue stayed silent (verified in the headset with Deadpool VR) |
 | `ClassNotFoundException com.oculus.os.AnalyticsEvent` → abort | Quest telemetry lookup in Meta XR Audio (Unreal build) or native code | `frame.metaxr_telemetry` + `frame.oculusos` (automatic) |
 | `JNI DETECTED ERROR`, `GetStringUTFChars … NULL` | CheckJNI is on because overport marks the app debuggable | `frame.nodebug` |
 | Unreal game quits a few seconds after start (`System.exit`) | ForceQuit after a failed Quest platform check | alternate build with `patch_remove_unreal_force_quit` (`use_alt`) |
-| Unreal game crashes a few seconds after the logo with no backtrace (Unreal's own signal handler hides it: logcat-crash.log empty, Zygote `exited due to signal 11`); the crashing thread is `GameThread`, pc in `libaaudio.so`, lr `libovrplatformloader.so (ovr_Microphone_GetOutputBufferMaxSize+0x10)`; the last platform call is `ovr_Microphone_Create` (e.g. The Walking Dead: Saints & Sinners Ch. 2) | OVRPort's platform loader opens the microphone's AAudio stream only in `ovr_Microphone_Start`, but `GetOutputBufferMaxSize` reads that stream unchecked; Unreal's Oculus voice asks for the size right after `Create` | `frame.ovr_microphone` (NULL check rewritten in place; size 0 until the microphone starts) |
+| Unreal game crashes a few seconds after the logo with no backtrace (Unreal's own signal handler hides it: logcat-crash.log empty, Zygote `exited due to signal 11`); the crashing thread is `GameThread`, pc in `libaaudio.so`, lr `libovrplatformloader.so (ovr_Microphone_GetOutputBufferMaxSize+0x10)`; the last platform call is `ovr_Microphone_Create` (e.g. The Walking Dead: Saints & Sinners Ch. 2) | OVRPort's platform loader opens the microphone's AAudio stream only in `ovr_Microphone_Start`, but `GetOutputBufferMaxSize` reads that stream unchecked; Unreal's Oculus voice asks for the size right after `Create` | `frame.ovr_microphone` (NULL check rewritten in place; size 0 until the microphone starts). OVRPort runtime 3.4.3-aa54c3f has the check itself: builds made with it leave the patch out (log "not needed: frame.ovr_microphone", `patches/upstream.py`) |
 | `xrCreateSwapchain` -26 / format unsupported (GLES) | Frame takes only sRGB formats, no MSAA | adapter `swapchain_fix` (default on) |
 | Frames rejected, "Waiting…" forever | a layer uses a failed swapchain or an extension that isn't enabled (e.g. equirect2) | adapter `layer_fix` (default on) |
 | `xrConvert…TimeKHR` FUNCTION_UNSUPPORTED spam; VrApi bridge stalls before recenter | runtime lacks timespec conversion | current adapter emulates it |
@@ -69,8 +79,13 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | 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 |
 | Game (Unity, GLES) freezes, `zink: DEVICE LOST` | multisampled render-to-texture hangs the GPU | `frame.unity_no_msaa`; if it persists: unfixable → PC version |
+| Unreal GLES game crashes ~3 s after start: `Fatal signal 11 … fault addr 0x10000 in tid … (RHIThread)`, `#01 … libgallium_dri.so` (GitHub #83 Star Wars Pinball VR, triage `unreal-msrtt-crash`) | Unreal's mobile MSAA renders through multisampled render-to-texture; Zink's `find_rp_state` then indexes `rendering_state_cache[6]` one past its end (sample count ≥ 32) and calls a junk hash function (0x10000). Mesa bug (no bounds check) | `frame.unreal_gl_shim` (GL shim with `gl_hide_msrtt`, multiview kept for Unreal: Unreal 4.25 only enables multiview with GL_OVR_multiview, GL_OVR_multiview2 **and** GL_OVR_multiview_multisampled_render_to_texture, so the shim keeps the last one visible for Unreal and maps glFramebufferTextureMultisampleMultiviewOVR to the single-sampled glFramebufferTextureMultiviewOVR; log `multiview multisampled render-to-texture (N samples) drawn single-sampled`) |
+| Crash with `SIGILL (ILL_ILLOPN)` and `*pc=0xd50323bf` (autiasp), e.g. on Unreal's HttpManager thread (GitHub #83 Star Wars Pinball VR, triage `pac-unpaired`) | The engine's OpenSSL ARMv8 assembly has autiasp without a matching paciasp (libUE4.so: 38 paciasp, 40 autiasp; Poly1305 NEON). Quest CPUs treat PAC hints as NOPs, the Frame's CPU checks them | `frame.pac_hints`: in a library with unpaired counts every paciasp/autiasp becomes a NOP (in place) |
+| Unreal game (OVRPlugin) never starts VR: launch.log has `OVRPlugin: JNI_OnLoad` but never `CompositorOpenXR::PreInitialize`, no OpenXR session, then a crash a few seconds in (e.g. Star Wars Pinball VR, UE 4.25: null pointer in `FSceneRenderer::GetMultiViewSceneColor`, GitHub #83) | Unreal's Oculus module looks up every `ovrp_*` function of the OVRPlugin it was built against (`InitializeOculusPluginWrapper`, all ANDed); OVRPort's OpenXR OVRPlugin lacks a few old ones (UE 4.25 / OVRPlugin 1.44: `ovrp_GetPTWNear`), so the wrapper fails and OculusHMD is never pre-initialised | `frame.unreal_ovrp_entrypoints` (suggested when analysis `unreal_ovrp_lookups` name functions the shipped OVRPlugin lacks): generated `libfp_ovrpstubs.so` (DT_NEEDED of libOVRPlugin.so; dlsym on the plugin's handle searches its dependencies) with a stand-in per missing name returning ovrpFailure (-1000); build note lists the names |
 | Only the Android home screen shows; the log has Unity's VR device as `None` (e.g. Accounting+, Unity 2017) | Unity 2017–2018 built-in Oculus support starts VR only when `com.oculus.systemactivities` is installed; Lepton has no Meta system apps, so Unity falls back to non-VR | `frame.unity_oculus_check`: that package name in libunity.so → `android`, plus `native/ovrpshim` (libfp_ovrp.so): Unity 2017's legacy frame loop (`ovrp_Update2`/`ovrp_BeginFrame`) never calls `ovrp_WaitToBeginFrame`, so without the shim no `xrWaitFrame` happens, `CompositorOpenXR::Update … outside of frame bounds` floods the log and the dashboard freezes. With it: log `ovrp frame loop shim: waited for frame N`, ~71 fps. Accounting+ then stops at "press any button" although its OVRInput gets clean input (`INPUT_PROBE` in the patch logs connected controllers/buttons/input focus per call) — unresolved |
 | Black flat window, then a GPU hang: kernel `hangcheck detected gpu lockup` (offending task the game), `zink: DEVICE LOST`, Unity render-thread crash; `outside of frame bounds` thousands of times a second (e.g. BattleSisters, Unity 2019.4) | Unity 2019 on its built-in VR (no `libOculusXRPlugin.so`) uses the same legacy frame loop as Unity 2017: no `xrWaitFrame`, the render thread floods the GPU | `frame.unity_oculus_check` adds the ovrpshim frame wait for these too (revision 2) |
+| Unity built-in VR game (with `frame.unity_oculus_check`) freezes at a scene switch: the log stops after `Boot: Activating Scene: …`, the process stays alive, every thread sleeps (e.g. Sniper Elite VR, Unity 2019.4) | The shim's `xrWaitFrame` blocks until the previously waited frame is begun; Unity skipped beginning it at the scene switch and its render thread then waited for the main thread (gdb: UnityMain in vrclient `CSxrSession::StartNextFrame` ← `ovrp_WaitToBeginFrame` ← `fpov_Update2`). OVRPlugin also only begins the frame index it waited for | `frame.unity_oculus_check` revision 5: libunity.so's `ovrp_BeginFrame`/`ovrp_EndFrame` go through the shim, which waits ≤ 50 ms for the last waited frame to begin, else skips the wait (log `the last waited frame wasn't begun`), and gives a begin/end of another index the waited one |
+| Unity built-in VR game: the hands/weapons trail the controllers by centimetres when moving (headset fine, 72 fps), e.g. Sniper Elite VR | Unity's physics-step `ovrp_Update2` (prediction 0) makes OVRPlugin locate the nodes at the monotonic clock's "now", the XrTime base on a Quest but 0.05–0.9 s behind the Frame's XrTime; the runtime extrapolates backwards and the render-step reads after it get those poses too. A larger prediction is capped by OVRPlugin (~0.07 s) | `frame.unity_oculus_check` revision 5 holds the physics-step update back: both steps read the render update's display-time poses |
 | Unreal game stuck on a loading image after the intro, frames keep coming (72 fps), no crash (e.g. Vader Immortal) | suspect: a Meta Platform SDK request no message ever answers | diagnostics: `frame.ovr_trace` (opt-in) logs every `ovr_*` call, the answers `ovr_PopMessage` returns and every 10 s the unanswered requests (`fp_ovrtrace` in launch.log). Never fake an entitlement answer |
 | Own-engine game crashes in `libVkLayer_fossilize.so` (Fossilize's recording thread, e.g. Roblox) | same as Deadpool VR: uninitialised pointers in what Fossilize records | `frame.vk_sanitize` now also covers own-engine libraries that load `libvulkan.so` by name |
 | Crash right after the game gets focus, in `vrclient.so … UpdateActionStateInternal` / `sxr_xrSyncActions` (e.g. Myst) | a race in the Frame runtime's input code on the first sync after focus (not every launch) | adapter `sync_guard` (input syncs one at a time with event polling, paused 250 ms after FOCUSED) |
@@ -105,7 +120,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | 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) |
 | Minor glitches on some objects (Myst, Unreal Vulkan) | unknown; not application space warp (turning it off changed nothing and ran worse) | unresolved |
-| Graphics crash in vkCreateInstance with pc == fault address, from the game's own Vulkan hooks (BONELAB 1.2974 `libSLZQuestNative`) | a pointer into memory freed with OVRPlugin's pre-init OpenXR instance; not the runtime (vrclient.so) or Fossilize being unloaded (keeping both loaded with RTLD_NODELETE didn't help) | unresolved |
+| Unity game crashes or hangs right as Vulkan starts, after `SLZ Graphics plugin loading!` and OVRPlugin's pre-init `xrDestroyInstance`: SIGSEGV with pc 0 (or pc == fault address in an unloaded library), x16/x23 in `libSLZQuestNative.so` (BONELAB 1.2974) | Stress Level Zero's graphics plugin hooks Unity's Vulkan start-up (IUnityGraphicsVulkanV2 interception: vkCreateInstance/vkCreateDevice) and vkCreateSampler; its vkCreateInstance wrapper calls an invalid pointer on the Frame | `frame.slz_vulkan_hooks` (its two registrations become no-ops; Unity starts Vulkan itself; ~35 s of shader prewarming without its pipeline cache) |
 | Unity game shows a picture but the player body is frozen: no head tracking, the controllers stay on the model, no buttons, although OpenXR input works (BONELAB 1.2068, Oculus XR Plugin) | OVRPlugin reports the headset as not worn (`ovrp_GetUserPresent2` → 0) a few seconds after start, and the game's rig only follows a present user (Marrow `XRHMD.IsUserPresent` = Unity's HMD `UserPresence`) | `frame.unity_user_presence` (the Oculus XR Plugin's lookup → `libfp_ovrp.so`, reports present; log `user presence: OVRPlugin 0 …`) |
 | Unreal 5 game crashes at its first render pass, backtrace `vulkan.freedreno.so` ← `libVkLayer_fossilize.so` ← `libfp_vk.so (create_render_pass2)` (Metro Awakening) | a subpass without a depth attachment names a depth/stencil resolve attachment; the Frame's Turnip reads the missing depth attachment (NULL) | the Vulkan shim drops that resolve (always, FramePort after 0.11.0; log `dropped the depth resolve of subpass N (no depth attachment)`); triage `unreal-vulkan-driver-crash` |
 | Unreal 5 game crashes in `vulkan.freedreno.so` called straight from `libUnreal.so` right after its swapchains, or a few seconds into the first frames (Metro Awakening) | Unreal turns on fragment-density-map foveation because Turnip offers VK_EXT_fragment_density_map, then records barriers (to `FRAGMENT_DENSITY_MAP_OPTIMAL`) and image views (2D array R8G8) for a density map the Frame never provides (VK_NULL_HANDLE); Turnip dereferences it | adapter `vk_hide_fdm=1` (the game doesn't see the extension) + `vk_spec_fixes=1` (leaves out null-image barriers, refuses null-image views); triage `unreal-fdm-missing`. Found by disassembling the driver at the crash pc: the struct offsets (0x58 = VkSubpassDescription2, 0x48/0x60 = image barriers, viewType/format in registers) name the call |
@@ -141,6 +156,14 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
  touching new memory (`perf script -F comm,tid,ip,dso`); `-t <tid> -F 499` samples one thread. Map IL2CPP
  addresses with a full Cpp2IL diffable-cs dump (method `Offset` = address − the r-xp mapping of libil2cpp.so).
  Sample memory per mapping name from `/proc/<pid>/smaps` (`[anon:libc_malloc]` = native heap).
+- Hangs (every thread asleep): backtraces of all threads with gdb. Root inside the Lepton container may ptrace the
+  game (the host's `ptrace_scope` 1 doesn't apply there) and the guest has `gdbserver64`; `debuggerd -b` fails (no
+  tombstoned). Copy every mapped library to a local sysroot (`podman exec <container> cat /proc/<pid>/maps`, then
+  `tar -chf - -T <list>` through `podman exec -i`; the app's own libs from the installed `lepton-app/game.apk` at their
+  `/data/app/…/lib/arm64` path), then on the PC: `gdb -batch -ex "set sysroot <dir>" -ex "target remote | ssh
+  steamos@<frame> podman exec -i lepton-steamlaunch-<appid> gdbserver64 - --attach <pid in the container>" -ex
+  "thread apply all bt 25" -ex detach` (`set sysroot target:` makes gdbserver assert in linux_mntns_readlink).
+  `/proc/<pid>/task/*/syscall` (read inside the container) shows each thread's syscall and pc without a debugger.
 - Unity catches native crashes itself: no debuggerd backtrace in Lepton's logcat-crash.log, but a
  `tombstone_00` in the game's `Android/data/<pkg>/files/` with the memory map (map pc/lr/registers to libraries).
 - Focus losses: the game sees FOCUSED→VISIBLE→SYNCHRONIZED (OVRPlugin `[XR_SESSION]`, FrameBridge `focus_hold:`
@@ -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) |
@@ -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/COMPATIBILITY.md]
+    steps:
+      - go: files
+      - wait_for: "Upload files…"
+      - wait: 1.0
+      - hook: {name: select_files, args: [1, 2]}
+
+  - name: screenshots
+    docs: [README.md]
+    steps:
+      - go: screenshots
+      - wait_for: "Take screenshot"
+
+  - name: screenshot-viewer
+    docs: [README.md]
+    steps:
+      - go: screenshots
+      - wait_for: "Take screenshot"
+      - wait: 1.5
+      - call: {fn: screenshots_view.viewer, args: [0]}
+      - wait_for: "Close"
+
+  - name: type-on-frame
+    docs: [README.md]
+    steps:
+      - hook: type_tab
+      - wait_for: "Keyboard connected"
+
+  - name: monitor
+    docs: [README.md]
+    viewport: [1280, 1150]
+    steps:
+      - go: monitor
+      - wait_for: "Processes"
+
+  # newer screens (docs/SHOWCASE.md's gallery; the README picks what it needs)
+  - name: live-view        # idle: a running stream shows its relay's random port and the data rate (no stable picture)
+    docs: [docs/SHOWCASE.md]
+    steps:
+      - go: live
+      - wait_for: "What the player sees"
+
+  - name: install-progress
+    docs: [docs/SHOWCASE.md]
+    steps:
+      - hook: {name: held_install, args: ["${new_game}"]}
+      - open_game: ${new_game}
+      - wait_for: "Cancel"
+
+  - name: appearance
+    docs: [docs/SHOWCASE.md]
+    steps:
+      - go: settings
+      - wait_for: "Portal (OLED)"
@@ -0,0 +1,125 @@
+# The install tutorial: from the download to the first game on the Steam Frame (docs/INSTALL.md links it; every
+# release attaches it as FramePort-install.mp4). FramePort starts as on a new computer (the "fresh" demo profile:
+# empty library, welcome screen, no Frame set up); what happens outside FramePort (the download, a command typed
+# on the Frame) is told on instruction cards. Recorded by scripts/showcase/record_video.py; the format is in
+# docs/SHOWCASE.md ("Videos").
+
+output: docs/media/frameport-install.mp4
+budget_mb: 12
+poster_at: 9
+start:
+  profile: fresh           # FramePort's first start
+  frame: disconnected      # the Frame isn't set up yet
+  route: welcome
+setup:
+  - hook: {name: first_run, args: ["D:/Games", 1.4]}   # the tool download and the folder scan, at a watchable pace
+
+vars:
+  game: com.playful.LuckysTale
+
+title:
+  heading: Installing FramePort
+  line: From the download to your first game on the Steam Frame
+  seconds: 3.4
+end:
+  heading: You're set
+  line: Your game is in the Frame's Steam library. More help in docs/INSTALL.md
+  footer: github.com/spoopyghosty0/frameport
+  seconds: 4.0
+
+scenes:
+  - name: download
+    seconds: 7.5
+    card:
+      eyebrow: "Step 1 · On your computer"
+      heading: Download FramePort
+      steps:
+        - "Open **github.com/spoopyghosty0/frameport** → **Releases** → the latest one"
+        - "Download the archive for your computer: **FramePort-windows-x64.zip**, **FramePort-macos-arm64.zip** or **FramePort-linux-x64.tar.gz**"
+        - "Extract it anywhere. There's no installer and no admin rights are needed"
+
+  - name: first-start
+    seconds: 7.5
+    card:
+      eyebrow: "Step 2 · First start"
+      heading: Start FramePort
+      steps:
+        - "**Windows:** open **FramePort.exe**. At “Windows protected your PC” choose **More info** → **Run anyway**"
+        - "**macOS:** right-click **FramePort.app** → **Open** → **Open**"
+        - "**Linux:** run **FramePort/FramePort**"
+      note: "FramePort is signed with a free certificate, so your system asks once."
+
+  - name: welcome
+    caption: ["FramePort gets itself ready", "It downloads the tools it uses (Java, OVRPort, apksigner) by itself"]
+    hold: 1.0
+    steps:
+      - wait: 1.0
+      - hook: {name: wait_jobs, args: [40]}
+      - wait_for: "Java, OVRPort and apksigner are ready."
+      - wait: 1.0
+
+  - name: connect
+    caption: ["Connect your Steam Frame", "Once: FramePort shows a command to run on the Frame"]
+    hold: 1.5
+    steps:
+      - click: "Set up the Frame"
+      - wait: 1.6
+      - click: "Show setup command"
+      - wait_for: "Waiting for your Frame"
+      - wait: 1.0
+      - hover: "Copy"
+      - wait: 1.4
+
+  - name: on-the-frame
+    seconds: 10
+    card:
+      eyebrow: "Step 3 · On the Frame, first time only"
+      heading: Run the setup command
+      steps:
+        - "In the SteamVR dashboard: **Launch a program** → **Desktop**"
+        - "Open the app menu (bottom left) → **System** → **Konsole**"
+        - "Type the command FramePort shows and press **Enter**"
+      code: "curl -fsS <your-PC-address>:8765/<one-time-code> | bash"
+      note: "FramePort shows your PC's address and a one-time code in place of **<…>**. The desktop closes by itself after a few seconds (Steam restarts once); if Steam asks to install **Lepton**, confirm it. No password is needed."
+
+  - name: connected
+    caption: ["Your Frame is connected", "From now on FramePort finds it by itself"]
+    hold: 1.2
+    steps:
+      - hook: {name: pairing_done, args: [1.6]}
+      - wait_for: "Ready to play"
+      - wait: 1.2
+      - hover: "Quest games (Lepton)"
+      - wait: 1.6
+
+  - name: add-games
+    caption: ["Add your games", "Point FramePort at the folder with your games"]
+    hold: 1.0
+    steps:
+      - nav: "Library"
+      - wait: 1.2
+      - click: "Scan a folder…"
+      - hook: {name: wait_jobs, args: [40]}
+      - wait: 1.2
+      - hover: {name: "Lucky's Tale", dy: 0.3}
+      - wait: 1.0
+
+  - name: install
+    caption: ["Install a game", "FramePort patches it, installs it and adds it to the Frame's Steam library"]
+    hold: 1.2
+    steps:
+      - click: {name: "Lucky's Tale", dy: 0.35}   # (the title: the card's middle is its Install button)
+      - wait_for: "Where it's installed"           # (the game page: a click that missed fails here)
+      - wait: 1.2
+      - click: "Install on Frame"
+      - wait: 0.6
+      - move: [860, 640]
+      - hook: {name: wait_jobs, args: [45]}
+      - wait: 1.0
+
+  - name: play
+    caption: ["Play", "Start it from FramePort, or from Steam in the headset"]
+    steps:
+      - click: "Play on Frame"
+      - wait: 2.6
+      - park: true
@@ -0,0 +1,134 @@
+# The demo tour: FramePort in use (README teaser, docs/media, every release as FramePort-tour.mp4).
+# Recorded by scripts/showcase/record_video.py; the storyboard format is in docs/SHOWCASE.md ("Videos").
+
+output: docs/media/frameport-tour.mp4
+teaser: docs/images/tour-teaser.webp
+budget_mb: 12
+start:
+  profile: demo           # the library in use: games installed on the pretend Frame, BONELAB running
+  frame: connected
+
+vars:
+  game: com.camouflaj.manta        # installed on the pretend Frame
+  new_game: com.CyanWorlds.Riven   # installed during the tour
+
+title:
+  heading: FramePort
+  line: Quest, Android and PC VR games on the Steam Frame
+  seconds: 3.2
+end:
+  heading: FramePort
+  line: Open source · bring your own games
+  footer: github.com/spoopyghosty0/frameport
+  seconds: 3.6
+
+scenes:
+  - name: library
+    caption: ["Your library, ready for the Frame", "Quest, Android and PC VR games from your own folders"]
+    teaser: [0.8, 3.2]
+    steps:
+      - go: library
+      - wait: 1.2
+      - hover: {name: "Batman: Arkham Shadow", dy: 0.3}
+      - wait: 1.0
+      - hover: {name: "Marvel's Deadpool VR", dy: 0.3}
+      - wait: 0.8
+      - hover: "Assassin's Creed Nexus"
+      - wait: 0.8
+      - hover: "Lucky's Tale"
+      - wait: 0.8
+      - park: true
+      - type: "ri"
+      - wait: 1.6
+
+  - name: game
+    caption: ["Every game gets its own recipe", "Known-good fixes from the catalog, or suggested from the game itself"]
+    steps:
+      - click: {name: "Riven", dy: 0.35}   # (the title: the card's middle is its Install button)
+      - wait: 1.8
+      - hover: "Works"
+      - wait: 0.7
+      - scroll: {dy: 420, at: [860, 560]}
+      - wait: 1.2
+      - scroll: {dy: -420, at: [860, 560]}
+      - wait: 0.5
+
+  - name: install
+    caption: ["One click to install", "Patched, signed, uploaded, added to Steam and launch-tested"]
+    teaser: [0.6, 4.0]
+    hold: 1.2
+    steps:
+      - click: "Install on Frame"
+      - wait: 0.6
+      - move: [860, 640]
+      - hook: {name: wait_jobs, args: [45]}
+      - wait: 1.0
+
+  - name: play
+    caption: ["Play from your PC", "Starts the game in the headset through Steam"]
+    teaser: [4.3, 3.2]
+    steps:
+      - nav: "Library"
+      - call: library_view.clear_search
+      - wait: 1.4
+      - hover: {name: "Asgard's Wrath 2", dy: 0.3}
+      - wait: 0.6
+      - hover: {name: "Batman: Arkham Shadow", dy: 0.3}
+      - wait: 0.6
+      - click: {name: "Play on Frame", nth: 0}
+      - wait: 2.6
+      - park: true
+      - wait: 0.4
+
+  - name: monitor
+    caption: ["See what the Frame is doing", "Frame rate, CPU, GPU, temperatures and every process, live"]
+    teaser: [0.5, 2.6]
+    steps:
+      - nav: "Monitor"
+      - wait: 2.4
+      - hover: "Temperature"   # (a tile only: "GPU" is also the process table's sortable column)
+      - wait: 1.0
+      - hover: "Battery"
+      - wait: 1.0
+      - click: "Show details"
+      - wait: 1.8
+      - park: true
+
+  - name: screenshots
+    caption: ["Screenshots from the headset", "Take one from the PC, then view or download them"]
+    steps:
+      - nav: "Screenshots"
+      - wait: 1.6
+      - click: "Take screenshot"
+      - wait_for: "BONELAB · 2026-10-04 21:50"
+      - wait: 0.8
+      - click: "BONELAB · 2026-10-04 21:50"
+      - wait: 2.0
+      - click: "Close"
+      - wait: 0.4
+
+  - name: files
+    caption: ["Files on the Frame", "Videos, mods and saves: upload, download, select with a drag"]
+    steps:
+      - nav: "Files"
+      - wait: 1.6
+      - drag: ["Concert 8K 3D.mp4", "Mars landing (VR180).mkv"]
+      - wait: 1.0
+      - right_click: "Earth from orbit (360).mp4"
+      - wait: 1.4
+      - press: Escape
+      - wait: 0.6
+
+  - name: themes
+    caption: ["Make it yours", "Dark themes, including true black for OLED screens"]
+    steps:
+      - nav: "Settings"
+      - wait: 1.4
+      - click: "Portal (OLED)"
+      - wait: 1.4
+      - click: "Original"
+      - wait: 1.4
+      - click: "Portal"
+      - wait: 1.0
+      - nav: "Library"
+      - wait: 1.4
@@ -30,8 +30,13 @@ static void (*real_glGetIntegerv)(GLenum, GLint *);
 static __eglMustCastToProperFunctionPointerType (*real_eglGetProcAddress)(const char *);
 static pthread_once_t once = PTHREAD_ONCE_INIT;

-static int hide_multiview = -1;  // -1: not set (Unity keeps multiview, everything else hides it)
+static int hide_multiview = -1;  // -1: not set (Unity and Unreal keep multiview, everything else hides it)
 static int hide_msrtt = 1;
+// Unreal (4.25) only turns on its mobile multiview when GL_OVR_multiview, GL_OVR_multiview2 AND
+// GL_OVR_multiview_multisampled_render_to_texture are all there (FOpenGLES::ProcessExtensions). Hiding the last one
+// with the MSRTT extensions switched Unreal's multiview off, so for Unreal it stays visible and its function draws
+// single-sampled (glFramebufferTextureMultiviewOVR), like the EXT stand-ins below.
+static int unreal;

 static void read_conf_file(const char *path) {
    FILE *f = fopen(path, "r");
@@ -335,12 +340,21 @@ static void init(void) {
    real_glGetStringi = gles ? dlsym(gles, "glGetStringi") : NULL;
    real_glGetIntegerv = gles ? dlsym(gles, "glGetIntegerv") : NULL;
    real_eglGetProcAddress = egl ? dlsym(egl, "eglGetProcAddress") : NULL;
-    if (hide_multiview < 0) {  // Unity renders multiview itself and only needs MSRTT hidden
-        void *unity = dlopen("libunity.so", RTLD_NOW | RTLD_NOLOAD);
-        hide_multiview = unity ? 0 : 1;
-        if (unity) dlclose(unity);
+    static const char *const engines[] = {"libunity.so", "libUE4.so", "libUnreal.so"};
+    int engine_found = 0;
+    for (unsigned i = 0; i < sizeof engines / sizeof *engines && !engine_found; i++) {
+        void *engine = dlopen(engines[i], RTLD_NOW | RTLD_NOLOAD);
+        if (engine) {
+            engine_found = 1;
+            unreal = i > 0;
+            dlclose(engine);
+        }
    }
-    LOG("GL shim active: hide_multiview=%d hide_msrtt=%d", hide_multiview, hide_msrtt);
+    // Unity and Unreal render multiview themselves and only need MSRTT hidden
+    if (hide_multiview < 0) hide_multiview = !engine_found;
+    unreal = unreal && hide_msrtt && !hide_multiview;  // only matters while MSRTT is hidden and multiview kept
+    LOG("GL shim active: hide_multiview=%d hide_msrtt=%d%s", hide_multiview, hide_msrtt,
+        unreal ? " (Unreal: multiview MSRTT kept, drawn single-sampled)" : "");
 }

 static int is_hidden(const char *name) {
@@ -349,7 +363,8 @@ static int is_hidden(const char *name) {
            if (!strcmp(name, hidden_multiview[i])) return 1;
    if (hide_msrtt)
        for (size_t i = 0; i < sizeof(hidden_msrtt) / sizeof(hidden_msrtt[0]); ++i)
-            if (!strcmp(name, hidden_msrtt[i])) return 1;
+            if (!strcmp(name, hidden_msrtt[i]))
+                return !(unreal && !strcmp(name, "GL_OVR_multiview_multisampled_render_to_texture"));
    return 0;
 }

@@ -416,6 +431,14 @@ static void plain_rbsms(GLenum target, GLsizei samples, GLenum format, GLsizei w
    (void)samples;
    if (r_plain_rbs) r_plain_rbs(target, format, width, height);
 }
+static PFN_FTMV r_plain_ftmv;
+static int mv_msrtt_logged;
+static void plain_ftmsmv(GLenum target, GLenum attachment, GLuint texture, GLint level, GLsizei samples,
+                         GLint base, GLsizei views) {
+    if (!mv_msrtt_logged++)
+        LOG("GL shim: multiview multisampled render-to-texture (%d samples) drawn single-sampled", (int)samples);
+    if (r_plain_ftmv) r_plain_ftmv(target, attachment, texture, level, base, views);
+}

 __attribute__((visibility("default"))) __eglMustCastToProperFunctionPointerType eglGetProcAddress(const char *name) {
    pthread_once(&once, init);
@@ -432,6 +455,10 @@ __attribute__((visibility("default"))) __eglMustCastToProperFunctionPointerType
        return name[2] == 'F' ? (__eglMustCastToProperFunctionPointerType)plain_ft2dms
                              : (__eglMustCastToProperFunctionPointerType)plain_rbsms;
    }
+    if (unreal && !strcmp(name, "glFramebufferTextureMultisampleMultiviewOVR")) {
+        if (!r_plain_ftmv) r_plain_ftmv = (PFN_FTMV)real_eglGetProcAddress("glFramebufferTextureMultiviewOVR");
+        return (__eglMustCastToProperFunctionPointerType)plain_ftmsmv;
+    }
 #ifdef GLSHIM_TRACE  // build with -DGLSHIM_TRACE for eye-buffer / draw / error tracing
    WRAP("glFramebufferTextureMultiviewOVR", real_ftmv, w_ftmv)
    WRAP("glFramebufferTextureMultisampleMultiviewOVR", real_ftmsmv, w_ftmsmv)
@@ -9,10 +9,14 @@
 //
 // FramePort renames the "ovrp_Update2" lookup in libunity.so to "fpov_Update2" (same length) and adds this library to
 // libOVRPlugin.so's DT_NEEDED, so Unity's dlsym on the plugin finds this function: it waits for the frame first (once
-// per frame index, render step only), then calls the real ovrp_Update2.
+// per frame index, render step only), then calls the real ovrp_Update2 (render step; the physics step: see below).
 #include <android/log.h>
 #include <dlfcn.h>
 #include <pthread.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>

 #define TAG "FrameBridge"
 #define EXPORT __attribute__((visibility("default")))
@@ -25,31 +29,168 @@ static PFN_Update2 real_update2;
 static PFN_WaitToBeginFrame real_wait;
 static pthread_once_t once = PTHREAD_ONCE_INIT;

+// Per-game settings (the same sources as FrameBridge and the GL shim, later ones winning): the frame-begin gate and
+// the held-back physics update below were needed by Sniper Elite VR; in Unity 2019 games (BattleSisters) holding the
+// physics update back made the hands lag and the gate made loading screens stutter, so both are off unless the recipe
+// turns them on (ovrp_begin_gate=1, ovrp_hold_physics=1).
+static int begin_gate, hold_physics;
+
+static void read_conf_file(const char *path) {
+    FILE *f = fopen(path, "r");
+    if (!f) return;
+    char line[256];
+    while (fgets(line, sizeof(line), f)) {
+        if (!strncmp(line, "ovrp_begin_gate=", 16)) begin_gate = atoi(line + 16);
+        if (!strncmp(line, "ovrp_hold_physics=", 18)) hold_physics = atoi(line + 18);
+    }
+    fclose(f);
+}
+
+static void read_conf(void) {
+    Dl_info info;
+    char path[600];
+    if (dladdr((void *)read_conf, &info) && info.dli_fname) {
+        const char *slash = strrchr(info.dli_fname, '/');
+        if (slash && slash - info.dli_fname < 500) {
+            snprintf(path, sizeof(path), "%.*s/libframe_settings.so", (int)(slash - info.dli_fname), info.dli_fname);
+            read_conf_file(path);
+        }
+    }
+    char pkg[256] = {0};
+    FILE *f = fopen("/proc/self/cmdline", "r");
+    if (f) {
+        size_t n = fread(pkg, 1, sizeof(pkg) - 1, f);
+        fclose(f);
+        pkg[n] = 0;
+    }
+    char *colon = strchr(pkg, ':');
+    if (colon) *colon = 0;
+    if (*pkg && !strchr(pkg, '/')) {
+        snprintf(path, sizeof(path), "/sdcard/Android/data/%s/files/framebridge.conf", pkg);
+        read_conf_file(path);
+    }
+    const char *env = getenv("FRAMEBRIDGE_CONFIG");
+    if (env && *env) read_conf_file(env);
+}
+
 static void init(void) {
+    read_conf();
    void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
    if (!ovrp) ovrp = dlopen("libOVRPlugin.so", RTLD_NOW);
    if (ovrp) {
        real_update2 = (PFN_Update2)dlsym(ovrp, "ovrp_Update2");
        real_wait = (PFN_WaitToBeginFrame)dlsym(ovrp, "ovrp_WaitToBeginFrame");
    }
-    LOG("ovrp frame loop shim: ovrp_Update2 %s, ovrp_WaitToBeginFrame %s", real_update2 ? "OK" : "MISSING",
-        real_wait ? "OK" : "MISSING");
+    LOG("ovrp frame loop shim: ovrp_Update2 %s, ovrp_WaitToBeginFrame %s, begin gate %d, hold physics %d",
+        real_update2 ? "OK" : "MISSING", real_wait ? "OK" : "MISSING", begin_gate, hold_physics);
 }

 #define STEP_RENDER (-1)  // ovrpStep_Render

 static void mouse_click_frame(void);  // below: controller presses as Unity mouse clicks

+// xrWaitFrame blocks until the frame waited for before it has begun (xrBeginFrame). Unity begins frames on its render
+// thread, which sometimes skips one (scene activation) and then waits for the main thread: our next wait never
+// returned (Sniper Elite VR hung at its Init scene, main thread in SteamVR's CSxrSession::StartNextFrame, render
+// thread idle). FramePort also renames libunity.so's "ovrp_BeginFrame"/"ovrp_EndFrame" lookups to the functions below.
+// Once a begin has come through, the main thread first waits (≤ BEGIN_TIMEOUT_MS) for the last waited frame to begin
+// and skips this frame's wait if it doesn't (normally the render thread begins it within a frame: pacing unchanged).
+// OVRPlugin only begins the frame index it waited for (else "outside of frame bounds" and no xrBeginFrame, after which
+// the next wait blocked for good), so a begin of another index while a wait is outstanding becomes a begin of the
+// waited index, and the matching end follows it.
+#define BEGIN_TIMEOUT_MS 50
+static pthread_mutex_t begin_lock = PTHREAD_MUTEX_INITIALIZER;
+static pthread_cond_t begin_cond = PTHREAD_COND_INITIALIZER;
+static int begin_hooked;     // fpov_BeginFrame has been called: the gate is armed
+static int outstanding = -1; // frame index waited for and not begun yet, else -1 (under begin_lock)
+static int remap_from = -1, remap_to = -1;  // the last begin that was given the waited index (for its end)
+
+static int last_wait_begun(int frame_index) {
+    if (!begin_gate) return 1;
+    pthread_mutex_lock(&begin_lock);
+    struct timespec until;
+    clock_gettime(CLOCK_REALTIME, &until);
+    until.tv_nsec += BEGIN_TIMEOUT_MS * 1000000L;
+    if (until.tv_nsec >= 1000000000L) until.tv_sec++, until.tv_nsec -= 1000000000L;
+    while (begin_hooked && outstanding >= 0)
+        if (pthread_cond_timedwait(&begin_cond, &begin_lock, &until)) break;
+    int ok = !begin_hooked || outstanding < 0;
+    if (ok) outstanding = frame_index;
+    pthread_mutex_unlock(&begin_lock);
+    return ok;
+}
+
+// Unity's physics step updates OVRPlugin's poses with prediction 0 ("now"). OVRPlugin takes "now" from the monotonic
+// clock, which is the XrTime base on a Quest but not on the Frame (its XrTime ran 0.05-0.9 s ahead), so it located
+// every node that much in the past (the runtime extrapolates backwards), and the render-step reads after it got those
+// poses too: the game's hands trailed the controllers by several centimetres whenever they moved (Sniper Elite VR). A
+// larger prediction doesn't reach (OVRPlugin caps it at ~0.07 s), so the physics update isn't passed on: OVRPlugin
+// keeps the render update's display-time poses for the whole frame (physics and render reads agree).
+#define STEP_PHYSICS 0
+
 EXPORT int fpov_Update2(int step, int frame_index, double prediction_seconds) {
    pthread_once(&once, init);
-    static int last_waited = -1, logged;
+    static int last_waited = -1, rendered, logged, skipped, last_result;
    if (step == STEP_RENDER && real_wait && frame_index != last_waited) {
        last_waited = frame_index;
-        int r = real_wait(frame_index);
-        if (logged++ < 3) LOG("ovrp frame loop shim: waited for frame %d: %d", frame_index, r);
+        if (last_wait_begun(frame_index)) {
+            int r = real_wait(frame_index);
+            if (logged++ < 3) LOG("ovrp frame loop shim: waited for frame %d: %d", frame_index, r);
+        } else if (skipped++ < 20 || skipped % 1000 == 0) {
+            LOG("ovrp frame loop shim: frame %d: the last waited frame wasn't begun within %d ms, not waiting "
+                "(%d times)", frame_index, BEGIN_TIMEOUT_MS, skipped);
+        }
        mouse_click_frame();
    }
-    return real_update2 ? real_update2(step, frame_index, prediction_seconds) : -1000;  // ovrpFailure
+    if (hold_physics && step == STEP_PHYSICS && rendered) return last_result;  // see above: keeps the display-time poses
+    int r = real_update2 ? real_update2(step, frame_index, prediction_seconds) : -1000;  // ovrpFailure
+    if (step == STEP_RENDER) rendered = 1, last_result = r;
+    return r;
+}
+
+// Unity's legacy ovrp_BeginFrame(frameIndex) / ovrp_EndFrame(frameIndex) on the render thread; further arguments
+// (older plugins) are passed on as they are
+typedef int (*PFN_FrameCall)(long, long, long, long);
+
+static PFN_FrameCall ovrp_fn(const char *name) {
+    void *ovrp = dlopen("libOVRPlugin.so", RTLD_NOW | RTLD_NOLOAD);
+    PFN_FrameCall fn = ovrp ? (PFN_FrameCall)dlsym(ovrp, name) : 0;
+    LOG("ovrp frame loop shim: %s %s", name, fn ? "OK" : "MISSING");
+    return fn;
+}
+
+EXPORT int fpov_BeginFrame(long frame, long b, long c, long d) {
+    static PFN_FrameCall real;
+    static int logged;
+    pthread_once(&once, init);  // the settings (begin_gate) before the first begin
+    if (!real) real = ovrp_fn("ovrp_BeginFrame");
+    pthread_mutex_lock(&begin_lock);
+    long index = frame;
+    if (begin_gate && outstanding >= 0 && outstanding != (int)frame) {
+        index = outstanding;
+        remap_from = (int)frame, remap_to = outstanding;
+    } else {
+        remap_from = remap_to = -1;
+    }
+    pthread_mutex_unlock(&begin_lock);
+    int r = real ? real(index, b, c, d) : -1000;
+    if (index != frame && logged++ < 20)
+        LOG("ovrp frame loop shim: begin frame %ld as waited frame %ld: %d", frame, index, r);
+    pthread_mutex_lock(&begin_lock);
+    begin_hooked = 1;
+    outstanding = -1;  // the waited frame (if any) is begun now
+    pthread_cond_broadcast(&begin_cond);
+    pthread_mutex_unlock(&begin_lock);
+    return r;
+}
+
+EXPORT int fpov_EndFrame(long frame, long b, long c, long d) {
+    static PFN_FrameCall real;
+    if (!real) real = ovrp_fn("ovrp_EndFrame");
+    pthread_mutex_lock(&begin_lock);
+    if ((int)frame == remap_from) frame = remap_to;
+    pthread_mutex_unlock(&begin_lock);
+    return real ? real(frame, b, c, d) : -1000;
 }

 // ---------------------------------------------------------------- input diagnostics (pass-through)
@@ -11,8 +11,9 @@
 // Haptics (GitHub #9, found by Klownicle in Lucky's Tale): overport's dispatcher converts an
 // XrHapticAmplitudeEnvelopeVibrationFB with its nanosecond duration taken as seconds, so one vibration allocates an
 // enormous sample buffer and the Frame runs out of memory and freezes. The shim hands OVRPlugin its own
-// xrApplyHapticFeedback, which turns such an envelope into a plain XrHapticVibration (same duration, its peak
-// amplitude) before the dispatcher sees it. Everything else passes through unchanged.
+// xrApplyHapticFeedback, which turns such an envelope into a plain XrHapticVibration (same duration, its RMS
+// amplitude) before the dispatcher sees it; PCM vibrations (XrHapticPcmVibrationFB) are converted the same way.
+// Everything else passes through unchanged.
 // Upstream: ovrport/app#73; tracked in FramePort GitHub #74.
 #include <openxr/openxr.h>
 #include <android/log.h>
@@ -69,6 +70,23 @@ static XRAPI_ATTR XrResult XRAPI_CALL apply_haptic_feedback(XrSession session, c
                                "vibration %.2f", env->amplitudeCount, (long long)env->duration, plain.amplitude);
        return overport_haptics(session, info, (const XrHapticBaseHeader *)&plain);
    }
+    if (feedback && feedback->type == XR_TYPE_HAPTIC_PCM_VIBRATION_FB) {
+        // the other buffered form goes through the same conversion: a plain vibration as long as the samples (all
+        // consumed), with their RMS
+        const XrHapticPcmVibrationFB *pcm = (const XrHapticPcmVibrationFB *)feedback;
+        double sum = 0.0;
+        for (uint32_t i = 0; pcm->buffer && i < pcm->bufferSize; ++i)
+            sum += (double)pcm->buffer[i] * pcm->buffer[i];
+        float rms = pcm->bufferSize ? (float)sqrt(sum / pcm->bufferSize) : 0.0f;
+        XrDuration duration = pcm->sampleRate > 0 ? (XrDuration)(pcm->bufferSize / pcm->sampleRate * 1e9) : 0;
+        XrHapticVibration plain = {XR_TYPE_HAPTIC_VIBRATION, NULL, duration > 0 ? duration : XR_MIN_HAPTIC_DURATION,
+                                   XR_FREQUENCY_UNSPECIFIED, rms > 1.0f ? 1.0f : rms};
+        if (pcm->samplesConsumed) *pcm->samplesConsumed = pcm->bufferSize;
+        if (haptics_logged++ < 3)
+            __android_log_print(ANDROID_LOG_INFO, TAG, "extension shim: haptic PCM (%u samples at %.0f Hz) -> "
+                                "vibration %.2f", pcm->bufferSize, pcm->sampleRate, plain.amplitude);
+        return overport_haptics(session, info, (const XrHapticBaseHeader *)&plain);
+    }
    return overport_haptics(session, info, feedback);
 }

@@ -22,6 +22,10 @@ dependencies = [
    "flet>=1.0",
    "flet-desktop>=1.0",
    "flet-dropzone>=0.4.0",  # drag-and-drop uploads in the Files tab (packaged app only; Apache-2.0)
+    # the live view inside the window (media_kit/libmpv; Apache-2.0). Not on Linux: there the plugin links libmpv.so.1
+    # and a bundle with it wouldn't start without that library (Linux plays in an mpv window or the browser instead).
+    # flet-video pins flet exactly: keep it at the installed flet's version.
+    "flet-video==1.0.2; sys_platform != 'linux'",
    "paramiko>=3.4",
    "zeroconf>=0.132",
    "psutil>=5.9",
@@ -1,368 +0,0 @@
-#!/usr/bin/env python3
-"""Record short clips of the real GUI's animations (web mode, a pretend Frame) for a showcase page: the install
-transit, the live Frame card, navigation, selection and theme switching. One browser context per clip (Playwright's
-video recorder), converted to MP4 + a poster JPG with ffmpeg.
-
-    FRAMEPORT_HOME=<a test data dir> python scripts/demo_record.py --out /tmp/clips [--game <package>] [--only transit]
-
-Reuses ui_smoke's fakes (FakeTarget, FakeMonitorSession, …): nothing reaches a real Frame. Mouse positions are for
-the 1440x900 window at UI scale 1.0 (the same as ui_smoke --gestures).
-"""
-from __future__ import annotations
-
-import argparse
-import os
-import queue
-import random
-import shutil
-import subprocess
-import sys
-import threading
-import time
-import traceback
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
-
-import flet as ft  # noqa: E402
-import ui_smoke  # noqa: E402
-from ui_smoke import FakeMonitorSession, attach_fake_frame, install_fakes  # noqa: E402
-
-from frameport.core import library  # noqa: E402
-from frameport.ui.app import FramePortApp  # noqa: E402
-
-PORT = ui_smoke.PORT
-W, H = 1440, 900
-FFMPEG = shutil.which("ffmpeg") or "/usr/bin/ffmpeg"
-ERRORS: list[str] = []
-APPS: queue.Queue = queue.Queue()  # one FramePortApp per browser session (= per clip)
-
-# sidebar tabs (x, y) at 1440x900
-TAB = {"library": (100, 110), "frame": (100, 152), "files": (100, 194), "screenshots": (100, 236),
-       "live": (100, 278), "keyboard": (100, 320), "monitor": (100, 362), "settings": (100, 404)}
-NOWHERE = (130, 520)  # the sidebar's empty part: nothing hovered
-
-
-class LiveMonitorSession(FakeMonitorSession):
-    """The fake stream, livelier for the live-card clip: a sample every 0.6 s and a frame rate with a few-second
-    stutter now and then (also in the two minutes sent first), so the card's sparkline (5 s points) has a shape and
-    visibly moves."""
-
-    def _sample(self) -> dict:
-        s = super()._sample()
-        t = self.t
-        fps = 72 - abs(random.gauss(0, 0.8))
-        if (t // 8) % 3 == 1:  # 8 samples of stutter in every 24
-            fps = 56 + 6 * abs(((t % 8) - 4) / 4) + random.uniform(-1.5, 1.5)
-        for g in s["games"]:
-            g["fps"] = round(fps, 1)
-        return s
-
-    def _run(self) -> None:
-        self.t = 0
-        while not self.closed and self.t < 100000:
-            self.on_sample(self._sample())
-            if self.t >= self.BACKFILL:
-                time.sleep(0.6)
-            self.t += 1
-
-
-def ui(app: FramePortApp, fn, *args) -> None:
-    """Run an app action, logging (not raising) errors so one broken step doesn't end the recording."""
-    try:
-        fn(*args)
-    except Exception:  # noqa: BLE001
-        ERRORS.append(traceback.format_exc())
-
-
-# ------------------------------------------------------------------ scenarios
-# each: (setup(app) before the clip starts, play(app, page) = the clip, poster time in s)
-
-def transit_setup(game):
-    def run(app):
-        app.open_game(game)
-        time.sleep(1)
-        app.show_activity(True)
-    return run
-
-
-def transit_play(game):
-    """A pretend install through the real JobManager: every stage the real one reports, with an upload ticking."""
-    def run(job):
-        rep = job.reporter
-
-        def stage(name, secs, logs=()):
-            rep.stage(name)
-            for line in logs:
-                rep.log(line)
-            time.sleep(secs)
-        stage("Patching the game", 0.9)
-        stage("OVRPort (primary)", 1.2, ["overport patch --version=latest"])
-        stage("Frame fixes (primary)", 1.0, ["frame.ovrstubs", "frame.vk_sanitize"])
-        stage("sign (primary)", 0.7)
-        rep.stage("validate (primary)")
-        for name in ("APK signature", "64-bit libraries", "OpenXR loader"):
-            rep.check(name, True)
-            time.sleep(0.25)
-        time.sleep(0.2)
-        stage("Prepare Frame", 0.7)
-        total = 1.42e9
-        rep.stage("Upload APK")
-        apk_part = 0.42
-        steps = 14
-        for i in range(1, steps + 1):
-            f = apk_part * i / steps
-            speed = 34.0 + random.uniform(0, 4)
-            left = (1 - f) * total / (speed * 1e6)
-            rep.progress(f, "com.BithellGames.Arcsmith.apk", speed=f"{speed:.1f} MB/s · ~{left:.0f} s left")
-            time.sleep(0.22)
-        rep.stage("Upload data (3 files)")
-        for i in range(1, steps + 1):
-            f = apk_part + (1 - apk_part) * i / steps
-            speed = 34.0 + random.uniform(0, 4)
-            left = (1 - f) * total / (speed * 1e6)
-            rep.progress(f, f"main.{120 + i // 5}.com.BithellGames.Arcsmith.obb",
-                         speed=f"{speed:.1f} MB/s · ~{left:.0f} s left" if f < 1 else f"{speed:.1f} MB/s")
-            time.sleep(0.22)
-        stage("Artwork for the Steam library", 0.8)
-        stage("Finalize install", 0.9)
-        stage("Add to Steam library", 0.8)
-        stage("Launch test (headless)", 1.8, ["process alive", "OpenXR session created", "frames paced: 72 fps"])
-        job.summary = {"verdict": "pass", "findings": []}
-        rep.stage("Launch test: passed")
-        time.sleep(0.5)
-        return "Arcsmith is ready on your Frame: put the headset on and launch it from your Steam library"
-
-    def play(app, page):
-        time.sleep(1.0)
-        app.submit(f"Install {app._title(game)} on Frame", run, game, "install", to="frame")
-        deadline = time.time() + 40
-        while time.time() < deadline and any(j.active for j in app.jobs.jobs):
-            time.sleep(0.3)
-        time.sleep(1.8)  # done: the cover arrives, the toast
-    return play
-
-
-def live_setup(app):
-    # disconnected-looking: no target, state "none" (the fake isn't attached yet)
-    app.target, app.frame_info, app.frame_state = None, None, "none"
-    app.go("library")
-
-
-def live_play(app, page):
-    time.sleep(1.2)
-    app.frame_state = "connecting"
-    app._refresh_sidebar()
-    time.sleep(1.0)
-    attach_fake_frame(app, LiveMonitorSession)
-    app.refresh_view()
-    app._refresh_sidebar()
-    time.sleep(14)
-
-
-def navigation_setup(app):
-    app.go("library")
-
-
-def navigation_play(app, page):
-    m = page.mouse
-    time.sleep(0.8)
-    for tab in ("frame", "files", "monitor", "settings", "library"):
-        m.move(*TAB[tab], steps=8)
-        time.sleep(0.25)
-        m.click(*TAB[tab])
-        time.sleep(1.3)
-    # type to search: an empty part of the header, then the keyboard
-    m.move(480, 60, steps=6)
-    m.click(480, 60)
-    time.sleep(0.4)
-    page.keyboard.type("arc", delay=160)
-    time.sleep(1.6)
-    page.keyboard.press("Escape")
-    time.sleep(1.2)
-    # the "On your Frame" shelf's first card: lift + Play
-    m.move(403, 268, steps=12)
-    time.sleep(1.6)
-    # a grid card's menu
-    m.move(360, 540, steps=10)
-    time.sleep(0.6)
-    m.click(360, 540, button="right")
-    time.sleep(0.9)
-    for dy in (20, 60, 100, 140, 180):
-        m.move(400, 540 + dy, steps=5)
-        time.sleep(0.35)
-    page.keyboard.press("Escape")
-    time.sleep(0.4)
-    m.move(*NOWHERE, steps=8)
-    time.sleep(1.0)
-
-
-def selection_setup(app):
-    app.go("files")
-
-
-def selection_play(app, page):
-    m = page.mouse
-    time.sleep(0.8)
-    m.move(900, 320, steps=10)  # a row: its checkbox and actions fade in
-    time.sleep(1.4)
-    m.move(900, 268, steps=6)
-    time.sleep(0.5)
-    m.down()
-    for pt in ((900, 320), (900, 372)):
-        m.move(*pt, steps=20)
-        time.sleep(0.4)
-    m.up()
-    time.sleep(1.2)
-    m.move(900, 320, steps=5)
-    time.sleep(0.3)
-    m.click(900, 320, button="right")
-    time.sleep(0.8)
-    for dy in (20, 68, 116):
-        m.move(960, 320 + dy, steps=5)
-        time.sleep(0.4)
-    page.keyboard.press("Escape")
-    time.sleep(0.6)
-    m.move(*TAB["screenshots"], steps=10)
-    m.click(*TAB["screenshots"])
-    time.sleep(2.2)
-    for x in (410, 680, 946):  # hover the first row
-        m.move(x, 275, steps=10)
-        time.sleep(0.6)
-    for x in (305, 573):  # select two
-        m.move(x, 227, steps=10)
-        time.sleep(0.4)
-        m.click(x, 227)
-        time.sleep(0.8)
-    m.move(700, 760, steps=10)
-    time.sleep(1.5)
-
-
-def themes_setup(app):
-    app.go("settings")
-
-
-def themes_play(app, page):
-    m = page.mouse
-    time.sleep(1.0)
-    for x, y in ((838, 268), (1090, 268), (587, 420), (587, 275)):  # Portal (OLED), Original, Ember & Ice, Portal
-        m.move(x, y, steps=12)
-        time.sleep(0.3)
-        m.click(x, y)
-        time.sleep(2.4)
-    m.move(*TAB["library"], steps=12)
-    m.click(*TAB["library"])
-    time.sleep(3.0)
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser()
-    ap.add_argument("--out", type=Path, required=True)
-    ap.add_argument("--game", default=None)
-    ap.add_argument("--only", default=None, help="comma-separated clip names (transit,live-card,navigation,…)")
-    ap.add_argument("--crf", type=int, default=26)
-    ap.add_argument("--width", type=int, default=W, help="scale the MP4 to this width (e.g. 1280)")
-    ap.add_argument("--keep-raw", action="store_true", help="keep Playwright's .webm recordings in <out>/raw")
-    args = ap.parse_args()
-    game = args.game or (library.games()[0]["package"] if library.games() else None)
-    if not game:
-        print("the library is empty: nothing to show", file=sys.stderr)
-        return 2
-    library.set_setting("ui.theme", "portal")
-    from frameport.ui import theme as T
-    from frameport.ui.app import assets_dir, themes_dir
-
-    T.set_scale(1.0)
-    T.load_user_themes(themes_dir())
-    install_fakes(game)
-    # the transit last: the job queue is shared by every session, and its finished install would show in the
-    # sidebar's activity card of the clips after it
-    scenarios = [("live-card", live_setup, live_play, 4.0),
-                 ("navigation", navigation_setup, navigation_play, 0.5),
-                 ("selection", selection_setup, selection_play, 3.5),
-                 ("themes", themes_setup, themes_play, 3.0),
-                 ("transit", transit_setup(game), transit_play(game), 9.0)]
-    if args.only:
-        keep = args.only.split(",")
-        scenarios = [s for s in scenarios if s[0] in keep]
-    out, raw = args.out, args.out / "raw"
-    out.mkdir(parents=True, exist_ok=True)
-    raw.mkdir(exist_ok=True)
-
-    def app_main(page: ft.Page):
-        try:
-            app = FramePortApp(page)
-            attach_fake_frame(app)
-        except Exception:  # noqa: BLE001
-            ERRORS.append("startup: " + traceback.format_exc())
-            return
-        APPS.put(app)
-
-    def convert(webm: Path, name: str, start: float, length: float, poster_at: float) -> None:
-        mp4, jpg = out / f"{name}.mp4", out / f"{name}.jpg"
-        scale = [] if args.width == W else ["-vf", f"scale={args.width}:-2:flags=lanczos"]
-        subprocess.run([FFMPEG, "-y", "-loglevel", "error", "-ss", f"{start:.2f}", "-i", str(webm),
-                        "-t", f"{length:.2f}", *scale, "-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf",
-                        str(args.crf), "-preset", "slow", "-movflags", "+faststart", "-an", str(mp4)], check=True)
-        subprocess.run([FFMPEG, "-y", "-loglevel", "error", "-ss", f"{min(poster_at, length - 0.2):.2f}", "-i",
-                        str(mp4), "-frames:v", "1", "-q:v", "3", str(jpg)], check=True)
-        print(f"CLIP {name}: {length:.1f} s, {mp4.stat().st_size / 1e6:.2f} MB", flush=True)
-
-    def recorder():
-        import socket
-
-        from playwright.sync_api import sync_playwright
-
-        for _ in range(90):
-            try:
-                socket.create_connection(("127.0.0.1", PORT), timeout=1).close()
-                break
-            except OSError:
-                time.sleep(1)
-        time.sleep(2)
-        try:
-            with sync_playwright() as p:
-                browser = p.chromium.launch(args=["--use-gl=swiftshader", "--enable-unsafe-swiftshader"])
-                for name, setup, play, poster in scenarios:
-                    while not APPS.empty():  # sessions from elsewhere (a browser the web mode opened)
-                        APPS.get_nowait()
-                    ctx = browser.new_context(viewport={"width": W, "height": H}, record_video_dir=str(raw),
-                                              record_video_size={"width": W, "height": H})
-                    page = ctx.new_page()
-                    t0 = time.monotonic()
-                    page.goto(f"http://127.0.0.1:{PORT}", wait_until="networkidle", timeout=120_000)
-                    app = APPS.get(timeout=120)
-                    time.sleep(2)  # the first screen + web fonts
-                    ui(app, setup, app)
-                    time.sleep(3.5)  # the scenario's first view painted, cards loaded
-                    page.mouse.move(*NOWHERE)
-                    start = time.monotonic() - t0
-                    try:
-                        play(app, page)
-                    except Exception:  # noqa: BLE001
-                        ERRORS.append(f"{name}: " + traceback.format_exc())
-                    length = time.monotonic() - t0 - start
-                    video = page.video
-                    ctx.close()  # flushes the video
-                    webm = Path(video.path())
-                    target = raw / f"{name}.webm"
-                    webm.replace(target)
-                    convert(target, name, start + 0.2, length, poster)
-                    library.set_setting("ui.theme", "portal")  # the next session starts in Portal again
-                browser.close()
-        except Exception:  # noqa: BLE001
-            ERRORS.append("browser: " + traceback.format_exc())
-        if not args.keep_raw:
-            shutil.rmtree(raw, ignore_errors=True)
-        for e in ERRORS:
-            print("ERROR", e, flush=True)
-        os._exit(1 if ERRORS else 0)
-
-    threading.Thread(target=recorder, daemon=True).start()
-    ft.run(app_main, view=ft.AppView.WEB_BROWSER, port=PORT, assets_dir=assets_dir())
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())
@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""Build the demo library (docs/showcase/demo-library.yaml + demo-analyses.json) into a fresh, isolated data dir for
+docs screenshots and the demo tour. No personal data: the games are catalog games, their analyses were exported
+without paths, local paths are made up (D:/Games/…), and the art + store details come from the same public sources
+the app uses (Meta/OculusDB, Steam), cached in ~/.cache/frameport-showcase so later builds (and CI) are offline and
+identical. A game whose art can't be fetched keeps FramePort's own placeholder art; the build never fails over art.
+
+    python scripts/showcase/demo_home.py build <dir> [--offline] [--refresh]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+import time
+import zlib
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[2]
+FIXTURE = REPO / "docs" / "showcase" / "demo-library.yaml"
+ANALYSES = REPO / "docs" / "showcase" / "demo-analyses.json"
+CACHE = Path(os.environ.get("FRAMEPORT_SHOWCASE_CACHE") or Path.home() / ".cache" / "frameport-showcase")
+DAY = 86400.0
+FETCHED = 1790000000.0  # the "fetched" time stored with cached details (fixed: builds are identical)
+
+
+def real_data_dir() -> Path:
+    """The user's own FramePort data dir (never written by the showcase; not even created by asking)."""
+    from frameport.core import paths
+
+    saved = os.environ.pop("FRAMEPORT_HOME", None)
+    removed = paths._removed.is_set()
+    paths._removed.set()  # (user_data_dir creates the folder unless FramePort is being removed)
+    try:
+        return paths.user_data_dir().resolve()
+    finally:
+        if not removed:
+            paths._removed.clear()
+        if saved is not None:
+            os.environ["FRAMEPORT_HOME"] = saved
+
+
+def load_fixture(path: Path = FIXTURE) -> dict:
+    import yaml
+
+    data = yaml.safe_load(path.read_text())
+    games = data.get("games") or []
+    seen = set()
+    for g in games:
+        if not isinstance(g, dict) or not g.get("package"):
+            raise ValueError(f"{path.name}: every game needs a package: {g!r}")
+        if g["package"] in seen:
+            raise ValueError(f"{path.name}: {g['package']} is listed twice")
+        seen.add(g["package"])
+        unknown = set(g) - {"package", "frame", "played", "added", "tested", "tags", "title", "art"}
+        if unknown:
+            raise ValueError(f"{path.name}: {g['package']}: unknown field(s) {sorted(unknown)}")
+        if g.get("frame") not in (None, "internal", "sd", "outdated"):
+            raise ValueError(f"{path.name}: {g['package']}: frame must be internal, sd or outdated")
+    if (data.get("frame") or {}).get("running") not in (None, *seen):
+        raise ValueError(f"{path.name}: frame.running isn't one of the games")
+    return data
+
+
+def fake_sha(package: str, salt: str = "") -> str:
+    import hashlib
+
+    return hashlib.sha1(f"showcase:{package}:{salt}".encode()).hexdigest()
+
+
+def steam_appid(package: str, title: str) -> int:
+    return (zlib.crc32(f'"/home/steamos/Applications/quest-frame/{package}/launch.sh"{title}'.encode())
+            | 0x80000000) & 0xFFFFFFFF
+
+
+def _entry(spec: dict, tech: dict, now: float) -> dict:
+    """The library fields of one demo game, made the way pipeline.add_game / add_rift_game make them."""
+    from frameport.analysis.detect import ANALYSIS_VERSION
+    from frameport.core import library
+    from frameport.patches.base import recipe_fingerprint
+    from frameport.recommend import catalog, engine
+
+    pkg = spec["package"]
+    a = library.analysis_from_dict(dict(tech["analysis"], package=pkg))
+    rift = pkg.startswith("rift.")
+    if not rift:
+        a.extra["analysis_version"] = ANALYSIS_VERSION
+    recipe = engine.suggest(a)
+    title = spec.get("title") or recipe.title or a.label or pkg
+    rdict = library.recipe_to_dict(recipe)
+    fields = dict(title=title, name=title, data_bytes=tech.get("data_bytes") or 0, analysis=a.to_dict(),
+                  recipe=rdict, suggested=rdict, status=recipe.status, added=now - DAY * spec.get("added", 30),
+                  build={"sha256": fake_sha(pkg), "ok": True, "recipe_fp": recipe_fingerprint(rdict),
+                         "applied": sorted(p for p in rdict.get("patches") or {} if "." in p)})
+    if rift:
+        folder = f"D:/Games/PC VR/{title}"
+        exe = tech.get("exe_rel") or tech.get("exe") or "Game.exe"
+        entry = catalog.lookup(pkg)
+        fields.update(kind="rift", apk=None, game_dir=folder, exe=exe.split("/", 1)[-1] if "/" in exe else exe,
+                      exe_confirmed=True, origin="D:/Games/PC VR", quest_package=entry.quest_package if entry
+                      else None, art_source="oculusdb")
+        fields["build"].update(kind="rift", revive="3.2.0")
+    else:
+        folder = f"D:/Games/Quest/{title}"
+        fields.update(apk=f"{folder}/{pkg}.apk", data_dir=f"{folder}/{pkg}" if tech.get("data_bytes") else None,
+                      origin="D:/Games/Quest")
+    if spec.get("tags"):
+        fields["tags"] = list(spec["tags"])
+    if spec.get("played") is not None:
+        fields["last_played"] = now - DAY * spec["played"]
+    installed = spec.get("frame") is not None
+    if installed:
+        t = now - DAY * (spec.get("played", 3) + 0.4)
+        fields["installs"] = {"frame": {"result": {"ok": True, "appid": steam_appid(pkg, title)}, "time": t}}
+    if spec.get("tested", installed):
+        fields["last_test"] = {"state": "RUNNING", "verdict": "pass",
+                               "milestone": "Game window created" if rift else "Submitting frames",
+                               "fps": None if rift else 72.0, "findings": [], "suggestions": [],
+                               "time": now - DAY * (spec.get("played", 3) + 0.39), "target": "frame"}
+    return fields
+
+
+def _art(pkg: str, refresh: bool, offline: bool, log, pick: bool = False) -> str:
+    """Art + store details for one game: from the showcase cache, else fetched (and cached). Returns its source."""
+    from frameport import pipeline
+    from frameport.artwork import fetch
+    from frameport.core import library
+
+    cached = CACHE / "games" / (pkg + ("@pick" if pick else ""))
+    dest = fetch.artwork_dir(pkg)
+    if cached.is_dir() and not refresh:
+        for f in cached.iterdir():
+            if f.is_file() and f.name != "details.json":
+                shutil.copy2(f, dest / f.name)
+        details = cached / "details.json"
+        if details.exists():
+            library.upsert_game(pkg, details=json.loads(details.read_text()))
+        return "cache"
+    if offline:
+        return "none"
+    entry = library.game(pkg)
+    try:
+        if entry.get("kind") == "rift":
+            pipeline._rift_art(entry)
+        elif pick:  # what a user does when the store's art is a placeholder: the picker's Meta (OculusDB) result
+            from frameport.artwork import sources
+
+            choice = next((c for c in sources.search(entry.get("title") or pkg) if c.get("package") == pkg), None)
+            if not (choice and sources.apply_choice(pkg, choice)):
+                log(f"  {pkg}: the picker had no Meta result, store art instead")
+                fetch.fetch(pkg, None, refresh=True)
+        else:
+            fetch.fetch(pkg, None, refresh=True)
+    except Exception as exc:  # noqa: BLE001
+        log(f"  {pkg}: no art ({exc})")
+    d = pipeline.fetch_details(pkg)
+    d["fetched"] = FETCHED
+    library.upsert_game(pkg, details=d)
+    have = [f for f in dest.iterdir() if f.is_file() and not f.name.startswith("t_")]  # (not thumbnails)
+    if not have:
+        return "none"
+    if cached.exists():
+        shutil.rmtree(cached)
+    cached.mkdir(parents=True)
+    for f in have:
+        shutil.copy2(f, cached / f.name)
+    (cached / "details.json").write_text(json.dumps(d, indent=1, sort_keys=True))
+    return "fetched"
+
+
+PROFILES = ("demo", "fresh")
+SCAN_FILE = "showcase-scan.json"  # the fresh profile's games, found by the pretend folder scan (fakes.scan_job)
+
+
+def build(home: Path, offline: bool = False, refresh: bool = False, log=print, profile: str = "demo") -> dict:
+    """Write the demo library into `home` (emptied first). Sets FRAMEPORT_HOME for this process.
+
+    profile "demo": the library in use (games installed on the pretend Frame, one running). "fresh": FramePort's
+    first start (the install tutorial): an empty library, the welcome screen, a Frame with nothing installed and no
+    game running; the demo games (art and store details already in place) wait in showcase-scan.json for the
+    pretend folder scan, as a scan would find them (no install or play history)."""
+    if profile not in PROFILES:
+        raise ValueError(f"unknown profile {profile!r} ({', '.join(PROFILES)})")
+    home = Path(home).resolve()
+    if home == real_data_dir() or real_data_dir() in home.parents:
+        raise SystemExit(f"refusing to build the demo library in FramePort's own data dir ({home})")
+    if home.exists():
+        shutil.rmtree(home)
+    home.mkdir(parents=True)
+    os.environ["FRAMEPORT_HOME"] = str(home)
+    for var in ("FRAMEPORT_NO_UPDATE_CHECK", "FRAMEPORT_NO_CATALOG_UPDATE", "FRAMEPORT_NO_LINK_HANDLER"):
+        os.environ[var] = "1"
+    from frameport.artwork import thumbs
+    from frameport.core import library
+
+    fixture = load_fixture()
+    tech = json.loads(ANALYSES.read_text())
+    now = time.time()
+    missing = [g["package"] for g in fixture["games"] if g["package"] not in tech]
+    if missing:
+        raise SystemExit(f"demo-analyses.json has no analysis for {missing}")
+    for spec in fixture["games"]:
+        library.upsert_game(spec["package"], **_entry(spec, tech[spec["package"]], now))
+    # settings: what a first start would set (no welcome, no migrations or catalog refresh, no update nags)
+    from frameport import __version__
+
+    with library.edit() as data:
+        s = data.setdefault("settings", {})
+        # (ui.easter_eggs off: no holiday badge or milestone confetti in the docs; the hook easter_eggs turns them on)
+        s.update({"ui.theme": "portal", "ui.scale": 1.0, "ui.reduce_motion": False, "ui.welcome_done": True,
+                  "ui.easter_eggs": False,
+                  "ui.language": "en",
+                  "catalog.auto_update": False, "update.auto_check": False, "recipes.app_version": __version__,
+                  "update.last_seen_version": __version__})
+    # the pretend Frame
+    installed = []
+    for spec in fixture["games"]:
+        where = spec.get("frame")
+        if where:
+            installed.append({"package": spec["package"], "drive": "sd" if where == "sd" else "internal",
+                              **({"sha256": fake_sha(spec["package"], "older")} if where == "outdated" else {})})
+    state = {"installed": installed, **{k: v for k, v in (fixture.get("frame") or {}).items()}}
+    (home / "showcase-frame.json").write_text(json.dumps(state, indent=1))
+    # art + store details
+    sources: dict[str, list[str]] = {}
+    for spec in fixture["games"]:
+        src = _art(spec["package"], refresh, offline, log, pick=spec.get("art") == "pick")
+        sources.setdefault(src, []).append(spec["package"])
+        try:
+            thumbs.prewarm(spec["package"])
+        except Exception:  # noqa: BLE001
+            pass
+    # the managed tools are "installed" (no download toast in pictures): stand-in files
+    tools = home / "showcase-tools"
+    tools.mkdir()
+    for var, name in (("FRAMEPORT_JAVA", "java"), ("FRAMEPORT_OVERPORT_JAR", "overport.jar"),
+                      ("FRAMEPORT_APKSIGNER_JAR", "apksigner.jar")):
+        (tools / name).write_bytes(b"")
+        os.environ[var] = str(tools / name)
+    if profile == "fresh":
+        history = ("installs", "last_test", "last_played", "tags", "build")
+        found = [{k: v for k, v in g.items() if k not in history} for g in library.games()]
+        (home / SCAN_FILE).write_text(json.dumps(found))
+        with library.edit() as data:
+            data["games"] = {}
+            data["settings"]["ui.welcome_done"] = False
+        (home / "showcase-frame.json").write_text(json.dumps({"installed": [], "running": None,
+                                                              "battery": state.get("battery", 95)}, indent=1))
+    log(f"demo library ({profile}): {len(fixture['games'])} games in {home} (art: "
+        + ", ".join(f"{k} {len(v)}" for k, v in sorted(sources.items())) + ")")
+    if sources.get("none"):
+        log(f"  without art (placeholders): {', '.join(sources['none'])}")
+    return {"home": str(home), "games": len(fixture["games"]), "art": sources}
+
+
+def build_for_render(home: Path, offline: bool = False, allow_missing_art: bool = False,
+                     profile: str = "demo") -> dict:
+    """build(), but a render must not go on with placeholder art (a store that didn't answer would otherwise put
+    placeholders into the docs and the video): exits 4 unless allowed."""
+    result = build(home, offline=offline, profile=profile)
+    if result["art"].get("none") and not allow_missing_art:
+        raise SystemExit(f"no art for {', '.join(result['art']['none'])} (a store didn't answer?): not rendering. "
+                         "Try again later, or pass --allow-missing-art")
+    return result
+
+
+def tool_env(home: Path) -> dict:
+    """The environment variables a render needs for a built demo home (also for child processes)."""
+    tools = Path(home) / "showcase-tools"
+    return {"FRAMEPORT_HOME": str(home), "FRAMEPORT_NO_UPDATE_CHECK": "1", "FRAMEPORT_NO_CATALOG_UPDATE": "1",
+            "FRAMEPORT_NO_LINK_HANDLER": "1", "FRAMEPORT_JAVA": str(tools / "java"),
+            "FRAMEPORT_OVERPORT_JAR": str(tools / "overport.jar"),
+            "FRAMEPORT_APKSIGNER_JAR": str(tools / "apksigner.jar")}
+
+
+def main() -> int:
+    sys.path.insert(0, str(REPO / "src"))
+    ap = argparse.ArgumentParser()
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    b = sub.add_parser("build")
+    b.add_argument("home", type=Path)
+    b.add_argument("--offline", action="store_true", help="only cached art (no network)")
+    b.add_argument("--refresh", action="store_true", help="fetch art + details again (updates the cache)")
+    b.add_argument("--profile", choices=PROFILES, default="demo", help="demo (in use) or fresh (first start)")
+    args = ap.parse_args()
+    build(args.home, offline=args.offline, refresh=args.refresh, profile=args.profile)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,686 @@
+"""Pretend Frame for GUI renders (ui_smoke, docs screenshots, the demo tour): its files, screenshots, games, drives,
+monitor stream and Type on Frame, with no network and no device. Shared by scripts/ui_smoke.py and scripts/showcase/.
+
+The demo library (scripts/showcase/demo_home.py) writes `showcase-frame.json` into the data dir: which games the
+pretend Frame has installed (and on which drive), the running game and its battery; without it the library's working
+Quest builds are "installed" (the 8 largest).
+"""
+from __future__ import annotations
+
+import json
+import os
+import random
+import threading
+import time
+
+from frameport.core import library
+from frameport.core.paths import user_data_dir
+from frameport.ui.app import FramePortApp
+
+FRAME_STATE = "showcase-frame.json"
+SHOTS_AT = time.mktime((2026, 10, 4, 21, 40, 0, 0, 0, -1))  # the newest sample screenshot (local time)
+
+
+def frame_state() -> dict:
+    """The demo library's pretend Frame ({installed: [{package, drive, sha256?}], running, battery}), else {}."""
+    try:
+        return json.loads((user_data_dir() / FRAME_STATE).read_text())
+    except (OSError, ValueError):
+        return {}
+
+
+class FakeFS:
+    """--fake-frame's file system for the Files tab: a temp folder with sample files, served like SFTP."""
+
+    def __init__(self):
+        import tempfile
+
+        self.home = tempfile.mkdtemp(prefix="fp-fake-frame-")
+        samples = {"Videos": ["Earth from orbit (360).mp4", "Mars landing (VR180).mkv", "Concert 8K 3D.mp4"],
+                   "Downloads": ["Mods/", "readme.txt"], "Documents": ["Saves/", "Notes.pdf"]}
+        sizes = {".mp4": 2_400_000_000, ".mkv": 1_100_000_000}
+        for folder, names in samples.items():
+            base = os.path.join(self.home, folder)
+            os.makedirs(os.path.join(base, "Trips"), exist_ok=True)
+            for n in names:
+                if n.endswith("/"):
+                    os.makedirs(os.path.join(base, n), exist_ok=True)
+                else:
+                    with open(os.path.join(base, n), "wb") as f:
+                        f.truncate(sizes.get(os.path.splitext(n)[1], 48_000))  # sparse: no real disk use
+        # fixed dates (the Files tab shows them): a few days before the newest screenshot, a different one each
+        for i, (root, dirs, files) in enumerate(sorted(os.walk(self.home), reverse=True)):
+            for j, name in enumerate(sorted(dirs + files)):
+                t = SHOTS_AT - 86400 * (2 + (i + j) % 5) - 3600 * ((i * 7 + j * 3) % 11)
+                os.utime(os.path.join(root, name), (t, t))
+        self.shots = self._screenshots()
+
+    def _screenshots(self) -> list[dict]:
+        """Sample Steam screenshots for the Screenshots tab, two days, a few games + SteamVR. They are the games' own
+        in-game store screenshots (shot_*.jpg from the store details), never cover art: games installed on the
+        pretend Frame first, the running one leading (Take screenshot adds one of it); SteamVR's own shots (taken in
+        a game FramePort didn't install) come from another game's. Only a library without any store screenshots falls
+        back to hero/wide art, else colour gradients."""
+        from frameport.artwork import fetch
+
+        folder = os.path.join(self.home, "shots")
+        os.makedirs(folder, exist_ok=True)
+        state = frame_state()
+        on_frame = {i["package"] for i in state.get("installed") or []}
+        running = state.get("running")
+        real, covers = [], []
+        for g in library.games():
+            if g.get("kind") == "rift":
+                continue
+            shots_art = sorted(fetch.artwork_dir(g["package"]).glob("shot_*.jpg"))
+            if shots_art:
+                real.append((g, shots_art))
+            else:
+                covers.append((g, [p for p in fetch.files(g["package"]) if p.stem in ("hero", "landscape")]))
+        games = real or covers
+        games.sort(key=lambda ga: (ga[0]["package"] != running, ga[0]["package"] not in on_frame, -len(ga[1]),
+                                   ga[0]["package"]))
+        self.owners = [(g["package"], g.get("title") or g["package"], arts) for g, arts in games[:3]]
+        rest = [arts for g, arts in games[3:] if g["package"] not in on_frame] or [arts for _g, arts in games[3:4]]
+        self.owners.append((None, "SteamVR", rest[0] if rest else []))
+        self._used = [0] * len(self.owners)  # the next screenshot of each owner (no picture shown twice)
+        # fixed dates (renders don't change from one day to the next): 6 shots on the first day, 4 on the one before
+        # (--gestures drags across the first row)
+        shots = []
+        for i in range(10):
+            t = SHOTS_AT - i * 2400 - (86400 if i >= 6 else 0)
+            shots.append(self._shot(t, i, i % len(self.owners)))
+        return shots
+
+    def _shot(self, t: float, i: int, owner: int) -> dict:
+        """One Steam screenshot: the owner's next store screenshot, whole (scaled to 1280x720)."""
+        from PIL import Image, ImageOps
+
+        pkg, title, arts = self.owners[owner]
+        name = time.strftime("%Y%m%d%H%M%S", time.localtime(t)) + "_1.jpg"
+        path = os.path.join(self.home, "shots", name)
+        if arts:
+            n = self._used[owner]
+            self._used[owner] += 1
+            with Image.open(arts[n % len(arts)]) as src:
+                im = ImageOps.fit(src.convert("RGB"), (1280, 720))
+        else:
+            im = Image.linear_gradient("L").resize((640, 360)).convert("RGB")
+            im = Image.merge("RGB", (im.getchannel(0).point(lambda v, i=i: (v + 40 * i) % 256),
+                                     im.getchannel(1).point(lambda v: 255 - v), im.getchannel(2)))
+        im.save(path, "JPEG", quality=85)
+        return {"path": path, "thumb": None, "time": int(t), "width": 1920, "height": 1080,
+                "size": os.path.getsize(path), "account": "1", "appid": "250820", "package": pkg, "title": title}
+
+    def take_screenshot(self) -> dict:
+        """Take screenshot: a new shot of the running game (its next store screenshot), newest of all."""
+        time.sleep(1.2)  # SteamVR captures, Steam saves
+        t = max(s["time"] for s in self.shots) + 600
+        shot = self._shot(t, len(self.shots) + 1, 0)
+        self.shots.insert(0, shot)
+        return {"taken": True, "path": shot["path"], "reason": None, "hmd": "Normal"}
+
+    def agent(self, command, **args):
+        if command == "storage_targets":
+            return {"targets": [{"id": n.lower(), "path": os.path.join(self.home, n), "android": a, "shared": True}
+                                for n, a in (("Videos", "/sdcard/Movies"), ("Downloads", "/sdcard/Download"),
+                                             ("Documents", "/sdcard/Documents"))]}
+        if command == "list_screenshots":
+            want = args.get("package")
+            shots = [s for s in self.shots if want is None or (s["package"] or "") == want]
+            games = {}
+            for s in self.shots:
+                games.setdefault(s["package"] or "", {"package": s["package"], "title": s["title"], "count": 0})
+                games[s["package"] or ""]["count"] += 1
+            return {"shots": shots, "total": len(shots), "games": list(games.values())}
+        if command == "take_screenshot":  # the Screenshots tab's button: a new shot of the running game
+            return self.take_screenshot()
+        raise RuntimeError(f"fake Frame: {command} not available")
+
+    @property
+    def sftp(self):
+        import paramiko
+
+        class SFTP:
+            def listdir_attr(self, path):
+                out = []
+                for name in sorted(os.listdir(path)):
+                    a = paramiko.SFTPAttributes.from_stat(os.lstat(os.path.join(path, name)))
+                    a.filename = name
+                    out.append(a)
+                return out
+
+            def stat(self, path):
+                return paramiko.SFTPAttributes.from_stat(os.stat(path))
+
+            def get(self, remote, local, callback=None):
+                import shutil
+
+                shutil.copyfile(remote, local)
+        return SFTP()
+
+
+class FakeTarget:
+    """--fake-frame: a pretend Steam Frame with the library's working Quest builds installed (no network, no device),
+    for documentation screenshots."""
+
+    def __init__(self, count: int = 8):
+        from frameport.frame.connection import parse_target
+
+        self.label = "steamframe"
+        self.frame = FakeFS()
+        self.target = parse_target("steamos@steamframe.local")
+        state = frame_state()
+        if state.get("installed"):  # the demo library says what's on the Frame
+            sd_games = {i["package"] for i in state["installed"] if i.get("drive") == "sd"}
+            self.games = [self._record(g, i.get("sha256")) for i in state["installed"]
+                          if (g := library.game(i["package"]))]
+        else:
+            works = [g for g in library.games() if g.get("kind") != "rift" and (g.get("build") or {}).get("sha256")
+                     and (g.get("recipe") or {}).get("status") in ("works", "issues")]
+            works.sort(key=lambda g: -(g.get("data_bytes") or 0))
+            self.games = [self._record(g) for g in works[:count]]
+            sd_games = {self.games[1]["package"]} if len(self.games) > 1 else set()
+        # --linux: the AppImage is on the Frame, but SteamOS lacks one of its libraries
+        self.games += [{"package": g["package"], "kind": "linux", "title": g.get("title"), "apk_size": 2**26,
+                        "apk_present": True, "recipe": None, "exe": g.get("exe"),
+                        "missing_libraries": ["libwebkit2gtk-4.1.so.0"]}
+                       for g in library.games() if g.get("kind") == "linux" and g["package"] == LINUX_APPIMAGE]
+        # GitHub #90: most games on internal storage, some on a microSD card
+        sd = {"internal": False, "path": "/run/media/steamos/SD Card", "label": "SD Card"}
+        for g in self.games:
+            g["drive"] = sd if g["package"] in sd_games else \
+                {"internal": True, "path": "/home/steamos", "label": "Internal storage"}
+            g["drive_missing"] = False
+
+    @staticmethod
+    def _record(g: dict, sha256: str | None = None) -> dict:
+        """The agent's list_installed record of a library game (sha256: a different build = "Update on Frame")."""
+        rift = g.get("kind") == "rift"
+        return {"package": g["package"], "kind": "rift" if rift else "quest", "title": g.get("title"),
+                "apk_size": (g.get("data_bytes") or 0) + (0 if rift else 2**28),
+                "sha256": sha256 or (g.get("build") or {}).get("sha256"),
+                "recipe": {"patches": list((g.get("recipe") or {}).get("patches", []))}}
+
+    def launch(self, pkg: str) -> dict:
+        """Play: Steam on the pretend Frame starts the game (the "Starting … put the headset on" toast)."""
+        return {"via": "shortcut", "steam": {"result": "started", "lines": []}}
+
+    def drives(self) -> list[dict]:
+        sd_games = sum(1 for g in self.games if not g["drive"]["internal"])
+        return [{"id": "internal", "path": "/home/steamos", "install_dir": "/home/steamos/Applications/quest-frame",
+                 "label": "Internal storage", "fstype": "ext4", "internal": True, "removable": False,
+                 "free_bytes": 312 * 2**30, "total_bytes": 460 * 2**30, "usable": True, "reason": "",
+                 "games": len(self.games) - sd_games},
+                {"id": "/run/media/steamos/SD Card", "path": "/run/media/steamos/SD Card",
+                 "install_dir": "/run/media/steamos/SD Card/FramePort", "label": "SD Card", "fstype": "ext4",
+                 "internal": False, "removable": True, "free_bytes": 187 * 2**30, "total_bytes": 238 * 2**30,
+                 "usable": True, "reason": "", "games": sd_games},
+                {"id": "/run/media/steamos/USB", "path": "/run/media/steamos/USB", "install_dir":
+                 "/run/media/steamos/USB/FramePort", "label": "USB", "fstype": "exfat", "internal": False,
+                 "removable": True, "free_bytes": 50 * 2**30, "total_bytes": 64 * 2**30, "usable": False,
+                 "reason": "exfat can't hold game data (no Unix permissions or symlinks); format the drive in "
+                           "SteamOS to install games on it", "games": 0}]
+
+    def move(self, package, dest, reporter) -> dict:
+        reporter.stage("Move game files")
+        for i in range(5):
+            reporter.progress(i / 4, f"Copying {i / 2:.1f}/2.0 GiB")
+            time.sleep(0.5)
+        return {"state": "done", "package": package}
+
+    def set_desktop_entry(self, package, enabled) -> dict:
+        for g in self.games:
+            if g["package"] == package:
+                g["desktop_entry"] = enabled
+        return {"enabled": enabled}
+
+    def describe(self) -> dict:
+        return {"hostname": "steamframe", "os": "SteamOS", "os_version": "3.8", "build_id": "20260922",
+                "free_bytes": 312 * 2**30, "installed": self.games, "lepton": True,
+                "proton": {"ready": {"display_name": "Proton 11 (ARM64)"}, "openxr": {"name": "SteamVR"}},
+                "kernel_keys": {"keys": 31, "max_keys": 200},
+                "battery": {"percent": frame_state().get("battery", 95), "status": "Discharging"}}
+
+    def installed(self) -> list[dict]:
+        return self.games
+
+    def close(self) -> None:
+        pass
+
+
+class FakeKeyboardSession:
+    """--fake-frame: Type on Frame connects at once (nothing is sent anywhere)."""
+
+    def __init__(self, frame):
+        self.closed = False
+
+    def key(self, name, action="down"):
+        return True
+
+    def text(self, text):
+        return ""
+
+    def close(self):
+        self.closed = True
+
+
+class FakeMonitorSession:
+    """--fake-frame: the Monitor tab's stream as synthetic samples, one per second, shaped like a real Quest game on
+    the dev Frame (2026-10-07): 72 fps, the game's Android container, SteamVR/Steam as context. Two minutes are sent
+    at once first, so the charts are full in screenshots. GAME = --game (else the library's first game)."""
+
+    GAME: str | None = None
+    DIP: tuple[float, float] | None = None  # (until, fps): steps hook fps_dip
+    PERFECT = 0.0  # until (time.time()): right on 72 fps (steps hook perfect_pacing)
+    BATTERY: dict | None = None  # the battery from now on (steps hook battery)
+    BACKFILL = 120
+    # (name, group, CPU %, GPU %, memory); "GAME" = the game's package
+    PROCS = [("GAME", "game", 9.8, 44.0, 1_350_000_000), ("vrcompositor", "steamvr", 1.4, 9.0, 80_000_000),
+             ("system_server", "game", 1.1, 0.0, 296_000_000), ("XRServiceLoopTh", "steamvr", 0.5, 0.0, 433_000_000),
+             ("steamwebhelper", "steam", 0.4, 0.0, 350_000_000), ("com.android.systemui", "game", 0.1, 0.0,
+                                                                   229_000_000),
+             ("surfaceflinger", "game", 0.1, 0.4, 96_000_000), ("audioserver", "game", 0.1, 0.0, 31_000_000),
+             ("com.android.providers.media.module", "game", 0.1, 0.0, 130_000_000),
+             ("com.android.launcher3", "game", 0.0, 0.0, 194_000_000), ("main", "game", 0.0, 0.0, 178_000_000),
+             ("com.android.settings", "game", 0.0, 0.0, 172_000_000),
+             ("com.android.networkstack.process", "game", 0.0, 0.0, 130_000_000),
+             ("android.ext.services", "game", 0.0, 0.0, 111_000_000)] + \
+            [("vrwebhelper", "steamvr", 0.3, 0.0, 160_000_000 + i * 9_000_000) for i in range(4)]
+
+    def __init__(self, frame, on_sample, on_end=None):
+        import math
+
+        self.math, self.closed, self.on_sample = math, False, on_sample
+        self.static = {"agent": 62, "cores": 8, "gpu_max_mhz": 903, "mem_total": 16 * 1024 ** 3, "fan": True,
+                       "clusters": [{"cpus": [0, 1], "max_mhz": 2265}, {"cpus": [2, 3, 4], "max_mhz": 3148},
+                                    {"cpus": [5, 6], "max_mhz": 2956}, {"cpus": [7], "max_mhz": 3052}],
+                       "temp_groups": ["CPU", "GPU", "Memory", "Battery", "NPU", "Power ICs", "Modem", "Camera"]}
+        self.t = 0
+        threading.Thread(target=self._run, daemon=True).start()
+
+    def _sample(self) -> dict:
+        m, t = self.math, self.t
+        wave = lambda a, p, o=0: a * (1 + m.sin(t / p + o)) / 2  # noqa: E731
+        state = frame_state()
+        idle = not self.GAME and "running" in state and state["running"] is None  # (a fresh Frame: no game)
+        running = self.GAME or state.get("running")
+        g = library.game(running) if running else (library.games() or [None])[0]
+        game = g or {"package": "com.example.game", "title": "Example Game"}
+        pkg = game["package"]
+        procs = [{"pid": 570799 + i * 37, "ppid": 1, "name": pkg if n == "GAME" else n,
+                  "group": f"game:{pkg}" if grp == "game" else grp, "game": pkg if grp == "game" else None,
+                  "cpu": round(c * (0.85 + wave(0.3, 3, i)), 1), "gpu": round(gp * (0.9 + wave(0.2, 5, i)), 1),
+                  "rss": r, "age": 1500 + t, "uid": 1000, "critical": grp in ("steamvr", "steam"), "locked": False,
+                  "context": grp != "game"}
+                 for i, (n, grp, c, gp, r) in enumerate(self.PROCS) if not (idle and grp == "game")]
+        return {
+            "t": time.time() - max(0, self.BACKFILL - t), "dt": 1.0, "self_ms": 11.5,
+            "cpu": {"total": round(15 + wave(4, 4), 1), "cores": [round(4 + wave(30, 3 + i, i), 1) for i in range(8)],
+                    "mhz": [2265, 1996, 1920, 518]},
+            "gpu": {"busy": round(52 + wave(8, 5), 1), "mhz": 903},
+            "mem": {"total": 15.3 * 1024 ** 3, "avail": int((8.3 - wave(0.15, 9)) * 1024 ** 3),
+                    "swap_total": 7.6 * 1024 ** 3, "swap_free": 7.4 * 1024 ** 3},
+            "psi": {"cpu": 1.0, "memory": 0.0, "io": 0.1},
+            "temps": {"CPU": round(48 + wave(1.5, 11), 1), "GPU": round(46.5 + wave(1, 13), 1), "Memory": 47.1,
+                      "Battery": 27.7, "NPU": 47.3, "Power ICs": 37.0, "Modem": 44.2, "Camera": 46.3},
+            "zones": {"CPU": {"cpu7-top": 48.4, "cpu0": 44.0}, "GPU": {"gpuss-0": 46.5}},
+            "fan": 8500 + int(wave(300, 7)),
+            "power": {"system": round(7.3 + wave(0.6, 4), 2), "cpu": 0.85, "gpu": round(1.0 + wave(0.3, 5), 2),
+                      "npu": 0.1},
+            "battery": {"percent": frame_state().get("battery", 95), "status": "Discharging", "plugged": False,
+                        "draining": True, "watts": -1.96, "empty_s": 22440},
+            "net": {"wlan0": [int(2000 + wave(4000, 3)), 1000], "wlanap": [0, 0], "usb0": [0, 0]},
+            "games": [{"package": pkg, "title": game.get("title") or pkg, "kind": "quest", "appid": 1,
+                       "elapsed": 1500 + t, "cpu": 9.4, "gpu": round(44 + wave(6, 5), 1), "mem": 3_390_000_000,
+                       "processes": 87, "fps": round(71.6 + wave(0.6, 2) - (9 if t % 41 == 30 else 0), 1),
+                       "frame_ms": 0.0}] if not idle else [],
+            "procs": procs, "filter": "game"}
+
+    def _run(self) -> None:
+        self.t = 0
+        while not self.closed and self.t < 100000:
+            self.on_sample(self._sample())
+            if self.t >= self.BACKFILL:  # the first two minutes at once (full charts), then one per second
+                time.sleep(1)
+            self.t += 1
+
+    def set_modules(self, m):
+        # the hub asks for everything when the Monitor tab subscribes (the Frame card started the stream): send the
+        # two minutes again so its charts are full in screenshots too
+        if m == "all":
+            self.t = 0
+        return True
+
+    def set_interval(self, s): pass  # noqa: E704
+    def set_filter(self, w): pass  # noqa: E704
+    def pause(self, p): pass  # noqa: E704
+
+    def kill(self, pid, sig="TERM", force=False):
+        return {"ended": True, "pid": pid}
+
+    def end_game(self, package):
+        return {"ended": True, "via": "steam"}
+
+    def close(self):
+        self.closed = True
+
+
+FAKE_INSTALL_STAGES = ["Patching the game", "OVRPort (primary)", "Frame fixes (primary)", "sign (primary)",
+                       "validate (primary)", "Prepare Frame", "Upload APK"]
+
+
+def start_fake_install(app: FramePortApp, package: str) -> None:
+    """A running install job of `package` that reports the real stage names up to the upload (62 %) and then waits
+    (it never ends: the smoke run exits with it)."""
+    from frameport.ui.jobs import Job
+
+    hold, reached = threading.Event(), threading.Event()
+
+    def run(job):
+        for stage in FAKE_INSTALL_STAGES:
+            job.reporter.stage(stage)
+        time.sleep(0.3)  # past the job queue's notification throttle
+        job.reporter.progress(0.62, "com.example.apk", speed="36.4 MB/s · ~1 min left")
+        reached.set()
+        hold.wait()
+
+    app.jobs.submit(Job(f"Install {app._title(package)} on Frame", run, package, "install"))
+    reached.wait(10)
+
+
+def open_type_tab(app: FramePortApp) -> None:
+    """The Type on Frame tab, with one key 'pressed' so the screenshot shows it working."""
+    app.type_on_frame()
+    time.sleep(1.5)
+    app.keyboard_view.press("Enter")
+
+
+def fake_live_stream(app: FramePortApp) -> None:
+    """The Live view while streaming: a local ffmpeg test picture through the real relay (no Frame needed). Web mode
+    has no in-window player, so it's shown as playing in the browser (the bar's streaming layout)."""
+    import shutil
+    import subprocess
+
+    from frameport.install.livestream import LiveStream
+
+    view = app.live_view
+    if view is None or shutil.which("ffmpeg") is None:
+        return
+    src = ["ffmpeg", "-loglevel", "error", "-re", "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30",
+           "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-c:v", "libx264", "-preset", "ultrafast",
+           "-g", "30", "-pix_fmt", "yuv420p", "-c:a", "aac", "-f", "mp4",
+           "-movflags", "empty_moov+default_base_moof+frag_keyframe", "-frag_duration", "100000", "-"]
+    proc = subprocess.Popen(src, stdout=subprocess.PIPE)
+    view.live = LiveStream(lambda: proc.stdout, proc.terminate).start()
+    view.mode = "browser"
+    view._refresh()
+
+
+def stop_fake_live(app: FramePortApp) -> None:
+    if app.live_view is not None and app.live_view.live is not None:
+        app.live_view.stop()
+
+
+def open_monitor_details(app: FramePortApp) -> None:
+    """The Monitor with its details row open."""
+    app.go("monitor")
+    time.sleep(2)
+    if not app.monitor_view.details.visible:
+        app.monitor_view.toggle_details()
+
+
+LINUX_APPIMAGE = "linux.venera"  # --linux's packages
+LINUX_FOLDER = "linux.matineevr"
+
+
+def _elf(machine: int = 183, appimage: bool = False, extra: bytes = b"") -> bytes:
+    """A minimal ELF header (183 = aarch64): enough for FramePort's Linux app detection."""
+    head = bytearray(64)
+    head[:4], head[4], head[5] = b"\x7fELF", 2, 1
+    if appimage:
+        head[8:11] = b"AI\x02"
+    head[18:20] = machine.to_bytes(2, "little")
+    return bytes(head) + extra
+
+
+def add_fake_linux_apps() -> None:
+    """--linux: an AppImage and a VR app folder (with a helper program, so "Change program…" shows) in the library."""
+    from frameport import pipeline
+
+    base = user_data_dir() / "smoke-linux"
+    app = base / "MatineeVR"
+    (app / "lib").mkdir(parents=True, exist_ok=True)
+    (base / "Venera-2.4.2-aarch64.AppImage").write_bytes(_elf(appimage=True, extra=b"\0" * 4096))
+    (app / "MatineeVR").write_bytes(_elf(extra=b"\0" * 8192))
+    (app / "crashpad_handler").write_bytes(_elf())
+    (app / "lib" / "libopenxr_loader.so.1").write_bytes(_elf(extra=b"xrCreateInstance"))
+    pipeline.add_linux_app(base / "Venera-2.4.2-aarch64.AppImage")
+    pipeline.add_linux_app(app)
+
+
+def install_fakes(game: str | None, monitor_session=None) -> None:
+    """--fake-frame: never reach a real Frame (start-up auto-connect, discovery, the 30 s poll); Type on Frame and
+    the Monitor stream are fakes. `game` = the Monitor's game card (with its artwork)."""
+    from frameport.frame import keyboard, monitor
+
+    keyboard.KeyboardSession = FakeKeyboardSession
+    monitor.MonitorSession = monitor_session or FakeMonitorSession
+    FakeMonitorSession.GAME = game
+    FramePortApp.connect = lambda self, *a, **k: None
+    FramePortApp.refresh_frame = lambda self, *a, **k: None
+    install_first_run_fakes()
+
+
+# ------------------------------------------------------------------ first run (the install tutorial)
+# The setup command shows placeholders for the address and code (each PC has its own; never this PC's real address).
+PAIR_HOST, PAIR_PORT, PAIR_CODE = "<your-PC-address>", 8765, "<one-time-code>"
+TOOLS = {"ready": True}  # False: the managed tools look missing until the (pretend) download finishes
+
+
+class FakePairingServer:
+    """The Frame page's setup command without a server: nothing listens and no firewall rule is touched. The
+    `pairing_done` step hook plays the Frame running the command (on_paired → the pretend Frame connects)."""
+
+    def __init__(self, on_paired=None, host: str = "", **_kw):
+        # host stays as given ("" = over the network; the Frame page words a set host as the USB-cable setup)
+        self.on_paired, self.host = on_paired, host
+        self.port, self.code = PAIR_PORT, PAIR_CODE
+        self.requests, self.failures, self.paired, self.hint = 1, 0, [], ""  # (requests: no firewall hint)
+        self.running = False
+
+    @property
+    def url(self) -> str:
+        return f"http://{self.host or PAIR_HOST}:{self.port}"
+
+    @property
+    def one_liner(self) -> str:
+        return f"curl -fsS {self.host or PAIR_HOST}:{self.port}/{self.code} | bash"
+
+    def start(self):
+        self.running = True
+        return self
+
+    def stop_soon(self) -> None:
+        self.running = False
+
+    def stop(self) -> None:
+        self.running = False
+
+
+def install_first_run_fakes() -> None:
+    """Fakes for a first start: no Frame discovery on the real network (a recording must not show a real device),
+    the pretend setup command, and the managed tools' state (TOOLS)."""
+    from frameport.frame import discovery, pairing
+    from frameport.tools import toolchain
+
+    discovery.browse = lambda *a, **k: []
+    pairing.PairingServer = FakePairingServer
+    pairing.ensure_reachable = lambda server: "ok"
+    if not getattr(toolchain.status, "_showcase", False):
+        real_status = toolchain.status
+
+        def status(*a, **k):
+            out = real_status(*a, **k)
+            if not TOOLS["ready"]:
+                for s in out:
+                    s.installed, s.version = False, None
+            return out
+        status._showcase = True
+        toolchain.status = status
+
+
+def tools_job(app, pace: float = 1.0, delay: float = 0.0):
+    """The welcome screen's "Getting FramePort ready": a pretend download of Java, OVRPort and apksigner through the
+    real job queue (app.update_tools while TOOLS["ready"] is False). `delay`: seconds at 0 % first."""
+    from frameport.ui.jobs import Job
+
+    def run(job):
+        rep = job.reporter
+        rep.stage("Downloading tools")
+        time.sleep(delay)
+        parts = [("Java runtime (Temurin 21)", 48.0), ("OVRPort CLI", 21.0), ("apksigner", 1.6)]
+        total = sum(mb for _n, mb in parts)
+        done = 0.0
+        for name, mb in parts:
+            rep.stage(f"Downloading {name}")
+            steps = max(3, int(mb / 4))
+            for i in range(1, steps + 1):
+                got = done + mb * i / steps
+                rep.progress(got / total, f"{name}: {mb * i / steps:.1f} of {mb:.1f} MB")
+                time.sleep(0.12 * pace)
+            done += mb
+        TOOLS["ready"] = True
+        return "FramePort is ready"
+    job = app.jobs.submit(Job("Download tools", run, None, "tools"))
+    return job
+
+
+def scan_job(app, folder: str, entries: list[dict], pace: float = 1.0):
+    """Scan a folder: the demo games appear one by one through the real job queue (the folder picker is a native
+    dialog a script can't drive; `entries` = the demo library saved aside by demo_home's "fresh" profile)."""
+    from frameport.artwork import thumbs
+
+    def run(job):
+        rep = job.reporter
+        rep.stage("Looking for games")
+        for i, e in enumerate(entries, 1):
+            rep.progress(i / len(entries), e.get("title") or e["package"])
+            library.upsert_game(e["package"], **{k: v for k, v in e.items() if k != "package"})
+            try:
+                thumbs.prewarm(e["package"])
+            except Exception:  # noqa: BLE001
+                pass
+            time.sleep(0.12 * pace)
+        library.set_setting("scan.roots", [folder])
+        if app.route[0] == "welcome":
+            library.set_setting("ui.welcome_done", True)
+        return f"{len(entries)} games found in {folder}"
+    return app.submit(f"Scan {folder.rstrip('/').rsplit('/', 1)[-1]}", run, None, "scan")
+
+
+def attach_fake_frame(app: FramePortApp, monitor_session=None) -> None:
+    """Connect `app` to a FakeTarget (the shared monitor stream, used by the Monitor tab and the Frame card, too)."""
+    app.monitor_hub.session_factory = monitor_session or FakeMonitorSession
+    app.target = FakeTarget()
+    app.frame_info, app.frame_state = app.target.describe(), "connected"
+
+
+class FrozenMonitorSession(FakeMonitorSession):
+    """The fake stream for still pictures: the two minutes of history, then nothing new (every render of a page shows
+    the same numbers, whenever the screenshot is taken)."""
+
+    def _run(self) -> None:
+        self.t = 0
+        while not self.closed:
+            if self.t <= self.BACKFILL:
+                self.on_sample(self._sample())
+                self.t += 1
+            else:
+                time.sleep(0.2)
+
+
+class LiveMonitorSession(FakeMonitorSession):
+    """The fake stream, livelier for videos: a sample every 0.6 s and a steady frame rate with a short, shallow dip
+    now and then (also in the two minutes sent first), so the card's sparkline (5 s points) has a shape and visibly
+    moves without the game looking like it struggles. Seeded: every recording gets the same curve."""
+
+    def _sample(self) -> dict:
+        s = super()._sample()
+        t = self.t
+        rnd = random.Random(t)
+        fps = 72 - abs(rnd.gauss(0, 0.6))
+        if t % 45 in (20, 21, 22):  # a short, shallow dip now and then
+            fps = 66 + 2 * abs(t % 45 - 21) + rnd.uniform(-0.8, 0.8)
+        if self.DIP and time.time() < self.DIP[0]:  # (the step hook fps_dip: a stutter on cue)
+            fps = self.DIP[1] + rnd.uniform(-0.8, 0.8)
+        if time.time() < self.PERFECT:  # (the step hook perfect_pacing: right on target)
+            fps = 72 - rnd.uniform(0, 0.2)
+        for g in s["games"]:
+            g["fps"] = round(fps, 1)
+        if self.BATTERY:
+            s["battery"] = dict(self.BATTERY)
+        return s
+
+    def _run(self) -> None:
+        self.t = 0
+        while not self.closed and self.t < 100000:
+            self.on_sample(self._sample())
+            if self.t >= self.BACKFILL:
+                time.sleep(0.6)
+            self.t += 1
+
+    def set_modules(self, m):
+        """Opening the Monitor tab adds modules: on film the stream just goes on, as the real one does (the tab's
+        charts start there and grow live). Replaying the two minutes, as the stills' stream does, showed the charts
+        racing to catch up."""
+        return True
+
+
+def install_job(package: str, pace: float = 1.0):
+    """A pretend install of `package` for the real JobManager (app.submit): every stage the real one reports, an
+    upload ticking at a plausible speed, the launch test passing. pace < 1 = faster."""
+    def run(job):
+        rep = job.reporter
+        g = library.game(package) or {}
+        title = g.get("title") or package
+        rnd = random.Random(7)
+
+        def stage(name, secs, logs=()):
+            rep.stage(name)
+            for line in logs:
+                rep.log(line)
+            time.sleep(secs * pace)
+        if g.get("kind") == "rift":
+            stage("Prepare the game", 1.0)
+        else:
+            stage("Patching the game", 0.9)
+            stage("OVRPort (primary)", 1.2, ["overport patch --version=latest"])
+            stage("Frame fixes (primary)", 1.0, list((g.get("recipe") or {}).get("patches") or [])[-3:])
+            stage("sign (primary)", 0.7)
+            rep.stage("validate (primary)")
+            for name in ("APK signature", "64-bit libraries", "OpenXR loader"):
+                rep.check(name, True)
+                time.sleep(0.25 * pace)
+        stage("Prepare Frame", 0.7)
+        total = max(g.get("data_bytes") or 0, 1.4e9)
+        first, steps = 0.42, 14
+        for name, file, lo, hi in (("Upload APK", f"{package}.apk", 0.0, first),
+                                   ("Upload data (3 files)", f"main.1.{package}.obb", first, 1.0)):
+            rep.stage(name)
+            for i in range(1, steps + 1):
+                f = lo + (hi - lo) * i / steps
+                speed = 34.0 + rnd.uniform(0, 4)
+                left = (1 - f) * total / (speed * 1e6)
+                rep.progress(f, file, speed=f"{speed:.1f} MB/s · ~{left:.0f} s left" if f < 1 else f"{speed:.1f} MB/s")
+                time.sleep(0.22 * pace)
+        stage("Artwork for the Steam library", 0.8)
+        stage("Finalize install", 0.9)
+        stage("Add to Steam library", 0.8)
+        stage("Launch test (headless)", 1.8, ["process alive", "OpenXR session created", "frames paced: 72 fps"])
+        job.summary = {"verdict": "pass", "findings": []}
+        rep.stage("Launch test: passed")
+        time.sleep(0.5 * pace)
+        return f"{title} is ready on your Frame: put the headset on and launch it from your Steam library"
+    return run
+
@@ -0,0 +1,278 @@
+"""Post-production for the demo tour, with ffmpeg only: screencast frames → a constant-frame-rate video, one clip per
+scene with its caption faded in, title and end cards, crossfades between everything, then the final MP4, a poster and
+the short looping WebP teaser for the README.
+
+The filter graphs are built by pure functions (tested without ffmpeg); `run` executes a command and fails loudly.
+Cards and captions are small HTML pages rendered by the same Chromium (render_card), in the app's own colours.
+"""
+from __future__ import annotations
+
+import html
+import json
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+FFMPEG = shutil.which("ffmpeg") or "ffmpeg"
+FPS = 30
+SIZE = (1920, 1080)
+
+
+def run(args: list[str]) -> None:
+    cmd = [FFMPEG, "-y", "-hide_banner", "-loglevel", "error", *map(str, args)]
+    r = subprocess.run(cmd, capture_output=True, text=True)
+    if r.returncode != 0:
+        raise RuntimeError(f"ffmpeg failed ({r.returncode}): {' '.join(cmd)}\n{r.stderr[-3000:]}")
+
+
+# ------------------------------------------------------------------ frames → video
+
+def concat_list(frames: list[tuple[float, str]], end: float | None = None, min_frame: float = 1 / 120) -> str:
+    """An ffconcat script showing each screencast frame until the next one came (Chrome sends frames only on
+    changes); the last one until `end` (wall-clock), else for one frame time."""
+    lines = ["ffconcat version 1.0"]
+    for i, (t, name) in enumerate(frames):
+        nxt = frames[i + 1][0] if i + 1 < len(frames) else (end if end is not None else t + 1 / FPS)
+        lines += [f"file '{name}'", f"duration {max(min_frame, nxt - t):.6f}"]
+    if frames:
+        lines.append(f"file '{frames[-1][1]}'")  # ffconcat: the last entry's duration needs a following file
+    return "\n".join(lines) + "\n"
+
+
+def frames_to_video(folder: Path, out: Path, end: float | None = None, size: tuple[int, int] = SIZE) -> float:
+    """The screencast (folder/frames.json + JPEGs) as a constant-frame-rate H.264 file (high quality, an
+    intermediate). Returns the wall-clock time of its first frame (scene times are relative to it)."""
+    frames = [tuple(f) for f in json.loads((folder / "frames.json").read_text())]
+    if not frames:
+        raise RuntimeError("the screencast has no frames")
+    (folder / "frames.ffconcat").write_text(concat_list(frames, end))
+    w, h = size
+    run(["-f", "concat", "-safe", "0", "-i", folder / "frames.ffconcat",
+         "-vf", f"fps={FPS},scale={w}:{h}:flags=lanczos:force_original_aspect_ratio=decrease,"
+                f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2,format=yuv420p",
+         "-c:v", "libx264", "-preset", "veryfast", "-crf", "12", out])
+    return frames[0][0]
+
+
+# ------------------------------------------------------------------ scenes
+
+def caption_window(duration: float, show: float = 4.2, fade: float = 0.45, lead: float = 0.35) -> tuple[float, float]:
+    """When a scene's caption is on screen: from `lead` s in, for `show` s (shorter scenes: until 0.6 s before
+    their end), fading `fade` s in and out. Returns (start, end)."""
+    start = min(lead, max(0.0, duration / 4))
+    end = min(start + show, max(start + 2 * fade, duration - 0.6))
+    return start, end
+
+
+def scene_filter(duration: float, fade: float = 0.45, size: tuple[int, int] = SIZE) -> str:
+    """The filter graph laying a caption (input 1, a still RGBA PNG looped) over a scene (input 0)."""
+    start, end = caption_window(duration, fade=fade)
+    return (f"[1:v]scale={size[0]}:{size[1]}:flags=lanczos,format=rgba,fade=t=in:st={start:.3f}:d={fade}:alpha=1,"
+            f"fade=t=out:st={end - fade:.3f}:d={fade}:alpha=1[cap];"
+            f"[0:v][cap]overlay=0:0:format=auto:shortest=1,format=yuv420p[v]")
+
+
+def cut_scene(raw: Path, start: float, duration: float, caption: Path | None, out: Path,
+              size: tuple[int, int] = SIZE) -> None:
+    """One scene from the raw recording, with its caption."""
+    if caption is None:
+        run(["-ss", f"{start:.3f}", "-t", f"{duration:.3f}", "-i", raw, "-an",
+             "-c:v", "libx264", "-preset", "veryfast", "-crf", "12", "-pix_fmt", "yuv420p", out])
+        return
+    run(["-ss", f"{start:.3f}", "-t", f"{duration:.3f}", "-i", raw,
+         "-loop", "1", "-t", f"{duration:.3f}", "-i", caption,
+         "-filter_complex", scene_filter(duration, size=size), "-map", "[v]", "-an", "-r", FPS,
+         "-c:v", "libx264", "-preset", "veryfast", "-crf", "12", out])
+
+
+def card_clip(image: Path, duration: float, out: Path, zoom: float = 0.03) -> None:
+    """A title/end card: the still, slowly zooming in by `zoom` over its duration (alive, not frozen)."""
+    frames = max(1, int(duration * FPS))
+    w, h = SIZE
+    run(["-loop", "1", "-t", f"{duration:.3f}", "-i", image,
+         "-vf", f"scale={w * 2}:{h * 2},zoompan=z='1+{zoom}*on/{frames}':x='iw/2-(iw/zoom/2)':"
+                f"y='ih/2-(ih/zoom/2)':d={frames}:s={w}x{h}:fps={FPS},format=yuv420p",
+         "-frames:v", frames, "-c:v", "libx264", "-preset", "veryfast", "-crf", "12", out])
+
+
+# ------------------------------------------------------------------ joining
+
+def xfade_offsets(durations: list[float], transition: float) -> list[float]:
+    """Where each crossfade starts on the joined timeline: clip k+1 begins `transition` s before clip k ends."""
+    offsets, total = [], 0.0
+    for d in durations[:-1]:
+        total += d - transition
+        offsets.append(round(total, 3))
+    return offsets
+
+
+def xfade_graph(durations: list[float], transition: float, size: tuple[int, int] = SIZE) -> tuple[str, str]:
+    """(filter graph, output label) crossfading inputs 0..n-1 in order. Every input is brought to the same size,
+    frame rate, timebase and pixel format first (xfade refuses anything else)."""
+    w, h = size
+    parts = [f"[{k}:v]fps={FPS},scale={w}:{h}:flags=lanczos,setsar=1,format=yuv420p,settb=AVTB[n{k}]"
+             for k in range(len(durations))]
+    prev = "[n0]"
+    for k, off in enumerate(xfade_offsets(durations, transition), start=1):
+        label = f"[x{k}]"
+        parts.append(f"{prev}[n{k}]xfade=transition=fade:duration={transition}:offset={off}{label}")
+        prev = label
+    parts.append(f"{prev}format=yuv420p[vout]")
+    return ";".join(parts), "[vout]"
+
+
+def joined_length(durations: list[float], transition: float) -> float:
+    return sum(durations) - transition * (len(durations) - 1)
+
+
+def join(clips: list[Path], durations: list[float], out: Path, transition: float = 0.5, crf: int = 23,
+         size: tuple[int, int] = SIZE, extra: list[str] | None = None) -> None:
+    graph, label = xfade_graph(durations, transition, size)
+    args = []
+    for c in clips:
+        args += ["-i", c]
+    run([*args, "-filter_complex", graph, "-map", label, "-an", "-r", FPS, "-c:v", "libx264", "-preset", "slow",
+         "-crf", crf, "-pix_fmt", "yuv420p", "-movflags", "+faststart", *(extra or []), out])
+
+
+def encode_within(clips: list[Path], durations: list[float], out: Path, budget_mb: float, transition: float = 0.5,
+                  crf: int = 22, max_crf: int = 32) -> int:
+    """The final MP4 at the best quality (lowest CRF) that fits `budget_mb`. Returns the CRF used."""
+    while True:
+        join(clips, durations, out, transition, crf)
+        if out.stat().st_size <= budget_mb * 1e6 or crf >= max_crf:
+            return crf
+        crf += 2
+
+
+def poster(video: Path, at: float, out: Path) -> None:
+    run(["-ss", f"{at:.2f}", "-i", video, "-frames:v", "1", "-q:v", "2", out])
+
+
+def teaser_webp(clips: list[Path], durations: list[float], out: Path, width: int = 960, fps: int = 15,
+                budget_mb: float = 4.0, transition: float = 0.35) -> int:
+    """A looping animated WebP of the highlight clips (README: plays inline where an MP4 wouldn't). Lowers the
+    quality until it fits `budget_mb`. Returns the quality used."""
+    graph, label = xfade_graph(durations, transition)
+    graph = graph.replace("format=yuv420p[vout]", f"fps={fps},scale={width}:-2:flags=lanczos[vout]")
+    args = []
+    for c in clips:
+        args += ["-i", c]
+    quality = 72
+    while True:
+        run([*args, "-filter_complex", graph, "-map", label, "-an", "-c:v", "libwebp_anim", "-lossless", "0",
+             "-quality", quality, "-compression_level", "6", "-loop", "0", out])
+        if out.stat().st_size <= budget_mb * 1e6 or quality <= 30:
+            return quality
+        quality -= 8
+
+
+# ------------------------------------------------------------------ cards and captions
+
+def theme_colors(name: str = "portal") -> dict:
+    from frameport.ui import theme as T
+
+    T.set_theme(name)
+    return {k: getattr(T, k) for k in ("BG", "SURFACE", "SURFACE_2", "BORDER", "TEXT", "TEXT_2", "TEXT_3", "ACCENT",
+                                       "SECONDARY")}
+
+
+FONT_CSS = ('<link rel="preconnect" href="https://fonts.gstatic.com">'
+            '<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700;900&display=block" '
+            'rel="stylesheet">')
+FONT = "'Roboto', 'Segoe UI', system-ui, sans-serif"
+
+
+def caption_html(title: str, subtitle: str, c: dict, left: int = 372, bottom: int = 56) -> str:
+    """A lower third: a dark glass panel with a blue→orange edge (the logo's two portals), title + one line."""
+    e = html.escape
+    return f"""<!doctype html><html><head><meta charset="utf-8">{FONT_CSS}<style>
+html,body{{margin:0;width:{SIZE[0]}px;height:{SIZE[1]}px;background:transparent;font-family:{FONT}}}
+.cap{{position:absolute;left:{left}px;bottom:{bottom}px;max-width:1180px;padding:26px 40px 28px 44px;
+border-radius:22px;background:rgba(12,14,20,.86);box-shadow:0 18px 50px rgba(0,0,0,.55),
+inset 0 0 0 1px rgba(255,255,255,.08);overflow:hidden}}
+.cap:before{{content:"";position:absolute;left:0;top:0;bottom:0;width:8px;
+background:linear-gradient(180deg,{c['SECONDARY']},{c['ACCENT']})}}
+h1{{margin:0;font-size:46px;font-weight:700;color:{c['TEXT']};letter-spacing:-.3px}}
+p{{margin:10px 0 0;font-size:28px;font-weight:400;color:{c['TEXT_2']}}}
+</style></head><body><div class="cap"><h1>{e(title)}</h1>{f'<p>{e(subtitle)}</p>' if subtitle else ''}</div>
+</body></html>"""
+
+
+def card_html(title: str, subtitle: str, footer: str, logo_svg: str, c: dict) -> str:
+    """A full-screen card: the logo, the two-colour wordmark, a line, a footer; a soft portal glow behind."""
+    e = html.escape
+    word = ('<span style="color:{a}">Frame</span><span style="color:{b}">Port</span>'
+            .format(a=c["ACCENT"], b=c["SECONDARY"])) if title == "FramePort" else e(title)
+    return f"""<!doctype html><html><head><meta charset="utf-8">{FONT_CSS}<style>
+html,body{{margin:0;width:{SIZE[0]}px;height:{SIZE[1]}px;background:{c['BG']};font-family:{FONT};overflow:hidden}}
+.glow{{position:absolute;inset:0;
+background:radial-gradient(ellipse 46% 52% at 42% 50%,{c['SECONDARY']}33,transparent 70%),
+radial-gradient(ellipse 46% 52% at 58% 50%,{c['ACCENT']}2e,transparent 70%)}}
+.wrap{{position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center}}
+.logo{{width:220px;height:220px;filter:drop-shadow(0 18px 40px rgba(0,0,0,.6))}}
+.logo svg{{width:100%;height:100%}}
+h1{{margin:34px 0 0;font-size:112px;font-weight:900;letter-spacing:-2px;color:{c['TEXT']}}}
+p{{margin:18px 0 0;font-size:38px;color:{c['TEXT_2']};font-weight:400}}
+.foot{{position:absolute;bottom:64px;left:0;right:0;text-align:center;font-size:26px;color:{c['TEXT_3']}}}
+</style></head><body><div class="glow"></div><div class="wrap"><div class="logo">{logo_svg}</div>
+<h1>{word}</h1><p>{e(subtitle)}</p></div><div class="foot">{e(footer)}</div></body></html>"""
+
+
+def step_card_html(card: dict, c: dict) -> str:
+    """An instruction card for what happens outside FramePort (a download, a command on the Frame): an eyebrow
+    (where you are), a heading, numbered steps, an optional command in a terminal box and a note. Steps and the note
+    may mark words **bold** (a button or menu name)."""
+    e = html.escape
+
+    def rich(text: str) -> str:
+        return re.sub(r"\*\*(.+?)\*\*", r"<b>\1</b>", e(text))
+    steps = "".join(f'<li><span class="n">{i}</span><span>{rich(s)}</span></li>'
+                    for i, s in enumerate(card.get("steps") or [], 1))
+    code = (f'<div class="code"><span class="prompt">$</span>{e(card["code"])}</div>' if card.get("code") else "")
+    return f"""<!doctype html><html><head><meta charset="utf-8">{FONT_CSS}<style>
+html,body{{margin:0;width:{SIZE[0]}px;height:{SIZE[1]}px;background:{c['BG']};font-family:{FONT};overflow:hidden}}
+.glow{{position:absolute;inset:0;
+background:radial-gradient(ellipse 40% 55% at 12% 30%,{c['SECONDARY']}26,transparent 70%),
+radial-gradient(ellipse 45% 55% at 92% 80%,{c['ACCENT']}22,transparent 70%)}}
+.wrap{{position:absolute;left:180px;right:180px;top:0;bottom:0;display:flex;flex-direction:column;
+justify-content:center;gap:30px}}
+.eyebrow{{font:600 26px/1 'Roboto Mono','Consolas',monospace;letter-spacing:3px;text-transform:uppercase;
+color:{c['ACCENT']}}}
+h1{{margin:0;font-size:76px;font-weight:700;letter-spacing:-1px;color:{c['TEXT']};line-height:1.08}}
+.line{{margin:0;font-size:34px;color:{c['TEXT_2']};max-width:1400px;line-height:1.35}}
+ol{{list-style:none;margin:8px 0 0;padding:0;display:flex;flex-direction:column;gap:22px}}
+li{{display:flex;gap:26px;align-items:baseline;font-size:36px;color:{c['TEXT']};line-height:1.35}}
+li b{{color:{c['ACCENT']};font-weight:700}}
+.n{{flex:none;width:56px;height:56px;border-radius:50%;display:inline-flex;align-items:center;
+justify-content:center;font-weight:700;font-size:28px;color:{c['TEXT']};position:relative;top:-4px;
+background:linear-gradient(135deg,{c['SECONDARY']}66,{c['ACCENT']}88)}}
+.code{{margin-top:6px;align-self:flex-start;max-width:100%;padding:26px 36px;border-radius:18px;
+background:#05060A;border:2px solid {c['BORDER']};font:500 40px/1.3 'Roboto Mono','Consolas',monospace;
+color:#E8F1FF;box-shadow:0 20px 60px rgba(0,0,0,.5)}}
+.prompt{{color:{c['SECONDARY']};margin-right:22px}}
+.note{{margin:0;font-size:26px;color:{c['TEXT_3']};max-width:1400px}}
+.note b{{color:{c['TEXT_2']}}}
+.brand{{position:absolute;left:180px;bottom:54px;font-size:26px;font-weight:900;letter-spacing:-.3px}}
+</style></head><body><div class="glow"></div><div class="wrap">
+{f'<div class="eyebrow">{e(card["eyebrow"])}</div>' if card.get("eyebrow") else ''}
+<h1>{e(card["heading"])}</h1>
+{f'<p class="line">{rich(card["line"])}</p>' if card.get("line") else ''}
+{f'<ol>{steps}</ol>' if steps else ''}{code}
+{f'<p class="note">{rich(card["note"])}</p>' if card.get("note") else ''}
+</div><div class="brand"><span style="color:{c['ACCENT']}">Frame</span><span style="color:{c['SECONDARY']}">Port</span>
+</div></body></html>"""
+
+
+def render_card(playwright, page_html: str, out: Path, transparent: bool = False) -> Path:
+    """Render an HTML card to a PNG at the video size (fonts loaded first)."""
+    browser = playwright.chromium.launch()
+    try:
+        page = browser.new_page(viewport={"width": SIZE[0], "height": SIZE[1]})
+        page.set_content(page_html, wait_until="networkidle")
+        page.evaluate("document.fonts.ready")
+        page.screenshot(path=str(out), omit_background=transparent)
+    finally:
+        browser.close()
+    return out
@@ -0,0 +1,337 @@
+#!/usr/bin/env python3
+"""Record the showcase videos (docs/showcase/videos/<name>.yaml): the real GUI on the demo library with a pretend
+Frame, driven like a person would (a drawn pointer on eased paths), filmed with Chrome's screencast; then each scene
+captioned, instruction cards rendered for what happens outside FramePort (a download, a command on the Frame), title
+and end cards added and everything joined with crossfades.
+
+    python scripts/showcase/record_video.py                    # every video
+    python scripts/showcase/record_video.py tour install       # some
+    python scripts/showcase/record_video.py install --draft    # quick 720p check of a storyboard edit (work dir only)
+    python scripts/showcase/record_video.py /tmp/my-demo.yaml       # a storyboard file anywhere (its output may
+                                                                         # be any .mp4 path: demos, not docs)
+    python scripts/showcase/record_video.py --changed-since <git rev>   # the ones whose storyboard (or this code)
+                                                                         # changed since then (CI)
+
+Each video writes its `output` MP4 (+ .jpg poster) and, when it has `teaser` parts, its teaser WebP; a video.json
+timeline goes next to the work files (--work). --names prints what can be clicked after each scene, --scenes records
+only some scenes (with --draft). SHOWCASE_DEBUG=1 prints every step with its start time. See docs/SHOWCASE.md.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+REPO = HERE.parents[1]
+sys.path[:0] = [str(HERE.parent), str(REPO / "src")]
+
+from showcase import demo_home  # noqa: E402
+
+VIDEOS = REPO / "docs" / "showcase" / "videos"
+VIDEO_KEYS = {"output", "teaser", "budget_mb", "poster_at", "start", "setup", "vars", "title", "end", "scenes"}
+START_KEYS = {"profile", "frame", "stream", "route"}
+SCENE_KEYS = {"name", "caption", "teaser", "hold", "steps", "card", "seconds"}
+CARD_KEYS = {"eyebrow", "heading", "line", "steps", "code", "note"}
+VIEWPORT = (1440, 810)  # the layout size; filmed at 4/3 device pixels = 1920x1080
+TEASER_MB = 4.0
+
+
+def video_names() -> list[str]:
+    return sorted(p.stem for p in VIDEOS.glob("*.yaml"))
+
+
+def load_video(name: str) -> dict:
+    """A storyboard, checked (StepError for anything malformed: before a recording starts, and in the tests)."""
+    import yaml
+
+    from showcase import steps
+
+    path = Path(name) if name.endswith(".yaml") else VIDEOS / f"{name}.yaml"  # (or a storyboard file anywhere)
+    where = path.name if name.endswith(".yaml") else f"videos/{name}.yaml"
+    data = yaml.safe_load(path.read_text())
+    unknown = set(data) - VIDEO_KEYS
+    if unknown:
+        raise steps.StepError(f"{where}: unknown key(s) {sorted(unknown)}")
+    if not str(data.get("output") or "").endswith(".mp4"):
+        raise steps.StepError(f"{where}: output must be an .mp4 path")
+    if data.get("teaser") is not None and not str(data["teaser"]).endswith(".webp"):
+        raise steps.StepError(f"{where}: teaser must be a .webp path")
+    start = data.get("start") or {}
+    if set(start) - START_KEYS:
+        raise steps.StepError(f"{where}: start: unknown key(s) {sorted(set(start) - START_KEYS)}")
+    if start.get("profile", "demo") not in demo_home.PROFILES:
+        raise steps.StepError(f"{where}: start.profile is one of {', '.join(demo_home.PROFILES)}")
+    if start.get("frame", "connected") not in ("connected", "disconnected"):
+        raise steps.StepError(f"{where}: start.frame is connected or disconnected")
+    if start.get("stream", "live") not in ("live", "frozen"):
+        raise steps.StepError(f"{where}: start.stream is live or frozen")
+    steps.validate(data.get("setup") or [], f"{where} setup")
+    seen = set()
+    for sc in data.get("scenes") or []:
+        name_ = sc.get("name")
+        if not name_ or name_ in seen:
+            raise steps.StepError(f"{where}: missing or repeated scene name {name_!r}")
+        seen.add(name_)
+        if set(sc) - SCENE_KEYS:
+            raise steps.StepError(f"{where}: {name_}: unknown key(s) {sorted(set(sc) - SCENE_KEYS)}")
+        if "card" in sc:  # an instruction card: rendered, not filmed
+            card = sc["card"]
+            if not isinstance(card, dict) or not card.get("heading") or set(card) - CARD_KEYS:
+                raise steps.StepError(f"{where}: {name_}: card needs a heading (keys: {', '.join(sorted(CARD_KEYS))})")
+            if "steps" in sc or "caption" in sc or "teaser" in sc:
+                raise steps.StepError(f"{where}: {name_}: a card scene has no steps, caption or teaser")
+            if not isinstance(sc.get("seconds", 5), (int, float)) or sc.get("seconds", 5) <= 0:
+                raise steps.StepError(f"{where}: {name_}: seconds must be positive")
+            continue
+        cap = sc.get("caption")
+        if cap is not None and not (isinstance(cap, list) and 1 <= len(cap) <= 2):
+            raise steps.StepError(f"{where}: {name_}: caption is [title] or [title, line]")
+        teaser = sc.get("teaser")
+        if teaser is not None and not (isinstance(teaser, list) and len(teaser) == 2 and teaser[1] > 0):
+            raise steps.StepError(f"{where}: {name_}: teaser is [from, seconds]")
+        steps.validate(sc.get("steps") or [], f"{where} {name_}")
+    if not seen:
+        raise steps.StepError(f"{where}: no scenes")
+    for card in ("title", "end"):
+        if not (data.get(card) or {}).get("heading"):
+            raise steps.StepError(f"{where}: {card} needs a heading")
+    return data
+
+
+def changed_videos(since: str) -> list[str]:
+    """The videos to record again after the commits since `since`: all when the recorder or the step language
+    changed, else the ones whose storyboard changed."""
+    out = subprocess.run(["git", "diff", "--name-only", since, "HEAD"], cwd=REPO, capture_output=True, text=True)
+    if out.returncode != 0:
+        return video_names()  # (unknown base, e.g. a new branch): everything
+    files = out.stdout.split()
+    if any(f.startswith("scripts/showcase/") for f in files):
+        return video_names()
+    return sorted({Path(f).stem for f in files if f.startswith("docs/showcase/videos/") and f.endswith(".yaml")}
+                  & set(video_names()))
+
+
+def video_installs(session, pace: float = 0.5) -> None:
+    """Installs in a video run the scripted job (every real stage, nothing built or sent) through the real queue,
+    and leave the game installed on the pretend Frame."""
+    from frameport.core import library
+    from showcase import fakes
+
+    app = session.app
+
+    def submit(pkg: str, to: str = "frame"):
+        script = fakes.install_job(pkg, pace)
+
+        def run(job):
+            message = script(job)
+            g = library.game(pkg)
+            if app.target is not None and g:
+                app.target.games.append(fakes.FakeTarget._record(g))
+                app.frame_info = app.target.describe()
+            now = time.time()
+            library.upsert_game(pkg, installs={"frame": {"result": {"ok": True}, "time": now}},
+                                last_test={"state": "RUNNING", "verdict": "pass", "milestone": "Submitting frames",
+                                           "fps": 72.0, "findings": [], "suggestions": [], "time": now,
+                                           "target": "frame"})
+            return message
+        return app.submit(f"Install {app._title(pkg)} on Frame", run, pkg, "install", to="frame")
+    app._submit_install = submit
+
+
+def print_names(session, scene: str) -> None:
+    names = sorted({(n["label"] or n["text"] or n["all"].splitlines()[-1] if n["all"] else "")[:60]
+                    for n in session.nodes() if n["tappable"]} - {""})
+    print(f"NAMES after {scene}: {names}", flush=True)
+
+
+def record(name: str, args) -> int:
+    """Record one video in this process."""
+    video = load_video(name)
+    start = video.get("start") or {}
+    scenes = video["scenes"]
+    if args.scenes:
+        want = args.scenes.split(",")
+        scenes = [s for s in scenes if s["name"] in want]
+    stem = Path(name).stem
+    work = (args.work / stem) if args.work else Path(tempfile.mkdtemp(prefix=f"fp-video-{stem}-"))
+    work.mkdir(parents=True, exist_ok=True)
+    home = (args.home / stem) if args.home else Path(tempfile.mkdtemp(prefix="fp-video-home-"))
+    demo_home.build_for_render(home, offline=args.offline, allow_missing_art=args.allow_missing_art,
+                               profile=start.get("profile", "demo"))
+
+    from showcase import postprod, steps
+    from showcase.fakes import FrozenMonitorSession, LiveMonitorSession
+    from showcase.web import Screencast, Server
+
+    variables = video.get("vars") or {}
+    started = time.monotonic()
+    step_log = (lambda msg: print(f"{time.monotonic() - started:7.1f} {msg}", flush=True)) \
+        if os.environ.get("SHOWCASE_DEBUG") else None
+
+    def script(server) -> int:
+        scale = 1.0 if args.draft else 4 / 3
+        s = server.session(VIEWPORT, cursor=True, device_scale=scale)
+        video_installs(s)
+        if start.get("frame") == "disconnected":
+            steps.HOOKS["disconnect"](s)
+        steps.run(s, video.get("setup") or [], variables, log=step_log)  # before filming: a failure stops here
+        s.app.go(start.get("route", "library"))
+        s.sleep(2.5)
+        s.park()
+        cast = Screencast(s, work / "frames", quality=80 if args.draft else 92)
+        cast.start()
+        s.sleep(0.8)
+        timeline = []
+        for sc in scenes:
+            if "card" in sc:  # rendered later: nothing to film
+                timeline.append({"name": sc["name"], "card": True, "seconds": sc.get("seconds", 5)})
+                continue
+            t0 = time.time()
+            print(f"SCENE {sc['name']}", flush=True)
+            try:
+                steps.run(s, sc.get("steps") or [], variables, log=step_log)
+            except Exception as exc:  # noqa: BLE001
+                server.errors.append(f"scene {sc['name']}: {exc!r}")
+            s.sleep(sc.get("hold", 0.6))
+            timeline.append({"name": sc["name"], "start": t0, "end": time.time()})
+            if args.names:
+                print_names(s, sc["name"])
+        cast.stop()
+        cast.write_index()
+        s.close()
+        return produce(server, timeline)
+
+    def produce(server, timeline) -> int:
+        size = (1280, 720) if args.draft else postprod.SIZE
+        filmed = [t for t in timeline if not t.get("card")]
+        raw = work / "raw.mp4"
+        first = postprod.frames_to_video(work / "frames", raw, end=filmed[-1]["end"], size=size) if filmed else 0
+        colors = postprod.theme_colors("portal")
+        logo = (REPO / "src" / "frameport" / "ui" / "icons" / "logo.svg").read_text()
+        cards = work / "cards"
+        cards.mkdir(exist_ok=True)
+
+        def end_card(which: str) -> tuple[Path, float]:
+            c = video[which]
+            png = postprod.render_card(server.playwright, postprod.card_html(
+                c["heading"], c.get("line", ""), c.get("footer", ""), logo, colors), cards / f"{which}.png")
+            clip = work / f"{which}.mp4"
+            postprod.card_clip(png, c.get("seconds", 3.0), clip)
+            return clip, c.get("seconds", 3.0)
+
+        clip, secs = end_card("title")
+        clips, durations, scene_clips = [clip], [secs], {}
+        by_name = {sc["name"]: sc for sc in scenes}
+        for item in timeline:
+            sc = by_name[item["name"]]
+            if item.get("card"):
+                png = postprod.render_card(server.playwright, postprod.step_card_html(sc["card"], colors),
+                                           cards / f"card-{sc['name']}.png")
+                clip = work / f"card-{sc['name']}.mp4"
+                postprod.card_clip(png, item["seconds"], clip, zoom=0.015)
+                clips.append(clip)
+                durations.append(item["seconds"])
+                continue
+            start_s, length = item["start"] - first, item["end"] - item["start"]
+            cap = None
+            if sc.get("caption"):
+                title, line = (sc["caption"] + [""])[:2]
+                cap = postprod.render_card(server.playwright, postprod.caption_html(title, line, colors),
+                                           cards / f"cap-{sc['name']}.png", transparent=True)
+            clip = work / f"scene-{sc['name']}.mp4"
+            postprod.cut_scene(raw, max(0.0, start_s), length, cap, clip, size=size)
+            clips.append(clip)
+            durations.append(length)
+            scene_clips[sc["name"]] = (clip, length)
+            item.update(clip_start=round(start_s, 3), seconds=round(length, 3))
+        clip, secs = end_card("end")
+        clips.append(clip)
+        durations.append(secs)
+        transition = 0.25 if args.draft else 0.5
+        if args.draft:
+            out = work / f"{stem}-draft.mp4"
+            postprod.join(clips, durations, out, transition=transition, crf=28, size=size)
+            crf = 28
+        else:
+            out = REPO / video["output"]
+            out.parent.mkdir(parents=True, exist_ok=True)
+            crf = postprod.encode_within(clips, durations, out, float(video.get("budget_mb", 12)))
+            postprod.poster(out, durations[0] + float(video.get("poster_at", 1.5)), out.with_suffix(".jpg"))
+            parts, lengths = [], []
+            for sc in scenes:  # the teaser: each scene's `teaser` part (with its caption)
+                if sc.get("teaser") and sc["name"] in scene_clips:
+                    frm, secs = sc["teaser"]
+                    part = work / f"teaser-{sc['name']}.mp4"
+                    postprod.run(["-ss", f"{frm:.2f}", "-t", f"{secs:.2f}", "-i", scene_clips[sc["name"]][0],
+                                  "-an", "-c:v", "libx264", "-preset", "veryfast", "-crf", "14", part])
+                    parts.append(part)
+                    lengths.append(secs)
+            if parts and video.get("teaser"):
+                teaser = REPO / video["teaser"]
+                teaser.parent.mkdir(parents=True, exist_ok=True)
+                q = postprod.teaser_webp(parts, lengths, teaser, budget_mb=TEASER_MB)
+                print(f"TEASER {teaser} ({teaser.stat().st_size / 1e6:.2f} MB, quality {q})", flush=True)
+        # where each scene starts in the finished video (chapters)
+        at = durations[0] - transition
+        for item, d in zip(timeline, durations[1:-1], strict=True):
+            item["at"] = round(at, 2)
+            at += d - transition
+        total = postprod.joined_length(durations, transition)
+        (work / "video.json").write_text(json.dumps({"video": name, "scenes": timeline, "seconds": round(total, 2),
+                                                     "crf": crf, "output": str(out)}, indent=1))
+        print(f"VIDEO {name}: {out} ({out.stat().st_size / 1e6:.2f} MB, {total:.1f} s, crf {crf}); work: {work}",
+              flush=True)
+        return 0
+
+    stream = FrozenMonitorSession if start.get("stream") == "frozen" else LiveMonitorSession
+    return Server(monitor_session=stream).run(script)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("videos", nargs="*", help=f"video names (default: all of {', '.join(video_names())})")
+    ap.add_argument("--changed-since", default=None, help="only videos whose storyboard (or the recorder) changed "
+                    "since this git revision")
+    ap.add_argument("--scenes", default=None, help="comma-separated scene names (one video)")
+    ap.add_argument("--draft", action="store_true", help="720p, quick, no teaser; nothing written to docs/")
+    ap.add_argument("--names", action="store_true", help="print the clickable names after each scene")
+    ap.add_argument("--work", type=Path, default=None, help="folder for frames and clips (<work>/<video>)")
+    ap.add_argument("--home", type=Path, default=None, help="demo data dirs (<home>/<video>; default: temp)")
+    ap.add_argument("--offline", action="store_true", help="use only cached art")
+    ap.add_argument("--allow-missing-art", action="store_true", help="render even when a game got no art")
+    args = ap.parse_args()
+    names = args.videos or (changed_videos(args.changed_since) if args.changed_since else video_names())
+    unknown = {n for n in names if not (n.endswith(".yaml") and Path(n).is_file())} - set(video_names())
+    if unknown:
+        print(f"unknown video(s): {sorted(unknown)} (known: {', '.join(video_names())})", file=sys.stderr)
+        return 2
+    for name in names:
+        load_video(name)  # every storyboard checked before anything is recorded
+    if not names:
+        print("no video to record", flush=True)
+        return 0
+    if len(names) == 1:
+        return record(names[0], args)
+    # one process per video: each builds its own demo data dir (the app reads it per process)
+    failed = []
+    passed = [*(["--draft"] if args.draft else []), *(["--names"] if args.names else []),
+              *(["--offline"] if args.offline else []), *(["--allow-missing-art"] if args.allow_missing_art else []),
+              *(["--work", str(args.work)] if args.work else []), *(["--home", str(args.home)] if args.home else [])]
+    for name in names:
+        cmd = [sys.executable, __file__, name, *passed]
+        print(f"RECORD {name}", flush=True)
+        if subprocess.run(cmd).returncode != 0:
+            failed.append(name)
+    if failed:
+        print(f"failed: {', '.join(failed)}", file=sys.stderr)
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""Render the docs screenshots (docs/showcase/shots.yaml) from the demo library with a pretend Frame, and write each
+into docs/images/ only when the picture really changed (anti-aliasing noise doesn't count).
+
+    python scripts/showcase/render_docs.py [--only library,game] [--check] [--out docs/images] [--offline]
+
+--check renders into a temp folder and exits 1 if any docs image is out of date (CI). Needs the dev extras
+(flet-web, playwright + `playwright install chromium`). See docs/SHOWCASE.md.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+REPO = HERE.parents[1]
+sys.path[:0] = [str(HERE.parent), str(REPO / "src")]
+
+from showcase import demo_home  # noqa: E402
+
+MANIFEST = REPO / "docs" / "showcase" / "shots.yaml"
+IMAGES = REPO / "docs" / "images"
+SHOT_KEYS = {"name", "docs", "steps", "viewport", "scale", "crop"}
+# a picture counts as changed when the mean difference per channel exceeds MEAN_LIMIT (0-255 scale) or more than
+# PIXEL_SHARE of its pixels differ by more than PIXEL_LIMIT in some channel. Measured: run-to-run noise (the live
+# card's sparkline) stays under 0.007 % of the pixels; the smallest real change seen (the sidebar card showing
+# another game) is 0.12 %
+MEAN_LIMIT, PIXEL_LIMIT, PIXEL_SHARE = 0.5, 24, 0.0004
+ATTEMPTS = 2  # a shot whose steps fail (e.g. the window never connected) is tried once more in a fresh window
+
+
+def load_manifest(path: Path = MANIFEST) -> dict:
+    import yaml
+
+    from showcase import steps
+
+    data = yaml.safe_load(path.read_text())
+    names = set()
+    for shot in data.get("shots") or []:
+        name = shot.get("name")
+        if not name or not re.fullmatch(r"[a-z0-9-]+", name):
+            raise steps.StepError(f"shots.yaml: bad shot name {name!r}")
+        if name in names:
+            raise steps.StepError(f"shots.yaml: {name} is listed twice")
+        names.add(name)
+        unknown = set(shot) - SHOT_KEYS
+        if unknown:
+            raise steps.StepError(f"shots.yaml: {name}: unknown key(s) {sorted(unknown)}")
+        steps.validate(shot.get("steps") or [], f"shots.yaml {name}")
+        crop = shot.get("crop")
+        placed = "anchor" in (crop or {}) or {"x", "y"} <= set(crop or {})
+        if crop and crop.get("dialog"):
+            continue
+        if crop is not None and not ({"width", "height"} <= set(crop) and placed):
+            raise steps.StepError(f"shots.yaml: {name}: crop needs width, height and an anchor or x/y")
+    return data
+
+
+def changed(old: Path, new: Path) -> bool:
+    """Whether `new` differs visibly from `old` (a missing or differently sized old picture counts as changed)."""
+    from PIL import Image, ImageChops, ImageStat
+
+    if not old.exists():
+        return True
+    with Image.open(old) as a, Image.open(new) as b:
+        if a.size != b.size:
+            return True
+        diff = ImageChops.difference(a.convert("RGB"), b.convert("RGB"))
+    if max(ImageStat.Stat(diff).mean) > MEAN_LIMIT:
+        return True
+    strong = diff.convert("L").point(lambda v: 255 if v > PIXEL_LIMIT else 0)
+    share = ImageStat.Stat(strong).mean[0] / 255
+    return share > PIXEL_SHARE
+
+
+def optimise(path: Path) -> None:
+    from PIL import Image
+
+    with Image.open(path) as im:
+        im.load()
+        im.convert("RGB").save(path, "PNG", optimize=True)
+
+
+def privacy_problems(home: Path) -> list[str]:
+    """Anything in the demo data dir that looks like someone's own data: this machine's home folder or user name, the
+    real data dir, IP addresses (version numbers like 1.4.0.0 aside: only private/public ranges with a non-zero last
+    part that aren't a known version are reported)."""
+    needles = {str(Path.home()), str(demo_home.real_data_dir())}
+    user = os.environ.get("USER") or os.environ.get("USERNAME")
+    found = []
+    ip = re.compile(r"(?<![\d.])(?:10|172|192|100)\.\d{1,3}\.\d{1,3}\.\d{1,3}(?![\d.])")
+    for f in home.rglob("*"):
+        if not f.is_file() or f.suffix.lower() not in (".json", ".txt", ".yaml", ".yml", ".conf", ".log", ""):
+            continue
+        try:
+            text = f.read_text(errors="ignore")
+        except OSError:
+            continue
+        rel = f.relative_to(home)
+        for n in needles:
+            if n and n in text.replace(str(home), ""):
+                found.append(f"{rel}: contains {n}")
+        if user and len(user) > 2 and re.search(rf"\b{re.escape(user)}\b", text.replace(str(home), "")):
+            found.append(f"{rel}: contains the user name {user!r}")
+        for m in ip.findall(text):
+            found.append(f"{rel}: IP address {m}")
+    return found
+
+
+def crop_box(session, crop: dict):
+    from showcase.web import Box
+
+    if crop.get("dialog"):
+        d, pad = session.dialog(), crop.get("pad", 0)
+        return Box(d.x - pad, d.y - pad, d.w + 2 * pad, d.h + 2 * pad)
+    if "anchor" in crop:
+        a = session.find(crop["anchor"], timeout=10)
+        return Box(a.x + crop.get("left", 0), a.y + crop.get("top", 0), crop["width"], crop["height"])
+    return Box(crop["x"], crop["y"], crop["width"], crop["height"])
+
+
+def render(shots: list[dict], variables: dict, defaults: dict, out: Path, log=print, verify: bool = True):
+    """A script for web.Server.run: renders every shot into out/<name>.png."""
+    from showcase import steps
+
+    def one(server, shot: dict, path: Path) -> None:
+        """Render one shot. Any failing step raises: no picture is taken of a page that didn't get where the steps
+        lead (a window that never connected once produced an empty, unconnected Library)."""
+        vw, vh = shot.get("viewport") or defaults.get("viewport") or (1280, 820)
+        s = server.session((vw, vh))
+        try:
+            steps.run(s, shot.get("steps") or [], variables)
+            s.park(away=True)
+            box = crop_box(s, steps.substitute(shot["crop"], variables)) if shot.get("crop") else None
+            s.shot(path, clip=box)
+        finally:
+            s.close()
+
+    def attempt(server, shot: dict, path: Path) -> bool:
+        """One render into `path` (a failing step: one more try in a fresh window). False when both failed."""
+        for n in range(1, ATTEMPTS + 1):
+            try:
+                one(server, shot, path)
+                return True
+            except Exception as exc:  # noqa: BLE001
+                path.unlink(missing_ok=True)
+                if n < ATTEMPTS:
+                    log(f"RETRY {shot['name']}: {exc!r}")
+                else:
+                    server.errors.append(f"{shot['name']}: {exc!r}")
+        return False
+
+    def script(server) -> int:
+        """Every shot is rendered twice, each in a fresh window, and kept only when both agree: the headless GPU
+        now and then draws a glyph wrong ("7.θ W" for "7.30 W"), a fault the settling can't see. Disagreeing
+        renders get a third: the one two of them match is kept."""
+        failed = 0
+        for shot in shots:
+            t0 = time.monotonic()
+            final = out / f"{shot['name']}.png"
+            takes = []
+            for k in range(3 if verify else 1):
+                path = out / f".take{k}-{shot['name']}.png"
+                if not attempt(server, shot, path):
+                    break
+                takes.append(path)
+                if not verify:
+                    path.replace(final)
+                    break
+                agreed = next((a for i, a in enumerate(takes) for b in takes[i + 1:] if not changed(a, b)), None)
+                if agreed is not None:
+                    agreed.replace(final)
+                    break
+            else:
+                server.errors.append(f"{shot['name']}: three renders, no two alike (an unstable page?)")
+            for p in takes:
+                p.unlink(missing_ok=True)
+            if final.exists():
+                log(f"SHOT {shot['name']} ({time.monotonic() - t0:.1f} s, {len(takes)} renders)")
+            else:
+                failed += 1
+        return 1 if failed else 0
+    return script
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("--only", default=None, help="comma-separated shot names")
+    ap.add_argument("--out", type=Path, default=IMAGES, help="where the images go (default docs/images)")
+    ap.add_argument("--check", action="store_true", help="only report out-of-date images (exit 1 if any)")
+    ap.add_argument("--home", type=Path, default=None, help="demo data dir (default: a temp folder)")
+    ap.add_argument("--offline", action="store_true", help="use only cached art")
+    ap.add_argument("--allow-missing-art", action="store_true", help="render even when a game got no art")
+    ap.add_argument("--keep", type=Path, default=None, help="also keep every raw render in this folder")
+    ap.add_argument("--fast", action="store_true", help="render each shot once (no second render to catch a "
+                    "misdrawn glyph); for trying out a manifest edit")
+    args = ap.parse_args()
+
+    manifest = load_manifest()
+    shots = manifest["shots"]
+    if args.only:
+        want = args.only.split(",")
+        unknown = set(want) - {s["name"] for s in shots}
+        if unknown:
+            print(f"unknown shot(s): {sorted(unknown)}", file=sys.stderr)
+            return 2
+        shots = [s for s in shots if s["name"] in want]
+    home = args.home or Path(tempfile.mkdtemp(prefix="fp-showcase-home-"))
+    demo_home.build_for_render(home, offline=args.offline, allow_missing_art=args.allow_missing_art)
+    problems = privacy_problems(home)
+    if problems:
+        print("refusing to render, the demo data contains personal-looking data:\n  " + "\n  ".join(problems),
+              file=sys.stderr)
+        return 3
+    renders = Path(tempfile.mkdtemp(prefix="fp-showcase-shots-"))
+    status_file = renders / "status.json"
+
+    def finish(server_code: int) -> int:
+        """After rendering (still in the server's script thread): compare, write, report."""
+        report = {"written": [], "unchanged": [], "missing": [], "changed": []}
+        for shot in shots:
+            new = renders / f"{shot['name']}.png"
+            if not new.exists():
+                report["missing"].append(shot["name"])
+                continue
+            optimise(new)
+            old = args.out / new.name
+            if changed(old, new):
+                report["changed"].append(shot["name"])
+                if not args.check:
+                    args.out.mkdir(parents=True, exist_ok=True)
+                    shutil.copyfile(new, old)
+                    report["written"].append(shot["name"])
+            else:
+                report["unchanged"].append(shot["name"])
+        if args.keep:
+            args.keep.mkdir(parents=True, exist_ok=True)
+            for f in renders.glob("*.png"):
+                shutil.copyfile(f, args.keep / f.name)
+        status_file.write_text(json.dumps(report))
+        print("RESULT " + json.dumps(report), flush=True)
+        if report["missing"] or server_code:
+            return 1
+        return 1 if args.check and report["changed"] else 0
+
+    from showcase.web import Server
+
+    script = render(shots, manifest.get("vars") or {}, manifest.get("defaults") or {}, renders, verify=not args.fast)
+    from showcase.fakes import FrozenMonitorSession
+
+    return Server(monitor_session=FrozenMonitorSession).run(lambda server: finish(script(server)))
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,390 @@
+"""The step language shared by the docs screenshots (docs/showcase/shots.yaml) and the demo tour (tour.yaml).
+
+A step is a one-key mapping. App steps call the app the way its own handlers do; pointer steps move a real (drawn)
+mouse to things found by name (see web.Session.find); hooks run the pretend Frame's scripted events.
+
+    - go: monitor                      # a sidebar route (library, frame, files, screenshots, live, keyboard, …)
+    - nav: "Monitor"                   # click that tab like a person (checked: the page really changed)
+    - open_game: ${game}               # or {package: …, advanced: true} = with Customize open
+    - call: {fn: screenshots_view.viewer, args: [0]}   # any app method (dotted path from the app)
+    - pop_dialog: true                 # close the top dialog
+    - theme: original                  # switch the colour theme live (what Settings → Appearance does)
+    - hover: "Batman"                  # pointer: a name, {name, nth, dx, dy, exact} or [x, y]
+    - click: "Monitor"                 # also right_click, double_click
+    - drag: ["Videos", "Documents"]    # press on the first target, move through the others, release
+    - clicks: {at: [37, 42], times: 7, gap: 0.22}   # quick clicks in one place
+    - type: "arc"                      # keyboard; press: Escape
+    - scroll: {dy: 600, at: "Patches"}
+    - wait: 1.5                        # seconds
+    - wait_for: "Starting on Frame"    # until something with that name shows (timeout 15 s)
+    - settle: true                     # until the picture stops changing
+    - park: true                       # pointer to a place that hovers nothing
+    - hook: fake_install               # or {name: fake_install, args: [${game}]}: see HOOKS
+
+`${name}` in any string is replaced from the file's `vars:`.
+"""
+from __future__ import annotations
+
+import asyncio
+import re
+import threading
+import time
+
+from showcase import fakes
+
+POINTER = {"hover", "move", "click", "right_click", "double_click"}
+ACTIONS = POINTER | {"clicks", "nav", "go", "open_game", "call", "pop_dialog", "theme", "drag", "type", "press",
+                     "scroll", "wait", "wait_for", "settle", "park", "hook"}
+
+
+class StepError(ValueError):
+    pass
+
+
+def substitute(value, variables: dict):
+    """${name} → variables[name] in every string of a step (a whole-string reference keeps the value's type)."""
+    if isinstance(value, str):
+        m = re.fullmatch(r"\$\{(\w+)\}", value)
+        if m:
+            if m.group(1) not in variables:
+                raise StepError(f"unknown variable ${{{m.group(1)}}}")
+            return variables[m.group(1)]
+
+        def one(m):
+            if m.group(1) not in variables:
+                raise StepError(f"unknown variable ${{{m.group(1)}}}")
+            return str(variables[m.group(1)])
+        return re.sub(r"\$\{(\w+)\}", one, value)
+    if isinstance(value, list):
+        return [substitute(v, variables) for v in value]
+    if isinstance(value, dict):
+        return {k: substitute(v, variables) for k, v in value.items()}
+    return value
+
+
+def validate(steps, where: str = "steps") -> None:
+    """Raises StepError for a malformed step list (checked before a render starts, and by the tests)."""
+    if not isinstance(steps, list):
+        raise StepError(f"{where}: a list of steps expected")
+    for i, step in enumerate(steps):
+        at = f"{where}[{i}]"
+        if not isinstance(step, dict) or len(step) != 1:
+            raise StepError(f"{at}: a step is a mapping with exactly one action, got {step!r}")
+        (action, value), = step.items()
+        if action not in ACTIONS:
+            raise StepError(f"{at}: unknown action {action!r} (known: {', '.join(sorted(ACTIONS))})")
+        if action == "hook":
+            name = value.get("name") if isinstance(value, dict) else value
+            if name not in HOOKS:
+                raise StepError(f"{at}: unknown hook {name!r} (known: {', '.join(sorted(HOOKS))})")
+        if action == "call" and not (isinstance(value, str) or isinstance(value, dict) and "fn" in value):
+            raise StepError(f"{at}: call needs a method name or {{fn, args}}")
+        if action == "drag" and not (isinstance(value, list) and len(value) >= 2):
+            raise StepError(f"{at}: drag needs two or more targets")
+        if action in ("wait",) and not isinstance(value, (int, float)):
+            raise StepError(f"{at}: wait needs seconds")
+
+
+def _resolve(app, dotted: str):
+    obj = app
+    for part in dotted.split("."):
+        obj = getattr(obj, part)
+    return obj
+
+
+def run(session, steps: list, variables: dict | None = None, log=None) -> None:
+    """Run the steps on a web.Session. App calls run in this thread (the app serialises its own updates)."""
+    app = session.app
+    for step in substitute(steps, variables or {}):
+        (action, v), = step.items()
+        if log:
+            log(f"  {action}: {v}")
+        if action == "go":
+            app.go(v)
+        elif action == "open_game":
+            if isinstance(v, dict):
+                app.open_game(v["package"], advanced=bool(v.get("advanced")))
+            else:
+                app.open_game(v)
+        elif action == "call":
+            fn, args = (v, []) if isinstance(v, str) else (v["fn"], v.get("args") or [])
+            method = _resolve(app, fn)
+            if asyncio.iscoroutinefunction(method):  # (e.g. a FilePicker flow): the page's loop runs it
+                app.page.run_task(method, *args)
+            else:
+                method(*args)
+        elif action == "nav":
+            _nav(session, v, log)
+        elif action == "pop_dialog":
+            app.page.pop_dialog()
+        elif action == "theme":
+            from frameport.core import library
+
+            library.set_setting("ui.theme", v)
+            app.restyle(v)
+        elif action in POINTER:
+            if action in ("hover", "move"):
+                session.move(v)
+            elif action == "click":
+                session.click(v)
+            elif action == "right_click":
+                session.click(v, button="right")
+            else:
+                session.click(v)
+                session.sleep(0.08)
+                session.page.mouse.down()
+                session.page.mouse.up()
+        elif action == "clicks":  # quick clicks in one place (each shows the click ring)
+            session.move(v["at"])
+            for _ in range(int(v.get("times", 2))):
+                session.sleep(float(v.get("gap", 0.22)))
+                session.page.mouse.down()
+                session.sleep(0.05)
+                session.page.mouse.up()
+        elif action == "drag":
+            session.drag(v)
+        elif action == "type":
+            session.type(v)
+        elif action == "press":
+            session.press(v)
+        elif action == "scroll":
+            session.scroll(v.get("dy", 300), v.get("at"))
+        elif action == "wait":
+            session.sleep(float(v))
+        elif action == "wait_for":
+            session.find(v, timeout=15)
+        elif action == "settle":
+            session.settle(**({} if v is True else {k: w for k, w in v.items() if k in ("timeout",)}))
+        elif action == "park":
+            session.park()
+        elif action == "hook":
+            name, args = (v, []) if isinstance(v, str) else (v["name"], v.get("args") or [])
+            HOOKS[name](session, *args)
+
+
+def _nav(session, label: str, log=None) -> None:
+    """Click a sidebar tab like a person, then make sure the page really changed: its heading shows in the content
+    area. A click whose handler died would otherwise leave the old page in the picture for the rest of a recording
+    (seen on CI before property writes took FLET_LOCK; kept as a safety net): then the route is opened directly and
+    a WARN line printed."""
+    from frameport.ui import app as app_module
+    from showcase.web import Box, NotFound
+
+    keys = {str(lbl).casefold(): key for key, lbl, _icon in app_module.NAV}
+    key = keys.get(label.casefold())
+    if key is None:
+        raise StepError(f"nav: {label!r} is not a sidebar tab ({', '.join(sorted(keys))})")
+    session.click(label)
+    vw, _vh = session.viewport
+    content = Box(260, 0, vw - 260, 160)  # right of the sidebar, the page's title row
+    for _ in range(2):
+        try:
+            session.find(label, within=content, timeout=2.5)
+            return
+        except NotFound:
+            print(f"WARN nav {label}: the page didn't change after the click, opening it directly", flush=True)
+            session.app.go(key)
+    session.find(label, within=content, timeout=2.5)
+
+
+# ------------------------------------------------------------------ hooks: the pretend Frame's scripted events
+
+def _fake_install(session, package: str, pace: float = 1.0, wait: bool = False) -> None:
+    """Install `package` on the pretend Frame through the real job queue (every real stage, an upload, a passing
+    launch test). wait: until it's done."""
+    app = session.app
+    app.submit(f"Install {app._title(package)} on Frame", fakes.install_job(package, pace), package, "install",
+               to="frame")
+    if wait:
+        _wait_jobs(session)
+
+
+def _wait_jobs(session, timeout: float = 60) -> None:
+    deadline = time.time() + timeout
+    session.sleep(0.5)
+    while time.time() < deadline and any(j.active for j in session.app.jobs.jobs):
+        session.sleep(0.3)
+
+
+def _held_install(session, package: str, fraction: float = 0.62) -> None:
+    """An install held mid-upload: the transit in the sidebar, the game page and Activity. It stays there until the
+    window closes (Session.close cancels it)."""
+    from frameport.ui.jobs import Job
+
+    app, reached = session.app, threading.Event()
+
+    def run(job):
+        rep = job.reporter
+        for stage in fakes.FAKE_INSTALL_STAGES:
+            rep.stage(stage)
+        time.sleep(0.3)  # past the job queue's notification throttle
+        rep.progress(fraction, f"{package}.apk", speed="36.4 MB/s · ~1 min left")
+        reached.set()
+        while True:
+            rep.check_cancel()
+            time.sleep(0.2)
+
+    app.jobs.submit(Job(f"Install {app._title(package)} on Frame", run, package, "install"))
+    reached.wait(10)
+
+
+def _live_stream(session) -> None:
+    fakes.fake_live_stream(session.app)
+
+
+def _stop_live(session) -> None:
+    fakes.stop_fake_live(session.app)
+
+
+def _monitor_details(session) -> None:
+    fakes.open_monitor_details(session.app)
+
+
+def _type_tab(session) -> None:
+    fakes.open_type_tab(session.app)
+
+
+def _select_files(session, first: int = 1, count: int = 2) -> None:
+    v = session.app.files_view
+    for e in v.entries[first:first + count]:
+        v._toggle(e.path, True)
+
+
+def _disconnect(session) -> None:
+    """The sidebar as before connecting (the tour connects in front of the camera)."""
+    app = session.app
+    app.target, app.frame_info, app.frame_state = None, None, "none"
+    app._refresh_sidebar()
+    app.refresh_view()
+
+
+def _connect(session, delay: float = 1.0) -> None:
+    """Connecting… then connected to the pretend Frame (the live card starts streaming)."""
+    app = session.app
+    app.frame_state = "connecting"
+    app._refresh_sidebar()
+    session.sleep(delay)
+    fakes.attach_fake_frame(app, session.server.monitor_session)
+    app.refresh_view()
+    app._refresh_sidebar()
+
+
+def _settings_section(session, key: str) -> None:
+    """Settings, scrolled to one section (its index entry)."""
+    app = session.app
+    app.go("settings")
+    session.sleep(1.0)  # mounted first: scrolling an unmounted column does nothing
+    app.page.run_task(app.settings_view.show_section, key)
+
+
+def _first_run(session, folder: str = "D:/Games", pace: float = 1.0, tools_missing: bool = True,
+               tools_delay: float = 4.0) -> None:
+    """FramePort's first start (the "fresh" demo profile): the welcome screen's tool download is the pretend one
+    (fakes.tools_job; it waits `tools_delay` s so filming catches it from the start), and "Scan a folder…" scans
+    `folder` at once instead of opening the native folder picker (a script can't drive it): the demo games appear
+    one by one."""
+    import json
+
+    from frameport.core.paths import user_data_dir
+
+    app = session.app
+    fakes.TOOLS["ready"] = not tools_missing
+    app.update_tools = lambda update=False, quiet=False: fakes.tools_job(app, pace, tools_delay)
+    entries = json.loads((user_data_dir() / "showcase-scan.json").read_text())
+    app.pick_folder = lambda e=None: fakes.scan_job(app, folder, entries, pace)
+    app.welcome_started = False
+    app.library_view = None  # (a Library built already would keep the real folder picker)
+
+
+def _pairing_done(session, delay: float = 1.5) -> None:
+    """The Frame ran the setup command: FramePort hears from it and connects (the pretend Frame)."""
+    app = session.app
+    if app.pairing is not None:
+        app.pairing.stop()
+    _connect(session, delay)
+
+
+def _easter_eggs(session, on: bool = True, today: str = "", installs: int | None = None) -> None:
+    """The app's easter eggs (ui/easter.py) on or off (the demo library has them off). today: pretend this date
+    (YYYY-MM-DD: the holiday badges); installs: the install count so far (the next install may be a milestone).
+    The window's shell is rebuilt, so the sidebar logo picks it up."""
+    import os
+
+    from frameport.core import library
+    from frameport.ui import easter
+    from frameport.ui import theme as T
+
+    library.set_setting(easter.SETTING, bool(on))
+    if today:
+        os.environ["FRAMEPORT_TODAY"] = today
+    if installs is not None:
+        before = [f"demo.installed.{i}" for i in range(int(installs))]  # that many different games so far
+        library.set_setting(easter.INSTALLS, before)
+        library.set_setting(easter.SHOWN, [m for m in easter.MILESTONES if m <= len(before)])
+    session.app.restyle(T.THEME)
+
+
+def _fps_dip(session, fps: float = 58.0, seconds: float = 6.0) -> None:
+    """The pretend game stutters: the stream reports `fps` for `seconds` (the Monitor's frame-rate moods)."""
+    fakes.FakeMonitorSession.DIP = (time.time() + seconds, fps)
+
+
+def _perfect_pacing(session, needed: float = 6.0, seconds: float = 60.0) -> None:
+    """The pretend game runs right on target for `seconds`, and `needed` seconds of that count as the Monitor's
+    "full minute" (the perfect-pacing easter egg on film)."""
+    from frameport.ui import easter
+
+    easter.PERFECT_SECONDS = float(needed)
+    fakes.FakeMonitorSession.PERFECT = time.time() + seconds
+
+
+def _battery(session, percent: int = 99, plugged: bool = True) -> None:
+    """The pretend Frame's battery from now on (the card's fully-charged sparkle: 99 then 100 on the charger)."""
+    fakes.FakeMonitorSession.BATTERY = {"percent": int(percent), "status": "Charging" if plugged else "Discharging",
+                                        "plugged": bool(plugged), "draining": not plugged,
+                                        "watts": 6.5 if plugged else -1.96}
+
+
+def _long_upload(session, package: str, seconds: float = 30.0, after: float = 2.0, every: float = 3.5) -> None:
+    """An install whose upload runs `seconds` (progress ticking 4x a second); the transit's long-upload hop starts
+    after `after` seconds instead of five minutes, every `every` seconds. It finishes like a real install."""
+    from frameport.ui import easter
+    from frameport.ui.jobs import Job
+
+    easter.HOP_AFTER, easter.HOP_EVERY = float(after), float(every)
+    app = session.app
+
+    def run(job):
+        rep = job.reporter
+        for stage in fakes.FAKE_INSTALL_STAGES[:-1]:
+            rep.stage(stage)
+            time.sleep(0.15)
+        rep.stage("Upload data (3 files)")
+        steps = max(1, int(seconds * 4))
+        for i in range(1, steps + 1):
+            rep.check_cancel()
+            f = i / steps
+            left = (1 - f) * seconds * 60
+            rep.progress(f, f"main.1.{package}.obb", speed=f"11.2 MB/s · ~{left / 60:.0f} min left")
+            time.sleep(0.25)
+        rep.stage("Finalize install")
+        time.sleep(0.6)
+        return "done"
+
+    app.jobs.submit(Job(f"Install {app._title(package)} on Frame", run, package, "install"))
+
+
+def _press_keys(session, text: str, gap: float = 0.28) -> None:
+    """Keys typed on the Type on Frame tab (the pretend keyboard), one by one."""
+    view = session.app.keyboard_view
+    for ch in text:
+        view.press("Space" if ch == " " else ch.upper())
+        session.sleep(gap)
+
+
+HOOKS = {"fake_install": _fake_install, "wait_jobs": _wait_jobs, "held_install": _held_install,
+         "live_stream": _live_stream, "stop_live": _stop_live, "monitor_details": _monitor_details,
+         "type_tab": _type_tab, "select_files": _select_files, "disconnect": _disconnect, "connect": _connect,
+         "settings_section": _settings_section, "first_run": _first_run, "pairing_done": _pairing_done,
+         "easter_eggs": _easter_eggs, "fps_dip": _fps_dip, "perfect_pacing": _perfect_pacing,
+         "battery": _battery, "long_upload": _long_upload, "press_keys": _press_keys}
@@ -0,0 +1,536 @@
+"""Serve the real GUI in web mode with a pretend Frame and drive it with headless Chromium (Playwright), for docs
+screenshots and the demo tour.
+
+`Server(...).run(script)` owns the main thread (Flet's `ft.run` must) and runs `script(server)` in a thread; the
+script opens browser sessions with `server.session(...)`: one Playwright context + page and the FramePortApp that
+page started (one app per browser session). Elements are found by name through Flutter's semantics tree (the
+accessibility DOM Flutter web builds on request): visible text, a tooltip or a semantics label; the pointer events
+still go to Flutter's canvas, so hover effects and gestures behave as with a real mouse.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import queue
+import socket
+import threading
+import time
+import traceback
+from dataclasses import dataclass
+from pathlib import Path
+
+import flet as ft
+
+from frameport.ui.app import FramePortApp
+from showcase import fakes
+
+PORT = int(os.environ.get("FRAMEPORT_SHOWCASE_PORT", "8571"))
+CHROMIUM_ARGS = ["--use-gl=swiftshader", "--enable-unsafe-swiftshader", "--font-render-hinting=none"]
+REPO = Path(__file__).resolve().parents[2]
+
+# Flutter builds its semantics DOM only once something asks for it (a screen reader): the placeholder button does.
+# The semantics nodes then sit above the canvas; with pointer-events off they don't take the mouse.
+_ENABLE_SEMANTICS = """() => {
+  const p = document.querySelector('flt-semantics-placeholder');
+  if (p) p.click();
+  if (!document.getElementById('fp-sem-style')) {
+    const s = document.createElement('style');
+    s.id = 'fp-sem-style';
+    s.textContent = 'flt-semantics-host, flt-semantics, flt-semantics * { pointer-events: none !important; }';
+    document.head.appendChild(s);
+  }
+  return !!p;
+}"""
+
+# every named node: its own text, aria-label or the text of its children, with its box on screen
+_NODES = """() => [...document.querySelectorAll('flt-semantics')].map(e => {
+  const r = e.getBoundingClientRect();
+  const own = [...e.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join(' ').trim();
+  return {label: (e.getAttribute('aria-label') || '').trim(), text: own, all: (e.innerText || '').trim(),
+          role: e.getAttribute('role') || '', tappable: e.hasAttribute('flt-tappable'),
+          x: r.x, y: r.y, w: r.width, h: r.height};
+}).filter(n => n.w > 0 && n.h > 0)"""
+
+# the visible pointer for recordings (headless Chromium draws none): an arrow that follows the mouse, a ring on press
+CURSOR_JS = """(() => {
+  if (window.__fpCursor) return;
+  window.__fpCursor = true;
+  const add = () => {
+    const c = document.createElement('div');
+    c.id = 'fp-cursor';
+    c.innerHTML = '<svg width="28" height="28" viewBox="0 0 28 28"><path d="M4 2 L4 22 L9.5 17 L13 25 L16.5 23.5 ' +
+      'L13 15.8 L20.5 15.8 Z" fill="#fff" stroke="#111" stroke-width="1.6" stroke-linejoin="round"/></svg>';
+    Object.assign(c.style, {position: 'fixed', left: '-40px', top: '-40px', width: '28px', height: '28px',
+      pointerEvents: 'none', zIndex: 2147483647, filter: 'drop-shadow(0 2px 3px rgba(0,0,0,.45))',
+      transform: 'translate(-3px,-2px)'});
+    document.documentElement.appendChild(c);
+    const ring = (x, y) => {
+      const r = document.createElement('div');
+      Object.assign(r.style, {position: 'fixed', left: (x - 18) + 'px', top: (y - 18) + 'px', width: '36px',
+        height: '36px', borderRadius: '50%', border: '3px solid rgba(255,140,40,.95)', pointerEvents: 'none',
+        zIndex: 2147483646, transition: 'transform .45s ease-out, opacity .45s ease-out', transform: 'scale(.4)',
+        opacity: '1'});
+      document.documentElement.appendChild(r);
+      requestAnimationFrame(() => { r.style.transform = 'scale(1.5)'; r.style.opacity = '0'; });
+      setTimeout(() => r.remove(), 600);
+    };
+    const move = e => { c.style.left = e.clientX + 'px'; c.style.top = e.clientY + 'px'; };
+    window.addEventListener('pointermove', move, true);
+    window.addEventListener('mousemove', move, true);
+    window.addEventListener('pointerdown', e => ring(e.clientX, e.clientY), true);
+  };
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', add); else add();
+})();"""
+
+
+@dataclass
+class Box:
+    x: float
+    y: float
+    w: float
+    h: float
+
+    @property
+    def center(self) -> tuple[float, float]:
+        return self.x + self.w / 2, self.y + self.h / 2
+
+
+class NotFound(LookupError):
+    pass
+
+
+def names_of(node: dict) -> list[str]:
+    """What a semantics node is called: its label (tooltip), its own text and each line of its children's text
+    (a card reads "Click to open…\\nQuest\\nBatman: Arkham Shadow\\nWorks")."""
+    out = [node.get("label") or "", node.get("text") or ""]
+    for key in ("label", "text", "all"):
+        out += (node.get(key) or "").splitlines()
+    return [s.strip().casefold() for s in out if s and s.strip()]
+
+
+def _contains(outer: dict, inner: dict) -> bool:
+    """outer's box holds inner's centre and is bigger: a container of inner (a list around its row)."""
+    cx, cy = inner["x"] + inner["w"] / 2, inner["y"] + inner["h"] / 2
+    return (outer["x"] <= cx <= outer["x"] + outer["w"] and outer["y"] <= cy <= outer["y"] + outer["h"]
+            and outer["w"] * outer["h"] > inner["w"] * inner["h"] * 1.2)
+
+
+def innermost(nodes: list[dict]) -> list[dict]:
+    """The nodes that don't contain another one of them (a list's text includes its rows': the row wins)."""
+    return [n for n in nodes if not any(m is not n and _contains(n, m) for m in nodes)]
+
+
+def pick(nodes: list[dict], name: str, nth: int = 0, exact: bool | None = None) -> dict | None:
+    """The nth node called `name`: exact names first, then names starting with it, then containing it (unless
+    exact). Tappable nodes (buttons, cards) win, top to bottom and left to right; else the plain text itself, i.e.
+    the smallest node (the containers around it carry its text too)."""
+    want = name.strip().casefold()
+    tests = [lambda s: s == want]
+    if not exact:
+        tests += [lambda s: s.startswith(want), lambda s: want in s]
+    for test in tests:
+        hits = [n for n in nodes if any(test(s) for s in names_of(n))]
+        tappable = innermost([n for n in hits if n.get("tappable")])
+        if tappable:
+            tappable.sort(key=lambda n: (round(n["y"]), round(n["x"]), n["w"] * n["h"]))
+            return tappable[nth] if nth < len(tappable) else None
+        if hits:
+            hits.sort(key=lambda n: (n["w"] * n["h"], round(n["y"]), round(n["x"])))
+            return hits[nth] if nth < len(hits) else None
+    return None
+
+
+def ease(t: float) -> float:
+    """Ease-in-out (smoothstep of a smoothstep): slow start, fast middle, gentle landing."""
+    t = max(0.0, min(1.0, t))
+    t = t * t * (3 - 2 * t)
+    return t * t * (3 - 2 * t)
+
+
+def human_path(start: tuple[float, float], end: tuple[float, float], steps: int, bend: float = 0.12
+               ) -> list[tuple[float, float]]:
+    """Points from start to end along a slight arc (a quadratic Bezier whose control point sits `bend` of the
+    distance off the straight line), spaced by `ease`: the path a hand takes, not a ruler line."""
+    (x0, y0), (x1, y1) = start, end
+    dx, dy = x1 - x0, y1 - y0
+    dist = math.hypot(dx, dy)
+    cx, cy = (x0 + x1) / 2 - dy * bend, (y0 + y1) / 2 + dx * bend  # perpendicular offset
+    if dist < 1:
+        return [end] * max(1, steps)
+    out = []
+    for i in range(1, steps + 1):
+        t = ease(i / steps)
+        out.append(((1 - t) ** 2 * x0 + 2 * (1 - t) * t * cx + t * t * x1,
+                    (1 - t) ** 2 * y0 + 2 * (1 - t) * t * cy + t * t * y1))
+    return out
+
+
+def move_duration(dist: float) -> float:
+    """Seconds for a pointer hop of `dist` px: ~0.45 s for short hops, up to ~0.9 s across the window."""
+    return max(0.35, min(0.9, 0.3 + dist / 1800))
+
+
+class Session:
+    """One browser page showing one FramePortApp."""
+
+    def __init__(self, server: Server, ctx, page, app: FramePortApp, cursor: bool):
+        self.server, self.ctx, self.page, self.app = server, ctx, page, app
+        self.mouse_at = (0.0, 0.0)
+        self.cursor = cursor
+        self.semantics = False
+        self.browser = None
+        self.park_at: tuple[float, float] | None = None
+
+    def sleep(self, seconds: float) -> None:
+        """Wait while the browser keeps going (Playwright's event loop runs, so a screencast keeps its frames)."""
+        if seconds > 0:
+            self.page.wait_for_timeout(seconds * 1000)
+
+    # ------------------------------------------------------------ finding things
+    def enable_semantics(self) -> None:
+        if not self.semantics:
+            self.semantics = bool(self.page.evaluate(_ENABLE_SEMANTICS))
+            self.sleep(0.5)
+
+    def nodes(self) -> list[dict]:
+        self.enable_semantics()
+        return self.page.evaluate(_NODES)
+
+    def find(self, name: str, within: Box | None = None, nth: int = 0, exact: bool | None = None,
+             timeout: float = 8.0) -> Box:
+        """The box of the element called `name` (its text, tooltip or label; exact match first, then the start of
+        the text, then anywhere in it), optionally inside `within`; the smallest tappable one wins ties. Waits up
+        to `timeout` s for it to appear."""
+        deadline = time.monotonic() + timeout
+        while True:
+            vw, vh = self.viewport
+            nodes = [n for n in self.nodes() if 0 <= n["x"] + n["w"] / 2 <= vw and 0 <= n["y"] + n["h"] / 2 <= vh]
+            if within:
+                nodes = [n for n in nodes if within.x <= n["x"] + n["w"] / 2 <= within.x + within.w
+                         and within.y <= n["y"] + n["h"] / 2 <= within.y + within.h]
+            hit = pick(nodes, name, nth, exact)
+            if hit:
+                return Box(hit["x"], hit["y"], hit["w"], hit["h"])
+            if time.monotonic() > deadline:
+                raise NotFound(f"no element named {name!r} on screen")
+            self.sleep(0.3)
+
+    def dialog(self, timeout: float = 8.0) -> Box:
+        """The box of the topmost open dialog (Flutter labels a dialog's surface "Alert")."""
+        deadline = time.monotonic() + timeout
+        while True:
+            boxes = [n for n in self.nodes() if n["label"] == "Alert"]
+            if boxes:
+                n = boxes[-1]
+                return Box(n["x"], n["y"], n["w"], n["h"])
+            if time.monotonic() > deadline:
+                raise NotFound("no dialog open")
+            self.sleep(0.3)
+
+    def exists(self, name: str, timeout: float = 0.0) -> bool:
+        try:
+            self.find(name, timeout=timeout)
+            return True
+        except NotFound:
+            return False
+
+    @property
+    def viewport(self) -> tuple[int, int]:
+        v = self.page.viewport_size
+        return v["width"], v["height"]
+
+    # ------------------------------------------------------------ the pointer
+    def point(self, target) -> tuple[float, float]:
+        """A target: a name (see find), a Box, an (x, y) pair, or {"name": …, "dx": …, "dy": …, "nth": …}
+        (dx/dy: offset from the box's centre in px, or as a fraction of its size when |d| < 1)."""
+        if isinstance(target, (tuple, list)) and len(target) == 2 and all(isinstance(v, (int, float)) for v in target):
+            return float(target[0]), float(target[1])
+        if isinstance(target, Box):
+            return target.center
+        if isinstance(target, str):
+            return self.find(target).center
+        if isinstance(target, dict):
+            box = self.find(target["name"], nth=target.get("nth", 0), exact=target.get("exact"))
+            cx, cy = box.center
+            dx, dy = target.get("dx", 0), target.get("dy", 0)
+            dx = dx * box.w if abs(dx) < 1 else dx
+            dy = dy * box.h if abs(dy) < 1 else dy
+            return cx + dx, cy + dy
+        raise TypeError(f"not a target: {target!r}")
+
+    def move(self, target, duration: float | None = None, smooth: bool = True) -> tuple[float, float]:
+        x, y = self.point(target)
+        if not smooth:
+            self.page.mouse.move(x, y)
+        else:
+            dist = math.hypot(x - self.mouse_at[0], y - self.mouse_at[1])
+            duration = move_duration(dist) if duration is None else duration
+            steps = max(2, int(duration * 60))
+            t0 = time.monotonic()
+            for i, (px, py) in enumerate(human_path(self.mouse_at, (x, y), steps)):
+                self.page.mouse.move(px, py)
+                wait = t0 + duration * (i + 1) / steps - time.monotonic()
+                if wait > 0:
+                    self.sleep(wait)
+        self.mouse_at = (x, y)
+        return x, y
+
+    def click(self, target, button: str = "left", smooth: bool = True, pause: float = 0.15) -> None:
+        self.move(target, smooth=smooth)
+        if isinstance(target, (str, dict)):  # the layout moved while the pointer travelled (a list reloaded): follow
+            x, y = self.point(target)
+            if math.hypot(x - self.mouse_at[0], y - self.mouse_at[1]) > 6:
+                self.move((x, y), duration=0.25)
+        self.sleep(pause)
+        self.page.mouse.down(button=button)
+        self.sleep(0.07)
+        self.page.mouse.up(button=button)
+
+    def drag(self, points: list, smooth: bool = True) -> None:
+        self.move(points[0], smooth=smooth)
+        self.sleep(0.2)
+        self.page.mouse.down()
+        for p in points[1:]:
+            self.move(p, smooth=smooth, duration=0.6)
+            self.sleep(0.2)
+        self.page.mouse.up()
+
+    def type(self, text: str, delay: float = 0.11) -> None:
+        self.page.keyboard.type(text, delay=int(delay * 1000))
+
+    def press(self, key: str) -> None:
+        self.page.keyboard.press(key)
+
+    def scroll(self, dy: float, at=None) -> None:
+        if at is not None:
+            self.move(at)
+        for _ in range(max(1, int(abs(dy) // 100))):
+            self.page.mouse.wheel(0, 100 if dy > 0 else -100)
+            self.sleep(0.05)
+
+    def park(self, away: bool = False) -> None:
+        """The pointer somewhere it hovers nothing: the sidebar's empty part (videos: the drawn cursor stays in the
+        picture), or with `away` off the page (still pictures: nothing hovered, whatever the layout)."""
+        if away:
+            self.page.mouse.move(-40, -40)
+            self.mouse_at = (-40.0, -40.0)
+            return
+        if self.park_at is None:  # just below the sidebar's last tab (Settings): nothing there takes the pointer
+            try:
+                tab = self.find("Settings", timeout=3)
+                self.park_at = (tab.x + tab.w * 0.6, tab.y + tab.h + 44)
+            except NotFound:
+                self.park_at = self.server.park_point(self.viewport)
+        self.page.mouse.move(*self.park_at)
+        self.mouse_at = self.park_at
+
+    # ------------------------------------------------------------ pictures
+    def settle(self, timeout: float = 8.0, interval: float = 0.15, quiet: int = 4, mask: list[Box] = ()) -> bool:
+        """Wait until the page stops changing: `quiet` screenshots in a row (interval apart) are identical (masked
+        boxes, e.g. a live chart, ignored). False when it was still changing at `timeout`."""
+        deadline, last, same = time.monotonic() + timeout, None, 0
+        while time.monotonic() < deadline:
+            png = self._raw(mask)
+            same = same + 1 if png == last else 0
+            if same >= quiet:
+                return True
+            last = png
+            self.sleep(interval)
+        return False
+
+    def _raw(self, mask: list[Box] = ()) -> bytes:
+        if not mask:
+            return self.page.screenshot(animations="disabled", caret="hide")
+        from io import BytesIO
+
+        from PIL import Image, ImageDraw
+
+        im = Image.open(BytesIO(self.page.screenshot(caret="hide")))
+        d = ImageDraw.Draw(im)
+        for b in mask:
+            d.rectangle((b.x, b.y, b.x + b.w, b.y + b.h), fill=(0, 0, 0))
+        return im.tobytes()
+
+    def shot(self, path: Path, clip: Box | None = None, settle: bool = True) -> Path:
+        if settle:
+            self.settle()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        kw = {"clip": {"x": clip.x, "y": clip.y, "width": clip.w, "height": clip.h}} if clip else {}
+        self.page.screenshot(path=str(path), caret="hide", **kw)
+        return path
+
+    def close(self) -> None:
+        """Close the window and leave nothing behind for the next one: the job queue is shared by every session
+        (a pretend install would show in the next window's Activity), the live stream's ffmpeg and the monitor
+        stream would run on, and a closed page must not get job events."""
+        app = self.app
+        try:
+            app.jobs.unsubscribe(app._on_job)
+            for job in list(app.jobs.jobs):
+                if job.active:
+                    app.jobs.cancel(job)
+            deadline = time.monotonic() + 5
+            while any(j.active for j in app.jobs.jobs) and time.monotonic() < deadline:
+                self.sleep(0.1)
+            app.jobs.clear_finished()
+            fakes.stop_fake_live(app)
+            app.stop_monitor()
+        except Exception:  # noqa: BLE001
+            pass
+        for thing in (self.ctx, self.browser):
+            try:
+                if thing is not None:
+                    thing.close()
+            except Exception:  # noqa: BLE001
+                pass
+
+
+class Server:
+    """The GUI on 127.0.0.1:PORT (web mode) with fakes installed; `run(script)` serves until the script returns."""
+
+    def __init__(self, port: int = PORT, fake_frame: bool = True, monitor_session=None, game: str | None = None,
+                 scale: float = 1.0):
+        self.port, self.fake_frame, self.scale = port, fake_frame, scale
+        self.monitor_session = monitor_session or fakes.FakeMonitorSession
+        self.apps: queue.Queue = queue.Queue()
+        self.errors: list[str] = []
+        self.playwright = None
+        self.game = game
+
+    def park_point(self, viewport: tuple[int, int]) -> tuple[float, float]:
+        return 130 * self.scale, viewport[1] * 0.62
+
+    def _app_main(self, page: ft.Page) -> None:
+        try:
+            app = FramePortApp(page)
+            if self.fake_frame:
+                fakes.attach_fake_frame(app, self.monitor_session)
+        except Exception:  # noqa: BLE001
+            self.errors.append("startup: " + traceback.format_exc())
+            return
+        self.apps.put(app)
+
+    def session(self, viewport: tuple[int, int], cursor: bool = False, video_dir: Path | None = None,
+                device_scale: float = 1.0) -> Session:
+        """A new browser context + page (fresh app). `video_dir`: Playwright's own recorder (fallback capture)."""
+        while not self.apps.empty():  # apps from sessions already closed
+            self.apps.get_nowait()
+        kw = {}
+        if video_dir is not None:
+            kw = {"record_video_dir": str(video_dir), "record_video_size": {"width": viewport[0],
+                                                                           "height": viewport[1]}}
+        # a browser of its own per window: windows sharing one browser (its GPU process) sometimes drew text with
+        # glyphs from the wrong place ("/sdcard/ʍvies")
+        browser = self.playwright.chromium.launch(args=CHROMIUM_ARGS)
+        # (clipboard: the Screenshots tab's Copy image writes an image to the browser's clipboard in web mode)
+        ctx = browser.new_context(viewport={"width": viewport[0], "height": viewport[1]},
+                                  device_scale_factor=device_scale, permissions=["clipboard-read", "clipboard-write"],
+                                  **kw)
+        if cursor:
+            ctx.add_init_script(CURSOR_JS)
+        page = ctx.new_page()
+        page.goto(f"http://127.0.0.1:{self.port}", wait_until="networkidle", timeout=120_000)
+        app = self.apps.get(timeout=120)
+        s = Session(self, ctx, page, app, cursor)
+        s.browser = browser
+        # web fonts: text measured before they load wraps or overlaps ("Q / uest"): a text-heavy first screen (the
+        # Settings page) takes them before the steps start
+        s.sleep(1.0)
+        app.go("settings")
+        s.sleep(2.0)
+        s.enable_semantics()
+        s.park()
+        return s
+
+    def run(self, script) -> int:
+        """Serve; `script(server) -> exit code` runs in a thread with the browser ready; the process ends with it."""
+        from frameport.ui.app import serialize_flet_updates
+
+        serialize_flet_updates()  # as the app's main() does: patches and property writes don't interleave
+        if self.fake_frame:
+            fakes.install_fakes(self.game, self.monitor_session)
+
+        def runner():
+            from playwright.sync_api import sync_playwright
+
+            for _ in range(90):
+                try:
+                    socket.create_connection(("127.0.0.1", self.port), timeout=1).close()
+                    break
+                except OSError:
+                    time.sleep(1)
+            time.sleep(1.5)
+            code = 1
+            try:
+                with sync_playwright() as p:
+                    self.playwright = p
+                    code = script(self) or 0
+            except Exception:  # noqa: BLE001
+                self.errors.append("script: " + traceback.format_exc())
+            for e in self.errors:
+                print("ERROR", e, flush=True)
+            os._exit(1 if self.errors else code)
+
+        from frameport.ui.app import assets_dir
+
+        threading.Thread(target=runner, daemon=True).start()
+        ft.run(self._app_main, view=ft.AppView.WEB_BROWSER, port=self.port, assets_dir=assets_dir())
+        return 1
+
+
+class Screencast:
+    """The page's frames as Chrome paints them (CDP Page.startScreencast: JPEGs with timestamps), written to a folder.
+    Sharper than Playwright's own recorder (VP8 at a low bit rate). Chrome sends a frame only when the page changed,
+    so the frames come with their times and are turned into a constant frame rate later (postprod.frames_to_video).
+    Frames only arrive while Playwright runs (Session.sleep, mouse moves), never during time.sleep."""
+
+    def __init__(self, session: Session, folder: Path, quality: int = 92):
+        import base64
+
+        self._b64 = base64.b64decode
+        self.session, self.folder, self.quality = session, Path(folder), quality
+        self.folder.mkdir(parents=True, exist_ok=True)
+        self.frames: list[tuple[float, str]] = []  # (wall-clock time, file name)
+        self.cdp = session.ctx.new_cdp_session(session.page)
+        self.cdp.on("Page.screencastFrame", self._frame)
+        self.running = False
+
+    def _frame(self, params: dict) -> None:
+        name = f"{len(self.frames):06d}.jpg"
+        (self.folder / name).write_bytes(self._b64(params["data"]))
+        self.frames.append((float(params["metadata"].get("timestamp") or time.time()), name))
+        try:
+            self.cdp.send("Page.screencastFrameAck", {"sessionId": params["sessionId"]})
+        except Exception:  # noqa: BLE001  (stopping)
+            pass
+
+    def start(self) -> None:
+        vw, vh = self.session.viewport
+        scale = self.session.page.evaluate("window.devicePixelRatio") or 1
+        self.cdp.send("Page.startScreencast", {"format": "jpeg", "quality": self.quality,
+                                               "maxWidth": int(vw * scale), "maxHeight": int(vh * scale),
+                                               "everyNthFrame": 1})
+        self.running = True
+
+    def stop(self) -> None:
+        if self.running:
+            self.session.sleep(0.3)
+            self.cdp.send("Page.stopScreencast")
+            self.running = False
+
+    def write_index(self) -> Path:
+        """frames.json: [[time, file], …] for postprod."""
+        path = self.folder / "frames.json"
+        path.write_text(json.dumps(self.frames))
+        return path
+
+
+def call(session: Session, fn, *args, **kwargs):
+    """Run an app action from the script thread, logging (not raising) its errors so one broken step doesn't end a
+    whole render."""
+    try:
+        return fn(*args, **kwargs)
+    except Exception:  # noqa: BLE001
+        session.server.errors.append(f"{getattr(fn, '__name__', fn)}: " + traceback.format_exc())
+        return None
@@ -17,9 +17,22 @@ import time
 import traceback
 from pathlib import Path

+sys.path.insert(0, str(Path(__file__).resolve().parent))
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))

 import flet as ft  # noqa: E402
+from showcase.fakes import (  # noqa: E402,F401
+    LINUX_APPIMAGE,
+    LINUX_FOLDER,
+    add_fake_linux_apps,
+    attach_fake_frame,
+    fake_live_stream,
+    install_fakes,
+    open_monitor_details,
+    open_type_tab,
+    start_fake_install,
+    stop_fake_live,
+)

 from frameport.core import library  # noqa: E402
 from frameport.ui.app import FramePortApp  # noqa: E402
@@ -28,346 +41,6 @@ PORT = int(os.environ.get("FRAMEPORT_SMOKE_PORT", "8557"))  # two smoke runs at
 ERRORS: list[str] = []


-class FakeFS:
-    """--fake-frame's file system for the Files tab: a temp folder with sample files, served like SFTP."""
-
-    def __init__(self):
-        import tempfile
-
-        self.home = tempfile.mkdtemp(prefix="fp-fake-frame-")
-        samples = {"Videos": ["Earth from orbit (360).mp4", "Mars landing (VR180).mkv", "Concert 8K 3D.mp4"],
-                   "Downloads": ["Mods/", "readme.txt"], "Documents": ["Saves/", "Notes.pdf"]}
-        sizes = {".mp4": 2_400_000_000, ".mkv": 1_100_000_000}
-        for folder, names in samples.items():
-            base = os.path.join(self.home, folder)
-            os.makedirs(os.path.join(base, "Trips"), exist_ok=True)
-            for n in names:
-                if n.endswith("/"):
-                    os.makedirs(os.path.join(base, n), exist_ok=True)
-                else:
-                    with open(os.path.join(base, n), "wb") as f:
-                        f.truncate(sizes.get(os.path.splitext(n)[1], 48_000))  # sparse: no real disk use
-        self.shots = self._screenshots()
-
-    def _screenshots(self) -> list[dict]:
-        """Sample Steam screenshots for the Screenshots tab, two days, a few games + SteamVR: crops of the games' own
-        store art (hero/landscape) when the library has some (docs screenshots), else colour gradients."""
-        from PIL import Image, ImageOps
-
-        from frameport.artwork import fetch
-
-        folder = os.path.join(self.home, "shots")
-        os.makedirs(folder, exist_ok=True)
-        games = []
-        for g in library.games():
-            if g.get("kind") == "rift":
-                continue
-            # the store's own screenshots look like real captures; else hero/wide art
-            shots_art = sorted(fetch.artwork_dir(g["package"]).glob("shot_*.jpg"))
-            games.append((g, shots_art or [p for p in fetch.files(g["package"]) if p.stem in ("hero", "landscape")],
-                          bool(shots_art)))
-        games.sort(key=lambda ga: (not ga[2], -len(ga[1])))
-        owners = [(g["package"], g.get("title") or g["package"], arts) for g, arts, _real in games[:3]]
-        spare = games[3][1] if len(games) > 3 else []  # SteamVR's own shots (taken outside a FramePort game)
-        owners.append((None, "SteamVR", spare))
-        # the same days layout at any time of day (6 shots on the first day, 4 on the one before; --gestures drags
-        # across the first row): shortly after midnight the shots start the evening before
-        now, shots = time.time(), []
-        if time.localtime(now).tm_hour < 5:
-            now -= (time.localtime(now).tm_hour + 1) * 3600
-        for i in range(10):
-            t = now - i * 2400 - (86400 if i >= 6 else 0)
-            name = time.strftime("%Y%m%d%H%M%S", time.localtime(t)) + "_1.jpg"
-            path = os.path.join(folder, name)
-            pkg, title, arts = owners[i % len(owners)]
-            if arts:  # a different crop of the game's art per shot, so they don't all look alike
-                with Image.open(arts[i % len(arts)]) as src:
-                    src = src.convert("RGB")
-                    zoom = 1.0 + 0.15 * (i % 3) * (src.width < 2 * src.height)
-                    w, h = int(src.width / zoom), int(src.height / zoom)
-                    x, y = (src.width - w) * (i % 2), (src.height - h) // 2
-                    im = ImageOps.fit(src.crop((x, y, x + w, y + h)), (1280, 720))
-            else:
-                im = Image.linear_gradient("L").resize((640, 360)).convert("RGB")
-                im = Image.merge("RGB", (im.getchannel(0).point(lambda v, i=i: (v + 40 * i) % 256),
-                                         im.getchannel(1).point(lambda v: 255 - v), im.getchannel(2)))
-            im.save(path, "JPEG", quality=85)
-            shots.append({"path": path, "thumb": None, "time": int(t), "width": 1920, "height": 1080,
-                          "size": os.path.getsize(path), "account": "1", "appid": "250820", "package": pkg,
-                          "title": title})
-        return shots
-
-    def agent(self, command, **args):
-        if command == "storage_targets":
-            return {"targets": [{"id": n.lower(), "path": os.path.join(self.home, n), "android": a, "shared": True}
-                                for n, a in (("Videos", "/sdcard/Movies"), ("Downloads", "/sdcard/Download"),
-                                             ("Documents", "/sdcard/Documents"))]}
-        if command == "list_screenshots":
-            want = args.get("package")
-            shots = [s for s in self.shots if want is None or (s["package"] or "") == want]
-            games = {}
-            for s in self.shots:
-                games.setdefault(s["package"] or "", {"package": s["package"], "title": s["title"], "count": 0})
-                games[s["package"] or ""]["count"] += 1
-            return {"shots": shots, "total": len(shots), "games": list(games.values())}
-        raise RuntimeError(f"fake Frame: {command} not available")
-
-    @property
-    def sftp(self):
-        import paramiko
-
-        class SFTP:
-            def listdir_attr(self, path):
-                out = []
-                for name in sorted(os.listdir(path)):
-                    a = paramiko.SFTPAttributes.from_stat(os.lstat(os.path.join(path, name)))
-                    a.filename = name
-                    out.append(a)
-                return out
-
-            def stat(self, path):
-                return paramiko.SFTPAttributes.from_stat(os.stat(path))
-
-            def get(self, remote, local, callback=None):
-                import shutil
-
-                shutil.copyfile(remote, local)
-        return SFTP()
-
-
-class FakeTarget:
-    """--fake-frame: a pretend Steam Frame with the library's working Quest builds installed (no network, no device),
-    for documentation screenshots."""
-
-    def __init__(self, count: int = 8):
-        from frameport.frame.connection import parse_target
-
-        self.label = "steamframe"
-        self.frame = FakeFS()
-        self.target = parse_target("steamos@steamframe.local")
-        works = [g for g in library.games() if g.get("kind") != "rift" and (g.get("build") or {}).get("sha256")
-                 and (g.get("recipe") or {}).get("status") in ("works", "issues")]
-        works.sort(key=lambda g: -(g.get("data_bytes") or 0))
-        self.games = [{"package": g["package"], "kind": "quest", "title": g.get("title"),
-                       "apk_size": (g.get("data_bytes") or 0) + 2**28, "sha256": g["build"]["sha256"],
-                       "recipe": {"patches": (g.get("recipe") or {}).get("patches", [])}} for g in works[:count]]
-        # --linux: the AppImage is on the Frame, but SteamOS lacks one of its libraries
-        self.games += [{"package": g["package"], "kind": "linux", "title": g.get("title"), "apk_size": 2**26,
-                        "apk_present": True, "recipe": None, "exe": g.get("exe"),
-                        "missing_libraries": ["libwebkit2gtk-4.1.so.0"]}
-                       for g in library.games() if g.get("kind") == "linux" and g["package"] == LINUX_APPIMAGE]
-
-    def describe(self) -> dict:
-        return {"hostname": "steamframe", "os": "SteamOS", "os_version": "3.8", "build_id": "20260922",
-                "free_bytes": 312 * 2**30, "installed": self.games, "lepton": True,
-                "proton": {"ready": {"display_name": "Proton 11 (ARM64)"}, "openxr": {"name": "SteamVR"}},
-                "kernel_keys": {"keys": 31, "max_keys": 200}}
-
-    def installed(self) -> list[dict]:
-        return self.games
-
-    def close(self) -> None:
-        pass
-
-
-class FakeKeyboardSession:
-    """--fake-frame: Type on Frame connects at once (nothing is sent anywhere)."""
-
-    def __init__(self, frame):
-        self.closed = False
-
-    def key(self, name, action="down"):
-        return True
-
-    def text(self, text):
-        return ""
-
-    def close(self):
-        self.closed = True
-
-
-class FakeMonitorSession:
-    """--fake-frame: the Monitor tab's stream as synthetic samples, one per second, shaped like a real Quest game on
-    the dev Frame (2026-10-07): 72 fps, the game's Android container, SteamVR/Steam as context. Two minutes are sent
-    at once first, so the charts are full in screenshots. GAME = --game (else the library's first game)."""
-
-    GAME: str | None = None
-    BACKFILL = 120
-    # (name, group, CPU %, GPU %, memory); "GAME" = the game's package
-    PROCS = [("GAME", "game", 9.8, 44.0, 1_350_000_000), ("vrcompositor", "steamvr", 1.4, 9.0, 80_000_000),
-             ("system_server", "game", 1.1, 0.0, 296_000_000), ("XRServiceLoopTh", "steamvr", 0.5, 0.0, 433_000_000),
-             ("steamwebhelper", "steam", 0.4, 0.0, 350_000_000), ("com.android.systemui", "game", 0.1, 0.0,
-                                                                   229_000_000),
-             ("surfaceflinger", "game", 0.1, 0.4, 96_000_000), ("audioserver", "game", 0.1, 0.0, 31_000_000),
-             ("com.android.providers.media.module", "game", 0.1, 0.0, 130_000_000),
-             ("com.android.launcher3", "game", 0.0, 0.0, 194_000_000), ("main", "game", 0.0, 0.0, 178_000_000),
-             ("com.android.settings", "game", 0.0, 0.0, 172_000_000),
-             ("com.android.networkstack.process", "game", 0.0, 0.0, 130_000_000),
-             ("android.ext.services", "game", 0.0, 0.0, 111_000_000)] + \
-            [("vrwebhelper", "steamvr", 0.3, 0.0, 160_000_000 + i * 9_000_000) for i in range(4)]
-
-    def __init__(self, frame, on_sample, on_end=None):
-        import math
-
-        self.math, self.closed, self.on_sample = math, False, on_sample
-        self.static = {"agent": 62, "cores": 8, "gpu_max_mhz": 903, "mem_total": 16 * 1024 ** 3, "fan": True,
-                       "clusters": [{"cpus": [0, 1], "max_mhz": 2265}, {"cpus": [2, 3, 4], "max_mhz": 3148},
-                                    {"cpus": [5, 6], "max_mhz": 2956}, {"cpus": [7], "max_mhz": 3052}],
-                       "temp_groups": ["CPU", "GPU", "Memory", "Battery", "NPU", "Power ICs", "Modem", "Camera"]}
-        self.t = 0
-        threading.Thread(target=self._run, daemon=True).start()
-
-    def _sample(self) -> dict:
-        m, t = self.math, self.t
-        wave = lambda a, p, o=0: a * (1 + m.sin(t / p + o)) / 2  # noqa: E731
-        g = library.game(self.GAME) if self.GAME else (library.games() or [None])[0]
-        game = g or {"package": "com.example.game", "title": "Example Game"}
-        pkg = game["package"]
-        procs = [{"pid": 570799 + i * 37, "ppid": 1, "name": pkg if n == "GAME" else n,
-                  "group": f"game:{pkg}" if grp == "game" else grp, "game": pkg if grp == "game" else None,
-                  "cpu": round(c * (0.85 + wave(0.3, 3, i)), 1), "gpu": round(gp * (0.9 + wave(0.2, 5, i)), 1),
-                  "rss": r, "age": 1500 + t, "uid": 1000, "critical": grp in ("steamvr", "steam"), "locked": False,
-                  "context": grp != "game"}
-                 for i, (n, grp, c, gp, r) in enumerate(self.PROCS)]
-        return {
-            "t": time.time() - max(0, self.BACKFILL - t), "dt": 1.0, "self_ms": 11.5,
-            "cpu": {"total": round(15 + wave(4, 4), 1), "cores": [round(4 + wave(30, 3 + i, i), 1) for i in range(8)],
-                    "mhz": [2265, 1996, 1920, 518]},
-            "gpu": {"busy": round(52 + wave(8, 5), 1), "mhz": 903},
-            "mem": {"total": 15.3 * 1024 ** 3, "avail": int((8.3 - wave(0.15, 9)) * 1024 ** 3),
-                    "swap_total": 7.6 * 1024 ** 3, "swap_free": 7.4 * 1024 ** 3},
-            "psi": {"cpu": 1.0, "memory": 0.0, "io": 0.1},
-            "temps": {"CPU": round(48 + wave(1.5, 11), 1), "GPU": round(46.5 + wave(1, 13), 1), "Memory": 47.1,
-                      "Battery": 27.7, "NPU": 47.3, "Power ICs": 37.0, "Modem": 44.2, "Camera": 46.3},
-            "zones": {"CPU": {"cpu7-top": 48.4, "cpu0": 44.0}, "GPU": {"gpuss-0": 46.5}},
-            "fan": 8500 + int(wave(300, 7)),
-            "power": {"system": round(7.3 + wave(0.6, 4), 2), "cpu": 0.85, "gpu": round(1.0 + wave(0.3, 5), 2),
-                      "npu": 0.1},
-            "battery": {"percent": 95, "status": "Discharging", "plugged": False, "draining": True, "watts": -1.96,
-                        "empty_s": 22440},
-            "net": {"wlan0": [int(2000 + wave(4000, 3)), 1000], "wlanap": [0, 0], "usb0": [0, 0]},
-            "games": [{"package": pkg, "title": game.get("title") or pkg, "kind": "quest", "appid": 1,
-                       "elapsed": 1500 + t, "cpu": 9.4, "gpu": round(44 + wave(6, 5), 1), "mem": 3_390_000_000,
-                       "processes": 87, "fps": round(71.6 + wave(0.6, 2) - (9 if t % 41 == 30 else 0), 1),
-                       "frame_ms": 0.0}],
-            "procs": procs, "filter": "game"}
-
-    def _run(self) -> None:
-        self.t = 0
-        while not self.closed and self.t < 100000:
-            self.on_sample(self._sample())
-            if self.t >= self.BACKFILL:  # the first two minutes at once (full charts), then one per second
-                time.sleep(1)
-            self.t += 1
-
-    def set_modules(self, m):
-        # the hub asks for everything when the Monitor tab subscribes (the Frame card started the stream): send the
-        # two minutes again so its charts are full in screenshots too
-        if m == "all":
-            self.t = 0
-        return True
-
-    def set_interval(self, s): pass  # noqa: E704
-    def set_filter(self, w): pass  # noqa: E704
-    def pause(self, p): pass  # noqa: E704
-
-    def kill(self, pid, sig="TERM", force=False):
-        return {"ended": True, "pid": pid}
-
-    def end_game(self, package):
-        return {"ended": True, "via": "steam"}
-
-    def close(self):
-        self.closed = True
-
-
-FAKE_INSTALL_STAGES = ["Patching the game", "OVRPort (primary)", "Frame fixes (primary)", "sign (primary)",
-                       "validate (primary)", "Prepare Frame", "Upload APK"]
-
-
-def start_fake_install(app: FramePortApp, package: str) -> None:
-    """A running install job of `package` that reports the real stage names up to the upload (62 %) and then waits
-    (it never ends: the smoke run exits with it)."""
-    from frameport.ui.jobs import Job
-
-    hold, reached = threading.Event(), threading.Event()
-
-    def run(job):
-        for stage in FAKE_INSTALL_STAGES:
-            job.reporter.stage(stage)
-        time.sleep(0.3)  # past the job queue's notification throttle
-        job.reporter.progress(0.62, "com.example.apk", speed="36.4 MB/s · ~1 min left")
-        reached.set()
-        hold.wait()
-
-    app.jobs.submit(Job(f"Install {app._title(package)} on Frame", run, package, "install"))
-    reached.wait(10)
-
-
-def open_type_tab(app: FramePortApp) -> None:
-    """The Type on Frame tab, with one key 'pressed' so the screenshot shows it working."""
-    app.type_on_frame()
-    time.sleep(1.5)
-    app.keyboard_view.press("Enter")
-
-
-def open_monitor_details(app: FramePortApp) -> None:
-    """The Monitor with its details row open."""
-    app.go("monitor")
-    time.sleep(2)
-    if not app.monitor_view.details.visible:
-        app.monitor_view.toggle_details()
-
-
-LINUX_APPIMAGE = "linux.venera"  # --linux's packages
-LINUX_FOLDER = "linux.matineevr"
-
-
-def _elf(machine: int = 183, appimage: bool = False, extra: bytes = b"") -> bytes:
-    """A minimal ELF header (183 = aarch64): enough for FramePort's Linux app detection."""
-    head = bytearray(64)
-    head[:4], head[4], head[5] = b"\x7fELF", 2, 1
-    if appimage:
-        head[8:11] = b"AI\x02"
-    head[18:20] = machine.to_bytes(2, "little")
-    return bytes(head) + extra
-
-
-def add_fake_linux_apps() -> None:
-    """--linux: an AppImage and a VR app folder (with a helper program, so "Change program…" shows) in the library."""
-    from frameport import pipeline
-    from frameport.core.paths import user_data_dir
-
-    base = user_data_dir() / "smoke-linux"
-    app = base / "MatineeVR"
-    (app / "lib").mkdir(parents=True, exist_ok=True)
-    (base / "Venera-2.4.2-aarch64.AppImage").write_bytes(_elf(appimage=True, extra=b"\0" * 4096))
-    (app / "MatineeVR").write_bytes(_elf(extra=b"\0" * 8192))
-    (app / "crashpad_handler").write_bytes(_elf())
-    (app / "lib" / "libopenxr_loader.so.1").write_bytes(_elf(extra=b"xrCreateInstance"))
-    pipeline.add_linux_app(base / "Venera-2.4.2-aarch64.AppImage")
-    pipeline.add_linux_app(app)
-
-
-def install_fakes(game: str | None, monitor_session=None) -> None:
-    """--fake-frame: never reach a real Frame (start-up auto-connect, discovery, the 30 s poll); Type on Frame and
-    the Monitor stream are fakes. `game` = the Monitor's game card (with its artwork)."""
-    from frameport.frame import keyboard, monitor
-
-    keyboard.KeyboardSession = FakeKeyboardSession
-    monitor.MonitorSession = monitor_session or FakeMonitorSession
-    FakeMonitorSession.GAME = game
-    FramePortApp.connect = lambda self, *a, **k: None
-    FramePortApp.refresh_frame = lambda self, *a, **k: None
-
-
-def attach_fake_frame(app: FramePortApp, monitor_session=None) -> None:
-    """Connect `app` to a FakeTarget (the shared monitor stream, used by the Monitor tab and the Frame card, too)."""
-    app.monitor_hub.session_factory = monitor_session or FakeMonitorSession
-    app.target = FakeTarget()
-    app.frame_info, app.frame_state = app.target.describe(), "connected"
-
-
 PAINT_SECONDS = 3  # after a step, before its screenshot: Flutter paints (and a view's content loads)
 STEP_TIMEOUT = 240  # the longest a step may wait for its screenshot (a crashed browser mustn't hang the run)

@@ -426,7 +99,8 @@ def main() -> int:
    ap.add_argument("--no-test", action="store_true", help="with --frame: skip the launch-test job")
    ap.add_argument("--scale", type=float, default=1.0, help="UI scale to render at (e.g. 1.5)")
    ap.add_argument("--viewport", default="1280x820", help="browser size, e.g. 2560x1440")
-    ap.add_argument("--update", action="store_true", help="pretend a new FramePort release exists (update UI)")
+    ap.add_argument("--update", action="store_true", help="pretend a new FramePort release exists (update UI: "
+                    "changelog dialog, what's new bar + dialog, Settings changelog)")
    ap.add_argument("--fake-frame", action="store_true", help="pretend a Steam Frame is connected (no device needed)")
    ap.add_argument("--hover", default=None, help="x,y: move the mouse there before the Library screenshot")
    ap.add_argument("--install-questions", nargs="+", metavar="PKG", default=None,
@@ -456,7 +130,8 @@ def main() -> int:
    game = args.game or (library.games()[0]["package"] if library.games() else None)
    steps = [("library", lambda a: a.navigate(0)), ("frame", lambda a: a.navigate(1)),
             ("files", lambda a: a.go("files")), ("screenshots", lambda a: a.go("screenshots")),
-             ("live", lambda a: a.go("live")), ("keyboard", lambda a: a.go("keyboard")),
+             ("live", lambda a: a.go("live")), ("live-streaming", fake_live_stream),
+             ("keyboard", lambda a: (stop_fake_live(a), a.go("keyboard"))),
             ("monitor", lambda a: a.go("monitor")), ("monitor-details", open_monitor_details),
             ("tools", lambda a: a.go("settings")),
             # the index on the left: "This PC" scrolls the page there
@@ -470,6 +145,8 @@ def main() -> int:
        # a pretend install of --game, mid-upload: the transit in the sidebar, the game page and Activity
        steps += [("transit-game", lambda a: (a.page.pop_dialog(), start_fake_install(a, game), a.open_game(game))),
                  ("transit-activity", lambda a: a.show_activity(True))]
+        if args.fake_frame:  # GitHub #90: the Move to… dialog (drives load in the background)
+            steps.append(("move-dialog", lambda a: (a.page.pop_dialog(), a.move_game(game))))
        # last: the right-click menu stays open over whatever comes next
        steps.append(("library-menu", lambda a: (a.show_activity(False), a.navigate(0), time.sleep(3),
                                                 a.library_view.open_menu(game))))
@@ -505,12 +182,42 @@ def main() -> int:
        mouse["library"] = open_and_shoot(1354, 54, "library-add-menu")
        # type to search: click an empty part of the header, then type (the "-mouse" shot shows "arc" + the matches)
        steps.insert(1, ("library-typed", lambda a: a.library_view.clear_search()))
-        mouse["library-typed"] = lambda page: (page.mouse.click(480, 60), time.sleep(0.5),
-                                               page.keyboard.type("arc", delay=120))
+        def typed(page):
+            page.mouse.click(480, 60)
+            time.sleep(0.5)
+            page.keyboard.type("arc", delay=120)
+            if args.fake_frame:  # the matches' cover buttons: Install (Arcsmith, not installed), Update (Pinball FX)
+                time.sleep(PAINT_SECONDS)
+                for name, pt in (("library-install-hover", (742, 215)), ("library-install-button", (742, 276)),
+                                 ("library-update-button", (357, 276))):
+                    page.mouse.move(*pt, steps=8)
+                    time.sleep(1.2)
+                    page.screenshot(path=str(args.out / f"{name}.png"))
+                page.mouse.move(1300, 700)
+        mouse["library-typed"] = typed
        steps.insert(2, ("library-cleared", lambda a: a.library_view.clear_search()))
        if args.fake_frame:  # the "On your Frame" shelf's first card, hovered: its Play button shows
            steps.insert(3, ("library-shelf-hover", lambda a: None))
            hover["library-shelf-hover"] = (403, 268)
+            # the grid's first card: hovered (lift, zoom, the glass button), the pointer on its button, then Play:
+            # the portal rings mid-ripple and the "Starting on Frame…" pill
+            steps.insert(4, ("library-card-hover", lambda a: None))
+            hover["library-card-hover"] = (357, 420)
+            steps.insert(5, ("library-card-button", lambda a: None))
+            hover["library-card-button"] = (357, 497)
+
+            def launch(page):
+                page.mouse.move(357, 497)
+                time.sleep(1.2)
+                page.mouse.click(357, 497)
+                for i in range(6):  # the launch, frame by frame (rings, then the pill)
+                    time.sleep(0.15)
+                    page.screenshot(path=str(args.out / f"library-play-launch-{i}.png"))
+                time.sleep(1.0)
+                page.screenshot(path=str(args.out / "library-play-starting.png"))
+                page.mouse.move(130, 520)
+                return True
+            mouse["library-card-button"] = launch
        if game:
            mouse["game"] = open_and_shoot(491, 306, "game-more-menu")  # the hero's "…"
    if args.gestures:  # the mouse actions run after each step's screenshot, before the next step
@@ -567,7 +274,9 @@ def main() -> int:
                 ("linux-folder-customize", lambda a: a.open_game(LINUX_FOLDER, advanced=True)),
                 ("linux-change-program", lambda a: a.choose_exe(LINUX_FOLDER)),
                 ("frame", lambda a: (a.page.pop_dialog(), a.navigate(1))),
-                 ("linux-menu", lambda a: (a.navigate(0), time.sleep(3), a.library_view.open_menu(LINUX_APPIMAGE)))]
+                 ("linux-move", lambda a: a.move_game(LINUX_APPIMAGE) if args.fake_frame else None),
+                 ("linux-menu", lambda a: (a.page.pop_dialog(), a.navigate(0), time.sleep(3),
+                                           a.library_view.open_menu(LINUX_APPIMAGE)))]
    if args.links:
        from frameport import deeplink
        from frameport.ui.views import link_dialog
@@ -654,14 +363,48 @@ def main() -> int:
        steps = [("library", lambda a: a.navigate(0)), ("questions", open_questions),
                 ("after-1st-double", double_click), ("after-2nd-double", double_click), ("end", report)]
    if args.update:
-        from frameport import updates
+        from frameport import __version__, updates

+        notes = ("FramePort v9.9.9: Windows (x64), macOS (Apple Silicon) and Linux (x64, ARM64).\n\n## What's new\n\n"
+                 "- Self-update test release: the update dialog shows every version since yours\n"
+                 "- **Bold** and `code` in notes, and a [link](https://example.invalid)\n- A third bullet\n\n"
+                 "Already have FramePort? It offers this update itself (Library → **Update now**).\n\n## Install\n\n"
+                 "- footer that the changelog leaves out\n")
        fake = updates.Update(version="9.9.9", tag="v9.9.9", page="https://example.invalid", asset=None, asset_url=None,
-                              sums_url=None, wheel_url=None,
-                              notes="## What's new\n- Self-update test release\n- **Bold** and `code` in notes")
+                              sums_url=None, wheel_url=None, notes=notes, published="2026-10-08T10:00:00Z")
+        major, minor, _patch = updates.parse_version(__version__)[:3]
+        older = f"{major}.{max(minor - 1, 0)}"
+
+        def entry(version, date, body):
+            return updates.ChangelogEntry(version=version, tag=f"v{version}", date=date, title=f"FramePort v{version}",
+                                          body=body, page="https://example.invalid",
+                                          dev=updates.is_dev_version(version))
+        fake_log = [updates.entry_from_update(fake),
+                    entry("9.9.8", "2026-10-06", "- Install links from FrameDrop buttons\n- Faster uploads over USB"),
+                    entry("9.9.7", "2026-10-04", "- Monitor tab with live Frame stats"),
+                    entry(__version__, "2026-10-02", "- The version you have: **Live view** with sound\n"
+                                                     "- Files tab: drag and drop\n- Smaller fixes"),
+                    entry(f"{older}.3", "2026-09-30", "- Proton defaults to the newest stable build"),
+                    entry(f"{older}.2", "2026-09-28", "- Language packs")]
+        updates.fetch_changelog = lambda force=False, need=None: list(fake_log)  # no GitHub in screenshots
+
+        def news(a):
+            a.updater._set(None)
+            a.updater.news = updates.recent_history(fake_log, n=3)
+            a.navigate(0)
+            a.refresh_view()
+
+        def settings_updates(a):
+            a.go("settings")
+            # once the page is mounted: scrolling an unmounted column does nothing
+            threading.Timer(1.0, lambda: a.page.run_task(a.settings_view.show_section, "updates")).start()
        steps += [("update-banner", lambda a: (a.updater._set(fake), a.navigate(0))),
                  ("update-dialog", lambda a: a.updater.show_dialog()),
-                  ("update-settings", lambda a: (a.page.pop_dialog(), a.go("settings")))]
+                  ("update-settings", lambda a: (a.page.pop_dialog(), settings_updates(a))),
+                  ("update-whats-new-bar", lambda a: news(a)),
+                  ("update-whats-new-dialog", lambda a: a.updater.show_news()),
+                  ("update-settings-changelog", lambda a: (a.page.pop_dialog(), settings_updates(a),
+                                                           a.updater.show_history()))]
    if args.frame:
        from frameport.frame.connection import parse_target

@@ -693,6 +436,9 @@ def main() -> int:
    steps.insert(0, ("warmup", lambda a: a.go("settings")))
    ready, shot_done, done = threading.Event(), threading.Event(), []

+    from frameport.ui.app import serialize_flet_updates
+
+    serialize_flet_updates()  # as the app's main() does
    if args.fake_frame:  # never reach a real Frame (start-up auto-connect, discovery, the 30 s poll)
        install_fakes(game)

@@ -9,19 +9,84 @@ from pathlib import Path
 from ..apk import axml
 from ..core.models import Analysis
 from . import elf
+from .unity_split import split_build as unity_split_build

 logging.getLogger("pyaxmlparser").setLevel(logging.ERROR)

 UNITY_GGM = "assets/bin/Data/globalgamemanagers"
 IL2CPP_METADATA = "assets/bin/Data/Managed/Metadata/global-metadata.dat"

+# The version of what analyze() stores (Analysis.extra["analysis_version"]). BUMP IT whenever analyze() gains a field
+# or detects something differently that patches/heuristics read: library entries analysed by an older FramePort are
+# then analysed again in the background at the next start (pipeline.refresh_analyses), so their new patches are
+# offered (GitHub #104: entries from before `sdl_java` never got frame.sdl_clipboard). Entries without it are 0.
+# 1: sdl_java, min_sdk, web_wrapper, expects_obb, vr_activity, unity_version (2026-10)
+# 2: unity_split (a Unity split-binary build expects an OBB too: expects_obb) (2026-10)
+# 3: unreal_ovrp_lookups (the OVRPlugin functions Unreal's Oculus module looks up: frame.unreal_ovrp_entrypoints)
+ANALYSIS_VERSION = 3

-def _read_manifest_info(path: Path) -> tuple[str, str, str, str | None]:
+
+# Android versions by API level (for messages); the Frame's Lepton container runs Android 11 (API 30)
+ANDROID_VERSIONS = {29: "10", 30: "11", 31: "12", 32: "12L", 33: "13", 34: "14", 35: "15", 36: "16", 37: "17"}
+FRAME_API = 30
+# Quest games declare up to API 32 (Quest's Android 12L) and run on the Frame (OVRPort lowers minSdk to 29; they
+# don't call newer Android classes). From API 33 on, apps call Android 13+ classes at start (GitHub #71/#72: minSdk
+# 34, NoClassDefFoundError android/window/OnBackInvokedCallback, NoSuchMethodError VarHandle.storeStoreFence).
+MAX_RUNNABLE_MIN_SDK = 32
+
+
+def android_version(api: int) -> str:
+    """'14' for API 34."""
+    return ANDROID_VERSIONS.get(api, f"API {api}")
+
+
+def too_new_android(min_sdk: int | None) -> bool:
+    """The APK needs a newer Android than the Frame's Lepton (11): it crashes at start on missing Android classes."""
+    return bool(min_sdk) and min_sdk > MAX_RUNNABLE_MIN_SDK
+
+
+TWA_URL_KEY = "android.support.customtabs.trusted.DEFAULT_URL"
+TWA_ACTIVITY = "com.google.androidbrowserhelper.trusted.LauncherActivity"
+UE_OBB_KEY = ".GameActivity.bHasOBBFiles"  # com.epicgames.ue4.… (UE4) / com.epicgames.unreal.… (UE5)
+
+
+def expects_obb(meta: dict) -> bool:
+    """Unreal packaged the game's content as an OBB (expansion file) and opens it at start."""
+    return any(k.endswith(UE_OBB_KEY) and v in (True, "true", "True") for k, v in meta.items())
+
+
+def _read_manifest_info(path: Path):
+    """(package, versionName, label, main activity, pyaxmlparser APK)."""
    from pyaxmlparser import APK

    apk = APK(str(path))
    label = apk.application or apk.package
-    return apk.package, apk.version_name or "", label, apk.get_main_activity()
+    return apk.package, apk.version_name or "", label, apk.get_main_activity(), apk
+
+
+def _resolve_string(apk, value) -> str | None:
+    """A meta-data value: the string itself, or a @string/… reference resolved through resources.arsc."""
+    if isinstance(value, str):
+        return value
+    if apk is None or isinstance(value, bool) or not isinstance(value, int):
+        return None
+    try:
+        res = apk.get_android_resources()
+        for _config, v in (res.get_resolved_res_configs(value) if res else ()):
+            if isinstance(v, str) and v:
+                return v
+    except Exception:  # noqa: BLE001 - a broken resource table only loses the URL
+        pass
+    return None
+
+
+def web_wrapper(meta: dict, manifest_strings: list[str], apk=None) -> dict | None:
+    """A Trusted Web Activity (Bubblewrap, Meta's PWA packaging): the APK only opens a website in a browser app
+    (Meta's com.oculus.browser on Quest), which Lepton doesn't have (GitHub #86). {"url": str | None} or None."""
+    if TWA_URL_KEY not in meta and TWA_ACTIVITY not in manifest_strings:
+        return None
+    url = _resolve_string(apk, meta.get(TWA_URL_KEY))
+    return {"url": url if url and url.startswith(("https://", "http://")) else None}


 def _unreal_version(z: zipfile.ZipFile, lib: str) -> str | None:
@@ -111,8 +176,10 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
                if "assets/bin/Data/boot.config" in names else "")
        ggm = z.read(UNITY_GGM) if deep and UNITY_GGM in names else None
        il2cpp_meta = z.read(IL2CPP_METADATA) if deep and IL2CPP_METADATA in names and "libil2cpp.so" in libs else None
+        # a Unity split build: the rest of the game is in a zip OBB (analysis/unity_split.py)
+        unity_split = "libunity.so" in libs and unity_split_build(z, names, ggm, deep)

-    package, version, label, activity = _read_manifest_info(path)
+    package, version, label, activity, apk_info = _read_manifest_info(path)
    libset = set(libs)
    engine = ("Unreal" if libset & {"libUE4.so", "libUnreal.so"} else "Unity" if "libunity.so" in libset
              else "CryEngine" if "libCrySystem.so" in libset else "Other")
@@ -159,6 +226,7 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
    manifest_strings = axml.Axml(manifest).strings()
    features = _features(manifest)
    used_perms, _ = axml.used_and_declared_permissions(manifest)
+    meta = axml.meta_data(manifest)
    return Analysis(
        package=package,
        version=version,
@@ -178,6 +246,7 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
        is_overport_output=is_overport,
        debuggable=bool(axml.Axml(manifest).get_bool("application", "debuggable")),
        extra={
+            "analysis_version": ANALYSIS_VERSION,
            "frame_patched": "libframe_settings.so" in libset,  # already has FramePort's FrameBridge adapter
            # Team Beef's TBXR ports pick their OpenXR path by headset maker (frame.tbxr_vendor): their libraries
            # the game asks Meta's platform for asset files (content shipped as separate files, frame.asset_files)
@@ -216,10 +285,37 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
            # a 2D launcher activity that starts a separate VR activity (frame.start_activity)
            "vr_activity": axml.vr_activity(manifest),
            "unity_version": unity_version(ggm, lib_bytes.get("libunity.so")) if engine == "Unity" else None,
+            # the minimum Android version the APK declares (read from the original: OVRPort lowers it to 29)
+            "min_sdk": axml.min_sdk(manifest),
+            # a website in an Android wrapper (TWA): nothing to port
+            "web_wrapper": web_wrapper(meta, manifest_strings, apk_info),
+            # Unreal packaged its content as an OBB (expansion file), or a Unity split build keeps all but its first
+            # scene in one: without it the game hangs at start (GitHub #85, #92)
+            "expects_obb": expects_obb(meta) or unity_split,
+            "unity_split": unity_split,
+            # Unreal's Oculus module needs every OVRPlugin function it looks up (frame.unreal_ovrp_entrypoints)
+            "unreal_ovrp_lookups": (ovrp_lookups(lib_bytes.get(engine_lib.rsplit("/", 1)[1], b""))
+                                    if engine_lib and "libOVRPlugin.so" in libset else []),
        },
    )


+def ovrp_lookups(data: bytes) -> list[str]:
+    """The OVRPlugin function names (`ovrp_*` strings) an engine library holds: Unreal's Oculus module looks each one
+    up with dlsym in libOVRPlugin.so and gives up on VR when any is missing (FOculusHMDModule::
+    InitializeOculusPluginWrapper)."""
+    names, at = set(), data.find(b"\0ovrp_")
+    while at >= 0:
+        end = data.find(b"\0", at + 1)
+        if end < 0:
+            break
+        name = data[at + 1:end]
+        if re.fullmatch(rb"ovrp_[A-Za-z0-9_]+", name):
+            names.add(name.decode())
+        at = data.find(b"\0ovrp_", end)
+    return sorted(names)
+
+
 def unity_text_fields(metadata: bytes) -> list[str]:
    """The Unity text field classes an IL2CPP game contains (names from its global-metadata.dat string table)."""
    out = []
@@ -102,6 +102,60 @@ def _desktop_name(root: Path) -> str | None:
    return None


+def _png_width(path: Path) -> int | None:
+    try:
+        with open(path, "rb") as f:
+            head = f.read(24)
+    except OSError:
+        return None
+    if head[:8] != b"\x89PNG\r\n\x1a\n" or len(head) < 24:
+        return None
+    return int.from_bytes(head[16:20], "big")
+
+
+def find_icon(root: Path) -> Path | None:
+    """The app's own icon in a folder (GitHub #99): the Icon= of its bundled .desktop file, looked up next to the
+    file, in (usr/)share/icons/hicolor/<size>/apps and (usr/)share/pixmaps, or a top-level .DirIcon; the biggest PNG
+    (the PC can't draw SVG icons; the Frame's agent uses those for Desktop Mode). Nothing outside `root` (symlinks
+    are resolved and checked). AppImages are read on the Frame instead (their files are compressed)."""
+    root = Path(root)
+    try:
+        real_root = root.resolve()
+    except OSError:
+        return None
+    paths = [root / ".DirIcon"]
+    desktops = [p for p in sorted(root.rglob("*.desktop"))[:5] if len(p.relative_to(root).parts) <= 4]
+    for desktop in desktops:
+        m = re.search(r"^Icon=(.+)$", desktop.read_text(encoding="utf-8", errors="replace"), re.M)
+        name = m.group(1).strip() if m else ""
+        if not name or name.startswith("/") or ".." in name.split("/"):
+            continue
+        stem = re.sub(r"\.(png|svg|xpm)$", "", name, flags=re.I)
+        bases = [root] + [d for d in desktop.parents if d != root and real_root in d.resolve().parents]
+        for base in bases:
+            paths += [base / name, base / f"{stem}.png"]
+            for share in (base / "usr" / "share", base / "share"):
+                paths += sorted(share.glob(f"icons/hicolor/*/apps/{glob_escape(stem)}.png"))
+                paths.append(share / "pixmaps" / f"{stem}.png")
+        break
+    best: tuple[int, Path] | None = None
+    for p in paths:
+        try:
+            real = p.resolve()
+            if real_root not in real.parents or not real.is_file() or real.stat().st_size > 4 << 20:
+                continue
+        except OSError:
+            continue
+        width = _png_width(real)
+        if width and (best is None or width > best[0]):
+            best = (width, real)
+    return best[1] if best else None
+
+
+def glob_escape(text: str) -> str:
+    return re.sub(r"([*?\[])", r"[\1]", text)
+
+
 def rank_programs(root: Path) -> list[tuple[Path, int]]:
    """(ELF program, machine) candidates, best first: the .desktop Exec= name, then a name like the folder's, then
    shallow and big ones. Libraries (*.so*) are never programs."""
@@ -24,12 +24,21 @@ def _elf_hash(name: bytes) -> int:
    return h


-def build_stub_library(symbols: list[str], soname: str = "libovrstubs.so", abi: str = "arm64-v8a") -> bytes:
+def build_stub_library(symbols: list[str], soname: str = "libovrstubs.so", abi: str = "arm64-v8a",
+                       result: int = 0) -> bytes:
+    """`result`: what every function returns (a 32-bit int; arm64 only for values other than 0), e.g. OVRPlugin's
+    ovrpFailure (-1000) for stand-ins whose callers must not trust untouched output arguments."""
    is64 = abi == "arm64-v8a"
    symbols = sorted(set(symbols))
+    if result and not (is64 and -0x10000 <= result <= 0xFFFF):
+        raise ValueError(f"stub result {result} not supported for {abi}")
    if is64:
        machine, ehsize, phentsize, shentsize, symsize, dynsize = 183, 64, 56, 64, 24, 16  # EM_AARCH64
        body = struct.pack("<II", 0xD2800000, 0xD65F03C0)  # mov x0, #0 ; ret
+        if result > 0:  # movz w0, #result ; ret
+            body = struct.pack("<II", 0x52800000 | result << 5, 0xD65F03C0)
+        elif result < 0:  # movn w0, #~result ; ret  (w0 = result)
+            body = struct.pack("<II", 0x12800000 | (~result & 0xFFFF) << 5, 0xD65F03C0)
    else:
        machine, ehsize, phentsize, shentsize, symsize, dynsize = 40, 52, 32, 40, 16, 8  # EM_ARM
        body = struct.pack("<II", 0xE3A00000, 0xE12FFF1E)  # mov r0, #0 ; bx lr
@@ -0,0 +1,152 @@
+"""Unity "split application binary" builds: the APK keeps the first scene, the rest of the game is a zip OBB
+(main.<versionCode>.<package>.obb holding assets/bin/Data/...). Without it the game starts into nothing.
+
+Two signs, either is enough (checked against 48 Unity APKs, 30 games: all 13 split builds flagged, none of the 17 full
+builds, whose OBBs, where they have one, are asset bundles or sound banks):
+  A  an XR-plugin build (Oculus XR Plugin / Unity OpenXR library) without assets/bin/Data/UnitySubsystems/ in the APK:
+     the split moves the UnitySubsystems manifests into the OBB; full XR-plugin builds always have them (zip names only;
+     the only sign for split builds with one scene, e.g. BONELAB)
+  B  the build settings list more scenes than the APK has level files (a split keeps level0 only). The scene list
+     comes from globalgamemanagers (loose, or the node of data.unity3d: only the bundle's head and the blocks up to it
+     are read, a few hundred KB of a file that can be hundreds of MB)
+"""
+from __future__ import annotations
+
+import lzma
+import re
+import struct
+import zipfile
+
+DATA = "assets/bin/Data/"
+XR_PLUGIN_LIBS = ("libOculusXRPlugin.so", "libUnityOpenXR.so")
+LEVEL = re.compile(re.escape(DATA) + r"level(\d+)(?:\.|$)")
+MAX_NODE = 64 * 2**20  # globalgamemanagers is 0.1-3 MB; a larger node isn't read
+
+
+def xr_plugin_without_subsystems(names: list[str]) -> bool:
+    """Sign A (zip names only)."""
+    xr_plugin = any(n.startswith("lib/") and n.rsplit("/", 1)[-1] in XR_PLUGIN_LIBS for n in names)
+    return xr_plugin and not any(n.startswith(DATA + "UnitySubsystems/") for n in names)
+
+
+def _cstr(f) -> bytes:
+    out = bytearray()
+    while (c := f.read(1)) not in (b"\0", b""):
+        out += c
+    return bytes(out)
+
+
+def _decompress(data: bytes, kind: int, size: int) -> bytes:
+    if kind == 0:
+        return data
+    if kind in (2, 3):  # LZ4 / LZ4HC
+        import lz4.block
+
+        return lz4.block.decompress(data, uncompressed_size=size)
+    if kind == 1:  # LZMA: 5 bytes of properties, then raw LZMA1
+        props, dict_size = data[0], struct.unpack("<I", data[1:5])[0]
+        dec = lzma.LZMADecompressor(lzma.FORMAT_RAW, filters=[{
+            "id": lzma.FILTER_LZMA1, "dict_size": dict_size, "lc": props % 9, "lp": (props // 9) % 5,
+            "pb": props // 45}])
+        return dec.decompress(data[5:], size)
+    raise ValueError(f"unknown compression {kind}")
+
+
+class _Counting:
+    """A forward-only stream that knows its position (zip member streams have no reliable tell())."""
+
+    def __init__(self, f):
+        self.f, self.pos = f, 0
+
+    def read(self, n: int) -> bytes:
+        b = self.f.read(n)
+        self.pos += len(b)
+        return b
+
+    def align(self, n: int = 16) -> None:
+        if self.pos % n:
+            self.read(n - self.pos % n)
+
+
+def bundle_node(stream, want: str = "globalgamemanagers") -> tuple[list[str], bytes | None]:
+    """(node names, bytes of node `want`) of a UnityFS bundle, reading only up to the end of that node. ([], None)
+    for anything else (old formats, block info at the end of the file)."""
+    f = _Counting(stream)
+    if f.read(8) != b"UnityFS\0":
+        return [], None
+    version = struct.unpack(">I", f.read(4))[0]
+    _cstr(f), _cstr(f)
+    _size, csize, usize, flags = struct.unpack(">qIII", f.read(20))
+    if version >= 7:
+        f.align()
+    if flags & 0x80:  # block info at the end of the file
+        return [], None
+    info = _decompress(f.read(csize), flags & 0x3F, usize)
+    off = 16  # data hash
+    (nblocks,) = struct.unpack(">i", info[off:off + 4])
+    off += 4
+    blocks = []
+    for _ in range(nblocks):
+        blocks.append(struct.unpack(">IIH", info[off:off + 10]))
+        off += 10
+    (nnodes,) = struct.unpack(">i", info[off:off + 4])
+    off += 4
+    nodes = []
+    for _ in range(nnodes):
+        node_off, node_size, _flags = struct.unpack(">qqI", info[off:off + 20])
+        off += 20
+        end = info.index(b"\0", off)
+        nodes.append((info[off:end].decode("utf-8", "replace"), node_off, node_size))
+        off = end + 1
+    if flags & 0x200:  # padding before the first block
+        f.align()
+    names = [n[0] for n in nodes]
+    target = next((n for n in nodes if n[0] == want), None)
+    if target is None or target[2] > MAX_NODE:
+        return names, None
+    need = target[1] + target[2]
+    out = bytearray()
+    for u, c, bf in blocks:
+        if len(out) >= need:
+            break
+        out += _decompress(f.read(c), bf & 0x3F, u)
+    return names, bytes(out[target[1]:need])
+
+
+def build_scene_count(ggm: bytes) -> int | None:
+    """Number of scenes in the build settings (BuildSettings.scenes) of a globalgamemanagers file."""
+    try:
+        import UnityPy
+
+        for obj in UnityPy.load(ggm).objects:
+            if obj.type.name == "BuildSettings":
+                return len(obj.read_typetree().get("scenes") or [])
+    except Exception:  # noqa: BLE001 - unreadable/unknown version: no answer
+        return None
+    return None
+
+
+def more_scenes_than_levels(z: zipfile.ZipFile, names: list[str], ggm: bytes | None = None) -> bool:
+    """Sign B. ggm: the loose globalgamemanagers when already read."""
+    nameset = set(names)
+    levels: set[int] = set()
+    if ggm is None and DATA + "globalgamemanagers" in nameset:
+        ggm = z.read(DATA + "globalgamemanagers")
+    if ggm is not None:
+        levels = {int(m.group(1)) for n in names if (m := LEVEL.match(n))}
+    elif DATA + "data.unity3d" in nameset:
+        try:
+            with z.open(DATA + "data.unity3d") as raw:
+                nodes, ggm = bundle_node(raw)
+        except Exception:  # noqa: BLE001
+            return False
+        levels = {int(m.group(1)) for n in nodes if (m := re.fullmatch(r"level(\d+)", n))}
+    if ggm is None:
+        return False
+    scenes = build_scene_count(ggm)
+    return scenes is not None and scenes > len(levels)
+
+
+def split_build(z: zipfile.ZipFile, names: list[str], ggm: bytes | None = None, deep: bool = True) -> bool:
+    """The APK of a Unity split build (its OBB holds the rest of the game). Without `deep` only sign A."""
+    return xr_plugin_without_subsystems(names) or (deep and more_scenes_than_levels(z, names, ggm))
@@ -15,6 +15,9 @@ RES_XML_START_ELEMENT = 0x0102
 RES_XML_END_ELEMENT = 0x0103
 TYPE_STRING = 0x03
 TYPE_INT_BOOLEAN = 0x12
+TYPE_REFERENCE = 0x01
+TYPE_INT_DEC = 0x10
+TYPE_INT_HEX = 0x11
 ANDROID_NS = "http://schemas.android.com/apk/res/android"
 LAUNCHER = "android.intent.category.LAUNCHER"
 INFO = "android.intent.category.INFO"
@@ -214,6 +217,48 @@ def undeclared_meta_permissions(manifest: bytes) -> list[str]:
    return [p for p in used if p.startswith(("com.oculus.permission.", "horizonos.permission.")) and p not in declared]


+def min_sdk(manifest: bytes) -> int | None:
+    """<uses-sdk android:minSdkVersion> (None when absent or a preview codename)."""
+    x = Axml(manifest)
+    names = x.strings()
+    for el in x.elements():
+        if el.name != "uses-sdk":
+            continue
+        for a in el.attrs:
+            if a.name < len(names) and names[a.name] == "minSdkVersion":
+                if a.dtype in (TYPE_INT_DEC, TYPE_INT_HEX):
+                    return a.value
+                s = x.attr_str(el, "minSdkVersion")
+                return int(s) if s and s.isdigit() else None
+    return None
+
+
+def meta_data(manifest: bytes) -> dict[str, str | int | bool | None]:
+    """<meta-data android:name android:value|resource> entries: a string, a bool, an int, or a resource id (int)
+    for references (@string/…), None when the value isn't one of those."""
+    x = Axml(manifest)
+    names = x.strings()
+    out: dict = {}
+    for el in x.elements():
+        if el.name != "meta-data":
+            continue
+        key = x.attr_str(el, "name")
+        if not key:
+            continue
+        value = None
+        for a in el.attrs:
+            if a.name >= len(names) or names[a.name] not in ("value", "resource"):
+                continue
+            if a.raw < len(names) or a.dtype == TYPE_STRING:
+                value = x.attr_str(el, names[a.name])
+            elif a.dtype == TYPE_INT_BOOLEAN:
+                value = a.value != 0
+            elif a.dtype in (TYPE_INT_DEC, TYPE_INT_HEX, TYPE_REFERENCE):
+                value = a.value
+        out[key] = value
+    return out
+
+
 def categories(manifest: bytes) -> set[str]:
    x = Axml(manifest)
    return {v for el in x.elements() if el.name == "category" for v in [x.attr_str(el, "name")] if v}
@@ -304,6 +304,68 @@ def apply_custom(package: str, kind: str, path: str | Path) -> Path:
    return out


+# A Linux app's own icon (GitHub #99: from its .desktop file / AppImage), applied automatically: no PICKED marker, and
+# APP_ICON records which icon.* it is, so a later pick (store art, the user's own) is told apart from it.
+APP_ICON = ".app-icon"
+APP_ICON_MIN_PX = 16
+
+
+def _sha256(path: Path) -> str:
+    import hashlib
+
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def icon_source(package: str) -> str:
+    """What the game's icon artwork is: "custom" (the user's pick, store art or an install link's icon), "app" (the
+    Linux app's own icon, applied automatically) or "generated" (no icon: Steam's is composed or a placeholder). The
+    Frame's agent puts the app's own icon first unless this says "custom"."""
+    d = fetch.artwork_dir(package)
+    icon = next(iter(sorted(d.glob("icon.*"))), None)
+    if icon is None:
+        return "generated"
+    marker = d / APP_ICON
+    try:
+        if marker.read_text(encoding="utf-8").strip() == _sha256(icon):
+            return "app"
+    except OSError:
+        pass
+    return "custom"
+
+
+def apply_app_icon(package: str, data: bytes) -> Path | None:
+    """Store a Linux app's own icon (PNG/JPEG bytes) as the game's icon when it has none and nothing was picked (the
+    user's choice and store art always stay). Not marked as the user's pick. Returns the stored file, or None when
+    nothing changed."""
+    import io
+
+    from PIL import Image, UnidentifiedImageError
+
+    d = fetch.artwork_dir(package)
+    if (d / fetch.PICKED).exists() or icon_source(package) == "custom":
+        return None
+    try:
+        with Image.open(io.BytesIO(data)) as im:
+            im.load()
+            im = im.copy()
+    except (OSError, UnidentifiedImageError, Image.DecompressionBombError):
+        return None
+    if min(im.size) < APP_ICON_MIN_PX:
+        return None
+    if max(im.size) > 1024:
+        im.thumbnail((1024, 1024), Image.LANCZOS)
+    tmp = d / ".app-icon.tmp"
+    im.convert("RGBA").save(tmp, "PNG", optimize=True)
+    out = d / "icon.png"
+    if out.exists() and out.read_bytes() == tmp.read_bytes():
+        tmp.unlink()
+        return None
+    _drop_kind(d, "icon")
+    tmp.replace(out)
+    (d / APP_ICON).write_text(_sha256(out), encoding="utf-8")
+    return out
+
+
 def remove_custom(package: str, kind: str) -> None:
    """Remove one kind of artwork (the Steam set then composes it from the other kinds, or uses a placeholder)."""
    if kind not in CUSTOM_KINDS:
@@ -10,7 +10,7 @@ from .apk.workspace import ApkWorkspace
 from .core.events import Reporter
 from .core.models import Analysis, BuildResult, Recipe, SourceGame
 from .core.paths import work_dir
-from .patches import base
+from .patches import base, upstream
 from .patches.overport import OVERPORT_PATCHES
 from .tools import overport as overport_tool
 from .validate.static import check_apk
@@ -36,25 +36,28 @@ def overport_ids(recipe: Recipe, alt: bool = False) -> list[str]:
    return ids


-def apk_patches(recipe: Recipe) -> list[base.Patch]:
-    patches = [base.get(pid) for pid in recipe.patches if base.get(pid).stage == "apk"]
+def apk_patches(selection: dict) -> list[base.Patch]:
+    patches = [base.get(pid) for pid in selection if base.get(pid).stage == "apk"]
    return sorted(patches, key=lambda p: p.order)


 def apply_frame_fixes(apk_in: Path, apk_out_unsigned: Path, analysis: Analysis, recipe: Recipe,
-                      reporter: Reporter) -> tuple[list[str], list[dict]]:
+                      reporter: Reporter) -> tuple[list[str], list[dict], dict[str, str]]:
+    """Apply the recipe's apk-stage patches; returns (applied ids, checks, workarounds left out because OVRPort's
+    output already has the upstream fix (patches/upstream.py))."""
    applied, checks = [], []
    with ApkWorkspace(apk_in) as ws:
-        for patch in apk_patches(recipe):
+        selection = upstream.resolve(ws, recipe.patches, reporter)
+        for patch in apk_patches(selection.patches):
            reporter.check_cancel()
-            ctx = base.ApkContext(ws, analysis, recipe.params(patch.id), reporter, recipe.patches)
+            ctx = base.ApkContext(ws, analysis, selection.patches.get(patch.id) or {}, reporter, selection.patches)
            if patch.apply(ctx):
                applied.append(patch.id)
                reporter.log(f"applied {patch.id}" + (f" ({'; '.join(ctx.notes)})" if ctx.notes else ""))
            for name, ok, detail in patch.validate(ctx):
                checks.append({"name": name, "ok": ok, "detail": detail})
        ws.write(apk_out_unsigned)
-    return applied, checks
+    return applied, checks, selection.superseded


 def build(source: SourceGame, analysis: Analysis, recipe: Recipe, outdir: Path, reporter: Reporter,
@@ -73,7 +76,7 @@ def build(source: SourceGame, analysis: Analysis, recipe: Recipe, outdir: Path,
    variants = [("primary", False)] + ([("alt", True)] if recipe.alt_patches and recipe.overport else [])
    alt_copy = Path(source.apk).with_name(f"{pkg}.alt-noforcequit.apk")
    results = {}
-    all_checks, applied = [], []
+    all_checks, applied, superseded = [], [], {}
    try:
        for variant, alt in variants:
            input_apk = alt_copy if converted and alt and alt_copy.exists() else Path(source.apk)
@@ -88,7 +91,9 @@ def build(source: SourceGame, analysis: Analysis, recipe: Recipe, outdir: Path,
                shutil.copyfile(input_apk, patched)
            reporter.stage(f"Frame fixes ({variant})")
            unsigned = work / f"{pkg}.{variant}.unsigned.apk"
-            applied, checks = apply_frame_fixes(patched, unsigned, analysis, recipe, reporter)
+            applied, checks, left_out = apply_frame_fixes(patched, unsigned, analysis, recipe, reporter)
+            if variant == "primary":
+                superseded = left_out
            patched.unlink(missing_ok=True)
            reporter.stage(f"sign ({variant})")
            final = outdir / (f"{pkg}.apk" if not alt else f"{pkg}.alt-noforcequit.apk")
@@ -106,4 +111,4 @@ def build(source: SourceGame, analysis: Analysis, recipe: Recipe, outdir: Path,
    primary, alt_apk = results["primary"], results.get("alt")
    return BuildResult(pkg, primary, alt_apk, sha256(primary), sha256(alt_apk) if alt_apk else None, applied,
                       all_checks, {"overport": overport_ids(recipe), "alt_overport": overport_ids(recipe, True)
-                                    if alt_apk else None})
+                                    if alt_apk else None, "superseded": superseded})
@@ -229,6 +229,8 @@ def scan(path: Path = typer.Argument(..., help="a folder with game backups (APKs
    for g in pipeline.add_path(path, rep):
        r = g["recipe"]
        typer.echo(f"{g['package']:40} {g.get('title', '')[:34]:34} {r['status']:11} {r['source']}")
+        for warning in pipeline.analysis_warnings(g):
+            typer.echo(f"  ! {warning}")


@app.command("catalog-update")
@@ -329,6 +331,9 @@ def show(package: str, as_json: bool = typer.Option(False, "--json", help=JSON_H
    typer.echo(f"{g.get('title')}  ({pkg} {a['version']})\n  engine {a['engine']}, XR {a['xr']}, {a['graphics']}, "
               f"ABIs {', '.join(a['abis'])}, direct VrApi: {a['direct_vrapi']}")
    typer.echo(f"  status: {r['status']}  recipe source: {r['source']}  {r['notes']}")
+    for warning in pipeline.analysis_warnings(g):
+        if warning not in r["notes"]:
+            typer.echo(f"  ! {warning}")
    from .recommend.engine import visible_patches

    shown, hidden = visible_patches(library.analysis_from_dict(a), library.recipe_from_dict(r))
@@ -337,6 +342,8 @@ def show(package: str, as_json: bool = typer.Option(False, "--json", help=JSON_H
        params = r["patches"].get(p.id) or {}
        typer.echo(f"  [{'x' if on else ' '}] {p.id:36} {p.title}{'  ' + json.dumps(params) if params else ''}"
                   f"{'  — ' + r['reasons'][p.id] if on and p.id in r.get('reasons', {}) else ''}")
+    for pid, fix in ((g.get("build") or {}).get("superseded") or {}).items():
+        typer.echo(f"  last build left out {pid}: fixed upstream ({fix})")
    if hidden and not all_:
        typer.echo(f"  ({len(hidden)} patches hidden as not relevant for this game; --all to list them)")
    if r.get("alt_patches"):
@@ -414,13 +421,20 @@ def install(package: Optional[str] = typer.Argument(None), all_: bool = typer.Op
            no_library: bool = typer.Option(False, help="don't add to the Steam library now"),
            to: str = typer.Option("frame", help="frame, or pc (PC VR games only: install on this PC)"),
            apk: Optional[Path] = typer.Option(None, help="install this APK instead of the last build (one game; e.g. "
-                                                          "a test build signed with the game's key)")):
+                                                          "a test build signed with the game's key)"),
+            dest: Optional[str] = typer.Option(None, help="drive for new installs: 'internal' or a drive's path from "
+                                                          "'frameport frame drives' (default: the app's setting); "
+                                                          "installed games stay where they are")):
    """Install games on the Frame (or PC VR games on this PC) and add them to the Steam library."""
    target = _target(frame, password, to)
+    if dest is not None and hasattr(target, "dest"):
+        target.dest = "" if dest == "internal" else dest
    pkgs = _pkgs(package, all_)
    if apk and len(pkgs) != 1:
        raise typer.BadParameter("--apk needs exactly one game")
    for pkg in pkgs:
+        if not apk_only and pipeline.missing_obb(library.game(pkg) or {}):
+            typer.echo(f"{pkg}: warning: " + pipeline.MISSING_OBB_NOTE.format(package=pkg), err=True)
        pipeline.install_game(pkg, target, printing_reporter(False), apk_only, add_to_library=False, apk=apk)
    if not no_library:
        target.add_to_library(pkgs, printing_reporter(False))
@@ -553,6 +567,38 @@ def frame_storage(game: Optional[str] = typer.Option(None, help="also show this
        typer.echo(f"{t['id']:10} {t['android']:45} {t['path']}" + ("  (every app)" if t["shared"] else ""))


+@frame_app.command("drives")
+def frame_drives(frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
+                 as_json: bool = typer.Option(False, "--json", help=JSON_HELP)):
+    """The Frame's drives (internal storage, a microSD card) games can be installed on or moved to."""
+    from .install import drives
+
+    found = _target(frame).drives()
+    if as_json:
+        typer.echo(json.dumps(found, indent=1))
+        return
+    current = drives.install_dest()
+    for d in found:
+        free = drives.free_text(d) or "?"
+        mark = "*" if (d["internal"] and not current) or current in (d["install_dir"], d["path"]) else " "
+        state = f"{d.get('games', 0)} game(s)" if d.get("usable") else f"can't be used: {d.get('reason')}"
+        typer.echo(f"{mark} {d['label']:20} {d.get('fstype') or '':6} {free:>16}  {state}")
+        if not d["internal"]:
+            typer.echo(f"  {'':20} {d['path']}")
+    typer.echo("* = where new games go (frameport install --dest, or the app's Settings: Frame)")
+
+
+@frame_app.command("move")
+def frame_move(package: str = typer.Argument(..., help="an installed game"),
+               to_: str = typer.Option(..., "--to", help="'internal' or a drive's path from 'frameport frame drives'"),
+               frame: Optional[str] = typer.Option(None, help=FRAME_HELP)):
+    """Move an installed game's files to another drive of the Frame (e.g. the microSD card) or back. Saves, the
+    Steam library entry and settings stay as they are."""
+    pkg = _pkgs(package, False)[0]
+    st = _target(frame).move(pkg, to_, printing_reporter())
+    typer.echo(f"moved to {st.get('base') or st.get('to')}")
+
+
@frame_app.command("info")
 def frame_info(frame: Optional[str] = typer.Option(None, help=FRAME_HELP)):
    """The Frame's SteamOS build, runtimes, storage and installed games (JSON)."""
@@ -0,0 +1,103 @@
+"""Put an image on the system clipboard (no Flet: Flet's own Clipboard.set_image only works in web and mobile apps).
+
+- Windows (and WSL, where the user's clipboard is Windows'): Windows PowerShell + System.Windows.Forms, as a
+  bitmap (pastes into chats, Paint, documents) plus the file (pastes into Explorer and file uploads). From WSL the
+  image is copied to the Windows user's %TEMP% first: .NET reads that reliably, a \\\\wsl$ path not always.
+- macOS: osascript with the image as PNG.
+- Linux: wl-copy (Wayland) or xclip (X11), as PNG.
+
+copy_image() raises ClipboardError with a sentence for the user when nothing on this system can do it.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from . import winhost
+
+
+class ClipboardError(RuntimeError):
+    pass
+
+
+def as_png(path: Path, dest_dir: Path) -> Path:
+    """The image as a PNG in dest_dir (PNG input is copied as it is)."""
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    out = dest_dir / (path.stem + ".png")
+    if path.suffix.lower() == ".png":
+        shutil.copyfile(path, out)
+    else:
+        from PIL import Image
+
+        with Image.open(path) as im:
+            im.save(out, "PNG")
+    return out
+
+
+def _ps_quote(text: str) -> str:
+    return "'" + text.replace("'", "''") + "'"
+
+
+def windows_script(win_path: str) -> str:
+    """The PowerShell that puts the image at win_path on the clipboard (bitmap + file)."""
+    p = _ps_quote(win_path)
+    return ("Add-Type -AssemblyName System.Windows.Forms, System.Drawing; "
+            f"$bytes = [IO.File]::ReadAllBytes({p}); "
+            "$img = [Drawing.Image]::FromStream((New-Object IO.MemoryStream(,$bytes))); "
+            "$data = New-Object Windows.Forms.DataObject; $data.SetImage($img); "
+            "$files = New-Object Collections.Specialized.StringCollection; "
+            f"[void]$files.Add({p}); $data.SetFileDropList($files); "
+            "[Windows.Forms.Clipboard]::SetDataObject($data, $true)")
+
+
+def _windows(path: Path) -> None:
+    src = path
+    if winhost.is_wsl():
+        temp = winhost.env_path("TEMP")
+        if temp is None:
+            raise ClipboardError("Windows' temporary folder isn't reachable from WSL")
+        folder = temp / "FramePort-clipboard"
+        folder.mkdir(parents=True, exist_ok=True)
+        src = folder / path.name
+        shutil.copyfile(path, src)
+    r = winhost.powershell(windows_script(winhost.to_windows(src)), timeout=30)
+    if r.returncode:
+        raise ClipboardError((r.stderr or r.stdout or "PowerShell failed").strip().splitlines()[-1])
+
+
+def _mac(path: Path) -> None:
+    png = as_png(path, Path(tempfile.gettempdir()) / "frameport-clipboard")
+    script = f'set the clipboard to (read (POSIX file "{png}") as «class PNGf»)'
+    r = subprocess.run(["osascript", "-e", script], capture_output=True, text=True, timeout=30)
+    if r.returncode:
+        raise ClipboardError(r.stderr.strip() or "osascript failed")
+
+
+def _linux(path: Path) -> None:
+    png = as_png(path, Path(tempfile.gettempdir()) / "frameport-clipboard")
+    if os.environ.get("WAYLAND_DISPLAY") and shutil.which("wl-copy"):
+        cmd = ["wl-copy", "--type", "image/png"]
+    elif shutil.which("xclip"):
+        cmd = ["xclip", "-selection", "clipboard", "-t", "image/png"]
+    else:
+        raise ClipboardError("copying pictures needs wl-copy (Wayland) or xclip (X11): install one of them")
+    # (both stay running to serve the clipboard: don't wait for them)
+    with png.open("rb") as f:
+        subprocess.Popen(cmd, stdin=f, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, start_new_session=True)
+
+
+def copy_image(path: Path) -> None:
+    """The image file at `path` onto the system clipboard."""
+    path = Path(path)
+    if not path.is_file():
+        raise ClipboardError(f"{path.name} isn't there")
+    if winhost.available():
+        _windows(path)
+    elif sys.platform == "darwin":
+        _mac(path)
+    else:
+        _linux(path)
@@ -120,9 +120,10 @@ def _refresh_data_fields(g: dict, a: dict) -> bool:
        return False
    from ..analysis import langpacks

+    data = g.get("data_dir") if g.get("data_files") is None else None  # expansion files only: no packs
    try:
-        extra.setdefault("lang_packs", langpacks.find_tags(g.get("data_dir")))
-        extra.setdefault("asset_files", langpacks.find_content_files(g.get("data_dir")))
+        extra.setdefault("lang_packs", langpacks.find_tags(data))
+        extra.setdefault("asset_files", langpacks.find_content_files(data))
    except OSError:
        return False
    return True
@@ -15,11 +15,21 @@ class SourceGame:
    data_dir: Path | None = None  # folder whose contents go to Android/obb/<package>/
    origin: Path | None = None  # the folder the game was found in
    alt_apks: list[Path] = field(default_factory=list)
+    # only these files of data_dir are the game's data (expansion files found by name, e.g. next to the APK); None =
+    # everything below data_dir
+    data_files: list[str] | None = None

    def data_bytes(self) -> int:
-        if not self.data_dir or not self.data_dir.is_dir():
-            return 0
-        return sum(p.stat().st_size for p in self.data_dir.rglob("*") if p.is_file())
+        return sum(data_manifest(self.data_dir, self.data_files).values())
+
+
+def data_manifest(data_dir: Path | None, files: list[str] | None = None) -> dict[str, int]:
+    """{path relative to data_dir: size} of a game's data: every file below data_dir, or only `files` (names in it)."""
+    if not data_dir or not data_dir.is_dir():
+        return {}
+    if files is not None:
+        return {name: (data_dir / name).stat().st_size for name in sorted(files) if (data_dir / name).is_file()}
+    return {p.relative_to(data_dir).as_posix(): p.stat().st_size for p in sorted(data_dir.rglob("*")) if p.is_file()}


@dataclass
@@ -15,7 +15,7 @@ from collections.abc import Callable
 from ..core import applog

 MIN_AGENT = 62  # first agent with `_monitor`
-MIN_AGENT_MODULES = 63  # first agent that takes {"modules": [...]} (collects only what's asked for)
+MIN_AGENT_MODULES = 65  # first agent that takes {"modules": [...]} (collects only what's asked for)
 MODULES = ("games", "procs", "cpu", "gpu", "mem", "temps", "power", "battery", "net", "disk")  # agent MON_MODULES
 HISTORY = 120   # points per sparkline (2 min at 1 s)
 REPLY_TIMEOUT = 15.0
@@ -0,0 +1,98 @@
+"""Games on another drive of the Frame (a microSD card, GitHub #90): which drives there are, where new games go
+(library setting `install.drive`) and moving an installed game. No Flet here (the CLI and GUI share it).
+
+The agent keeps each game's anchor (launch.sh, deployment.json, artwork) on internal storage and its files in
+`<drive>/FramePort/<package>`; a drive is given by its install dir (or mount point), internal storage by "internal"."""
+from __future__ import annotations
+
+import time
+
+from ..core import library
+from ..core.events import Reporter
+from ..frame.connection import AgentFailed, Frame
+
+SETTING = "install.drive"
+INTERNAL = "internal"
+
+
+def list_drives(frame: Frame) -> list[dict]:
+    """The agent's `drives`: [{id, path, install_dir, label, fstype, internal, removable, free_bytes, total_bytes,
+    usable, reason, games}]."""
+    return frame.agent("drives")["drives"]
+
+
+def install_dest() -> str | None:
+    """Where new games go (None = internal storage)."""
+    value = library.setting(SETTING) or INTERNAL
+    return None if value == INTERNAL else value
+
+
+def set_install_dest(install_dir: str | None) -> None:
+    library.set_setting(SETTING, install_dir or INTERNAL)
+
+
+def free_text(d: dict) -> str:
+    """"112.4 GiB free" ("" when unknown)."""
+    from ..i18n import tr
+
+    free = d.get("free_bytes")
+    return tr("{size:.1f} GiB free").format(size=free / 2**30) if isinstance(free, (int, float)) else ""
+
+
+def drive_text(d: dict) -> str:
+    """"SD Card · 112.4 GiB free" (labels for menus and dropdowns)."""
+    return " · ".join(filter(None, [d.get("label") or d.get("path"), free_text(d)]))
+
+
+def game_drive(dep: dict | None) -> dict | None:
+    """{"internal", "path", "label", "missing"} of an installed game (the agent's list_installed entry), or None for
+    agents before v63."""
+    if not dep or "drive" not in dep:
+        return None
+    return {**dep["drive"], "missing": bool(dep.get("drive_missing"))}
+
+
+def is_on(dep: dict | None, d: dict) -> bool:
+    """The game (list_installed entry) is on drive d (a `drives` entry)."""
+    g = game_drive(dep)
+    if not g:
+        return d.get("internal", False)
+    return bool(g["internal"]) if d.get("internal") else (not g["internal"] and g["path"] == d["path"])
+
+
+def move(frame: Frame, package: str, dest: str, reporter: Reporter, poll: float = 2.0,
+         timeout: float = 6 * 3600, sleep=time.sleep) -> dict:
+    """Move an installed game to `dest` (a drive's install dir or "internal"). The copy runs on the Frame by itself;
+    this follows its progress (a reconnect picks a running move of the same game up again). Cancel works until the
+    copy has started."""
+    reporter.stage("Move game files")
+    st = frame.agent("move_status")
+    if not (st.get("state") == "running" and st.get("package") == package):
+        reporter.check_cancel()
+        try:
+            st = frame.agent("move", package=package, dest=dest)
+        except AgentFailed as exc:
+            # a job that lost the Frame runs again: the move it started may have finished meanwhile
+            if "already there" in str(exc):
+                reporter.check("Game files moved", True, "already there")
+                return {"state": "done", "package": package}
+            raise
+        reporter.log(f"moving {st['from']} → {st['to']} ({st['total_bytes'] / 2**30:.1f} GiB"
+                     + (", same drive" if st.get("same_drive") else "") + ")")
+    end = time.time() + timeout
+    while time.time() < end:
+        st = frame.agent("move_status")
+        if st.get("state") in ("done", "failed"):
+            break
+        total, done = st.get("total_bytes") or 0, st.get("done_bytes") or 0
+        phase = {"copying": "Copying", "verifying": "Checking the copy", "removing": "Removing the old copy"}.get(
+            st.get("phase") or "", "Starting")
+        reporter.progress(done / total if total else 0.0,
+                          f"{phase} {done / 2**30:.1f}/{total / 2**30:.1f} GiB" if total else phase)
+        sleep(poll)
+    else:
+        raise RuntimeError("the move didn't finish in time; it may still be running on the Frame")
+    if st.get("state") != "done":
+        raise RuntimeError(f"moving failed: {st.get('error') or 'unknown error'} (the game stays where it was)")
+    reporter.check("Game files moved", True, st.get("base") or st.get("to") or "")
+    return st
@@ -10,7 +10,7 @@ from pathlib import Path
 from ..artwork import fetch as artwork
 from ..build import sha256
 from ..core.events import Reporter
-from ..core.models import Recipe
+from ..core.models import Recipe, data_manifest
 from ..frame.connection import Frame, sh_quote
 from ..patches import base
 from ..patches.settings import adapter_settings
@@ -25,6 +25,7 @@ class InstallPlan:
    recipe: Recipe
    apk_only: bool = False  # reuse the data already on the Frame
    dest: str | None = None
+    data_files: list[str] | None = None  # only these files of data_dir (SourceGame.data_files); None = all of it


 def install_context(recipe: Recipe) -> base.InstallContext:
@@ -38,10 +39,8 @@ def install_context(recipe: Recipe) -> base.InstallContext:
    return ctx


-def local_data_manifest(data_dir: Path | None) -> dict[str, int]:
-    if not data_dir or not data_dir.is_dir():
-        return {}
-    return {p.relative_to(data_dir).as_posix(): p.stat().st_size for p in sorted(data_dir.rglob("*")) if p.is_file()}
+def local_data_manifest(data_dir: Path | None, files: list[str] | None = None) -> dict[str, int]:
+    return data_manifest(data_dir, files)


 class Speed:
@@ -74,7 +73,7 @@ def install(frame: Frame, plan: InstallPlan, reporter: Reporter) -> dict:
    if not prep.get("lepton"):
        raise RuntimeError("Lepton is not installed on the Frame (Setup → Install Lepton)")
    incoming = prep["incoming"]
-    manifest = {} if plan.apk_only else local_data_manifest(plan.data_dir)
+    manifest = {} if plan.apk_only else local_data_manifest(plan.data_dir, plan.data_files)
    existing = prep["existing_obb"]
    to_send = [rel for rel, size in manifest.items() if existing.get(rel) != size]
    need = sum(manifest[r] for r in to_send) + (0 if prep["same_apk"] else plan.apk.stat().st_size)
@@ -228,6 +227,8 @@ class LinuxPlan:
    appimage: bool = False
    openxr: bool = False
    x86_64: bool = False  # runs through FEX (installed on the Frame first, like Proton)
+    dest: str | None = None  # a drive's install dir for a new install (GitHub #90); None = internal storage
+    desktop_entry: bool = True  # an entry in Desktop Mode's menu and on its desktop (GitHub #84)


 def install_linux(frame: Frame, plan: LinuxPlan, reporter: Reporter) -> dict:
@@ -236,7 +237,7 @@ def install_linux(frame: Frame, plan: LinuxPlan, reporter: Reporter) -> dict:
    if plan.x86_64:
        ensure_proton(frame, reporter, kind="linux_x86")
    reporter.stage("Prepare Frame")
-    prep = frame.agent("prepare_linux", package=plan.package, title=plan.title)
+    prep = frame.agent("prepare_linux", package=plan.package, title=plan.title, dest=plan.dest)
    if plan.files:
        manifest = {name: (plan.root / name).stat().st_size for name in plan.files}
    else:
@@ -259,8 +260,13 @@ def install_linux(frame: Frame, plan: LinuxPlan, reporter: Reporter) -> dict:
    executables = [rel for rel in manifest if rel != plan.exe and _is_elf(plan.root / rel)][:200]
    result = frame.agent("finalize_linux", package=plan.package, title=plan.title, exe=plan.exe,
                         appimage=plan.appimage, openxr=plan.openxr, x86_64=plan.x86_64, manifests={"app": manifest},
-                         executables=executables, tags=_tags(plan.package), timeout=900)
+                         executables=executables, tags=_tags(plan.package), dest=plan.dest,
+                         desktop_entry=plan.desktop_entry, timeout=900)
    reporter.log(f"installed at {result['base']} (Steam shortcut id {result['appid']})")
+    apply_app_icon(frame, plan.package, prep.get("anchor"), result, reporter)
+    if result.get("desktop_entry"):
+        reporter.check("Desktop Mode entry", True, "in the application menu"
+                       + (" and on the desktop" if result["desktop_entry"].get("desktop") else ""))
    return result


@@ -426,9 +432,46 @@ def upload_steam_art(frame: Frame, package: str, base: str, reporter: Reporter)
    frame.run(f"rm -rf {sh_quote(remote_art)} && mkdir -p {sh_quote(remote_art)}")
    for kind, f in art.items():
        frame.put(f, posixpath.join(remote_art, f"{kind}{f.suffix}"), resume=False)
+    send_icon_source(frame, package, remote_art)
    reporter.check("Steam artwork", bool(art) or None, ", ".join(sorted(art)) or "none found")


+def send_icon_source(frame: Frame, package: str, remote_art: str) -> None:
+    """Tell the agent what the art set's icon is (artwork/.icon-source, agent v64): a Linux app's own icon is used
+    for its Desktop Mode entry and Steam shortcut unless the user chose one ("custom")."""
+    from ..artwork.sources import icon_source
+
+    frame.run(f"printf %s {sh_quote(icon_source(package))} > {sh_quote(posixpath.join(remote_art, '.icon-source'))}")
+
+
+def apply_app_icon(frame: Frame, package: str, anchor: str | None, result: dict, reporter: Reporter) -> None:
+    """A Linux app's own icon the agent found in its files (GitHub #99) becomes the library's icon when the game has
+    none (no user pick, no store icon); the Frame's art set is then sent again so Steam's art shows it too."""
+    import base64
+
+    from ..artwork import sources, steam
+
+    icon = result.get("app_icon") or {}
+    if icon:
+        reporter.log(f"the app's own icon: {icon.get('file')}")
+    if not icon.get("png") or not anchor:
+        return
+    try:
+        stored = sources.apply_app_icon(package, base64.b64decode(icon["png"]))
+        if not stored:
+            return
+        steam.ensure_cover(package)
+        art = steam.steam_set_for(package)
+    except Exception as exc:  # noqa: BLE001 - artwork is optional
+        reporter.log(f"the app's own icon wasn't used for the library: {exc}")
+        return
+    remote = posixpath.join(anchor, "artwork")
+    for kind, f in art.items():
+        frame.put(f, posixpath.join(remote, f"{kind}{f.suffix}"), resume=False)
+    send_icon_source(frame, package, remote)
+    reporter.check("App icon", True, "the app's own icon is used for the library")
+
+
 def update_steam_art(frame: Frame, package: str, reporter: Reporter) -> dict:
    """Replace an installed game's Steam library art with the current artwork (after the user picked new art):
    the art set goes to the game's anchor, then the shortcut is rewritten (Steam restarts once)."""
@@ -447,6 +490,7 @@ def update_steam_art(frame: Frame, package: str, reporter: Reporter) -> dict:
    frame.run(f"rm -rf {sh_quote(remote)} && mkdir -p {sh_quote(remote)}")
    for kind, f in art.items():
        frame.put(f, posixpath.join(remote, f"{kind}{f.suffix}"), resume=False)
+    send_icon_source(frame, package, remote)
    reporter.check("Steam artwork", True, ", ".join(sorted(art)))
    return add_to_steam(frame, [package], reporter)

@@ -318,6 +318,7 @@ class _Handler(BaseHTTPRequestHandler):
            self._send(503, relay.ended.encode(), "text/plain")
            return
        init, gop, q = relay.subscribe()
+        sent, why, t0 = 0, "the stream ended", time.time()
        try:
            deadline = time.time() + 30
            while init is None:  # the source hasn't sent its init segment yet
@@ -335,6 +336,9 @@ class _Handler(BaseHTTPRequestHandler):
            self._chunk(init)
            for f in gop:
                self._chunk(f)
+            sent = len(gop)
+            agent = self.headers.get("User-Agent", "?")[:60]
+            log.info("live view: viewer joined (%s)", agent)
            while True:
                try:
                    f = q.get(timeout=5)
@@ -342,14 +346,18 @@ class _Handler(BaseHTTPRequestHandler):
                    if relay.ended:
                        break
                    continue
-                if f is None:
+                if f is None:  # finish() or dropped for lagging CLIENT_QUEUE fragments behind
+                    why = "the stream ended" if relay.ended else "it fell too far behind"
                    break
                self._chunk(f)
+                sent += 1
            self.wfile.write(b"0\r\n\r\n")
-        except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError, OSError):
-            pass
+        except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError, OSError) as exc:
+            why = f"it disconnected ({type(exc).__name__})"
        finally:
            relay.unsubscribe(q)
+        if init is not None:
+            log.info("live view: viewer left after %.1f s, %d fragments: %s", time.time() - t0, sent, why)

    def _chunk(self, data: bytes) -> None:
        self.wfile.write(f"{len(data):x}\r\n".encode() + data + b"\r\n")
@@ -614,6 +622,13 @@ class FrameSource:

 def start(frame, quality: str = DEFAULT_QUALITY) -> LiveStream:
    """Start streaming the Frame's headset view; open `.url` in a browser to watch."""
+    client = getattr(frame, "client", None)
+    transport = client.get_transport() if client is not None else None
+    if transport is None or not transport.is_active():
+        # (e.g. the Frame slept: without this, the helper upload failed with "'NoneType' object has no attribute
+        # 'exec_command'" and the start went on with the software encoder)
+        raise ConnectionError("The Frame isn't connected (it may be asleep): connect it again on the Steam Frame "
+                              "page, then start the live view")
    src = FrameSource(frame, quality)
    live = LiveStream(src.open, src.close)
    live.relay.on_join = src.request_keyframe
@@ -149,3 +149,10 @@ def delete(frame, shots: list[dict]) -> int:
        for kind in ("thumb", "full"):
            (cache_dir(frame) / _cache_name(s, kind)).unlink(missing_ok=True)
    return len(r.get("deleted") or [])
+
+
+def take(frame, wait: float = 8) -> dict:
+    """Take a headset screenshot on the Frame (agent v66 `take_screenshot`: OpenVR's RequestScreenshot +
+    SubmitScreenshot, saved by Steam under SteamVR like one taken in the headset): {taken, path, reason, hmd}.
+    reason "steamvr" = SteamVR isn't running, "capture" = nothing captured (the headset sleeps)."""
+    return frame.agent("take_screenshot", wait=wait)
@@ -19,9 +19,11 @@
 " · link": "",
 " · not installed yet": "",
 " · on the Frame: ": "",
+ " · on {label}": "",
 " · restart the Frame soon to reset it": "",
 " · Revive provides the Oculus runtime": "",
 " · {human} in files": "",
+ " · {label} not inserted": "",
 " · {queued} more queued": "",
 " · {value:.0f} MiB": "",
 " · {value:.1f} GiB": "",
@@ -35,6 +37,8 @@
 ],
 ", {n} screenshots": "",
 "0 = the size of your play area.": "",
+ "10 games on the Frame. It's getting cosy in there.": "",
+ "100 games on the Frame. The Frame thanks you.": "",
 "108 Hz": "",
 "120 Hz": "",
 "144 Hz": "",
@@ -92,6 +96,7 @@
 "Add {name}": "",
 "Added automatically (engine, VR API or store genre)": "",
 "Added automatically when needed": "",
+ "Added to Desktop Mode": "",
 "Added {n} game": [
  "",
  ""
@@ -104,6 +109,7 @@
 "Adds a small piece of Meta's platform library that some games need to start.": "",
 "Adds no-op com.oculus.os.AnalyticsEvent / UnifiedTelemetryLogger classes for native code that looks them up through the app class loader (e.g. Nano, NOPE Challenge).": "",
 "Adds OVRPort's OpenXR loader dispatcher and platform loader. Required: without it nothing is translated.": "",
+ "Adds the app to Desktop Mode's application menu and puts 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.": "",
 "Adds the parts that let a Quest game talk to the Steam Frame. Needed for every Quest game.": "",
 "Adds the VR app metadata other launchers expect.": "",
 "Advanced": "",
@@ -111,6 +117,8 @@
 "All at their defaults": "",
 "All games": "",
 "All of FramePort's data on this PC is gone": "",
+ "All of Steam's headset screenshots, newest first.": "",
+ "All releases": "",
 "All {n} {name} processes ended.": "",
 "Allow swapchains larger than 4096 px": "",
 "Allows data backup.": "",
@@ -131,6 +139,7 @@
 "Analyze again": "",
 "Analyze {title} again": "",
 "Android": "",
+ "Android and Linux apps": "",
 "Android app": "",
 "Android app (APK)": "",
 "Android app without VR: installed unchanged and shown as a flat window": "",
@@ -158,6 +167,7 @@
 "Assassin's Creed Nexus: smoother picture at 72 Hz (turns off Meta's frame-rate trick).": "",
 "Assassin's Creed Nexus: smoother picture at 90 Hz (turns off Meta's frame-rate trick).": "",
 "At most this many redraws per second of a 360° layer (0 = no limit). Video players need at least the video's frame rate.": "",
+ "Automatic": "",
 "Automatic ({auto:.0%})": "",
 "Automatic SteamVR performance settings (this PC)": "",
 "Back to library": "",
@@ -169,9 +179,11 @@
 "Best guess": "",
 "Blit quads flagged XrCompositionLayerImageLayoutFB VERTICAL_FLIP upside down (Vulkan). Fixes UI panels and text that show upside down (e.g. Assassin's Creed Nexus).": "",
 "Browse and manage files on the Frame (Files tab): upload from this PC, download, rename, delete. Videos, Downloads and Documents are shared by every Quest game (/sdcard/Movies, /sdcard/Download, /sdcard/Documents); each installed game also has its own storage (its /sdcard). Apps find files by browsing folders. Video players that list only their own folder (for example 4XVR's Internal Storage = 4XPlayer): upload into that folder in the game's storage.": "",
+ "Browse each installed game's files and download your saves.": "",
 "Build page": "",
 "Cable connected.": "",
 "Camera": "",
+ "can't hold games: {reason}": "",
 "Can't reach your Frame. Make sure it's on, awake and on the same network, then try again.": "",
 "Can't run": "",
 "Can't use that link: {reason}": "",
@@ -225,6 +237,11 @@
 "Command-line arguments for the game program. Games that support several VR runtimes pick one with an argument, e.g. Unreal's -hmd=OpenXR or -hmd=SteamVR, Unity's -vrmode OpenVR, or a game's own switch (-Runtime=OpenXRHMD). FramePort fills them in from the game files (the repack's VD.bat with the Oculus module swapped for OpenXR, else the engine's usual switch).": "",
 "Connect": "",
 "Connect the Frame's USB-C port to this PC with a USB cable (a data cable, not a charge-only one).": "",
+ "Connect to your Steam Frame to browse its videos, downloads and each game's storage.": "",
+ "Connect to your Steam Frame to see its screenshots here.": "",
+ "Connect to your Steam Frame to stream its view and sound to this PC.": "",
+ "Connect to your Steam Frame to type into the headset from here.": "",
+ "Connect to your Steam Frame to watch its games, load, temperatures and battery live.": "",
 "Connect your Frame": "",
 "Connect your Frame first": "",
 "Connect your Steam Frame": "",
@@ -240,13 +257,16 @@
 "Continue": "",
 "Controller input diagnostics (log)": "",
 "Controllers": "",
+ "Converted for the Steam Frame, then installed over Wi-Fi or USB.": "",
 "Converts Quest games to OpenXR": "",
 "Copied": "",
 "Copied: save it as a .json file, change the colors and install it": "",
+ "Copies the game's files, data and saves to the other drive, checks the copy and then removes the old one. The Steam entry, settings and saves stay valid. The game must be closed. A game on a microSD card only starts while the card is inserted.": "",
 "Copy": "",
 "Copy all": "",
 "Copy failed; select the text instead": "",
 "Copy folder path": "",
+ "Copy image": "",
 "Copy log": "",
 "Copy name": "",
 "Copy OVRPlugin if VrApi is present": "",
@@ -256,6 +276,8 @@
 "Copy this theme as a file": "",
 "Couldn't check this PC": "",
 "Couldn't connect: {exc}": "",
+ "Couldn't copy the screenshot: {error}": "",
+ "Couldn't list the Frame's drives: {error}": "",
 "Couldn't list the screenshots: {exc}": "",
 "Couldn't list {path}: {exc}": "",
 "couldn't load the full image: {exc}": "",
@@ -265,12 +287,14 @@
 "Couldn't read {path}: {exc}": "",
 "Couldn't remove the theme: {error}": "",
 "Couldn't start the live view: {exc}": "",
+ "Couldn't take a screenshot: {error}": "",
 "Couldn't use {choice}: {exc}": "",
 "Counts the headset as worn, so games that only move the player while it's worn get head tracking and controls (e.g. BONELAB).": "",
 "Cover": "",
 "CPU": "",
 "CPU cores": "",
 "CPU {cpu} · GPU {gpu} · memory {mem} · {n} processes": "",
+ "CPU, GPU, memory, temperatures, power and battery.": "",
 "Create": "",
 "Customize": "",
 "Cylinder layers (curved menus and movie screens, e.g. 4XVR), which the Frame's runtime lacks, are shown as a few flat strips along the curve. 0 = drop them. 360° (equirect) layers can't be shown on the Frame.": "",
@@ -296,7 +320,9 @@
 "Delete…": "",
 "Deselect": "",
 "Desktop": "",
+ "Desktop Mode": "",
 "Details": "",
+ "dev build": "",
 "Dev builds let you test fixes before they're released. They're less tested than releases and may have bugs. You get the next release as a normal update (you have {version}).": "",
 "Developer Mode (on the Frame: Settings → System → Enable Developer Mode) lets FramePort find the Frame on your network and connect to it over SSH. The first-time setup command turns it on for you. With Developer Mode on you can also pair without the setup command: on the Frame open Settings → Developer → Pair new host, click Connect there and approve FramePort. That way needs no connection from the Frame into this PC.": "",
 "Diagnostics: the Vulkan shim (frame.vk_sanitize) adds Khronos' validation layer to the game's instance; its findings go to launch.log. The layer library (libVkLayer_khronos_validation.so) must be in the APK.": "",
@@ -315,6 +341,7 @@
 "Download all ({n})…": "",
 "Download all…": "",
 "Download and install": "",
+ "Download one, a selection or all of them.": "",
 "Download selected…": "",
 "Download to this PC…": "",
 "Download to which folder on this PC?": "",
@@ -346,6 +373,7 @@
 "Drop to upload": "",
 "Drops Quest-only shared library requirements.": "",
 "Each patch is described in plain words. Turn this on to also see its id, exactly what it changes in the game (useful when reporting a problem) and its parameters.": "",
+ "Each shot is labelled with the game you were playing.": "",
 "Enabled by you.": "",
 "End all": "",
 "End all {n} {name}?": "",
@@ -363,7 +391,9 @@
 "Environment variables for the Proton launcher on the Frame (e.g. DXVK_HUD=fps), one KEY=value per line.": "",
 "Every 'local' play space the game creates lines up with the one at the start. For games whose menus or screens jump to where you look on the Frame.": "",
 "Every game start on the Frame used to leak one kernel key, and after about 200 launches every game fails to start. FramePort switches that leak off, but keys already used only come back after a restart of the Frame.": "",
+ "Every key goes through": "",
 "Every N seconds, saves the left-eye image the game submits (a quarter of its size) as fb_snap_0-7.ppm in the game's files folder on the Frame. Launch tests run without anyone wearing the headset, so the headset view stays black; this shows what the game itself draws. OpenGL ES games only.": "",
+ "Every shot you take in the headset": "",
 "Every uploaded file is present with the right size.": "",
 "Every {n}": "",
 "everything in ~ (not seen by games)": "",
@@ -386,7 +416,7 @@
 "Files": "",
 "Files and environment on the Frame": "",
 "Files and environment variables placed next to the game on the Frame.": "",
- "Files on the Frame can be browsed once FramePort is connected to it.": "",
+ "Files and whole folders": "",
 "Files on the Frame — {title}": "",
 "Files on the Frame: browse what this install contains": "",
 "Filter files (for example .pak, Binaries)": "",
@@ -439,6 +469,7 @@
 "Found": "",
 "fps": "",
 "fps isn't reported for PC VR and Linux games": "",
+ "fps · perfect pacing": "",
 "fps · target {hz} Hz": "",
 "fps: waiting for the game's first frames": "",
 "Frame agent": "",
@@ -446,10 +477,12 @@
 "Frame battery: not charging": "",
 "Frame not connected": "",
 "Frame OpenXR compatibility layer": "",
+ "Frame rate": "",
 "FrameBridge OpenXR adapter": "",
 "FramePort": "",
 "FramePort can't add {name}: drop an APK, a Linux build (.zip, AppImage), a Windows program (.exe) or a folder": "",
 "FramePort can't replace itself in {value} (no permission): opening the release page to download it": "",
+ "FramePort changelog": "",
 "FramePort checks GitHub for a new release every few hours and shows it in the sidebar and the Library. \"Update now\" downloads it, checks its checksum (and on Windows its signature), closes FramePort and opens the new version; your games, settings and Frame connection are kept. With automatic install, the download happens in the background and the new version starts next time.": "",
 "FramePort downloads it, checks it, closes and opens again as the new version. Your games, settings and Frame connection stay as they are.": "",
 "FramePort found more than one arm64 program in this app. Pick the one that starts it (helpers such as crash reporters or updaters are the wrong choice).": "",
@@ -457,6 +490,7 @@
 "FramePort has Steam on the Frame download Proton and the runtime it needs (about 1 GiB). Steam restarts once, which closes a running game.": "",
 "FramePort installs games on the Frame over your network": "",
 "FramePort installs games on the Frame over your network.": "",
+ "FramePort live view": "",
 "FramePort manages its own copies; nothing is installed system-wide": "",
 "FramePort picked {value} to start this game, but there are other candidates. Check it before installing.": "",
 "FramePort runs in WSL with its default NAT network, which other devices can't reach. Set networkingMode=mirrored under [wsl2] in %UserProfile%\\.wslconfig, run wsl --shutdown and start FramePort again.": "",
@@ -464,6 +498,8 @@
 "FramePort then finds the Frame on the cable by itself.": "",
 "FramePort updates and restarts after the current job": "",
 "FramePort was removed": "",
+ "FramePort was updated to {version}.": "",
+ "FramePort {version}": "",
 "FramePort {version} is available": "",
 "FramePort {version} is available (you have {version2}).": "",
 "FramePort {version} is available.": "",
@@ -489,6 +525,7 @@
 "Game": "",
 "Game arguments (select SteamVR / OpenXR)": "",
 "Game config files": "",
+ "Game data (.obb) not found": "",
 "game data (OBB)": "",
 "Game launch capacity": "",
 "Game not found": "",
@@ -501,6 +538,7 @@
 "Game settings: picture, controllers, menus and more, used by the adapter FramePort adds to Quest games. Change them here or from the Frame page; an installed game uses them the next time it starts.": "",
 "Game settings…": "",
 "Game storage": "",
+ "Game storage and saves": "",
 "Game's choice": "",
 "Game: the running FramePort game's processes (its Android container or Proton) plus the busiest others. Steam & SteamVR: Steam, SteamVR and the desktop. All: every program of your user on the Frame. A lock marks programs whose end would close Steam, SteamVR or the desktop.": "",
 "Games see this folder as {value}": "",
@@ -513,6 +551,7 @@
 "Gives older Quest games a newer version of Meta's VR plugin that can be converted.": "",
 "GL shim (Mesa GLSL compatibility)": "",
 "GL shim for Unity (no multisampled render-to-texture)": "",
+ "GL shim for Unreal (no multisampled render-to-texture)": "",
 "GL shim only: hide GL_EXT_multisampled_render_to_texture(2) (Zink crashes rendering Unity's runtime MSAA eye buffer through it, e.g. The Room VR).": "",
 "GL shim only: hide GL_OVR_multiview so all passes use single-view shaders. For GLES games whose multiview shaders fail on single-view render targets (e.g. Path of the Warrior).": "",
 "GL shim: hide multisampled render-to-texture": "",
@@ -523,7 +562,16 @@
 "GPU": "",
 "Graphics": "",
 "Group": "",
+ "Hang in there, little Frame": "",
+ "Happy Easter!": "",
+ "Happy Halloween!": "",
+ "Happy holidays!": "",
+ "Happy New Year!": "",
+ "Happy Pi Day! 3.14159…": "",
+ "Happy St. Patrick's Day!": "",
+ "Happy Valentine's Day!": "",
 "hardware encoder": "",
+ "Hi there!": "",
 "Hide Android's navigation bar": "",
 "Hide details": "",
 "Hide its processes": "",
@@ -554,7 +602,12 @@
 "If you know the Frame's address.": "",
 "Ignore focus dips up to": "",
 "Image for the {label}": "",
+ "in an mpv window": "",
 "In the headset, select a text field, then type here.": "",
+ "In the menu and on the desktop": "",
+ "In this window": "",
+ "in this window": "",
+ "in your browser": "",
 "In your Steam library": "",
 "In your Steam library · launch settings changed — update it": "",
 "Install": "",
@@ -568,6 +621,7 @@
 "Install link: {host}": "",
 "Install links": "",
 "Install missing": "",
+ "Install new games to": "",
 "Install on Frame": "",
 "Install on this PC": "",
 "Install Proton on the Frame": "",
@@ -582,6 +636,7 @@
 "Install {n} on Frame": "",
 "Install {title} anyway?": "",
 "Install {title} on {value}": "",
+ "installed": "",
 "Installed": "",
 "Installed games ({len})": "",
 "Installed the theme \"{name}\"": "",
@@ -597,6 +652,7 @@
 "Installs the app as it is, with an entry in the Frame's Steam library": "",
 "Installs the game exactly as it is: no patches (your copy is already patched)": "",
 "Install…": "",
+ "Internal storage": "",
 "into {value}": "",
 "It belongs to a running game, which may stop with it.": "",
 "It can't be reached (asleep, turned off or out of Wi-Fi). Wake it or turn it on: FramePort continues by itself, and uploads pick up where they stopped.": "",
@@ -608,6 +664,10 @@
 "It will be closed without saving. Continue?": "",
 "It won't start on the Frame: SteamOS doesn't have these libraries and the app doesn't bring them. Look for a build of the app that includes them, then install that one.": "",
 "It works: share…": "",
+ "It's doing its best": "",
+ "it's here now": "",
+ "its drive": "",
+ "Its manifest asks for Android {version} (API {api}); the Frame's Android is 11 (API 30). Apps like this often crash at start, but not always: try it, a launch test tells.": "",
 "Java runtime": "",
 "Java, OVRPort and apksigner are ready.": "",
 "just now": "",
@@ -646,17 +706,21 @@
 "Lets games written for newer OpenXR versions run on the Frame.": "",
 "Lets mixed-reality games start even though they insist on a camera view of your room.": "",
 "Lets older Unity games start VR without Meta's system apps (they'd stay on a 2D screen).": "",
+ "Lets older Unreal games start VR although the converted VR plugin lacks a few functions they look for (e.g. Star Wars Pinball VR).": "",
 "Lets SDL and LÖVE games start on the Frame (they'd crash looking for a clipboard).": "",
 "Lets Team Beef ports (e.g. Lambda1VR) start on the Frame and use their Meta Quest setup.": "",
 "Lets the game find content it keeps in separate files next to its data (e.g. Star Wars Tales' seasons).": "",
 "Lets the game find language files (like de.lang) that are already in its data, instead of waiting for a download that never comes.": "",
 "Lets typing reach this app: Steam's on-screen keyboard or your computer's keyboard (VR is unaffected).": "",
 "Lets Unity games accept a headset that isn't a Quest.": "",
+ "Lets Unity start the graphics itself instead of Stress Level Zero's plugin, which crashes on the Frame (e.g. BONELAB 1.2974).": "",
 "Lets Unreal games accept a headset that isn't a Quest.": "",
 "Lets Unreal games accept a headset that isn't an Oculus Rift.": "",
 "Lets you read logs/attach. Some Unreal games abort under CheckJNI when debuggable; the Frame 'nodebug' fix undoes it.": "",
 "Lets you type into this app's text fields on the Frame (they'd close at once).": "",
+ "Letters, Enter, Backspace, arrows, Esc and shortcuts reach the headset.": "",
 "Library": "",
+ "Light on the game": "",
 "Link": "",
 "Linux": "",
 "Linux app": "",
@@ -666,10 +730,12 @@
 "Linux VR app · OpenXR": "",
 "Live": "",
 "Live view": "",
+ "Load and temperatures": "",
 "Loading…": "",
 "Loads FramePort's OpenXR layer under Proton on the Frame. The Frame's SteamVR runtime only accepts OpenXR 1.0 apps, but Proton's VR helper asks for 1.1, so without the layer VR never starts (the game shows as a flat window, or Revive fails with 'Unable to load LibOVRRT DLL'); the layer retries as 1.0. It also emulates xrConvertTimespecTimeToTimeKHR if a runtime refuses it. Ignored on this PC.": "",
 "Loads libglshim.so ahead of libEGL in every engine library that fetches GL through eglGetProcAddress. Fixes Quest-only leniency that Mesa/Zink rejects: #pragma before #extension, implicit int/float conversions (enables GL_EXT_shader_implicit_conversions), and multiview shaders used on single-view framebuffers (hides GL_OVR_multiview; gl_hide_multiview=0 turns that off). Logs every failed shader with its source lines (logcat tag GLShim). Symptom: black screen with working audio in a GLES game.": "",
 "Loads the GL shim into a Unity GLES game and hides GL_EXT_multisampled_render_to_texture (and the multiview variant). Some Unity games switch their eye buffer to 4x MSAA at runtime; the Frame only gives single-sampled swapchains, Unity then renders through multisampled render-to-texture and Mesa/Zink crashes (SIGSEGV in libgallium_dri.so on the render thread: grey or frozen screen, e.g. The Room VR). Hidden, Unity uses an ordinary MSAA buffer and resolves it. Unity's multiview stays on (gl_hide_multiview defaults to 0 here).": "",
+ "Loads the GL shim into an Unreal GLES game and hides GL_EXT_multisampled_render_to_texture. Unreal's mobile MSAA renders through multisampled render-to-texture, and the Frame's GL driver (Mesa/Zink) can crash on it: SIGSEGV with fault address 0x10000 in libgallium_dri.so on the RHIThread a few seconds after start (Zink looks up a render-pass cache slot past its end, e.g. Star Wars Pinball VR). Hidden, Unreal renders without that path. Unreal's multiview stays on: Unreal only uses it when GL_OVR_multiview_multisampled_render_to_texture is listed too, so for Unreal the shim keeps that one visible and draws its multiview MSAA attachments single-sampled (glFramebufferTextureMultiviewOVR).": "",
 "Locations": "",
 "Logo": "",
 "Logs details for debugging: composition layers and swapchains, focus changes, play-space creation, pointer vs grip poses, refresh rates. No effect on the game.": "",
@@ -677,6 +743,7 @@
 "Longer for headsets that briefly think they're off your head.": "",
 "Looking at the app": "",
 "Looking at the program": "",
+ "Looking for drives…": "",
 "Looking for Frames on your network…": "",
 "Looking for games": "",
 "Looking for the Frame on a USB cable (Developer Mode on, USB-C port connected to this PC).": "",
@@ -694,6 +761,7 @@
 "Mark application to allow backup": "",
 "Marked \"Can't run\": ": "",
 "Marks the game as a VR app so headsets show it as one.": "",
+ "Matched to your games": "",
 "Maximum": "",
 "Maximum size in pixels of each face of the cube the 360° image is converted to (256–2730). Higher is sharper but uses more GPU memory.": "",
 "Memory": "",
@@ -714,8 +782,13 @@
 "Monitor is using {pct}% of the Frame's CPU": "",
 "More actions": "",
 "More actions…": "",
+ "Move": "",
+ "Move to…": "",
+ "Move {title} to {label}": "",
+ "Move {title} to…": "",
 "Moves where the pointer starts, forward or back.": "",
 "Moves where the pointing ray starts forward (+) or back (−).": "",
+ "mpv window": "",
 "Multiplies the recommended eye-buffer width and height (0.5–2.0). 1.5 ≈ 2.25× pixels.": "",
 "Must be at least the video's own frame rate.": "",
 "Mutable swapchain fix": "",
@@ -729,6 +802,7 @@
 "New folder": "",
 "New folder…": "",
 "New Frame? Run one command on it and FramePort does the rest. Did this once already? Your Frame appears under step 2.": "",
+ "New games go to {label}": "",
 "New name": "",
 "New recipe applied: use Update on Frame to install it": "",
 "Next": "",
@@ -746,9 +820,9 @@
 "No limit": "",
 "No matching files": "",
 "No new games in {name}": "",
- "No notes.": "",
 "No other Frames remembered yet.": "",
 "No process matches.": "",
+ "no reason given": "",
 "No release notes.": "",
 "No screenshots yet": "",
 "No Unreal crash reporter": "",
@@ -763,6 +837,8 @@
 "Not enough space on the Frame ({detail}). Remove games you don't play or use Free up space on the Steam Frame page.": "",
 "Not from a FramePort game": "",
 "Not installed": "",
+ "Not needed in the last build, OVRPort fixed it itself: {names}": "",
+ "Not needed in the last build: OVRPort fixed this itself.": "",
 "Not now": "",
 "Not offered by Steam on this Frame yet": "",
 "Not recommended: breaks games that load VrApi through OVRPlugin.": "",
@@ -777,7 +853,9 @@
 "Nothing running. Installs, launch tests and downloads show up here.": "",
 "Nothing to install": "",
 "Nothing to install on the Frame — those Oculus games need PC mode (SteamVR + Revive).": "",
+ "Nothing to install: add the games' .obb files first": "",
 "Nothing to patch: it runs as is.": "",
+ "Nothing to see here.": "",
 "Now {scale:.0%}.": "",
 "Now {scale:.0%}. Changes apply the next time FramePort starts.": "",
 "Now {scale:.0%}; {new:.0%} after restarting FramePort.": "",
@@ -790,6 +868,8 @@
 "off: {names}": "",
 "Offline": "",
 "Older workaround for upside-down quads: rotates them 180° (quads are single-sided; prefer flip_emul).": "",
+ "ON AIR": "",
+ "On air: the live view is streaming": "",
 "On Frame": "",
 "On the Frame, open Steam's Settings (Steam button → Settings).": "",
 "On the Frame, place Revive's runtime (FramePort's Revive, or the repack's bundled LibRevive) where the game's Oculus SDK looks for LibOVRRT so it can load a VR runtime (pure runtime substitution — what Revive's LoadLibrary hook does on Windows; that hook doesn't work under Proton on the Frame). It does NOT bypass the Oculus runtime signature check: a game that verifies the runtime's signature will still refuse it. Ignored on this PC (Revive's hook handles it there).": "",
@@ -804,14 +884,15 @@
 "Only if 360° pictures show wrongly.": "",
 "Only if 360° pictures show wrongly: 1 = upside down, 2 = mirrored, 4 = turned around (add values to combine).": "",
 "Only install software from sites you trust. FramePort downloads it from {host} and installs it on your Frame.": "",
+ "Only internal storage": "",
 "Open": "",
 "Open \"Install with FrameDrop\" buttons (framedrop:// links) in FramePort": "",
 "Open frameport:// links in FramePort": "",
 "Open game": "",
 "Open game page": "",
 "Open GitHub issue": "",
+ "Open in browser": "",
 "Open the Monitor": "",
- "Open viewer": "",
 "Open {scheme}:// links with FramePort?": "",
 "OpenGL ES games run on the Frame through Zink (OpenGL on top of Vulkan), which is stricter than Quest drivers. Vulkan games run natively.": "",
 "Opens a prefilled GitHub issue with this game's recipe, so it can join the built-in catalog (no account token needed; you review and submit it on GitHub). No game files or personal data are sent.": "",
@@ -823,6 +904,7 @@
 "Or paste text to type it in one go": "",
 "Or turn on Developer Mode on the Frame (Settings → System → Enable Developer Mode) and pair it under step 2: that needs no connection into this PC.": "",
 "Orange for actions, blue for the PC side: the logo's two portals": "",
+ "Ordinary Android apps and Linux programs run there too.": "",
 "Other": "",
 "other file": "",
 "Override the guardian depth (0 = use guardian, min 1.5 m).": "",
@@ -838,6 +920,7 @@
 "Package": "",
 "Pairing: on the Frame open Settings → Developer → Pair new host, then approve FramePort.": "",
 "Password (first time only)": "",
+ "Paste long text": "",
 "Paste the address of an \"Install with FrameDrop\" button (right-click it → Copy link), a FramePort or FrameDrop manifest (.json) or a direct link to an APK, a Linux build (.zip) or a Windows program (.exe).": "",
 "Patch": "",
 "Patch Meta XR Audio": "",
@@ -855,6 +938,7 @@
 "PC VR": "",
 "PC VR (Revive / Proton)": "",
 "PC VR alternative: {pcvr_alternative}": "",
+ "PC VR games": "",
 "PC VR games (Proton)": "",
 "PC VR games can run on this PC only with Windows (or WSL on Windows)": "",
 "PC VR games on this PC run through SteamVR, so a headset connected to this PC works with them.": "",
@@ -864,7 +948,9 @@
 "PC VR —": "",
 "PC VR ✓": "",
 "Per-eye diagnostics (log)": "",
+ "Perfect pacing": "",
 "Pick several games and install them in one go. FramePort asks every question first, then works through the queue in the background.": "",
+ "Pick the field in the headset": "",
 "Picks a refresh rate and motion smoothing that suit the game on this PC.": "",
 "Pico/YVR/Quest metadata": "",
 "Picture": "",
@@ -872,11 +958,15 @@
 "Pictures you took in the headset (Steam screenshots on the Frame)": "",
 "PID": "",
 "Platform compat (ovrMessageType_ToString)": "",
+ "Play in": "",
 "Play on Frame": "",
 "Play on this PC": "",
 "Play your Quest, Android and PC VR games on the Steam Frame. Three steps and you're set.": "",
 "Play: starts the game through the Frame's Steam (put the headset on)": "",
 "playing": "",
+ "Playing below, in this window.": "",
+ "Playing in an mpv window.": "",
+ "Playing in your web browser.": "",
 "playing · {t}": "",
 "Point FramePort at a folder with Quest or Android games (APK + OBB) or PC VR games. It finds them, works out what each needs and fetches artwork.": "",
 "Pointer angle": "",
@@ -888,6 +978,7 @@
 "Power ICs": "",
 "Prepare {title}": "",
 "Pretend room layout": "",
+ "Pretty smooth": "",
 "Prevents a start-up crash in some Unreal games.": "",
 "Previous": "",
 "Problems and feedback": "",
@@ -902,12 +993,14 @@
 "Provide the Oculus runtime from Revive (Frame)": "",
 "Provides stand-ins for Meta store functions the game expects, so it doesn't crash at start.": "",
 "Provides stand-ins for Quest system reporting some games call at start.": "",
+ "Put a password, link or note in the box and press Type it.": "",
 "Put the Frame to sleep": "",
 "Put the Frame to sleep?": "",
 "Puts settings files next to the game on the Frame (e.g. to turn off an unsupported effect).": "",
 "Quality": "",
 "Quest": "",
 "Quest game": "",
+ "Quest games": "",
 "Quest games (Lepton)": "",
 "Quest ✓": "",
 "Quest ✓: Lepton is installed, so Quest games can run. PC VR ✓: Proton is installed, so PC VR games can run on the Frame.": "",
@@ -923,6 +1016,7 @@
 "ready": "",
 "Ready": "",
 "Ready to play": "",
+ "Ready when you are": "",
 "Rebuild only (no install)": "",
 "Recently added": "",
 "Recently used": "",
@@ -941,6 +1035,7 @@
 "Reinstall on this PC": "",
 "Reinstalls FramePort from the release, then restarts it.": "",
 "Release page": "",
+ "Releases": "",
 "Remembered": "",
 "Remove": "",
 "Remove converted copies now": "",
@@ -954,6 +1049,7 @@
 "Remove VrApi library": "",
 "Remove XR_KHR_composition_layer_depth chains (diagnostic).": "",
 "Remove {title} from the library?": "",
+ "Removed from Desktop Mode": "",
 "Removed the converted copies ({size})": "",
 "Removed the theme \"{name}\"": "",
 "Removed {title}": "",
@@ -1006,6 +1102,7 @@
 "Revive {value} · {value2} backend": "",
 "Revive: SteamVR (OpenVR) backend on PC": "",
 "Rift": "",
+ "Rift games on the Frame through Proton, or on this PC.": "",
 "Room depth": "",
 "Room height": "",
 "Room width": "",
@@ -1024,6 +1121,7 @@
 "Save": "",
 "Save as known-good recipe": "",
 "Save the screenshots to which folder on this PC?": "",
+ "Save them to this PC": "",
 "Saved as a known-good recipe": "",
 "Saved as known-good. Check the issue on GitHub and submit it": "",
 "Saved {name} (in {parent})": "",
@@ -1035,8 +1133,9 @@
 "Scan a folder…": "",
 "Scan {name}": "",
 "Scans the folders you added games from again and adds games that appeared since. Games already in the library keep their recipe, tags and art; unchanged ones aren't analyzed again.": "",
+ "Screenshot copied: paste it anywhere": "",
+ "Screenshot taken": "",
 "Screenshots": "",
- "Screenshots on the Frame can be shown once FramePort is connected to it.": "",
 "SDL apps: start without a clipboard service": "",
 "Search": "",
 "Search again": "",
@@ -1045,8 +1144,11 @@
 "Searched a moment ago.": "",
 "Searching…": "",
 "See every patch and turn them on or off": "",
+ "See what the headset sees": "",
+ "See what's new…": "",
 "See your room": "",
 "Select": "",
+ "Select a text field in the game first: typing goes where it has focus.": "",
 "Select all": "",
 "Select all shown": "",
 "Select games to install": "",
@@ -1081,6 +1183,7 @@
 "Show Steam Frame controllers": "",
 "Show technical details (patch ids, exact effects, parameters)": "",
 "Show the app's Android window (for typing)": "",
+ "Show the mpv window": "",
 "Show the running game on the Frame card": "",
 "Show video panels": "",
 "Showing the top {shown} of {n} rows: search to find others.": "",
@@ -1102,9 +1205,11 @@
 "Skips a Quest-only reporting step in Meta's audio library that crashes some games.": "",
 "Skips Meta XR Audio's telemetry under x86_64 ARM translation (emulators). Not needed on the Frame, which runs games natively.": "",
 "Sleep": "",
+ "Smooth as butter": "",
 "software encoder": "",
 "Some apps open a flat Android launcher that then starts a separate VR activity (e.g. WiiCompiled). Shown with Lepton's flat window, that window stays in view after the VR part starts. This makes the VR activity the one Lepton starts (its LAUNCHER category), so the app opens in VR with no flat window. Everything only the launcher does (choosing or importing content) is skipped: turn it off for a run when you need the launcher, and turn off \"Show the app's Android window\".": "",
 "Some developers put an \"Install with FrameDrop\" button on their site (the protocol of the FrameDrop sideloader). FramePort reads the same links: it shows what the link offers, asks, downloads it, adds it to your library and installs it on the Frame. Only https links to public servers are used. Windows and Linux open these links in FramePort; on macOS, paste the link into Add games → Add from a link….": "",
+ "Some engines contain assembly (e.g. OpenSSL's) that checks a return-address signature it never made. The Quest's CPU ignores those checks, the Steam Frame's enforces them: the game crashes with SIGILL as soon as it uses that code, e.g. on its first network connection (Star Wars Pinball VR). In a library with unpaired checks, the signing and checking instructions become no-ops.": "",
 "Some engines leave the pNext of unused Vulkan attachment references uninitialized. The Frame's driver never reads it, but Lepton always loads Steam's Fossilize shader-cache layer, which follows it and crashes on the first frame (SIGSEGV in libVkLayer_fossilize.so from FVulkanRenderPass, e.g. Deadpool VR). Loads Vulkan through a small shim that keeps valid pointers and drops only unreadable ones or ones pointing at the wrong structure type. It also drops a depth resolve named in a subpass without a depth attachment, which crashes the Frame's driver at the first render pass (e.g. Metro Awakening).": "",
 "Some game folders are already set up for SteamVR: a Revive copy (LibRevive64.dll) next to the game, started by a small loader DLL (e.g. xinput1_3.dll) that Windows loads from the game's folder. Then FramePort starts the game program directly — like double-clicking it — instead of through its own Revive (two Revives conflict; e.g. the Oculus Platform check then fails). On the Frame, Wine is told to use those loader DLLs from the game folder instead of its own.": "",
 "Some games keep content in separate files next to their OBB (e.g. Star Wars: Tales from the Galaxy's Edge: its seasons and sound banks) and ask Meta's platform for them as asset files. OVRPort's platform loader doesn't know them, so the game waits for content that never arrives (black screen after loading). Lists the content files shipped with the game's data (*.pak) as installed and answers their download request at once with the file's path; nothing is copied or downloaded. Shares the language-pack library.": "",
@@ -1113,19 +1218,28 @@
 "Something not working? Collect a diagnostics zip (logs, settings, device info; personal data removed) and attach it to a GitHub issue. For one game, use its menu instead.": "",
 "Something went wrong": "",
 "Sort": "",
+ "Sorted by day": "",
+ "Sound off": "",
+ "Sound on": "",
 "Source": "",
 "square, 256 × 256": "",
 "SSH found by network scan": "",
 "Standard for every game": "",
 "Start live view": "",
 "Start straight in VR (skip the 2D launcher)": "",
- "Start the live view to watch the headset in your browser": "",
+ "Start the live view to watch the headset here.": "",
+ "Start the live view to watch the headset in an mpv window.": "",
+ "Start the live view to watch the headset in your browser.": "",
+ "Starting on Frame…": "",
+ "Starting on this PC…": "",
 "Starting SteamVR and {title} — put your headset on": "",
 "Starting the stream on the Frame…": "",
 "Starting {title} on the Frame — put the headset on": "",
 "Starting {title}, but SteamVR isn't running — it may open as a flat window. Start SteamVR and relaunch.": "",
 "Starting…": "",
+ "Starts a video stream on the Frame and opens it in an mpv window.": "",
 "Starts a video stream on the Frame and opens it in your browser.": "",
+ "Starts a video stream on the Frame and shows it here.": "",
 "Starts the game on the Frame while nobody is wearing it and reads the log: did it start, create a VR session and render frames. It can't check what you'd see: tracking only runs with the headset on.": "",
 "Starts the game through Steam on this PC (SteamVR + Revive)": "",
 "Starts the game through the Frame's Steam — put the headset on": "",
@@ -1144,11 +1258,14 @@
 "SteamOS · Developer Mode": "",
 "steamos@frame.local or an IP address": "",
 "SteamVR": "",
+ "SteamVR isn't running on the Frame: put the headset on, then take the screenshot.": "",
 "Stereo (3D) 360° layers: 0 = as the game sends them, 2 = flat (the left image to both eyes).": "",
 "Stop": "",
 "Stop objects popping in and out": "",
 "Stopped: {why}": "",
+ "Stops a crash a few seconds after start in Unreal games whose anti-aliasing the Frame's graphics driver can't handle (e.g. Star Wars Pinball VR).": "",
 "Stops a crash a few seconds after the logo in games with voice chat.": "",
+ "Stops a crash on the Frame's CPU in games whose code has unpaired security checks the Quest ignores (e.g. Star Wars Pinball VR's first network connection).": "",
 "Stops a grey or frozen screen in Unity games that turn on anti-aliasing while running (e.g. The Room VR).": "",
 "Stops a grey screen crash in some Unity games by skipping their overlay layers (e.g. The Room VR's screen fades).": "",
 "Stops Meta's audio library from reporting to Meta (only matters on PC emulators).": "",
@@ -1162,7 +1279,11 @@
  ""
 ],
 "Store details: {title}": "",
+ "Streaming to an mpv window": "",
+ "Streaming to your browser": "",
 "Streams a small sample from the Frame every 5 seconds (game, frame rate, battery). Turn off to save the Frame's processor.": "",
+ "Stress Level Zero's graphics plugin (libSLZQuestNative.so, e.g. BONELAB 1.2974) hooks Unity's Vulkan start-up and its texture samplers. On the Frame the hook calls an invalid function while Vulkan starts, and the game crashes or hangs before the first frame. The plugin's two hooks are switched off, so Unity starts Vulkan itself. Its pipeline cache isn't used: the first start spends about half a minute prewarming shaders.": "",
+ "Stress Level Zero: let Unity start Vulkan itself": "",
 "Strip depth layers": "",
 "Stub missing Meta platform functions": "",
 "Suggested after a launch test": "",
@@ -1178,6 +1299,7 @@
 "Tags": "",
 "Tags:": "",
 "Take one in the headset with Steam's screenshot shortcut; it shows up here. Screenshots are matched to the FramePort game that was running.": "",
+ "Take screenshot": "",
 "tall, 600 × 900": "",
 "Team Beef ports: treat the Frame as a Meta headset": "",
 "Team Beef's ports (e.g. Lambda1VR, RTCWQuest) load an OpenXR library named after the headset maker and pick their VR setup by maker; for \"valve\" they stop at start (libopenxr_loader_valve.so not found) or take the Pico path. Adds that library and lets them take the Meta path.": "",
@@ -1187,7 +1309,9 @@
 "Test Proton on the Frame": "",
 "Text and layout size": "",
 "That theme file can't be used: {error}": "",
+ "That's me!": "",
 "The APK file is damaged or incomplete. Get the game again and rescan the folder.": "",
+ "The changelog couldn't be loaded (no internet connection?)": "",
 "The command fetches a small setup script from this app over your local network. It turns on Developer Mode (which includes SSH), lets this app's key in and installs Lepton if needed. Turning on Developer Mode closes the Frame's desktop; the setup finishes on its own and FramePort connects by itself. No password needed.": "",
 "The connection to the Frame is busy. Try again in a moment.": "",
 "The copy on your Frame differs from what FramePort would install now (the recipe or your game files changed). Update to install the new build; saves are kept.": "",
@@ -1200,6 +1324,7 @@
  ""
 ],
 "The Frame can't show curved panels; this shows them as gently bent strips.": "",
+ "The Frame didn't save a screenshot ({why}). Try again.": "",
 "The Frame goes to sleep in a few seconds. Wake it with its power button.": "",
 "The Frame goes to sleep now.": "",
 "The Frame is charging: continuing the installs.": "",
@@ -1216,23 +1341,31 @@
 "The Frame's battery is at {pct}%: installs paused so it doesn't switch off mid-upload. Plug it in; the queue continues by itself.": "",
 "The Frame's CPU is arm64. Programs built for x86_64 PCs run through FEX, Valve's x86 translator, with the x86 libraries SteamOS ships for it (glibc, Mesa) - the way Steam on the Frame runs x86 Linux games. That works for many programs but is slower: use an arm64 build when there is one.": "",
 "The Frame's desktop password, only needed the first time so FramePort can add its own key. After that it connects with the key.": "",
+ "The Frame's own video encoder does the work where it can.": "",
 "The Frame's Steam couldn't start {title} (Steam error {code}). Please send a problem report so we can see why.": "",
 "The Frame's Steam didn't accept {title}'s library entry, so FramePort added it as \"Devkit Game: …\" instead. Starting it now — put the headset on.": "",
 "The Frame's Steam library still shows the old artwork.": "",
 "the game didn't pass its checks (see the list above)": "",
 "The game is closed the way Steam's Exit game does it; if it doesn't stop, FramePort stops it. Progress that the game hasn't saved is lost.": "",
+ "The game's audio streams along with the picture.": "",
+ "The headset is asleep: put it on, then take the screenshot.": "",
+ "The headset's view and sound open in an mpv window. Open it in your browser any time.": "",
 "The headset's view and sound open in your web browser. Stop the stream when you're done.": "",
+ "The headset's view and sound play right here. Open it in your browser any time.": "",
+ "The headset's view is open in an mpv window. You can also watch it in your browser.": "",
+ "The headset's view is open in your browser. Closed the tab? Open it again.": "",
+ "The headset's view on this PC, for watching along or recording.": "",
 "the installed game (APK and its data)": "",
 "The launch settings changed since it was installed: update the Steam shortcut": "",
- "The live view can start once FramePort is connected to the Frame.": "",
+ "The live view couldn't play {first}, so it opened {where}.": "",
 "the log of the last start": "",
 "The monitor isn't connected.": "",
- "The monitor shows your Frame's games, load, temperatures and battery live once FramePort is connected to it.": "",
 "the other app": "",
 "The PC VR counterpart of OVRPort's 'Patch Oculus detection for Unreal'. Unreal's Oculus plugin only starts when the Oculus service announces a headset (the Windows event 'OculusHMDConnected'); without it the game runs as a flat window. On the Frame the launcher runs the game through FramePort's small helper (fp_oculushmd.exe) that provides that event while the game runs, instead of relying only on Revive's hook of the check. Ignored on this PC (the Oculus app or Revive handle it there).": "",
- "The picture opens in your default web browser, where it plays smoothly and can go full screen. It shows the headset's view with its sound (click Sound on in the player) whatever is running: Steam's menus, SteamVR or a game; while the headset sleeps the picture is black and updates about once a second. The Frame's hardware video encoder does the work (if it isn't available, the processor does, which costs a game more): stop the stream when you're done.": "",
+ "The picture plays right in this window where FramePort can (Windows and macOS), else in an mpv window if mpv is installed, else in your web browser — Play in picks one, and Open in browser always works too (full screen, Sound on in the player). It shows the headset's view with its sound whatever is running: Steam's menus, SteamVR or a game; while the headset sleeps the picture is black and updates about once a second. The Frame's hardware video encoder does the work (if it isn't available, the processor does, which costs a game more): stop the stream when you're done.": "",
 "the previous version, kept for one rollback": "",
 "The repack's own Revive · runs the game directly": "",
+ "The running game's frames per second, as it plays.": "",
 "The small helper program FramePort runs on the Frame (installs, launch tests, Steam entries). It comes with this app and is replaced on the Frame automatically whenever it differs.": "",
 "The time the Frame spends collecting these numbers": "",
 "The upload to the Frame was damaged on the way. Try again (a cable or the Frame's hotspot is more reliable than a busy Wi-Fi).": "",
@@ -1241,6 +1374,7 @@
 "Theme file to install": "",
 "These games can't run on the Steam Frame": "",
 "These games check their Oculus license": "",
+ "These games keep their content in a data file (.obb), and none was found next to their APK. Without it they hang at start. Put the .obb files in a folder named like the game's package (or obb/) next to the APK and add the folder again. Tick any you still want to install.": "",
 "These installs need about {need} on the Frame, and it has {free} free. Remove games you don't play (or use Free up space on the Steam Frame page), or install fewer at once.": "",
 "These links open FramePort.": "",
 "These links will open FramePort instead of {app}. You can switch back in {app}, or by turning this setting off.": "",
@@ -1249,11 +1383,13 @@
 "They use the Oculus Platform SDK, which comes with the Meta Horizon (Oculus) app — it isn't installed on this PC, so they may quit right after starting. FramePort doesn't change how a game checks its license. Untick the ones you'd rather skip.": "",
 "They use the Oculus Platform SDK, which comes with the Meta Horizon (Oculus) app. It doesn't exist on the Steam Frame, so there they crash right at startup (seen with Robo Recall, Lies Beneath and Lone Echo) — play them on this PC. Tick any you still want to try on the Frame.": "",
 "They're Oculus games that need Revive to reach VR, and Revive can't run on the Frame. Play them on this PC instead (Install on this PC — SteamVR + Revive). Tick any you still want to put on the Frame to experiment (they'll likely run flat or crash).": "",
+ "This app looks like a website in an Android wrapper: it opens the site in Meta's browser, which the Frame doesn't have. If nothing opens, use the website in a browser instead.": "",
 "This deletes the {what} on the Frame. It can't be undone.": "",
 "This folder is empty. Upload files with the buttons above.": "",
 "This Frame isn't set up for FramePort yet. Run the first-time setup: Steam Frame → Show setup command.": "",
 "This game can't run on the Steam Frame.": "",
 "This game is marked \"Can't run\" on the Steam Frame:": "",
+ "This game's data file (.obb) wasn't found next to the APK. Put the .obb files in a folder named {package} (or obb/) next to the APK and add the folder again; without it the game hangs at start.": "",
 "This game's folder has several programs and FramePort isn't sure which one starts the game. Open the game and use … → Change program… to pick it.": "",
 "this PC": "",
 "This PC": "",
@@ -1294,11 +1430,11 @@
 "Turns the controllers' pointing ray left (+) or right (−).": "",
 "Turns the pointer left or right.": "",
 "Type": "",
+ "Type in VR with your PC's keyboard": "",
 "Type it": "",
 "Type on Frame": "",
 "Type to search games and tags": "",
 "Typed it, except characters the Frame's US keyboard layout doesn't have: {chars}": "",
- "Typing on the Frame works once FramePort is connected to it.": "",
 "ufw is active. Allow the setup port with: sudo ufw allow {port}/tcp (and afterwards: sudo ufw delete allow {port}/tcp)": "",
 "Uninstall": "",
 "Uninstall FramePort": "",
@@ -1312,7 +1448,11 @@
 "Uninstall. ": "",
 "Uninstalled {title}": "",
 "Uninstalled {title} and deleted its files on this PC ({size})": "",
- "Unity's built-in Oculus support (Unity 2017–2019) only starts VR when Android has Meta's com.oculus.systemactivities package; without it the game runs as a 2D app (the Android home screen or a black window, e.g. Accounting+, BattleSisters). Points that package name in libunity.so at \"android\", which always exists. Games on Unity's built-in VR (2017–2018, and 2019 without the Oculus XR Plugin) also get the frame wait their legacy frame loop never makes (libfp_ovrp.so calls ovrp_WaitToBeginFrame before ovrp_Update2; without it no frame starts, the dashboard freezes or the GPU hangs). The shim also counts a newly pressed trigger or A/B/X/Y as a mouse click (Input.GetMouseButtonDown), which Go-era screens wait for (e.g. Accounting+'s motion warning) and which Lepton never delivers.": "",
+ "Unity frame loop: keep display-time poses": "",
+ "Unity frame loop: wait for skipped frames": "",
+ "Unity's built-in Oculus frame loop (frame.unity_oculus_check): before each frame wait, wait up to 50 ms for the last waited frame to begin and skip the wait if it doesn't. Fixes a freeze at the first scene switch (e.g. Sniper Elite VR); in other games it can make loading screens stutter.": "",
+ "Unity's built-in Oculus frame loop (frame.unity_oculus_check): don't pass Unity's physics-step pose update on, so the hands use the frame's display-time poses. Fixes hands trailing the controllers in some games (e.g. Sniper Elite VR); in others it makes the hands lag (e.g. BattleSisters).": "",
+ "Unity's built-in Oculus support (Unity 2017–2019) only starts VR when Android has Meta's com.oculus.systemactivities package; without it the game runs as a 2D app (the Android home screen or a black window, e.g. Accounting+, BattleSisters). Points that package name in libunity.so at \"android\", which always exists. Games on Unity's built-in VR (2017–2018, and 2019 without the Oculus XR Plugin) also get the frame wait their legacy frame loop never makes (libfp_ovrp.so calls ovrp_WaitToBeginFrame before ovrp_Update2; without it no frame starts, the dashboard freezes or the GPU hangs). Per game, the settings ovrp_begin_gate (a freeze at the first scene switch) and ovrp_hold_physics (hands trailing the controllers) switch on two more frame-loop fixes (e.g. Sniper Elite VR). The shim also counts a newly pressed trigger or A/B/X/Y as a mouse click (Input.GetMouseButtonDown), which Go-era screens wait for (e.g. Accounting+'s motion warning) and which Lepton never delivers.": "",
 "Unity's Oculus XR Plugin asks OVRPlugin whether the headset is worn; on the Frame the answer turns to \"not worn\" a few seconds after start. Games that only move the player while the headset is worn then show a frozen body with no head tracking and no controls (e.g. BONELAB). Reports the headset as worn; taking it off still pauses the game through the session's focus.": "",
 "Unity's TMP_InputField / InputField wait for Android's on-screen keyboard and close themselves a frame later when there is none (Lepton has no on-screen keyboard; Meta's system keyboard does this on a Quest), so a selected text field only flashes a caret. Rewrites TouchScreenKeyboardShouldBeUsed -> false and isKeyboardUsingEvents (TMP) / InPlaceEditing (uGUI) -> true in libil2cpp.so, found per game with Cpp2IL (downloaded on first use), so fields stay selected and take key presses: Steam's keyboard (with \"Show the app window\") or Type on Frame from the PC.": "",
 "Unity: disable MSAA": "",
@@ -1323,8 +1463,11 @@
 "Unity: start VR without Meta's system apps": "",
 "unknown": "",
 "Unknown date": "",
+ "Unpaired pointer-authentication checks": "",
 "Unreal builds of Meta XR Audio abort ('ClassNotFoundException com.oculus.os.AnalyticsEvent') on non-Quest devices. Patches that one JNI FindClass call so the library continues (e.g. NOPE Challenge).": "",
 "Unreal games start CrashReportClient when they crash, which leaves a crash dialog instead of simply closing. This passes -nocrashreports to the game and, on the Frame, renames the game's copy of CrashReportClient.exe so it can't start (your game files on this PC aren't changed).": "",
+ "Unreal's Oculus module looks up every OVRPlugin function it was built against and starts no VR when one is missing; OVRPort's OpenXR OVRPlugin lacks some old ones (e.g. ovrp_GetPTWNear, which Unreal 4.25 builds like Star Wars Pinball VR look up). The game then never starts an OpenXR session and crashes a few seconds in. Adds a generated library to libOVRPlugin.so with a stand-in for each missing function that reports failure (ovrpFailure), so Unreal's Oculus support starts. The functions OVRPort has are untouched.": "",
+ "Unreal: stand-ins for OVRPlugin functions OVRPort lacks": "",
 "Untested": "",
 "Update all": "",
 "Update all ({updates})": "",
@@ -1348,6 +1491,8 @@
 "Upload": "",
 "Upload files…": "",
 "Upload folder…": "",
+ "Upload from this PC, download, rename and tidy up.": "",
+ "Upload movies straight into a player's own folder.": "",
 "Upload to {label}": "",
 "Uploaded {n} file": [
  "",
@@ -1378,6 +1523,7 @@
 "Video panels that an Android media player draws into (XR_KHR_android_surface_swapchain, e.g. I Am Monkey's intro video), which the Frame's runtime refuses, get an Android Surface from FrameBridge: each video frame is copied into an ordinary swapchain the panel shows. Without it these panels are missing and a game waiting for its video stays black. 0 = leave them to the runtime.": "",
 "Video players' virtual theatres and 360° videos would otherwise stay black.": "",
 "Videos": "",
+ "Videos for your players": "",
 "Videos, documents, mods and saves on your Steam Frame": "",
 "View": "",
 "View screenshot": "",
@@ -1403,13 +1549,20 @@
 "Waiting for your Frame… (code {code})": "",
 "waiting {pct}%": "",
 "Watch what the headset shows, in a window on this PC": "",
+ "Web browser": "",
 "Welcome to FramePort": "",
+ "What changed in the {n} versions since yours:": "",
+ "What changed in this version and the ones before it.": "",
 "What FramePort will do": "",
 "What happens? (optional: you can also write it on GitHub)": "",
+ "What the player sees": "",
 "What the whole Frame draws right now (its main power rail), with the share of the CPU and the graphics chip. Higher power means more heat and a shorter battery.": "",
 "What your Frame is doing right now": "",
+ "What's new in FramePort {version}": "",
 "What's new…": "",
+ "What's running, and a way to end what's stuck.": "",
 "Where it's installed": "",
+ "Where new games go on the Frame: its internal storage or another drive, such as a microSD card (in a FramePort folder on it). Games you installed already stay where they are; move one with right-click → Move to…. The launcher and Steam entry always stay on internal storage. Drives formatted as FAT, exFAT or NTFS can't hold games (Android and Proton need Linux file permissions): format the card in SteamOS first.": "",
 "Where the power goes": "",
 "Where this game's recipe came from: catalog (tested on a Frame), heuristics (suggested by FramePort) or user (changed by you).": "",
 "Which program starts {get}?": "",
@@ -1425,6 +1578,7 @@
 "Windows treats this network as public and its firewall blocks the Frame. In Windows' network settings set this network to Private (or allow FramePort on public networks when Windows asks).": "",
 "Windows' firewall for WSL blocks the Frame from reaching FramePort. Open the setup command again and allow the change when Windows asks (admin).": "",
 "Windows' firewall for WSL blocks the Frame. Open the setup command again and allow the change when Windows asks (admin).": "",
+ "With sound": "",
 "Working": "",
 "Working…": "",
 "Works": "",
@@ -1450,10 +1604,13 @@
 "Your changes to its patches and game settings are replaced by the suggested recipe.": "",
 "Your copy is used as it is (only the Frame's copy gets launch patches)": "",
 "Your custom recipe": "",
+ "Your first game is on the Frame. Welcome aboard!": "",
 "your Frame": "",
+ "Your Frame at a glance": "",
 "Your Frame is back: continuing": "",
 "Your Frame isn't set up for FramePort yet. Run the first-time setup once (step 1).": "",
 "Your Frame restarted unexpectedly while {title} was running (or soon after). If that game crashed it, please report it.": "",
+ "Your Frame's files, from this PC": "",
 "Your headset, what it's ready for and what's installed": "",
 "Your own artwork for {title}": "",
 "Your own game files aren't touched.": "",
@@ -1474,6 +1631,7 @@
 "{human} · {files} files": "",
 "{int} h ago": "",
 "{int} min ago": "",
+ "{label} (not inserted)": "",
 "{label} ({host}) isn't reachable. Make sure it's switched on and on the same network.": "",
 "{label} removed for {title}.": "",
 "{label} updated for {title}.": "",
@@ -1513,6 +1671,10 @@
  "",
  ""
 ],
+ "{n} game was analyzed again for new fixes": [
+  "",
+  ""
+ ],
 "{n} install didn't finish: {names}. What was already copied is kept, so resuming continues where it stopped.": [
  "",
  ""
@@ -1549,6 +1711,7 @@
 "{on} on your Frame": "",
 "{rate}/s": "",
 "{remaining} more after this": "",
+ "{size:.1f} GiB free": "",
 "{title} couldn't be added to the Frame's Steam library: {why}": "",
 "{title} ended.": "",
 "{title} failed: {error}": "",
@@ -1556,6 +1719,7 @@
 "{title} is already starting — put the headset on": "",
 "{title} is still running.": "",
 "{title} isn't in the Frame's Steam library yet: adding it (Steam restarts once)": "",
+ "{title} moved to {label}": "",
 "{title} will be in the Frame's Steam library when the game that's running is closed": "",
 "{title} will be in the Frame's Steam library when you're back in Gaming Mode: start it from there": "",
 "{title}: analyzed again": "",
@@ -0,0 +1,63 @@
+"""Detects OVRPort's fix for the haptic-envelope bug, which makes `adapter.haptic_fix` unnecessary.
+
+OVRPort's dispatcher (libopenxr_loader.so) turns XrHapticAmplitudeEnvelopeVibrationFB into 100 Hz samples. Runtimes
+up to 3.4.3-23204ea used the envelope's duration (nanoseconds) as seconds when counting them: one vibration asked for
+gigabytes (Lucky's Tale froze the Frame, BattleSisters was killed for 11 GB). Runtime 3.4.3-aa54c3f converts it first
+(ovrport/app#73): right after the type check for the envelope (XR_TYPE_HAPTIC_AMPLITUDE_ENVELOPE_VIBRATION_FB =
+1000173001) it builds the constant 1e9 (`count * 1e9 / duration` = samples per second), which the buggy code never
+had. Verified in the headset with Lucky's Tale and haptic_fix off (2026-10-07). See patches/upstream.py.
+"""
+from __future__ import annotations
+
+import struct
+
+from ..upstream import UpstreamFix, code_words, constants, find_constant_load, lib_probe, register
+
+DISPATCHER = "libopenxr_loader.so"
+ENVELOPE_TYPE = 1000173001  # XR_TYPE_HAPTIC_AMPLITUDE_ENVELOPE_VIBRATION_FB
+WINDOW = 48  # instructions after the type check that hold the sample count (the fix: 7 after it)
+NS_PER_S = {struct.unpack("<Q", struct.pack("<d", v))[0] for v in (1e9, 1e-9)} | \
+           {struct.unpack("<I", struct.pack("<f", v))[0] for v in (1e9, 1e-9)}
+
+
+def _literals(data: bytes, offsets: list[int], words: list[int]) -> list[int]:
+    """Values loaded PC-relative (LDR literal: GP w/x, SIMD s/d) by the given instructions."""
+    out = []
+    for off, w in zip(offsets, words, strict=True):
+        if w & 0x3B000000 != 0x18000000:  # LDR (literal), GP (V=0) or SIMD (V=1)
+            continue
+        size = {0: 4, 1: 8}.get(w >> 30)  # opc: w / s = 4 bytes, x / d = 8 (q isn't a scalar constant)
+        if size is None:
+            continue
+        imm19 = (w >> 5) & 0x7FFFF
+        target = off + ((imm19 - (1 << 19)) if imm19 & (1 << 18) else imm19) * 4
+        if 0 <= target <= len(data) - size:
+            out.append(int.from_bytes(data[target:target + size], "little"))
+    return out
+
+
+def envelope_duration_fixed(data: bytes) -> bool | None:
+    """True when the dispatcher converts the envelope duration from nanoseconds (OVRPort's fix), False when its
+    envelope code has no such conversion (the bug), None when there's no envelope code to judge."""
+    code = list(code_words(data))
+    offsets, words = [o for o, _ in code], [w for _, w in code]
+    seen = False
+    start = 0
+    while (i := find_constant_load(words[start:], ENVELOPE_TYPE)) is not None:
+        i += start
+        seen = True
+        window = slice(i, i + WINDOW)
+        if NS_PER_S & set(constants(words[window])) or NS_PER_S & set(_literals(data, offsets[window], words[window])):
+            return True
+        start = i + 1
+    return False if seen else None
+
+
+register(UpstreamFix(
+    id="ovrport.haptic_envelope",
+    workaround="adapter.haptic_fix",
+    title="OVRPort converts the vibration envelope's duration from nanoseconds",
+    upstream="ovrport/app#73 (runtime 3.4.3-aa54c3f)",
+    probe=lib_probe(DISPATCHER, envelope_duration_fixed),
+    tracker="#74",
+))
@@ -7,12 +7,16 @@ Walking Dead: Saints & Sinners Ch. 2) dereferences a NULL stream: SIGSEGV in lib
 seconds after the logo. Meta's own library allows that order. The function is rewritten in place (same size) to return
 0 while no stream is open and behave as before otherwise.

-Upstream: Android-XR-Bridge/OVRPort#2, ovrport/app#73; tracked in GitHub #73 (drop this patch once fixed upstream).
+Upstream: Android-XR-Bridge/OVRPort#2, ovrport/app#73; tracked in GitHub #73. OVRPort runtime 3.4.3-aa54c3f checks
+the handle and the stream itself (returns 48000 without one): builds made with it leave this patch out
+(`microphone_checked`, patches/upstream.py).
 """
 from __future__ import annotations

 from ...analysis import elf
 from ..base import ApkContext, Patch, Suggestion, register
+from ..upstream import UpstreamFix, lib_probe
+from ..upstream import register as register_upstream_fix

 LOADER = "libovrplatformloader.so"
 FUNC = "ovr_Microphone_GetOutputBufferMaxSize"
@@ -31,9 +35,8 @@ def _words(data: bytes | bytearray, off: int, n: int) -> list[int]:
    return [int.from_bytes(data[off + 4 * i:off + 4 * i + 4], "little") for i in range(n)]


-def guard_microphone(data: bytes) -> bytes | None:
-    """The loader with a NULL-stream check in ovr_Microphone_GetOutputBufferMaxSize, or None if the function isn't
-    OVRPort's unchecked 7-instruction version (already fixed, Meta's library, another OVRPort build)."""
+def _function_offset(data: bytes, size: int) -> int | None:
+    """File offset of FUNC in the loader (None: not an ELF, no such export, or shorter than `size` bytes)."""
    try:
        dynsym = elf._elf(data).get_section_by_name(".dynsym")
    except Exception:  # noqa: BLE001
@@ -41,9 +44,31 @@ def guard_microphone(data: bytes) -> bytes | None:
    found = dynsym.get_symbol_by_name(FUNC) if dynsym is not None else None
    if not found or not found[0]["st_value"]:
        return None
-    vaddr = found[0]["st_value"]
-    off = elf.vaddr_to_offset(elf.load_segments(data), vaddr)
-    if off is None or off + 28 > len(data):
+    off = elf.vaddr_to_offset(elf.load_segments(data), found[0]["st_value"])
+    return off if off is not None and off + size <= len(data) else None
+
+
+def microphone_checked(data: bytes) -> bool | None:
+    """True when OVRPort's GetOutputBufferMaxSize tests something (a cbz/cbnz) before its first call, as the fixed
+    runtime does; False when it is the unchecked version this patch rewrites; None when it can't tell."""
+    if guard_microphone(data) is not None:
+        return False
+    off = _function_offset(data, 48)
+    if off is None:
+        return None
+    for word in _words(data, off, 12):
+        if word & BL_MASK == BL:
+            return None
+        if word & 0x7E000000 == 0x34000000:  # CBZ / CBNZ (32 or 64 bit)
+            return True
+    return None
+
+
+def guard_microphone(data: bytes) -> bytes | None:
+    """The loader with a NULL-stream check in ovr_Microphone_GetOutputBufferMaxSize, or None if the function isn't
+    OVRPort's unchecked 7-instruction version (already fixed, Meta's library, another OVRPort build)."""
+    off = _function_offset(data, 28)
+    if off is None:
        return None
    w = _words(data, off, 7)
    if w[:3] != [STP, MOV_FP, LDR_STREAM] or w[3] & BL_MASK != BL or w[4:] != [SXTW, LDP, RET]:
@@ -88,3 +113,11 @@ class OvrMicrophone(Patch):


 register(OvrMicrophone)
+register_upstream_fix(UpstreamFix(
+    id="ovrport.microphone_stream",
+    workaround=OvrMicrophone.id,
+    title="OVRPort checks for an unopened microphone stream",
+    upstream="ovrport/app#73 (runtime 3.4.3-aa54c3f)",
+    probe=lib_probe(LOADER, microphone_checked),
+    tracker="#73",
+))
@@ -0,0 +1,99 @@
+"""Unpaired pointer-authentication hints (PAC) in a game's native libraries.
+
+paciasp signs the return address on function entry and autiasp checks it before returning. Both are HINT
+instructions: CPUs without pointer authentication (the Quest's) execute them as NOPs, the Steam Frame's CPU checks
+them and raises SIGILL (ILL_ILLOPN at an autiasp) when a check fails. Some OpenSSL ARMv8 assembly built into game
+engines has an autiasp without the matching paciasp (e.g. Star Wars Pinball VR's libUE4.so: 38 paciasp, 40 autiasp,
+the crash in the Poly1305 NEON code on Unreal's HttpManager thread), so the game dies as soon as it opens a TLS
+connection. Only libraries whose PAC hints come from hand-written assembly are changed: compiler-protected code
+signs almost every function and has several autiasp per paciasp where a function has several returns (OVRPort's
+libopenxr_loader_generic.so: 1084 paciasp, 1114 autiasp, 7092 ret; stripping it hung OVRPlugin's start-up), while an
+engine without branch protection has a few dozen hints among hundreds of thousands of returns (libUE4.so: 38 among
+342581). So a library is changed when its counts differ and its paciasp are under 0.2 % of its ret instructions; then
+every paciasp/autiasp becomes a NOP (the same 4 bytes in place) and the code behaves as on the Quest. The combined
+forms (retaa/retab, pacibsp/autibsp) aren't touched; a library using them is left alone."""
+from __future__ import annotations
+
+from ...analysis import elf
+from ..base import ApkContext, Patch, register
+
+PACIASP = (0xD503233F).to_bytes(4, "little")
+AUTIASP = (0xD50323BF).to_bytes(4, "little")
+NOP = (0xD503201F).to_bytes(4, "little")
+RET = (0xD65F03C0).to_bytes(4, "little")
+MAX_ASM_SHARE = 0.002  # paciasp per ret: above this the library is compiler-protected (left alone)
+COMBINED = tuple(w.to_bytes(4, "little") for w in (0xD65F0BFF, 0xD65F0FFF, 0xD503237F, 0xD50323FF))  # retaa/b, *ibsp
+
+
+def _exec_ranges(data: bytes) -> list[tuple[int, int]]:
+    """File ranges of the executable PT_LOAD segments."""
+    import io
+
+    from elftools.elf.elffile import ELFFile
+
+    e = ELFFile(io.BytesIO(data))
+    return [(s["p_offset"], s["p_offset"] + s["p_filesz"]) for s in e.iter_segments()
+            if s["p_type"] == "PT_LOAD" and s["p_flags"] & 1]
+
+
+def _find(data: bytes, word: bytes, ranges) -> list[int]:
+    out = []
+    for lo, hi in ranges:
+        i = data.find(word, lo, hi)
+        while i >= 0:
+            if i % 4 == 0:
+                out.append(i)
+            i = data.find(word, i + 1, hi)
+    return out
+
+
+def unpaired(data: bytes) -> tuple[list[int], list[int]] | None:
+    """(paciasp offsets, autiasp offsets) when a library's counts differ, else None."""
+    if not elf.is_elf(data):
+        return None
+    ranges = _exec_ranges(data)
+    pac, aut = _find(data, PACIASP, ranges), _find(data, AUTIASP, ranges)
+    if len(pac) == len(aut) or any(_find(data, w, ranges) for w in COMBINED):
+        return None
+    if len(pac) > MAX_ASM_SHARE * max(len(_find(data, RET, ranges)), 1):
+        return None  # compiler-protected (several returns per signed function), not hand-written assembly
+    return pac, aut
+
+
+class PacHints(Patch):
+    id = "frame.pac_hints"
+    title = "Unpaired pointer-authentication checks"
+    description = ("Some engines contain assembly (e.g. OpenSSL's) that checks a return-address signature it never "
+                   "made. The Quest's CPU ignores those checks, the Steam Frame's enforces them: the game crashes with "
+                   "SIGILL as soon as it uses that code, e.g. on its first network connection (Star Wars Pinball "
+                   "VR). In a library with unpaired checks, the signing and checking instructions become no-ops.")
+    order = 47
+    revision = 1
+
+    def applies(self, a):
+        return "arm64-v8a" in a.abis
+
+    def detect(self, a):
+        return None  # reading every engine library at analysis time is too slow; triage (pac-unpaired) suggests it
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a":
+            return False
+        changed = False
+        for lib in ws.libs():
+            data = ws.read_lib(lib)
+            found = unpaired(data)
+            if not found:
+                continue
+            pac, aut = found
+            out = bytearray(data)
+            for off in pac + aut:
+                out[off:off + 4] = NOP
+            ws.put(ws.lib(lib), bytes(out))
+            ctx.notes.append(f"{lib}: {len(pac)} paciasp / {len(aut)} autiasp turned into NOPs (unpaired)")
+            changed = True
+        return changed
+
+
+register(PacHints)
@@ -0,0 +1,132 @@
+"""BONELAB 1.2974 (and other Stress Level Zero builds) ship libSLZQuestNative.so, a Unity native plugin that hooks
+Unity's Vulkan start-up (IUnityGraphicsVulkanV2 interception: its vkCreateInstance/vkCreateDevice wrappers raise the
+API version, enable device features and check its pipeline cache) and replaces Unity's vkCreateSampler (anisotropy
+<= 4, LOD bias -0.25). On the Frame its vkCreateInstance wrapper calls through an invalid pointer right after
+OVRPlugin's pre-init OpenXR instance is destroyed: a jump into an unloaded library, to address 0, or a hang, depending
+on the run. The plugin's two registrations with Unity are turned into no-ops (in place, 4 bytes each), so Unity runs
+Vulkan itself; the plugin still loads. Its sampler hook must go too: without the device hook it never learns the real
+vkCreateSampler."""
+from __future__ import annotations
+
+import struct
+
+from ...analysis import elf
+from ..base import ApkContext, Patch, Suggestion, register
+
+LIB = "libSLZQuestNative.so"
+ON_LOAD = "RenderAPI_Vulkan_OnPluginLoad"  # registers the Vulkan-init interception
+GFX_INIT = "_ZN8PluginVk12GfxEventInitEv"  # PluginVk::GfxEventInit: InterceptVulkanAPI("vkCreateSampler", hook)
+SAMPLER = b"vkCreateSampler\0"
+NOP = 0xD503201F
+MOV_X1_XZR, MOV_W2_WZR = 0xAA1F03E1, 0x2A1F03E2  # AddInterceptInitialization(func, userdata = NULL, flags = 0)
+
+
+def _is_blr(insn: int) -> bool:
+    return insn & 0xFFFFFC1F == 0xD63F0000
+
+
+def _x0_address(data: bytes, segs, at: int, back: int = 8) -> int | None:
+    """The address `adrp xN, page` + `add x0, xN, #imm` puts in x0 within `back` instructions before `at`."""
+    for i in range(1, back):
+        add_va = at - 4 * i
+        add_off = elf.vaddr_to_offset(segs, add_va)
+        if add_off is None:
+            return None
+        add = struct.unpack_from("<I", data, add_off)[0]
+        if add & 0xFFC0001F != 0x91000000:  # add x0, xN, #imm12 (no shift)
+            continue
+        rn, imm12 = (add >> 5) & 0x1F, (add >> 10) & 0xFFF
+        for j in range(i + 1, back + 4):
+            adrp_off = elf.vaddr_to_offset(segs, at - 4 * j)
+            if adrp_off is None:
+                return None
+            adrp = struct.unpack_from("<I", data, adrp_off)[0]
+            if adrp & 0x9F000000 == 0x90000000 and adrp & 0x1F == rn:
+                imm = ((adrp >> 5) & 0x7FFFF) << 2 | (adrp >> 29) & 3
+                if imm & (1 << 20):
+                    imm -= 1 << 21
+                return ((at - 4 * j) & ~0xFFF) + (imm << 12) + imm12
+        return None
+    return None
+
+
+def _function(data: bytes, name: str) -> tuple[int, int] | None:
+    sec = elf._elf(data).get_section_by_name(".dynsym")
+    for sym in (sec.get_symbol_by_name(name) or []) if sec else []:
+        if sym["st_value"] and sym["st_size"]:
+            return sym["st_value"], sym["st_size"]
+    return None
+
+
+def find_registrations(data: bytes) -> list[int]:
+    """File offsets of the plugin's two `blr` registrations (interception, vkCreateSampler), [] when not this plugin."""
+    segs = elf.load_segments(data)
+    sampler = data.find(b"\0" + SAMPLER) + 1
+    on_load, gfx_init = _function(data, ON_LOAD), _function(data, GFX_INIT)
+    if not on_load or not gfx_init or sampler <= 0:
+        return []
+    out = []
+    for (start, size), wanted in ((on_load, "intercept"), (gfx_init, "sampler")):
+        for va in range(start, start + size, 4):
+            off = elf.vaddr_to_offset(segs, va)
+            if off is None or not _is_blr(struct.unpack_from("<I", data, off)[0]):
+                continue
+            prev = [struct.unpack_from("<I", data, o)[0] for k in range(1, 5)
+                    if va - 4 * k >= start and (o := elf.vaddr_to_offset(segs, va - 4 * k)) is not None]
+            if wanted == "intercept" and MOV_X1_XZR in prev and MOV_W2_WZR in prev:
+                out.append(off)
+                break
+            # the string lives in the first (read-only) segment, where file offset == address
+            if wanted == "sampler" and _x0_address(data, segs, va) == sampler:
+                out.append(off)
+                break
+    return out if len(out) == 2 else []
+
+
+class SlzVulkanHooks(Patch):
+    id = "frame.slz_vulkan_hooks"
+    title = "Stress Level Zero: let Unity start Vulkan itself"
+    description = ("Stress Level Zero's graphics plugin (libSLZQuestNative.so, e.g. BONELAB 1.2974) hooks Unity's "
+                   "Vulkan start-up and its texture samplers. On the Frame the hook calls an invalid function while "
+                   "Vulkan starts, and the game crashes or hangs before the first frame. The plugin's two hooks are "
+                   "switched off, so Unity starts Vulkan itself. Its pipeline cache isn't used: the first start "
+                   "spends about half a minute prewarming shaders.")
+    order = 47
+    revision = 1
+
+    def applies(self, a):
+        return "arm64-v8a" in a.abis and LIB in a.libs
+
+    def detect(self, a):
+        if self.applies(a):
+            return Suggestion(True, "Stress Level Zero's graphics plugin crashes Unity's Vulkan start-up on the Frame "
+                                    "(e.g. BONELAB 1.2974).")
+        return None
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        name = ws.lib(LIB)
+        if ws.abi != "arm64-v8a" or not ws.has(name):
+            return False
+        data = ws.read(name)
+        sites = find_registrations(data)
+        if not sites:
+            return False
+        buf = bytearray(data)
+        for off in sites:
+            struct.pack_into("<I", buf, off, NOP)
+        ws.put(name, bytes(buf))
+        ctx.notes.append(f"{LIB}: Vulkan interception and vkCreateSampler hook switched off "
+                         f"({', '.join(hex(o) for o in sites)})")
+        return True
+
+    def validate(self, ctx: ApkContext):
+        ws = ctx.ws
+        name = ws.lib(LIB)
+        if not ws.has(name):
+            return []
+        left = find_registrations(ws.read(name))
+        return [("SLZ Vulkan hooks off", not left, "" if not left else "still registered")]
+
+
+register(SlzVulkanHooks)
@@ -16,6 +16,10 @@ ALWAYS_THERE = "android"
 # Unity's legacy frame loop never calls ovrp_WaitToBeginFrame: its ovrp_Update2 lookup goes to native/ovrpshim
 SHIM = "libfp_ovrp.so"
 UPDATE, SHIM_UPDATE = "ovrp_Update2", "fpov_Update2"
+# the shim follows Unity's frame begins/ends so its frame wait never blocks for a frame Unity didn't begin (Sniper Elite
+# VR deadlocked at a scene switch: xrWaitFrame waits for the previous frame's xrBeginFrame)
+BEGIN, SHIM_BEGIN = "ovrp_BeginFrame", "fpov_BeginFrame"
+END, SHIM_END = "ovrp_EndFrame", "fpov_EndFrame"
 # Unity creates its XR controller devices for the hand nodes OVRPlugin reports present (logged/fixed by the shim)
 NODE, SHIM_NODE = "ovrp_GetNodePresent", "fpov_GetNodePresent"
 # input diagnostics (off): the C# P/Invoke names in libil2cpp.so pointed at the shim's wrappers, which log what they
@@ -76,13 +80,19 @@ class UnityOculusCheck(Patch):
                   "libunity.so at \"android\", which always exists. Games on Unity's built-in VR (2017–2018, and 2019 "
                   "without the Oculus XR Plugin) also get the frame wait their legacy frame loop never makes "
                   "(libfp_ovrp.so calls ovrp_WaitToBeginFrame before ovrp_Update2; without it no frame starts, the "
-                   "dashboard freezes or the GPU hangs). The shim also counts a newly pressed trigger or A/B/X/Y as a "
-                   "mouse click (Input.GetMouseButtonDown), which Go-era screens wait for (e.g. Accounting+'s motion "
+                   "dashboard freezes or the GPU hangs). Per game, the settings ovrp_begin_gate (a freeze at the first "
+                   "scene switch) and ovrp_hold_physics (hands trailing the controllers) switch on two more frame-loop "
+                   "fixes (e.g. Sniper Elite VR). The shim also "
+                   "counts a newly pressed trigger or A/B/X/Y as a mouse click (Input.GetMouseButtonDown), which "
+                   "Go-era screens wait for (e.g. Accounting+'s motion "
                   "warning) and which Lepton never delivers.")
    order = 45
    # 2: frame wait also for Unity 2019 without the Oculus XR Plugin; 3: controller presses as mouse clicks
    # (ovrpshim); 4: Unity 2019's Oculus device-model checks (Touch controllers on Lepton)
-    revision = 4
+    # 5: frame begins gate the frame wait (no deadlock when Unity skips a frame); physics-step pose
+    # updates kept from OVRPlugin (they located poses in the past: hands lagged); both only with the per-game settings
+    # ovrp_begin_gate / ovrp_hold_physics (BattleSisters' hands lagged with them)
+    revision = 5

    @staticmethod
    def _major(a) -> int:
@@ -117,6 +127,11 @@ class UnityOculusCheck(Patch):
            return False
        data, loops = elf.replace_rodata_string(data, UPDATE, SHIM_UPDATE) if self.legacy_loop(ctx.analysis) \
            else (data, 0)
+        if loops:
+            data, begins = elf.replace_rodata_string(data, BEGIN, SHIM_BEGIN)
+            if begins:  # the end goes with it: a begin the shim gave the waited frame's index ends with that index
+                data, _ = elf.replace_rodata_string(data, END, SHIM_END)
+                ctx.notes.append(f"libunity.so: {BEGIN}/{END} -> {SHIM_BEGIN}/{SHIM_END}")
        if loops and self._major(ctx.analysis) >= 2019:  # Accounting+ (2017) reads OVRInput: works without
            data, models = oculus_model_checks(data)
            if models:
@@ -0,0 +1,120 @@
+"""OVRPlugin functions Unreal looks up that OVRPort's OVRPlugin lacks.
+
+Unreal's Oculus module (FOculusHMDModule::InitializeOculusPluginWrapper) looks up every `ovrp_*` function of the
+OVRPlugin version it was built against with dlsym on libOVRPlugin.so's handle and ANDs the results: one missing name
+and the wrapper fails, OculusHMD never pre-initialises, no OpenXR session starts and the game later crashes without an
+HMD (e.g. Star Wars Pinball VR, UE 4.25 built against OVRPlugin 1.44: OVRPort's OpenXR OVRPlugin has no
+ovrp_GetPTWNear). OVRPort replaces the plugin, so the names come from the engine library and are compared with the
+plugin the build ships. Each missing one gets a stand-in that returns ovrpFailure (-1000), so callers take their "not
+supported" path and never read untouched output arguments. The stand-ins live in a generated library that
+libOVRPlugin.so loads (DT_NEEDED): dlsym on a library's handle also searches its dependencies, and the plugin's own
+functions are found first, so a later OVRPort that adds a function wins over its stand-in. The engine library stays
+byte-identical."""
+from __future__ import annotations
+
+from ...analysis import elf
+from ...analysis.detect import ovrp_lookups
+from ...analysis.stubgen import build_stub_library
+from ..base import ApkContext, Patch, Suggestion, register
+
+PLUGIN = "libOVRPlugin.so"
+STUBS = "libfp_ovrpstubs.so"
+ENGINE_LIBS = ("libUE4.so", "libUnreal.so")
+OVRP_FAILURE = -1000  # ovrpResult ovrpFailure
+# fallback before OVRPort downloaded a runtime (nothing to compare with yet): names its OpenXR OVRPlugin (3.4.3) is
+# known to lack that Unreal builds look up. The build itself always compares with the plugin it ships.
+KNOWN_MISSING = ("ovrp_GetPTWNear",)
+
+
+def _shipped_exports(abi: str) -> set[str] | None:
+    """Exports of the newest OVRPort runtime's libOVRPlugin.so, cached per file version (None: none downloaded)."""
+    from ...tools import overport
+
+    path = overport.runtime_lib(PLUGIN, abi)
+    if not path:
+        return None
+    st = path.stat()
+    key = (str(path), st.st_mtime_ns, st.st_size)
+    if _cache.get("key") != key:
+        _cache.update(key=key, exports=elf.dyn_symbols(path.read_bytes(), True))
+    return _cache["exports"]
+
+
+_cache: dict = {}
+
+
+def missing_lookups(lookups, plugin_exports) -> list[str]:
+    return sorted(set(lookups) - set(plugin_exports))
+
+
+class UnrealOvrpEntrypoints(Patch):
+    id = "frame.unreal_ovrp_entrypoints"
+    title = "Unreal: stand-ins for OVRPlugin functions OVRPort lacks"
+    description = ("Unreal's Oculus module looks up every OVRPlugin function it was built against and starts no VR "
+                   "when one is missing; OVRPort's OpenXR OVRPlugin lacks some old ones (e.g. ovrp_GetPTWNear, which "
+                   "Unreal 4.25 builds like Star Wars Pinball VR look up). The game then never starts an OpenXR "
+                   "session and crashes a few seconds in. Adds a generated library to libOVRPlugin.so with a stand-in "
+                   "for each missing function that reports failure (ovrpFailure), so Unreal's Oculus support starts. "
+                   "The functions OVRPort has are untouched.")
+    order = 46
+
+    def applies(self, a):
+        return a.engine == "Unreal" and PLUGIN in a.libs and "arm64-v8a" in a.abis
+
+    def detect(self, a):
+        lookups = (a.extra or {}).get("unreal_ovrp_lookups") or []
+        if not self.applies(a) or not lookups:
+            return None
+        exports = _shipped_exports("arm64-v8a")
+        if exports is None:
+            missing = sorted(set(lookups) & set(KNOWN_MISSING))
+        else:
+            missing = missing_lookups(lookups, exports)
+        if not missing:
+            return None
+        return Suggestion(True, f"Unreal looks up OVRPlugin function(s) OVRPort's OVRPlugin lacks: "
+                                f"{', '.join(missing[:6])}{' …' if len(missing) > 6 else ''}. Without them Unreal "
+                                "starts no VR.")
+
+    def _missing(self, ctx: ApkContext) -> list[str]:
+        ws = ctx.ws
+        lookups = (ctx.analysis.extra or {}).get("unreal_ovrp_lookups")
+        if not lookups:  # analysed by an older FramePort: read the engine library itself
+            engine = next((ws.lib(n) for n in ENGINE_LIBS if ws.has(ws.lib(n))), None)
+            lookups = ovrp_lookups(ws.read(engine)) if engine else []
+        return missing_lookups(lookups, elf.dyn_symbols(ws.read_lib(PLUGIN), True))
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a" or not ws.has(ws.lib(PLUGIN)):
+            return False
+        missing = self._missing(ctx)
+        if not missing:
+            return False
+        plugin = ws.read_lib(PLUGIN)
+        stubs = build_stub_library(missing, STUBS, ws.abi, result=OVRP_FAILURE)
+        changed = False
+        if STUBS not in elf.needed(plugin):
+            ws.put(ws.lib(PLUGIN), elf.add_needed(plugin, STUBS))
+            changed = True
+        if not ws.has(ws.lib(STUBS)) or ws.read_lib(STUBS) != stubs:
+            ws.put(ws.lib(STUBS), stubs)
+            changed = True
+        if changed:
+            ctx.notes.append(f"{len(missing)} OVRPlugin stand-in(s) returning ovrpFailure: {', '.join(missing)}")
+        return changed
+
+    def validate(self, ctx):
+        ws = ctx.ws
+        if not ws.has(ws.lib(PLUGIN)):
+            return []
+        plugin = ws.read_lib(PLUGIN)
+        exports = set(elf.dyn_symbols(plugin, True))
+        if STUBS in elf.needed(plugin) and ws.has(ws.lib(STUBS)):
+            exports |= elf.dyn_symbols(ws.read_lib(STUBS), True)
+        lookups = (ctx.analysis.extra or {}).get("unreal_ovrp_lookups") or []
+        unresolved = missing_lookups(lookups, exports)
+        return [("OVRPlugin functions Unreal looks up resolvable", not unresolved, ", ".join(unresolved[:5]))]
+
+
+register(UnrealOvrpEntrypoints)
@@ -108,6 +108,31 @@ class UnityGlShim(GlShim):
        return a.engine == "Unity" and "GLES" in a.graphics and "arm64-v8a" in a.abis


+class UnrealGlShim(GlShim):
+    id = "frame.unreal_gl_shim"
+    title = "GL shim for Unreal (no multisampled render-to-texture)"
+    description = (
+        "Loads the GL shim into an Unreal GLES game and hides GL_EXT_multisampled_render_to_texture. Unreal's mobile "
+        "MSAA renders through multisampled render-to-texture, and the Frame's GL driver (Mesa/Zink) can crash on it: "
+        "SIGSEGV with fault address 0x10000 in libgallium_dri.so on the RHIThread a few seconds after start (Zink "
+        "looks up a render-pass cache slot past its end, e.g. Star Wars Pinball VR). Hidden, Unreal renders without "
+        "that path. Unreal's multiview stays on: Unreal only uses it when GL_OVR_multiview_multisampled_render_to_"
+        "texture is listed too, so for Unreal the shim keeps that one visible and draws its multiview MSAA "
+        "attachments single-sampled (glFramebufferTextureMultiviewOVR).")
+    order = 62
+    requires = ()
+    experimental = False
+
+    def detect(self, a):
+        # not suggested from the APK alone: most Unreal GLES games run without it; the launch test's triage
+        # (unreal-msrtt-crash) and catalog recipes turn it on
+        return None
+
+    def applies(self, a):
+        return a.engine == "Unreal" and "GLES" in a.graphics and "arm64-v8a" in a.abis
+
+
 register(VrApiBridge)
 register(GlShim)
 register(UnityGlShim)
+register(UnrealGlShim)
@@ -169,6 +169,14 @@ SETTINGS = [
     "fragment-density-map foveation when the driver offers it and expects the density map from the headset, which the "
     "Frame doesn't provide: image views and barriers for a missing image, then a crash in the Frame's Vulkan driver "
     "(e.g. Metro Awakening). Valve's own foveation layer isn't affected."),
+    ("ovrp_begin_gate", "int", 0, "Unity frame loop: wait for skipped frames",
+     "Unity's built-in Oculus frame loop (frame.unity_oculus_check): before each frame wait, wait up to 50 ms for the "
+     "last waited frame to begin and skip the wait if it doesn't. Fixes a freeze at the first scene switch (e.g. "
+     "Sniper Elite VR); in other games it can make loading screens stutter."),
+    ("ovrp_hold_physics", "int", 0, "Unity frame loop: keep display-time poses",
+     "Unity's built-in Oculus frame loop (frame.unity_oculus_check): don't pass Unity's physics-step pose update on, "
+     "so the hands use the frame's display-time poses. Fixes hands trailing the controllers in some games (e.g. Sniper "
+     "Elite VR); in others it makes the hands lag (e.g. BattleSisters)."),
    ("gl_hide_multiview", "int", 1, "GL shim: hide multiview",
     "GL shim only: hide GL_OVR_multiview so all passes use single-view shaders. For GLES games whose multiview "
     "shaders fail on single-view render targets (e.g. Path of the Warrior)."),
@@ -176,7 +184,8 @@ SETTINGS = [


 # settings that need a new build, not only new settings files: the Vulkan shim learned vk_shader_fix in 0.6.4 and
-# vk_query_slots and vk_spec_fixes in 0.10.0
+# vk_query_slots and vk_spec_fixes in 0.10.0. haptic_fix stays at 2 although the shim also converts PCM vibrations
+# since 0.12.1: no game is known to need that, and a bump would mark every OVRPlugin game's build outdated
 REVISIONS = {"vk_shader_fix": 2, "vk_query_slots": 3, "vk_spec_fixes": 2, "haptic_fix": 2, "pose_consistency": 2}

 # How the "Game settings" dialog shows each setting to non-technical users: group, level (common settings are always
@@ -281,7 +290,8 @@ UI: dict[str, dict] = {
    **{key: dict(group="troubleshooting", level="advanced", control=("switch",)) for key in (
        "foveation_fix", "hide_space_warp", "swapchain_fix", "layer_fix", "gl_hide_multiview", "mutable_fix",
        "flip_quads", "swap_eyes", "vk_validation", "rect_clamp", "gl_hide_msrtt", "strip_color_bias", "snapshot",
-        "strip_depth", "respace_kick", "layer_debug", "eye_debug", "input_diag", "release_wait", "vk_hide_fdm")},
+        "strip_depth", "respace_kick", "layer_debug", "eye_debug", "input_diag", "release_wait", "vk_hide_fdm",
+        "ovrp_begin_gate", "ovrp_hold_physics")},
 }


@@ -340,6 +350,8 @@ class AdapterSetting(Patch):
            "swapchain_fix": ap.is_gles,
            "gl_hide_multiview": lambda a: a.direct_vrapi and ap.is_gles(a),
            "gl_hide_msrtt": ap.is_gles,
+            "ovrp_begin_gate": lambda a: a.engine == "Unity" and "libOVRPlugin.so" in a.libs,
+            "ovrp_hold_physics": lambda a: a.engine == "Unity" and "libOVRPlugin.so" in a.libs,
            "vk_shader_fix": lambda a: a.engine == "Unreal",  # read by the Vulkan shim, which only Unreal games get
            "vk_hide_fdm": lambda a: a.engine == "Unreal",  # Unreal's Vulkan isn't always detected (Metro Awakening)
            "vk_query_slots": lambda a: a.engine == "Unreal" and ap.is_vulkan(a),
@@ -44,6 +44,12 @@ SUMMARIES = {
                       "Frame's graphics driver accepts.",
    "frame.unity_gl_shim": "Stops a grey or frozen screen in Unity games that turn on anti-aliasing while running "
                           "(e.g. The Room VR).",
+    "frame.unreal_gl_shim": "Stops a crash a few seconds after start in Unreal games whose anti-aliasing the Frame's "
+                            "graphics driver can't handle (e.g. Star Wars Pinball VR).",
+    "frame.unreal_ovrp_entrypoints": "Lets older Unreal games start VR although the converted VR plugin lacks a few "
+                                     "functions they look for (e.g. Star Wars Pinball VR).",
+    "frame.pac_hints": "Stops a crash on the Frame's CPU in games whose code has unpaired security checks the Quest "
+                       "ignores (e.g. Star Wars Pinball VR's first network connection).",
    "frame.unity_no_overlay_copy": "Stops a grey screen crash in some Unity games by skipping their overlay "
                                   "layers (e.g. The Room VR's screen fades).",
    "frame.nodebug": "Stops strict debugging checks that make some games quit.",
@@ -54,6 +60,8 @@ SUMMARIES = {
                       "waiting for a download that never comes.",
    "frame.ovr_trace": "For troubleshooting: records the game's requests to Meta's platform services and which ones "
                       "never get an answer.",
+    "frame.slz_vulkan_hooks": "Lets Unity start the graphics itself instead of Stress Level Zero's plugin, "
+                              "which crashes on the Frame (e.g. BONELAB 1.2974).",
    "frame.unity_user_presence": "Counts the headset as worn, so games that only move the player while it's worn "
                                 "get head tracking and controls (e.g. BONELAB).",
    "frame.unity_no_msaa": "Turns off a smoothing setting that crashes some older Unity games on the Frame.",
@@ -0,0 +1,152 @@
+"""Upstream fixes that make one of our workarounds unnecessary, applied per build.
+
+Several patches work around bugs in what OVRPort puts into a converted APK (its closed-source runtime libraries, its
+CLI). When upstream fixes such a bug, users don't all get the fix at once: OVRPort downloads runtime builds into its
+workspace and each conversion uses whichever one it picks, so one library can hold games built with the old and the
+new runtime. A version number doesn't help either (runtime builds are named `<version>-<commit>`, the commit part is
+unordered). So each fix is detected in the converted APK itself: a probe looks at the bytes OVRPort produced, and when
+it finds the upstream fix, the build leaves the workaround out.
+
+The recipe is never changed: it still asks for the fix (`adapter.haptic_fix` on), the build decides how to provide it.
+A build made with an old runtime keeps the workaround; the next build with a fixed runtime drops it by itself, and a
+build made with a later runtime that regressed would get the workaround back. Builds record what was left out
+(`build.superseded`), the installer leaves those out of settings.conf too, and the build log says why.
+
+Add one: write a probe (True = the upstream fix is there, False = the bug is there, None = can't tell, e.g. the library
+is missing or looks different) and `register(UpstreamFix(...))` in the workaround's own module. Only True drops the
+workaround, so a probe that can't recognise newer code errs on the safe side. Then update the workaround's tracker
+issue (`upstream` label). FRAMEPORT_KEEP_WORKAROUNDS=1 keeps every workaround (to compare builds).
+"""
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..apk.workspace import ApkWorkspace
+    from ..core.events import Reporter
+
+Probe = Callable[["ApkWorkspace"], "bool | None"]
+
+
+@dataclass(frozen=True)
+class UpstreamFix:
+    id: str  # e.g. "ovrport.haptic_envelope"
+    workaround: str  # the patch id this fix makes unnecessary, e.g. "adapter.haptic_fix"
+    title: str  # what upstream fixed, for the build log
+    upstream: str  # where it was fixed, e.g. "ovrport/app#73 (runtime 3.4.3-aa54c3f)"
+    probe: Probe
+    tracker: str = ""  # our tracking issue, e.g. "#74"
+
+
+REGISTRY: dict[str, UpstreamFix] = {}
+
+
+def register(fix: UpstreamFix) -> UpstreamFix:
+    if not fix.id or fix.id in REGISTRY:
+        raise ValueError(f"bad or duplicate upstream fix id {fix.id!r}")
+    REGISTRY[fix.id] = fix
+    return fix
+
+
+def lib_probe(library: str, check: Callable[[bytes], bool | None]) -> Probe:
+    """A probe that runs `check` on one of the APK's native libraries (None when the APK doesn't have it)."""
+    def probe(ws: ApkWorkspace) -> bool | None:
+        return check(ws.read_lib(library)) if ws.abi and ws.has(ws.lib(library)) else None
+
+    return probe
+
+
+@dataclass
+class Resolution:
+    patches: dict  # the selection this build applies
+    superseded: dict[str, str] = field(default_factory=dict)  # workaround patch id -> upstream fix id
+    found: dict[str, bool | None] = field(default_factory=dict)  # upstream fix id -> probe result (for the log)
+
+
+def resolve(ws: ApkWorkspace, patches: dict, reporter: Reporter | None = None) -> Resolution:
+    """Leave out the workarounds whose upstream fix is in this (converted) APK."""
+    from . import base
+
+    base.load_all()
+    res = Resolution(dict(patches))
+    if os.environ.get("FRAMEPORT_KEEP_WORKAROUNDS"):
+        return res
+    for fix in REGISTRY.values():
+        if fix.workaround not in patches:
+            continue
+        try:
+            found = fix.probe(ws)
+        except Exception as e:  # noqa: BLE001  (a probe that breaks must not break the build: keep the workaround)
+            found = None
+            if reporter:
+                reporter.log(f"upstream fix check {fix.id} failed ({e}); keeping {fix.workaround}")
+        res.found[fix.id] = found
+        if found:
+            res.patches.pop(fix.workaround, None)
+            res.superseded[fix.workaround] = fix.id
+            if reporter:
+                reporter.log(f"not needed: {fix.workaround} ({fix.title}, fixed upstream in {fix.upstream})")
+    return res
+
+
+def without_superseded(patches: dict, superseded) -> dict:
+    """A recipe's selection minus the workarounds a build left out (for the install of that build)."""
+    return {pid: params for pid, params in patches.items() if pid not in (superseded or ())}
+
+
+# ---------------------------------------------------------------- arm64 helpers for probes
+
+def code_words(data: bytes):
+    """(file offset, instruction word) for every word of the library's executable sections."""
+    from ..analysis import elf
+
+    for sec in elf._elf(data).iter_sections():
+        if sec["sh_type"] == "SHT_PROGBITS" and sec["sh_flags"] & 0x4:  # SHF_EXECINSTR
+            start, size = sec["sh_offset"], sec["sh_size"]
+            for off in range(start, start + size - 3, 4):
+                yield off, int.from_bytes(data[off:off + 4], "little")
+
+
+def move_wide(word: int) -> tuple[str, int, int, int, int] | None:
+    """Decode MOVZ/MOVK/MOVN: (kind, sf, rd, imm16, shift) or None."""
+    kinds = {0x52800000: "movz", 0x72800000: "movk", 0x12800000: "movn"}
+    kind = kinds.get(word & 0x7F800000)
+    if kind is None:
+        return None
+    return kind, word >> 31, word & 31, (word >> 5) & 0xFFFF, ((word >> 21) & 3) * 16
+
+
+def constants(words) -> list[int]:
+    """Every value a register holds after each MOVZ/MOVK/MOVN in a run of instruction words (how compilers build
+    64-bit constants such as doubles: movz + movk)."""
+    regs: dict[int, int] = {}
+    out = []
+    for w in words:
+        mw = move_wide(w)
+        if mw is None:
+            continue
+        kind, sf, rd, imm, shift = mw
+        mask = (1 << 64) - 1 if sf else (1 << 32) - 1
+        if kind == "movz":
+            regs[rd] = imm << shift
+        elif kind == "movn":
+            regs[rd] = ~(imm << shift) & mask
+        else:
+            regs[rd] = (regs.get(rd, 0) & ~(0xFFFF << shift) | imm << shift) & mask
+        out.append(regs[rd])
+    return out
+
+
+def find_constant_load(words: list[int], value: int) -> int | None:
+    """Index of the first MOVZ/MOVN that starts building `value` (32-bit) in its register, followed by the MOVK that
+    completes it within the next few instructions."""
+    for i, w in enumerate(words):
+        mw = move_wide(w)
+        if mw is None or mw[0] == "movk":
+            continue
+        if value in constants(words[i:i + 4]):
+            return i
+    return None
@@ -9,6 +9,7 @@ PC (Revive + local Steam) or on the Frame (Proton + Revive).
 """
 from __future__ import annotations

+import dataclasses
 import threading
 import time
 from pathlib import Path
@@ -21,6 +22,7 @@ from .core import library
 from .core.events import Reporter
 from .core.models import Recipe, SourceGame
 from .core.paths import output_dir
+from .patches import upstream
 from .recommend import engine
 from .sources import quest_dump, rift_dump
 from .targets.base import Target
@@ -284,6 +286,30 @@ def is_linux(entry: dict) -> bool:
    return entry.get("kind") == "linux"


+def analysis_warnings(entry: dict) -> list[str]:
+    """Blockers read from a Quest/Android game's APK, for the CLI (the game page shows them as callouts)."""
+    if is_rift(entry) or is_linux(entry) or not entry.get("analysis"):
+        return []
+    out = engine.blocker_notes(library.analysis_from_dict(entry["analysis"]))
+    if missing_obb(entry):
+        out.append(MISSING_OBB_NOTE.format(package=entry.get("package", "<package>")))
+    return out
+
+
+MISSING_OBB_NOTE = ("This game's data file (.obb) wasn't found next to the APK. Put the .obb files in a folder named "
+                    "{package} (or obb/) next to the APK and add the folder again; without it the game hangs at start.")
+
+
+def missing_obb(entry: dict) -> bool:
+    """A Quest game whose APK expects an OBB (analysis expects_obb: Unreal's bHasOBBFiles) but no data folder was
+    found next to it (GitHub #85: TRIANGLE STRATEGY hung silently after OVRPlugin's JNI_OnLoad). Library fields
+    only: no disk access (used by the game page)."""
+    if is_rift(entry) or is_linux(entry):
+        return False
+    extra = (entry.get("analysis") or {}).get("extra") or {}
+    return bool(extra.get("expects_obb")) and not (entry.get("data_dir") and entry.get("data_bytes") != 0)
+
+
 def add_linux_app(path: Path | str, reporter: Reporter | None = None, exe: str | None = None) -> dict:
    """Add a Linux app to the library (no conversion: it's installed as it is): arm64, or x86_64 (run through FEX on
    the Frame). `exe` overrides the program FramePort picked (relative to the app's folder)."""
@@ -327,8 +353,11 @@ def add_linux_app(path: Path | str, reporter: Reporter | None = None, exe: str |
        from .artwork import fetch

        fetch.artwork_dir(package)
-        from .artwork import steam
+        from .artwork import sources, steam

+        icon = None if info["files"] else linux.find_icon(root)  # a lone AppImage's icon comes from the Frame
+        if icon:
+            sources.apply_app_icon(package, icon.read_bytes())
        steam.ensure_cover(package)  # placeholder art (name on a colour) until the user picks some
    except Exception:  # noqa: BLE001 - artwork is optional
        pass
@@ -426,7 +455,8 @@ def install_linux(package: str, target: Target, reporter: Reporter, add_to_libra
    extra = (entry.get("analysis") or {}).get("extra") or {}
    result = target.install_linux(package, steam_title(entry), Path(entry["game_dir"]), entry["exe"],
                                  extra.get("files"), bool(extra.get("appimage")), bool(extra.get("openxr")),
-                                  reporter, x86_64=bool(extra.get("x86_64")))
+                                  reporter, x86_64=bool(extra.get("x86_64")),
+                                  desktop_entry=entry.get("desktop_entry", True) is not False)
    if extra.get("x86_64"):
        reporter.check("x86 translation", True, "runs through FEX on SteamOS's x86 system (its libraries come from "
                                                 "there; not checked ahead)")
@@ -445,12 +475,13 @@ def add_game(src: SourceGame, reporter: Reporter | None = None) -> dict:
    if reporter:
        reporter.log(f"analyzing {src.apk.name}")
    a = analyze(src.apk, data_bytes=src.data_bytes())
-    a.extra["lang_packs"] = langpacks.find_tags(src.data_dir)
-    a.extra["asset_files"] = langpacks.find_content_files(src.data_dir)
+    a.extra["lang_packs"] = langpacks.find_tags(_data_folder(src))
+    a.extra["asset_files"] = langpacks.find_content_files(_data_folder(src))
    recipe = engine.suggest(a)
    return library.upsert_game(
        a.package, title=recipe.title or a.label, name=src.name, apk=str(src.apk),
-        data_dir=str(src.data_dir) if src.data_dir else None, data_bytes=src.data_bytes(), origin=str(src.origin),
+        data_dir=str(src.data_dir) if src.data_dir else None, data_files=src.data_files, data_bytes=src.data_bytes(),
+        origin=str(src.origin),
        analysis=a.to_dict(), recipe=library.recipe_to_dict(recipe), suggested=library.recipe_to_dict(recipe),
        status=recipe.status,
    )
@@ -460,25 +491,110 @@ def reanalyze(package: str, reporter: Reporter | None = None) -> dict:
    """Read a Quest/Android game's APK again (e.g. after FramePort learned to detect something new). The suggestion is
    refreshed; the recipe too unless the user changed it (then their choices stay)."""
    entry = library.game(package)
-    if entry is None or is_rift(entry):
+    if entry is None or is_rift(entry) or is_linux(entry):
        raise ValueError("only Quest/Android games can be analyzed again")
+    return _store_analysis(package, _analyze_entry(entry, reporter))
+
+
+def _analyze_entry(entry: dict, reporter: Reporter | None = None):
    src = source_of(entry)
    if reporter:
        reporter.log(f"analyzing {src.apk.name}")
    a = analyze(src.apk, data_bytes=src.data_bytes())
-    a.extra["lang_packs"] = langpacks.find_tags(src.data_dir)
-    a.extra["asset_files"] = langpacks.find_content_files(src.data_dir)
+    a.extra["lang_packs"] = langpacks.find_tags(_data_folder(src))
+    a.extra["asset_files"] = langpacks.find_content_files(_data_folder(src))
+    return a
+
+
+def _store_analysis(package: str, a) -> dict:
+    """Replace only the entry's analysis and suggestion; the recipe follows unless it is the user's own (tags, art,
+    title, builds and installs are untouched)."""
    suggested = engine.suggest(a)
-    keep = library.recipe_from_dict(entry["recipe"]).source == "user"
-    return library.upsert_game(package, analysis=a.to_dict(), suggested=library.recipe_to_dict(suggested),
-                               **({} if keep else {"recipe": library.recipe_to_dict(suggested),
-                                                   "status": suggested.status}))
+
+    def change(g: dict) -> None:
+        g["analysis"] = a.to_dict()
+        g["suggested"] = library.recipe_to_dict(suggested)
+        g.pop("analysis_failed", None)
+        # checked under the library lock: the user may have saved a recipe while the APK was read
+        if library.recipe_from_dict(g.get("recipe") or {"package": package}).source != "user":
+            g["recipe"] = library.recipe_to_dict(suggested)
+            g["status"] = suggested.status
+    return library.update_game(package, change)
+
+
+def analysis_outdated(entry: dict) -> bool:
+    """A Quest/Android entry analysed by an older FramePort (fields newer patches depend on are missing) whose APK is
+    still there, and whose re-analysis didn't already fail for this analysis version. Rift/Linux entries: no."""
+    from .analysis.detect import ANALYSIS_VERSION
+
+    a = entry.get("analysis")
+    if not isinstance(a, dict) or not entry.get("apk") or is_rift(entry) or is_linux(entry):
+        return False
+    if str(a.get("package") or "").startswith("rift."):
+        return False
+    if ((a.get("extra") or {}).get("analysis_version") or 0) >= ANALYSIS_VERSION:
+        return False
+    if entry.get("analysis_failed") == ANALYSIS_VERSION:
+        return False
+    try:
+        return Path(entry["apk"]).is_file()  # on a drive that isn't connected now: tried again at a later start
+    except OSError:
+        return False
+
+
+def outdated_analyses() -> list[str]:
+    return [g["package"] for g in library.games() if analysis_outdated(g)]
+
+
+def refresh_analyses(packages: list[str] | None = None, reporter: Reporter | None = None) -> int:
+    """Analyse again the entries an older FramePort analysed (see detect.ANALYSIS_VERSION): runs in the background at
+    start (GUI) and before a build (CLI and GUI). Only the APK analysis (no OVRPort, no Cpp2IL). An APK that can't be
+    read leaves the entry as it was and is marked, so it isn't read again at every start. Returns how many changed."""
+    from .analysis.detect import ANALYSIS_VERSION
+
+    todo = outdated_analyses() if packages is None else \
+        [p for p in packages if analysis_outdated(library.game(p) or {})]
+    done = 0
+    for i, pkg in enumerate(todo):
+        entry = library.game(pkg)
+        if entry is None or not analysis_outdated(entry):
+            continue
+        if reporter:
+            reporter.check_cancel()
+            reporter.progress(i / len(todo), entry.get("title") or pkg)
+        try:
+            a = _analyze_entry(entry, reporter)
+        except Exception as exc:  # noqa: BLE001 - unreadable APK: keep the old analysis, don't retry every start
+            if reporter:
+                reporter.log(f"{pkg}: couldn't analyze the APK again: {exc}")
+            library.update_game(pkg, lambda g: g.__setitem__("analysis_failed", ANALYSIS_VERSION))
+            continue
+        if a.package != pkg:  # a different APK at that path now: leave the entry alone
+            library.update_game(pkg, lambda g: g.__setitem__("analysis_failed", ANALYSIS_VERSION))
+            continue
+        _store_analysis(pkg, a)
+        done += 1
+    return done
+
+
+def _data_folder(src: SourceGame) -> Path | None:
+    """The data folder when all of it is the game's data (language packs and content files are looked for there);
+    None when only expansion files found by name are (that folder also holds other things, e.g. the APK)."""
+    return None if src.data_files is not None else src.data_dir
+
+
+def data_paths(entry: dict) -> list[Path]:
+    """A Quest game's data on this PC: its data folder, or only its expansion files when those were found by name."""
+    if not entry.get("data_dir"):
+        return []
+    d = Path(entry["data_dir"])
+    return [d / n for n in entry["data_files"]] if entry.get("data_files") is not None else [d]


 def source_of(entry: dict) -> SourceGame:
    return SourceGame(entry.get("name") or entry["package"], Path(entry["apk"]),
                      Path(entry["data_dir"]) if entry.get("data_dir") else None,
-                      Path(entry["origin"]) if entry.get("origin") else None)
+                      Path(entry["origin"]) if entry.get("origin") else None, data_files=entry.get("data_files"))


 def set_recipe(package: str, recipe: Recipe) -> None:
@@ -595,6 +711,8 @@ def _build_lock(package: str) -> threading.Lock:


 def build_game(package: str, reporter: Reporter, outdir: Path | None = None) -> dict:
+    if analysis_outdated(library.game(package) or {}):  # analysed by an older FramePort: new fields first
+        refresh_analyses([package], reporter)
    entry = library.game(package)
    if is_linux(entry):  # nothing to convert: installed as it is
        return {"ok": True, "linux": True}
@@ -611,7 +729,8 @@ def build_game(package: str, reporter: Reporter, outdir: Path | None = None) ->
    art, store_title = artwork.fetch(package, res.apk)
    build_info = {"apk": str(res.apk), "alt_apk": str(res.alt_apk) if res.alt_apk else None, "sha256": res.sha256,
                  "alt_sha256": res.alt_sha256, "applied": res.applied, "checks": res.checks, "ok": res.ok,
-                  "overport": res.meta.get("overport"), "recipe_fp": recipe_fingerprint(entry["recipe"])}
+                  "overport": res.meta.get("overport"), "recipe_fp": recipe_fingerprint(entry["recipe"]),
+                  "superseded": res.meta.get("superseded") or {}}
    library.upsert_game(package, build=build_info, title=entry.get("title") or store_title)
    return build_info

@@ -634,9 +753,12 @@ def install_game(package: str, target: Target, reporter: Reporter, apk_only: boo
    if not test_build and not apk.exists():  # the converted copy was removed after an earlier install: make it again
        build_game(package, reporter)
        return install_game(package, target, reporter, apk_only, add_to_library)
+    if not test_build and b.get("superseded"):  # workarounds this build left out (upstream fixed): not in settings.conf
+        recipe = dataclasses.replace(recipe, patches=upstream.without_superseded(recipe.patches, b["superseded"]))
    data_dir = Path(entry["data_dir"]) if entry.get("data_dir") else None
    title = steam_title(entry)
-    result = target.install(package, title, apk, data_dir, recipe, reporter, apk_only)
+    result = target.install(package, title, apk, data_dir, recipe, reporter, apk_only,
+                            data_files=entry.get("data_files"))
    if add_to_library:
        target.add_to_library([package], reporter)
    _record_install(package, target.label, {"apk": str(apk), "result": result, "time": time.time()})
@@ -670,13 +792,14 @@ def local_game_files(package: str) -> list[Path]:
    elif is_linux(g):
        paths += linux_local_files(g)
    else:
-        paths += [Path(p) for p in (g.get("apk"), g.get("data_dir")) if p]
+        paths += [Path(g["apk"])] if g.get("apk") else []
+        paths += data_paths(g)
    b = g.get("build") or {}
    out = output_dir().resolve()
    paths += [Path(b[k]) for k in ("apk", "alt_apk") if b.get(k) and out in Path(b[k]).resolve().parents]
    others = [o for o in library.games() if o.get("package") != package]
    used = [Path(p).resolve() for o in others if not is_linux(o)
-            for p in (o.get("apk"), o.get("data_dir"), o.get("game_dir")) if p]
+            for p in (o.get("apk"), o.get("game_dir"), *data_paths(o)) if p]
    used += [p.resolve() for o in others if is_linux(o) for p in linux_local_files(o)]  # (lone AppImages: the file)

    def shared(p: Path) -> bool:  # the same path, a path inside it, or a folder around it belongs to another game
@@ -795,6 +918,10 @@ def install_rift(package: str, target: Target, reporter: Reporter, add_to_librar

 def test_game(package: str, target: Target, reporter: Reporter, seconds: int = 45) -> dict:
    result, log = target.launch_test(package, reporter, seconds)
+    if missing_obb(library.game(package) or {}):
+        from .validate.triage import add_missing_obb
+
+        add_missing_obb(result)
    from .core.paths import user_data_dir

    logs = user_data_dir() / "logs"
@@ -80,6 +80,7 @@ def suggest(analysis: Analysis, use_catalog: bool = True) -> Recipe:
            recipe.status = "unsupported"
            recipe.notes = f"No 64-bit ARM code ({', '.join(analysis.abis)}): the Steam Frame can't run it."
        if not rift:
+            _static_blockers(analysis, recipe)
            _non_quest(analysis, recipe)
    if not rift and not entry and (analysis.extra or {}).get("frame_patched"):
        # already has FramePort's adapter (e.g. a PATCHED/ build): installing it unchanged is the safe default
@@ -177,6 +178,39 @@ def warnings(recipe: Recipe) -> list[str]:
    return out


+def android_version_note(analysis: Analysis) -> str | None:
+    """'Its manifest asks for Android 14 (API 34)…' when the APK's minimum Android is newer than the Frame's."""
+    from ..analysis.detect import FRAME_API, android_version, too_new_android
+
+    min_sdk = (analysis.extra or {}).get("min_sdk")
+    if not too_new_android(min_sdk):
+        return None
+    return (f"Its manifest asks for Android {android_version(min_sdk)} (API {min_sdk}); the Frame's Android is "
+            f"{android_version(FRAME_API)} (API {FRAME_API}). Apps like this often crash at start on newer Android "
+            "parts, but not always: a launch test tells.")
+
+
+def web_wrapper_note(analysis: Analysis) -> str | None:
+    """A Trusted Web Activity: the APK only opens a website in Meta's browser (analysis.detect.web_wrapper)."""
+    ww = (analysis.extra or {}).get("web_wrapper")
+    if not ww:
+        return None
+    where = f"open {ww['url']} in a browser instead" if ww.get("url") else "open the website in a browser instead"
+    return (f"This app looks like a website in an Android wrapper (Trusted Web Activity): it opens the site in "
+            f"Meta's browser, which the Frame doesn't have. If nothing opens, {where}.")
+
+
+def blocker_notes(analysis: Analysis) -> list[str]:
+    """Warnings read from the APK's manifest that it may not run on the Frame (whatever the recipe says). Only
+    warnings: the manifest alone never marks a game unsupported (owner's rule); a launch test's triage decides."""
+    return [n for n in (android_version_note(analysis), web_wrapper_note(analysis)) if n]
+
+
+def _static_blockers(analysis: Analysis, recipe: Recipe) -> None:
+    for note in blocker_notes(analysis):
+        recipe.notes = _add(recipe.notes, note)
+
+
 def _non_quest(analysis: Analysis, recipe: Recipe) -> None:
    """Android apps that aren't Meta Quest apps (analysis.detect.vr_kind)."""
    kind = analysis.vr_kind
@@ -3,10 +3,17 @@
 Accepted layouts:
  <folder>/<something>.apk [+ <folder>/<package>/ (OBB or raw asset data)]   e.g. common downloader layouts
  <folder>/<package>.apk + <folder>/obb/                                       FramePort/PATCHED output layout
+  <folder>/x.apk + <folder>/obb/<package>/ or Android/obb/<package>/          backups with an obb folder
+  <game>/apk/x.apk + <game>/obb/<package>/                                     SideQuest-style backups (one game)
+  <folder>/x.apk + (main|patch).<versionCode>.<package>.obb anywhere nearby    found by file name (next to the APK,
+                                                                               <package>/apk/ + <package>/obb/, ...)
  a single .apk file
+(find_data has the details.)
 """
 from __future__ import annotations

+import contextvars
+import os
 import re
 import zipfile
 from pathlib import Path
@@ -22,13 +29,23 @@ def display_name(folder_name: str) -> str:
    return re.sub(r'[<>:"/\\|?*]', "_", TAG.sub("", folder_name).strip())


-def _package_of(apk: Path) -> str | None:
+def _apk_ids(apk: Path) -> tuple[str | None, int | None]:
+    """(package, versionCode) from the APK's manifest; None for what can't be read."""
    try:
        from pyaxmlparser import APK

-        return APK(str(apk)).package
+        a = APK(str(apk))
    except Exception:
-        return None
+        return None, None
+    try:
+        vc = int(a.version_code)
+    except (TypeError, ValueError):
+        vc = None
+    return a.package, vc
+
+
+def _package_of(apk: Path) -> str | None:
+    return _apk_ids(apk)[0]


 def _is_apk(path: Path) -> bool:
@@ -39,12 +56,185 @@ def _is_apk(path: Path) -> bool:
        return False


+OBB_FOLDERS = ("obb", "obbs")
+
+
+# folder listings, kept while scan() runs: every game of a collection searches its neighbours (slow on NTFS drives)
+_LISTINGS: contextvars.ContextVar[dict | None] = contextvars.ContextVar("quest_dump_listings", default=None)
+
+
+def _list(d: Path) -> list[tuple[Path, bool]]:
+    """(entry, is a folder) in d, sorted; [] when it can't be read."""
+    cache = _LISTINGS.get()
+    if cache is not None and d in cache:
+        return cache[d]
+    try:
+        with os.scandir(d) as it:
+            out = sorted((Path(e.path), e.is_dir()) for e in it)
+    except OSError:
+        out = []
+    if cache is not None:
+        cache[d] = out
+    return out
+
+
+def _subdirs(d: Path) -> list[Path]:
+    return [p for p, is_dir in _list(d) if is_dir and not p.name.startswith(("_", "."))]
+
+
+def _has_apks(d: Path) -> bool:
+    return any(p.suffix.lower() == ".apk" and not is_dir for p, is_dir in _list(d))
+
+
+def _child(d: Path, name: str) -> Path | None:
+    """d/name, matching the name's case loosely (backups come from Windows: 'OBB', a lower-case package folder)."""
+    exact = d / name
+    if exact.is_dir():
+        return exact
+    return next((p for p in _subdirs(d) if p.name.lower() == name.lower()), None)
+
+
+def _nonempty(d: Path | None) -> bool:
+    try:
+        return bool(d) and d.is_dir() and any(d.iterdir())
+    except OSError:
+        return False
+
+
+def _has_obb(d: Path) -> bool:
+    return any(p.suffix.lower() == ".obb" and not is_dir for p, is_dir in _list(d))
+
+
+def _package_dir_below(d: Path, pkg: str, depth: int, skip: Path | None = None, other_games: bool = False) \
+        -> Path | None:
+    """A folder named like the package holding .obb files, at most `depth` levels below d. other_games: skip
+    folders with APKs of their own (a neighbouring game folder, e.g. another version of the same game)."""
+    for sub in _subdirs(d):
+        if skip is not None and sub == skip:
+            continue
+        if sub.name.lower() == pkg.lower():
+            if _has_obb(sub):
+                return sub
+            continue
+        if depth > 1 and not (other_games and _has_apks(sub)):
+            found = _package_dir_below(sub, pkg, depth - 1)
+            if found:
+                return found
+    return None
+
+
+def _find_data_dir(apk_dir: Path, pkg: str | None) -> Path | None:
+    """The folder whose contents go to Android/obb/<package>/ (so the folder holding the .obb files themselves):
+      <apk dir>/<package>/                       downloader layouts
+      <apk dir>/obb/<package>/ or <apk dir>/obb/  FramePort/PATCHED output, backups with an obb folder
+      a <package> folder with .obb files up to 3 levels below the APK's folder (e.g. Android/obb/<package>/) or 2
+      below its parent (SideQuest-style backups: <game>/apk/x.apk + <game>/obb/<package>/; the parent's folders
+      with APKs of their own are other games and are skipped)."""
+    own = _child(apk_dir, pkg) if pkg else None
+    if _nonempty(own):
+        return own
+    for obb in (_child(apk_dir, name) for name in OBB_FOLDERS):
+        if obb is None:
+            continue
+        inner = _child(obb, pkg) if pkg else None
+        if _nonempty(inner):
+            return inner
+        if _nonempty(obb):
+            return obb
+    if not pkg:
+        return None
+    found = _package_dir_below(apk_dir, pkg, 3)
+    if found is None and apk_dir.parent != apk_dir:
+        found = _package_dir_below(apk_dir.parent, pkg, 2, skip=apk_dir, other_games=True)
+    return found
+
+
+# Android's expansion file names: main.<versionCode>.<package>.obb, patch.<versionCode>.<package>.obb
+OBB_NAME = re.compile(r"^(main|patch)\.(\d+)\.(.+)\.obb$", re.IGNORECASE)
+
+
+def _named_obbs(d: Path, pkg: str) -> list[tuple[str, int, Path]]:
+    """(kind, versionCode, file) of the package's expansion files directly in d."""
+    out = []
+    for f, is_dir in _list(d):
+        m = OBB_NAME.match(f.name)
+        if m and m.group(3).lower() == pkg.lower() and not is_dir:
+            out.append((m.group(1).lower(), int(m.group(2)), f))
+    return out
+
+
+def _obb_folders(apk_dir: Path, pkg: str, depth: int = 3) -> list[tuple[Path, list[tuple[str, int, Path]]]]:
+    """Folders holding the package's expansion files by name, nearest first: the APK's own folder, the folders below
+    it, its parent, then the parent's other folders (each up to `depth` levels). Folders with APKs of their own are
+    other games (e.g. another version of this one) and aren't searched."""
+    found: list[tuple[Path, list]] = []
+
+    def visit(d: Path) -> None:
+        obbs = _named_obbs(d, pkg)
+        if obbs:
+            found.append((d, obbs))
+
+    def below(d: Path, level: int, skip: Path | None = None) -> None:
+        for sub in _subdirs(d):
+            if sub == skip or _has_apks(sub):
+                continue
+            visit(sub)
+            if level > 1:
+                below(sub, level - 1)
+
+    visit(apk_dir)
+    below(apk_dir, depth)
+    parent = apk_dir.parent
+    if parent != apk_dir:
+        visit(parent)
+        below(parent, depth, skip=apk_dir)
+    return found
+
+
+def _pick_obbs(obbs: list[tuple[str, int, Path]], version_code: int | None) -> list[Path]:
+    """The expansion files for this APK: per kind (main, patch) the newest one not newer than the APK's versionCode
+    (expansion files keep the versionCode they were introduced with, so that's its own one when there is one); only
+    when there is none at all, the newest ones (another version of the game's files: better than nothing)."""
+    usable = [o for o in obbs if version_code is not None and o[1] <= version_code] or obbs
+    picked = []
+    for kind in ("main", "patch"):
+        same = sorted((vc, f) for k, vc, f in usable if k == kind)
+        if same:
+            picked.append(same[-1][1])
+    return picked
+
+
+def find_data(apk_dir: Path, pkg: str | None, version_code: int | None = None) -> tuple[Path | None, list[str] | None]:
+    """(data folder, files) for the APK in apk_dir. files is None when the whole folder is the game's data (the
+    layouts of _find_data_dir), else the names of the expansion files to send from it (found by file name, e.g.
+    lying next to the APK: the APK and anything else in that folder stay on the PC)."""
+    data = _find_data_dir(apk_dir, pkg)
+    if data is not None or not pkg:
+        return data, None
+    folders = _obb_folders(apk_dir, pkg)
+    if not folders:
+        return None, None
+    d, obbs = next((f for f in folders if any(vc == version_code for _, vc, _ in f[1])), folders[0])
+    files = _pick_obbs(obbs, version_code)
+    everything = {p.name for p, _ in _list(d)}
+    names = [f.name for f in files]
+    return d, (None if everything == set(names) else names)
+
+
+def find_data_dir(apk_dir: Path, pkg: str | None, version_code: int | None = None) -> Path | None:
+    return find_data(apk_dir, pkg, version_code)[0]
+
+
+# a folder that only holds the APK inside a game folder (<game>/apk/x.apk + <game>/obb/…): the game is the parent
+APK_FOLDERS = ("apk", "apks")
+
+
 def from_path(path: Path) -> SourceGame | None:
    path = Path(path)
    if path.is_file() and path.suffix.lower() == ".apk":
-        pkg = _package_of(path)
-        data = next((d for d in (path.parent / (pkg or ""), path.parent / "obb") if pkg and d.is_dir()), None)
-        return SourceGame(display_name(path.stem), path, data, path.parent)
+        pkg, vc = _apk_ids(path)
+        data, files = find_data(path.parent, pkg, vc)
+        return SourceGame(display_name(path.stem), path, data, path.parent, data_files=files)
    if not path.is_dir():
        return None
    apks = sorted(p for p in path.glob("*.apk") if _is_apk(p))
@@ -52,13 +242,10 @@ def from_path(path: Path) -> SourceGame | None:
        return None
    primary = [a for a in apks if ".alt-" not in a.name]
    apk = primary[0] if primary else apks[0]
-    pkg = _package_of(apk)
-    data = None
-    for cand in ((path / pkg) if pkg else None, path / "obb"):
-        if cand and cand.is_dir() and any(cand.iterdir()):
-            data = cand
-            break
-    return SourceGame(display_name(path.name), apk, data, path, [a for a in apks if a != apk])
+    pkg, vc = _apk_ids(apk)
+    data, files = find_data(path, pkg, vc)
+    game_dir = path.parent if path.name.lower() in APK_FOLDERS else path
+    return SourceGame(display_name(game_dir.name), apk, data, game_dir, [a for a in apks if a != apk], files)


 def _no_quest_games_below(d: Path) -> bool:
@@ -77,7 +264,8 @@ def _other_folders(d: Path, game: SourceGame) -> list[Path]:
    except OSError:
        return []
    own = {game.data_dir.resolve()} if game.data_dir else set()
-    return [p for p in subs if p.resolve() not in own and p.name.lower() not in ("obb", "android")]
+    own |= set(game.data_dir.resolve().parents) if game.data_dir else set()  # e.g. Android/ of Android/obb/<pkg>
+    return [p for p in subs if p.resolve() not in own and p.name.lower() not in (*OBB_FOLDERS, "android")]


 def scan(root: Path, depth: int = 5) -> list[SourceGame]:
@@ -111,5 +299,9 @@ def scan(root: Path, depth: int = 5) -> list[SourceGame]:
    if root.is_file():
        g = from_path(root)
        return [g] if g else []
-    walk(root, 0)
+    token = _LISTINGS.set({})
+    try:
+        walk(root, 0)
+    finally:
+        _LISTINGS.reset(token)
    return found
@@ -21,7 +21,7 @@ class Target(ABC):

    @abstractmethod
    def install(self, package: str, title: str, apk: Path, data_dir: Path | None, recipe: Recipe,
-                reporter: Reporter, apk_only: bool = False) -> dict: ...
+                reporter: Reporter, apk_only: bool = False, data_files: list[str] | None = None) -> dict: ...

    @abstractmethod
    def add_to_library(self, packages: list[str], reporter: Reporter) -> dict: ...
@@ -33,7 +33,8 @@ class Target(ABC):
        """Start an installed game for playing, through the target's Steam (Steam library shortcut)."""
        raise NotImplementedError(f"{self.label} can't launch games")

-    def install_linux(self, package, title, root, exe, files, appimage, openxr, reporter, x86_64=False) -> dict:
+    def install_linux(self, package, title, root, exe, files, appimage, openxr, reporter, x86_64=False,
+                      desktop_entry=True) -> dict:
        """Install a Linux app (only the Frame runs them; x86_64 ones through FEX)."""
        raise NotImplementedError(f"{self.label} can't install Linux apps")

@@ -7,7 +7,7 @@ from pathlib import Path
 from ..core.events import Reporter
 from ..core.models import Recipe
 from ..frame.connection import Frame, FrameTarget, sh_quote
-from ..install import installer
+from ..install import drives, installer
 from ..validate import device
 from .base import Target

@@ -19,6 +19,12 @@ class FrameLeptonTarget(Target):
        self.target = target
        self.frame = Frame(target, password)
        self.label = target.label
+        self.dest: str | None = None  # where new games go; None = the library setting (drives.install_dest)
+
+    def install_dest(self) -> str | None:
+        """A drive's install dir for new installs (GitHub #90), None = internal storage. Reinstalls stay where the
+        game is (the agent keeps an installed game's folder)."""
+        return self.dest if self.dest is not None else drives.install_dest()

    def connect(self) -> FrameLeptonTarget:
        if self.frame.client is not None and not self.frame.alive():
@@ -33,8 +39,10 @@ class FrameLeptonTarget(Target):
    def installed(self) -> list[dict]:
        return self.connect().frame.agent("list_installed")["games"]

-    def install(self, package, title, apk: Path, data_dir, recipe: Recipe, reporter: Reporter, apk_only=False):
-        plan = installer.InstallPlan(package, title, apk, data_dir, recipe, apk_only)
+    def install(self, package, title, apk: Path, data_dir, recipe: Recipe, reporter: Reporter, apk_only=False,
+                data_files=None):
+        plan = installer.InstallPlan(package, title, apk, data_dir, recipe, apk_only, dest=self.install_dest(),
+                                     data_files=data_files)
        return installer.install(self.connect().frame, plan, reporter)

    def add_to_library(self, packages, reporter):
@@ -60,13 +68,27 @@ class FrameLeptonTarget(Target):

    def install_pcvr(self, package, title, game_dir, exe, recipe, reporter, **extra):
        plan = installer.PcvrPlan(package, title, Path(game_dir), exe, recipe, extra.get("revive_dir"),
-                                  extra.get("exe_sha256"), extra.get("revive_version"), extra.get("art_lookup"))
+                                  extra.get("exe_sha256"), extra.get("revive_version"), extra.get("art_lookup"),
+                                  dest=self.install_dest())
        return installer.install_pcvr(self.connect().frame, plan, reporter)

-    def install_linux(self, package, title, root, exe, files, appimage, openxr, reporter, x86_64=False):
-        plan = installer.LinuxPlan(package, title, Path(root), exe, files, appimage, openxr, x86_64)
+    def install_linux(self, package, title, root, exe, files, appimage, openxr, reporter, x86_64=False,
+                      desktop_entry=True):
+        plan = installer.LinuxPlan(package, title, Path(root), exe, files, appimage, openxr, x86_64,
+                                   dest=self.install_dest(), desktop_entry=desktop_entry)
        return installer.install_linux(self.connect().frame, plan, reporter)

+    def drives(self) -> list[dict]:
+        return drives.list_drives(self.connect().frame)
+
+    def move(self, package: str, dest: str, reporter: Reporter) -> dict:
+        """Move an installed game's files to another drive (or back to internal storage: dest "internal")."""
+        return drives.move(self.connect().frame, package, dest, reporter)
+
+    def set_desktop_entry(self, package: str, enabled: bool) -> dict:
+        """A Linux app's Desktop Mode entry on or off (GitHub #84)."""
+        return self.connect().frame.agent("desktop_entry", package=package, enabled=enabled)
+
    def proton_status(self, tool: str | None = None) -> dict:
        return self.connect().frame.agent("proton_status", tool=tool)

@@ -141,7 +141,7 @@ class PcReviveTarget(Target):
        return out

    # ------------------------------------------------------------------ install
-    def install(self, package, title, apk, data_dir, recipe, reporter, apk_only=False):
+    def install(self, package, title, apk, data_dir, recipe, reporter, apk_only=False, data_files=None):
        raise NotImplementedError("Quest (APK) games install on the Steam Frame, not on the PC")

    def install_pcvr(self, package, title, game_dir, exe, recipe: Recipe, reporter: Reporter, **extra):
@@ -71,3 +71,23 @@ def patch(apk: Path, outdir: Path, name: str, patches: list[str], reporter: Repo
    if p.returncode or not target.exists():
        raise RuntimeError(f"OVRPort failed (exit {p.returncode}); see log")
    return target
+
+
+def runtime_lib(name: str, abi: str = "arm64-v8a") -> Path | None:
+    """A library of the newest OVRPort runtime in the workspace (what `patch --version=latest` ships, e.g.
+    libOVRPlugin.so), or None before OVRPort downloaded one. Newest = first in the workspace's installed.json (the
+    release tracker's order), else the most recently unpacked runtime folder."""
+    import json
+
+    root = user_data_dir() / "overport-workspace" / "libraries"
+    if not root.is_dir():
+        return None
+    order: list[str] = []
+    try:
+        releases = json.loads((root.parent / "installed.json").read_text()).get("releases") or []
+        order = [str(r.get("version")) for r in releases if isinstance(r, dict)]
+    except (OSError, ValueError, AttributeError):
+        pass
+    found = [d for d in root.iterdir() if (d / "lib" / abi / name).is_file()]
+    found.sort(key=lambda d: (order.index(d.name) if d.name in order else len(order), -d.stat().st_mtime))
+    return found[0] / "lib" / abi / name if found else None
@@ -199,11 +199,15 @@ class FramePortApp:
        self.power_row = ft.Container(visible=False)  # the Frame's power button (sleep / restart / shut down)
        self.activity_card = ft.Container()
        self.activity = ActivityPanel(self)
-        wordmark = C.wordmark(T.px(17))
-        self._portal_mark = wordmark.data  # the wordmark's portal (dual themes): pulses once on connect
+        from . import easter
+
+        wordmark = C.wordmark(T.px(easter.WORDMARK_PX))
+        self._portal_mark = wordmark.data  # the wordmark's portal (dual themes): pulses once on connect; easter eggs
+
+        self.logo_egg = easter.Logo(self, T.px(34))  # (ui/easter.py: a holiday badge, seven quick clicks)
        sidebar = ft.Container(ft.Column([
            ft.Container(ft.Row([
-                C.logo(T.px(34)),
+                self.logo_egg.control,
                wordmark], spacing=T.S3),
                padding=ft.Padding(T.S1, T.S2, 0, T.S5)),
            self.nav_col,
@@ -283,7 +287,16 @@ class FramePortApp:
            tx = ft.Text(label, size=T.px(14), weight=ft.FontWeight.W_500, color=T.TEXT_2, expand=True)
            badge = C.dot(T.OK, 7)
            badge.visible = False
-            box = ft.Container(ft.Row([ic, tx, badge], spacing=T.S3),
+            row = [ic, tx, badge]
+            if key == "live":  # (easter egg: a little studio sign blinks while the live view streams)
+                self._on_air = ft.Container(
+                    ft.Text(tr("ON AIR"), size=T.px(8.5), weight=ft.FontWeight.W_800, color="#FFFFFF", no_wrap=True),
+                    padding=ft.Padding(T.px(5), T.px(1), T.px(5), T.px(1)), border_radius=T.px(3), bgcolor=T.ERROR,
+                    shadow=ft.BoxShadow(blur_radius=8, color=T.soft(T.ERROR, 0.6)), visible=False, opacity=1,
+                    animate_opacity=ft.Animation(420, ft.AnimationCurve.EASE_IN_OUT),
+                    tooltip=tr("On air: the live view is streaming"))
+                row.append(self._on_air)
+            box = ft.Container(ft.Row(row, spacing=T.S3, vertical_alignment=ft.CrossAxisAlignment.CENTER),
                               padding=ft.Padding(T.S3, T.px(10), T.S3, T.px(10)), border_radius=T.RADIUS_SM, ink=True,
                               on_click=lambda e, k=key: self.go(k))
            nav[key] = (box, ic, tx, badge)
@@ -314,10 +327,17 @@ class FramePortApp:
        self._conn_ring = C.gauge(0, 40)
        self._conn_bat_text = ft.Text("", size=T.px(12), weight=ft.FontWeight.W_700, color=T.TEXT)
        self._conn_icon = C.as_icon(G.FRAME, T.px(20), T.TEXT_2)
+        from . import easter
+
+        # (easter egg: at 100 % on the charger the ring alone pulses, with a glow behind it)
+        self._conn_glow = easter.ring_glow(ring, T.OK)
+        self._conn_ring.scale = 1.0
+        self._conn_ring.animate_scale = ft.Animation(300, ft.AnimationCurve.EASE_OUT_BACK)
        self._conn_bat = ft.Container(ft.Stack([
-            self._conn_ring,
+            self._conn_glow, self._conn_ring,
            ft.Container(ft.Stack([self._conn_icon, self._conn_bat_text], alignment=ft.Alignment.CENTER),
-                         alignment=ft.Alignment.CENTER, width=ring, height=ring)], width=ring, height=ring),
+                         alignment=ft.Alignment.CENTER, width=ring, height=ring)], width=ring, height=ring,
+            clip_behavior=ft.ClipBehavior.NONE),
            width=ring, height=ring)
        self._conn_extra = ft.Container(C.meta(""), visible=False, tooltip=C.tip(C.HELP["frame_summary"]))
        art = T.px(36)
@@ -413,6 +433,7 @@ class FramePortApp:
            st, "Not set up")
        self._conn_line.color = color
        self.power_row.visible = st == "connected"
+        self.sync_on_air(update=False)
        self._sync_card()
        self._apply_card()
        if st == "connected" and self.frame_info:
@@ -426,6 +447,29 @@ class FramePortApp:
        if update:
            C.update(self.nav_col, self.activity_card, self.power_row, self.conn_card)

+    def sync_on_air(self, update: bool = True) -> None:
+        """The Live view tab's "ON AIR" sign: shown and blinking while a live view streams (an easter egg)."""
+        from . import easter
+
+        sign = getattr(self, "_on_air", None)
+        live = self.live_view.live if self.live_view is not None else None
+        on = bool(live and live.running) and easter.enabled()
+        if sign is None or sign.visible == on:
+            return
+        sign.visible, sign.opacity = on, 1
+        if update:
+            C.update(sign)
+        if on and not self.reduce_motion:
+            threading.Thread(target=self._blink_on_air, args=(sign,), daemon=True).start()
+
+    def _blink_on_air(self, sign: ft.Container) -> None:
+        bright = True
+        while sign.visible and sign is getattr(self, "_on_air", None):
+            time.sleep(0.9)
+            bright = not bright
+            sign.opacity = 1 if bright or not sign.visible else 0.3
+            C.update(sign)
+
    # ------------------------------------------------------------------ live Frame card
    def _sync_card(self) -> None:
        """Keep the card's monitor subscription in step: subscribed while connected and the setting is on, paused
@@ -487,6 +531,13 @@ class FramePortApp:
        bat = s.get("battery") if s and s.get("battery") else (self.frame_info or {}).get("battery") \
            if connected else None
        ring = FC.battery_ring(bat)
+        from . import easter
+
+        if bat is not getattr(self, "_bat_seen", None):  # (a new reading: did it just reach 100 % on the charger?)
+            if easter.charged_now(getattr(self, "_bat_seen", None), bat) and not self.reduce_motion \
+                    and easter.enabled():
+                easter.ring_pulse(self._conn_ring, self._conn_glow)
+            self._bat_seen = bat
        self._conn_icon.visible = ring is None
        self._conn_bat_text.visible = ring is not None
        if ring is None:
@@ -495,7 +546,8 @@ class FramePortApp:
        else:
            from .battery import charging

-            self._conn_ring.value = ring["value"]
+            if not getattr(self._conn_ring, "_pulsing", False):  # (the charge-complete spin steps the value itself)
+                self._conn_ring.value = ring["value"]
            self._conn_ring.color = {"warn": T.WARN, "charging": T.OK}.get(ring["level"], T.OK)
            self._conn_bat_text.value = ring["text"]
            self._conn_bat_text.color = T.WARN if ring["level"] == "warn" else T.TEXT
@@ -614,6 +666,19 @@ class FramePortApp:
        self.reduce_motion = bool(on)
        library.set_setting(REDUCE_MOTION, self.reduce_motion)

+    def _install_milestone(self, package: str | None) -> None:
+        """A game installed on the Frame: the 1st, 10th and 100th different game get a little celebration, once ever
+        (ui/easter.record_install: updates and reinstalls don't count; recorded even with easter eggs off, so turning
+        them on later can't bring an old milestone back), after the install's own toast has been read."""
+        from . import easter
+
+        message = easter.record_install(package)
+        if message and easter.enabled():
+            def later():
+                time.sleep(2.5)
+                easter.celebrate(self, message)
+            self.page.run_thread(later)
+
    def _pulse_portal(self) -> None:
        """The wordmark's portal grows and settles once (the Frame just connected)."""
        mark = self._portal_mark
@@ -768,6 +833,8 @@ class FramePortApp:
                self.toast(msg, action=tr("Open") if pkg and self.route[:2] != ("game", pkg) else tr("Details"),
                           on_action=(lambda e: self.open_game(pkg)) if pkg and self.route[:2] != ("game", pkg)
                           else (lambda e: self.show_activity(True)))
+                if job.kind == "install" and job.to == "frame" and summary.get("verdict") != "fail":
+                    self._install_milestone(job.package)
            elif job.state == "failed":
                msg = tr("{title} failed: {error}").format(title=job.title, error=job.error)
                pkg = job.package
@@ -1041,6 +1108,7 @@ class FramePortApp:
            "details": lambda e: self.refresh_details(pkg),
            "logs": lambda e: self.collect_logs(pkg),
            "report": lambda e: self.report_problem_dialog(pkg),
+            "move": lambda e: self.move_game(pkg),
            "uninstall_frame": lambda e: self.uninstall(pkg, "frame"),
            "uninstall_pc": lambda e: self.uninstall(pkg, "pc"),
            "remove": lambda e: self.remove_from_library(pkg),
@@ -1056,7 +1124,8 @@ class FramePortApp:
            installs=[] if busy or not quick else enabled(self.install_options(g)),
            settings=self.has_game_settings(g), programs=rift or (linux and bool(self.linux_programs(g))),
            selectable=lv is not None,
-            media_button=C.is_media_player(g) and not rift)
+            media_button=C.is_media_player(g) and not rift,
+            movable=connected and C.frame_drive(g, self.frame_info) is not None)
        return menu_sections(g, st, handlers.__getitem__)

    def open_game_menu(self, pkg: str) -> None:
@@ -1159,11 +1228,11 @@ class FramePortApp:
        def ask_frame_oculus():
            # Installing an Oculus/LibOVR Rift game on the Frame: warn that it needs Revive (which can't run there)
            if to != "frame":
-                return ask_license()
+                return ask_obb()
            oculus = [g for g in games if g.get("kind") == "rift"
                      and "pcvr.revive" in (g.get("recipe") or {}).get("patches", {})]
            if not oculus:
-                return ask_license()
+                return ask_obb()
            boxes = {g["package"]: ft.Checkbox(label=self._title(g["package"]), value=False, active_color=T.ACCENT)
                     for g in oculus}
            pick = C.one_choice()
@@ -1178,7 +1247,7 @@ class FramePortApp:
                                  "those Oculus games need PC mode (SteamVR + Revive)."))
                    finished()
                    return
-                ask_license()
+                ask_obb()
            self.page.show_dialog(C.dialog(
                tr("These games can't run on the Steam Frame"),
                ft.Column([
@@ -1191,6 +1260,38 @@ class FramePortApp:
                actions=[C.ghost(tr("Cancel"), on_click=pick(cancel)),
                         C.primary(tr("Continue"), on_click=pick(ok))]))

+        def ask_obb():
+            # the game expects a data file (.obb) that wasn't found next to its APK: it would hang at start (#85)
+            missing = [g for g in games if pipeline.missing_obb(g)]
+            if not missing:
+                return ask_license()
+            boxes = {g["package"]: ft.Checkbox(label=self._title(g["package"]), value=False, active_color=T.ACCENT)
+                     for g in missing}
+            pick = C.one_choice()
+
+            def ok(e):
+                nonlocal games
+                self.page.pop_dialog()
+                keep = {p for p, b in boxes.items() if b.value}
+                games = [g for g in games if g not in missing or g["package"] in keep]
+                if not games:
+                    self.toast(tr("Nothing to install: add the games' .obb files first"))
+                    finished()
+                    return
+                ask_license()
+            self.page.show_dialog(C.dialog(
+                tr("Game data (.obb) not found"),
+                ft.Column([
+                    C.body(tr("These games keep their content in a data file (.obb), and none was found next to "
+                              "their APK. Without it they hang at start. Put the .obb files in a folder named like "
+                              "the game's package (or obb/) next to the APK and add the folder again. Tick any you "
+                              "still want to install.")),
+                    *boxes.values()], spacing=T.S2, tight=True, scroll=ft.ScrollMode.AUTO),
+                height=T.px(min(150 + 36 * len(boxes), 480)),  # fits the list; scrolls when long
+                modal=True, on_dismiss=pick(closed),
+                actions=[C.ghost(tr("Cancel"), on_click=pick(cancel)),
+                         C.primary(tr("Continue"), on_click=pick(ok))]))
+
        def ask_license():
            from ..core import winhost

@@ -1475,6 +1576,67 @@ class FramePortApp:
            return tr("{title}: Steam artwork updated on the Frame").format(title=self._title(pkg))
        return self.submit(tr("Update Steam art: {title}").format(title=self._title(pkg)), run, pkg, "art")

+    def move_game(self, pkg: str) -> None:
+        """Move to…: pick another drive of the Frame (microSD card, internal storage) for an installed game; the copy
+        runs as a Frame job (GitHub #90)."""
+        from ..install import drives
+
+        title = self._title(pkg)
+        here = C.frame_drive(library.game(pkg) or {"package": pkg}, self.frame_info)
+        group = ft.RadioGroup(content=ft.Column([C.meta(tr("Looking for drives…"))], spacing=T.S2))
+        go = C.primary(tr("Move"), ft.Icons.DRIVE_FILE_MOVE_ROUNDED, disabled=True)
+        found: dict[str, dict] = {}
+
+        def picked(e):
+            go.disabled = not group.value
+            C.update(go)
+
+        group.on_change = picked
+
+        def fill():
+            try:
+                listed = self._target_for("frame").drives()
+            except Exception as exc:  # noqa: BLE001
+                group.content.controls = [C.meta(tr("Couldn't list the Frame's drives: {error}")
+                                                 .format(error=explain(exc)))]
+                C.update(group)
+                return
+            rows = []
+            for d in listed:
+                key = drives.INTERNAL if d["internal"] else d["install_dir"]
+                current = drives.is_on({"drive": here}, d) if here else d["internal"]
+                found[key] = d
+                note = tr("it's here now") if current else \
+                    (d.get("reason") or "") if not d.get("usable") else drives.free_text(d)
+                rows.append(ft.Row([
+                    ft.Radio(value=key, active_color=T.ACCENT, disabled=current or not d.get("usable")),
+                    ft.Icon(ft.Icons.SD_CARD_ROUNDED if d.get("removable") else ft.Icons.STORAGE_OUTLINED,
+                            size=T.px(18), color=T.TEXT_2),
+                    ft.Column([C.body(tr("Internal storage") if d["internal"] else d["label"], T.TEXT),
+                               C.meta(note)], spacing=T.px(2), expand=True),
+                ], spacing=T.S2))
+            group.content.controls = rows or [C.meta(tr("Only internal storage"))]
+            C.update(group)
+
+        def start(e):
+            dest = group.value
+            if not dest:
+                return
+            self.page.pop_dialog()
+            label = tr("Internal storage") if dest == drives.INTERNAL else found.get(dest, {}).get("label", dest)
+
+            def run(job: Job):
+                self._target_for("frame").move(pkg, dest, job.reporter)
+                return tr("{title} moved to {label}").format(title=title, label=label)
+            self.submit(tr("Move {title} to {label}").format(title=title, label=label), run, pkg, "tool-frame")
+
+        go.on_click = start
+        self.page.show_dialog(C.dialog(
+            tr("Move {title} to…").format(title=title),
+            ft.Column([C.body(C.HELP["move_game"]), group], spacing=T.S3, tight=True), size="s",
+            actions=[C.ghost(tr("Cancel"), on_click=lambda e: self.page.pop_dialog()), go]))
+        self.run_bg(fill)
+
    def build_game(self, pkg: str) -> Job:
        def run(job: Job):
            info = pipeline.build_game(pkg, job.reporter)
@@ -1952,6 +2114,7 @@ class FramePortApp:
    def _startup(self):
        from ..frame.connection import parse_target, saved_targets

+        self.run_bg(self._analysis_refresh)
        self._art_backfill()
        saved = saved_targets()
        if saved:
@@ -1963,6 +2126,18 @@ class FramePortApp:
            self.connect(parse_target(f"{f.user}@{f.host}"), quiet=True)
            break

+    def _analysis_refresh(self) -> None:
+        """Games analysed by an older FramePort lack fields newer fixes depend on (GitHub #104): their APKs are read
+        again once, in the background. Not a job: ~8 s per large APK, and the queue would hold the user's installs
+        for minutes (a build of such a game analyses it first itself). Recipes the user didn't edit then follow."""
+        if not pipeline.outdated_analyses():
+            return
+        n = pipeline.refresh_analyses()
+        if n:
+            self.refresh_view()
+            self.toast(tr_n("{n} game was analyzed again for new fixes", "{n} games were analyzed again for new fixes",
+                            n))
+
    def _art_backfill(self) -> None:
        """Rift games added before automatic artwork (or while offline): fetch it once in the background."""
        from ..artwork import sources
@@ -2425,22 +2600,38 @@ def assets_dir() -> str:
    return str(user_data_dir())


+FLET_LOCK = threading.RLock()  # held while a patch is computed and packed, and while a control property is set
+
+
 def serialize_flet_updates() -> None:
-    """Send page updates one at a time. Flet 1.0 diffs and sends a control's patch without a lock, and FramePort
-    updates the page from several threads (jobs, connection checks, the library loader, dialogs): two patches computed
-    at once desynchronised the window ("dropped a patch for unknown control … needs a reload"), e.g. a dialog shown
-    while a finished scan redrew the view never closed again."""
+    """Send page updates one at a time, and keep property writes out of a patch being packed.
+
+    Flet 1.0 diffs and sends a control's patch without a lock, and FramePort updates the page from several threads
+    (jobs, connection checks, the library loader, the monitor stream, dialogs):
+    - two patches computed at once desynchronised the window ("dropped a patch for unknown control … needs a
+      reload"), e.g. a dialog shown while a finished scan redrew the view never closed again;
+    - a property set on a background thread while the event loop packed a patch changed the control's `_values`
+      dict mid-iteration ("dictionary changed size during iteration"): the handler that was updating (a sidebar
+      click while the live Frame card took a sample) died and the page didn't change.
+    Both take one re-entrant lock: re-entrant because did_mount() may update again and the loop's own handlers set
+    properties during a patch."""
+    from flet.controls.value_types import Prop
    from flet.messaging.session import Session

    if getattr(Session.patch_control, "_serialized", False):
        return
-    original, lock = Session.patch_control, threading.RLock()  # re-entrant: did_mount() may update again
+    original_patch, original_set = Session.patch_control, Prop.__set__

    def patch_control(self, *args, **kwargs):
-        with lock:
-            return original(self, *args, **kwargs)
+        with FLET_LOCK:
+            return original_patch(self, *args, **kwargs)
+
+    def set_prop(self, obj, value):
+        with FLET_LOCK:
+            original_set(self, obj, value)
    patch_control._serialized = True
    Session.patch_control = patch_control
+    Prop.__set__ = set_prop


 def main(argv=None):
@@ -41,6 +41,22 @@ def _deployment(game: dict, frame_info: dict | None) -> dict | None:
    return next((d for d in (frame_info or {}).get("installed", []) if d.get("package") == game.get("package")), None)


+def frame_drive(game: dict, frame_info: dict | None) -> dict | None:
+    """The drive the game is installed on ({internal, path, label, missing}), None if not installed / old agent."""
+    from ..install.drives import game_drive
+
+    return game_drive(_deployment(game, frame_info))
+
+
+def drive_note(drive: dict | None) -> str:
+    """" · on SD Card" / " · SD Card not inserted" for a game on another drive, "" on internal storage."""
+    if not drive or drive.get("internal"):
+        return ""
+    if drive.get("missing"):
+        return tr(" · {label} not inserted").format(label=drive.get("label") or tr("its drive"))
+    return tr(" · on {label}").format(label=drive.get("label") or "")
+
+
 def settings_diff(game: dict, frame_info: dict | None) -> tuple[list[str], list[str]] | None:
    """(patches turned on, patches turned off) in the app since the Frame's copy was installed; None if the same (or
    unknown: installs from before FramePort recorded their recipe)."""
@@ -99,7 +115,9 @@ def install_state(game: dict, frame_info: dict | None) -> str | None:
    if frame_info is None:
        return None
    dep = _deployment(game, frame_info)
-    if not dep or dep.get("apk_present") is False:  # no record, or the game files are gone (half uninstalled)
+    # no record, or the game files are gone (half uninstalled); a game on a microSD card that isn't inserted now is
+    # still installed (GitHub #90)
+    if not dep or (dep.get("apk_present") is False and not dep.get("drive_missing")):
        return "missing"
    b = game.get("build") or {}
    built = {b.get("sha256"), b.get("alt_sha256")} - {None}
@@ -330,7 +348,8 @@ def primary(label: str, icon: str | None = None, on_click: Callable | None = Non
            tooltip: str | None = None, big: bool = False) -> ft.FilledButton:
    padding = (ft.Padding(T.px(22), T.px(18), T.px(22), T.px(18)) if big
               else ft.Padding(T.px(16), T.px(12), T.px(16), T.px(12)))
-    return ft.FilledButton(label, icon=_btn_icon(icon, T.ON_ACCENT, disabled), on_click=on_click, disabled=disabled,
+    return ft.FilledButton(label, icon=_btn_icon(glyphs.solid(icon), T.ON_ACCENT, disabled), on_click=on_click,
+                           disabled=disabled,
                           tooltip=tooltip,
                           style=ft.ButtonStyle(shape=_shape(), bgcolor={ft.ControlState.DEFAULT: T.ACCENT,
                                                                        ft.ControlState.DISABLED: T.SURFACE_3},
@@ -555,8 +574,11 @@ def callout(text: str | ft.Control, kind: str = "info", icon: str | None = None)
                    "error": ft.Icons.ERROR_OUTLINE_ROUNDED, "ok": ft.Icons.CHECK_CIRCLE_OUTLINE_ROUNDED,
                    "pc": G.PC}[kind]
    content = body(text, T.TEXT) if isinstance(text, str) else text
+    # a bar (text + buttons in one Row) is taller than a line of text: centre the icon on it; text that wraps keeps
+    # the icon at its first line
+    align = ft.CrossAxisAlignment.CENTER if isinstance(content, ft.Row) else ft.CrossAxisAlignment.START
    return ft.Container(ft.Row([as_icon(icon, T.px(18), color), ft.Container(content, expand=True)],
-                               spacing=T.S3, vertical_alignment=ft.CrossAxisAlignment.START),
+                               spacing=T.S3, vertical_alignment=align),
                        bgcolor=T.soft(color, 0.08), border=ft.Border.all(1, T.soft(color, 0.35)),
                        border_radius=T.RADIUS_SM, padding=ft.Padding(T.px(14), T.px(12), T.px(14), T.px(12)))

@@ -581,22 +603,70 @@ def portal_scene(icon: str, height: float | None = None) -> ft.Control:
        gradient=ft.RadialGradient(colors=[T.soft(T.ACCENT, 0.13), T.soft(T.ACCENT, 0.0)], radius=0.5))


-def empty_state(icon: str, heading: str, text: str, *actions: ft.Control) -> ft.Container:
+def feature_card(icon: str, heading: str, text: str) -> ft.Container:
+    """One thing a screen does, for empty states and tips: a tinted round icon, a short heading, one sentence."""
+    tint = T.SECONDARY if T.DUAL else T.ACCENT
    return ft.Container(ft.Column([
-        portal_scene(icon),
+        ft.Container(as_icon(icon, T.px(20), tint), width=T.px(40), height=T.px(40), border_radius=T.px(20),
+                     bgcolor=T.soft(tint, 0.13), alignment=ft.Alignment.CENTER),
+        ft.Text(heading, size=T.px(14), weight=ft.FontWeight.W_600, color=T.TEXT),
+        body(text, T.TEXT_2),
+    ], spacing=T.S2, tight=True), width=T.px(236), padding=T.S4, bgcolor=T.soft(T.SURFACE, 0.75),
+        border=ft.Border.all(1, T.BORDER), border_radius=T.RADIUS)
+
+
+def feature_row(features: list[tuple[str, str, str]]) -> ft.Row:
+    """feature_card()s side by side, wrapping on narrow windows."""
+    return ft.Row([feature_card(*f) for f in features], wrap=True, spacing=T.S3, run_spacing=T.S3,
+                  alignment=ft.MainAxisAlignment.CENTER, vertical_alignment=ft.CrossAxisAlignment.START)
+
+
+def portal_glow() -> ft.RadialGradient:
+    """The faint light behind an empty state: the portal's blue and orange (the accent alone in single themes)."""
+    if T.DUAL:
+        colors, stops = [T.soft(T.SECONDARY, 0.10), T.soft(T.ACCENT, 0.05), T.soft(T.BG, 0.0)], [0.0, 0.45, 1.0]
+    else:
+        colors, stops = [T.soft(T.ACCENT, 0.09), T.soft(T.BG, 0.0)], [0.0, 1.0]
+    return ft.RadialGradient(colors=colors, stops=stops, center=ft.Alignment(0, -0.25), radius=0.85)
+
+
+def empty_state(icon: str, heading: str, text: str, *actions: ft.Control,
+                features: list[tuple[str, str, str]] | None = None) -> ft.Container:
+    """A screen with nothing to show yet: the portal with what the screen is about coming out of it, a heading, one
+    sentence and the action that fills it. `features` (icon, heading, sentence) say what the screen will show, so a
+    first look isn't an empty page; with them the portal is bigger and a soft portal light fills the background."""
+    rich = bool(features)
+    return ft.Container(ft.Column([
+        portal_scene(icon, T.px(104) if rich else None),
        ft.Container(height=T.S2),
        title(heading, T.T_DISPLAY),
-        ft.Container(body(text, text_align=ft.TextAlign.CENTER), width=T.px(460)),
+        ft.Container(body(text, text_align=ft.TextAlign.CENTER), width=T.px(500)),
        ft.Container(height=T.S2),
        ft.Row(list(actions), alignment=ft.MainAxisAlignment.CENTER, spacing=T.S3),
-    ], horizontal_alignment=ft.CrossAxisAlignment.CENTER, spacing=T.S2, tight=True),
-        alignment=ft.Alignment.CENTER, expand=True)
+        *([ft.Container(height=T.S6), ft.Container(feature_row(features), width=T.px(780))] if rich else []),
+    ], horizontal_alignment=ft.CrossAxisAlignment.CENTER, spacing=T.S2, tight=not rich,
+        # rich: scrolls in small windows, centred otherwise (a scrolling Column takes the full height, so the
+        # Container's alignment no longer centres it)
+        scroll=ft.ScrollMode.AUTO if rich else None, expand=rich,
+        alignment=ft.MainAxisAlignment.CENTER if rich else ft.MainAxisAlignment.START),
+        alignment=ft.Alignment.CENTER, expand=True, gradient=portal_glow() if rich else None,
+        border_radius=T.RADIUS)


 def kv(label: str, value: str | ft.Control, help: str | None = None) -> ft.Row:
+    """A label and its value; a control as the value (a link, a button) sits on the left like text does."""
    return ft.Row([ft.Container(with_help(meta(label), help), width=T.px(130)),
                   ft.Container(value if isinstance(value, ft.Control) else body(value, T.TEXT, selectable=True),
-                                expand=True)], vertical_alignment=ft.CrossAxisAlignment.START)
+                                expand=True, alignment=ft.Alignment.CENTER_LEFT)],
+                  vertical_alignment=ft.CrossAxisAlignment.START)
+
+
+def link(label: str, url: str) -> ft.TextButton:
+    """A web link in running content: the accent colour, an "opens outside" icon, no indent on the left (it lines
+    up with the text around it)."""
+    return ft.TextButton(label, icon=ft.Icons.OPEN_IN_NEW_ROUNDED, icon_color=T.ACCENT, url=url,
+                         style=ft.ButtonStyle(shape=_shape(), color=T.ACCENT,
+                                              padding=ft.Padding(0, T.px(4), T.px(8), T.px(4))))


 class Check(NamedTuple):
@@ -670,6 +740,132 @@ def bottom_fade(height: int | None = None, strength: float = 0.85) -> ft.Contain
                                                   colors=[ft.Colors.TRANSPARENT, T.soft("#000000", strength)]))


+class CoverButton:
+    """The round button on a cover (Library cards, the On your Frame shelf): frosted glass with a thin light ring that
+    springs in while the card is hovered (`show`) and fills with the accent under the pointer. A Play button
+    (`launch` = the "Starting on …" text) launches with two portal rings rippling out of it, blue then orange, and
+    swaps itself for a "Starting on Frame…" pill for STARTING_S seconds. `.control` goes where the button sits (in the
+    card's hover layer); `.status` (the pill) goes in the card's Stack outside that layer, so it stays when the pointer
+    leaves. Only properties change (no controls are created after construction)."""
+
+    STARTING_S = 8
+
+    def __init__(self, icon: str, tooltip: str, on_click: Callable, size: float, launch: str | None = None,
+                 reduce_motion: bool = False):
+        self.on_click, self.launch, self.reduce = on_click, launch, reduce_motion
+        self.hovered = self.starting = False
+        motion = (lambda ms, curve=ft.AnimationCurve.EASE_OUT: None if reduce_motion else ft.Animation(ms, curve))
+        # (Material's play arrow is already drawn right of its box's centre for optical balance: no extra nudge — an
+        # extra one put the triangle visibly off centre)
+        self.icon = ft.Icon(icon, size=size * 0.52, color="#FFFFFF")
+        self.circle = ft.Container(
+            self.icon,
+            width=size, height=size, border_radius=size / 2, alignment=ft.Alignment.CENTER,
+            bgcolor=T.soft("#0B0C10", 0.45), border=ft.Border.all(1.5, T.soft("#FFFFFF", 0.6)),
+            blur=ft.Blur(10, 10), shadow=self._shadow(False),
+            animate=motion(180), scale=0.72, animate_scale=motion(320, ft.AnimationCurve.EASE_OUT_BACK),
+            tooltip=ft.Tooltip(message=tooltip, wait_duration=800), on_hover=self._hover_button, on_click=self._click)
+        self.rings = [ft.Container(width=size, height=size, border_radius=size / 2,
+                                   border=ft.Border.all(2.5, color), opacity=0, scale=1,
+                                   animate_opacity=ft.Animation(90), animate_scale=ft.Animation(1))
+                      for color in (T.SECONDARY if T.DUAL else T.ACCENT, T.ACCENT)]
+        self.control = ft.Stack([*self.rings, self.circle], width=size, height=size, alignment=ft.Alignment.CENTER,
+                                clip_behavior=ft.ClipBehavior.NONE)
+        self.label = ft.Text(launch or "", size=T.px(12), weight=ft.FontWeight.W_600, color="#FFFFFF")
+        self.status = ft.Container(
+            ft.Container(ft.Row([spinner("s", "#FFFFFF"), self.label], spacing=T.S2, tight=True),
+                         bgcolor=T.soft("#0B0C10", 0.6), border=ft.Border.all(1, T.soft(T.ACCENT, 0.7)),
+                         border_radius=T.px(999), blur=ft.Blur(10, 10),
+                         padding=ft.Padding(T.px(12), T.px(7), T.px(14), T.px(7))),
+            alignment=ft.Alignment.CENTER, opacity=0, animate_opacity=motion(220), visible=False)
+
+    @staticmethod
+    def _shadow(hot: bool):
+        if hot:  # the accent glows under the pointer
+            return [ft.BoxShadow(blur_radius=26, spread_radius=1, color=T.soft(T.ACCENT, 0.55)),
+                    ft.BoxShadow(blur_radius=18, color=T.soft("#000000", 0.5), offset=ft.Offset(0, 6))]
+        return ft.BoxShadow(blur_radius=22, color=T.soft("#000000", 0.55), offset=ft.Offset(0, 6))
+
+    def _paint(self, hot: bool) -> None:
+        c = self.circle
+        c.bgcolor = T.ACCENT if hot else T.soft("#0B0C10", 0.45)
+        c.border = ft.Border.all(1.5, T.ACCENT if hot else T.soft("#FFFFFF", 0.6))
+        c.shadow = self._shadow(hot)
+        self.icon.color = T.ON_ACCENT if hot else "#FFFFFF"
+
+    def show(self, on: bool) -> None:
+        """The card is (not) hovered: spring in / shrink back (the card fades its hover layer itself)."""
+        self.hovered = on
+        self.circle.scale = 0 if self.starting else (1.0 if on else 0.72)
+        if not on:
+            self._paint(False)
+
+    def _hover_button(self, e) -> None:
+        hot = e.data in (True, "true") and not self.starting
+        self._paint(hot)
+        self.circle.scale = 0 if self.starting else (1.08 if hot else 1.0)
+        update(self.circle)
+
+    def _click(self, e) -> None:
+        if self.starting:
+            return
+        self.on_click(e)
+        try:
+            page = e.control.page
+        except Exception:  # noqa: BLE001 - unmounted meanwhile (Flet 1.0 raises): no animation then
+            page = None
+        if page is not None:
+            page.run_task(self._launch if self.launch else self._pop)
+
+    async def _pop(self) -> None:
+        import asyncio
+
+        self.circle.scale = 0.9
+        update(self.circle)
+        await asyncio.sleep(0.12)
+        self.circle.scale = 1.0 if self.hovered else 0.72
+        update(self.circle)
+
+    async def _launch(self) -> None:
+        """Rings out (blue, then orange), the button shrinks away, "Starting on …" for STARTING_S seconds."""
+        import asyncio
+
+        self.starting = True
+        self._paint(False)
+        self.circle.scale = 0
+        self.status.visible = True
+        if self.reduce:
+            self.status.opacity = 1
+        else:
+            for r in self.rings:
+                r.opacity = 0.9
+        update(self.control, self.status)
+        if not self.reduce:
+            await asyncio.sleep(0.09)
+            for i, r in enumerate(self.rings):
+                r.animate_scale = ft.Animation(720, ft.AnimationCurve.EASE_OUT)
+                r.animate_opacity = ft.Animation(720, ft.AnimationCurve.EASE_IN)
+                r.scale, r.opacity = 2.5, 0
+                update(r)
+                if i == 0:
+                    await asyncio.sleep(0.16)
+            await asyncio.sleep(0.2)  # the button is gone, the rings are out: then the pill
+            self.status.opacity = 1
+            update(self.status)
+            await asyncio.sleep(0.6)
+            for r in self.rings:  # back in place, unseen
+                r.animate_scale, r.animate_opacity, r.scale = ft.Animation(1), ft.Animation(90), 1
+            update(*self.rings)
+        await asyncio.sleep(self.STARTING_S)
+        self.starting = False
+        self.status.opacity = 0
+        self.circle.scale = 1.0 if self.hovered else 0.72
+        update(self.status, self.circle)
+        await asyncio.sleep(0.25)
+        self.status.visible = False
+        update(self.status)
+
+
 DIALOG_TITLE_SIZE = 20  # px at 100 %


@@ -910,6 +1106,25 @@ class Sparkline:
        self.line.paint.color = color
        self.area.paint.color = T.soft(color, 0.16)

+    def portal(self, on: bool) -> None:
+        """The line and its fill in the portal's blue → orange, or back to set_color's colour (the Monitor's
+        perfect-pacing easter egg)."""
+        if on == getattr(self, "_portal", False):
+            return
+        self._portal = on
+        self.line.paint.stroke_width = T.px(2.4 if on else 1.6)
+        self._paint_portal()
+
+    def _paint_portal(self) -> None:
+        if getattr(self, "_portal", False) and self.width > 0:
+            x0, x1 = getattr(self, "_span", (0.0, self.width))  # the drawn line's extent: blue at its start
+            grad = lambda o: ft.PaintLinearGradient(  # noqa: E731
+                begin=ft.Offset(x0, 0), end=ft.Offset(max(x1, x0 + 1), 0),
+                colors=[T.soft(T.SECONDARY, o), T.soft(T.ACCENT, o)])
+            self.line.paint.gradient, self.area.paint.gradient = grad(1.0), grad(0.38)
+        else:
+            self.line.paint.gradient = self.area.paint.gradient = None
+
    def set(self, values: list, hi: float | None = None, target: float | None = None) -> None:
        """New values (oldest first); hi overrides the top of the scale; target draws a dashed guide (e.g. 72 fps)."""
        self.values, self.target = list(values)[-self.slots:], target
@@ -936,11 +1151,15 @@ class Sparkline:
            area += [cv.Path.MoveTo(run[0][0], h), *[cv.Path.LineTo(x, y) for x, y in run],
                     cv.Path.LineTo(run[-1][0], h), cv.Path.Close()]
        self.line.elements, self.area.elements = line, area
+        if runs:
+            self._span = (runs[0][0][0], runs[-1][-1][0])
        guide = []
        if self.target is not None and w > 0:
            y = spark_points([self.target, self.target], w, h, lo, hi)[0][0][1]
            guide = [cv.Path.MoveTo(0, y), cv.Path.LineTo(w, y)]
        self.guide.elements = guide
+        if getattr(self, "_portal", False):
+            self._paint_portal()  # (the gradient spans the chart's current width)


 def _darker(color: str, factor: float = 0.6) -> str:
@@ -997,7 +1216,12 @@ class Transit:
        self.cover = ft.Container(left=0, top=(self.track_h - self.cover_s) / 2, width=self.cover_s,
                                  height=self.cover_s, border_radius=T.px(4), bgcolor=T.SURFACE_3,
                                  border=ft.Border.all(1, T.BORDER_STRONG), alignment=ft.Alignment.CENTER,
-                                  clip_behavior=ft.ClipBehavior.ANTI_ALIAS, animate_position=anim)
+                                  clip_behavior=ft.ClipBehavior.ANTI_ALIAS, animate_position=anim,
+                                  offset=ft.Offset(0, 0), rotate=0,
+                                  animate_offset=ft.Animation(240, ft.AnimationCurve.EASE_OUT),
+                                  animate_rotation=ft.Animation(240, ft.AnimationCurve.EASE_OUT))
+        self._upload_since: float | None = None  # (easter egg: on long uploads the cover hops now and then)
+        self._last_hop = 0.0
        # the portal in two layers around the cover, so the cover goes through it: the back (shadow, hole, the rim's
        # PC/blue half) under the cover, the rim's Frame/orange half over it. Same viewBox: they line up exactly; the
        # pictures are a bit larger than the ring (its shadow reaches a little below the track)
@@ -1106,6 +1330,39 @@ class Transit:
                2, (T.ERROR if s.failed else T.WARN if s.waiting else T.ACCENT) if current
                else (T.SECONDARY if T.DUAL else T.ACCENT) if finished else T.SURFACE_3))
        self._place()
+        self._maybe_hop(s.label == "upload" and not s.waiting and not s.failed)
+
+    def _maybe_hop(self, uploading: bool) -> None:
+        """An upload running longer than easter.HOP_AFTER: the cover does a little hop every easter.HOP_EVERY
+        seconds (an easter egg; the settings are read only when a hop is due)."""
+        import time
+
+        if not uploading:
+            self._upload_since = None
+            return
+        now = time.monotonic()
+        if self._upload_since is None:
+            self._upload_since = self._last_hop = now
+            return
+        from . import easter
+
+        if now - self._upload_since < easter.HOP_AFTER or now - self._last_hop < easter.HOP_EVERY:
+            return
+        self._last_hop = now
+        from ..core import library
+
+        if not easter.enabled() or library.setting("ui.reduce_motion", False):
+            return
+        cover = self.cover
+
+        def hop():
+            for dy, turn, hold in ((-0.6, -0.17, 0.21), (0, 0.06, 0.21), (-0.22, 0.0, 0.17), (0, 0, 0.21)):
+                cover.offset, cover.rotate = ft.Offset(0, dy), turn
+                update(cover)
+                time.sleep(hold)
+        import threading
+
+        threading.Thread(target=hop, daemon=True).start()


 class MeterBar: