catalog: com.resolutiongames.abvriop.santacruz (from #46 )

Dashboard worker (agent v53) leaves a dashboard the player opened with the controller alone (v52 closed it 60 ms after each press, the game stayed paused); Into The Radius 2: focus_hold up to 2.5 s (the Frame dropped focus for 0.4 s and 1.0 s and Unreal paused each time), notes from the headset test
Dashboard at game start (agent v52): watch from the game's first submitted frame instead of the first pacing summary, which came ~8 s after Steam's "Resume game" menu (seen with Into The Radius 2); incremental log reads, 0.5 s checks
2026-10-06 18:00:43 +02:00 · 2026-10-05 21:57:44 +00:00 · 2026-10-05 15:58:50 -04:00 · 2026-10-05 15:46:54 -04:00 · 2026-10-05 15:43:06 -04:00 · 2026-10-05 14:55:23 -04:00
95 changed files with 8188 additions and 154 deletions
@@ -5,6 +5,15 @@ on:
    tags: ["v*"]
  pull_request:
  workflow_dispatch:
+    inputs:
+      dev:
+        description: "Publish the bundles as the dev build (testers: Settings → Updates → Install the latest dev build)"
+        type: boolean
+        default: true
+      notes:
+        description: "What testers should try (shown before they install it)"
+        type: string
+        default: ""

 jobs:
  test:
@@ -50,6 +59,9 @@ jobs:
        if: runner.os == 'Linux'
        run: sudo apt-get update && sudo apt-get install -y ninja-build libgtk-3-dev
      - run: uv sync --extra dev
+      - name: Dev build version (next patch + .dev<run number>; not committed)
+        if: github.event_name == 'workflow_dispatch' && inputs.dev
+        run: uv run --no-project python scripts/dev_version.py ${{ github.run_number }}
      - id: flet
        run: uv run python scripts/package.py
        continue-on-error: ${{ runner.os == 'macOS' || runner.arch == 'ARM64' }}
@@ -148,3 +160,43 @@ jobs:
            echo; cat packaging/release-footer.md; } > "$notes"  # short: the update dialog shows these notes
          gh release delete "$tag" --yes 2>/dev/null || true
          gh release create "$tag" out/* packaging/FramePort-selfsigned.cer --title "FramePort ${tag}" --notes-file "$notes"
+
+  dev-release:
+    # "Run workflow" with dev ticked: replaces the rolling `dev` pre-release (never shown by the automatic update check;
+    # testers install it from Settings → Updates). Same assets + SHA256SUMS as a release.
+    if: github.event_name == 'workflow_dispatch' && inputs.dev
+    needs: bundle
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v10.2.0
+      - id: version
+        run: echo "version=$(uv run --no-project python scripts/dev_version.py ${{ github.run_number }})" >> "$GITHUB_OUTPUT"
+      - uses: actions/download-artifact@v8
+        with:
+          path: out
+          merge-multiple: true
+      - name: Wheel
+        run: uv build --wheel -o out && ls out
+      - name: Checksums
+        run: cd out && sha256sum * > SHA256SUMS.txt && cat SHA256SUMS.txt
+      - name: Publish the dev build
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.version.outputs.version }}
+          NOTES: ${{ inputs.notes }}
+        run: |
+          notes=$(mktemp)
+          last=$(git describe --tags --abbrev=0 --match 'v*' 2>/dev/null || true)
+          { echo "Dev build **${VERSION}** from commit ${GITHUB_SHA::7} ($(date -u +%Y-%m-%d)). For testing fixes before"
+            echo "the next release; you get that release as a normal update."; echo
+            if [ -n "$NOTES" ]; then echo "## Please test"; echo; echo "$NOTES"; echo; fi
+            if [ -n "$last" ]; then echo "## Changes since ${last}"; echo
+              git log --no-merges --format='- %s' "${last}..HEAD" | cut -c1-160 | head -40; fi; } > "$notes"
+          gh release delete dev --yes --cleanup-tag 2>/dev/null || true
+          gh release create dev out/* packaging/FramePort-selfsigned.cer --prerelease --target "$GITHUB_SHA" \
+            --title "FramePort dev build ${VERSION}" --notes-file "$notes"
@@ -19,3 +19,4 @@ CLAUDE.local.md
 # outputs of `frameport report` / `parity` / ruff
 REPORT.md
 .ruff_cache/
+.claude/worktrees/
@@ -21,7 +21,19 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
    the "Send files" dialog, game menu → "Add videos & files…" = `go("files", pkg)`; multi-select bar (download/
    delete); drag-and-drop from the OS via the `flet-dropzone` extension (Apache-2.0, Flutter `desktop_drop`), which
    only a `flet build` bundle contains: `files.dropzone_available()` keeps it out of source runs and the PyInstaller
-    fallback, which would show an unknown control); settings; welcome; activity panel).
+    fallback, which would show an unknown control); screenshots (Steam screenshots on the Frame, `install/screenshots.py`
+    + agent v46 `list_screenshots`/`delete_screenshots`: the Frame files every headset shot under SteamVR 250820, so
+    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)`); settings; welcome; activity panel). Files, Screenshots and the Library share right-click menus
+    (one `ft.ContextMenu` per view, filled on right-click; on one of several selected items they act on the whole
+    selection, `C.menu_targets`) and click-and-drag multi-select (`C.DragSelect`: pan start/end on the area + item
+    hover events, which Flutter also sends with the button held; Flet can't report item positions, so no rubber band).
+    Selection bars sit below the list: above it, their appearing shifted the items mid-drag. Async handlers (they
+    await a FilePicker) must be coroutine functions or go through `page.run_task`: Flet doesn't await a lambda's
+    coroutine (the Files row Download button silently did nothing). `ui_smoke.py --fake-frame --gestures` drives real
+    mouse drags/right-clicks.
    User tags live in library entries (`tags`), filters in library setting `ui.library`.
    **Performance rules** (the app froze before): never put image bytes in controls — artwork is served by URL from the
    GUI assets dir (= user data dir; `ft.run(assets_dir=…)`), as thumbnails (`artwork/thumbs.py`, Pillow); the
@@ -76,6 +88,11 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
    auto-start SteamVR on Play (`winhost.start_steamvr`); the Frame launcher always uses `/openxr`. UI (`game.py`
    where()) states per-game where it runs; installing an Oculus game on the Frame shows a warning. Migration
    `rift_frame_native` re-analyzes + re-derives existing entries.
+  - Own artwork (0.8.0): game menu → "Use your own artwork…" (also from the Find artwork dialog) =
+    `views/art_dialog.show_custom_art_dialog`: one slot per kind (portrait/landscape/hero/logo/icon), FilePicker →
+    `sources.apply_custom` (Pillow check, ≥64 px, ≤40 MB, scaled to ≤3840 px, PNG if alpha/logo/icon else JPEG,
+    replaces only that kind + its thumbnails, drops the generated cover/banner, writes `.picked` = "custom") /
+    `remove_custom`; Steam shapes are still composed from what exists (`steam.py` PREFER).
  - Art for Rift games: `artwork/sources.py` — Quest version package (OculusDB packageName, exact name or +
    "Unplugged"-type suffix, never sequels) → Meta art; OculusDB square cover; Steam (exact names only); exe icon.
  - Store details (`artwork/details.py`, entry `details`): OculusDB (description, genres, publisher, website; by Quest
@@ -86,6 +103,11 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
    set: the name on a colour from the title hash + the APK icon, `steam_set_for`; 2D Android apps get no store lookups) and tags: how it runs, the original platform
    (Meta Quest / Oculus Rift), genres, user tags — merged with tags set in Steam (non-Steam shortcuts can't hold a
    description).
+  - Linux apps (GitHub #31, library kind `linux`, `linux.<slug>`): GUI = Add games → "Add a Linux app (arm64)…" /
+    "…folder…" (`app.add_linux` job → `pipeline.add_linux_app`); game page `linux_summary` (program + Change…, AppImage,
+    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.
  - 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
@@ -147,7 +169,7 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
 - `agent/frameport_agent.py` — runs **on the Frame** (python3 stdlib only), JSON over SSH. Owns the install layout,
  launch.sh template, Steam shortcuts (binary VDF), launch tests. Bump `AGENT_VERSION` when changing it.
 - `bootstrap/bootstrap.sh` — one-time Frame setup served by the pairing server (sshd, app key, avahi service, Lepton).
- `catalog/games/<package>.yaml` — 38 recipes (34 verified 2026-09-28; Deadpool VR, 4XVR, NEX Player and AC Nexus's
+- `catalog/games/<package>.yaml` (installed apps also fetch these from GitHub `main`, see "Catalog updates") — 38 recipes (34 verified 2026-09-28; Deadpool VR, 4XVR, NEX Player and AC Nexus's
  90 Hz default confirmed later by the owner); `catalog/triage.yaml` — log signatures → fixes.
 - `native/` — sources of the prebuilt binaries in `artifacts/` (adapter, VrApi bridge patches, GL shim, stubs).
  `native/build.py` rebuilds them with NDK r27c (downloaded on demand into `native/.cache`, git-ignored; uses
@@ -477,9 +499,36 @@ game runs (agent v37). New default fixes in FramePort's code reach games already
 `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
 (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
+swapchain is returned, the game gets a Surface from a SurfaceTexture on a worker thread (own EGL context, JavaVM from
+XrInstanceCreateInfoAndroidKHR), frames are read back (glReadPixels) and uploaded in xrEndFrame (Vulkan: own command
+buffer + fence per panel, never waits; GLES: glTexSubImage2D). I Am Monkey's intro works (owner-confirmed). SUPERHOT
+(Quest) quit at start: its cloud save folder was mode 1700 and Lepton's app writes through the folder's group →
+launch.sh `fix_perms` adds u+rwx,g+rwx (agent v41). Lucky's Tale: Unity's Loading.PreloadManager thread grows the
+native heap ~1 GB/s until the OOM killer (Frame freezes); no fix. `perf` works as steamos (paranoid 2; ptrace_scope 1
+blocks gdb/eu-stack/debuggerd) — see PLAYBOOK "Debugging techniques". QuestCraft downloads its JRE at first run into
+`files/runtimes/JRE` (Pojlib Installer); on the Frame it was missing (unpacked by hand, unverified). WiiCompiled: its launcher shows
+(lepton-show-flatscreen) but imports .wcgame files through Android's document picker (OPEN_DOCUMENT), which Lepton
+lacks (ActivityNotFoundException) → imported by hand: libmain.so + game.json → internal files/game/<profile>,
+DATA/ → external files/WiiCompiledOpenXRVR/DATA, MOD/ → .../RetroRewind6 (decompiled with jadx). Lepton has no
+picker at all: a FramePort fix would be an injected picker activity. Generated cover/banner art used to suppress the
+Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
+**Steam library failures (GitHub #21/#30):** on some Frames Steam never loads FramePort's shortcuts.vdf entries (same SteamOS build and arm64 beta client as the dev Frame; IDs correct; file written before Steam starts): Play → console_log `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` (= "Game configuration unavailable", Steam treats the id as a store app). Cause unknown; agent v42/43 diagnostics: `launch` returns `steam` (started / error + code / silent from console_log), `collect_diag` adds `steam_library` (real Steam dir, beta, Steam start vs vdf write time, entries per account, devkit games) + `steam-console.txt` (incl. Steam's `logs/shortcuts.previous.txt` if present; steamclient.so has "LoadShortcuts: rejecting attempt to load shortcuts: invalid account ID"). **Fallback (agent v43):** when Play gets AppError_9 the agent registers the game through Steam's devkit interface (what Valve's Devkit Management Tool does, MIT: `devkit-1 steam://devkit-1/<~/.steam/steam.token>/create-shortcut?response=<file>&gameid=<id>&directory=~/devkit-game` written to ~/.steam/steam.pipe; answer file / `.error`; `~/devkit-game/<id>/launch.sh` = link to the game's launch.sh, `<id>-argv.json` ["launch.sh"] (relative to the folder), `<id>-settings.json` {steam_play 0, compat_tool ""}). Steam adds it live (no restart), picks its own appid (read back from shortcuts.vdf by DevkitGameID), shows it as a normal non-Steam game named "Devkit Game: <id>" (OpenVR 0, but VR works: owner-verified 2026-10-04), art copied to grid/<appid>*. Ids: letter first, then letters/digits/_ only (spaces, '-', leading digit → "missing/invalid arguments"). Later Plays use the devkit entry; uninstall (`devkit_unregister`, `delete-shortcut` live) and purge remove it. Verified on the dev Frame: register/launch/unregister; the AppError_9 trigger itself only in unit tests.
+**Exit game (GitHub #36, 2026-10-04):** `Apps.TerminateApp` (what Exit game calls; reachable for tests through Steam's CEF devtools on 127.0.0.1:8080, SharedJSContext, `Runtime.evaluate` — a stdlib websocket client is enough) closed both a normal shortcut and a devkit entry on the dev Frame within 1-3 s. SIGTERM to Steam's `reaper` alone left launch.sh + Lepton (setsid) + the container running (an earlier headset launch ran on for 87 min); SIGTERM to launch.sh cleans up in ~4 s. Agent v44: launch.sh's 2 s loop ends the game when its parent (the reaper) is gone; `upgrade_launchers` (from ensure_host_fixes) adds that to existing launchers in place. Which in-headset exit path fails is still unknown. Screenshots on the Frame: all under SteamVR's appid 250820 (`760/remote/250820/screenshots`, screenshots.vdf has creation time, no game).
+**SteamVR dashboard at game start (2026-10-04):** the dashboard (Resume game / controller / VR options) was open whenever a FramePort game started (also over Lepton's 2D launcher). Steam's UI exposes `SteamClient.OpenVR.VROverlay.{IsDashboardVisible,HideDashboard,ShowDashboard}` (CEF devtools, `steam_js` in the agent). Agent v44: launch.sh starts `_dashboard_worker` (waits for FrameBridge's first `pacing:` line in launch.log, then hides a visible dashboard for 25 s, at most 3 times; log `<base>/dashboard.log`; opt out with env FRAMEPORT_KEEP_DASHBOARD=1). Verified on the dev Frame (dashboard shown → 4XVR launched via Steam → hidden ~5 s after the first frames); not yet seen in the headset. **Headset (ITR2, 2026-10-05): too late** — Steam shows its frame menu (`valve.steam.gamepadui.frame.menu`, vrwebhelper_systemui.txt `[PooledPopups] Showing`) ~0.3 s after the game's first submitted frame (FrameBridge `new layer:`), but the first `pacing:` summary comes ~8 s later; the owner had pressed Resume (`[HideDashboard] return_to_game`) before the worker looked. Agent v52: watches from the first `new layer:` line (incremental log reads, 0.5 s polls, 30 s window). Agent v53: stops for good once the player opens the dashboard with the controller (`toggle_dashboard_action` in vrwebhelper_systemui.txt since the worker started): v52 closed it 60 ms after each press, and the game, paused for it, stayed paused.
+**Space warp / ITR2 (2026-10-04):** Into The Radius 2 (UE5, `libUnreal.so` + OVRPlugin, Vulkan) uses Application SpaceWarp (extra swapchains `376x376 format=97` motion vectors + `format=129` depth); #35 reports flickering textures. OVRPort's `patch_disable_space_warp` has no effect on UE5, and hiding XR_FB_space_warp in FrameBridge's enumerate doesn't reach the game either: **OVRPort's dispatcher offers/enables XR_FB_space_warp itself**. FrameBridge `hide_space_warp` (per game, off) hides it and strips `XrCompositionLayerSpaceWarpInfoFB` (1000171000) from the projection views (log `hide_space_warp: removed space warp info`); the game still renders its MV swapchains. Test build installed on the dev Frame; flicker not yet checked in a headset. Heuristic: UE5 + OVRPlugin shows it as an option (off). `equirect_emul` is suggested for Unreal games whose graphics API isn't detected ("GLES or unknown"); on Vulkan it switches itself off (Myst/Riven/ITR2): harmless, but Unreal Vulkan detection is a known gap.
+**PR #34 (merged 2026-10-04, Lucas-Mathieu):** `native/adapter/audio_metadata.h` patches Meta XR Audio Wwise (only build ID e1619e7f…, Batman: Arkham Shadow 1.4.1) so queued audio metadata isn't freed while the current audio frame references it (smoke-bomb crash). Verified headless: installs ("metadata reclamation follows …"), 72 fps; we added a once-per-second scan limit. Outside PRs: review source, rebuild `artifacts/` ourselves, merge locally (contributor's commit kept), push main.
+**Heuristics eval (2026-10-04):** `scripts/eval_heuristics.py "<VR CyberDeck Portable>"` → 19/44 recipes exact, 322/352 fields (most diffs: `frame.unity_text_input` suggested where older catalog recipes lack it; the rest are runtime-only findings: use_alt, vk_shader_fix, focus_hold, sync_guard, multipass). `PATCHED/` copies aren't scored (already converted).
+**Power (0.9, agent v47):** sidebar bar above the Frame card: Sleep / Restart / Shut down, each confirmed (`app.frame_power`, a running game asks again). logind answers CanSuspend/CanReboot/CanPowerOff = "challenge" for an SSH session but "yes" inside a user unit, so agent `power` runs `systemctl suspend|reboot|poweroff` from a transient `systemd-run --user --on-active=3` timer (the command answers first). Restart verified on the device (back in ~84 s, new boot id).
+**Proton default (agent v51, owner's choice 2026-10-05):** the newest **stable** ARM64 Proton is the default for PC VR games (`pick_proton`: asked-for name/alias, else newest installed stable, else any stable). Agent v49-50 defaulted to Experimental; the owner's headset A/B with Rick and Morty (Experimental 69 % reprojected frames, stable felt much smoother) reverted it. The game page's Customize shows `pcvr.proton_tool` as a dropdown (Stable (default) / Experimental = alias `proton-experimental`); `ensure_proton` installs a chosen one (it asks once more for the runtime Steam only names after Proton is installed; Experimental installed unattended on the device in 53 s). A PC VR launch test that fails on stable suggests Experimental (`pipeline.PROTON_TOOL`, `proton_alternative_worth_trying`, button "Try Proton Experimental and reinstall"). Remaining Rick and Morty stutter on head turns = the game rendering below the refresh rate (reprojection), not Proton.
+**USB cable link (verified 2026-10-05, cabled to the dev PC):** `usb0` is a USB **NCM** gadget (configfs g1: `ncm.usb0` + `ffs.adb`, Valve 28de:2460) set up by `usb-ncm-gadget@usb0.service`, which only runs with `ConditionPathExists=|/etc/systemd/system/adbd.service.d/steamos-devkit-enabled` = **Developer Mode only**. `usb-ncm-dnsmasq@usb0` serves DHCP with fixed `dhcp-host` entries: Frame 10.86.200.233, PC **10.86.200.234** (`frame/usb.py` FRAME_USB_IP/PC_USB_IP). Windows 11 binds its built-in "UsbNcm Host Device" (no driver); WSL mirrored sees eth 10.86.200.234. USB is high-speed (USB 2.0): upload 36.9 MB/s vs 11.3 MB/s home Wi-Fi. Frame→PC over the cable worked without a firewall change. `scripts/usb_autotest.py` (Windows via powershell.exe from WSL), `frameport frame usb-check`. Wizard "Set up with a USB cable" (`PairingServer(host=PC_USB_IP)`; the real bootstrap ran end to end over USB). Discovery dedupes by SSH host key and prefers USB > Frame hotspot > network (`discovery.dedupe`); a lost address is re-found by key (`Frame.relocate`, tested with a dead saved address).
+**Catalog updates without a release (2026-10-05):** apps fetch `catalog/games/*.yaml` from GitHub `main` (`recommend/catalog.refresh_remote`: one API call `git/trees/main?recursive=1` + raw.githubusercontent downloads of changed blobs, cached as `catalog-gh-<sha>.yaml`, every 6 h; GUI at start + Settings → Data "Check now"; CLI background thread + `frameport catalog-update`). `catalog.load()` only reads the cache. A remote entry is skipped (`unusable_reason`) when it names a patch/adapter key this app doesn't register, has a field `CatalogEntry` doesn't know, or `min_app` > this version: add `min_app` (or rely on new patch ids) when a config needs an unreleased FramePort. Remote beats bundled unless the bundled entry has a later updated/verified date; the user's own entries still win as before. Off: setting `catalog.auto_update`, env FRAMEPORT_NO_CATALOG_UPDATE; FRAMEPORT_CATALOG_URL still overrides the source. So: **pushing a catalog change to main reaches users within 6 h** (their recipes follow via catalog_rev → Update on Frame).
 **Lepton storage (2026-09-30):** each app's /sdcard (= /storage/emulated/0 → `<base>/lepton-data/external`) has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (liblepton/mounting.sh, only if they exist at start); agent v24 `storage_targets` reads that mapping. Android's MediaProvider canonicalises paths to /home/steamos/... and rejects every file ("doesn't appear under [/system/media...]"), `sm list-volumes` is empty: the media index never works, apps must browse folders. Lepton installs with `adb install -g` (runtime permissions granted, MANAGE_EXTERNAL_STORAGE too). Files: `install/files.py`, `frameport frame send|storage`, GUI Files tab (formerly Frame → Send files).
 **SteamVR per-app settings (2026-09-30):** editing steamvr.vrsettings while SteamVR runs is lost; the web API (127.0.0.1:27062 /app/setsettings) needs `x-steamvr-secret`. `native/vrsettings` = `fp_vrsettings.exe` (freestanding, OpenVR `FnTable:IVRSettings_003` as a Utility app, loads SteamVR's bin/win64/openvr_api.dll) sets them live and SteamVR persists them: section `steam.app.<shortcut appid>`, keys `preferredRefreshRate` (float) and `motionSmoothingOverride` (0 global, 1 on, 2 off, 3 always). Steam Link (vrlink) lists the Frame's rates 72/80/90/96/108/120/144 in vrserver.txt and follows the per-app preference ("host preferred N Hz"; whether the key is honoured is unverified in-headset yet). Judder metric: vrcompositor.txt session summary dropped + "Timed out. N total" (Stormland: 0 dropped but 313 timeouts in 2 min); fpsVR (`%LOCALAPPDATA%\fpsVR\*.json`, 0.1 ms histograms) gives p99 CPU/GPU ms. `pcvr.steamvr_tuning` (default on, PC only) applies on Play: highest rate whose budget ≥ p99×1.05, at least one step down, smoothing on.

+**Language packs (merged from PR #20, 2026-10-04):** overport's `libovrplatformloader.so` is a dispatcher that `dlopen`s Meta's own loader (`libovrplatformloader_meta.so` / `_meta_q1.so`, also `libpxrplatformloader.so`) and keeps its own message queue; `ovr_LanguagePack_GetCurrent/SetCurrent` are 8-byte `return 0` stubs in it, `ovr_AssetFile_GetList` forwards to Meta's loader. `frame.langpacks` (opt-in, `native/langpack`) serves `<tag>.lang` files from the game's data; `elf.hide_exports` marks the loader's exports STB_LOCAL (bionic and glibc only match GLOBAL/WEAK; verified for glibc, bionic's `is_symbol_global_and_defined` is from memory). `libfp_langpack.so` is built here (`python native/build.py --only langpack`) and committed. Owner-verified 2026-10-04: Deadpool VR with only `en.lang` and the patch on plays English dialogue and runs normally (headless launch tests show 2-6 fps while it loads: not a regression sign). A dispatcher answer that arrives after we answered the timed-out GetList is dropped (one answer per request); games already in a library get `lang_packs` filled after an app update (`library._refresh_data_fields`). The library logs to logcat under the tag `fp_langpack` (dirs looked in, packs found, every language-pack call), so it shows up in the game's `launch.log`; an `ovr_AssetFile_GetList` the dispatcher leaves unanswered for 1.5 s is answered with our packs alone. Deadpool VR (Unreal) accepts a pack only when its `Metadata` equals the game's own version string (`ULanguagePacksSubsystem` compares it with `%s.%s.%s.%s.%s` built from the build info, e.g. `1.0.40.356975.Quest` = versionName; found by disassembling `libUE4.so`): the patch writes the APK's versionName into the library (`@FPMETA@` slot, `with_metadata`), `FRAMEPORT_LANGPACK_META` overrides it. Deadpool VR (2026-10-04, headset): German became selectable with that Metadata, but dialogue stayed silent (even English once reported as a pack) while the path was spelled `/sdcard/Android/obb/<pkg>/x.lang`; with the `/storage/emulated/0/Android/obb/<pkg>/x.lang` spelling (Unreal's own, now listed first in `scan_dirs`) German dialogue plays. `FRAMEPORT_LANGPACK_SKIP=<tags>` or a file `fp_langpack_skip` in the obb folder leaves packs out of the list (experiments).
+
 **Unresolved (as of 2026-09-28):** Arcsmith (right-eye distortion) and Time Stall (both eyes) — swap, tracking, Valve
 layers, depth, pacing ruled out. Sniper Elite VR (DEVICE LOST), Espire 1 (Mesa GL upload crash), HITMAN 3 (freedreno
 crash): use PC versions.
@@ -492,6 +541,11 @@ tests, builds Windows x64 / macOS arm64 / Linux x64 bundles, signs, attests and
 `FramePort-selfsigned.cer`; notes = "What's new" from the annotated tag message + the short `packaging/release-footer.md`; owner: keep release
 notes short — a few "What's new" bullets, nothing long after them).
 Installed apps find the release themselves (self-update), so the notes are what users see in the update dialog.
+- **Dev builds (for testers, no release):** Actions → build → Run workflow (main), "dev" ticked, optional "notes"
+  (what to test). The bundles get version `<next patch>.dev<run number>` (`scripts/dev_version.py`, not committed) and
+  replace the rolling `dev` pre-release (`dev-release` job; same assets + SHA256SUMS). Automatic update checks ignore
+  pre-releases; testers use Settings → Updates → "Install the latest dev build…" (`updates.check_dev`,
+  `Updater.install_dev`). `parse_version` sorts 0.9.0 < 0.9.1.devN < 0.9.1, so testers get the next release normally.
 - **Release checklist:** bump `src/frameport/_version.py` (the only version; `scripts/package.py` fails a tag build
  whose tag ≠ `v<_version>`), commit, `git tag -a vX.Y.Z -m "FramePort X.Y.Z" -m "<What's new, Markdown bullets>"`,
  push the commit and the tag. Never publish a release without its `SHA256SUMS.txt` (the updater refuses it) and keep
@@ -22,12 +22,16 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V
  [What it changes](docs/FRAME_SETUP.md).
 - **Type on Frame:** use your computer's keyboard on the Frame: in VR apps, Android apps, Steam and the desktop.
  [More](#type-on-frame).
- **One click per game:** convert, patch, sign, upload, add to Steam with artwork, launch test.
+- **One click per game:** convert, patch, sign, upload, add to Steam with artwork, launch test. Artwork that can't be found automatically can be picked from the stores or replaced with your own images.
 - **Per-game recipes:** a tested catalog plus detection rules; every patch explained in plain words.
 - **FrameBridge:** FramePort's OpenXR adapter emulates what the Frame natively lacks (passthrough, room, controller models,
  curved and 360° layers); game settings as simple switches.
 - **Beyond Quest:** Android apps as windows, PC VR via Proton or Revive, Windows (non-VR) games via Proton, a Files
  tab with drag and drop.
+- **Linux apps:** install arm64 Linux apps (AppImage, a folder, or a zip/tar archive) on the Frame with a Steam
+  shortcut; they run natively on SteamOS.
+- **Screenshots tab:** the screenshots you took in the headset, sorted by game (matched by play time) and day;
+  view them and download them to your computer.
 - **Self-updating** releases, redacted diagnostics, one-click problem reports and working-config sharing.

 ## Quick start
@@ -48,7 +52,8 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V
 3. **Add games → Scan a folder** with your game backups (APK + OBB, or PC VR game folders).
 4. Open a game → **Install on Frame**, then play it from the Frame's Steam library.

-Full guide, firewalls and troubleshooting: [docs/INSTALL.md](docs/INSTALL.md).
+Full guide, firewalls and troubleshooting: [docs/INSTALL.md](docs/INSTALL.md). Questions (e.g. how to lay out games
+with OBB files): [docs/FAQ.md](docs/FAQ.md).

 ## Type on Frame

@@ -63,6 +68,16 @@ Unity apps whose text fields close the moment you select them on the Frame (no s
 fix, so Steam's on-screen keyboard and Type on Frame work in them too.
 [Details](docs/INSTALL.md#typing-on-the-frame).

+## Screenshots
+
+Screenshots you take in the headset show up in FramePort's **Screenshots** tab, grouped by day and matched to the game
+you were playing. Open one full size, step through them, and download single shots, a selection or all of them to
+your computer.
+
+![Screenshots](docs/images/screenshots.png)
+
+![Screenshot viewer](docs/images/screenshot-viewer.png)
+
 ## Compatibility

 If a game has already been tested with FramePort, it will automatically use the optimal game config. Otherwise, FramePort
@@ -1,11 +1,12 @@
+48a3ecad77ec0f3215b29070e994590eb9579e04d3c88a47f37f306f9aeb01d9  ./arm64-v8a/libfp_langpack.so
 a5b03bb7ae5d953d7ded2bf117b0a19c57fae604f16f54310847f8e89593dde6  ./arm64-v8a/libfp_ovrp.so
 6d2b9f8cea2f2cf33b8ff30d29a2f3d9c4d55549260a867168a24e44abada021  ./arm64-v8a/libfp_vk.so
 8e00552d1ab90f82749db3caad4f773351fa8a28edcc5ea5cbd1b31c434ff32a  ./arm64-v8a/libframe_xrshim.so
 3dfcb0f2bec47857bcecc7261c58e076d872d4649718c40850f29e10c75477dd  ./arm64-v8a/libglshim.so
-f326df1a5bd600033661f53509f076b9b4ecbb6226e9050460b1d0cfdd70fb9d  ./arm64-v8a/libopenxr_loader_generic.so
+3e05bb8561c7fd8787b3120739b3ce66c68badb5b00571bd50ae7e6c1f159274  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
 32525cd0a9ee3d9993d8871cd6905bdcf22cde4f4ba28f5db6434ce7d6554758  ./arm64-v8a/libvrapi.so
-ddfd8b6c319bfd0ea8aada3b5e941981288ac10aa6443a79843a7b8c288f82fe  ./armeabi-v7a/libopenxr_loader_generic.so
+33bf52994b8024e139af20d6915bc76a0c7341ce9b5bd136a3002236168bcbd1  ./armeabi-v7a/libopenxr_loader_generic.so
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 1aa733117cf57ccff7cf23f0425dbfd73b0332a3ef1c905ceeca0ccd0449c4e0  ./linux-arm64/XR_APILAYER_FRAMEPORT_timefix.json
 28c2430a02bbd8902c5bfb9562c6fd0e318654f9e05c095bfeb94b0450ab1b07  ./linux-arm64/libxr_frameport_timefix.so
@@ -0,0 +1,25 @@
+package: com.CMGames.IntoTheRadius2
+title: Into The Radius 2
+status: issues
+notes: Space warp is turned off (no flickering textures in the headset); the headset's brief focus losses are hidden
+  (focus_hold, up to 2.5 s) because the game pauses on each. Loading a save can take over a minute.
+details: Unreal Engine 5 game that uses Meta's Application SpaceWarp (extra motion-vector and depth swapchains). OVRPort's
+  patch_disable_space_warp doesn't reach Unreal Engine 5, so FrameBridge's hide_space_warp hides XR_FB_space_warp and
+  removes the space warp info from the eye images. Working config shared in GitHub issue 35. In the headset
+  (2026-10-05) the Frame dropped focus for 0.4 s and 1.0 s within ten seconds and Unreal paused each time; loading a save
+  shows no frames for 40-80 s while the game's Sentry SDK (debug mode) logs its breadcrumbs.
+tested_version: 1.2.4
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+adapter:
+  equirect_emul: 1
+  hide_space_warp: 1
+  focus_hold: 1
+  focus_hold_ms: 2500
+verified:
+  date: '2026-10-04'
+  issue: 35
+updated: '2026-10-05'
+source_hint: Into The Radius 2
@@ -0,0 +1,21 @@
+package: com.NewFolderGames.IAmMonkey
+title: I Am Monkey
+status: works
+notes: Its intro video plays through FrameBridge's video panels.
+details: The game plays its intro on a panel that an Android media player (ExoPlayer) draws into
+  (XR_KHR_android_surface_swapchain). The Frame's runtime lists that extension but refuses the call, so the panel had
+  no image and the game stayed black waiting for the video (GitHub issue 25). The adapter's surface_emul (on by
+  default) hands the player a real Android Surface and copies each video frame into an ordinary swapchain the panel
+  shows.
+tested_version: 1.0.5
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+  issue: 25
+updated: '2026-10-04'
+source_hint: I Am Monkey
@@ -1,10 +1,11 @@
 package: com.playful.LuckysTale
 title: Lucky's Tale
 status: issues
-notes: Keeps MSAA off; the game turned it on by itself and the whole Frame restarted in a menu.
-details: Meta's OVRManager raises MSAA to 4x at runtime ("Switching to the recommended level"); multisampled
-  render-to-texture on GLES (Zink) hung the Frame's GPU (GitHub issue 9). frame.unity_runtime_msaa_off keeps it at 0;
-  not yet confirmed in a headset.
+notes: Runs out of memory within a few minutes and freezes the Frame until the game is killed.
+details: Unity's asset loading thread (Loading.PreloadManager) grows the game's native heap by about 1 GB/s
+  shortly after start (10+ GB plus all swap, then the kernel kills it; perf page-fault profile, 2026-10-04). The text
+  window and the MSAA patch aren't the cause (same with the window off); the OBB is byte-identical to the original.
+  The earlier "headset restarted in a menu" reports (GitHub issue 9) were most likely this. No fix yet.
 tested_version: 1.0.55
 engine: Unity
 xr: VrApi
@@ -0,0 +1,21 @@
+package: com.qcxr.qcxr
+title: QuestCraft
+status: issues
+notes: The launcher runs, but Minecraft crashes while starting its graphics (OpenGL error 1282).
+details: QuestCraft downloads its Java runtime (JRE.zip from QuestCraft's GitHub releases) into files/runtimes/JRE
+  on first start; on the Frame that step left nothing behind ("libjvm.so not found"). With the runtime unpacked there
+  by hand, Java, Fabric and the mods load and Minecraft 1.21.5 starts initializing, then its first texture fails with
+  OpenGL error 1282 in QuestCraft's GL-to-GLES layer on Zink. Leads (2026-10-04) - Android's libEGL ran out of
+  eglGetProcAddress slots for desktop GL functions; LWJGL and JNA natives in the APK don't match the newer files
+  QuestCraft downloads.
+tested_version: 6.0.0-RC4
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+updated: '2026-10-04'
+source_hint: QuestCraft
@@ -0,0 +1,20 @@
+package: com.resolutiongames.abvriop.santacruz
+title: palazzo_santacruz
+status: works
+notes: Played a few levels. Passthrough also works.
+tested_version: 3.7.6.10866-release
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-05'
+  known_good_sha256: 394214a68297c1e5b019dc4f65b145e7bd0e98604205616364e0c151c1afd894
+  app: 0.9.1
+  overport_cli: 1.2.5
+  frame_build: '20260922.6101926'
+  agent: 48
+  issue: 46
+source_hint: abvriop
@@ -0,0 +1,24 @@
+package: org.wiicompiled.quest
+title: WiiCompiled VR
+status: issues
+notes: 'To add a game: in FramePort''s Files tab, upload your .wcgame file to this game''s storage, folder
+  Android/data/org.wiicompiled.quest/files/WiiCompiledOpenXRVR/Import, then open WiiCompiled (it imports the newest
+  file there; one at a time). The right eye jitters during races.'
+details: A native Mario Kart Wii recompilation (needs your own disc as .wcgame files built by the WiiCompiled
+  launcher on a computer). Lepton's Android has no document picker, so the launcher's "Import from computer" and
+  "select disc image" buttons fail (ActivityNotFoundException for OPEN_DOCUMENT); its Import folder is read when the
+  launcher opens instead. The game's libmain.so has its own OpenXR loader and talks to the Frame's runtime directly
+  (FrameBridge isn't in its path); the right-eye jitter in races comes from its stereo replay of the race view, so it
+  needs a fix in WiiCompiled itself. The launcher is a flat Android window (shown with lepton-show-flatscreen).
+tested_version: 0.4.0-quest
+engine: Other
+xr: OpenXR
+frame:
+- frame.sdl_clipboard
+- frame.vk_sanitize
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+updated: '2026-10-04'
+source_hint: WiiCompiled
@@ -0,0 +1,22 @@
+package: unity.SUPERHOT_Team.SUPERHOT_VR_QA
+title: SUPERHOT VR
+status: works
+notes: Quest version. Needs FramePort's launcher from agent 41 (reinstall once) so the game can write its saves.
+details: Unity 2018.4 with built-in Oculus support (GLES). Its eye swapchains (GL_RGBA8, then a 16-bit format) are
+  created as sRGB by the adapter's swapchain_fix. The game creates its cloud save folder with mode 1700 and quits at
+  start when it can't write there ("Something failed to initialize. Quitting!"); the launcher now gives every folder
+  in the game's storage owner and group write permission.
+tested_version: '1.161'
+engine: Unity
+xr: VrApi
+frame:
+- frame.unity_no_msaa
+- frame.unity_oculus_check
+- frame.unity_text_input
+- frame.unity_runtime_msaa_off
+device:
+- device.text_input_window
+verified:
+  date: '2026-10-04'
+updated: '2026-10-04'
+source_hint: SUPERHOT VR
@@ -263,6 +263,25 @@ signatures:
    diagnosis: The game crashed under Wine/Proton (set the Proton debug log and check steam-<appid>.log).
    suggest: [pcvr.proton_log]

+  - id: save-folder-permission
+    pattern: "(We don't have write permission to|UnauthorizedAccessException: Access to the path \"/(sdcard|storage/emulated/0)/Android/data/)"
+    severity: error
+    diagnosis: The game can't write to a folder it created in its storage (e.g. SUPERHOT's cloud/data, mode 1700, which
+      makes it quit at start). FramePort's launcher (agent 41 or newer) gives such folders owner and group write
+      permission before and during every launch; update the game on the Frame (reinstall) to get the new launcher.
+    suggest: []
+  - id: surface-swapchain-emulated
+    pattern: 'surface_emul: emulated Android surface swapchain'
+    severity: info
+    diagnosis: The game plays a video on a panel through an Android Surface (XR_KHR_android_surface_swapchain), which the
+      Frame's runtime refuses; FrameBridge emulates it (surface_emul) and copies each video frame into the panel.
+    suggest: []
+  - id: surface-swapchain-failed
+    pattern: 'surface_emul: (setup failed|upload failed|EGL context failed|Vulkan upload path unavailable)'
+    severity: warning
+    diagnosis: FrameBridge couldn't emulate an Android video panel (XR_KHR_android_surface_swapchain); the panel stays
+      empty, and a game waiting for its intro video may stay black (e.g. I Am Monkey's intro).
+    suggest: []
 milestones:  # progress markers, in order; the furthest one reached is reported
  - {id: pcvr-launch, kind: pcvr, pattern: 'FramePort: launching|Launched injector with', label: Launcher started}
  - {id: pcvr-oculus-hmd, kind: pcvr, pattern: 'FramePort oculushmd: OculusHMDConnected event ready', label: Oculus headset event provided}
@@ -0,0 +1,31 @@
+# Meta XR Audio metadata lifetime
+
+FrameBridge automatically handles metadata retirement in the verified AArch64
+Meta XR Audio Wwise build (`e1619e7fb839badf0ea5ecc22d9f028d0b17c34d`). It requires
+the build ID and exact function prologues; other builds and 32-bit adapters are
+left unchanged. No additional patch switch or recipe entry is required.
+
+The SDK queues terminated metadata for deletion, then drains those queues before
+reading the current `AkAudioObjects` snapshot. In Batman: Arkham Shadow, that
+snapshot can still reference queued metadata during smoke-bomb playback. The
+audio thread subsequently clears its dirty flags at offset 8 through the stale
+pointer. A hardware watch captured this store in
+`OculusEndpointSink::ConsumeObjectExperimentalMetadata`, at library offset
+`0x2ced90`. Reallocated input tree nodes occupy the same 48-byte size class;
+the stale store corrupts their right pointer and the game crashes later.
+
+`native/adapter/audio_metadata.h` wraps the audio consumption boundary to make
+the current snapshot available to metadata cleanup. `audio_metadata_queue.h`
+retains queued objects still referenced by that snapshot, then reclaims them
+normally when the references disappear. It preserves the SDK's queue mutex,
+virtual deleting destructor, audio parameters and processing. There is no timed
+quarantine, replacement allocator, audio suppression or diagnostic memory arena.
+
+Synthetic regression tests exercise mixed referenced and unreferenced queue
+entries, both metadata types, subsequent retirement, and cleanup without a live
+snapshot. On-headset smoke-bomb tests first showed the observed overwrite stopped,
+then passed with ordinary allocations and all memory diagnostics removed.
+
+The existing `frame.adapter` install step includes the repair in its packaged
+adapter and updates already wrapped APKs. Rebuild the adapters and checksums with
+`python native/build.py --only adapter`.
@@ -0,0 +1,31 @@
+# FAQ
+
+## How should I lay out a game that has OBB files (an APK plus a data folder)?
+
+Give every game its own folder, put the APK in it, and put the game's data next to the APK in a folder named
+after the game's **package name** (the name the `.obb` files contain, e.g. `com.Armature.VR4`):
+
+```
+Games/                                  ← scan this folder (Add games → Scan a folder)
+├── Resident Evil 4/                    ← one folder per game (any name)
+│   ├── VR4.apk                         ← the APK (any file name)
+│   └── com.Armature.VR4/               ← the data folder: exactly the package name
+│       ├── main.203.com.Armature.VR4.obb
+│       └── patch.203.com.Armature.VR4.obb
+└── Beat Saber/
+    └── com.beatgames.beatsaber.apk     ← games without OBBs: just the APK
+```
+
+- **Data folder name:** the package name (`com.Armature.VR4` above), or `obb`. FramePort uses the first of the two
+  that exists and isn't empty.
+- **Everything in that folder is copied** to the game's `Android/obb/<package>/` on the Frame, subfolders included.
+  So games that ship raw data files instead of `.obb` files work the same way.
+- **One game per folder.** Several APKs in one folder count as one game; FramePort uses the first and keeps the others
+  as alternates.
+- **Scanning:** pick the folder that contains the game folders (`Games/` above) to add them all, or one game's folder
+  to add just that game. FramePort looks up to 5 levels deep.
+- **A single game:** Add games → Add an APK file… works with a lone APK too. Its data is found when the data folder sits next
+  to the APK, named as above.
+
+Not sure of the package name? Look at the OBB file names: `main.<version>.<package name>.obb`. Or add the APK
+first: the game's page shows the package name under **Details**.
@@ -23,6 +23,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Espire 2 | Quest | ✅ Works |  |
 | Genotype | Quest | ✅ Works |  |
 | H.U.N.T | Quest | ✅ Works |  |
+| I Am Monkey | Quest | ✅ Works |  |
 | In Death: Unchained | Quest | ✅ Works |  |
 | Job Simulator | Quest | ✅ Works |  |
 | Keep Talking and Nobody Explodes | Quest | ✅ Works |  |
@@ -42,6 +43,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Space Pirate Trainer Quest | Quest | ✅ Works |  |
 | Stremio | Quest | ✅ Works |  |
 | SUPERHOT VR | PC VR | ✅ Works |  |
+| SUPERHOT VR | Quest | ✅ Works |  |
 | The Climb 2 | Quest | ✅ Works |  |
 | Toy Master | Quest | ✅ Works |  |
 | Under Cover | Quest | ✅ Works |  |
@@ -52,11 +54,14 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | 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. |
 | I Am Cat | Quest | ⚠️ Works with issues | The view vibrates slightly, even when holding still. |
-| Lucky's Tale | Quest | ⚠️ Works with issues | Keeps MSAA off; the game turned it on by itself and the whole Frame restarted in a menu. |
+| Into The Radius 2 | Quest | ⚠️ Works with issues | Space warp is turned off (no flickering textures in the headset); the headset's brief focus losses are hidden (focus_hold, up to 2.5 s) because the game paus… |
+| Lucky's Tale | Quest | ⚠️ Works with issues | Runs out of memory within a few minutes and freezes the Frame until the game is killed. |
 | 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). |
+| QuestCraft | Quest | ⚠️ Works with issues | The launcher runs, but Minecraft crashes while starting its graphics (OpenGL error 1282). |
 | Silhouette | Quest | ⚠️ Works with issues | Hand-tracking game; the Frame synthesizes hands from controllers, so it is janky. |
 | Time Stall | Quest | ⚠️ Works with issues | Both eyes distort during movement (unresolved). |
+| WiiCompiled VR | Quest | ⚠️ Works with issues | To add a game: in FramePort's Files tab, upload your .wcgame file to this game's storage, folder Android/data/org.wiicompiled.quest/files/WiiCompiledOpenXRVR… |
 | BONELAB | Quest | ❌ Doesn't run | Crashes while starting its graphics (Vulkan); no fix yet. |
 | Espire 1: VR Operative (Quest Edition) | Quest | ❌ Doesn't run | Mesa GL driver crash during texture upload. |
 | HITMAN 3 VR: Reloaded | Quest | ❌ Doesn't run | Vulkan driver crash (freedreno), even without Valve layers. |
@@ -49,6 +49,20 @@ The Frame and the computer must be on the same network.
 and approve it on the Frame (Valve's own devkit pairing; it only sends this computer's key to the Frame). Install
 Lepton from the Steam Frame page afterwards if it's missing.

+### With a USB cable
+
+For networks that block the setup (guest Wi-Fi, firewalls, discovery not working), and for faster uploads:
+
+1. On the Frame, turn on **Developer Mode** (Settings → System → Developer Mode). The Frame's USB network only exists
+   in Developer Mode.
+2. Connect the Frame's USB-C port to the computer.
+3. In FramePort: **Steam Frame → Set up with a USB cable**. FramePort detects the cable and shows the setup command,
+   which reaches the computer over the cable. Already set up? It connects over the cable right away.
+
+The cable needs no driver on Windows 10/11, macOS or Linux, and the computer gets an address from the Frame
+automatically. Uploads use the cable whenever it's plugged in (about 37 MB/s, ~3× typical Wi-Fi), even when FramePort
+connected over Wi-Fi. Unplug it any time: FramePort finds the Frame on Wi-Fi again by itself.
+
 ### Firewalls

 If the setup command only says "timed out", a firewall on your computer blocks the Frame; the setup page
@@ -101,6 +115,12 @@ reality), showing only what matters for that game. Changes are kept with the gam

 ## Updating

+**Game configs** (the tested recipes in the catalog) update by themselves: FramePort checks GitHub every 6 hours for
+newly confirmed or fixed configs and uses them without a FramePort update; a game whose recipe changed then shows
+**Update on Frame**. Configs that need a newer FramePort are skipped until you update. Settings → Data shows the last
+check (**Check now**) and turns this off.
+
+
 FramePort checks for a new release at start and every 6 hours (it only downloads the release information). When one
 exists, the Library shows **Update now**: FramePort downloads the new version, verifies it against the release's
 `SHA256SUMS.txt` (on Windows also the signature), restarts and opens as the new version. Games, settings, signing keys
@@ -110,6 +130,10 @@ Settings → **Updates**: turn the check off, or turn on **Install updates autom
 installs at the next start). If FramePort's folder isn't writable, **Update now** opens the release page instead. The
 update log is `logs/update.log` in the data folder.

+**Dev builds:** when you're asked to test a fix before it's released, use Settings → Updates → **Install the latest
+dev build…**. It shows what to test, then installs like an update (same checks). Dev builds are less tested; the next
+release is offered to you as a normal update.
+
 Command line: `frameport update` (`--check` only checks, exit code 10 = update available; `--yes` doesn't ask).
 `FRAMEPORT_NO_UPDATE_CHECK=1` turns all checks off.

@@ -132,12 +156,28 @@ starts it if asked). FramePort installs it on the Frame and Proton runs it as a
 it shows up in the Frame's Steam library tagged "Windows game on Frame". Whether a game runs depends on Proton on ARM
 (x86 games run through emulation).

+## Linux apps (arm64)
+
+The Frame runs SteamOS on an arm64 CPU, so native Linux apps built for **aarch64/arm64** run on it directly (no
+Android container, no Proton). **Add games → Add a Linux app (arm64)…** takes an AppImage or a `.zip`/`.tar.gz`/
+`.tar.xz` archive; **Add a Linux app folder…** takes an unpacked app. FramePort finds the program that starts it (the
+game page's **Change…** picks another one) and whether it's a VR (OpenXR) app. **Install on Frame** uploads it
+unchanged and adds it to the Frame's Steam library, tagged "Linux app on Frame"; Play, launch tests and Uninstall
+work like for other games.
+
+- x86_64 builds can't run on the Frame: FramePort says so when you add one. Look for an aarch64/arm64 download.
+- The app must bring the libraries SteamOS doesn't have. If some are missing, the install reports them and the game
+  page lists them: look for a build that includes them.
+- From the command line: `frameport add-linux <AppImage, folder or archive> [--exe <program>]`.
+
 ## Files on the Frame (videos, documents, mods, saves)

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

@@ -167,6 +207,7 @@ and `frameport <command> --help` describe every option. The main ones:
 | Command | What it does |
 |---|---|
 | `scan <folder>` / `list` / `show <game>` | add games, list the library, show a game's analysis and patches |
+| `add-linux <path>` | add an arm64 Linux app (AppImage, folder or archive) |
 | `recipe <game> --enable/--disable <patch>` | change a game's patches (`patches` lists them all) |
 | `build <game>` / `install <game>` / `test <game>` | build, install on the Frame (`--to pc` for PC VR on this PC), launch test |
 | `frame discover` / `frame connect` / `frame info` | find, pair with and describe the Frame |
@@ -15,6 +15,11 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 |---|---|---|
 | Every game suddenly fails to start: `crun: create keyring …: Disk quota exceeded`, `is not a running context` | rootless podman leaked a kernel keyring per launch; 200-key quota exhausted | `keyring = false` in `~/.config/containers/containers.conf` (FramePort agent does it), then reboot the Frame once |
 | 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 |
+| Steam's Exit game leaves the game running (container `lepton-steamlaunch-<appid>` still up) | Steam stopped only its `reaper`; launch.sh and Lepton (setsid) never got a signal (GitHub #36) | agent v44: launch.sh's 2 s loop ends the game when its parent is gone (`upgrade_launchers` adds it to existing launchers); by hand: `podman kill lepton-steamlaunch-<appid>` |
+| Black screen at start while audio/ExoPlayer runs; log `xrEndFrame: dropped N unusable layer(s)`, a quad layer with swapchain 0x0 (e.g. I Am Monkey's intro video) | The game plays video into an Android-surface swapchain (XR_KHR_android_surface_swapchain); the Frame's runtime lists the extension but returns FUNCTION_UNSUPPORTED | adapter `surface_emul` (default on): FrameBridge gives the player a SurfaceTexture-backed Surface and copies each frame into an ordinary swapchain (log `surface_emul: …`) |
+| The game quits right after start: `Something failed to initialize. Quitting!` / `We don't have write permission to …/files/cloud/data` (e.g. SUPERHOT) | The game created a save folder with mode 1700; inside Lepton the app writes through the folder's group | launch.sh `fix_perms` adds owner + group write to every folder in the game's storage (agent 41); reinstall to get the new launcher |
+| The whole Frame slows to a halt, then the game is killed (`Out of memory: Killed process … anon-rss:10+ GB`), e.g. Lucky's Tale | The game's own memory grows ~1 GB/s on Unity's `Loading.PreloadManager` thread (perf page-fault profile); not the flat window, not the text-input patches | none yet: mark unsupported; profile with `perf record -p <pid> -e page-faults --call-graph fp` (works as steamos, `perf_event_paranoid` 2) |
 | `APP_ACTIVITY is empty`, nothing starts | Manifest has category INFO only; Lepton needs LAUNCHER | `frame.launcher` (automatic) |
 | PC VR game on the Frame shows as a flat window / Revive: `Unable to load LibOVRRT DLL` / `LoaderInstance::CreateInstance chained CreateInstance call failed` | Frame SteamVR runtime rejects OpenXR apiVersion 1.1 (`XR_ERROR_API_VERSION_UNSUPPORTED`), which Proton 11's VR helper requests | `pcvr.xr_timefix` (Frame OpenXR layer, default on): retries xrCreateInstance as 1.0 |
 | Unreal PC VR game on the Frame runs as a flat window although OpenXR works (no `LogHMD` OVRPlugin lines; Unreal logs nothing when it skips the Oculus plugin) / launch.log: `FramePort oculushmd: could not create the OculusHMDConnected event` | UE's OculusHMD (and LibOVR's `ovr_Detect`) only start when the Windows event `OculusHMDConnected` exists and is signalled; on a PC the Oculus service creates it. Revive hooks `OpenEventW` for it, but that relies on Detours patching Wine's (ARM64EC) kernelbase | `pcvr.oculus_unreal` (default for Unreal Rift games; PC VR counterpart of overport's `patch_oculus_unreal`): launch.sh runs the injector through `fp_oculushmd.exe`, which provides the real event until the game exits |
@@ -30,6 +35,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | `INSTALL_FAILED_NO_MATCHING_ABIS` | 32-bit-only APK; Frame has no AArch32 | None. PC/Rift version via Revive |
 | `UnsatisfiedLinkError` / `cannot locate symbol "ovr_…"` | overport's platform loader lacks Meta platform functions | `frame.ovrstubs` (automatic, generated stubs) |
 | missing `ovrMessageType_ToString` | same, but the game needs a real string | `frame.ovrplatformcompat` (automatic) |
+| 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`) |
@@ -49,6 +55,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | PC VR game judders/stutters although the GPU keeps up; vrcompositor.txt "Timed out. N total" high or frames dropped | the game misses the headset's refresh (e.g. 96 Hz = 10.4 ms; Stormland's slow frames take 10.7 ms) | `pcvr.steamvr_tuning` (default on): next Play sets SteamVR per-app `preferredRefreshRate` + `motionSmoothingOverride` via `fp_vrsettings.exe` |
 | Quest app keeps recentering / snapping the view when you turn your head; log shows session state 5→4→3→4→5 within a second | the Frame briefly takes focus; the app recenters on focus changes | unfixed: hiding the dips (debounce) made AC Nexus stay black, so it was removed |
 | Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | upload in the Files tab (Videos = /sdcard/Movies) and browse folders in the app |
+| 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 (Unity, GLES) freezes, `zink: DEVICE LOST` | multisampled render-to-texture hangs the GPU | `frame.unity_no_msaa`; if it persists: unfixable → PC version |
 | 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 |
 | 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 |
@@ -98,6 +105,11 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 - Which library a stale pointer belonged to: turn on the Android linker's log for one run by adding
  `debug.ld.app.<pkg>=dlopen` as an extra line of `LEPTON_GFXRECON_FP_PROPS` (first line `0`) in the game's
  launch.sh on the Frame (back it up, restore it after) and look for `dlclose: unloading "…"`.
+- Memory runaways / busy loops: `perf` works as steamos (`perf_event_paranoid` 2, user space only; `ptrace_scope` 1
+  blocks eu-stack/gdb/debuggerd). `perf record -p <pid> -e page-faults -c 64 --call-graph fp` names the thread
+  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).
 - 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:`
@@ -1,5 +1,9 @@
 # Native components

+FrameBridge includes automatic metadata retirement for the verified Meta XR Audio
+Wwise build; see [AUDIO_METADATA.md](../docs/AUDIO_METADATA.md) for its lifetime
+invariant and regression coverage. It uses the existing adapter installation.
+
 Sources of the prebuilt binaries in `../artifacts/` (committed, with `SHA256SUMS`). End users never compile anything;
 developers rebuild with `python native/build.py` (downloads NDK r27c, OpenXR headers at pinned commits, d8 into
 `native/.cache/`, git-ignored). The adapter, GL shim and platform compat rebuild byte-identically; the VrApi bridge
@@ -10,6 +14,7 @@ embeds debug paths (`-g`) and the dex depends on the d8 version, so those differ
 | `adapter/` | `{arm64-v8a,armeabi-v7a}/libopenxr_loader_generic.so` | **FrameBridge**: replaces overport's generic loader (which is renamed `libopenxr_loader_original.so`) and fixes Steam Frame runtime gaps. Hooks xrCreateInstance, swapchains, xrEndFrame, spaces, xrPollEvent, … everything else is forwarded by `gen_forwarders.py`-generated tail calls. `scene_emu.c` = Meta scene/spatial-entity emulation; `flip_vk.c` = Vulkan blit for VERTICAL_FLIP quads. `session_fixes.c` = per-game session fixes, all off by default and hooked only when on (`layer_debug` diagnostics, `stable_local`, `focus_hold`, aim correction `aim_pitch/aim_yaw/aim_forward`, `refresh_rate`); `layer_emul_gl.c` = `equirect_emul` (GLES sessions only): 360° equirect/equirect2 layers become one adapter projection layer, drawn by a worker thread with its own EGL context shared with the app's: each 360° image is converted to a cube map only when it changes, and the view is redrawn only after a 4° head turn (GL/EGL resolved with dlopen, so Vulkan games never load them); `layer_math.h` = their pose/face math, tested on the host by `tests/test_layer_emul.py`. `render_model.c` = XR_FB_render_model emulation (setting `controller_models`, off by default): serves `files/framebridge/controller_{left,right}.glb`, which the agent converts on the Frame from SteamVR's own Frame controller render models (never shipped by FramePort); tested on the host by `tests/test_render_model.py`. Settings: `libframe_settings.so` in the APK + `settings.conf`/`framebridge.conf` on the Frame. |
 | `vrapi-bridge/` | `arm64-v8a/libvrapi.so` | VrApi → OpenXR bridge from [Android-XR-Bridge/OVRPort](https://github.com/Android-XR-Bridge/OVRPort) `native/vrapi` at 5e7df52 (GPL-3.0, `LICENSE.upstream`; unchanged upstream as of OVRPort v1.2.5, which ships the unpatched code as its opt-in `patch_vrapi_openxr` in experimental CLI builds), with our changes in `upstream-patches/`: GLES sessions + GL texture swapchains, cylinder→quad layers, GL vertical flip, UNORM↔sRGB format twins, 30 s VR-mode deadline, VALID-only recenter, loading-icon layers skipped, diagnostics behind `-DOVP_GL_DIAG`. |
 | `platformcompat/` | `arm64-v8a/libovrplatformcompat.so` | Real `ovrMessageType_ToString` (same fork, `native/platform`). |
+| `langpack/` | `arm64-v8a/libfp_langpack.so` | Language packs for the Meta Platform SDK (patch `frame.langpacks`, opt-in). overport's platform loader is a dispatcher in front of Meta's own loader and answers `ovr_LanguagePack_GetCurrent/SetCurrent` with `return 0` (no reply ever). This library becomes the loader's first DT_NEEDED; the loader's own exports of the 31 functions it defines are made STB_LOCAL in `.dynsym` (`elf.hide_exports`, nothing moves), so symbol lookups reach the library first. It serves `<tag>.lang` files found in the game's OBB / app files (`$FRAMEPORT_LANGPACK_DIRS` overrides the search path) through `ovr_LanguagePack_*`, `ovr_AssetFile_GetList` (the loader's list + the packs) and `ovr_AssetFile_StatusById`; its own message queue is merged into `ovr_PopMessage`, and every handle that is not ours (an address-range check) goes to the loader's original function, whose address is read at run time from the loader's in-memory `.dynsym`. Host-tested against a stand-in loader (`tests/test_langpack.py`, plain `cc`, no NDK); the bionic/headset side is unverified. |
 | `glshim/` | `arm64-v8a/libglshim.so` | Mesa GLSL compatibility for GLAD engines (hooks eglGetProcAddress): comments out `#pragma` before `#extension`, enables `GL_EXT_shader_implicit_conversions`, hides GL_OVR_multiview (`gl_hide_multiview`, default 1) and logs failed shaders. `-DGLSHIM_TRACE` adds per-FBO draw/error tracing. |
 | `xrlayer/` | `linux-arm64/libxr_frameport_timefix.so` + `XR_APILAYER_FRAMEPORT_timefix.json` | OpenXR API layer for Windows PC VR games under Proton on the Frame (glibc aarch64, built freestanding with the NDK's clang), on by default (patch `pcvr.xr_timefix`). Retries `xrCreateInstance` as an OpenXR 1.0 app when the runtime rejects 1.1 (the Frame's SteamVR runtime does, and Proton 11's VR helper asks for 1.1). Also emulates `xrConvertTimespecTimeToTimeKHR`/`xrConvertTimeToTimespecTimeKHR` if the runtime refuses them (the Frame's Android runtime does; its Linux runtime, used by Proton, supports them as of 2026-09-29 — so this part is only a fallback; Proton's wineopenxr needs them for `XR_KHR_win32_convert_performance_counter_time`, which Revive requires) with the adapter's xrWaitFrame-calibrated offset, and drops the extension from xrCreateInstance if the runtime rejects it. Enabled per game by the Proton launch.sh (`XR_API_LAYER_PATH`, `XR_ENABLE_API_LAYERS`). `tests/test_xrlayer.py` builds it for x86_64 and drives it via ctypes. |
 | `oculushmd/` | `win-x64/fp_oculushmd.exe` | PC VR counterpart of overport's `patch_oculus_unreal` (patch `pcvr.oculus_unreal`, default for Unreal Rift games on the Frame). Unreal's OculusHMD and LibOVR's `ovr_Detect` only start when the Windows named event `OculusHMDConnected` exists and is signalled (the Oculus service creates it). `fp_oculushmd.exe <command line>` creates it (manual reset, signalled), runs the command (Revive's injector) in a job object and keeps the event until every process in the job — the game and its children — has exited (fallback without job support: 3 minutes); returns the command's exit code and logs `FramePort oculushmd: …` to stderr (launch.log). Freestanding Windows x64 console exe (no CRT, no Windows SDK): the NDK's clang + `lld-link /Brepro` with a kernel32 import library generated by `llvm-dlltool`, so it's byte-reproducible. Tested on Windows from WSL with a build whose event name is `-DEVENT_NAME=L"…"` (the Oculus service owns the real event on a PC with the Oculus app). |
@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Meta XR Audio Wwise metadata retirement. Enabled automatically for the
+// exact verified AArch64 SDK build; unrelated libraries remain untouched.
+#pragma once
+#if defined(__aarch64__)
+#include <pthread.h>
+#include <sched.h>
+#include <sys/mman.h>
+#include <unistd.h>
+#include <stdint.h>
+#include <time.h>
+#include <link.h>
+#include <string.h>
+static size_t mx_audio_page;
+static void *mx_audio_detour(unsigned char *address,void *replacement,const uint32_t expected[4]) {
+    if(memcmp(address,expected,16)) return NULL;
+    unsigned char *trampoline=mmap(NULL,mx_audio_page,PROT_READ|PROT_WRITE,MAP_PRIVATE|MAP_ANONYMOUS,-1,0);
+    if(trampoline==MAP_FAILED) return NULL;
+    uint32_t branch[2]={0x58000050u,0xd61f0200u}; // ldr x16, +8; br x16
+    memcpy(trampoline,address,16);
+    memcpy(trampoline+16,branch,8);
+    uintptr_t continuation=(uintptr_t)address+16;
+    memcpy(trampoline+24,&continuation,8);
+    __builtin___clear_cache((char*)trampoline,(char*)trampoline+32);
+    if(mprotect(trampoline,mx_audio_page,PROT_READ|PROT_EXEC)) return NULL;
+    unsigned char *page=(unsigned char*)((uintptr_t)address&~(mx_audio_page-1));
+    if(mprotect(page,mx_audio_page,PROT_READ|PROT_WRITE|PROT_EXEC)) return NULL;
+    memcpy(address,branch,8);
+    memcpy(address+8,&replacement,8);
+    __builtin___clear_cache((char*)address,(char*)address+16);
+    mprotect(page,mx_audio_page,PROT_READ|PROT_EXEC);
+    return trampoline;
+}
+#include "audio_metadata_queue.h"
+typedef struct {float previous,current;} MxAudioRamp;
+static uintptr_t mx_audio_base;
+// set once the library was found but isn't the verified build: stop looking (xrPollEvent runs several times a frame)
+static int mx_audio_checked;
+static uint64_t (*mx_audio_consume_original)(void*,void*,void*,const void*,MxAudioRamp);
+static void mx_audio_kill(unsigned experimental) {
+    void *mutex=(void*)(mx_audio_base+(experimental?0x5fe2e0:0x5fe380));
+    int (*trylock)(void*)=(void*)(mx_audio_base+0x5b369c);
+    void (*unlock)(void*)=(void*)(mx_audio_base+0x5b36bc);
+    if(!trylock(mutex))return;
+    mx_audio_drain((void**)(mx_audio_base+(experimental?0x5fe2d8:0x5fe378)),experimental?40:24);
+    unlock(mutex);
+}
+static void mx_audio_kill_experimental(void) {mx_audio_kill(1);}
+static void mx_audio_kill_regular(void) {mx_audio_kill(0);}
+static uint64_t mx_audio_consume(void *sink,void *main_mix,void *passthrough,const void *objects,MxAudioRamp ramp) {
+    const unsigned char *previous=mx_audio_objects;mx_audio_objects=objects;
+    // An audio thread can enter just after its prologue was patched, before
+    // the installing thread publishes the completed trampoline.
+    uint64_t (*original)(void*,void*,void*,const void*,MxAudioRamp);
+    while(!(original=__atomic_load_n(&mx_audio_consume_original,__ATOMIC_ACQUIRE)))sched_yield();
+    uint64_t result=original(sink,main_mix,passthrough,objects,ramp);
+    mx_audio_objects=previous;return result;
+}
+static int mx_audio_find(struct dl_phdr_info *info,size_t size,void *unused) {
+    (void)size;(void)unused;
+    if(!strstr(info->dlpi_name,"/libMetaXRAudioWwise.so"))return 0;
+    if(mx_audio_base)return 1;
+    const unsigned char id[20]={0xe1,0x61,0x9e,0x7f,0xb8,0x39,0xba,0xdf,0x0e,0xa5,0xec,0xc2,0x2d,0x9f,0x02,0x8d,0x0b,0x17,0xc3,0x4d};
+    int match=0;
+    for(unsigned i=0;i<info->dlpi_phnum;i++)if(info->dlpi_phdr[i].p_type==PT_NOTE) {
+        const unsigned char *p=(void*)(info->dlpi_addr+info->dlpi_phdr[i].p_vaddr);
+        const unsigned char *end=p+info->dlpi_phdr[i].p_memsz;
+        while(p+sizeof(Elf64_Nhdr)<=end) {
+            const Elf64_Nhdr *note=(void*)p;
+            const unsigned char *name=p+sizeof(*note),*desc=name+((note->n_namesz+3)&~3u);
+            const unsigned char *next=desc+((note->n_descsz+3)&~3u);
+            if(next>end || next<=p)break;
+            if(note->n_type==NT_GNU_BUILD_ID && note->n_namesz==4 && !memcmp(name,"GNU",4) && note->n_descsz==20 && !memcmp(desc,id,20))match=1;
+            p=next;
+        }
+    }
+    if(!match){__atomic_store_n(&mx_audio_checked,1,__ATOMIC_RELEASE);return 1;}
+    const uint32_t consume[4]={0xd10743ff,0x6d1623e9,0xa9177bfd,0xa9186ffc};
+    const uint32_t kill[4]={0xa9bd7bfd,0xf9000bf5,0xa9024ff4,0x910003fd};
+    unsigned char *base=(void*)info->dlpi_addr;
+    if(memcmp(base+0x2c8fac,consume,16) || memcmp(base+0x2be2c0,kill,16) || memcmp(base+0x2be7b0,kill,16)) {
+        __atomic_store_n(&mx_audio_checked,1,__ATOMIC_RELEASE);return 1;
+    }
+    __atomic_store_n(&mx_audio_base,info->dlpi_addr,__ATOMIC_RELEASE);
+    void *original=mx_audio_detour(base+0x2c8fac,(void*)mx_audio_consume,consume);
+    __atomic_store_n(&mx_audio_consume_original,original,__ATOMIC_RELEASE);
+    if(!__atomic_load_n(&mx_audio_consume_original,__ATOMIC_ACQUIRE)) {
+        __atomic_store_n(&mx_audio_base,0,__ATOMIC_RELEASE);return 1;
+    }
+    if(!mx_audio_detour(base+0x2be2c0,(void*)mx_audio_kill_experimental,kill) || !mx_audio_detour(base+0x2be7b0,(void*)mx_audio_kill_regular,kill)) {
+        LOG("FrameBridge audio metadata: incomplete installation");return 1;
+    }
+    LOG("FrameBridge audio metadata: metadata reclamation follows current audio-frame references; Meta audio base=%p",base);
+    return 1;
+}
+static pthread_mutex_t mx_audio_install_mutex=PTHREAD_MUTEX_INITIALIZER;
+static void mx_audio_initialize(void) {
+    if(__atomic_load_n(&mx_audio_base,__ATOMIC_ACQUIRE) || __atomic_load_n(&mx_audio_checked,__ATOMIC_ACQUIRE))return;
+    // until the game loads the library: look at most once a second (dl_iterate_phdr takes the linker's lock)
+    static _Atomic long mx_audio_last_scan;
+    struct timespec now;clock_gettime(CLOCK_MONOTONIC,&now);
+    if(now.tv_sec==mx_audio_last_scan)return;
+    mx_audio_last_scan=now.tv_sec;
+    if(pthread_mutex_trylock(&mx_audio_install_mutex))return;
+    if(!mx_audio_page)mx_audio_page=(size_t)sysconf(_SC_PAGESIZE);
+    if(!mx_audio_base)dl_iterate_phdr(mx_audio_find,NULL);
+    pthread_mutex_unlock(&mx_audio_install_mutex);
+}
+#else
+static void mx_audio_initialize(void) {}
+#endif
@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: GPL-3.0-only
+#pragma once
+#include <stdint.h>
+#include <stddef.h>
+#include <string.h>
+// Experimental lifetime repair for the pinned Meta XR Audio Wwise build.
+// A queued metadata object must not be reclaimed while the current immutable
+// AkAudioObjects snapshot still references it. Preserve the SDK's queue mutex,
+// virtual destructor, list linkage, audio processing, and dirty-flag writes.
+static _Thread_local const unsigned char *mx_audio_objects;
+static unsigned mx_audio_held,mx_audio_reclaimed;
+static int mx_audio_referenced(const void *pointer) {
+    if(!mx_audio_objects)return 0;
+    uint32_t count;memcpy(&count,mx_audio_objects,4);
+    const unsigned char *const *objects;memcpy(&objects,mx_audio_objects+16,8);
+    // Refuse to reclaim on an unrecognised snapshot rather than dereferencing
+    // unbounded arrays. These bounds exceed the game's ordinary voice counts.
+    if(count>4096 || (count && !objects))return 1;
+    for(unsigned i=0;i<count;i++) {
+        const unsigned char *object=objects[i];if(!object)continue;
+        uint32_t metadata_count;const unsigned char *metadata;
+        memcpy(&metadata,object+104,8);memcpy(&metadata_count,object+112,4);
+        if(metadata_count>4096 || (metadata_count && !metadata))return 1;
+        for(unsigned j=0;j<metadata_count;j++) {
+            const void *parameter;memcpy(&parameter,metadata+(size_t)j*24+8,8);
+            if(parameter==pointer)return 1;
+        }
+    }
+    return 0;
+}
+// Caller holds the original queue's mutex, just as ExecuteKillList did.
+static void mx_audio_drain(void **head,size_t next_offset) {
+    void **link=head;
+    while(*link) {
+        void *pointer=*link;void **next=(void**)((unsigned char*)pointer+next_offset);
+        if(mx_audio_referenced(pointer)) {
+            link=next;
+            unsigned held=__atomic_fetch_add(&mx_audio_held,1,__ATOMIC_RELAXED);
+            if(held<8)LOG("FrameBridge audio metadata: queued metadata=%p still referenced by audio frame; retained",pointer);
+        } else {
+            *link=*next;
+            void (**table)(void*)=*(void (***)(void*))pointer;
+            table[1](pointer);
+            __atomic_fetch_add(&mx_audio_reclaimed,1,__ATOMIC_RELAXED);
+        }
+    }
+}
@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Included by frame_adapter.c (after flip_vk.c). Per-game diagnostics for "one eye looks wrong" reports
+// (eye_debug=1; everything also goes to framebridge.log in the app's external files folder):
+//  * every frame's projection layer: each eye's submitted pose vs. a fresh xrLocateViews at the frame's display time
+//    (game-side pose errors), the left/right eye relation (eye distance, relative rotation: must stay constant),
+//    and how long before xrEndFrame each eye's image was released (images handed over too early/late);
+//    summarised every 5 s, the first frames in full.
+//  * release_wait: before an image is released, wait for the app's GPU work on the session's queue (Vulkan) or
+//    glFinish (GLES), for games that release images whose rendering hasn't finished. 2 = only after the first 60 s
+//    of frames, so one headset session compares both (log "release_wait now ON").
+
+#define EYE_TRACKED 16
+
+static struct { XrSwapchain handle; int64_t released_ns; } eye_released[EYE_TRACKED];
+static pthread_mutex_t eye_lock = PTHREAD_MUTEX_INITIALIZER;
+static int64_t eye_first_frame_ns;
+
+static int release_wait_active(void) {
+    if (release_wait == 1) return 1;
+    if (release_wait != 2 || !eye_first_frame_ns) return 0;
+    static int announced;
+    int on = monotonic_ns() - eye_first_frame_ns > 60000000000ll;
+    if (on && !announced++) LOG("eye_debug: release_wait now ON (A/B: the first 60 s ran without it)");
+    return on;
+}
+
+static void eye_wait_for_gpu(void) {
+    if (vk.device) {
+        static PFN_vkQueueWaitIdle wait_idle;
+        if (!wait_idle && vk_ready()) wait_idle = (PFN_vkQueueWaitIdle)vk.GetDeviceProcAddr(vk.device, "vkQueueWaitIdle");
+        if (wait_idle && vk.queue) wait_idle(vk.queue);
+    } else {
+        static void (*finish)(void);
+        if (!finish) finish = (void (*)(void))dlsym(RTLD_DEFAULT, "glFinish");
+        if (finish) finish();
+    }
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL eye_hook_xrReleaseSwapchainImage(XrSwapchain swapchain,
+                                                                       const XrSwapchainImageReleaseInfo *info) {
+    PFN_xrReleaseSwapchainImage fn = (PFN_xrReleaseSwapchainImage)lookup(active_instance, "xrReleaseSwapchainImage");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (release_wait_active()) eye_wait_for_gpu();
+    XrResult result = fn(swapchain, info);
+    if (eye_debug) {
+        int64_t now = monotonic_ns();
+        pthread_mutex_lock(&eye_lock);
+        int slot = -1;
+        for (int i = 0; i < EYE_TRACKED && slot < 0; ++i)
+            if (eye_released[i].handle == swapchain) slot = i;
+        for (int i = 0; i < EYE_TRACKED && slot < 0; ++i)
+            if (!eye_released[i].handle) slot = i;
+        if (slot < 0) slot = (int)(now % EYE_TRACKED);
+        eye_released[slot].handle = swapchain;
+        eye_released[slot].released_ns = now;
+        pthread_mutex_unlock(&eye_lock);
+    }
+    return result;
+}
+
+static int64_t eye_release_age_ns(XrSwapchain swapchain, int64_t now) {
+    int64_t age = -1;
+    pthread_mutex_lock(&eye_lock);
+    for (int i = 0; i < EYE_TRACKED; ++i)
+        if (eye_released[i].handle == swapchain) age = now - eye_released[i].released_ns;
+    pthread_mutex_unlock(&eye_lock);
+    return age;
+}
+
+static float eye_angle_deg(XrQuaternionf a, XrQuaternionf b) {
+    float d = fabsf(a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w);
+    return d >= 1.0f ? 0.0f : 2.0f * acosf(d) * 57.29578f;
+}
+
+static float eye_dist_mm(XrVector3f a, XrVector3f b) {
+    float x = a.x - b.x, y = a.y - b.y, z = a.z - b.z;
+    return sqrtf(x * x + y * y + z * z) * 1000.0f;
+}
+
+static void eye_debug_end_frame(XrSession session, const XrFrameEndInfo *info) {
+    if (!info) return;
+    const XrCompositionLayerProjection *proj = NULL;
+    for (uint32_t i = 0; i < info->layerCount && !proj; ++i)
+        if (info->layers[i] && info->layers[i]->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
+            ((const XrCompositionLayerProjection *)info->layers[i])->viewCount == 2)
+            proj = (const XrCompositionLayerProjection *)info->layers[i];
+    if (!proj) return;
+    int64_t now = monotonic_ns();
+    if (!eye_first_frame_ns) eye_first_frame_ns = now;
+    static struct {
+        int frames, located;
+        float pos_err[2], rot_err[2], pos_err_max[2], rot_err_max[2];  // submitted vs. fresh, per eye
+        float ipd_min, ipd_max, rel_rot_max, step_max[2];               // eye relation; frame-to-frame jump per eye
+        float age_min[2], age_max[2];                                   // ms from release to xrEndFrame
+        int64_t window;
+    } st;
+    static XrPosef last[2];
+    static int have_last;
+    static int detailed;
+    if (!st.window) { st.window = now; st.ipd_min = 1e9f; st.age_min[0] = st.age_min[1] = 1e9f; }
+    // a fresh location of the same views at the frame's display time, in the layer's space
+    XrView fresh[2] = {{XR_TYPE_VIEW, NULL}, {XR_TYPE_VIEW, NULL}};
+    XrViewState vs = {XR_TYPE_VIEW_STATE, NULL};
+    uint32_t n = 0;
+    PFN_xrLocateViews locate = (PFN_xrLocateViews)lookup(active_instance, "xrLocateViews");
+    XrViewLocateInfo li = {XR_TYPE_VIEW_LOCATE_INFO, NULL, XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO, info->displayTime,
+                           proj->space};
+    int located = locate && XR_SUCCEEDED(locate(session, &li, &vs, 2, &n, fresh)) && n == 2 &&
+                  (vs.viewStateFlags & XR_VIEW_STATE_POSITION_VALID_BIT);
+    const XrCompositionLayerProjectionView *v = proj->views;
+    float ipd = eye_dist_mm(v[0].pose.position, v[1].pose.position);
+    float rel = eye_angle_deg(v[0].pose.orientation, v[1].pose.orientation);
+    ++st.frames;
+    if (ipd < st.ipd_min) st.ipd_min = ipd;
+    if (ipd > st.ipd_max) st.ipd_max = ipd;
+    if (rel > st.rel_rot_max) st.rel_rot_max = rel;
+    for (int e = 0; e < 2; ++e) {
+        int64_t age = eye_release_age_ns(v[e].subImage.swapchain, now);
+        float ms = age < 0 ? -1.0f : age / 1e6f;
+        if (ms < st.age_min[e]) st.age_min[e] = ms;
+        if (ms > st.age_max[e]) st.age_max[e] = ms;
+        if (located) {
+            float pe = eye_dist_mm(v[e].pose.position, fresh[e].pose.position);
+            float re = eye_angle_deg(v[e].pose.orientation, fresh[e].pose.orientation);
+            st.pos_err[e] += pe;
+            st.rot_err[e] += re;
+            if (pe > st.pos_err_max[e]) st.pos_err_max[e] = pe;
+            if (re > st.rot_err_max[e]) st.rot_err_max[e] = re;
+        }
+        if (have_last) {
+            float step = eye_angle_deg(last[e].orientation, v[e].pose.orientation);
+            if (step > st.step_max[e]) st.step_max[e] = step;
+        }
+        last[e] = v[e].pose;
+    }
+    have_last = 1;
+    if (located) ++st.located;
+    if (detailed < 4) {
+        ++detailed;
+        for (int e = 0; e < 2; ++e)
+            LOG("eye_debug: eye %d swapchain=%p rect=%d,%d %dx%d array=%u pos=%.4f,%.4f,%.4f rot=%.4f,%.4f,%.4f,%.4f "
+                "fov=%.3f/%.3f/%.3f/%.3f fresh pos=%.4f,%.4f,%.4f", e, (void *)(uintptr_t)v[e].subImage.swapchain,
+                v[e].subImage.imageRect.offset.x, v[e].subImage.imageRect.offset.y, v[e].subImage.imageRect.extent.width,
+                v[e].subImage.imageRect.extent.height, v[e].subImage.imageArrayIndex, v[e].pose.position.x,
+                v[e].pose.position.y, v[e].pose.position.z, v[e].pose.orientation.x, v[e].pose.orientation.y,
+                v[e].pose.orientation.z, v[e].pose.orientation.w, v[e].fov.angleLeft, v[e].fov.angleRight,
+                v[e].fov.angleUp, v[e].fov.angleDown, fresh[e].pose.position.x, fresh[e].pose.position.y,
+                fresh[e].pose.position.z);
+    }
+    if (now - st.window > 5000000000ll) {
+        int l = st.located ? st.located : 1;
+        LOG("eye_debug: %d frames | eye distance %.1f-%.1f mm, eye-to-eye rotation max %.2f deg | vs fresh pose: "
+            "L avg %.1f mm/%.2f deg max %.1f mm/%.2f deg, R avg %.1f mm/%.2f deg max %.1f mm/%.2f deg (%d located) | "
+            "largest frame step L %.2f R %.2f deg | release->end L %.1f-%.1f ms R %.1f-%.1f ms | release_wait %s",
+            st.frames, st.ipd_min, st.ipd_max, st.rel_rot_max, st.pos_err[0] / l, st.rot_err[0] / l, st.pos_err_max[0],
+            st.rot_err_max[0], st.pos_err[1] / l, st.rot_err[1] / l, st.pos_err_max[1], st.rot_err_max[1], st.located,
+            st.step_max[0], st.step_max[1], st.age_min[0], st.age_max[0], st.age_min[1], st.age_max[1],
+            release_wait_active() ? "on" : "off");
+        memset(&st, 0, sizeof(st));
+    }
+}
@@ -45,15 +45,47 @@
 #include <string.h>

 #define TAG "FrameBridge"
-#define LOG(...) __android_log_print(ANDROID_LOG_INFO, TAG, __VA_ARGS__)
+#include <stdarg.h>
+#include <time.h>
+// Everything also goes to <app external files>/framebridge.log when eye_debug is on: some games end Lepton's logcat
+// mirror early (WiiCompiled), so a headset session's diagnostics would otherwise be lost.
+static FILE *log_file;
+static void fb_log(const char *fmt, ...) __attribute__((format(printf, 1, 2)));
+static void fb_log(const char *fmt, ...) {
+    va_list args;
+    va_start(args, fmt);
+    __android_log_vprint(ANDROID_LOG_INFO, TAG, fmt, args);
+    va_end(args);
+    if (!log_file) return;
+    struct timespec now;
+    clock_gettime(CLOCK_REALTIME, &now);
+    flockfile(log_file);
+    fprintf(log_file, "%lld.%03ld ", (long long)now.tv_sec, now.tv_nsec / 1000000);
+    va_start(args, fmt);
+    vfprintf(log_file, fmt, args);
+    va_end(args);
+    fputc('\n', log_file);
+    fflush(log_file);
+    funlockfile(log_file);
+}
+#define LOG(...) fb_log(__VA_ARGS__)
+#include "audio_metadata.h"

 static void *loader;
 static PFN_xrGetInstanceProcAddr next_gipa;
 static pthread_once_t init_once = PTHREAD_ONCE_INIT;
 static XrInstance active_instance = XR_NULL_HANDLE;
+static void *android_vm;     // JavaVM from XrInstanceCreateInfoAndroidKHR (surface_swapchain.c)
+static int surface_emul = 1;  // setting: emulate Android surface swapchains
+static int eye_debug;          // setting: per-eye diagnostics + file log (eye_debug.c)
+static int release_wait;       // setting: wait for the app's GPU work before releasing images (2 = after 60 s: A/B)
+static void surf_on_destroy(XrSwapchain handle);

 static float scale = 1.0f;
 static int foveation_fix = 1;
+// hide XR_FB_space_warp: games then render every frame themselves (UE5 Application SpaceWarp flickered on the Frame,
+// e.g. Into The Radius 2; OVRPort's patch_disable_space_warp doesn't reach UE5's OpenXR plugin)
+static int hide_space_warp = 0;
 static int controller_fix = 1;
 static int swapchain_fix = 1;
 static int layer_fix = 1;
@@ -101,6 +133,7 @@ static void read_settings(const char *path) {
    while (fgets(line, sizeof(line), f)) {
        if (sscanf(line, "scale=%f", &value) == 1 && value >= 0.5f && value <= 2.0f) scale = value;
        if (sscanf(line, "foveation_fix=%f", &value) == 1) foveation_fix = value != 0;
+        if (sscanf(line, "hide_space_warp=%f", &value) == 1) hide_space_warp = value != 0;
        if (sscanf(line, "controller_fix=%f", &value) == 1) controller_fix = value != 0;
        if (sscanf(line, "swapchain_fix=%f", &value) == 1) swapchain_fix = value != 0;
        if (sscanf(line, "layer_fix=%f", &value) == 1) layer_fix = value != 0;
@@ -118,6 +151,9 @@ static void read_settings(const char *path) {
        if (sscanf(line, "scene_depth=%f", &value) == 1 && value > 0.5f && value < 20.0f) scene_depth = value;
        if (sscanf(line, "controller_models=%f", &value) == 1) controller_models = value != 0;
        if (sscanf(line, "layer_debug=%f", &value) == 1) layer_debug = value != 0;
+        if (sscanf(line, "surface_emul=%f", &value) == 1) surface_emul = value != 0;
+        if (sscanf(line, "eye_debug=%f", &value) == 1) eye_debug = value != 0;
+        if (sscanf(line, "release_wait=%f", &value) == 1) release_wait = (int)value;
        if (sscanf(line, "profile_remap=%f", &value) == 1) profile_remap = value != 0;
        if (sscanf(line, "sync_guard=%f", &value) == 1) sync_guard = value != 0;
        if (sscanf(line, "stable_local=%f", &value) == 1) stable_local = value != 0;
@@ -169,6 +205,13 @@ static void initialize(void) {
    }
    const char *env = getenv("FRAMEBRIDGE_CONFIG");
    if (env && *env) read_settings(env);
+    if (eye_debug && *process && !strchr(process, '/')) {
+        snprintf(path, sizeof(path), "/sdcard/Android/data/%s/files/framebridge.log", process);
+        log_file = fopen(path, "a");
+    }
+    if (hide_space_warp) LOG("per-game: hide_space_warp=1 (XR_FB_space_warp hidden, space warp info removed)");
+    if (eye_debug || release_wait) LOG("per-game: eye_debug=%d release_wait=%d log_file=%s", eye_debug, release_wait,
+                                       log_file ? path : "none");
    if (controller_models && *process && !strchr(process, '/')) render_model_init(process);

    LOG("scale=%.2f foveation_fix=%d controller_fix=%d swapchain_fix=%d layer_fix=%d mutable_fix=%d swap_eyes=%d passthrough_emul=%d respace_kick=%d flip_quads=%d controller_models=%d loader=%s",
@@ -199,7 +242,10 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info

    int chained = 0, enabled = 0;
    for (const XrBaseInStructure *p = (const XrBaseInStructure *)info->next; p; p = p->next)
-        if (p->type == XR_TYPE_INSTANCE_CREATE_INFO_ANDROID_KHR) chained = 1;
+        if (p->type == XR_TYPE_INSTANCE_CREATE_INFO_ANDROID_KHR) {
+            chained = 1;
+            android_vm = ((const struct { XrStructureType type; const void *next; void *vm; void *activity; } *)p)->vm;
+        }
    for (uint32_t i = 0; i < info->enabledExtensionCount; ++i)
        if (!strcmp(info->enabledExtensionNames[i], "XR_KHR_android_create_instance")) enabled = 1;

@@ -229,6 +275,10 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
        int supported = !available;  // if we could not enumerate, pass everything through
        for (uint32_t j = 0; available && j < available_count && !supported; ++j)
            supported = !strcmp(available[j].extensionName, ext);
+        if (hide_space_warp && !strcmp(ext, "XR_FB_space_warp")) {
+            LOG("hide_space_warp: XR_FB_space_warp not enabled");
+            continue;
+        }
        if (supported) names[kept++] = ext;
        else if (scene_emul && is_scene_extension(ext)) {
            if (!emulate_scene) LOG("emulating Meta scene/spatial-entity extensions from the guardian bounds");
@@ -265,10 +315,11 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
    }
    no_equirect = !has_equirect; no_equirect2 = !has_equirect2; no_cylinder = !has_cylinder; no_cube = !has_cube;
    free(available);
+    mx_audio_initialize();
    XrResult result = fn(&fixed, instance);
    free(names);
    LOG("xrCreateInstance result=%d", result);
-    if (XR_SUCCEEDED(result)) active_instance = *instance;
+    if (XR_SUCCEEDED(result)) { active_instance = *instance; mx_audio_initialize(); }
    return result;
 }

@@ -420,6 +471,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrDestroySwapchain(XrSwapchain swapchain) {
    PFN_xrDestroySwapchain fn = (PFN_xrDestroySwapchain)lookup(active_instance, "xrDestroySwapchain");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
    forget_swapchain(swapchain);
+    surf_on_destroy(swapchain);
    flip_on_destroy(swapchain);
    emul_on_destroy_swapchain(swapchain);
    if (equirect_emul && emul_is_virtual(swapchain)) { emul_virtual_destroy(swapchain); return XR_SUCCESS; }
@@ -673,6 +725,8 @@ XRAPI_ATTR XrResult XRAPI_CALL xrDestroySpace(XrSpace space) {

 #include "session_fixes.c"
 #include "layer_emul_gl.c"
+#include "surface_swapchain.c"
+#include "eye_debug.c"

 XRAPI_ATTR XrResult XRAPI_CALL xrCreateSession(XrInstance instance, const XrSessionCreateInfo *info, XrSession *session) {
    PFN_xrCreateSession fn = (PFN_xrCreateSession)lookup(instance, "xrCreateSession");
@@ -726,6 +780,7 @@ static XrSession focused_session = XR_NULL_HANDLE;
 static int kicks_pending = -1;  // -1: not yet armed

 XRAPI_ATTR XrResult XRAPI_CALL xrPollEvent(XrInstance instance, XrEventDataBuffer *event) {
+    mx_audio_initialize();
    PFN_xrPollEvent fn = (PFN_xrPollEvent)lookup(instance, "xrPollEvent");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
    if (emulate_scene && event) {
@@ -864,6 +919,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrLocateViews(XrSession session, const XrViewLoca
 XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInfo *info) {
    PFN_xrEndFrame fn = (PFN_xrEndFrame)lookup(active_instance, "xrEndFrame");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (eye_debug) eye_debug_end_frame(session, info);
    {   // frame pacing statistics every ~5 s: fps and submitted-vs-predicted display time
        static struct timespec start;
        static int frames;
@@ -969,6 +1025,13 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
                continue;
            }
        }
+        if (layer && (layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD || layer->type == XR_TYPE_COMPOSITION_LAYER_CYLINDER_KHR) &&
+            !surf_prepare_layer(layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD
+                                    ? ((const XrCompositionLayerQuad *)layer)->subImage.swapchain
+                                    : ((const XrCompositionLayerCylinderKHR *)layer)->subImage.swapchain)) {
+            ++dropped;  // an emulated video surface without a frame yet
+            continue;
+        }
        if (!layer || (layer_fix && !layer_usable(layer))) { ++dropped; continue; }
        if (layer->type == XR_TYPE_COMPOSITION_LAYER_QUAD) {
            const XrCompositionLayerQuad *flipped = flip_quad(session, (const XrCompositionLayerQuad *)layer, &quads[count]);
@@ -1005,6 +1068,31 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
            if (!logged++) LOG("strip_depth: removed depth info from projection layer");
            ++swapped;
        }
+        if (hide_space_warp && layer->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
+            ((const XrCompositionLayerProjection *)layer)->viewCount == 2) {
+            // The game may still attach XrCompositionLayerSpaceWarpInfoFB (1000171000) to its views: OVRPort's
+            // dispatcher offers XR_FB_space_warp itself even when hidden here. Unlink it (keeping what follows when
+            // it heads the chain, else the whole chain) so the runtime never uses the motion vectors.
+            const XrCompositionLayerProjection *src = (const XrCompositionLayerProjection *)layer;
+            int found = 0;
+            for (uint32_t v = 0; v < 2; ++v)
+                for (const XrBaseInStructure *n = (const XrBaseInStructure *)src->views[v].next; n; n = n->next)
+                    found |= n->type == 1000171000;
+            if (found) {
+                if (layer != (const XrCompositionLayerBaseHeader *)&projections[count]) projections[count] = *src;
+                for (uint32_t v = 0; v < 2; ++v) {
+                    views[count][v] = src->views[v];
+                    const XrBaseInStructure *head = (const XrBaseInStructure *)src->views[v].next;
+                    if (head && head->type == 1000171000) views[count][v].next = head->next;
+                    else if (head) views[count][v].next = NULL;
+                }
+                projections[count].views = views[count];
+                layer = (const XrCompositionLayerBaseHeader *)&projections[count];
+                static int logged;
+                if (!logged++) LOG("hide_space_warp: removed space warp info from the eye images");
+                ++swapped;
+            }
+        }
        if (swap_eyes && layer->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION &&
            ((const XrCompositionLayerProjection *)layer)->viewCount == 2) {
            // Show each eye the image the game rendered for it: keep poses/FOVs, swap sub-images.
@@ -1128,7 +1216,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateInstanceExtensionProperties(const char
        XR_NULL_HANDLE, "xrEnumerateInstanceExtensionProperties");
    if (!fn) return XR_ERROR_INITIALIZATION_FAILED;
    if (!count) return XR_ERROR_VALIDATION_FAILURE;
-    if ((!foveation_fix && !passthrough_emul && !scene_emul && !controller_models) || layer)
+    if ((!foveation_fix && !hide_space_warp && !passthrough_emul && !scene_emul && !controller_models) || layer)
        return fn(layer, capacity, count, properties);

    uint32_t total = 0;
@@ -1145,6 +1233,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEnumerateInstanceExtensionProperties(const char
        if (!strcmp(all[i].extensionName, "XR_FB_passthrough")) runtime_has_fb_passthrough = 1;
        if (!strcmp(all[i].extensionName, XR_FB_RENDER_MODEL_EXTENSION_NAME)) runtime_has_render_model = 1;
        if (foveation_fix && strstr(all[i].extensionName, "foveation")) continue;
+        if (hide_space_warp && !strcmp(all[i].extensionName, "XR_FB_space_warp")) continue;
        if (properties && kept < capacity) properties[kept] = all[i];
        ++kept;
    }
@@ -1241,6 +1330,8 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
    if (layer_debug || refresh_rate > 0) {
        HOOK_AS(xrRequestDisplayRefreshRateFB, hook_request_refresh_rate)
    }
+    if (surface_emul) HOOK_AS(xrCreateSwapchainAndroidSurfaceKHR, hook_xrCreateSwapchainAndroidSurfaceKHR)
+    if (eye_debug || release_wait) HOOK_AS(xrReleaseSwapchainImage, eye_hook_xrReleaseSwapchainImage)
    if (sync_guard || layer_debug) HOOK_AS(xrSyncActions, hook_xrSyncActions)
    if (layer_debug) HOOK_AS(xrGetActionStateBoolean, hook_xrGetActionStateBoolean)
    if (layer_debug || aim_correction_on() || profile_remap)
@@ -0,0 +1,510 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Included by frame_adapter.c (after flip_vk.c and layer_emul_gl.c). Emulates XR_KHR_android_surface_swapchain,
+// which the Frame's runtime lists but answers with XR_ERROR_FUNCTION_UNSUPPORTED. Games use it to play a video on a
+// panel (OVROverlay "external surface", Android MediaPlayer/ExoPlayer drawing into a Surface): without it the panel has
+// no image and is dropped, and a game that waits for its intro video shows black forever (I Am Monkey).
+//
+//  * xrCreateSwapchainAndroidSurfaceKHR: the runtime first; if it can't, an ordinary runtime swapchain of the same size
+//    (sRGB RGBA8) is created and returned as the game's swapchain, and the game gets a real android.view.Surface from a
+//    SurfaceTexture owned by a worker thread (own EGL context; JNI through the JavaVM of xrCreateInstance).
+//  * The worker latches each new video frame (any size, YUV: SurfaceTexture samples it), draws it into an RGBA8
+//    texture of the swapchain's size and reads it back (glReadPixels) into a shared buffer.
+//  * xrEndFrame: a layer showing an emulated swapchain gets the newest frame uploaded first (Vulkan: staging buffer +
+//    copy on the session's queue; GLES: glTexSubImage2D in the app's context), then is submitted as usual.
+//  * Any failure: the call returns the runtime's own result (as before), so nothing gets worse.
+#include <jni.h>
+
+#define SURF_MAX 8
+
+typedef void *(*PFN_ASurfaceTexture_fromSurfaceTexture)(JNIEnv *, jobject);
+typedef int (*PFN_ASurfaceTexture_updateTexImage)(void *);
+typedef void (*PFN_ASurfaceTexture_getTransformMatrix)(void *, float[16]);
+typedef int64_t (*PFN_ASurfaceTexture_getTimestamp)(void *);
+typedef void (*PFN_ASurfaceTexture_release)(void *);
+
+#define surf_vm ((JavaVM *)android_vm)  // from XrInstanceCreateInfoAndroidKHR (frame_adapter.c)
+
+typedef struct {
+    int used;
+    XrSwapchain handle;
+    uint32_t width, height;
+    // worker
+    pthread_t thread;
+    int stop, ready, failed;  // ready: surface handed out; failed: worker gave up
+    jobject surface;          // global ref, returned to the game
+    // newest frame (RGBA8, top row first), written by the worker
+    uint8_t *pixels;
+    uint64_t seq;             // bumps with every new frame
+    int64_t frames;
+    // upload side (app render thread)
+    uint64_t uploaded_seq;
+    int uploads, upload_failures, has_content;
+    VkImage vk_images[MAX_IMAGES];
+    uint32_t gl_images[MAX_IMAGES];
+    uint32_t image_count;
+    VkBuffer staging;
+    VkDeviceMemory staging_memory;
+    void *staging_map;
+    VkCommandPool pool;  // own command buffer + fence: uploads never wait for the GPU in xrEndFrame
+    VkCommandBuffer cmd;
+    VkFence fence;
+    int in_flight;      // a copy was submitted and its fence not yet seen signalled
+} surf_swapchain;
+
+static pthread_mutex_t surf_lock = PTHREAD_MUTEX_INITIALIZER;
+static pthread_cond_t surf_cond = PTHREAD_COND_INITIALIZER;
+static surf_swapchain surfs[SURF_MAX];
+static int surf_vulkan;  // the session is Vulkan (else GLES)
+
+static surf_swapchain *surf_find(XrSwapchain handle) {
+    for (int i = 0; i < SURF_MAX; ++i)
+        if (surfs[i].used && surfs[i].handle == handle) return &surfs[i];
+    return NULL;
+}
+
+// ---------------------------------------------------------------- worker: SurfaceTexture -> RGBA pixels
+static const char *surf_vs = "#version 300 es\nout vec2 uv;\nvoid main() {\n"
+    "  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));\n"
+    "  uv = p; gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);\n}\n";
+// window row 0 (glReadPixels' first row) must hold the image's top: sample t = 1 - y (SurfaceTexture t=0 is the bottom)
+static const char *surf_fs = "#version 300 es\n#extension GL_OES_EGL_image_external_essl3 : require\n"
+    "precision mediump float;\nuniform samplerExternalOES tex;\nuniform mat4 st;\nin vec2 uv;\nout vec4 color;\n"
+    "void main() { color = texture(tex, (st * vec4(uv.x, 1.0 - uv.y, 0.0, 1.0)).xy); }\n";
+
+typedef void (*PFN_glReadPixels_)(GLint, GLint, GLsizei, GLsizei, GLenum, GLenum, void *);
+typedef void (*PFN_glTexParameteri_)(GLenum, GLenum, GLint);
+typedef void (*PFN_glUniformMatrix4fv_)(GLint, GLsizei, GLboolean, const GLfloat *);
+typedef void (*PFN_glPixelStorei_)(GLenum, GLint);
+typedef void (*PFN_glTexSubImage2D_)(GLenum, GLint, GLint, GLint, GLsizei, GLsizei, GLenum, GLenum, const void *);
+typedef EGLDisplay (*PFN_eglGetDisplay_)(EGLNativeDisplayType);
+typedef EGLBoolean (*PFN_eglInitialize_)(EGLDisplay, EGLint *, EGLint *);
+static PFN_glReadPixels_ s_glReadPixels;
+static PFN_glTexParameteri_ s_glTexParameteri;
+static PFN_glUniformMatrix4fv_ s_glUniformMatrix4fv;
+static PFN_glPixelStorei_ s_glPixelStorei;
+static PFN_glTexSubImage2D_ s_glTexSubImage2D;
+static PFN_eglGetDisplay_ s_eglGetDisplay;
+static PFN_eglInitialize_ s_eglInitialize;
+static PFN_ASurfaceTexture_fromSurfaceTexture s_ast_from;
+static PFN_ASurfaceTexture_updateTexImage s_ast_update;
+static PFN_ASurfaceTexture_getTransformMatrix s_ast_matrix;
+static PFN_ASurfaceTexture_getTimestamp s_ast_timestamp;
+static PFN_ASurfaceTexture_release s_ast_release;
+
+static int surf_load(void) {
+    static int state;  // 0 untried, 1 ok, -1 failed
+    if (state) return state > 0;
+    state = -1;
+    if (!emul_load_gl()) { LOG("surface_emul: EGL/GLES not available"); return 0; }
+    void *egl = dlopen("libEGL.so", RTLD_NOW | RTLD_LOCAL), *gles = dlopen("libGLESv3.so", RTLD_NOW | RTLD_LOCAL);
+    void *android = dlopen("libandroid.so", RTLD_NOW | RTLD_LOCAL);
+    if (!egl || !gles || !android) { LOG("surface_emul: libEGL/libGLESv3/libandroid missing"); return 0; }
+    s_glReadPixels = (PFN_glReadPixels_)dlsym(gles, "glReadPixels");
+    s_glTexParameteri = (PFN_glTexParameteri_)dlsym(gles, "glTexParameteri");
+    s_glUniformMatrix4fv = (PFN_glUniformMatrix4fv_)dlsym(gles, "glUniformMatrix4fv");
+    s_glPixelStorei = (PFN_glPixelStorei_)dlsym(gles, "glPixelStorei");
+    s_glTexSubImage2D = (PFN_glTexSubImage2D_)dlsym(gles, "glTexSubImage2D");
+    s_eglGetDisplay = (PFN_eglGetDisplay_)dlsym(egl, "eglGetDisplay");
+    s_eglInitialize = (PFN_eglInitialize_)dlsym(egl, "eglInitialize");
+    s_ast_from = (PFN_ASurfaceTexture_fromSurfaceTexture)dlsym(android, "ASurfaceTexture_fromSurfaceTexture");
+    s_ast_update = (PFN_ASurfaceTexture_updateTexImage)dlsym(android, "ASurfaceTexture_updateTexImage");
+    s_ast_matrix = (PFN_ASurfaceTexture_getTransformMatrix)dlsym(android, "ASurfaceTexture_getTransformMatrix");
+    s_ast_timestamp = (PFN_ASurfaceTexture_getTimestamp)dlsym(android, "ASurfaceTexture_getTimestamp");
+    s_ast_release = (PFN_ASurfaceTexture_release)dlsym(android, "ASurfaceTexture_release");
+    if (!s_glReadPixels || !s_glTexParameteri || !s_glUniformMatrix4fv || !s_glPixelStorei || !s_glTexSubImage2D ||
+        !s_eglGetDisplay || !s_eglInitialize || !s_ast_from || !s_ast_update || !s_ast_matrix || !s_ast_timestamp ||
+        !s_ast_release) {
+        LOG("surface_emul: a GL/EGL/ASurfaceTexture function is missing");
+        return 0;
+    }
+    state = 1;
+    return 1;
+}
+
+static void surf_fail(surf_swapchain *s, const char *why) {
+    LOG("surface_emul: %s", why);
+    pthread_mutex_lock(&surf_lock);
+    s->failed = 1;
+    pthread_cond_broadcast(&surf_cond);
+    pthread_mutex_unlock(&surf_lock);
+}
+
+static void *surf_worker(void *arg) {
+    surf_swapchain *s = arg;
+    JNIEnv *env = NULL;
+    if ((*surf_vm)->AttachCurrentThread(surf_vm, &env, NULL) != JNI_OK || !env) { surf_fail(s, "no JNI env"); return NULL; }
+    EGLDisplay dpy = s_eglGetDisplay(EGL_DEFAULT_DISPLAY);
+    EGLint cfg_attribs[] = {EGL_RENDERABLE_TYPE, 0x40 /* EGL_OPENGL_ES3_BIT */, EGL_SURFACE_TYPE, EGL_PBUFFER_BIT,
+                            EGL_RED_SIZE, 8, EGL_GREEN_SIZE, 8, EGL_BLUE_SIZE, 8, EGL_ALPHA_SIZE, 8, EGL_NONE};
+    EGLConfig config = NULL;
+    EGLint n = 0, ctx_attribs[] = {EGL_CONTEXT_CLIENT_VERSION, 3, EGL_NONE}, pb[] = {EGL_WIDTH, 16, EGL_HEIGHT, 16, EGL_NONE};
+    EGLContext ctx = EGL_NO_CONTEXT;
+    EGLSurface pbuf = EGL_NO_SURFACE;
+    void *ast = NULL;
+    jobject st_local = NULL, st_global = NULL;
+    GLuint ext_tex = 0, rgba_tex = 0, fbo = 0, vao = 0, program = 0;
+    if (dpy == EGL_NO_DISPLAY || !s_eglInitialize(dpy, NULL, NULL) || !p_eglChooseConfig(dpy, cfg_attribs, &config, 1, &n) ||
+        n < 1 || (ctx = p_eglCreateContext(dpy, config, EGL_NO_CONTEXT, ctx_attribs)) == EGL_NO_CONTEXT ||
+        (pbuf = p_eglCreatePbufferSurface(dpy, config, pb)) == EGL_NO_SURFACE || !p_eglMakeCurrent(dpy, pbuf, pbuf, ctx)) {
+        surf_fail(s, "EGL context failed");
+        goto out;
+    }
+    // the SurfaceTexture's external texture, and the RGBA target the frames are drawn into
+    p_glGenTextures(1, &ext_tex);
+    p_glBindTexture(0x8D65 /* GL_TEXTURE_EXTERNAL_OES */, ext_tex);
+    s_glTexParameteri(0x8D65, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
+    s_glTexParameteri(0x8D65, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
+    p_glGenTextures(1, &rgba_tex);
+    p_glBindTexture(GL_TEXTURE_2D, rgba_tex);
+    p_glTexStorage2D(GL_TEXTURE_2D, 1, GL_RGBA8, (GLsizei)s->width, (GLsizei)s->height);
+    p_glGenFramebuffers(1, &fbo);
+    p_glBindFramebuffer(GL_FRAMEBUFFER, fbo);
+    p_glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, rgba_tex, 0);
+    if (p_glCheckFramebufferStatus(GL_FRAMEBUFFER) != GL_FRAMEBUFFER_COMPLETE) { surf_fail(s, "framebuffer incomplete"); goto out; }
+    {
+        GLuint v = emul_compile(GL_VERTEX_SHADER, "", surf_vs), f = emul_compile(GL_FRAGMENT_SHADER, "", surf_fs);
+        if (!v || !f) { surf_fail(s, "shader compile failed"); goto out; }
+        program = p_glCreateProgram();
+        p_glAttachShader(program, v);
+        p_glAttachShader(program, f);
+        p_glLinkProgram(program);
+        GLint ok = 0;
+        p_glGetProgramiv(program, GL_LINK_STATUS, &ok);
+        if (!ok) { surf_fail(s, "program link failed"); goto out; }
+    }
+    p_glGenVertexArrays(1, &vao);
+    // android.graphics.SurfaceTexture(texName) + android.view.Surface(SurfaceTexture)
+    {
+        jclass st_class = (*env)->FindClass(env, "android/graphics/SurfaceTexture");
+        jclass surface_class = (*env)->FindClass(env, "android/view/Surface");
+        if (!st_class || !surface_class) { (*env)->ExceptionClear(env); surf_fail(s, "SurfaceTexture/Surface class missing"); goto out; }
+        jmethodID st_init = (*env)->GetMethodID(env, st_class, "<init>", "(I)V");
+        jmethodID st_size = (*env)->GetMethodID(env, st_class, "setDefaultBufferSize", "(II)V");
+        jmethodID surface_init = (*env)->GetMethodID(env, surface_class, "<init>", "(Landroid/graphics/SurfaceTexture;)V");
+        st_local = (*env)->NewObject(env, st_class, st_init, (jint)ext_tex);
+        if (!st_local || (*env)->ExceptionCheck(env)) { (*env)->ExceptionClear(env); surf_fail(s, "new SurfaceTexture failed"); goto out; }
+        (*env)->CallVoidMethod(env, st_local, st_size, (jint)s->width, (jint)s->height);
+        jobject surface_local = (*env)->NewObject(env, surface_class, surface_init, st_local);
+        if (!surface_local || (*env)->ExceptionCheck(env)) { (*env)->ExceptionClear(env); surf_fail(s, "new Surface failed"); goto out; }
+        st_global = (*env)->NewGlobalRef(env, st_local);
+        ast = s_ast_from(env, st_local);
+        if (!ast) { surf_fail(s, "ASurfaceTexture_fromSurfaceTexture failed"); goto out; }
+        pthread_mutex_lock(&surf_lock);
+        s->surface = (*env)->NewGlobalRef(env, surface_local);
+        s->ready = 1;
+        pthread_cond_broadcast(&surf_cond);
+        pthread_mutex_unlock(&surf_lock);
+        (*env)->DeleteLocalRef(env, surface_local);
+    }
+    LOG("surface_emul: Surface ready for %ux%u swapchain %p", s->width, s->height, (void *)(uintptr_t)s->handle);
+    {
+        GLint u_tex = p_glGetUniformLocation(program, "tex"), u_st = p_glGetUniformLocation(program, "st");
+        size_t bytes = (size_t)s->width * s->height * 4;
+        uint8_t *buf = malloc(bytes);
+        int64_t last_ts = -1, window_frames = 0, window_start = 0;
+        while (!s->stop && buf) {
+            struct timespec pause = {0, 8000000};  // ~120 checks a second: well above video frame rates
+            nanosleep(&pause, NULL);
+            if (s_ast_update(ast) != 0) continue;
+            int64_t ts = s_ast_timestamp(ast);
+            if (ts == last_ts) continue;  // no new frame latched
+            last_ts = ts;
+            float m[16];
+            s_ast_matrix(ast, m);
+            p_glBindFramebuffer(GL_FRAMEBUFFER, fbo);
+            p_glViewport(0, 0, (GLsizei)s->width, (GLsizei)s->height);
+            p_glUseProgram(program);
+            p_glActiveTexture(GL_TEXTURE0);
+            p_glBindTexture(0x8D65, ext_tex);
+            p_glUniform1i(u_tex, 0);
+            s_glUniformMatrix4fv(u_st, 1, GL_FALSE, m);
+            p_glBindVertexArray(vao);
+            p_glDrawArrays(GL_TRIANGLES, 0, 3);
+            s_glPixelStorei(GL_PACK_ALIGNMENT, 1);
+            s_glReadPixels(0, 0, (GLsizei)s->width, (GLsizei)s->height, GL_RGBA, GL_UNSIGNED_BYTE, buf);
+            GLenum err = p_glGetError();
+            pthread_mutex_lock(&surf_lock);
+            if (!err && s->pixels) { memcpy(s->pixels, buf, bytes); s->seq++; s->frames++; }
+            pthread_mutex_unlock(&surf_lock);
+            if (err) { static int warned; if (warned++ < 5) LOG("surface_emul: GL error 0x%x drawing a frame", err); }
+            int64_t now = monotonic_ns();
+            if (!window_start) {
+                window_start = now;
+                LOG("surface_emul: first video frame (timestamp %lld)", (long long)ts);
+            }
+            if (++window_frames && now - window_start > 5000000000ll) {
+                LOG("surface_emul: %.1f video frames/s, %d uploaded, %d upload failures", window_frames * 1e9 / (now - window_start),
+                    s->uploads, s->upload_failures);
+                window_frames = 0;
+                window_start = now;
+            }
+        }
+        free(buf);
+    }
+out:
+    if (ast) s_ast_release(ast);
+    if (st_global) (*env)->DeleteGlobalRef(env, st_global);
+    if (ctx != EGL_NO_CONTEXT) { p_eglMakeCurrent(dpy, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT); p_eglDestroyContext(dpy, ctx); }
+    if (pbuf != EGL_NO_SURFACE) p_eglDestroySurface(dpy, pbuf);
+    (*surf_vm)->DetachCurrentThread(surf_vm);
+    return NULL;
+}
+
+// ---------------------------------------------------------------- uploads (app render thread)
+static struct {
+    PFN_vkCreateBuffer CreateBuffer;
+    PFN_vkGetBufferMemoryRequirements GetBufferMemoryRequirements;
+    PFN_vkAllocateMemory AllocateMemory;
+    PFN_vkBindBufferMemory BindBufferMemory;
+    PFN_vkMapMemory MapMemory;
+    PFN_vkCmdCopyBufferToImage CmdCopyBufferToImage;
+    PFN_vkCmdClearColorImage CmdClearColorImage;
+    PFN_vkGetPhysicalDeviceMemoryProperties GetPhysicalDeviceMemoryProperties;
+    PFN_vkGetFenceStatus GetFenceStatus;
+    int state;
+} svk;
+
+static int surf_vk_ready(void) {
+    if (svk.state) return svk.state > 0;
+    svk.state = -1;
+    if (!vk_ready()) return 0;
+#define SDEV(name) svk.name = (PFN_vk##name)vk.GetDeviceProcAddr(vk.device, "vk" #name); if (!svk.name) return 0;
+    SDEV(CreateBuffer) SDEV(GetBufferMemoryRequirements) SDEV(AllocateMemory) SDEV(BindBufferMemory) SDEV(MapMemory)
+    SDEV(CmdCopyBufferToImage) SDEV(CmdClearColorImage) SDEV(GetFenceStatus)
+#undef SDEV
+    void *lib = dlopen("libvulkan.so", RTLD_NOW | RTLD_LOCAL);
+    PFN_vkGetInstanceProcAddr gipa = lib ? (PFN_vkGetInstanceProcAddr)dlsym(lib, "vkGetInstanceProcAddr") : NULL;
+    svk.GetPhysicalDeviceMemoryProperties = gipa ? (PFN_vkGetPhysicalDeviceMemoryProperties)gipa(vk.instance,
+        "vkGetPhysicalDeviceMemoryProperties") : NULL;
+    if (!svk.GetPhysicalDeviceMemoryProperties) return 0;
+    svk.state = 1;
+    return 1;
+}
+
+static void surf_barrier(VkCommandBuffer cmd, VkImage image, VkImageLayout from, VkImageLayout to,
+                         VkAccessFlags src_access, VkAccessFlags dst_access) {
+    VkImageMemoryBarrier b = {VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER, NULL, src_access, dst_access, from, to,
+                              VK_QUEUE_FAMILY_IGNORED, VK_QUEUE_FAMILY_IGNORED, image,
+                              {VK_IMAGE_ASPECT_COLOR_BIT, 0, 1, 0, 1}};
+    vk.CmdPipelineBarrier(cmd, VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, 0, 0, NULL, 0,
+                          NULL, 1, &b);
+}
+
+static int surf_staging(surf_swapchain *s) {
+    if (s->staging_map) return 1;
+    VkCommandPoolCreateInfo pool = {VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO, NULL,
+                                    VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT, vk.family};
+    if (vk.CreateCommandPool(vk.device, &pool, NULL, &s->pool) != VK_SUCCESS) return 0;
+    VkCommandBufferAllocateInfo alloc = {VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO, NULL, s->pool,
+                                         VK_COMMAND_BUFFER_LEVEL_PRIMARY, 1};
+    if (vk.AllocateCommandBuffers(vk.device, &alloc, &s->cmd) != VK_SUCCESS) return 0;
+    VkFenceCreateInfo fence = {VK_STRUCTURE_TYPE_FENCE_CREATE_INFO, NULL, 0};
+    if (vk.CreateFence(vk.device, &fence, NULL, &s->fence) != VK_SUCCESS) return 0;
+    VkBufferCreateInfo bi = {VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO, NULL, 0, (VkDeviceSize)s->width * s->height * 4,
+                             VK_BUFFER_USAGE_TRANSFER_SRC_BIT, VK_SHARING_MODE_EXCLUSIVE, 0, NULL};
+    if (svk.CreateBuffer(vk.device, &bi, NULL, &s->staging) != VK_SUCCESS) return 0;
+    VkMemoryRequirements req;
+    svk.GetBufferMemoryRequirements(vk.device, s->staging, &req);
+    VkPhysicalDeviceMemoryProperties props;
+    svk.GetPhysicalDeviceMemoryProperties(vk.physical, &props);
+    uint32_t want = VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, type = UINT32_MAX;
+    for (uint32_t i = 0; i < props.memoryTypeCount && type == UINT32_MAX; ++i)
+        if ((req.memoryTypeBits & (1u << i)) && (props.memoryTypes[i].propertyFlags & want) == want) type = i;
+    if (type == UINT32_MAX) return 0;
+    VkMemoryAllocateInfo ai = {VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO, NULL, req.size, type};
+    if (svk.AllocateMemory(vk.device, &ai, NULL, &s->staging_memory) != VK_SUCCESS) return 0;
+    if (svk.BindBufferMemory(vk.device, s->staging, s->staging_memory, 0) != VK_SUCCESS) return 0;
+    return svk.MapMemory(vk.device, s->staging_memory, 0, VK_WHOLE_SIZE, 0, &s->staging_map) == VK_SUCCESS;
+}
+
+// Copy the newest frame (or black, the first time) into the next image of the runtime swapchain. Returns 1 if the
+// swapchain now has an image to show, -1 if the previous copy is still running (try next frame), 0 on failure.
+static int surf_upload(surf_swapchain *s, int black) {
+    PFN_xrAcquireSwapchainImage acquire = (PFN_xrAcquireSwapchainImage)lookup(active_instance, "xrAcquireSwapchainImage");
+    PFN_xrWaitSwapchainImage wait = (PFN_xrWaitSwapchainImage)lookup(active_instance, "xrWaitSwapchainImage");
+    PFN_xrReleaseSwapchainImage release = (PFN_xrReleaseSwapchainImage)lookup(active_instance, "xrReleaseSwapchainImage");
+    if (!acquire || !wait || !release || !s->image_count) return 0;
+    uint32_t index = 0;
+    XrSwapchainImageAcquireInfo ai = {XR_TYPE_SWAPCHAIN_IMAGE_ACQUIRE_INFO, NULL};
+    XrSwapchainImageWaitInfo wi = {XR_TYPE_SWAPCHAIN_IMAGE_WAIT_INFO, NULL, 100000000};
+    XrSwapchainImageReleaseInfo ri = {XR_TYPE_SWAPCHAIN_IMAGE_RELEASE_INFO, NULL};
+    if (surf_vulkan && s->in_flight) {  // the previous copy still reads the staging buffer: try again next frame
+        if (svk.GetFenceStatus(vk.device, s->fence) != VK_SUCCESS) return -1;
+        vk.ResetFences(vk.device, 1, &s->fence);
+        s->in_flight = 0;
+    }
+    if (XR_FAILED(acquire(s->handle, &ai, &index)) || index >= s->image_count) return 0;
+    if (XR_FAILED(wait(s->handle, &wi))) { release(s->handle, &ri); return 0; }
+    int ok = 0;
+    size_t bytes = (size_t)s->width * s->height * 4;
+    if (surf_vulkan) {
+        if (!black) {
+            pthread_mutex_lock(&surf_lock);
+            memcpy(s->staging_map, s->pixels, bytes);
+            pthread_mutex_unlock(&surf_lock);
+        }
+        VkImage img = s->vk_images[index];
+        VkCommandBufferBeginInfo begin = {VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO, NULL,
+                                          VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT, NULL};
+        VkCommandBuffer cmd = s->cmd;
+        vk.ResetCommandBuffer(cmd, 0);
+        vk.BeginCommandBuffer(cmd, &begin);
+        surf_barrier(cmd, img, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 0, VK_ACCESS_TRANSFER_WRITE_BIT);
+        if (black) {
+            VkClearColorValue c = {{0, 0, 0, 1}};
+            VkImageSubresourceRange r = {VK_IMAGE_ASPECT_COLOR_BIT, 0, 1, 0, 1};
+            svk.CmdClearColorImage(cmd, img, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, &c, 1, &r);
+        } else {
+            VkBufferImageCopy copy = {0, 0, 0, {VK_IMAGE_ASPECT_COLOR_BIT, 0, 0, 1}, {0, 0, 0}, {s->width, s->height, 1}};
+            svk.CmdCopyBufferToImage(cmd, s->staging, img, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1, &copy);
+        }
+        surf_barrier(cmd, img, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
+                VK_ACCESS_TRANSFER_WRITE_BIT, VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT);
+        vk.EndCommandBuffer(cmd);
+        VkSubmitInfo submit = {VK_STRUCTURE_TYPE_SUBMIT_INFO, NULL, 0, NULL, NULL, 1, &cmd, 0, NULL};
+        // released right after the submit: the runtime's own work on this queue runs after the copy
+        ok = vk.QueueSubmit(vk.queue, 1, &submit, s->fence) == VK_SUCCESS;
+        s->in_flight = ok;
+    } else if (!black) {  // GLES: the app's context is current on its render thread (xrEndFrame)
+        GLint prev_tex = 0, prev_align = 4, prev_unpack = 0;
+        p_glGetIntegerv(GL_TEXTURE_BINDING_2D, &prev_tex);
+        p_glGetIntegerv(GL_UNPACK_ALIGNMENT, &prev_align);
+        p_glGetIntegerv(0x88EF /* GL_PIXEL_UNPACK_BUFFER_BINDING */, &prev_unpack);
+        if (prev_unpack) { typedef void (*bb)(GLenum, GLuint); static bb bind; if (!bind) bind = (bb)dlsym(RTLD_DEFAULT, "glBindBuffer"); if (bind) bind(0x88EC, 0); }
+        p_glBindTexture(GL_TEXTURE_2D, s->gl_images[index]);
+        s_glPixelStorei(GL_UNPACK_ALIGNMENT, 1);
+        pthread_mutex_lock(&surf_lock);
+        s_glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, (GLsizei)s->width, (GLsizei)s->height, GL_RGBA, GL_UNSIGNED_BYTE, s->pixels);
+        pthread_mutex_unlock(&surf_lock);
+        ok = p_glGetError() == GL_NO_ERROR;
+        s_glPixelStorei(GL_UNPACK_ALIGNMENT, prev_align);
+        p_glBindTexture(GL_TEXTURE_2D, (GLuint)prev_tex);
+        if (prev_unpack) { typedef void (*bb)(GLenum, GLuint); static bb bind; if (!bind) bind = (bb)dlsym(RTLD_DEFAULT, "glBindBuffer"); if (bind) bind(0x88EC, (GLuint)prev_unpack); }
+    }
+    release(s->handle, &ri);
+    return ok;
+}
+
+// xrEndFrame: before a layer showing an emulated swapchain is submitted. Returns 0 if it has nothing to show yet.
+static int surf_prepare_layer(XrSwapchain handle) {
+    pthread_mutex_lock(&surf_lock);
+    surf_swapchain *s = surf_find(handle);
+    uint64_t seq = s ? s->seq : 0;
+    pthread_mutex_unlock(&surf_lock);
+    if (!s) return 1;  // not ours
+    if (seq != s->uploaded_seq) {
+        int r = surf_upload(s, 0);
+        if (r > 0) { s->uploaded_seq = seq; s->uploads++; s->has_content = 1; }
+        else if (r == 0 && s->upload_failures++ < 5) LOG("surface_emul: upload failed (swapchain %p)", (void *)(uintptr_t)handle);
+    }
+    return s->has_content;
+}
+
+// ---------------------------------------------------------------- the emulated entry points
+typedef XrResult (XRAPI_PTR *PFN_xrCreateSwapchainAndroidSurfaceKHR_)(XrSession, const XrSwapchainCreateInfo *,
+                                                                      XrSwapchain *, jobject *);
+
+static XRAPI_ATTR XrResult XRAPI_CALL hook_xrCreateSwapchainAndroidSurfaceKHR(XrSession session,
+        const XrSwapchainCreateInfo *info, XrSwapchain *swapchain, jobject *surface) {
+    PFN_xrCreateSwapchainAndroidSurfaceKHR_ fn =
+        (PFN_xrCreateSwapchainAndroidSurfaceKHR_)lookup(active_instance, "xrCreateSwapchainAndroidSurfaceKHR");
+    XrResult result = fn ? fn(session, info, swapchain, surface) : XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (result != XR_ERROR_FUNCTION_UNSUPPORTED || !info || !swapchain || !surface) return result;
+    LOG("surface_emul: runtime has no Android surface swapchains: emulating %ux%u (vm %s, %s session)", info->width,
+        info->height, surf_vm ? "ok" : "MISSING", vk.device ? "Vulkan" : "GLES");
+    if (!surf_vm || !info->width || !info->height || !surf_load()) return result;
+    surf_vulkan = vk.device != VK_NULL_HANDLE;
+    if (surf_vulkan && !surf_vk_ready()) { LOG("surface_emul: Vulkan upload path unavailable"); return result; }
+    pthread_mutex_lock(&surf_lock);
+    surf_swapchain *s = NULL;
+    for (int i = 0; i < SURF_MAX && !s; ++i)
+        if (!surfs[i].used) s = &surfs[i];
+    if (s) { memset(s, 0, sizeof(*s)); s->used = 1; }
+    pthread_mutex_unlock(&surf_lock);
+    if (!s) { LOG("surface_emul: too many surface swapchains"); return result; }
+    // the runtime swapchain the game gets instead (what its layer will show)
+    PFN_xrCreateSwapchain create = (PFN_xrCreateSwapchain)lookup(active_instance, "xrCreateSwapchain");
+    PFN_xrEnumerateSwapchainImages enumerate =
+        (PFN_xrEnumerateSwapchainImages)lookup(active_instance, "xrEnumerateSwapchainImages");
+    PFN_xrDestroySwapchain destroy = (PFN_xrDestroySwapchain)lookup(active_instance, "xrDestroySwapchain");
+    XrSwapchainCreateInfo ci = {XR_TYPE_SWAPCHAIN_CREATE_INFO, NULL, 0,
+                                XR_SWAPCHAIN_USAGE_COLOR_ATTACHMENT_BIT | XR_SWAPCHAIN_USAGE_TRANSFER_DST_BIT |
+                                XR_SWAPCHAIN_USAGE_SAMPLED_BIT,
+                                surf_vulkan ? 43 /* VK_FORMAT_R8G8B8A8_SRGB */ : 0x8C43 /* GL_SRGB8_ALPHA8 */,
+                                1, info->width, info->height, 1, 1, 1};
+    XrSwapchain handle = XR_NULL_HANDLE;
+    XrResult cr = create && enumerate ? create(session, &ci, &handle) : XR_ERROR_FUNCTION_UNSUPPORTED;
+    if (XR_FAILED(cr)) {
+        LOG("surface_emul: xrCreateSwapchain failed %d", cr);
+        pthread_mutex_lock(&surf_lock); s->used = 0; pthread_mutex_unlock(&surf_lock);
+        return result;
+    }
+    s->handle = handle;
+    s->width = info->width;
+    s->height = info->height;
+    s->pixels = calloc((size_t)s->width * s->height, 4);
+    uint32_t n = 0;
+    if (surf_vulkan) {
+        XrSwapchainImageVulkanKHR images[MAX_IMAGES];
+        for (int i = 0; i < MAX_IMAGES; ++i) images[i] = (XrSwapchainImageVulkanKHR){XR_TYPE_SWAPCHAIN_IMAGE_VULKAN_KHR, NULL, VK_NULL_HANDLE};
+        if (XR_SUCCEEDED(enumerate(handle, MAX_IMAGES, &n, (XrSwapchainImageBaseHeader *)images)))
+            for (uint32_t i = 0; i < n && i < MAX_IMAGES; ++i) s->vk_images[i] = images[i].image;
+    } else {
+        emul_gles_image images[MAX_IMAGES];
+        for (int i = 0; i < MAX_IMAGES; ++i) images[i] = (emul_gles_image){XR_TYPE_SWAPCHAIN_IMAGE_OPENGL_ES_KHR, NULL, 0};
+        if (XR_SUCCEEDED(enumerate(handle, MAX_IMAGES, &n, (XrSwapchainImageBaseHeader *)images)))
+            for (uint32_t i = 0; i < n && i < MAX_IMAGES; ++i) s->gl_images[i] = images[i].image;
+    }
+    s->image_count = n < MAX_IMAGES ? n : MAX_IMAGES;
+    int setup_ok = s->pixels && s->image_count && (!surf_vulkan || surf_staging(s));
+    if (setup_ok) {
+        pthread_mutex_lock(&surf_lock);
+        setup_ok = pthread_create(&s->thread, NULL, surf_worker, s) == 0;
+        struct timespec until;
+        clock_gettime(CLOCK_REALTIME, &until);
+        until.tv_sec += 3;
+        while (setup_ok && !s->ready && !s->failed && pthread_cond_timedwait(&surf_cond, &surf_lock, &until) == 0) {}
+        setup_ok = setup_ok && s->ready;
+        pthread_mutex_unlock(&surf_lock);
+    }
+    if (!setup_ok) {
+        LOG("surface_emul: setup failed (images %u, pixels %d): the panel stays empty", s->image_count, s->pixels != NULL);
+        if (s->thread) { s->stop = 1; pthread_join(s->thread, NULL); }
+        if (destroy) destroy(handle);
+        free(s->pixels);
+        pthread_mutex_lock(&surf_lock); s->used = 0; pthread_mutex_unlock(&surf_lock);
+        return result;
+    }
+    // something valid to show from the first frame on (Vulkan: a black image; GLES: the layer waits for a frame)
+    if (surf_vulkan && surf_upload(s, 1) > 0) s->has_content = 1;
+    remember_swapchain(handle);
+    *swapchain = handle;
+    *surface = s->surface;
+    LOG("surface_emul: emulated Android surface swapchain %p (%u images)", (void *)(uintptr_t)handle, s->image_count);
+    return XR_SUCCESS;
+}
+
+// xrDestroySwapchain: an emulated swapchain's worker and surface go with it
+static void surf_on_destroy(XrSwapchain handle) {
+    pthread_mutex_lock(&surf_lock);
+    surf_swapchain *s = surf_find(handle);
+    pthread_mutex_unlock(&surf_lock);
+    if (!s) return;
+    s->stop = 1;
+    if (s->thread) pthread_join(s->thread, NULL);
+    if (surf_vm && s->surface) {
+        JNIEnv *env = NULL;
+        int attached = 0;
+        if ((*surf_vm)->GetEnv(surf_vm, (void **)&env, JNI_VERSION_1_6) != JNI_OK) {
+            attached = (*surf_vm)->AttachCurrentThread(surf_vm, &env, NULL) == JNI_OK;
+        }
+        if (env) (*env)->DeleteGlobalRef(env, s->surface);
+        if (attached) (*surf_vm)->DetachCurrentThread(surf_vm);
+    }
+    pthread_mutex_lock(&surf_lock);
+    free(s->pixels);
+    s->pixels = NULL;
+    s->used = 0;
+    pthread_mutex_unlock(&surf_lock);
+    LOG("surface_emul: destroyed %p", (void *)(uintptr_t)handle);
+}
@@ -5,12 +5,12 @@ Everything is fetched on demand into native/.cache (git-ignored):
  - Android NDK r27c (27.2.12479018) from Google's repository (checksummed via repository2-3.xml)
  - OpenXR headers at the commits each component was written against (KhronosGroup/OpenXR-SDK)
  - Temurin JDK 21 (javac) and Android build-tools (d8) for the Java stub classes
-Then builds: FrameBridge adapter (arm64 + arm32), VrApi bridge, platform compat, GL shim, oculusos stub dex, the
+Then builds: FrameBridge adapter (arm64 + arm32), VrApi bridge, platform compat, language packs, GL shim, oculusos stub dex, the
 timefix OpenXR layer for Proton games (linux-arm64, glibc; the NDK's clang builds it freestanding), the
 OculusHMDConnected helper for Rift games under Proton (win-x64 PE; the NDK's clang + lld-link, no Windows SDK), and
 rewrites artifacts/SHA256SUMS. Run `frameport parity` afterwards to see which games change.

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

@@ -223,6 +223,15 @@ def build_compat(tc: Path):
         "-Wl,--version-script=exports.map", "-o", ART / "arm64-v8a/libovrplatformcompat.so"], cwd=src)


+def build_langpack(tc: Path):
+    """Language packs from the game's files (see langpack/langpack.c): DT_NEEDED-injected into overport's platform loader."""
+    src = HERE / "langpack"
+    run([exe(tc, "aarch64-linux-android29-clang"), "-shared", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror",
+         "-fvisibility=hidden", f"-ffile-prefix-map={src}=native/langpack", "-Wl,--no-undefined",
+         "-Wl,-z,max-page-size=16384", "-Wl,-soname,libfp_langpack.so", "langpack.c", "-ldl", "-llog",
+         "-o", ART / "arm64-v8a/libfp_langpack.so"], cwd=src)
+
+
 def build_glshim(tc: Path):
    src = HERE / "glshim"
    run([exe(tc, "aarch64-linux-android29-clang"), "-shared", "-fPIC", "-O2", "-Wall", "-Wextra", "-Werror",
@@ -299,7 +308,7 @@ def write_sums():

 def main():
    ap = argparse.ArgumentParser()
-    ap.add_argument("--only", default="adapter,bridge,compat,glshim,dex,xrlayer,oculushmd,xrshim,vkshim,ovrpshim,vrsettings")
+    ap.add_argument("--only", default="adapter,bridge,compat,langpack,glshim,dex,xrlayer,oculushmd,xrshim,vkshim,ovrpshim,vrsettings")
    ap.add_argument("--ndk")
    args = ap.parse_args()
    parts = set(args.only.split(","))
@@ -307,11 +316,12 @@ def main():
        (ART / d).mkdir(parents=True, exist_ok=True)
    tc = clang_dir(ndk(args.ndk)) if parts - {"dex"} else None
    steps = {"adapter": lambda: build_adapter(tc), "bridge": lambda: build_bridge(tc), "compat": lambda: build_compat(tc),
+             "langpack": lambda: build_langpack(tc),
             "glshim": lambda: build_glshim(tc), "xrshim": lambda: build_xrshim(tc), "dex": build_dex, "xrlayer": lambda: build_xrlayer(tc),
             "oculushmd": lambda: build_oculushmd(tc), "vkshim": lambda: build_vkshim(tc),
             "ovrpshim": lambda: build_ovrpshim(tc),
             "vrsettings": lambda: build_vrsettings(tc)}
-    for name in ("adapter", "bridge", "compat", "glshim", "xrshim", "vkshim", "ovrpshim", "dex", "xrlayer", "oculushmd", "vrsettings"):
+    for name in ("adapter", "bridge", "compat", "langpack", "glshim", "xrshim", "vkshim", "ovrpshim", "dex", "xrlayer", "oculushmd", "vrsettings"):
        if name in parts:
            log(f"build {name}")
            steps[name]()
@@ -0,0 +1,913 @@
+// SPDX-License-Identifier: GPL-3.0-only
+//
+// FramePort language packs: answers the Meta Platform SDK's language-pack calls from `*.lang` files that already
+// sit in the game's data (OBB / app files), without any download.
+//
+// Why: OVRPort's libovrplatformloader.so is a dispatcher in front of Meta's own loader (…_meta.so). It answers
+// ovr_LanguagePack_GetCurrent / ovr_LanguagePack_SetCurrent with `return 0` (request id 0, no message ever comes
+// back), so a game that asks for its language pack waits for an answer that never arrives.
+//
+// How it is wired (patch frame.langpacks):
+//   * this library becomes the first DT_NEEDED of the dispatcher;
+//   * the dispatcher's own exports of the functions defined here are marked STB_LOCAL in its .dynsym, so symbol
+//     lookups (the game's imports and dlsym on the dispatcher's handle) continue to this library;
+//   * everything we do not answer ourselves is forwarded to the dispatcher's original function, found at run time by
+//     reading the dispatcher's in-memory .dynsym (the entries are still there, only no longer visible to lookups).
+//
+// What it implements (see https://developers.meta.com/vr/documentation/native/ps-language-packs/):
+//   ovr_LanguagePack_GetCurrent / SetCurrent        answered here
+//   ovr_AssetFile_GetList                           the dispatcher's list + our packs (type "language_pack")
+//   ovr_AssetFile_StatusById                        answered here for our packs (always "installed")
+//   ovr_PopMessage, ovr_FreeMessage, ovr_Message_*, ovr_AssetDetails*_*, ovr_LanguagePackInfo_*,
+//   ovr_AssetFileDownloadResult_*, ovr_Error_*      wrappers: our messages/handles are served here, any other
+//                                                   handle goes to the dispatcher unchanged
+//
+// Where the packs are looked for (first file per tag wins; depth <= 3):
+//   $FRAMEPORT_LANGPACK_DIRS (':'-separated), otherwise
+//   /sdcard/Android/obb/<pkg>, /sdcard/Android/data/<pkg>/files, the same under /storage/emulated/0, and
+//   /data/steam_app/obb (where Lepton mounts the host's obb folder)
+// A pack is a regular file named <BCP47 tag>.lang (de.lang -> tag "de").
+//
+// Which pack is "current": the one the game applied with SetCurrent; else $FRAMEPORT_LANGPACK (a tag); else the only
+// pack if there is exactly one.
+#define _GNU_SOURCE
+#include <ctype.h>
+#include <dirent.h>
+#include <dlfcn.h>
+#include <elf.h>
+#include <link.h>
+#include <pthread.h>
+#include <stdarg.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <strings.h>
+#include <sys/stat.h>
+#include <time.h>
+#include <unistd.h>
+#ifdef __ANDROID__
+#include <android/log.h>
+#endif
+
+#define EXPORT __attribute__((visibility("default")))
+
+typedef uint64_t u64;
+typedef uint32_t u32;
+
+// Log line (logcat tag "fp_langpack" on Android, so it lands in the game's launch.log; on other systems stderr, only
+// when $FRAMEPORT_LANGPACK_DEBUG is set).
+static void fplog(const char *fmt, ...) __attribute__((format(printf, 1, 2)));
+static void fplog(const char *fmt, ...) {
+    char line[512];
+    va_list ap;
+    va_start(ap, fmt);
+    vsnprintf(line, sizeof line, fmt, ap);
+    va_end(ap);
+#ifdef __ANDROID__
+    __android_log_print(ANDROID_LOG_INFO, "fp_langpack", "%s", line);
+#else
+    if (getenv("FRAMEPORT_LANGPACK_DEBUG")) fprintf(stderr, "fp_langpack: %s\n", line);
+#endif
+}
+
+// accessor calls can repeat every frame: only the first FP_TRACE_MAX are logged
+#define FP_TRACE_MAX 400
+static int g_traced;
+#define fptrace(...) \
+    do { \
+        if (__atomic_fetch_add(&g_traced, 1, __ATOMIC_RELAXED) < FP_TRACE_MAX) fplog(__VA_ARGS__); \
+    } while (0)
+
+// how long the dispatcher gets to answer AssetFile_GetList before we answer with our packs alone
+#ifndef FP_LIST_TIMEOUT_MS
+#define FP_LIST_TIMEOUT_MS 1500
+#endif
+
+#ifndef FP_LOADER_BASENAME
+#define FP_LOADER_BASENAME "libovrplatformloader.so"
+#endif
+
+// ovrMessageType values (same table as native/platformcompat/message_type.cpp)
+#define MSG_ASSETFILE_GETLIST 0x4AFC6F74u
+#define MSG_ASSETFILE_STATUSBYID 0x5D955D38u
+#define MSG_LANGUAGEPACK_GETCURRENT 0x1F90F0D5u
+#define MSG_LANGUAGEPACK_SETCURRENT 0x5B4FBBE0u
+
+#define MAXP 32
+#define PATHLEN 1024
+#define MAX_DEPTH 3
+
+/* ---------------------------------------------------------------------------------------------------------------
+ * Finding the dispatcher's original functions
+ * ------------------------------------------------------------------------------------------------------------- */
+
+typedef struct {
+    const char *name;
+    void *addr;
+} find_t;
+
+static uintptr_t fixptr(uintptr_t base, uintptr_t v) {
+    // bionic leaves d_ptr as a link-time address, glibc adds the load bias in place
+    return v < base ? base + v : v;
+}
+
+static size_t count_syms(uintptr_t base, const ElfW(Dyn) *dyn) {
+    const uint32_t *gnu = NULL, *sysv = NULL;
+    for (const ElfW(Dyn) *d = dyn; d->d_tag != DT_NULL; d++) {
+        if (d->d_tag == DT_GNU_HASH) gnu = (const uint32_t *)fixptr(base, d->d_un.d_ptr);
+        if (d->d_tag == DT_HASH) sysv = (const uint32_t *)fixptr(base, d->d_un.d_ptr);
+    }
+    if (sysv) return sysv[1];  // nchain
+    if (!gnu) return 0;
+    uint32_t nbuckets = gnu[0], symoffset = gnu[1], bloom_size = gnu[2];
+    const uint32_t *buckets = gnu + 4 + bloom_size * (sizeof(ElfW(Addr)) / 4);
+    const uint32_t *chains = buckets + nbuckets;
+    uint32_t max = 0;
+    for (uint32_t i = 0; i < nbuckets; i++)
+        if (buckets[i] > max) max = buckets[i];
+    if (max < symoffset) return symoffset;
+    while (!(chains[max - symoffset] & 1)) max++;
+    return (size_t)max + 1;
+}
+
+static int find_cb(struct dl_phdr_info *info, size_t size, void *data) {
+    (void)size;
+    find_t *f = (find_t *)data;
+    const char *n = info->dlpi_name ? info->dlpi_name : "";
+    const char *slash = strrchr(n, '/');
+    if (strcmp(slash ? slash + 1 : n, FP_LOADER_BASENAME) != 0) return 0;
+    uintptr_t base = info->dlpi_addr;
+    const ElfW(Dyn) *dyn = NULL;
+    for (int i = 0; i < info->dlpi_phnum; i++)
+        if (info->dlpi_phdr[i].p_type == PT_DYNAMIC) dyn = (const ElfW(Dyn) *)(base + info->dlpi_phdr[i].p_vaddr);
+    if (!dyn) return 1;
+    const ElfW(Sym) *symtab = NULL;
+    const char *strtab = NULL;
+    for (const ElfW(Dyn) *d = dyn; d->d_tag != DT_NULL; d++) {
+        if (d->d_tag == DT_SYMTAB) symtab = (const ElfW(Sym) *)fixptr(base, d->d_un.d_ptr);
+        if (d->d_tag == DT_STRTAB) strtab = (const char *)fixptr(base, d->d_un.d_ptr);
+    }
+    size_t n_syms = count_syms(base, dyn);
+    if (!symtab || !strtab || !n_syms) return 1;
+    for (size_t i = 1; i < n_syms; i++) {
+        const ElfW(Sym) *s = &symtab[i];
+        if (s->st_shndx == SHN_UNDEF || s->st_value == 0) continue;
+        if (ELF64_ST_TYPE(s->st_info) != STT_FUNC) continue;
+        if (strcmp(strtab + s->st_name, f->name) == 0) {
+            f->addr = (void *)(base + s->st_value);
+            break;
+        }
+    }
+    return 1;
+}
+
+static void *orig_sym(const char *name) {
+    find_t f = {name, NULL};
+    dl_iterate_phdr(find_cb, &f);
+    return f.addr;
+}
+
+// o_<Name>(...) calls the dispatcher's original ovr_<Name>; 0/NULL when it has none
+#define DEFORIG(RET, NAME, PARAMS, ARGS)                       \
+    static RET o_##NAME PARAMS {                               \
+        typedef RET(*fn_t) PARAMS;                             \
+        static fn_t f;                                         \
+        static int tried;                                      \
+        if (!tried) {                                          \
+            f = (fn_t)orig_sym("ovr_" #NAME);                  \
+            tried = 1;                                         \
+        }                                                      \
+        return f ? f ARGS : (RET)0;                            \
+    }
+
+DEFORIG(void *, PopMessage, (void), ())
+DEFORIG(void, FreeMessage, (void *m), (m))
+DEFORIG(u32, Message_GetType, (const void *m), (m))
+DEFORIG(u64, Message_GetRequestID, (const void *m), (m))
+DEFORIG(_Bool, Message_IsError, (const void *m), (m))
+DEFORIG(void *, Message_GetError, (const void *m), (m))
+DEFORIG(void *, Message_GetAssetDetails, (const void *m), (m))
+DEFORIG(void *, Message_GetAssetDetailsArray, (const void *m), (m))
+DEFORIG(void *, Message_GetAssetFileDownloadResult, (const void *m), (m))
+DEFORIG(size_t, AssetDetailsArray_GetSize, (const void *a), (a))
+DEFORIG(void *, AssetDetailsArray_GetElement, (const void *a, size_t i), (a, i))
+DEFORIG(u64, AssetDetails_GetAssetId, (const void *d), (d))
+DEFORIG(const char *, AssetDetails_GetAssetType, (const void *d), (d))
+DEFORIG(const char *, AssetDetails_GetDownloadStatus, (const void *d), (d))
+DEFORIG(const char *, AssetDetails_GetFilepath, (const void *d), (d))
+DEFORIG(const char *, AssetDetails_GetIapStatus, (const void *d), (d))
+DEFORIG(void *, AssetDetails_GetLanguage, (const void *d), (d))
+DEFORIG(const char *, AssetDetails_GetMetadata, (const void *d), (d))
+DEFORIG(const char *, LanguagePackInfo_GetTag, (const void *l), (l))
+DEFORIG(const char *, LanguagePackInfo_GetEnglishName, (const void *l), (l))
+DEFORIG(const char *, LanguagePackInfo_GetNativeName, (const void *l), (l))
+DEFORIG(u64, AssetFileDownloadResult_GetAssetId, (const void *r), (r))
+DEFORIG(const char *, AssetFileDownloadResult_GetFilepath, (const void *r), (r))
+DEFORIG(u64, AssetFile_GetList, (void), ())
+DEFORIG(u64, AssetFile_StatusById, (u64 id), (id))
+DEFORIG(int, Error_GetCode, (const void *e), (e))
+DEFORIG(int, Error_GetHttpCode, (const void *e), (e))
+DEFORIG(const char *, Error_GetMessage, (const void *e), (e))
+DEFORIG(const char *, Error_GetDisplayableMessage, (const void *e), (e))
+
+/* ---------------------------------------------------------------------------------------------------------------
+ * Finding the packs
+ * ------------------------------------------------------------------------------------------------------------- */
+
+typedef struct {
+    char tag[48];
+    char path[PATHLEN];
+    u64 id;
+} pack_t;
+
+static const struct {
+    const char *tag, *en, *native;
+} NAMES[] = {
+    {"en", "English", "English"},      {"de", "German", "Deutsch"},        {"fr", "French", "Français"},
+    {"es", "Spanish", "Español"},      {"it", "Italian", "Italiano"},      {"pt", "Portuguese", "Português"},
+    {"nl", "Dutch", "Nederlands"},     {"pl", "Polish", "Polski"},         {"ru", "Russian", "Русский"},
+    {"tr", "Turkish", "Türkçe"},       {"ja", "Japanese", "日本語"},        {"ko", "Korean", "한국어"},
+    {"zh", "Chinese", "中文"},          {"ar", "Arabic", "العربية"},        {"cs", "Czech", "Čeština"},
+    {"sv", "Swedish", "Svenska"},      {"da", "Danish", "Dansk"},          {"fi", "Finnish", "Suomi"},
+    {"nb", "Norwegian", "Norsk"},      {"hu", "Hungarian", "Magyar"},      {"uk", "Ukrainian", "Українська"},
+    {"el", "Greek", "Ελληνικά"},       {"he", "Hebrew", "עברית"},          {"th", "Thai", "ไทย"},
+    {"id", "Indonesian", "Indonesia"}, {"vi", "Vietnamese", "Tiếng Việt"}, {"ro", "Romanian", "Română"},
+};
+
+static u64 hash_tag(const char *tag) {
+    u64 h = 1469598103934665603ULL;  // FNV-1a over the lower-case tag
+    for (const char *p = tag; *p; p++) {
+        h ^= (unsigned char)((*p >= 'A' && *p <= 'Z') ? *p + 32 : *p);
+        h *= 1099511628211ULL;
+    }
+    return 0x4650000000000000ULL | (h & 0x0000FFFFFFFFFFFFULL);  // 'FP' prefix: never a store asset id
+}
+
+static int tag_eq(const char *a, const char *b) { return strcasecmp(a, b) == 0; }
+
+static int base_len(const char *tag) {
+    int n = 0;
+    while (tag[n] && tag[n] != '-' && tag[n] != '_') n++;
+    return n;
+}
+
+static int valid_tag(const char *t) {
+    if (!*t) return 0;
+    for (; *t; t++)
+        if (!((*t >= 'a' && *t <= 'z') || (*t >= 'A' && *t <= 'Z') || (*t >= '0' && *t <= '9') || *t == '-' ||
+              *t == '_'))
+            return 0;
+    return 1;
+}
+
+static void add_pack(pack_t *out, int *n, const char *tag, const char *path) {
+    for (int i = 0; i < *n; i++)
+        if (tag_eq(out[i].tag, tag)) return;  // first one wins
+    pack_t *p = &out[(*n)++];
+    snprintf(p->tag, sizeof p->tag, "%s", tag);
+    snprintf(p->path, sizeof p->path, "%s", path);
+    p->id = hash_tag(tag);
+}
+
+static int g_logged_dirs;
+
+// Tags to leave out of the list (comma separated, case-insensitive): env FRAMEPORT_LANGPACK_SKIP, plus the lines
+// of a file "fp_langpack_skip" in any scanned folder. For finding out which pack a game needs reported: e.g. a game
+// whose built-in language works without being a "pack".
+static __thread char g_skip[160];  // per thread: scans may run on several game threads at once
+
+static void read_skip_file(const char *dir) {
+    char path[PATHLEN], line[160];
+    if (snprintf(path, sizeof path, "%s/fp_langpack_skip", dir) >= (int)sizeof path) return;
+    FILE *f = fopen(path, "r");
+    if (!f) return;
+    size_t n = fread(line, 1, sizeof line - 1, f);
+    fclose(f);
+    line[n] = 0;
+    for (char *c = line; *c; c++)
+        if (*c == '\n' || *c == '\r' || *c == ' ') *c = ',';
+    size_t have = strlen(g_skip), room = sizeof g_skip - have;
+    if (room > 3) snprintf(g_skip + have, room, ",%.*s,", (int)room - 3, line);
+}
+
+static int skipped(const char *tag) {
+    char want[64], have[sizeof g_skip + 2];
+    snprintf(want, sizeof want, ",%s,", tag);
+    snprintf(have, sizeof have, ",%s,%s", getenv("FRAMEPORT_LANGPACK_SKIP") ? getenv("FRAMEPORT_LANGPACK_SKIP") : "",
+             g_skip);
+    for (char *c = want; *c; c++) *c = (char)tolower((unsigned char)*c);
+    for (char *c = have; *c; c++) *c = (char)tolower((unsigned char)*c);
+    return strstr(have, want) != NULL;
+}
+
+static void scan_dir(const char *dir, int depth, pack_t *out, int *n) {
+    DIR *d = opendir(dir);
+    if (d && depth == 0) read_skip_file(dir);
+    if (!g_logged_dirs && depth == 0) fplog("looking in %s: %s", dir, d ? "found" : "not readable");
+    if (!d) return;
+    struct dirent *e;
+    while (*n < MAXP && (e = readdir(d)) != NULL) {
+        if (e->d_name[0] == '.') continue;
+        char path[PATHLEN];
+        if (snprintf(path, sizeof path, "%s/%s", dir, e->d_name) >= (int)sizeof path) continue;
+        struct stat st;
+        if (stat(path, &st) != 0) continue;
+        if (S_ISDIR(st.st_mode)) {
+            if (depth < MAX_DEPTH) scan_dir(path, depth + 1, out, n);
+        } else if (S_ISREG(st.st_mode)) {
+            size_t len = strlen(e->d_name);
+            if (len > 5 && strcasecmp(e->d_name + len - 5, ".lang") == 0) {
+                char tag[48];
+                if (len - 5 >= sizeof tag) continue;
+                memcpy(tag, e->d_name, len - 5);
+                tag[len - 5] = 0;
+                if (valid_tag(tag) && !skipped(tag)) add_pack(out, n, tag, path);
+            }
+        }
+    }
+    closedir(d);
+}
+
+static void package_name(char *out, size_t cap) {
+    out[0] = 0;
+    FILE *f = fopen("/proc/self/cmdline", "r");
+    if (!f) return;
+    size_t n = fread(out, 1, cap - 1, f);
+    fclose(f);
+    out[n] = 0;  // argv[0] ends at the first NUL: the package (or package:process)
+    char *colon = strchr(out, ':');
+    if (colon) *colon = 0;
+}
+
+static int scan_dirs(pack_t *out);
+
+static int scan(pack_t *out) {
+    int n = scan_dirs(out);
+    static int last = -1;
+    if (n != last) {
+        last = n;
+        fplog("%d language pack(s) found", n);
+        for (int i = 0; i < n; i++) fplog("  pack %s -> %s", out[i].tag, out[i].path);
+    }
+    g_logged_dirs = 1;
+    return n;
+}
+
+static int scan_dirs(pack_t *out) {
+    int n = 0;
+    g_skip[0] = 0;  // read again from the folders below
+    const char *dirs = getenv("FRAMEPORT_LANGPACK_DIRS");
+    if (dirs && *dirs) {
+        char buf[PATHLEN * 2];
+        snprintf(buf, sizeof buf, "%s", dirs);
+        for (char *save = NULL, *p = strtok_r(buf, ":", &save); p; p = strtok_r(NULL, ":", &save)) scan_dir(p, 0, out, &n);
+        return n;
+    }
+    char pkg[256];
+    package_name(pkg, sizeof pkg);
+    if (!g_logged_dirs) fplog("package \"%s\"", pkg);
+    if (!pkg[0] || strchr(pkg, '/')) return 0;
+    // Unreal names the files of an Android game by their /storage/emulated/0 path (its own OBB mount does), so that
+    // spelling comes first: a pack found in both gets the path the engine would use itself.
+    static const char *const FORMATS[] = {"/storage/emulated/0/Android/obb/%s",
+                                          "/storage/emulated/0/Android/data/%s/files", "/sdcard/Android/obb/%s",
+                                          "/sdcard/Android/data/%s/files"};
+    for (size_t i = 0; i < sizeof FORMATS / sizeof *FORMATS; i++) {
+        char dir[PATHLEN];
+        snprintf(dir, sizeof dir, FORMATS[i], pkg);
+        scan_dir(dir, 0, out, &n);
+    }
+    // Lepton mounts the host's <app>/lepton-app/obb here (read-only) and only links /sdcard/Android/obb/<pkg> to it
+    // at boot (liblepton/mounting.sh: podman_mount_entry "$LEPTON_MOUNT_OBB_DIR" "/$APP_MOUNT_TARGET/obb", default
+    // APP_MOUNT_TARGET=data/steam_app), so look there too.
+    scan_dir("/data/steam_app/obb", 0, out, &n);
+    return n;
+}
+
+static pthread_mutex_t g_lock = PTHREAD_MUTEX_INITIALIZER;
+static char g_current[48];  // tag the game applied with SetCurrent
+
+static int find_tag(const pack_t *p, int n, const char *tag) {
+    for (int i = 0; i < n; i++)
+        if (tag_eq(p[i].tag, tag)) return i;
+    int bl = base_len(tag);  // "de-DE" -> "de" (and the reverse: "de" asked, "de-de" present)
+    for (int i = 0; i < n; i++)
+        if (base_len(p[i].tag) == bl && strncasecmp(p[i].tag, tag, (size_t)bl) == 0) return i;
+    return -1;
+}
+
+static int pick_current(const pack_t *p, int n) {
+    char want[48] = "";
+    pthread_mutex_lock(&g_lock);
+    snprintf(want, sizeof want, "%s", g_current);
+    pthread_mutex_unlock(&g_lock);
+    if (want[0]) {
+        int i = find_tag(p, n, want);
+        if (i >= 0) return i;
+    }
+    const char *env = getenv("FRAMEPORT_LANGPACK");
+    if (env && *env) {
+        int i = find_tag(p, n, env);
+        if (i >= 0) return i;
+    }
+    return n == 1 ? 0 : -1;
+}
+
+/* ---------------------------------------------------------------------------------------------------------------
+ * Messages and handles. Every object we hand out lives inside one msg_t, so "is this handle ours" is an address
+ * range check against the live messages.
+ * ------------------------------------------------------------------------------------------------------------- */
+
+// The asset's Metadata. Deadpool VR (Unreal) only accepts a language pack whose Metadata equals its own version string
+// ("1.0.40.356975.Quest", built from five parts with "%s.%s.%s.%s.%s"), which Meta's store sets at upload. The
+// patch writes the game's versionName behind the marker below (frame.langpacks, frameport.patches.frame.langpack);
+// FRAMEPORT_LANGPACK_META overrides it. Without either the Metadata stays empty, as before.
+#define META_LEN 96
+#define META_MARK "@FPMETA@"
+__attribute__((used)) static char g_meta_slot[sizeof META_MARK + META_LEN] = META_MARK;
+
+static void pack_meta(char *out) {
+    const char *env = getenv("FRAMEPORT_LANGPACK_META");
+    const volatile char *slot = g_meta_slot + sizeof META_MARK;
+    out[0] = 0;
+    if (env && *env) snprintf(out, META_LEN, "%s", env);
+    else {
+        int i = 0;
+        for (; i < META_LEN - 1 && slot[i]; i++) out[i] = slot[i];
+        out[i] = 0;
+    }
+}
+
+typedef struct {
+    char tag[48], en[64], nat[64];
+} lang_t;
+
+typedef struct {
+    u64 id;
+    char type[16], status[16], iap[8], meta[META_LEN];
+    char path[PATHLEN];
+    lang_t *lang;
+} details_t;
+
+typedef struct {
+    u64 id;
+    char path[PATHLEN];
+} result_t;
+
+typedef struct {
+    int code, http;
+    char msg[128];
+} err_t;
+
+typedef struct msg {
+    struct msg *all_next, *q_next;
+    u32 type;
+    u64 req;
+    int is_error, has_det, has_res;
+    err_t err;
+    details_t det;
+    lang_t lng;
+    result_t res;
+    u32 arr;  // its address is the handle of the details array
+    int n;
+    details_t dets[MAXP];
+    lang_t langs[MAXP];
+    void *orig_msg, *orig_arr;
+    size_t orig_n;
+} msg_t;
+
+static msg_t *g_all, *g_qhead, *g_qtail;
+static u64 g_next_req = 0x4650000000000001ULL;
+#define MAX_PENDING 16
+static u64 g_pending[MAX_PENDING];
+static u64 g_pending_ms[MAX_PENDING];
+static u64 g_expired[MAX_PENDING];  // requests we answered ourselves after the timeout: their late answer is dropped
+static int g_expired_next;  // when each one was asked  // dispatcher requests whose AssetFile_GetList answer we extend
+
+static msg_t *owner(const void *p) {
+    msg_t *found = NULL;
+    pthread_mutex_lock(&g_lock);
+    for (msg_t *m = g_all; m; m = m->all_next)
+        if ((const char *)p >= (const char *)m && (const char *)p < (const char *)m + sizeof *m) {
+            found = m;
+            break;
+        }
+    pthread_mutex_unlock(&g_lock);
+    return found;
+}
+
+static msg_t *new_msg(u32 type, u64 req) {
+    msg_t *m = (msg_t *)calloc(1, sizeof *m);
+    if (!m) return NULL;
+    m->type = type;
+    m->req = req ? req : __atomic_fetch_add(&g_next_req, 1, __ATOMIC_RELAXED);
+    pthread_mutex_lock(&g_lock);
+    m->all_next = g_all;
+    g_all = m;
+    pthread_mutex_unlock(&g_lock);
+    return m;
+}
+
+static void post(msg_t *m) {
+    pthread_mutex_lock(&g_lock);
+    m->q_next = NULL;
+    if (g_qtail) g_qtail->q_next = m;
+    else g_qhead = m;
+    g_qtail = m;
+    pthread_mutex_unlock(&g_lock);
+}
+
+static void fail(msg_t *m, int code, const char *text) {
+    m->is_error = 1;
+    m->err.code = code;
+    snprintf(m->err.msg, sizeof m->err.msg, "%s", text);
+}
+
+static void fill_details(details_t *d, lang_t *l, const pack_t *p) {
+    d->id = p->id;
+    snprintf(d->type, sizeof d->type, "language_pack");
+    snprintf(d->status, sizeof d->status, "installed");
+    snprintf(d->iap, sizeof d->iap, "free");
+    snprintf(d->path, sizeof d->path, "%s", p->path);
+    pack_meta(d->meta);
+    snprintf(l->tag, sizeof l->tag, "%s", p->tag);
+    snprintf(l->en, sizeof l->en, "%s", p->tag);
+    snprintf(l->nat, sizeof l->nat, "%s", p->tag);
+    int bl = base_len(p->tag);
+    for (size_t i = 0; i < sizeof NAMES / sizeof *NAMES; i++)
+        if ((int)strlen(NAMES[i].tag) == bl && strncasecmp(NAMES[i].tag, p->tag, (size_t)bl) == 0) {
+            snprintf(l->en, sizeof l->en, "%s", NAMES[i].en);
+            snprintf(l->nat, sizeof l->nat, "%s", NAMES[i].native);
+            break;
+        }
+    d->lang = l;
+}
+
+static u64 now_ms(void) {
+    struct timespec t;
+    clock_gettime(CLOCK_MONOTONIC, &t);
+    return (u64)t.tv_sec * 1000u + (u64)t.tv_nsec / 1000000u;
+}
+
+static int take_pending(u64 req) {
+    int hit = 0;
+    pthread_mutex_lock(&g_lock);
+    for (int i = 0; i < MAX_PENDING; i++)
+        if (g_pending[i] == req) {
+            g_pending[i] = 0;
+            hit = 1;
+            break;
+        }
+    pthread_mutex_unlock(&g_lock);
+    return hit;
+}
+
+static int take_expired(u64 req) {
+    int hit = 0;
+    pthread_mutex_lock(&g_lock);
+    for (int i = 0; i < MAX_PENDING; i++)
+        if (req && g_expired[i] == req) {
+            g_expired[i] = 0;
+            hit = 1;
+            break;
+        }
+    pthread_mutex_unlock(&g_lock);
+    return hit;
+}
+
+static void add_pending(u64 req) {
+    pthread_mutex_lock(&g_lock);
+    for (int i = 0; i < MAX_PENDING; i++)
+        if (!g_pending[i]) {
+            g_pending[i] = req;
+            g_pending_ms[i] = now_ms();
+            break;
+        }
+    pthread_mutex_unlock(&g_lock);
+}
+
+static void fill_list(msg_t *m, const pack_t *p, int n) {
+    for (int i = 0; i < n && i < MAXP; i++) fill_details(&m->dets[i], &m->langs[i], &p[i]);
+    m->n = n < MAXP ? n : MAXP;
+}
+
+// The dispatcher's AssetFile_GetList answer arrived: ours + theirs in one array.
+static void *wrap_list(void *orig) {
+    pack_t packs[MAXP];
+    int n = scan(packs);
+    if (n == 0) return orig;
+    msg_t *m = new_msg(MSG_ASSETFILE_GETLIST, o_Message_GetRequestID(orig));
+    if (!m) return orig;
+    fill_list(m, packs, n);
+    m->orig_msg = orig;
+    if (!o_Message_IsError(orig)) {
+        m->orig_arr = o_Message_GetAssetDetailsArray(orig);
+        if (m->orig_arr) m->orig_n = o_AssetDetailsArray_GetSize(m->orig_arr);
+    }
+    return m;
+}
+
+// A GetList the dispatcher has not answered within FP_LIST_TIMEOUT_MS: answer with our packs alone (request id kept).
+// Returns NULL if nothing is overdue or no pack exists (then a late answer from the dispatcher still reaches the
+// game); once we answered, the dispatcher's late answer is dropped (ovr_PopMessage), so the game gets one answer.
+static msg_t *expire_pending(void) {
+    u64 req = 0, now = now_ms();
+    pthread_mutex_lock(&g_lock);
+    for (int i = 0; i < MAX_PENDING; i++)
+        if (g_pending[i] && now - g_pending_ms[i] >= FP_LIST_TIMEOUT_MS) {
+            req = g_pending[i];
+            g_pending[i] = 0;
+            break;
+        }
+    pthread_mutex_unlock(&g_lock);
+    if (!req) return NULL;
+    pack_t packs[MAXP];
+    int n = scan(packs);
+    fplog("AssetFile_GetList %llu: no answer after %d ms, answering with %d pack(s)", (unsigned long long)req,
+          FP_LIST_TIMEOUT_MS, n);
+    if (n == 0) return NULL;
+    msg_t *m = new_msg(MSG_ASSETFILE_GETLIST, req);
+    if (!m) return NULL;
+    fill_list(m, packs, n);
+    pthread_mutex_lock(&g_lock);
+    g_expired[g_expired_next] = req;
+    g_expired_next = (g_expired_next + 1) % MAX_PENDING;
+    pthread_mutex_unlock(&g_lock);
+    return m;
+}
+
+/* ---------------------------------------------------------------------------------------------------------------
+ * Requests
+ * ------------------------------------------------------------------------------------------------------------- */
+
+EXPORT u64 ovr_LanguagePack_GetCurrent(void) {
+    pack_t packs[MAXP];
+    int n = scan(packs), i = pick_current(packs, n);
+    fplog("LanguagePack_GetCurrent -> %s", i >= 0 ? packs[i].tag : "none applied");
+    msg_t *m = new_msg(MSG_LANGUAGEPACK_GETCURRENT, 0);
+    if (!m) return 0;
+    u64 req = m->req;
+    if (i < 0) {
+        fail(m, 404, "no language pack is applied");
+    } else {
+        fill_details(&m->det, &m->lng, &packs[i]);
+        m->has_det = 1;
+    }
+    post(m);
+    return req;
+}
+
+EXPORT u64 ovr_LanguagePack_SetCurrent(const char *tag) {
+    pack_t packs[MAXP];
+    int n = scan(packs), i = (tag && *tag) ? find_tag(packs, n, tag) : -1;
+    fplog("LanguagePack_SetCurrent(\"%s\") -> %s", tag ? tag : "(null)", i >= 0 ? packs[i].path : "not available");
+    msg_t *m = new_msg(MSG_LANGUAGEPACK_SETCURRENT, 0);
+    if (!m) return 0;
+    u64 req = m->req;
+    if (i < 0) {
+        fail(m, 404, "language pack not available on this device");
+    } else {
+        pthread_mutex_lock(&g_lock);
+        snprintf(g_current, sizeof g_current, "%s", packs[i].tag);
+        pthread_mutex_unlock(&g_lock);
+        m->res.id = packs[i].id;
+        snprintf(m->res.path, sizeof m->res.path, "%s", packs[i].path);
+        m->has_res = 1;
+    }
+    post(m);
+    return req;
+}
+
+EXPORT u64 ovr_AssetFile_GetList(void) {
+    u64 req = o_AssetFile_GetList();
+    fplog("AssetFile_GetList (dispatcher request %llu)", (unsigned long long)req);
+    if (req) {
+        add_pending(req);
+        return req;
+    }
+    // no dispatcher function behind us: answer with our packs alone
+    pack_t packs[MAXP];
+    int n = scan(packs);
+    msg_t *m = new_msg(MSG_ASSETFILE_GETLIST, 0);
+    if (!m) return 0;
+    req = m->req;
+    fill_list(m, packs, n);
+    post(m);
+    return req;
+}
+
+EXPORT u64 ovr_AssetFile_StatusById(u64 id) {
+    fplog("AssetFile_StatusById(%llu)%s", (unsigned long long)id, (id >> 48) == 0x4650 ? " (ours)" : "");
+    if ((id >> 48) == 0x4650) {
+        pack_t packs[MAXP];
+        int n = scan(packs);
+        for (int i = 0; i < n; i++)
+            if (packs[i].id == id) {
+                msg_t *m = new_msg(MSG_ASSETFILE_STATUSBYID, 0);
+                if (!m) return 0;
+                u64 req = m->req;
+                fill_details(&m->det, &m->lng, &packs[i]);
+                m->has_det = 1;
+                post(m);
+                return req;
+            }
+        msg_t *m = new_msg(MSG_ASSETFILE_STATUSBYID, 0);
+        if (!m) return 0;
+        u64 req = m->req;
+        fail(m, 404, "asset file not found");
+        post(m);
+        return req;
+    }
+    return o_AssetFile_StatusById(id);
+}
+
+/* ---------------------------------------------------------------------------------------------------------------
+ * Message loop
+ * ------------------------------------------------------------------------------------------------------------- */
+
+EXPORT void *ovr_PopMessage(void) {
+    pthread_mutex_lock(&g_lock);
+    msg_t *m = g_qhead;
+    if (m) {
+        g_qhead = m->q_next;
+        if (!g_qhead) g_qtail = NULL;
+        m->q_next = NULL;
+    }
+    pthread_mutex_unlock(&g_lock);
+    if (m) return m;
+    void *o = o_PopMessage();
+    while (o && o_Message_GetType(o) == MSG_ASSETFILE_GETLIST && take_expired(o_Message_GetRequestID(o))) {
+        // we already answered this request (timeout): a second answer for the same request would reach the game twice
+        fplog("AssetFile_GetList %llu: late answer from the dispatcher dropped", (unsigned long long)o_Message_GetRequestID(o));
+        o_FreeMessage(o);
+        o = o_PopMessage();
+    }
+    if (o && o_Message_GetType(o) == MSG_ASSETFILE_GETLIST) {
+        u64 r = o_Message_GetRequestID(o);
+        if (take_pending(r)) {
+            fplog("AssetFile_GetList %llu answered by the dispatcher", (unsigned long long)r);
+            return wrap_list(o);
+        }
+    }
+    if (o) return o;
+    return expire_pending();
+}
+
+EXPORT void ovr_FreeMessage(void *h) {
+    msg_t *m = h ? owner(h) : NULL;
+    if (!m || (void *)m != h) {
+        o_FreeMessage(h);
+        return;
+    }
+    pthread_mutex_lock(&g_lock);
+    for (msg_t **pp = &g_all; *pp; pp = &(*pp)->all_next)
+        if (*pp == m) {
+            *pp = m->all_next;
+            break;
+        }
+    for (msg_t **pp = &g_qhead; *pp; pp = &(*pp)->q_next)  // freed unpopped: leave the queue too
+        if (*pp == m) {
+            *pp = m->q_next;
+            break;
+        }
+    g_qtail = NULL;
+    for (msg_t *q = g_qhead; q; q = q->q_next) g_qtail = q;
+    pthread_mutex_unlock(&g_lock);
+    if (m->orig_msg) o_FreeMessage(m->orig_msg);
+    free(m);
+}
+
+EXPORT u32 ovr_Message_GetType(const void *h) {
+    msg_t *m = owner(h);
+    u32 t = m ? m->type : o_Message_GetType(h);
+    if (m) fptrace("Message_GetType(ours) = 0x%08X", t);
+    return t;
+}
+
+EXPORT u64 ovr_Message_GetRequestID(const void *h) {
+    msg_t *m = owner(h);
+    return m ? m->req : o_Message_GetRequestID(h);
+}
+
+EXPORT _Bool ovr_Message_IsError(const void *h) {
+    msg_t *m = owner(h);
+    return m ? (_Bool)m->is_error : o_Message_IsError(h);
+}
+
+EXPORT void *ovr_Message_GetError(const void *h) {
+    msg_t *m = owner(h);
+    if (!m) return o_Message_GetError(h);
+    return m->is_error ? (void *)&m->err : NULL;
+}
+
+EXPORT void *ovr_Message_GetAssetDetails(const void *h) {
+    msg_t *m = owner(h);
+    if (!m) return o_Message_GetAssetDetails(h);
+    return m->has_det ? (void *)&m->det : NULL;
+}
+
+EXPORT void *ovr_Message_GetAssetFileDownloadResult(const void *h) {
+    msg_t *m = owner(h);
+    if (!m) return o_Message_GetAssetFileDownloadResult(h);
+    return m->has_res ? (void *)&m->res : NULL;
+}
+
+EXPORT void *ovr_Message_GetAssetDetailsArray(const void *h) {
+    msg_t *m = owner(h);
+    if (!m) return o_Message_GetAssetDetailsArray(h);
+    fptrace("Message_GetAssetDetailsArray(ours)");
+    return m->type == MSG_ASSETFILE_GETLIST && !m->is_error ? (void *)&m->arr : NULL;
+}
+
+EXPORT size_t ovr_AssetDetailsArray_GetSize(const void *h) {
+    msg_t *m = owner(h);
+    size_t n = m ? (size_t)m->n + m->orig_n : o_AssetDetailsArray_GetSize(h);
+    if (m) fptrace("AssetDetailsArray_GetSize = %zu (%d ours + %zu dispatcher)", n, m->n, (size_t)m->orig_n);
+    return n;
+}
+
+EXPORT void *ovr_AssetDetailsArray_GetElement(const void *h, size_t i) {
+    msg_t *m = owner(h);
+    if (!m) return o_AssetDetailsArray_GetElement(h, i);
+    if (i < (size_t)m->n) {
+        fptrace("AssetDetailsArray_GetElement(%zu) = our pack %s", i, m->dets[i].lang ? m->dets[i].lang->tag : "?");
+        return &m->dets[i];
+    }
+    fptrace("AssetDetailsArray_GetElement(%zu) = dispatcher entry", i);
+    return m->orig_arr ? o_AssetDetailsArray_GetElement(m->orig_arr, i - (size_t)m->n) : NULL;
+}
+
+/* ---------------------------------------------------------------------------------------------------------------
+ * Accessors on our own objects (anything else goes to the dispatcher)
+ * ------------------------------------------------------------------------------------------------------------- */
+
+#define IS_OURS(h) (owner(h) != NULL)
+
+EXPORT u64 ovr_AssetDetails_GetAssetId(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetAssetId(h);
+    fptrace("AssetDetails_GetAssetId(ours) = %llu", (unsigned long long)((const details_t *)h)->id);
+    return ((const details_t *)h)->id;
+}
+EXPORT const char *ovr_AssetDetails_GetAssetType(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetAssetType(h);
+    fptrace("AssetDetails_GetAssetType(ours) = \"%s\"", ((const details_t *)h)->type);
+    return ((const details_t *)h)->type;
+}
+EXPORT const char *ovr_AssetDetails_GetDownloadStatus(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetDownloadStatus(h);
+    fptrace("AssetDetails_GetDownloadStatus(ours) = \"%s\"", ((const details_t *)h)->status);
+    return ((const details_t *)h)->status;
+}
+EXPORT const char *ovr_AssetDetails_GetFilepath(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetFilepath(h);
+    fptrace("AssetDetails_GetFilepath(ours) = \"%s\"", ((const details_t *)h)->path);
+    return ((const details_t *)h)->path;
+}
+EXPORT const char *ovr_AssetDetails_GetIapStatus(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetIapStatus(h);
+    fptrace("AssetDetails_GetIapStatus(ours) = \"%s\"", ((const details_t *)h)->iap);
+    return ((const details_t *)h)->iap;
+}
+EXPORT void *ovr_AssetDetails_GetLanguage(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetLanguage(h);
+    fptrace("AssetDetails_GetLanguage(ours)");
+    return (void *)((const details_t *)h)->lang;
+}
+EXPORT const char *ovr_AssetDetails_GetMetadata(const void *h) {
+    if (!IS_OURS(h)) return o_AssetDetails_GetMetadata(h);
+    fptrace("AssetDetails_GetMetadata(ours) = \"%s\"", ((const details_t *)h)->meta);
+    return ((const details_t *)h)->meta;
+}
+
+EXPORT const char *ovr_LanguagePackInfo_GetTag(const void *h) {
+    if (!IS_OURS(h)) return o_LanguagePackInfo_GetTag(h);
+    fptrace("LanguagePackInfo_GetTag(ours) = \"%s\"", ((const lang_t *)h)->tag);
+    return ((const lang_t *)h)->tag;
+}
+EXPORT const char *ovr_LanguagePackInfo_GetEnglishName(const void *h) {
+    if (!IS_OURS(h)) return o_LanguagePackInfo_GetEnglishName(h);
+    fptrace("LanguagePackInfo_GetEnglishName(ours) = \"%s\"", ((const lang_t *)h)->en);
+    return ((const lang_t *)h)->en;
+}
+EXPORT const char *ovr_LanguagePackInfo_GetNativeName(const void *h) {
+    if (!IS_OURS(h)) return o_LanguagePackInfo_GetNativeName(h);
+    fptrace("LanguagePackInfo_GetNativeName(ours) = \"%s\"", ((const lang_t *)h)->nat);
+    return ((const lang_t *)h)->nat;
+}
+
+EXPORT u64 ovr_AssetFileDownloadResult_GetAssetId(const void *h) {
+    return IS_OURS(h) ? ((const result_t *)h)->id : o_AssetFileDownloadResult_GetAssetId(h);
+}
+EXPORT const char *ovr_AssetFileDownloadResult_GetFilepath(const void *h) {
+    return IS_OURS(h) ? ((const result_t *)h)->path : o_AssetFileDownloadResult_GetFilepath(h);
+}
+
+EXPORT int ovr_Error_GetCode(const void *h) { return IS_OURS(h) ? ((const err_t *)h)->code : o_Error_GetCode(h); }
+EXPORT int ovr_Error_GetHttpCode(const void *h) { return IS_OURS(h) ? ((const err_t *)h)->http : o_Error_GetHttpCode(h); }
+EXPORT const char *ovr_Error_GetMessage(const void *h) {
+    return IS_OURS(h) ? ((const err_t *)h)->msg : o_Error_GetMessage(h);
+}
+EXPORT const char *ovr_Error_GetDisplayableMessage(const void *h) {
+    return IS_OURS(h) ? ((const err_t *)h)->msg : o_Error_GetDisplayableMessage(h);
+}
@@ -79,10 +79,13 @@ company = "FramePort"
 path = "src"
 module = "main"

+[tool.flet.macos]
+entitlement."com.apple.security.files.user-selected.read-write" = true
+
 [tool.ruff]
 line-length = 120
 target-version = "py311"
-extend-exclude = ["native", "src/frameport/_data"]
+extend-exclude = ["native", "src/frameport/_data", ".claude"]

 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "B", "UP"]
@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Stamp a dev build's version into src/frameport/_version.py (CI only; never committed): the next patch release plus
+.dev<build number>, e.g. 0.9.0 -> 0.9.1.dev57. It sorts above the current release and below the next one, so
+testers on a dev build get the next release offered as a normal update.
+
+    python scripts/dev_version.py <build number>     # prints the stamped version
+"""
+import re
+import sys
+from pathlib import Path
+
+VERSION_FILE = Path(__file__).resolve().parents[1] / "src/frameport/_version.py"
+
+
+def dev_version(current: str, build: int) -> str:
+    base = re.match(r"(\d+)\.(\d+)\.(\d+)", current)
+    if not base:
+        raise ValueError(f"unexpected version {current!r}")
+    major, minor, patch = (int(x) for x in base.groups())
+    return f"{major}.{minor}.{patch + 1}.dev{int(build)}"
+
+
+def main() -> None:
+    text = VERSION_FILE.read_text(encoding="utf-8")
+    current = re.search(r'__version__\s*=\s*"([^"]+)"', text).group(1)
+    version = dev_version(current, int(sys.argv[1]))
+    VERSION_FILE.write_text(text.replace(f'"{current}"', f'"{version}"', 1), encoding="utf-8")
+    print(version)
+
+
+if __name__ == "__main__":
+    main()
@@ -3,6 +3,9 @@
 Chromium (Playwright). Any exception in a view shows up on stdout; screenshots land in --out.

    FRAMEPORT_HOME=<a test data dir> python scripts/ui_smoke.py --out /tmp/shots [--game <package>]
+
+--linux adds two pretend arm64 Linux apps (an AppImage and a VR folder app, tiny fake ELF files in FRAMEPORT_HOME)
+and renders their pages; with --fake-frame the AppImage is "installed" with a missing library.
 """
 from __future__ import annotations

@@ -21,7 +24,7 @@ import flet as ft  # noqa: E402
 from frameport.core import library  # noqa: E402
 from frameport.ui.app import FramePortApp  # noqa: E402

-PORT = 8557
+PORT = int(os.environ.get("FRAMEPORT_SMOKE_PORT", "8557"))  # two smoke runs at once need different ports
 ERRORS: list[str] = []


@@ -44,12 +47,65 @@ class FakeFS:
                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))
+        now, shots = time.time(), []
+        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
@@ -67,6 +123,11 @@ class FakeFS:

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


@@ -86,6 +147,11 @@ class FakeTarget:
        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",
@@ -129,6 +195,36 @@ def open_type_dialog(app: FramePortApp) -> None:
    listener.on_key_down(SimpleNamespace(key="Enter"))


+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)
+
+
 STEP_SECONDS = 4  # per screen (the screenshot is taken ~3 s in)


@@ -143,6 +239,35 @@ def driver(app: FramePortApp, steps: list[tuple[str, callable]], ready: threadin
        time.sleep(STEP_SECONDS)


+def find_button(root, text: str):
+    """The first button under `root` whose label is `text` (walks Flet's control tree)."""
+    seen, stack = set(), [root]
+    while stack:
+        c = stack.pop()
+        if c is None or id(c) in seen:
+            continue
+        seen.add(id(c))
+        label = getattr(c, "content", None)
+        if (label == text or getattr(c, "text", None) == text) and getattr(c, "on_click", None):
+            return c
+        for attr in ("controls", "content", "actions"):
+            v = getattr(c, attr, None)
+            if isinstance(v, list):
+                stack.extend(v)
+            elif v is not None and not isinstance(v, str):
+                stack.append(v)
+    return None
+
+
+def click_usb_setup(app) -> None:
+    app.navigate(1)
+    time.sleep(2)
+    button = find_button(app.body, "Set up with a USB cable")
+    print(f"usb button found: {button is not None}", flush=True)
+    if button:
+        button.on_click(None)
+
+
 def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("--out", type=Path, required=True)
@@ -157,8 +282,15 @@ def main() -> int:
    ap.add_argument("--install-questions", nargs="+", metavar="PKG", default=None,
                    help="open the install questions for these games, then click each dialog's main button twice "
                         "(a double click must not duplicate dialogs); nothing is installed")
+    ap.add_argument("--usb-setup", action="store_true", help="click 'Set up with a USB cable' on the connect page "
+                    "(a Frame cabled to this PC) and screenshot what follows")
    ap.add_argument("--docs", action="store_true", help="only the screens used in the docs (Library, --game, Frame)")
+    ap.add_argument("--gestures", action="store_true", help="with --fake-frame: real mouse drags (drag-select) and "
+                    "right-clicks (menus) in Files, Screenshots and the Library; prints what got selected")
+    ap.add_argument("--linux", action="store_true", help="add two pretend arm64 Linux apps and render their pages")
    args = ap.parse_args()
+    if args.linux:
+        add_fake_linux_apps()
    global STEP_SECONDS
    if args.hover:
        STEP_SECONDS = 7
@@ -169,12 +301,14 @@ def main() -> int:
    args.out.mkdir(parents=True, exist_ok=True)
    game = args.game or (library.games()[0]["package"] if library.games() else None)
    steps = [("library", lambda a: a.navigate(0)), ("frame", lambda a: a.navigate(1)),
-             ("files", lambda a: a.go("files")), ("tools", lambda a: a.go("settings"))]
+             ("files", lambda a: a.go("files")), ("screenshots", lambda a: a.go("screenshots")),
+             ("tools", lambda a: a.go("settings"))]
    if game:
        steps.insert(1, ("game", lambda a: a.open_game(game)))
        steps.insert(2, ("game-customize", lambda a: a.open_game(game, advanced=True)))
        steps += [("share-dialog", lambda a: a.share_config_dialog(game)),
-                  ("report-dialog", lambda a: (a.page.pop_dialog(), a.report_problem_dialog(game)))]
+                  ("report-dialog", lambda a: (a.page.pop_dialog(), a.report_problem_dialog(game))),
+                  ("custom-art-dialog", lambda a: (a.page.pop_dialog(), a.custom_artwork(game)))]
        # last: the right-click menu stays open over whatever comes next
        steps.append(("library-menu", lambda a: (a.page.pop_dialog(), a.navigate(0), time.sleep(3),
                                                 a.library_view.open_menu(game))))
@@ -187,7 +321,75 @@ def main() -> int:
        steps.append(("files", lambda a: a.go("files")))
        steps.append(("files-select", lambda a: [a.files_view._toggle(e.path, True)
                                                 for e in a.files_view.entries[1:3]]))
-        steps.append(("type-on-frame", open_type_dialog))
+        steps.append(("screenshots", lambda a: a.go("screenshots")))
+        steps.append(("screenshot-viewer", lambda a: a.screenshots_view.viewer(0)))
+        steps.append(("type-on-frame", lambda a: (a.page.pop_dialog(), open_type_dialog(a))))
+        steps.append(("power-confirm", lambda a: (a.page.pop_dialog(), a.frame_power("restart"))))
+    mouse: dict[str, callable] = {}  # step name -> mouse actions (Playwright page) after its screenshot
+    if args.gestures:
+        STEP_SECONDS = 14  # the mouse actions run after each step's screenshot, before the next step
+
+        def drag(*points):
+            def run(page):
+                page.mouse.move(*points[0])
+                time.sleep(0.5)
+                page.mouse.down()
+                for pt in points[1:]:
+                    page.mouse.move(*pt, steps=25)
+                    time.sleep(0.4)
+                page.mouse.up()
+            return run
+
+        def right_click(x, y):
+            return lambda page: (page.mouse.move(x, y), time.sleep(0.5), page.mouse.click(x, y, button="right"))
+
+        def report(label, view, extra=""):
+            def run(a):
+                v = getattr(a, view)
+                print(f"GESTURE {label}: selected={sorted(v.selected)} {extra and eval(extra)}", flush=True)
+            return run
+
+        def escape(page):
+            page.keyboard.press("Escape")
+        steps = [("files", lambda a: a.go("files")),
+                 ("files-dragged", report("files drag", "files_view")),
+                 ("files-menu", lambda a: None),
+                 ("files-space-menu", lambda a: None),
+                 ("screenshots", lambda a: a.go("screenshots")),
+                 ("screenshots-dragged", report("screenshots drag", "screenshots_view")),
+                 ("screenshots-menu", lambda a: None),
+                 ("library", lambda a: a.navigate(0)),
+                 ("library-dragged", report("library drag", "library_view", "a.library_view.select_mode")),
+                 ("library-undrag", report("library drag back", "library_view"))]
+        mouse = {"files": drag((900, 268), (900, 320), (900, 372)),          # the folder + 2 files
+                 "files-dragged": right_click(900, 320),                      # a selected one: "… 3 items"
+                 "files-menu": lambda page: (escape(page), time.sleep(0.5), right_click(900, 600)(page)),
+                 "files-space-menu": escape,
+                 "screenshots": drag((680, 280), (950, 280), (950, 430)),     # 3 shots
+                 "screenshots-dragged": right_click(950, 430),
+                 "screenshots-menu": escape,
+                 "library": drag((360, 300), (560, 300), (760, 300)),        # 3 cards, select mode on
+                 "library-dragged": drag((560, 300), (760, 300))}             # from a selected card: deselects 2
+    if args.linux:
+        def linux_filter(a, value):
+            a.navigate(0)
+            time.sleep(2)
+            a.library_view._set("platform", value)
+        steps = [("library", lambda a: a.navigate(0)), ("library-linux", lambda a: linux_filter(a, "linux")),
+                 ("linux-appimage", lambda a: (a.library_view._set("platform", "all"), a.open_game(LINUX_APPIMAGE))),
+                 ("linux-folder", lambda a: a.open_game(LINUX_FOLDER)),
+                 ("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)))]
+    if args.usb_setup:
+        def continue_usb(a):
+            dialog = [d for d in a.page._dialogs.controls if d.open and type(d).__name__ == "AlertDialog"][-1]
+            button = find_button(dialog, "Done: look for the cable") or dialog.actions[-1]  # (label inside a Row)
+            print(f"dialog button found: {button is not None}", flush=True)
+            button.on_click(None)
+        steps = [("usb-explain", click_usb_setup), ("usb-continue", continue_usb),
+                 ("usb-wait", lambda a: time.sleep(8)), ("usb-after", lambda a: time.sleep(10))]
    if args.install_questions:
        queued: list[str] = []

@@ -279,6 +481,11 @@ def main() -> int:
                            time.sleep(1.5)
                        page.screenshot(path=str(args.out / f"{shot:02d}-{name}.png"))
                        shot += 1
+                        if name in mouse:
+                            mouse[name](page)
+                            time.sleep(2)
+                            page.screenshot(path=str(args.out / f"{shot:02d}-{name}-mouse.png"))
+                            shot += 1
                browser.close()
        except Exception:  # noqa: BLE001
            ERRORS.append("browser: " + traceback.format_exc())
@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+# ruff: noqa: E501  (the shell snippet for the Frame keeps its lines whole)
+"""Autonomous USB-cable test (Frame cabled to this PC): everything needed to decide on a "Connect with a USB cable"
+setup option, in one run, without touching the headset. Writes a Markdown report.
+
+    uv run python scripts/usb_autotest.py --out <report.md> [--no-speed]
+
+Checks: Windows (via powershell.exe from WSL, or directly): new network adapters, Valve USB devices (VID 28DE), the
+driver Windows bound and the USB class codes (NCM 02/0D, ECM 02/06, RNDIS E0 or EF/04); the adapter's IPv4 and
+network category; Frame side (over the normal connection): agent `usb_link`, the systemd units / NetworkManager
+connection behind usb0 (does it depend on Developer Mode?); Frame -> PC over the cable (the setup direction: a
+temporary listener on a pairing port); PC -> Frame SSH over the cable (same host key); upload speed USB vs normal.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+PS_PATHS = ("/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe", "powershell.exe", "powershell")
+LISTEN_PORT = 8766  # in FramePort's pairing range (8765-8767)
+
+
+def powershell() -> str | None:
+    for p in PS_PATHS:
+        if os.path.exists(p) or shutil.which(p):
+            return p
+    return None
+
+
+def ps(script: str, timeout: int = 60) -> str:
+    exe = powershell()
+    if not exe:
+        return "(no PowerShell)"
+    env = {k: v for k, v in os.environ.items() if k != "PSModulePath"}
+    try:
+        p = subprocess.run([exe, "-NoProfile", "-NonInteractive", "-Command", script], capture_output=True,
+                           text=True, timeout=timeout, env=env)
+        return (p.stdout + p.stderr).replace("\r", "").strip()
+    except (OSError, subprocess.SubprocessError) as exc:
+        return f"(powershell failed: {exc})"
+
+
+WINDOWS = r"""
+$ErrorActionPreference = 'SilentlyContinue'
+'== adapters'
+Get-NetAdapter -IncludeHidden | Select-Object Name,InterfaceDescription,Status,LinkSpeed,MacAddress |
+  Format-Table -AutoSize | Out-String -Width 250
+'== Valve USB devices (VID 28DE)'
+Get-PnpDevice -PresentOnly | Where-Object { $_.InstanceId -match 'VID_28DE' } | ForEach-Object {
+  $d = $_
+  $compat = (Get-PnpDeviceProperty -InstanceId $d.InstanceId -KeyName 'DEVPKEY_Device_CompatibleIds').Data -join ' '
+  $svc = (Get-PnpDeviceProperty -InstanceId $d.InstanceId -KeyName 'DEVPKEY_Device_Service').Data
+  $drv = (Get-PnpDeviceProperty -InstanceId $d.InstanceId -KeyName 'DEVPKEY_Device_DriverDesc').Data
+  "{0} | {1} | status={2} | class={3} | service={4} | driver={5} | compat={6}" -f $d.FriendlyName, $d.InstanceId,
+    $d.Status, $d.Class, $svc, $drv, $compat
+}
+'== problem devices'
+Get-PnpDevice -PresentOnly | Where-Object { $_.Status -ne 'OK' -and $_.InstanceId -match 'USB' } |
+  Select-Object FriendlyName,Status,InstanceId | Format-Table -AutoSize | Out-String -Width 250
+'== IPv4 on 10.86.200.*'
+Get-NetIPAddress -AddressFamily IPv4 | Where-Object { $_.IPAddress -like '10.86.200.*' } |
+  Select-Object InterfaceAlias,IPAddress,PrefixLength,PrefixOrigin | Format-Table | Out-String
+'== network profiles'
+Get-NetConnectionProfile | Select-Object InterfaceAlias,NetworkCategory | Format-Table | Out-String
+'== SSH to the Frame over the cable (from Windows)'
+(Test-NetConnection 10.86.200.233 -Port 22 -WarningAction SilentlyContinue).TcpTestSucceeded
+'== FramePort firewall rules'
+Get-NetFirewallRule -DisplayName '*FramePort*' | Select-Object DisplayName,Enabled,Profile,Direction |
+  Format-Table | Out-String
+"""
+
+FRAME_UNITS = r"""
+echo "== units mentioning usb/gadget"; systemctl list-units --all --no-pager 2>/dev/null | grep -i -E 'gadget|usb' | head -20
+for u in $(systemctl list-unit-files --no-pager 2>/dev/null | grep -i -E 'gadget|usb' | awk '{print $1}' | head -8); do
+  echo "== $u"; systemctl cat "$u" --no-pager 2>/dev/null | grep -v '^#' | grep -v '^$' | head -30; done
+echo "== NetworkManager usb0"; nmcli -f GENERAL.CONNECTION,IP4.ADDRESS device show usb0 2>/dev/null
+c=$(nmcli -g GENERAL.CONNECTION device show usb0 2>/dev/null); [ -n "$c" ] && nmcli -f ipv4.method,ipv4.addresses,connection.autoconnect connection show "$c" 2>/dev/null
+echo "== configfs"; ls -la /sys/kernel/config/usb_gadget/ 2>&1 | head; ls /sys/kernel/config/usb_gadget/*/functions/ 2>&1 | head
+echo "== udc"; for u in /sys/class/udc/*; do echo "$u $(cat $u/current_speed 2>/dev/null) $(cat $u/state 2>/dev/null)"; done
+echo "== devkit"; ls -la /etc/steamos-devkit-enabled 2>&1
+"""
+
+
+def frame_to_pc(frame, pc_ips: list[str]) -> list[str]:
+    """Can the Frame open a TCP connection to this PC over the cable (what the setup step needs)?"""
+    lines, got = [], []
+    srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    try:
+        srv.bind(("0.0.0.0", LISTEN_PORT))
+    except OSError as exc:
+        return [f"couldn't listen on {LISTEN_PORT}: {exc}"]
+    srv.listen(4)
+    srv.settimeout(1)
+
+    def accept():
+        end = time.time() + 20
+        while time.time() < end:
+            try:
+                conn, addr = srv.accept()
+                got.append(addr[0])
+                conn.sendall(b"HTTP/1.0 200 OK\r\n\r\nframeport-usb-ok\n")
+                conn.close()
+            except OSError:
+                continue
+    t = threading.Thread(target=accept, daemon=True)
+    t.start()
+    for ip in pc_ips:
+        code, out, err = frame.run(f"curl -s --max-time 6 http://{ip}:{LISTEN_PORT}/ping || echo FAILED", timeout=20)
+        lines.append(f"Frame -> {ip}:{LISTEN_PORT}: {(out or err).strip()[:80]}")
+    t.join(timeout=22)
+    srv.close()
+    lines.append(f"connections seen from: {got or 'none'}")
+    return lines
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out", type=Path, default=Path("usb-autotest.md"))
+    ap.add_argument("--no-speed", action="store_true")
+    args = ap.parse_args()
+    from frameport.frame import usb
+    from frameport.frame.connection import saved_targets
+    from frameport.targets.frame_lepton import FrameLeptonTarget
+
+    report = [f"# USB cable autotest {time.strftime('%Y-%m-%d %H:%M')}", ""]
+
+    def section(title, text):
+        report.extend([f"## {title}", "```", text.strip() or "(nothing)", "```", ""])
+        print(f"--- {title}\n{text.strip()[:3000]}\n", flush=True)
+
+    section("Windows", ps(WINDOWS, timeout=120))
+    wsl = subprocess.run(["ip", "-4", "-o", "addr", "show"], capture_output=True, text=True).stdout
+    section("This side (WSL/Linux) IPv4", wsl)
+    frame = FrameLeptonTarget(saved_targets()[0], None).connect().frame
+    section("Frame units / NetworkManager / configfs", frame.run(FRAME_UNITS, timeout=60)[1])
+    result = usb.check(frame, measure=not args.no_speed)
+    section("frameport frame usb-check", json.dumps(result, indent=1, default=str))
+    ips = result.get("pc_addresses") or []
+    section("Frame -> PC over the cable (setup direction)", "\n".join(frame_to_pc(frame, ips)) if ips else
+            "skipped: this side has no address on the Frame's USB network")
+    args.out.write_text("\n".join(report), encoding="utf-8")
+    print(f"report: {args.out}")
+
+
+if __name__ == "__main__":
+    main()
@@ -1,2 +1,2 @@
 # The FramePort version: the single source (pyproject reads it via hatch; CI checks a release tag matches it).
-__version__ = "0.7.0"
+__version__ = "0.9.1"
@@ -247,7 +247,7 @@ def missing_ovr_symbols(lib_bytes: dict[str, bytes]) -> set[str]:
        return set()
    exported = set(elf.dyn_symbols(loader, True))
    linked = set(elf.needed(loader))
-    for extra in ("libovrplatformcompat.so", "libovrstubs.so"):
+    for extra in ("libovrplatformcompat.so", "libovrstubs.so", "libfp_langpack.so"):
        if extra in lib_bytes and extra in linked:  # only counts when the loader loads it (a lone file doesn't help)
            exported |= elf.dyn_symbols(lib_bytes[extra], True)
    wanted = set()
@@ -106,6 +106,29 @@ def replace_rodata_string(data: bytes, old: str, new: str) -> tuple[bytes, int]:
    return bytes(buf), count


+def hide_exports(data: bytes, names) -> tuple[bytes, list[str]]:
+    """Make the exported functions `names` invisible to symbol lookup without removing them: their .dynsym entries
+    become STB_LOCAL (name, value and section stay, nothing moves, the hash tables are untouched). Both bionic's and
+    glibc's lookups only match GLOBAL/WEAK entries, so a lookup for such a name (a game's import, or dlsym on this
+    library's handle) goes on to the next library in the dependency list; code that reads the library's own .dynsym
+    (native/langpack) still finds the original address. Returns (data, names actually hidden); ELF64 only."""
+    if not is_elf(data) or not is_64bit(data) or data[5] != 1:
+        return data, []
+    sec = _elf(data).get_section_by_name(".dynsym")
+    if not isinstance(sec, SymbolTableSection):
+        return data, []
+    wanted = set(names)
+    entsize, start = sec["sh_entsize"] or 24, sec["sh_offset"]
+    buf, hidden = bytearray(data), []
+    for i, sym in enumerate(sec.iter_symbols()):
+        if (sym.name in wanted and sym["st_shndx"] != "SHN_UNDEF"
+                and sym["st_info"]["bind"] in ("STB_GLOBAL", "STB_WEAK")):
+            at = start + i * entsize + 4  # Elf64_Sym.st_info: binding in the high nibble, type in the low one
+            buf[at] &= 0x0F
+            hidden.append(sym.name)
+    return bytes(buf), sorted(hidden)
+
+
 def add_needed(data: bytes, library: str) -> bytes:
    """Add a DT_NEEDED entry in front of the existing ones (same effect as `patchelf --add-needed`; being first matters
    for symbol interposition, e.g. the GL shim must precede libEGL).
@@ -0,0 +1,28 @@
+"""Language packs (`<BCP47 tag>.lang`) in a game's data folder (OBB / app files); see native/langpack."""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+MAX_DEPTH = 3  # same depth as the runtime scan in native/langpack/langpack.c
+TAG = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def find_tags(data_dir: Path | str | None) -> list[str]:
+    """Tags of the language packs below `data_dir` (de.lang -> "de"), sorted, first file per tag."""
+    if not data_dir:
+        return []
+    root = Path(data_dir)
+    if not root.is_dir():
+        return []
+    seen: dict[str, str] = {}
+    base_depth = len(root.parts)
+    for folder, dirs, files in os.walk(root):
+        if len(Path(folder).parts) - base_depth >= MAX_DEPTH:
+            dirs[:] = []
+        for name in files:
+            stem, dot, ext = name.rpartition(".")
+            if dot and ext.lower() == "lang" and TAG.match(stem):
+                seen.setdefault(stem.lower(), stem)
+    return sorted(seen.values(), key=str.lower)
@@ -0,0 +1,184 @@
+"""Native arm64 Linux apps for the Frame (GitHub #31): an AppImage, a folder, or a .zip/.tar.* archive with an
+aarch64 program. Finds the program to start, checks the CPU architecture (x86_64 builds can't run natively) and
+whether it's an OpenXR (VR) app. Archives are unpacked once into FramePort's data folder, so installs upload a
+plain folder like PC VR games do."""
+from __future__ import annotations
+
+import hashlib
+import re
+import shutil
+import tarfile
+import zipfile
+from pathlib import Path
+
+from ..core.paths import user_data_dir
+
+EM_AARCH64, EM_X86_64 = 183, 62
+ARCHIVES = (".zip", ".tar.gz", ".tgz", ".tar.xz", ".txz", ".tar.bz2", ".tar")
+OPENXR_MARKERS = (b"libopenxr_loader.so", b"xrCreateInstance")
+MAX_SCAN = 256 << 20  # don't read huge files looking for OpenXR markers
+
+
+def elf_machine(path: Path) -> int | None:
+    """e_machine of an ELF file (183 = aarch64, 62 = x86_64), None if it isn't ELF."""
+    try:
+        with open(path, "rb") as f:
+            head = f.read(20)
+    except OSError:
+        return None
+    if head[:4] != b"\x7fELF" or len(head) < 20:
+        return None
+    return int.from_bytes(head[18:20], "little" if head[5] == 1 else "big")
+
+
+def is_appimage(path: Path) -> bool:
+    try:
+        with open(path, "rb") as f:
+            head = f.read(11)
+    except OSError:
+        return False
+    return head[:4] == b"\x7fELF" and head[8:11] == b"AI\x02"
+
+
+def is_archive(path: Path) -> bool:
+    return path.is_file() and path.name.lower().endswith(ARCHIVES)
+
+
+def looks_like_linux_app(path: Path) -> bool:
+    """For the file picker / drag-and-drop: something this module can add."""
+    path = Path(path)
+    return path.is_dir() or is_archive(path) or is_appimage(path) or elf_machine(path) is not None
+
+
+def slug(name: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", name.lower()).strip("_")[:48] or "app"
+
+
+def clean_title(name: str) -> str:
+    """'Venera-Prime-2.4.2-aarch64.AppImage' -> 'Venera Prime'."""
+    stem = re.sub(r"(\.AppImage|\.tar\.\w+|\.tgz|\.txz|\.zip)$", "", name, flags=re.I)
+    stem = re.split(r"[-_ .]v?\d+(\.\d+)+", stem, maxsplit=1)[0]
+    stem = re.sub(r"[-_ .](linux|aarch64|arm64|x86_64|amd64)\b.*$", "", stem, flags=re.I)
+    return re.sub(r"[-_.]+", " ", stem).strip() or name
+
+
+def unpack(archive: Path) -> Path:
+    """Unpack an archive into <data>/linux-apps/<slug>-<hash>/ (once per archive version)."""
+    st = archive.stat()
+    key = hashlib.sha1(f"{archive.resolve()}:{st.st_size}:{st.st_mtime_ns}".encode()).hexdigest()[:8]
+    dest = user_data_dir() / "linux-apps" / f"{slug(clean_title(archive.name))}-{key}"
+    done = dest / ".unpacked"
+    if done.exists():
+        return dest
+    shutil.rmtree(dest, ignore_errors=True)
+    dest.mkdir(parents=True)
+    if archive.name.lower().endswith(".zip"):
+        with zipfile.ZipFile(archive) as z:
+            for info in z.infolist():
+                target = (dest / info.filename).resolve()
+                if not str(target).startswith(str(dest.resolve())):
+                    raise ValueError(f"unsafe path in archive: {info.filename}")
+            z.extractall(dest)
+    else:
+        with tarfile.open(archive) as t:
+            t.extractall(dest, filter="data")
+    done.write_text(archive.name, encoding="utf-8")
+    return dest
+
+
+def _desktop_exec(root: Path) -> str | None:
+    for desktop in sorted(root.rglob("*.desktop"))[:5]:
+        m = re.search(r"^Exec=(\S+)", desktop.read_text(encoding="utf-8", errors="replace"), re.M)
+        if m:
+            return Path(m.group(1).strip('"')).name
+    return None
+
+
+def _desktop_name(root: Path) -> str | None:
+    for desktop in sorted(root.rglob("*.desktop"))[:5]:
+        m = re.search(r"^Name=(.+)$", desktop.read_text(encoding="utf-8", errors="replace"), re.M)
+        if m:
+            return m.group(1).strip()
+    return None
+
+
+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."""
+    wanted = _desktop_exec(root)
+    folder = slug(root.name.split("-")[0])
+    found = []
+    for p in root.rglob("*"):
+        if not p.is_file() or ".so" in p.name or p.suffix in (".py", ".pyc", ".txt", ".json"):
+            continue
+        machine = elf_machine(p)
+        if machine is None:
+            continue
+        rel_depth = len(p.relative_to(root).parts)
+        score = (100 if wanted and p.name == wanted else 0) + (30 if slug(p.stem) and slug(p.stem) in folder else 0) \
+            + (20 if folder and folder in slug(p.stem) else 0) - 5 * rel_depth
+        found.append((score, p.stat().st_size, p, machine))
+    found.sort(key=lambda t: (-t[0], -t[1]))
+    return [(p, m) for _s, _size, p, m in found]
+
+
+def app_libraries(root: Path, exe: Path) -> list[Path]:
+    """Libraries the program loads: next to it, in a lib*/ folder beside it, or the app's usr/lib*. Libraries deep
+    in data folders don't count (FramePort's own build ships FrameBridge's OpenXR loader as data and isn't VR)."""
+    dirs = {exe.parent}
+    for base in (exe.parent, root, root / "usr"):
+        dirs.update(d for d in base.glob("lib*") if d.is_dir())
+    out = []
+    for d in dirs:
+        out += [p for p in d.glob("*.so*") if p.is_file()]
+    return sorted(out)[:200]
+
+
+def uses_openxr(paths: list[Path]) -> bool:
+    for p in paths:
+        try:
+            if p.stat().st_size > MAX_SCAN:
+                continue
+            data = p.read_bytes()
+        except OSError:
+            continue
+        if any(m in data for m in OPENXR_MARKERS):
+            return True
+    return False
+
+
+def inspect(path: Path) -> dict:
+    """{root, exe (relative to root), appimage, machine, arch_ok, openxr, title, candidates} for an AppImage, a
+    folder or an archive. Raises ValueError when there's no Linux program in it."""
+    path = Path(path)
+    if path.is_file() and is_archive(path):
+        root = unpack(path)
+        subdirs = [d for d in root.iterdir() if not d.name.startswith(".")]
+        if len(subdirs) == 1 and subdirs[0].is_dir():  # the usual single top folder
+            pass
+        title = clean_title(path.name)
+    elif path.is_file():
+        root = path.parent
+        title = clean_title(path.name)
+    else:
+        root = path
+        title = clean_title(path.name)
+    if path.is_file() and not is_archive(path):
+        machine = elf_machine(path)
+        if machine is None:
+            raise ValueError(f"{path.name} isn't a Linux program (AppImage or ELF)")
+        appimage = is_appimage(path)
+        return {"root": str(path.parent), "exe": path.name, "files": [path.name], "appimage": appimage,
+                "machine": machine, "arch_ok": machine == EM_AARCH64, "openxr": uses_openxr([path]),
+                "title": title, "candidates": [path.name]}
+    programs = rank_programs(root)
+    if not programs:
+        raise ValueError(f"no Linux program found in {path.name}")
+    appimages = [p for p, _m in programs if is_appimage(p)]
+    exe, machine = (appimages[0], elf_machine(appimages[0])) if appimages else programs[0]
+    libs = app_libraries(root, exe)
+    title = _desktop_name(root) or title
+    return {"root": str(root), "exe": exe.relative_to(root).as_posix(), "files": None,
+            "appimage": is_appimage(exe), "machine": machine, "arch_ok": machine == EM_AARCH64,
+            "openxr": uses_openxr([exe] + libs), "title": title,
+            "candidates": [p.relative_to(root).as_posix() for p, m in programs[:20] if m == EM_AARCH64]}
@@ -251,3 +251,68 @@ def apply_choice(package: str, choice: dict) -> bool:
        return True
    finally:
        shutil.rmtree(stage, ignore_errors=True)
+
+
+# The user's own images (Artwork dialog → "Your own images"), for games whose art can't be found automatically.
+CUSTOM_KINDS = ("portrait", "landscape", "hero", "logo", "icon")
+CUSTOM_MAX_BYTES = 40 << 20
+CUSTOM_MIN_PX = 64
+CUSTOM_MAX_PX = 3840  # larger images are scaled down (Steam's biggest shape is 1920 px wide)
+
+
+class ArtError(ValueError):
+    """The chosen file can't be used as artwork (the message says why, for the GUI)."""
+
+
+def apply_custom(package: str, kind: str, path: str | Path) -> Path:
+    """Store an image file the user chose as one kind of artwork, replacing that kind only. It is checked and
+    re-encoded (PNG when it has transparency, else JPEG; logos and icons always PNG), marked as the user's pick so
+    automatic fetches never replace it, and the old thumbnails go. FramePort's generated cover/banner (games without
+    store art) are dropped once a real cover shape exists. Returns the stored file."""
+    from PIL import Image, UnidentifiedImageError
+
+    if kind not in CUSTOM_KINDS:
+        raise ArtError(f"unknown artwork kind {kind!r}")
+    path = Path(path)
+    try:
+        if path.stat().st_size > CUSTOM_MAX_BYTES:
+            raise ArtError(f"{path.name} is larger than {CUSTOM_MAX_BYTES >> 20} MB")
+        with Image.open(path) as im:
+            im.load()
+            im = im.copy()
+    except (OSError, UnidentifiedImageError, Image.DecompressionBombError):
+        raise ArtError(f"{path.name} isn't an image FramePort can read (use PNG, JPEG or WebP)") from None
+    if min(im.size) < CUSTOM_MIN_PX:
+        raise ArtError(f"{path.name} is too small ({im.width}×{im.height}); use at least {CUSTOM_MIN_PX} px")
+    if max(im.size) > CUSTOM_MAX_PX:
+        im.thumbnail((CUSTOM_MAX_PX, CUSTOM_MAX_PX), Image.LANCZOS)
+    alpha = im.mode in ("RGBA", "LA", "PA") or (im.mode == "P" and "transparency" in im.info)
+    png = alpha or kind in ("logo", "icon")
+    d = fetch.artwork_dir(package)
+    tmp = d / f".custom-{kind}.tmp"
+    if png:
+        im.convert("RGBA" if alpha else "RGB").save(tmp, "PNG", optimize=True)
+    else:
+        im.convert("RGB").save(tmp, "JPEG", quality=92, optimize=True)
+    _drop_kind(d, kind)
+    out = d / f"{kind}{'.png' if png else '.jpg'}"
+    tmp.replace(out)
+    if kind in ("portrait", "landscape", "hero"):
+        for stem in ("cover", "banner"):
+            _drop_kind(d, stem)
+    (d / fetch.PICKED).write_text("custom", encoding="utf-8")  # automatic fetches leave the art alone
+    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:
+        raise ArtError(f"unknown artwork kind {kind!r}")
+    d = fetch.artwork_dir(package)
+    _drop_kind(d, kind)
+    (d / fetch.PICKED).write_text("custom", encoding="utf-8")  # "Find automatically" brings store art back
+
+
+def _drop_kind(d: Path, kind: str) -> None:
+    for f in list(d.glob(f"{kind}.*")) + list(d.glob(f"t_{kind}_*")):
+        f.unlink(missing_ok=True)
@@ -76,7 +76,8 @@ def steam_set(package: str, title: str = "", apk: str | Path | None = None) -> d
    title = title or package
    out_dir = fetch.artwork_dir(package) / "steam"
    out_dir.mkdir(parents=True, exist_ok=True)
-    placeholder = not (set(src) - {"icon"})  # no store art (at most the APK's icon): the name on a coloured tile
+    # no store art (at most the APK's icon; the GUI's generated cover/banner don't count): the name on a coloured tile
+    placeholder = not (set(src) & (STORE_KINDS | {"shot"}))
    parts = [f"{k}:{p.stat().st_size}:{p.stat().st_mtime_ns}" for k, p in sorted(src.items())]
    if placeholder:
        parts.append(f"placeholder:{PLACEHOLDER_VERSION}:{title}:{apk or ''}")
@@ -298,6 +299,8 @@ def _placeholder(out_dir: Path, title: str, icon_file: Path | None, apk) -> dict
 def original_platform(entry: dict) -> str:
    """What the game was made for (a Steam tag)."""
    extra = (entry.get("analysis") or {}).get("extra") or {}
+    if entry.get("kind") == "linux":
+        return "Linux"
    if entry.get("kind") == "rift":
        if extra.get("flat"):
            return "Windows"
@@ -314,7 +317,7 @@ def steam_tags(entry: dict, where: str = "frame") -> list[str]:
    kind = ((entry.get("analysis") or {}).get("extra") or {}).get("vr_kind") or "quest"
    flat = bool(((entry.get("analysis") or {}).get("extra") or {}).get("flat"))
    runs = TAG if where != "frame" else ("Windows game on Frame" if flat else "PC VR on Frame") \
-        if entry.get("kind") == "rift" else \
+        if entry.get("kind") == "rift" else "Linux app on Frame" if entry.get("kind") == "linux" else \
        "Quest on Frame" if kind == "quest" else "Android on Frame"
    base = [runs, original_platform(entry)]
    genres = ((entry.get("details") or {}).get("genres") or [])[:4]
@@ -84,6 +84,9 @@ def _update_hint() -> None:
    age = updates.cache_age()
    if age is None or age > updates.CHECK_EVERY:
        threading.Thread(target=updates.refresh_cache, daemon=True).start()
+        from .recommend import catalog as _catalog
+
+        threading.Thread(target=_catalog.refresh_remote, daemon=True).start()  # confirmed configs from GitHub main
    up = updates.cached_update()
    today = time.strftime("%Y-%m-%d")
    if up and library.setting("update.cli_hint") != today:
@@ -227,6 +230,31 @@ def scan(path: Path = typer.Argument(..., help="a folder with game backups (APKs
        typer.echo(f"{g['package']:40} {g.get('title', '')[:34]:34} {r['status']:11} {r['source']}")


+@app.command("catalog-update")
+def catalog_update():
+    """Fetch confirmed game configs from the repo's main branch now (normally automatic, every 6 h)."""
+    from .recommend import catalog
+
+    n = catalog.refresh_remote(force=True)
+    st = catalog.remote_status()
+    typer.echo(f"{n} config(s) downloaded; {st['entries']} on GitHub main")
+    for pkg, why in sorted(st["skipped"].items()):
+        typer.echo(f"  skipped {pkg}: {why}")
+
+
+@app.command("add-linux")
+def add_linux(path: Path = typer.Argument(..., help="an arm64 AppImage, a folder, or a .zip/.tar.gz with the app"),
+              exe: Optional[str] = typer.Option(None, help="the program to start (relative to the app's folder)")):
+    """Add a native arm64 Linux app to the library (installed on the Frame as it is, with a Steam shortcut)."""
+    try:
+        g = pipeline.add_linux_app(path, printing_reporter(verbose=False), exe=exe)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from None
+    extra = g["analysis"]["extra"]
+    typer.echo(f"{g['package']:40} {g.get('title', '')[:34]:34} program {extra['exe']}"
+               f"{' (AppImage)' if extra['appimage'] else ''}{' VR' if extra['openxr'] else ''}")
+
+
@app.command("list")
 def list_games():
    """The games in the library."""
@@ -480,6 +508,16 @@ def frame_info(frame: Optional[str] = typer.Option(None, help=FRAME_HELP)):
    typer.echo(json.dumps(_target(frame).describe(), indent=1, default=str))


+@frame_app.command("usb-check")
+def frame_usb_check(frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
+                    no_speed: bool = typer.Option(False, help="skip the upload speed test (2 × 128 MB)")):
+    """Check the USB cable link to the Frame: what the Frame presents, this PC's address on it, SSH over it and its
+    upload speed vs the normal connection (JSON)."""
+    from .frame import usb
+
+    typer.echo(json.dumps(usb.check(_target(frame).connect().frame, measure=not no_speed), indent=1, default=str))
+
+
@frame_app.command("controller-models")
 def frame_controller_models(frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
                            convert: bool = typer.Option(False, help="also convert them (cached on the Frame)")):
@@ -58,6 +58,10 @@ def _follow_catalog(data: dict) -> bool:
    settings["recipes.app_version"] = __version__
    for pkg, g in (data.get("games") or {}).items():
        r, a = g.get("recipe"), g.get("analysis")
+        if g.get("kind") == "linux":  # installed as it is: no recipe to derive
+            continue
+        if app_updated and isinstance(a, dict):
+            changed |= _refresh_data_fields(g, a)
        if not isinstance(r, dict) or not isinstance(a, dict) or r.get("source") == "user":
            continue
        entry = catalog.lookup(pkg)
@@ -71,6 +75,21 @@ def _follow_catalog(data: dict) -> bool:
    return changed


+def _refresh_data_fields(g: dict, a: dict) -> bool:
+    """Analysis fields read from the game's data folder (cheap, no APK analysis) that newer FramePort versions added:
+    filled in for games already in the library, so their patches are offered without a re-analysis."""
+    extra = a.setdefault("extra", {})
+    if "lang_packs" in extra or a.get("package", "").startswith("rift."):
+        return False
+    from ..analysis import langpacks
+
+    try:
+        extra["lang_packs"] = langpacks.find_tags(g.get("data_dir"))
+    except OSError:
+        return False
+    return True
+
+
 def _migrate(data: dict) -> bool:
    """One-time updates of stored recipes when a new default is introduced (each runs once per library)."""
    done = data.setdefault("settings", {}).setdefault("migrations", [])
@@ -206,7 +225,7 @@ def _migrate(data: dict) -> bool:
        # Android apps without VR gain the default-on "Hide Android's navigation bar" patch
        for g in (data.get("games") or {}).values():
            a, r = g.get("analysis") or {}, g.get("recipe")
-            if isinstance(r, dict) and (a.get("extra") or {}).get("vr_kind") == "none":
+            if isinstance(r, dict) and (a.get("extra") or {}).get("vr_kind") == "none" and g.get("kind") != "linux":
                r.setdefault("patches", {}).setdefault("device.hide_navbar", {})
                r.setdefault("reasons", {}).setdefault(
                    "device.hide_navbar", "2D app: Android's navigation buttons would cover the app's own controls.")
@@ -16,7 +16,7 @@ def twins(games: list[dict]) -> set[str]:
    by_pkg = {g["package"]: g for g in games}
    quest_by_title = {}
    for g in games:
-        if g.get("kind") != "rift":
+        if g.get("kind") not in ("rift", "linux"):  # (Linux apps have no Quest/Rift twin)
            quest_by_title.setdefault(_norm(g.get("title") or ""), []).append(g["package"])
    out = set()
    for g in games:
@@ -41,11 +41,13 @@ def display_title(game: dict, twin_set: set[str] | None = None) -> str:

 def counterparts(game: dict, games: list[dict]) -> list[dict]:
    """The other-platform versions of this game in the library."""
+    if game.get("kind") == "linux":
+        return []
    rift = game.get("kind") == "rift"
    t = _norm(game.get("title") or "")
    out = []
    for g in games:
-        if g["package"] == game["package"] or (g.get("kind") == "rift") == rift:
+        if g["package"] == game["package"] or (g.get("kind") == "rift") == rift or g.get("kind") == "linux":
            continue
        linked = (rift and game.get("quest_package") == g["package"]) or \
            (not rift and g.get("quest_package") == game["package"])
@@ -170,6 +170,18 @@ def package_listing(g: dict) -> dict[str, object]:
                    pe[rel] = {"error": str(exc)}
            out["pe.json"] = pe
        return out
+    if g.get("kind") == "linux":  # the app's file list (a lone AppImage: only it, not the folder it's in)
+        root, extra = Path(g.get("game_dir") or ""), (g.get("analysis") or {}).get("extra") or {}
+        paths = [root / f for f in extra["files"]] if extra.get("files") else \
+            sorted(root.rglob("*")) if root.is_dir() else []
+        files = []
+        for p in paths:
+            if p.is_file():
+                files.append([p.relative_to(root).as_posix(), p.stat().st_size])
+                if len(files) >= 20000:
+                    break
+        out["files.json"] = files
+        return out
    apk = Path(g.get("apk") or "")
    if not apk.is_file():
        return out
@@ -55,7 +55,7 @@ def working_config_url(g: dict, recipe_yaml: str, status: str, notes: str, env:
                       red: redact.Redactor | None = None) -> str:
    red = red or redact.Redactor()
    title = g.get("title") or g["package"]
-    kind = "Oculus Rift (PC VR)" if g.get("kind") == "rift" else "Meta Quest"
+    kind = {"rift": "Oculus Rift (PC VR)", "linux": "Linux app (arm64)"}.get(g.get("kind"), "Meta Quest")
    a = g.get("analysis") or {}
    game = f"{title} — {g['package']} ({kind}, version {a.get('version') or '?'}, {a.get('engine') or '?'} / " \
           f"{a.get('xr') or '?'})"
@@ -28,6 +28,12 @@ log = logging.getLogger(__name__)
 REMOTE_AGENT_DIR = ".local/share/frameport/agent"


+def agent_version_of(text: str) -> int:
+    """AGENT_VERSION from an agent's source (0 if missing)."""
+    m = re.search(r"^AGENT_VERSION\s*=\s*(\d+)", text, re.M)
+    return int(m.group(1)) if m else 0
+
+
 class FrameNotPaired(ConnectionError):
    """SSH works but none of FramePort's ways in was accepted: the Frame hasn't run the first-time setup (or the
    password was wrong). The message keeps "authentication failed" for older callers."""
@@ -512,8 +518,17 @@ class Frame:
        remote = posixpath.join(remote_dir, "frameport_agent.py")
        if self._agent_digest == digest:
            return remote
-        code, out, _ = self.run(f"sha256sum {sh_quote(remote)} 2>/dev/null | cut -c1-16")
-        if out.strip() != digest:
+        code, out, _ = self.run(f"sha256sum {sh_quote(remote)} 2>/dev/null | cut -c1-16; "
+                                f"grep -m1 '^AGENT_VERSION' {sh_quote(remote)} 2>/dev/null")
+        lines = out.split("\n")
+        remote_version = agent_version_of(lines[1] if len(lines) > 1 else "")
+        if lines[0].strip() != digest and remote_version > agent_version_of(text.decode("utf-8", "replace")):
+            # a newer FramePort (another PC, or FramePort on the Frame) installed a newer agent: keep it. Agents
+            # stay compatible with older apps; replacing it broke the newer one's launchers (2026-10-04: an older
+            # app put agent 43 back over 45 every few seconds)
+            self._agent_digest = digest
+            return remote
+        if lines[0].strip() != digest:
            self.run(f"mkdir -p {sh_quote(remote_dir)}")
            tmp = f"{remote}.{os.getpid()}.{threading.get_ident()}.tmp"  # two threads never share a temp file
            with self.sftp.open(tmp, "wb") as f:
@@ -152,8 +152,41 @@ def browse(seconds: float = 4.0, scan: bool = True) -> list[Found]:
        known = {f.host for f in out}
        for ip in _scan(local_subnets(), known):
            out.append(Found(ip, ip, 22, "steamos", "scan", [ip]))
-    rank = {"frameport": 0, "devkit": 1, "saved": 2, "scan": 3}
-    return sorted(out, key=lambda f: (rank.get(f.source, 9), f.name, link_label(f.host) != "network", f.host))
+    out = dedupe(out)
+    return sorted(out, key=lambda f: (SOURCE_RANK.get(f.source, 9), f.name, LINK_RANK.get(f.via, 9), f.host))
+
+
+SOURCE_RANK = {"frameport": 0, "devkit": 1, "saved": 2, "scan": 3}
+LINK_RANK = {"USB": 0, "Frame hotspot": 1, "network": 2}  # fastest first (USB ~37 MB/s, hotspot ~85, but the hotspot
+# needs the PC on the Frame's Wi-Fi: when both answer, the cable is the deliberate choice)
+
+
+def dedupe(found: list[Found], key_of=None) -> list[Found]:
+    """One entry per Frame: entries whose SSH host key matches (the same device reached over home Wi-Fi, its hotspot
+    and USB, or found by mDNS, the saved list and the network scan) merge into one that uses the fastest link, keeps
+    the best-known source/name and lists the other addresses. Entries whose key can't be read stay as they are."""
+    if key_of is None:
+        from .connection import server_key
+
+        def key_of(f: Found):
+            k = server_key(f.host, f.port, timeout=3)
+            return k.get_base64() if k else None
+    with ThreadPoolExecutor(16) as pool:
+        keys = list(pool.map(key_of, found))
+    groups: dict[str, list[Found]] = {}
+    out = []
+    for f, k in zip(found, keys, strict=True):
+        if k is None:
+            out.append(f)
+        else:
+            groups.setdefault(k, []).append(f)
+    for members in groups.values():
+        best = min(members, key=lambda f: (LINK_RANK.get(f.via, 9), f.host))
+        named = min(members, key=lambda f: (SOURCE_RANK.get(f.source, 9), f.source == "scan"))
+        addresses = list(dict.fromkeys([best.host] + [a for f in members for a in [f.host, *f.addresses]]))
+        out.append(Found(named.name if named.source != "scan" else best.name, best.host, best.port, named.user,
+                         named.source, addresses, {**best.properties, **named.properties}))
+    return out


 def local_ip_towards(host: str = "8.8.8.8") -> str:
@@ -102,11 +102,13 @@ class PairingServer:
    requests: int = 0  # requests from the network (right or wrong code): the Frame can reach us
    flag: Path | None = None  # WSL: the temporary firewall rule stays while this file exists
    hint: str = ""  # set by the UI when nothing reached us after HINT_AFTER seconds: what may block the Frame
+    host: str = ""  # the address the Frame uses to reach this PC; "" = the PC's address towards the internet. The USB
+    # setup uses the cable's fixed PC address (10.86.200.234), so no Wi-Fi, router or discovery is involved
    _httpd: http.server.ThreadingHTTPServer | None = None

    @property
    def url(self) -> str:
-        return f"http://{local_ip_towards()}:{self.port}"
+        return f"http://{self.host or local_ip_towards()}:{self.port}"

    @property
    def one_liner(self) -> str:
@@ -0,0 +1,81 @@
+"""USB cable link to the Frame (usb0, a USB network gadget): one check that answers whether "connect with a USB
+cable" can work on this PC: what the Frame presents, whether this PC got an address on it, whether SSH answers
+over it (same host key), and how fast an upload is compared with the normal connection."""
+from __future__ import annotations
+
+import io
+import os
+import re
+import socket
+import subprocess
+import sys
+import time
+
+USB_IFACE = "usb0"
+FRAME_USB_IP, PC_USB_IP = "10.86.200.233", "10.86.200.234"  # fixed by the Frame's dnsmasq (dhcp-host by MAC)
+TEST_BYTES = 128 << 20
+
+
+def pc_usb_addresses(frame_ip: str) -> list[str]:
+    """This PC's IPv4 addresses in the same /24 as the Frame's USB address (Windows via ipconfig, else `ip`)."""
+    prefix = frame_ip.rsplit(".", 1)[0] + "."
+    texts = []
+    for cmd in (["ip", "-4", "-o", "addr", "show"], ["ipconfig"], ["ifconfig"], ["ipconfig.exe"]):
+        try:
+            texts.append(subprocess.run(cmd, capture_output=True, text=True, timeout=10).stdout)
+        except (OSError, subprocess.SubprocessError):
+            continue
+    text = "\n".join(texts)
+    # interface addresses only (`ip`/ifconfig "inet X", ipconfig "IPv4 Address ... : X"): not broadcast/netmask values
+    found = re.findall(r"\binet\s+(\d+\.\d+\.\d+\.\d+)", text) + \
+        re.findall(r"IPv4[^:\n]*:\s*(\d+\.\d+\.\d+\.\d+)", text)
+    return sorted({ip for ip in found if ip.startswith(prefix) and ip != frame_ip})
+
+
+def upload_speed(frame, size: int = TEST_BYTES) -> float:
+    """MB/s of one SFTP upload of `size` bytes to /tmp on the Frame (removed afterwards)."""
+    path = f"/tmp/frameport-speed-{os.getpid()}"
+    data = io.BytesIO(os.urandom(1 << 20) * (size >> 20))
+    start = time.time()
+    frame.sftp.putfo(data, path)
+    elapsed = time.time() - start
+    frame.run(f"rm -f {path}")
+    return size / elapsed / 1e6
+
+
+def check(frame, measure: bool = True) -> dict:
+    """{frame: <agent usb_link>, frame_ip, pc_addresses, reachable, same_frame, speed_usb, speed_default, notes}."""
+    info = frame.agent("usb_link", timeout=60)
+    out = {"frame": info, "platform": sys.platform, "notes": []}
+    ip = next((a.split("/")[0] for a in info.get("addresses") or []), None)
+    out["frame_ip"] = ip
+    if not info.get("present"):
+        out["notes"].append("The Frame has no usb0 link: is the cable in the Frame's USB-C port and the PC?")
+        return out
+    if not ip:
+        out["notes"].append("usb0 exists but has no address on the Frame (cable not connected to a PC?)")
+        return out
+    out["pc_addresses"] = pc_usb_addresses(ip)
+    if not out["pc_addresses"]:
+        out["notes"].append("This PC has no address on the Frame's USB network: no driver for the gadget "
+                            f"({', '.join(info.get('functions') or []) or 'unknown type'}) or no DHCP from the Frame")
+    try:
+        socket.create_connection((ip, frame.target.port), timeout=3).close()
+        out["reachable"] = True
+    except OSError:
+        out["reachable"] = False
+        out["notes"].append(f"SSH ({ip}:{frame.target.port}) doesn't answer over the cable from this PC")
+        return out
+    from .connection import Frame, FrameTarget
+
+    other = Frame(FrameTarget(ip, frame.target.user, frame.target.port), frame.password)
+    try:
+        other.connect(timeout=10)
+        out["same_frame"] = (other.client.get_transport().get_remote_server_key()
+                             == frame.client.get_transport().get_remote_server_key())
+        if measure:
+            out["speed_usb"] = round(upload_speed(other), 1)
+            out["speed_default"] = round(upload_speed(frame), 1)
+    finally:
+        other.close()
+    return out
@@ -217,6 +217,57 @@ def install_pcvr(frame: Frame, plan: PcvrPlan, reporter: Reporter) -> dict:
    return result


+@dataclass
+class LinuxPlan:
+    package: str  # "linux.<slug>"
+    title: str
+    root: Path  # the app's folder (for a lone AppImage: the folder it's in, with files = [its name])
+    exe: str  # relative to root
+    files: list[str] | None = None  # only these files of root (a lone AppImage), else the whole folder
+    appimage: bool = False
+    openxr: bool = False
+
+
+def install_linux(frame: Frame, plan: LinuxPlan, reporter: Reporter) -> dict:
+    """Upload an arm64 Linux app to the Frame (resumable, unchanged files aren't re-sent); the agent extracts
+    AppImages, checks the app's libraries and writes its launcher (GitHub #31)."""
+    reporter.stage("Prepare Frame")
+    prep = frame.agent("prepare_linux", package=plan.package, title=plan.title)
+    if plan.files:
+        manifest = {name: (plan.root / name).stat().st_size for name in plan.files}
+    else:
+        manifest = local_data_manifest(plan.root)
+        manifest = {k: v for k, v in manifest.items() if not k.startswith(".unpacked")}
+    to_send = [rel for rel, size in manifest.items() if prep["existing"].get("app", {}).get(rel) != size]
+    need = sum(manifest[rel] for rel in to_send)
+    if need > prep["free_bytes"] - (1 << 30):
+        raise RuntimeError(f"not enough space on the Frame: need {need / 2**30:.1f} GiB + 1 GiB headroom, "
+                           f"have {prep['free_bytes'] / 2**30:.1f} GiB")
+    if to_send:
+        reporter.stage(f"Upload app ({len(to_send)} files, {need / 2**20:.0f} MiB)")
+        with transfer_link(frame, reporter, need) as xfer:
+            upload_files(xfer, [(plan.root / rel, f"app/{rel}", manifest[rel]) for rel in to_send],
+                         prep["incoming"], reporter, max(need, 1), 0)
+    else:
+        reporter.log("all app files already on the Frame; not re-sending")
+    upload_steam_art(frame, plan.package, prep["base"], reporter)
+    reporter.stage("Finalize install")
+    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, manifests={"app": manifest},
+                         executables=executables, tags=_tags(plan.package), timeout=900)
+    reporter.log(f"installed at {result['base']} (Steam shortcut id {result['appid']})")
+    return result
+
+
+def _is_elf(path: Path) -> bool:
+    try:
+        with open(path, "rb") as f:
+            return f.read(4) == b"\x7fELF"
+    except OSError:
+        return False
+
+
 def ensure_proton(frame: Frame, reporter: Reporter, tool: str | None = None, timeout: float = 45 * 60) -> dict:
    """Install Proton (ARM64) + its runtime on the Frame without user interaction: the agent writes Steam appmanifest
    stubs and restarts Steam, which downloads them. Waits until they're installed (progress from the appmanifests)."""
@@ -230,6 +281,7 @@ def ensure_proton(frame: Frame, reporter: Reporter, tool: str | None = None, tim
    reporter.log(r.get("hint") or f"installing {r.get('tool')}")
    end = time.time() + timeout
    last = None
+    asked_runtime = False
    while time.time() < end:
        reporter.check_cancel()
        time.sleep(10)
@@ -241,6 +293,14 @@ def ensure_proton(frame: Frame, reporter: Reporter, tool: str | None = None, tim
            reporter.check("Proton installed", True, st["ready"]["display_name"])
            return st["ready"]
        dl = st.get("download") or {}
+        sug = st.get("suggested") or {}
+        if sug.get("installed") and not sug.get("require_installed") and not dl.get("total") and not asked_runtime:
+            # Steam names the runtime a Proton needs (e.g. Experimental) only once Proton itself is installed: ask
+            # for it now
+            asked_runtime = True
+            reporter.log("installing the Steam Linux Runtime this Proton needs")
+            frame.agent("install_proton", mode="unattended", tool=tool)
+            continue
        if dl.get("total"):
            reporter.progress(dl["done"] / dl["total"], f"downloading Proton {dl['done'] / 2**20:.0f}/"
                                                         f"{dl['total'] / 2**20:.0f} MiB")
@@ -0,0 +1,151 @@
+"""Steam screenshots taken on the Frame (the GUI's Screenshots tab).
+
+Steam keeps them per account in userdata/<id>/760/remote/<appid>/screenshots/ (+ thumbnails/). The Frame files every
+headset screenshot under SteamVR (250820), so the agent (`list_screenshots`) matches them to FramePort games by time:
+launch.sh logs each play session to <anchor>/plays.log. Thumbnails and opened images are cached on this PC in
+<user data>/screenshots-cache/<frame>/ and shown by asset URL (never image bytes in controls).
+"""
+from __future__ import annotations
+
+import hashlib
+import posixpath
+import re
+import threading
+from pathlib import Path
+
+from ..core.events import Reporter
+from ..core.paths import user_data_dir
+from . import installer
+
+THUMB_WIDTH = 480
+_locks: dict[str, threading.Lock] = {}
+_guard = threading.Lock()
+
+
+def list_shots(frame, package: str | None = None, offset: int = 0, limit: int = 0) -> dict:
+    """{shots, total, games} from the agent, newest first. package: a game ("" = shots of no FramePort game)."""
+    args = {"offset": offset, "limit": limit}
+    if package is not None:
+        args["package"] = package
+    return frame.agent("list_screenshots", **args)
+
+
+def frame_id(frame) -> str:
+    target = getattr(frame, "target", None)
+    raw = (getattr(target, "name", "") or getattr(target, "host", "") or "frame") if target else "frame"
+    return re.sub(r"[^A-Za-z0-9._-]+", "_", raw).strip("._") or "frame"
+
+
+def cache_dir(frame) -> Path:
+    d = user_data_dir() / "screenshots-cache" / frame_id(frame)
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _key(shot: dict) -> str:
+    return hashlib.sha1(f"{shot['path']}:{shot.get('size')}".encode()).hexdigest()[:16]
+
+
+def _lock(key: str) -> threading.Lock:
+    with _guard:
+        return _locks.setdefault(key, threading.Lock())
+
+
+def _fetch(frame, remote: str, dest: Path) -> Path:
+    with _lock(str(dest)):
+        if not dest.exists():
+            tmp = dest.with_suffix(dest.suffix + ".part")
+            frame.sftp.get(remote, str(tmp))
+            tmp.replace(dest)
+    return dest
+
+
+def cached(frame, shot: dict, kind: str = "thumb") -> Path | None:
+    """The cached thumbnail/full image if it was already downloaded (no network: for render paths)."""
+    p = cache_dir(frame) / _cache_name(shot, kind)
+    return p if p.exists() else None
+
+
+def _cache_name(shot: dict, kind: str) -> str:
+    ext = posixpath.splitext(shot["path"])[1].lower() if kind == "full" else ".jpg"
+    return f"{kind}_{_key(shot)}{ext or '.jpg'}"
+
+
+def image_path(frame, shot: dict) -> Path:
+    """The full image, downloaded once into the cache (the viewer shows it from there)."""
+    return _fetch(frame, shot["path"], cache_dir(frame) / _cache_name(shot, "full"))
+
+
+def thumb_path(frame, shot: dict) -> Path:
+    """A small image for the grid: Steam's own thumbnail, downloaded once; without one, made from the full image."""
+    dest = cache_dir(frame) / _cache_name(shot, "thumb")
+    if dest.exists():
+        return dest
+    if shot.get("thumb"):
+        try:
+            return _fetch(frame, shot["thumb"], dest)
+        except OSError:
+            pass  # thumbnail gone: make one
+    full = image_path(frame, shot)
+    with _lock(str(dest)):
+        if not dest.exists():
+            try:
+                from PIL import Image
+
+                with Image.open(full) as im:
+                    im.thumbnail((THUMB_WIDTH, THUMB_WIDTH))
+                    tmp = dest.with_suffix(".jpg.part")
+                    im.convert("RGB").save(tmp, "JPEG", quality=85)
+                    tmp.replace(dest)
+            except Exception:  # noqa: BLE001  (unreadable image: show the original)
+                return full
+    return dest
+
+
+def safe_name(text: str) -> str:
+    return re.sub(r'[<>:"/\\|?*\x00-\x1f]+', "_", text or "").strip(" .") or "Screenshots"
+
+
+def download(frame, shots: list[dict], dest_dir: Path, reporter: Reporter | None = None) -> dict:
+    """Copy the full images into dest_dir/<game title>/ (files already there with the same size are skipped).
+    Interruptible (Cancel)."""
+    reporter = reporter or Reporter()
+    dest_dir = Path(dest_dir)
+    items = []
+    for s in shots:
+        dest = dest_dir / safe_name(s.get("title") or "") / posixpath.basename(s["path"])
+        if dest.exists() and dest.stat().st_size == s.get("size"):
+            continue
+        items.append((s, dest))
+    total = sum(s.get("size") or 0 for s, _ in items)
+    skipped = len(shots) - len(items)
+    reporter.log(f"{len(items)} screenshot(s), {total / 2**20:.1f} MiB → {dest_dir}"
+                 + (f" ({skipped} already there)" if skipped else ""))
+    done = 0
+    if items:
+        with installer.transfer_link(frame, reporter, total) as xfer:
+            reporter.stage(f"Download {len(items)} screenshot(s)")
+            for s, dest in items:
+                reporter.check_cancel()
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                tmp = dest.with_name(dest.name + ".part")
+
+                def progress(got, _total, base=done, name=dest.name):
+                    reporter.check_cancel()
+                    reporter.progress((base + got) / max(total, 1), name)
+                xfer.sftp.get(s["path"], str(tmp), callback=progress)
+                tmp.replace(dest)
+                done += s.get("size") or 0
+    return {"files": len(items), "skipped": skipped, "bytes": total, "folder": str(dest_dir)}
+
+
+def delete(frame, shots: list[dict]) -> int:
+    """Delete screenshots on the Frame (the agent only deletes images in Steam's screenshot folders) and their cached
+    copies here. Steam's own screenshot list may still show them until Steam restarts."""
+    if not shots:
+        return 0
+    r = frame.agent("delete_screenshots", paths=[s["path"] for s in shots])
+    for s in shots:
+        for kind in ("thumb", "full"):
+            (cache_dir(frame) / _cache_name(s, kind)).unlink(missing_ok=True)
+    return len(r.get("deleted") or [])
@@ -48,11 +48,15 @@
 "72 Hz": "",
 "80 Hz": "",
 "90 Hz": "",
+ "920 × 430": "",
 "96 Hz": "",
 "A folder with Android games (APK + OBB, e.g. Quest games) or PC VR games.": "",
+ "A game is running on the Frame": "",
 "A game is running on the Frame. Close it in the headset first, then try again.": "",
 "a known blocker": "",
+ "A Linux app for arm64 (AppImage, .zip or .tar.gz)": "",
 "A Meta Quest game (APK). It's rebuilt for the Frame and runs in Lepton, Valve's Android container.": "",
+ "A native Linux program built for arm64 (aarch64), like the Frame's own CPU. It's installed unchanged and runs directly on SteamOS (no Android container, no Proton), started from the Frame's Steam library. VR apps use the Frame's OpenXR runtime.": "",
 "A new FramePort version is ready to install": "",
 "A recipe is the list of patches FramePort applies to a game before installing it. Known-good recipes were tested on a Frame; the others are suggested from the game's engine and VR API. Hover a patch for why it's there.": "",
 "A VR app made for another Android headset. OpenXR apps are translated like Quest games; apps built on a headset maker's own SDK (Pico, HTC Wave) can't run on the Frame.": "",
@@ -65,6 +69,8 @@
 "AC Nexus: no AppSW at 72 Hz": "",
 "AC Nexus: no AppSW at 90 Hz": "",
 "Activity": "",
+ "Add a Linux app (arm64)…": "",
+ "Add a Linux app folder…": "",
 "Add a tag": "",
 "Add an APK file": "",
 "Add an APK file…": "",
@@ -75,12 +81,15 @@
 "Add videos": "",
 "Add videos and files…": "",
 "Add your games": "",
+ "Add {name}": "",
 "Added automatically (engine, VR API or store genre)": "",
 "Added automatically when needed": "",
 "Added {n} game": [
  "",
  ""
 ],
+ "Added {title}": "",
+ "Added {title}: it starts with {exe}. Not the right program? Change it on its page.": "",
 "Adds a launcher entry point (Lepton additionally needs category LAUNCHER, see the Frame 'launcher' fix).": "",
 "Adds a real ovrMessageType_ToString (OVRPort's platform compat library) for games whose platform loader lacks it (e.g. The Climb 2). OVRPort 1.2.5+ adds the same library itself; then this is skipped.": "",
 "Adds a small piece of Meta's platform library that some games need to start.": "",
@@ -91,6 +100,7 @@
 "Advanced": "",
 "All": "",
 "All at their defaults": "",
+ "All games": "",
 "All of FramePort's data on this PC is gone": "",
 "Allow swapchains larger than 4096 px": "",
 "Allows data backup.": "",
@@ -103,6 +113,8 @@
 "Also delete this game's files on this PC ({size})": "",
 "Also in your library: {value} version": "",
 "Also remove FramePort's games and files from the Frame": "",
+ "An AppImage is a Linux app packed into one file. FramePort unpacks it on the Frame once, so it starts without FUSE.": "",
+ "An AppImage, a folder or a .zip/.tar archive with a Linux program built for arm64 (aarch64). x86_64 builds can't run on the Frame. The app must bring the libraries SteamOS doesn't have.": "",
 "An ordinary Android app or game (no VR). It's installed unchanged and runs in Lepton, Valve's Android container.": "",
 "Analyze again": "",
 "Analyze {title} again": "",
@@ -114,6 +126,7 @@
 "Any": "",
 "APK": "",
 "Appearance": "",
+ "AppImage": "",
 "Apply the suggested patches and reinstall": "",
 "Apps that suggest controller bindings only for Meta's newer profiles (Touch Plus, Touch Pro), which the Frame's runtime rejects (XR_ERROR_PATH_UNSUPPORTED), get the same bindings as oculus/touch_controller instead (components Touch lacks are dropped). Without it such apps get no controller input.": "",
 "Artwork for {get}": "",
@@ -123,6 +136,7 @@
 "Artwork: {value}": "",
 "As the game sends it": "",
 "Asked Steam to install Lepton": "",
+ "Asked to test a fix? Dev builds come before the next release.": "",
 "Assassin's Creed Nexus (build 207706 only): turns off application space warp and runs at 72 Hz.": "",
 "Assassin's Creed Nexus (build 207706 only): turns off application space warp and runs at 90 Hz.": "",
 "Assassin's Creed Nexus: smoother picture at 72 Hz (turns off Meta's frame-rate trick).": "",
@@ -132,10 +146,14 @@
 "Automatic SteamVR performance settings (this PC)": "",
 "Back to library": "",
 "Back up the signing keys ({len}) to {shown_dir} first": "",
+ "Banner": "",
+ "Before a swapchain image is handed to the Frame, wait until the game's GPU work on it has finished, for games that hand over images early (an eye flickers or jitters). Costs some frame time. 2 = only after the first 60 s (compare both in one session).": "",
 "Before each Play on this PC, FramePort reads SteamVR's record of the game's last session (frames dropped; frame times from fpsVR if installed). If it dropped frames, it lowers the game's refresh rate to one whose frame budget fits (e.g. 96 → 90 Hz) and turns motion smoothing on, through SteamVR's per-application settings; each later session can step down again. Set a refresh rate or smoothing mode here to choose yourself. Ignored on the Frame.": "",
 "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 (e.g. 4XVR's Internal Storage = 4XPlayer): upload into that folder in the game's storage.": "",
+ "Build page": "",
+ "Cable connected.": "",
 "Can't reach your Frame. Make sure it's on, awake and on the same network, then try again.": "",
 "Can't run": "",
 "Cancel": "",
@@ -146,28 +164,34 @@
 "Ceiling height for scene_emul.": "",
 "Ceiling height of the pretend room.": "",
 "Change executable…": "",
+ "Change program…": "",
 "Change settings…": "",
 "Changes apply the next time FramePort starts.": "",
 "Changes apply to the next install. Hover a chip above for why it was suggested.": "",
 "Changes are used the next time the game starts. Not sure? Leave a setting as it is.": "",
+ "Change…": "",
 "Check": "",
 "Check exe": "",
 "Check for new versions automatically": "",
 "Check for updates": "",
 "Check game files": "",
+ "Check now": "",
 "Check that the Frame and this computer are on the same network.": "",
 "Checking this PC…": "",
 "Checking tools…": "",
- "Chooses which Proton version runs the game on the Frame.": "",
+ "Choose PNG, JPEG or WebP images. Steam fills any missing shape from the ones you choose; FramePort never replaces your images automatically.": "",
+ "Choose…": "",
+ "Chosen by you.": "",
 "Clean up Frida leftovers in smali": "",
 "Cleans up graphics data that crashes some Unreal games on the Frame.": "",
 "Clear": "",
 "Clear android:debuggable": "",
 "Clear finished": "",
 "Clear search": "",
+ "Clear selection": "",
 "Clear tags": "",
 "Click here, then type. Everything you type goes to the Frame (Esc and shortcuts too).": "",
- "Click to open · right-click for quick actions": "",
+ "Click to open · right-click for quick actions · drag across cards to select several": "",
 "Close": "",
 "Close FramePort": "",
 "Collect and open GitHub": "",
@@ -176,6 +200,7 @@
 "Collect logs: {title}": "",
 "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 computer with a USB cable (a data cable, not a charge-only one).": "",
 "Connect your Frame": "",
 "Connect your Frame first": "",
 "Connect your Steam Frame": "",
@@ -193,18 +218,22 @@
 "Copy": "",
 "Copy all": "",
 "Copy failed; select the text instead": "",
+ "Copy folder path": "",
 "Copy log": "",
 "Copy OVRPlugin if VrApi is present": "",
 "Copy OVRPort libraries": "",
 "Copy path": "",
 "Couldn't check this PC": "",
 "Couldn't connect: {exc}": "",
+ "Couldn't list the screenshots: {exc}": "",
 "Couldn't list {path}: {exc}": "",
+ "couldn't load the full image: {exc}": "",
 "Couldn't open the game's storage: {exc}": "",
 "Couldn't read the file list: {exc}": "",
 "Couldn't read the Frame's folders: {exc}": "",
 "Couldn't read {path}: {exc}": "",
 "Couldn't use {choice}: {exc}": "",
+ "Cover": "",
 "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.": "",
@@ -216,8 +245,21 @@
 "Declares Meta's permissions some mixed-reality games ask for, so they don't stop.": "",
 "Delete": "",
 "Delete {names}?": "",
+ "Delete {n} items…": "",
+ "Delete {n} screenshot?": [
+  "",
+  ""
+ ],
+ "Delete {n} screenshots…": "",
+ "Deleted {n} screenshot": [
+  "",
+  ""
+ ],
 "Deletes the rollback copies kept from each game's previous install and leftover uploads. The games and saves stay.": "",
+ "Delete…": "",
+ "Deselect": "",
 "Details": "",
+ "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 → Developer) lets FramePort find the Frame on your network and connect to it over SSH. The first-time setup command turns it on for you.": "",
 "Didn't finish ({value}): {error}": "",
 "Disable application space warp if used": "",
@@ -229,17 +271,33 @@
 "Don't pause on short interruptions": "",
 "done": "",
 "Done": "",
+ "Done: look for the cable": "",
 "Download": "",
+ "Download all": "",
+ "Download all ({n})…": "",
+ "Download selected": "",
 "Download to this PC": "",
+ "Download to this PC…": "",
 "Download to which folder on this PC?": "",
 "Download {name}": "",
+ "Download {n} items to this PC…": "",
+ "Download {n} screenshot": [
+  "",
+  ""
+ ],
+ "Download {n} screenshots…": "",
 "Downloaded when first needed": "",
 "Downloaded {n} file to {folder}": [
  "",
  ""
 ],
+ "Downloaded {n} screenshot to {folder}": [
+  "",
+  ""
+ ],
 "Downloading…": "",
 "Downloads": "",
+ "Download…": "",
 "Draws each eye separately; try it when one eye shows a grey or broken picture.": "",
 "Drop invalid layers": "",
 "Drop layers whose swapchain failed or whose extension isn't enabled.": "",
@@ -291,6 +349,7 @@
 "folder and everything in it": "",
 "Folder name": "",
 "Folder to upload to the Frame": "",
+ "Folder with a Linux app for arm64": "",
 "Folder with VR games (Android APKs or PC VR games)": "",
 "For apps that only know Quest 3/Pro controllers: without it they get no buttons.": "",
 "For games that crash right after you return to them (e.g. after the Steam menu).": "",
@@ -299,6 +358,7 @@
 "For games whose menus or screens jump to wherever you look.": "",
 "For heavy games that use application space warp: it causes artifacts or hangs on non-Quest runtimes (e.g. Asgard's Wrath 2, Batman: Arkham Shadow).": "",
 "For mixed-reality-only games. On the Frame, passthrough is emulated by the FrameBridge adapter (greyscale cameras).": "",
+ "For one eye looking wrong (e.g. a jittering right eye): logs each eye's submitted pose against a fresh one, the eye-to-eye relation and when each eye's image was released, also into framebridge.log in the game's storage (some games stop Android's log early). No effect on the game.": "",
 "For Unreal games that close themselves right after starting (e.g. Phantom: Covert Ops). Also disables the in-game Quit.": "",
 "Force enable passthrough": "",
 "Found": "",
@@ -310,6 +370,7 @@
 "FramePort": "",
 "FramePort can't replace itself in {value} (no permission): opening the release page to download it": "",
 "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 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).": "",
 "FramePort found more than one program that could start this game. Pick the one you'd double-click to play it. Oculus builds usually work better with Revive than Steam builds.": "",
 "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": "",
@@ -318,6 +379,7 @@
 "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.": "",
 "FramePort saves a diagnostics zip (logs, recipe, device info; no game files, personal data removed) and opens a prefilled GitHub issue. Drag the zip into it, check the text, submit.": "",
+ "FramePort then finds the Frame on the cable by itself.": "",
 "FramePort updates and restarts after the current job": "",
 "FramePort was removed": "",
 "FramePort {version} is available": "",
@@ -338,8 +400,11 @@
 "From the tested recipe for this game": "",
 "From the {src}": "",
 "Full launch log": "",
+ "Game": "",
 "Game arguments (select SteamVR / OpenXR)": "",
 "Game config files": "",
+ "Game configs are up to date": "",
+ "Game configs from GitHub: last checked {when}": "",
 "Game launch capacity": "",
 "Game not found": "",
 "Game settings": "",
@@ -361,6 +426,7 @@
 "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 multiview": "",
 "Go to my library": "",
+ "Go to System and turn on \"Enable Developer Mode\". A Developer page appears in Settings; nothing else changes, your games and data stay as they are.": "",
 "Graphics": "",
 "Hide Android's navigation bar": "",
 "Hide log": "",
@@ -369,6 +435,7 @@
 "Hides Android's back/home/recents buttons, which cover the app's own buttons.": "",
 "Hides Quest foveation extensions the Frame runtime lacks.": "",
 "Hides the Frame's brief focus dips (up to a second) once the game has been focused for a second. For games that recentre or pause every time focus returns.": "",
+ "Hides XR_FB_space_warp, so the game renders every frame itself instead of half of them plus motion vectors (Application SpaceWarp). For games whose picture flickers or smears on the Frame (e.g. Unreal Engine 5 games such as Into The Radius 2).": "",
 "High": "",
 "Higher is sharper but needs more power.": "",
 "Higher keeps more detail but uses more memory.": "",
@@ -378,14 +445,18 @@
 "How often the picture updates. Higher is smoother if the game can keep up.": "",
 "How well the game runs on the Steam Frame. \"Works\" and \"Works with issues\" come from recipes tested on a real Frame. \"Untested\" means FramePort suggested a recipe from the game's engine and VR API that nobody has confirmed yet. \"Can't run\" means there's a known blocker (for example a 32-bit-only game).": "",
 "I played it in the headset with this recipe": "",
+ "Icon": "",
 "If the pointer doesn't hit what you aim at, tilt it up or down.": "",
 "If Windows asked whether FramePort may use the network, allow it (Private networks).": "",
 "If you know the Frame's address.": "",
 "Ignore focus dips up to": "",
+ "Image for the {label}": "",
 "In your Steam library": "",
 "In your Steam library · launch settings changed — update it": "",
 "Install": "",
 "Install anyway": "",
+ "Install dev build": "",
+ "Install dev build {version}?": "",
 "Install it anyway to try it, e.g. with different patches.": "",
 "Install Lepton on the Frame": "",
 "Install missing": "",
@@ -395,6 +466,7 @@
 "Install Proton on the Frame?": "",
 "Install SteamVR from Steam to play PC VR games": "",
 "Install the alternate build (": "",
+ "Install the latest dev build…": "",
 "Install updates automatically (downloads in the background, installs when FramePort next starts)": "",
 "Install {len} on this PC": "",
 "Install {n} on Frame": "",
@@ -406,6 +478,8 @@
 "Installed · launch test failed": "",
 "Installed, but it didn't start properly: ": "",
 "Installing": "",
+ "Installs the app as it is, unpacked on the Frame, with an entry in its Steam library": "",
+ "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)": "",
 "into {value}": "",
 "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.": "",
@@ -415,6 +489,8 @@
 "it stopped at '{value}'": "",
 "It trusts this app, turns on Developer Mode and installs Lepton if needed. Turning on Developer Mode closes the desktop; the setup finishes on its own and FramePort connects by itself. You only do this once.": "",
 "It was removed from the library.": "",
+ "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…": "",
 "Java runtime": "",
 "Java, OVRPort and apksigner are ready.": "",
@@ -429,6 +505,7 @@
 "Keyboard disconnected: {error}": "",
 "KiB": "",
 "Language": "",
+ "Language packs from the game's files": "",
 "Last build": "",
 "Last launch test: {get} · furthest: {value}": "",
 "Later": "",
@@ -453,6 +530,7 @@
 "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 SDL and LÖVE games start on the Frame (they'd crash looking for a clipboard).": "",
+ "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 Unreal games accept a headset that isn't a Quest.": "",
@@ -460,13 +538,18 @@
 "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).": "",
 "Library": "",
+ "Linux": "",
+ "Linux app (arm64)": "",
+ "Linux VR app · OpenXR": "",
 "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.": "",
 "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.": "",
 "Longer for headsets that briefly think they're off your head.": "",
 "Looking for Frames on your network…": "",
+ "Looking for the Frame on a USB cable (Developer Mode on, USB-C port connected to this computer).": "",
 "Looking for your Frame…": "",
 "Looking up the store description and screenshots…": "",
 "Low": "",
@@ -502,25 +585,35 @@
 "Needs the Oculus Platform (Meta Horizon app) for its license check, which the Frame doesn't have — it crashes at startup there. Play it on this PC.": "",
 "Needs Windows (or WSL on Windows)": "",
 "Neutralises Meta XR Audio's Quest-only calls (Unity/Wwise).": "",
+ "never": "",
 "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 name": "",
 "Next": "",
+ "No": "",
 "No activity": "",
 "no answer from the Frame": "",
 "No artwork could be downloaded from that {source} result; the current artwork stays. Try another one.": "",
+ "No dev build is published right now": "",
 "No folders to rescan yet: add games with Scan a folder": "",
 "No Frames found. New Frame? Use first-time setup (step 1). Otherwise make sure Developer Mode is on (Settings → System → Developer) and the Frame is on the same network.": "",
 "No games found in that folder": "",
 "No limit": "",
 "No matching files": "",
 "No new games in {name}": "",
+ "No notes.": "",
 "No release notes.": "",
+ "No screenshots yet": "",
 "No Unreal crash reporter": "",
+ "No Wi-Fi needed: for networks that block the setup, and faster game uploads": "",
+ "No: a 2D app": "",
+ "None": "",
 "None found": "",
 "Normal": "",
 "Not enough space on the Frame": "",
 "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 now": "",
 "Not offered by Steam on this Frame yet": "",
@@ -545,7 +638,9 @@
 "Offline": "",
 "Older workaround for upside-down quads: rotates them 180° (quads are single-sided; prefer flip_emul).": "",
 "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).": "",
+ "On the Frame: SteamVR dashboard → Launch a program → Desktop, then app menu → System → Konsole, and run (it reaches this computer over the USB cable):": "",
 "On the Frame: SteamVR dashboard → Launch a program → Desktop, then app menu → System → Konsole, and run:": "",
 "On this PC": "",
 "On this PC, launch the game through Revive's OpenVR backend, which talks straight to SteamVR — the original, most reliable Revive path. On by default for PC installs. Turn it off to use Revive's newer OpenXR backend instead. Ignored on the Frame (which always uses OpenXR).": "",
@@ -561,6 +656,7 @@
 "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.": "",
 "Opens this player's storage on the Frame (Files tab): upload videos into the folder it lists": "",
 "OpenXR runtime": "",
+ "OR": "",
 "Or paste text to type it in one go": "",
 "Or turn on Developer Mode on the Frame (Settings → System → Developer): it then shows up under step 2. Open Settings → Developer → Pair new host on the Frame, click Connect there and approve FramePort. That way needs no connection into this computer.": "",
 "Override the guardian depth (0 = use guardian, min 1.5 m).": "",
@@ -571,6 +667,7 @@
 "OVRPort's OpenXR dispatcher aborts the app ('Wrong createInfo size', SIGABRT in libopenxr_loader.so xrCreateSwapchain) when a swapchain is wider or taller than 4096 px, which video players do for 8K video or big theatre textures (e.g. 4XVR). Raises the guard to 16384 px so the Frame's runtime (8192 px max) decides instead.": "",
 "OVRPort's own converter for games that use Meta's oldest VR interface (experimental).": "",
 "OVRPort's own VrApi→OpenXR adapter for engines that call libvrapi.so directly: the same upstream code as FramePort's 'VrApi → OpenXR bridge' without its Frame-specific changes. Only in OVRPort's experimental CLI builds (the stable CLI lists it but can't apply it).": "",
+ "OVRPort's platform loader answers the Meta Platform SDK's language-pack calls (ovr_LanguagePack_GetCurrent/SetCurrent) with 'no request', so a game that asks for its language pack never gets an answer. Adds a small library that serves language packs (<tag>.lang, e.g. de.lang) found in the game's own data folders (OBB and app files) through the same calls, the asset-file list and the status call, without any download. The game then finds the file path itself. The pack it applies with SetCurrent wins; otherwise the environment variable FRAMEPORT_LANGPACK (a tag), otherwise the only pack there is. Everything else goes to the loader unchanged. Off by default: turn it on for a game whose data has such files (the game page lists the patch only then).": "",
 "Package": "",
 "Pairing: on the Frame open Settings → Developer → Pair new host, then approve FramePort.": "",
 "Password (first time only)": "",
@@ -594,11 +691,13 @@
 "PC VR · Proton": "",
 "PC VR —": "",
 "PC VR ✓": "",
+ "Per-eye diagnostics (log)": "",
 "Pick several games and install them in one go. FramePort asks every question first, then works through the queue in the background.": "",
 "Picks a refresh rate and motion smoothing that suit the game on this PC.": "",
 "Pico/YVR/Quest metadata": "",
 "Picture": "",
 "pictures for the Steam library": "",
+ "Pictures you took in the headset (Steam screenshots on the Frame)": "",
 "Platform compat (ovrMessageType_ToString)": "",
 "Play on Frame": "",
 "Play on this PC": "",
@@ -614,6 +713,7 @@
 "Prevents a start-up crash in some Unreal games.": "",
 "Previous": "",
 "Problems and feedback": "",
+ "Program": "",
 "Proton couldn't run a test program (see the log)": "",
 "Proton debug log (Frame)": "",
 "Proton is Valve's Windows compatibility layer. On the Frame it runs PC VR games. Its ARM64 build isn't installed by default; FramePort can install it (Steam restarts once).": "",
@@ -622,6 +722,8 @@
 "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 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).": "",
 "Quest": "",
 "Quest games (Lepton)": "",
@@ -680,6 +782,7 @@
 "Removes {title}'s game files from the Frame. Saves are kept; the Steam entry disappears after the next Steam restart.": "",
 "Rename": "",
 "Rename {name}": "",
+ "Rename…": "",
 "Replace application label and icon": "",
 "Replaces libvrapi.so with a VrApi→OpenXR bridge (Android-XR-Bridge/OVRPort fork, GPL-3.0, patched for the Frame: GLES sessions, cylinder→quad layers, sRGB format fallback, 30 s VR-mode deadline, emulated time conversion). Needed when the engine calls VrApi itself instead of through OVRPlugin (e.g. The Climb 2, Path of the Warrior); OVRPort cannot translate those.": "",
 "Report a problem": "",
@@ -693,7 +796,10 @@
 ],
 "Reset to recommended": "",
 "Reset to suggested recipe": "",
+ "Restart": "",
 "Restart now": "",
+ "Restart the Frame": "",
+ "Restart the Frame?": "",
 "Resume": "",
 "Resuming — files already copied are skipped": "",
 "Retry rejected GLES formats/MSAA with sRGB, samples=1.": "",
@@ -707,12 +813,14 @@
 "Room width": "",
 "Rotate quads 180°": "",
 "Runs directly — no Revive needed": "",
+ "Runs natively on SteamOS, started from the Frame's Steam library": "",
 "Runs Oculus PC games on OpenXR": "",
 "Runs OVRPort and apksigner": "",
 "Runs the game directly": "",
 "Runs xrSyncActions one at a time with xrPollEvent and skips it for 250 ms after focus returns. For games that crash in the runtime's input code right after focus comes back (SIGSEGV in vrclient.so UpdateActionStateInternal / xrSyncActions, e.g. Myst).": "",
 "Save": "",
 "Save as known-good recipe": "",
+ "Save the screenshots to which folder on this PC?": "",
 "Saved as a known-good recipe": "",
 "Saved as known-good. Check the issue on GitHub and submit it": "",
 "Saved {name} (in {parent})": "",
@@ -724,10 +832,13 @@
 "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.": "",
+ "Screenshots": "",
+ "Screenshots on the Frame can be shown once FramePort is connected to it.": "",
 "SDL apps: start without a clipboard service": "",
 "Search": "",
 "Search again": "",
 "Search games and tags": "",
+ "Search the stores instead": "",
 "Searched a moment ago.": "",
 "Searching…": "",
 "See every patch and turn them on or off": "",
@@ -740,6 +851,7 @@
 "Set by you.": "",
 "Set up the connection to your Steam Frame first": "",
 "Set up the Frame": "",
+ "Set up with a USB cable": "",
 "Sets Unity QualitySettings antiAliasing to 0. Unity's multisampled render-to-texture path can hang the Frame's GL driver ('zink: DEVICE LOST', e.g. Sniper Elite VR). Try it for GLES Unity games that freeze or crash the GPU.": "",
 "Settings": "",
 "shader cache: makes later starts load faster; rebuilt if deleted": "",
@@ -755,14 +867,20 @@
 "Show less": "",
 "Show log": "",
 "Show more": "",
+ "Show only screenshots not from a FramePort game": "",
+ "Show only this game's screenshots": "",
 "Show progress": "",
 "Show setup command": "",
 "Show Steam Frame controllers": "",
 "Show technical details (patch ids, exact effects, parameters)": "",
 "Show the app's Android window (for typing)": "",
+ "Show video panels": "",
 "Showing {len} of {n}": "",
 "Shows 3D 360° pictures flat if they look doubled.": "",
 "Shows the Frame's cameras where the game expects passthrough.": "",
+ "Shows videos that games play on a flat panel (e.g. an intro video).": "",
+ "Shut down": "",
+ "Shut down the Frame?": "",
 "Signing keys matter: game updates must be signed with the same key or their saves are lost on reinstall.": "",
 "Signs rebuilt games": "",
 "Size": "",
@@ -772,6 +890,7 @@
 "Skip this version": "",
 "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": "",
 "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.": "",
 "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 need a second build with different OVRPort patches (for some Unreal games: one with Unreal's ForceQuit removed). Turn this on to install that build instead.": "",
@@ -779,6 +898,7 @@
 "Something went wrong": "",
 "Sort": "",
 "Source": "",
+ "square, 256 × 256": "",
 "Standard for every game": "",
 "Starting SteamVR and {title} — put your headset on": "",
 "Starting {title} on the Frame — put the headset on": "",
@@ -821,6 +941,8 @@
 "Switch Frame…": "",
 "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.": "",
+ "tall, 600 × 900": "",
 "Test": "",
 "Test Proton on the Frame": "",
 "Text and layout size": "",
@@ -831,14 +953,23 @@
 "The CPU types the game ships code for. The Frame runs only 64-bit ARM (arm64-v8a); 32-bit-only games can't run on it.": "",
 "The download didn't finish. Check your internet connection.": "",
 "The Frame can't show curved panels; this shows them as gently bent strips.": "",
+ "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.": "",
+ "The Frame is restarting.": "",
+ "The Frame is shutting down.": "",
 "the Frame isn't connected": "",
 "The Frame isn't connected": "",
+ "The Frame only offers its USB connection in Developer Mode:": "",
 "The Frame refused that password. Check it, or run the first-time setup instead: Steam Frame → Show setup command.": "",
+ "The Frame restarts in a few seconds; FramePort reconnects when it's back.": "",
+ "The Frame turns off in a few seconds. Turn it on again with its power button.": "",
 "The Frame went offline: {exc}": "",
 "The Frame's battery is at {pct} % and not charging. Plug it in (a strong charger, not a PC port): long installs can drain it, and FramePort pauses them at {pause} %.": "",
 "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 desktop password, only needed the first time so FramePort can add its own key. After that it connects with the key.": "",
+ "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 installed game (APK and its data)": "",
@@ -853,6 +984,7 @@
 "These games can't run on the Steam Frame": "",
 "These games check their Oculus license": "",
 "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.": "",
+ "They are deleted on the Frame and can't be restored. Steam's own screenshot list may still show them until Steam restarts.": "",
 "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).": "",
@@ -871,15 +1003,21 @@
 "This source checkout has uncommitted changes: commit or stash them, then update": "",
 "Tilts the controllers' pointing ray up (+) or down (−), for games whose pointer doesn't hit what you aim at.": "",
 "To finish, close FramePort and delete its program folder.": "",
+ "Today": "",
 "Tools": "",
 "Tools are up to date": "",
 "Translator for games built on Meta's oldest VR interface.": "",
+ "transparent PNG": "",
 "Treat newer Quest controllers as Touch": "",
 "Tried it in the headset? Tell us how it runs: with your recipe it can join FramePort's built-in list, so it works out of the box for everyone.": "",
 "Troubleshooting": "",
 "Try again": "",
 "Try now": "",
+ "Try Proton Experimental and reinstall": "",
 "Turn off only for games you play with your hands instead of controllers.": "",
+ "Turn off space warp": "",
+ "Turn on Developer Mode first": "",
+ "Turn the Frame off": "",
 "Turn this on if your copy is already patched: an APK is installed unchanged instead of being patched again. PC VR games are never modified on this PC; the Frame's copy only gets launch fixes.": "",
 "Turned around": "",
 "Turned on by you": "",
@@ -912,6 +1050,7 @@
 "Unity: disable MSAA": "",
 "Unity: keep MSAA off at runtime (OVRManager)": "",
 "Unity: render each eye separately (no multiview)": "",
+ "Unknown date": "",
 "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).": "",
 "Untested": "",
@@ -921,6 +1060,7 @@
 "Update available": "",
 "Update failed: {exc}": "",
 "Update FramePort to {version}": "",
+ "Update game configs from GitHub automatically (confirmed configs arrive without a FramePort update)": "",
 "Update now": "",
 "Update on Frame": "",
 "Update on this PC": "",
@@ -933,7 +1073,9 @@
 "Updates, tools, this PC and where FramePort keeps its data": "",
 "Updating works in the desktop app": "",
 "Upload files": "",
+ "Upload files…": "",
 "Upload folder": "",
+ "Upload folder…": "",
 "Upload to {label}": "",
 "Uploaded {n} file": [
  "",
@@ -946,6 +1088,8 @@
 "Use the repack's launcher (bundled Revive)": "",
 "Use this computer's keyboard on the Frame": "",
 "Use this program": "",
+ "Use your own artwork…": "",
+ "Use your own images…": "",
 "Uses OVRPort, Revive (LibreVR), Valve's Lepton and Proton. Not affiliated with Valve or Meta.": "",
 "Uses the Oculus Platform SDK: it checks your Oculus license. Normally that needs the Oculus app on this PC with a license you own, so it may quit right after starting on the headset. You can still try it.": "",
 "Uses the repack's bundled Revive — experimental on the Frame": "",
@@ -954,18 +1098,23 @@
 "Valve's Android runtime isn't installed (needs Developer Mode)": "",
 "Version": "",
 "Very high": "",
+ "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, documents, mods and saves on your Steam Frame": "",
+ "View": "",
 "View screenshot": "",
+ "VR (OpenXR)": "",
 "VrApi → OpenXR adapter (OVRPort)": "",
 "VrApi → OpenXR bridge": "",
 "Vulkan shader fixes": "",
 "Vulkan shim (frame.vk_sanitize): SPIR-V modules matching size + SHA-256 get words inserted at a byte offset, e.g. stores that initialize locals a shader reads before writing (an undefined loop counter hung the GPU in VR4's campaign). Format: <size>:<sha256>:<byte offset>:<word>,<word>,...; several separated by ';'. Comes from a game's recipe.": "",
 "Vulkan: drop invalid render-pass pointers": "",
 "v{remote} (updates on the next action)": "",
+ "Wait for the game's GPU before showing an image": "",
 "Waiting": "",
 "Waiting ({n})": "",
+ "Waiting for the cable…": "",
 "Waiting for the Frame": "",
 "Waiting for your Frame": "",
 "Waiting for your Frame… (code {code})": "",
@@ -976,7 +1125,10 @@
 "Where it's installed": "",
 "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}?": "",
- "Which Proton build runs the game on the Frame (a Steam compat tool name from the Frame's ARM64 compat list, e.g. proton_11-arm64 or proton-experimental-arm64). Empty = newest installed.": "",
+ "Which Proton build runs the game on the Frame: the stable Proton (the default: smoother in our tests) or Proton Experimental (gets Valve's ARM64 fixes first; try it when a game doesn't start or runs badly). Also takes any compat tool name from the Frame's ARM64 list.": "",
+ "Which Proton runs the game on the Frame: Stable is smoother; choose Experimental if the game doesn't start or runs badly.": "",
+ "Wide cover": "",
+ "wide, 1920 × 620": "",
 "Windows": "",
 "Windows game (Proton)": "",
 "Windows not detected": "",
@@ -996,6 +1148,10 @@
 "Writes liboverport.config.so with runtime options.": "",
 "Writes the conversion's settings into the game.": "",
 "XR_FB_passthrough via ALPHA_BLEND (Frame greyscale cameras).": "",
+ "Yes": "",
+ "Yes: uses the Frame's OpenXR runtime": "",
+ "Yesterday": "",
+ "You already have the latest dev build ({version})": "",
 "You have the latest version as of the last check ({when}).": "",
 "You have {version}. {how}": "",
 "Your copy is used as it is (only the Frame's copy gets launch patches)": "",
@@ -1005,6 +1161,7 @@
 "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 headset, what it's ready for and what's installed": "",
+ "Your own artwork for {title}": "",
 "Your own game files aren't touched.": "",
 "Your own tags (filled) can be anything you like. Outlined tags are added automatically from the engine, VR API and store genres. Filter the library by either.": "",
 "{count} files · {human}": "",
@@ -1022,10 +1179,14 @@
 "{int} h ago": "",
 "{int} min ago": "",
 "{label} ({host}) isn't reachable. Make sure it's switched on and on the same network.": "",
+ "{label} removed for {title}.": "",
+ "{label} updated for {title}.": "",
 "{len} known-good recipes (bundled, remote and yours)": "",
 "{len} results": "",
 "{len} selected": "",
+ "{message} The Frame's Steam library still shows the old art.": "",
 "{n_pc} on this PC": "",
+ "{name} isn't a Linux app (an AppImage, a Linux program or a .zip/.tar archive)": "",
 "{n} file": [
  "",
  ""
@@ -1042,6 +1203,10 @@
  "",
  ""
 ],
+ "{n} game config was updated": [
+  "",
+  ""
+ ],
 "{n} game didn't work out": [
  "",
  ""
@@ -1055,10 +1220,18 @@
  ""
 ],
 "{n} lines, the last 4000 shown": "",
+ "{n} needs a newer FramePort": [
+  "",
+  ""
+ ],
 "{n} new game in {name}": [
  "",
  ""
 ],
+ "{n} screenshot": [
+  "",
+  ""
+ ],
 "{n} selected": "",
 "{n} setting changed from the default": [
  "",
@@ -1077,6 +1250,7 @@
 "{title}: launch test {verdict} (furthest: {value})": "",
 "{title}: Steam artwork updated on the Frame": "",
 "{user}@{host} · {get} {get2} (build {get3})": "",
+ "{value:.0f} MiB": "",
 "{value:.1f} GiB": "",
 "{value} didn't work out": "",
 "{value} failed ({returncode})": "",
@@ -0,0 +1,90 @@
+"""Language packs (`<tag>.lang` files in the game's data) for the Meta Platform SDK (native/langpack)."""
+from __future__ import annotations
+
+from ...analysis import elf
+from ..base import ApkContext, Patch, register
+from . import artifact
+
+LOADER = "libovrplatformloader.so"
+LIB = "libfp_langpack.so"
+META_MARK = b"@FPMETA@\0"  # native/langpack: g_meta_slot = marker + META_LEN bytes the Metadata is written into
+META_LEN = 96
+
+
+def with_metadata(lib: bytes, text: str) -> bytes:
+    """The library with `text` (the game's versionName) as the Metadata of the packs it serves.
+
+    Unreal games such as Deadpool VR only treat a pack as installed when its Metadata equals their own version string,
+    which Meta's store sets when the pack is uploaded."""
+    raw = text.encode("utf-8")
+    at = lib.find(META_MARK)
+    if not raw or len(raw) >= META_LEN or at < 0:
+        return lib
+    at += len(META_MARK)
+    return lib[:at] + raw + b"\0" * (META_LEN - len(raw)) + lib[at + META_LEN:]
+
+# Every function native/langpack/langpack.c defines. The loader's own exports of these are hidden (see
+# elf.hide_exports) so lookups reach LIB first; tests/test_langpack.py keeps this list equal to the C source.
+EXPORTS = (
+    "ovr_AssetDetailsArray_GetElement", "ovr_AssetDetailsArray_GetSize", "ovr_AssetDetails_GetAssetId",
+    "ovr_AssetDetails_GetAssetType", "ovr_AssetDetails_GetDownloadStatus", "ovr_AssetDetails_GetFilepath",
+    "ovr_AssetDetails_GetIapStatus", "ovr_AssetDetails_GetLanguage", "ovr_AssetDetails_GetMetadata",
+    "ovr_AssetFileDownloadResult_GetAssetId", "ovr_AssetFileDownloadResult_GetFilepath", "ovr_AssetFile_GetList",
+    "ovr_AssetFile_StatusById", "ovr_Error_GetCode", "ovr_Error_GetDisplayableMessage", "ovr_Error_GetHttpCode",
+    "ovr_Error_GetMessage", "ovr_FreeMessage", "ovr_LanguagePackInfo_GetEnglishName",
+    "ovr_LanguagePackInfo_GetNativeName", "ovr_LanguagePackInfo_GetTag", "ovr_LanguagePack_GetCurrent",
+    "ovr_LanguagePack_SetCurrent", "ovr_Message_GetAssetDetails", "ovr_Message_GetAssetDetailsArray",
+    "ovr_Message_GetAssetFileDownloadResult", "ovr_Message_GetError", "ovr_Message_GetRequestID",
+    "ovr_Message_GetType", "ovr_Message_IsError", "ovr_PopMessage",
+)
+
+
+class LanguagePacks(Patch):
+    id = "frame.langpacks"
+    title = "Language packs from the game's files"
+    description = ("OVRPort's platform loader answers the Meta Platform SDK's language-pack calls "
+                   "(ovr_LanguagePack_GetCurrent/SetCurrent) with 'no request', so a game that asks for its language "
+                   "pack never gets an answer. Adds a small library that serves language packs (<tag>.lang, e.g. "
+                   "de.lang) found in the game's own data folders (OBB and app files) through the same calls, the "
+                   "asset-file list and the status call, without any download. The game then finds the file path "
+                   "itself. The pack it applies with SetCurrent wins; otherwise the environment variable "
+                   "FRAMEPORT_LANGPACK (a tag), otherwise the only pack there is. Everything else goes to the "
+                   "loader unchanged. Off by default: turn it on for a game whose data has such files (the game "
+                   "page lists the patch only then).")
+    order = 32
+    experimental = True  # opt-in: checked in a headset with Deadpool VR, AC Nexus and Asgard's Wrath 2 only
+
+    # never part of a default recipe (few games tested): shown under Customize for games whose data has
+    # language packs, off until the user turns it on
+
+    def applies(self, a):
+        return LOADER in a.libs and "arm64-v8a" in a.abis and bool((a.extra or {}).get("lang_packs"))
+
+    def apply(self, ctx: ApkContext) -> bool:
+        ws = ctx.ws
+        if ws.abi != "arm64-v8a" or not ws.has(ws.lib(LOADER)):
+            return False
+        loader = ws.read_lib(LOADER)
+        patched, hidden = elf.hide_exports(loader, EXPORTS)
+        if not hidden and LIB in elf.needed(loader):
+            return False  # applied by an earlier build
+        if not hidden:
+            ctx.notes.append("the platform loader has none of the language-pack functions: nothing to replace")
+            return False
+        patched = elf.add_needed(patched, LIB)
+        ws.put(ws.lib(LOADER), patched)
+        version = (ctx.analysis.version or "").strip()
+        ws.put(ws.lib(LIB), with_metadata(artifact(ws.abi, LIB), version))
+        ctx.notes.append(f"language packs served by {LIB} ({len(hidden)} loader functions replaced, "
+                         f"Metadata \"{version}\")")
+        return True
+
+    def validate(self, ctx: ApkContext):
+        ws = ctx.ws
+        if not ws.has(ws.lib(LOADER)):
+            return []
+        linked = LIB in elf.needed(ws.read_lib(LOADER))
+        return [("Language-pack library linked to the platform loader", linked and ws.has(ws.lib(LIB)), LIB)]
+
+
+register(LanguagePacks)
@@ -97,6 +97,10 @@ class OverportPatch(Patch):
                return Suggestion(True, f"Very heavy game ({total / 2**30:.0f} GiB) using OVRPlugin: application space "
                                        "warp causes artifacts/hangs off-Quest.")
            return Suggestion(False, "Enable if the game shows warping artifacts or hangs (uses OVRPlugin space warp).")
+        if self.id == "patch_ac_nexus_no_appsw_90" and self.applies(a):
+            # verified in the headset (owner preferred 90 Hz over 72): the catalog default, now also without it
+            return Suggestion(True, "This Assassin's Creed Nexus build runs smoothly on the Frame without application "
+                                    "space warp, at 90 Hz.")
        if self.id == "patch_remove_unreal_force_quit" and ap.is_unreal(a):
            return Suggestion(False, "Built as the alternate APK for Unreal games (use it if the game quits itself).")
        return None
@@ -202,10 +202,12 @@ class ProtonLog(_PcvrPatch):
 class ProtonTool(_PcvrPatch):
    id = "pcvr.proton_tool"
    title = "Proton version (Frame)"
-    description = ("Which Proton build runs the game on the Frame (a Steam compat tool name from the Frame's ARM64 "
-                   "compat list, e.g. proton_11-arm64 or proton-experimental-arm64). Empty = newest installed.")
+    description = ("Which Proton build runs the game on the Frame: the stable Proton (the default: smoother in our "
+                   "tests) or Proton Experimental (gets Valve's ARM64 fixes first; try it when a game doesn't start "
+                   "or runs badly). Also takes any compat tool name from the Frame's ARM64 list.")
    order = 40
-    params = [Param("tool", "str", "", "compat tool name")]
+    params = [Param("tool", "str", "", "proton-stable (default), proton-experimental, or a compat tool name")]
+    CHOICES = (("", "Stable (default)"), ("proton-experimental", "Experimental"))


 class ProtonEnv(_PcvrPatch):
@@ -16,6 +16,10 @@ SETTINGS = [
    ("scale", "float", 1.0, "Resolution scale",
     "Multiplies the recommended eye-buffer width and height (0.5–2.0). 1.5 ≈ 2.25× pixels."),
    ("foveation_fix", "int", 1, "Hide Quest foveation", "Hides Quest foveation extensions the Frame runtime lacks."),
+    ("hide_space_warp", "int", 0, "Turn off space warp",
+     "Hides XR_FB_space_warp, so the game renders every frame itself instead of half of them plus motion vectors "
+     "(Application SpaceWarp). For games whose picture flickers or smears on the Frame (e.g. Unreal Engine 5 games "
+     "such as Into The Radius 2)."),
    ("controller_fix", "int", 1, "Report Touch controllers",
     "Reports Frame controllers as Oculus Touch and hides synthetic hand tracking. Set 0 for games that require hand "
     "tracking (e.g. Silhouette)."),
@@ -31,6 +35,11 @@ SETTINGS = [
    ("cylinder_strips", "int", 1, "Show curved panels",
     "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."),
+    ("surface_emul", "int", 1, "Show video panels",
+     "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."),
    ("equirect_emul", "int", 0, "Show 360° layers",
     "360° (equirect) layers, e.g. a video player's virtual theatre or 360° videos (e.g. 4XVR), which the Frame's "
     "runtime lacks, are drawn by a background thread into a layer behind the game's own picture: the 360° image is "
@@ -78,6 +87,14 @@ SETTINGS = [
    ("layer_debug", "int", 0, "Extra diagnostics (log)",
     "Logs details for debugging: composition layers and swapchains, focus changes, play-space creation, pointer vs "
     "grip poses, refresh rates. No effect on the game."),
+    ("eye_debug", "int", 0, "Per-eye diagnostics (log)",
+     "For one eye looking wrong (e.g. a jittering right eye): logs each eye's submitted pose against a fresh one, the "
+     "eye-to-eye relation and when each eye's image was released, also into framebridge.log in the game's storage "
+     "(some games stop Android's log early). No effect on the game."),
+    ("release_wait", "int", 0, "Wait for the game's GPU before showing an image",
+     "Before a swapchain image is handed to the Frame, wait until the game's GPU work on it has finished, for games "
+     "that hand over images early (an eye flickers or jitters). Costs some frame time. 2 = only after the first 60 s "
+     "(compare both in one session)."),
    ("scene_emul", "int", 0, "Emulate Meta scene (room)",
     "Fake XR_FB_scene/spatial entities: a guardian-sized room with floor, ceiling and four walls, for mixed-reality "
     "games that build their level from the room (e.g. Demeter)."),
@@ -150,6 +167,9 @@ UI: dict[str, dict] = {
    "cylinder_strips": dict(group="screens", level="common", label="Show curved menus and screens",
                            help="The Frame can't show curved panels; this shows them as gently bent strips.",
                            control=("switch",)),
+    "surface_emul": dict(group="screens", level="common", label="Show video panels",
+                         help="Shows videos that games play on a flat panel (e.g. an intro video).",
+                         control=("switch",)),
    "flip_emul": dict(group="screens", level="common", label="Fix upside-down menus",
                      help="Turns menus and text the right way up.", control=("switch",)),
    "stable_local": dict(group="screens", level="common", label="Keep menus in place",
@@ -190,8 +210,9 @@ UI: dict[str, dict] = {
                            help="Shows 3D 360° pictures flat if they look doubled.",
                            control=("choice", [(0, "As the game sends it"), (2, "Flat")])),
    **{key: dict(group="troubleshooting", level="advanced", control=("switch",)) for key in (
-        "foveation_fix", "swapchain_fix", "layer_fix", "gl_hide_multiview", "mutable_fix", "flip_quads", "swap_eyes",
-        "strip_depth", "respace_kick", "layer_debug")},
+        "foveation_fix", "hide_space_warp", "swapchain_fix", "layer_fix", "gl_hide_multiview", "mutable_fix",
+        "flip_quads", "swap_eyes",
+        "strip_depth", "respace_kick", "layer_debug", "eye_debug", "release_wait")},
 }


@@ -220,6 +241,11 @@ class AdapterSetting(Patch):
        if self.key == "equirect_emul" and uses_equirect_layers(a):
            return Suggestion(True, "The game draws 360° layers (e.g. a video player's theatre or 360° videos), which "
                                    "the Frame's runtime can't show: show them as panels around you.", {"value": 1})
+        if self.key == "hide_space_warp" and "libUnreal.so" in a.libs and "libOVRPlugin.so" in a.libs:
+            # Unreal Engine 5 + Meta's plugin: Application SpaceWarp is on by default (Into The Radius 2 flickered;
+            # OVRPort's patch_disable_space_warp doesn't reach UE5). Off until confirmed in more games.
+            return Suggestion(False, "Unreal Engine 5 game with Meta's space warp: turn on if the picture flickers or "
+                                     "smears (e.g. Into The Radius 2).", {"value": 1})
        if self.key == "scene_emul" and needs_scene(a):
            return Suggestion(True, "Mixed-reality game that builds its level from the room model: emulate a "
                                    "guardian-sized room (e.g. Demeter).", {"value": 1})
@@ -42,6 +42,8 @@ SUMMARIES = {
    "frame.meta_permissions": "Declares Meta's permissions some mixed-reality games ask for, so they don't stop.",
    "frame.ovrplatformcompat": "Adds a small piece of Meta's platform library that some games need to start.",
    "frame.ovrstubs": "Provides stand-ins for Meta store functions the game expects, so it doesn't crash at start.",
+    "frame.langpacks": "Lets the game find language files (like de.lang) that are already in its data, instead of "
+                       "waiting for a download that never comes.",
    "frame.unity_no_msaa": "Turns off a smoothing setting that crashes some older Unity games on the Frame.",
    "frame.unity_runtime_msaa_off": "Keeps a smoothing setting off that the game turns on itself and that can freeze "
                                    "the Frame.",
@@ -72,7 +74,8 @@ SUMMARIES = {
    "pcvr.revive_openvr": "On this PC, runs Revive through SteamVR (works with more headsets).",
    "pcvr.xr_timefix": "Lets games written for newer OpenXR versions run on the Frame.",
    "pcvr.proton_log": "Writes a detailed Proton log for troubleshooting.",
-    "pcvr.proton_tool": "Chooses which Proton version runs the game on the Frame.",
+    "pcvr.proton_tool": "Which Proton runs the game on the Frame: Stable is smoother; choose Experimental if the "
+                        "game doesn't start or runs badly.",
    "pcvr.steamvr_tuning": "Picks a refresh rate and motion smoothing that suit the game on this PC.",
    "pcvr.proton_env": "Extra settings for Proton (for testing).",
 }
@@ -9,10 +9,12 @@ PC (Revive + local Steam) or on the Frame (Proton + Revive).
 """
 from __future__ import annotations

+import threading
 import time
 from pathlib import Path

 from . import build as builder
+from .analysis import langpacks
 from .analysis.detect import analyze
 from .artwork import fetch as artwork
 from .core import library
@@ -252,6 +254,12 @@ def fetch_details(package: str, reporter: Reporter | None = None) -> dict:
 def set_exe(package: str, exe: str) -> dict:
    """The user picked the program that starts a Rift game: re-analyze with it (keeps recipe choices and tags)."""
    entry = library.game(package)
+    if entry and is_linux(entry):  # a Linux app: the same source again, with this program
+        folder = Path(entry["game_dir"])
+        if not (folder / exe).is_file():
+            raise FileNotFoundError(folder / exe)
+        source = ((entry.get("analysis") or {}).get("extra") or {}).get("source") or entry["game_dir"]
+        return add_linux_app(source, exe=exe)
    if not entry or entry.get("kind") != "rift":
        raise ValueError(f"{package} is not a Rift game")
    folder = Path(entry["game_dir"])
@@ -271,10 +279,80 @@ def is_rift(entry: dict) -> bool:
    return entry.get("kind") == "rift"


+def is_linux(entry: dict) -> bool:
+    """A native arm64 Linux app (AppImage / folder / archive), installed as it is (GitHub #31)."""
+    return entry.get("kind") == "linux"
+
+
+def add_linux_app(path: Path | str, reporter: Reporter | None = None, exe: str | None = None) -> dict:
+    """Add an arm64 Linux app to the library (no conversion: it's installed as it is). `exe` overrides the program
+    FramePort picked (relative to the app's folder)."""
+    from .analysis import linux
+    from .core.models import Recipe
+
+    path = Path(path)
+    info = linux.inspect(path)
+    if exe:
+        info["exe"] = exe
+    if not info["arch_ok"]:
+        arch = "x86_64" if info["machine"] == linux.EM_X86_64 else f"machine {info['machine']}"
+        raise ValueError(f"{path.name} is built for {arch}, not arm64 (aarch64): it can't run on the Frame. Look for "
+                         "an aarch64/arm64 download of it.")
+    package = f"linux.{linux.slug(info['title'])}"
+    if reporter:
+        reporter.log(f"{info['title']}: program {info['exe']}{' (AppImage)' if info['appimage'] else ''}"
+                     f"{', OpenXR (VR)' if info['openxr'] else ''}")
+    recipe = Recipe(package=package, title=info["title"], overport=False, as_is=True, source="heuristics")
+    analysis = {"package": package, "label": info["title"], "engine": "Linux", "xr": "OpenXR" if info["openxr"]
+                else "none", "abis": ["arm64-v8a"], "libs": [], "extra": {**info, "vr_kind": "openxr" if info["openxr"]
+                                                                            else "none", "source": str(path)}}
+    old = library.game(package) or {}
+    root = Path(info["root"])
+    try:  # what an install uploads (the library's size sort, the Frame's free-space check)
+        size = sum((root / f).stat().st_size for f in info["files"]) if info["files"] else \
+            sum(f.stat().st_size for f in root.rglob("*") if f.is_file())
+    except OSError:
+        size = 0
+    fields = dict(kind="linux", name=path.name, apk=None, game_dir=info["root"], exe=info["exe"], data_dir=None,
+                  origin=str(path.parent), analysis=analysis, suggested=library.recipe_to_dict(recipe),
+                  data_bytes=size)
+    if not old:
+        fields.update(title=info["title"], recipe=library.recipe_to_dict(recipe), status="unknown")
+    library.upsert_game(package, **fields)
+    try:
+        from .artwork import fetch
+
+        fetch.artwork_dir(package)
+        from .artwork import steam
+
+        steam.ensure_cover(package)  # placeholder art (name on a colour) until the user picks some
+    except Exception:  # noqa: BLE001 - artwork is optional
+        pass
+    return library.game(package)
+
+
+def install_linux(package: str, target: Target, reporter: Reporter, add_to_library: bool = True) -> dict:
+    entry = library.game(package)
+    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)
+    if result.get("missing_libraries"):
+        reporter.check("Libraries on the Frame", False, "missing: " + ", ".join(result["missing_libraries"]) +
+                       " (SteamOS doesn't have them and the app doesn't bundle them: it won't start)")
+    else:
+        reporter.check("Libraries on the Frame", True, "everything the app needs is there")
+    if add_to_library:
+        target.add_to_library([package], reporter)
+    _record_install(package, target.label, {"exe": entry["exe"], "result": result, "time": time.time()})
+    return result
+
+
 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)
    recipe = engine.suggest(a)
    return library.upsert_game(
        a.package, title=recipe.title or a.label, name=src.name, apk=str(src.apk),
@@ -294,6 +372,7 @@ def reanalyze(package: str, 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)
    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),
@@ -399,8 +478,19 @@ def recipe_fingerprint(recipe: dict) -> str:
    return fp(recipe)


+_build_locks: dict[str, threading.Lock] = {}
+_build_locks_guard = threading.Lock()
+
+
+def _build_lock(package: str) -> threading.Lock:
+    with _build_locks_guard:
+        return _build_locks.setdefault(package, threading.Lock())
+
+
 def build_game(package: str, reporter: Reporter, outdir: Path | None = None) -> dict:
    entry = library.game(package)
+    if is_linux(entry):  # nothing to convert: installed as it is
+        return {"ok": True, "linux": True}
    if is_rift(entry):
        return prepare_rift(package, reporter)
    if library.recipe_from_dict(entry["recipe"]).as_is:
@@ -409,7 +499,8 @@ def build_game(package: str, reporter: Reporter, outdir: Path | None = None) ->
    a = library.analysis_from_dict(entry["analysis"])
    recipe = library.recipe_from_dict(entry["recipe"])
    out = outdir or (output_dir() / quest_dump.display_name(entry.get("name") or package))
-    res = builder.build(src, a, recipe, out, reporter)
+    with _build_lock(package):  # one build per game at a time: builds share the game's work folder
+        res = builder.build(src, a, recipe, out, reporter)
    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,
@@ -422,6 +513,8 @@ def install_game(package: str, target: Target, reporter: Reporter, apk_only: boo
                 add_to_library: bool = True, apk: Path | None = None) -> dict:
    """Install the game's last build (or `apk`, e.g. a test build of the same package signed with the same key)."""
    entry = library.game(package)
+    if is_linux(entry):
+        return install_linux(package, target, reporter, add_to_library)
    if is_rift(entry):
        return install_rift(package, target, reporter, add_to_library)
    test_build = apk is not None
@@ -464,13 +557,17 @@ def local_game_files(package: str) -> list[Path]:
    paths: list[Path] = []
    if g.get("kind") == "rift":
        paths += [Path(g["game_dir"])] if g.get("game_dir") else []
+    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]
    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 for p in (o.get("apk"), o.get("data_dir"), o.get("game_dir")) if p]
+    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]
+    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
        rp = p.resolve()
@@ -478,6 +575,21 @@ def local_game_files(package: str) -> list[Path]:
    return [p for p in dict.fromkeys(paths) if p.exists() and not shared(p)]


+def linux_local_files(g: dict) -> list[Path]:
+    """A Linux app's own files: a lone AppImage/program (never the folder it sits in, e.g. Downloads), the app's
+    folder, or the archive it came from + FramePort's unpacked copy of it."""
+    extra = (g.get("analysis") or {}).get("extra") or {}
+    root = Path(g["game_dir"]) if g.get("game_dir") else None
+    if root is None:
+        return []
+    if extra.get("files"):
+        return [root / f for f in extra["files"]]
+    source = Path(extra["source"]) if extra.get("source") else None
+    if source is not None and source.is_file():  # an archive: it and its unpacked copy in FramePort's data folder
+        return [source, root]
+    return [root]
+
+
 def delete_local_files(package: str) -> tuple[list[str], int]:
    """Delete local_game_files(package), then the game's folder if that left it empty, and drop the library entry (the
    game can't be rebuilt without its files). Returns (deleted paths, bytes freed)."""
@@ -485,7 +597,8 @@ def delete_local_files(package: str) -> tuple[list[str], int]:

    files = local_game_files(package)
    freed, done = 0, []
-    parents = {p.parent for p in files}
+    # (not for Linux apps: a lone AppImage's folder is the user's, e.g. Downloads)
+    parents = set() if is_linux(library.game(package) or {}) else {p.parent for p in files}
    for p in files:
        size = sum(f.stat().st_size for f in p.rglob("*") if f.is_file()) if p.is_dir() else p.stat().st_size
        shutil.rmtree(p) if p.is_dir() else p.unlink()
@@ -555,14 +668,30 @@ def test_game(package: str, target: Target, reporter: Reporter, seconds: int = 4
    for old in sorted(logs.glob(f"{package}-*.log"))[:-5]:  # keep the last 5 per game
        old.unlink(missing_ok=True)
    reporter.log(f"full launch log ({len((log or '').splitlines())} lines): {log_path}")
+    suggestions = useful_suggestions(package, result.suggestions())
+    if proton_alternative_worth_trying(package, result.verdict):
+        suggestions.append(PROTON_TOOL)
+        reporter.log("it failed on the stable Proton: the suggestion is to try Proton Experimental")
    summary = {"state": result.state, "verdict": result.verdict, "milestone": result.milestone, "fps": result.fps,
               "findings": [f.__dict__ for f in result.findings],
-               "suggestions": useful_suggestions(package, result.suggestions()),
+               "suggestions": suggestions,
               "time": time.time(), "target": target.label, "log_path": str(log_path)}
    library.upsert_game(package, last_test=summary)
    return summary


+PROTON_TOOL = "pcvr.proton_tool"  # as a suggestion: run the game with Proton Experimental instead of the stable one
+
+
+def proton_alternative_worth_trying(package: str, verdict: str | None) -> bool:
+    """A PC VR game failed its launch test on the stable Proton (the default): Proton Experimental is worth a try."""
+    entry = library.game(package) or {}
+    if not is_rift(entry) or verdict == "pass":
+        return False
+    chosen = ((entry.get("recipe") or {}).get("patches") or {}).get(PROTON_TOOL) or {}
+    return "experimental" not in (chosen.get("tool") or "")
+
+
 def useful_suggestions(package: str, suggestions: list[str]) -> list[str]:
    """Triage suggestions that would change something: not already on, and not conflicting with the recipe (e.g. no
    Revive for a repack that runs its own)."""
@@ -584,6 +713,10 @@ def apply_suggestions(package: str, suggestions: list[str]) -> Recipe:
    entry = library.game(package)
    recipe = library.recipe_from_dict(entry["recipe"])
    for pid in suggestions:
+        if pid == PROTON_TOOL:
+            recipe.patches[pid] = {"tool": "proton-experimental"}
+            recipe.reasons[pid] = "It failed on the stable Proton: trying Proton Experimental."
+            continue
        if pid.startswith("adapter."):
            from .patches.base import get

@@ -2,8 +2,11 @@

 Sources, highest priority first:
  1. user entries   <user data>/catalog/games/*.yaml  (written by "Save as known-good" after a successful test)
-  2. remote catalog FRAMEPORT_CATALOG_URL (a folder URL serving index.json + <package>.yaml), cached; lets the
-                    catalog be updated without a new app release
+  2. remote catalog the repo's catalog/games on GitHub `main` (default; or FRAMEPORT_CATALOG_URL, a folder URL serving
+                    index.json + <package>.yaml): confirmed configs reach installed apps without a release. Fetched
+                    in the background (refresh_remote, at most every 6 h); loading only reads the cache. An entry that
+                    needs a newer FramePort (a patch, adapter setting or recipe field this version doesn't know, or
+                    min_app above this version) is skipped: the bundled entry stays.
  3. bundled        catalog/games/*.yaml in this repo
 """
 from __future__ import annotations
@@ -50,6 +53,7 @@ class CatalogEntry:
    as_is: bool = False  # Rift: the dump runs unchanged (e.g. a SteamVR build: no Revive)
    verified: dict = field(default_factory=dict)
    updated: str = ""  # date of the last maintainer change without a new headset test (e.g. a fix from a report)
+    min_app: str = ""  # oldest FramePort version this entry is for (remote entries for a newer app are skipped)
    source_hint: str = ""
    origin: str = "bundled"

@@ -96,10 +100,143 @@ def _load_dir(path: Path, origin: str) -> dict[str, CatalogEntry]:
 PACKAGE_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)+$")


+REMOTE_EVERY = 6 * 3600
+GITHUB_TREE = "https://api.github.com/repos/{repo}/git/trees/{ref}?recursive=1"
+GITHUB_RAW = "https://raw.githubusercontent.com/{repo}/{ref}/{path}"
+GITHUB_DIR = "catalog/games/"
+
+
+def _repo() -> str:
+    from .. import REPO_URL
+
+    return REPO_URL.removeprefix("https://github.com/").strip("/")
+
+
+def remote_enabled() -> bool:
+    """Automatic catalog updates from GitHub (Settings; FRAMEPORT_NO_CATALOG_UPDATE=1 turns them off)."""
+    from ..core import library
+
+    if os.environ.get("FRAMEPORT_NO_CATALOG_UPDATE"):
+        return False
+    try:
+        return bool(library.setting("catalog.auto_update", True))
+    except Exception:  # noqa: BLE001 - no library yet
+        return True
+
+
+def unusable_reason(entry_dict: dict) -> str | None:
+    """Why this FramePort can't use a (remote) entry, or None: a recipe field, patch or adapter setting it doesn't
+    know (the entry was written for a newer FramePort), or min_app above this version."""
+    from .. import __version__
+    from ..patches import base
+    from ..updates import parse_version
+
+    unknown = [k for k in entry_dict if k not in CatalogEntry.__dataclass_fields__]
+    if unknown:
+        return f"unknown field(s) {', '.join(sorted(unknown))}"
+    if entry_dict.get("min_app") and parse_version(str(entry_dict["min_app"])) > parse_version(__version__):
+        return f"needs FramePort {entry_dict['min_app']}"
+    base.load_all()  # every patch registered (overport ids come from this app's OVRPort list)
+    known = set(base.REGISTRY)
+    ids = [i for key in ("overport_extra", "overport_remove", "alt_overport", "frame", "frame_remove", "device",
+                         "pcvr", "pcvr_remove") for i in (entry_dict.get(key) or [])]
+    ids += [f"adapter.{k}" for k in (entry_dict.get("adapter") or {})]
+    missing = [i for i in ids if isinstance(i, str) and i not in known]
+    return f"unknown patch(es) {', '.join(missing)}" if missing else None
+
+
+def _remote_index_path() -> Path:
+    return cache.cache_dir() / "catalog-github.json"
+
+
+def refresh_remote(force: bool = False) -> int:
+    """Fetch new/changed entries from GitHub main into the cache (one API call for the file list + one raw download
+    per changed file). Returns the number of files downloaded. Never raises (offline: the cache stays)."""
+    import json
+    import time
+
+    if not remote_enabled() or os.environ.get("FRAMEPORT_CATALOG_URL"):
+        return 0
+    idx_path = _remote_index_path()
+    try:
+        old = json.loads(idx_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        old = {}
+    if not force and time.time() - old.get("checked", 0) < REMOTE_EVERY:
+        return 0
+    repo, fetched = _repo(), 0
+    try:
+        tree = cache.http_get(GITHUB_TREE.format(repo=repo, ref="main"), timeout=20).json()
+        files = {t["path"][len(GITHUB_DIR):]: t["sha"] for t in tree.get("tree") or []
+                 if t.get("type") == "blob" and t.get("path", "").startswith(GITHUB_DIR)
+                 and t["path"].endswith(".yaml") and "/" not in t["path"][len(GITHUB_DIR):]}
+        for name, sha in files.items():
+            dest = cache.cache_dir() / f"catalog-gh-{sha}.yaml"
+            if dest.exists() or not PACKAGE_RE.match(name.removesuffix(".yaml")):
+                continue
+            text = cache.http_get(GITHUB_RAW.format(repo=repo, ref="main", path=GITHUB_DIR + name), timeout=20).text
+            cache.write_atomic(dest, text)
+            fetched += 1
+        for f in cache.cache_dir().glob("catalog-gh-*.yaml"):  # files gone from main (or old versions)
+            if f.name.removeprefix("catalog-gh-").removesuffix(".yaml") not in files.values():
+                f.unlink(missing_ok=True)
+        cache.write_atomic(idx_path, json.dumps({"checked": time.time(), "files": files}))
+    except Exception:  # noqa: BLE001 - offline / rate limited: keep what we have, try again next time
+        return 0
+    if fetched or files != old.get("files"):
+        load(refresh=True)
+    if not old.get("files"):  # the first download (a new install): nothing was "updated"
+        return 0
+    return fetched
+
+
+def remote_status() -> dict:
+    """{checked: time or None, entries: n, skipped: {package: reason}} for Settings."""
+    import json
+
+    try:
+        idx = json.loads(_remote_index_path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        idx = {}
+    load()
+    return {"checked": idx.get("checked"), "entries": len(idx.get("files") or {}), "skipped": dict(_skipped)}
+
+
+_skipped: dict[str, str] = {}
+
+
+def _load_github() -> dict[str, CatalogEntry]:
+    """Cached entries from GitHub main (no network here)."""
+    import json
+
+    try:
+        files = json.loads(_remote_index_path().read_text(encoding="utf-8")).get("files") or {}
+    except (OSError, ValueError):
+        return {}
+    out = {}
+    for sha in files.values():
+        path = cache.cache_dir() / f"catalog-gh-{sha}.yaml"
+        try:
+            d = yaml.safe_load(path.read_text(encoding="utf-8"))
+        except (OSError, yaml.YAMLError):
+            continue
+        if not isinstance(d, dict) or not d.get("package"):
+            continue
+        reason = unusable_reason(d)
+        if reason:
+            _skipped[d["package"]] = reason
+            continue
+        try:
+            out[d["package"]] = CatalogEntry.from_dict(d, "remote")
+        except Exception:  # noqa: BLE001
+            continue
+    return out
+
+
 def _load_remote() -> dict[str, CatalogEntry]:
    base = os.environ.get("FRAMEPORT_CATALOG_URL")
    if not base:
-        return {}
+        return _load_github() if remote_enabled() else {}
    base = base.rstrip("/") + "/"
    index = cache.cached_json("catalog-index.json", base + "index.json", max_age=6 * 3600, fallback=[])
    out = {}
@@ -109,7 +246,12 @@ def _load_remote() -> dict[str, CatalogEntry]:
        text = cache.cached_text(f"catalog-{pkg}.yaml", f"{base}{pkg}.yaml", max_age=6 * 3600)
        if text:
            try:
-                out[pkg] = CatalogEntry.from_dict(yaml.safe_load(text), "remote")
+                d = yaml.safe_load(text)
+                reason = unusable_reason(d)
+                if reason:
+                    _skipped[pkg] = reason
+                    continue
+                out[pkg] = CatalogEntry.from_dict(d, "remote")
            except Exception:
                pass
    return out
@@ -122,7 +264,11 @@ def load(refresh: bool = False) -> dict[str, CatalogEntry]:
    global _cache
    if _cache is None or refresh:
        entries = _load_dir(catalog_dir() / "games", "bundled")
-        entries.update(_load_remote())
+        _skipped.clear()
+        for pkg, e in _load_remote().items():
+            # main is normally ahead of the bundled copy; a source checkout or dev build may be ahead of main
+            if pkg not in entries or _when(e) >= _when(entries[pkg]):
+                entries[pkg] = e
        for pkg, e in _load_dir(user_catalog_dir(), "user").items():
            if not _newer(entries.get(pkg), e):  # the user's own recipe, unless a maintained one was verified later
                entries[pkg] = e
@@ -130,6 +276,10 @@ def load(refresh: bool = False) -> dict[str, CatalogEntry]:
    return _cache


+def _when(e: CatalogEntry) -> str:
+    return max(str(e.updated or ""), str(e.verified.get("date") or ""))
+
+
 def _newer(maintained: CatalogEntry | None, user: CatalogEntry) -> bool:
    """True when the bundled/remote entry was verified after the user's (e.g. a fix for a config the user shared)."""
    if maintained is None:
@@ -33,6 +33,10 @@ 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) -> dict:
+        """Install a native arm64 Linux app (only the Frame runs them)."""
+        raise NotImplementedError(f"{self.label} can't install Linux apps")
+
    def collect_diag(self, package: str | None = None) -> dict:
        """Debug data from the target for a diagnostics bundle: {"host": {...}, "files": {name: text}, ...}."""
        return {}
@@ -63,6 +63,10 @@ class FrameLeptonTarget(Target):
                                  extra.get("exe_sha256"), extra.get("revive_version"), extra.get("art_lookup"))
        return installer.install_pcvr(self.connect().frame, plan, reporter)

+    def install_linux(self, package, title, root, exe, files, appimage, openxr, reporter):
+        plan = installer.LinuxPlan(package, title, Path(root), exe, files, appimage, openxr)
+        return installer.install_linux(self.connect().frame, plan, reporter)
+
    def proton_status(self, tool: str | None = None) -> dict:
        return self.connect().frame.agent("proton_status", tool=tool)

@@ -23,16 +23,35 @@ from ..frame.connection import NOT_IN_LIBRARY, AgentFailed
 from ..i18n import fmt_size, tr, tr_n
 from ..recommend import catalog
 from . import components as C
+from . import jobs as jobs_module
 from . import theme as T
 from .components import install_state  # noqa: F401  (re-exported: tests and older callers import it from here)
-from .jobs import Job, JobManager
+from .jobs import Job

 NAV = [("library", tr("Library"), ft.Icons.GRID_VIEW_ROUNDED),
       ("frame", tr("Steam Frame"), ft.Icons.VIEW_IN_AR_ROUNDED),
-       ("files", tr("Files"), ft.Icons.FOLDER_OPEN_ROUNDED), ("settings", tr("Settings"), ft.Icons.TUNE_ROUNDED)]
+       ("files", tr("Files"), ft.Icons.FOLDER_OPEN_ROUNDED),
+       ("screenshots", tr("Screenshots"), ft.Icons.PHOTO_LIBRARY_OUTLINED),
+       ("settings", tr("Settings"), ft.Icons.TUNE_ROUNDED)]
 POLL_SECONDS = 30


+
+def window_geometry(saved: dict | None, scale: float) -> dict:
+    """Window properties for the start from the saved `ui.window` setting: the size (first start: 16:10 sized for the
+    UI scale), the position when it is plausible (a window left on a monitor that is gone would open off screen; far
+    off values are ignored, the system then places it) and maximized."""
+    saved = saved or {}
+    w, h = saved.get("size") or (round(1280 * scale), round(780 * scale))
+    out = {"width": max(int(w), 1000), "height": max(int(h), 680)}
+    pos = saved.get("pos")
+    if isinstance(pos, (list, tuple)) and len(pos) == 2 and all(isinstance(v, (int, float)) for v in pos) \
+            and -16000 < pos[0] < 16000 and -8 <= pos[1] < 9000:
+        out["left"], out["top"] = int(pos[0]), int(pos[1])
+    if saved.get("maximized"):
+        out["maximized"] = True
+    return out
+
 class FramePortApp:
    def __init__(self, page: ft.Page):
        from .views.activity import ActivityPanel
@@ -50,9 +69,13 @@ class FramePortApp:
        self._pc_cache: tuple[float, dict] | None = None
        self.library_view = None  # created once (views/library.LibraryView), re-mounted on every visit
        self.files_view = None  # likewise (views/files.FilesView): keeps the location/folder between visits
+        self.screenshots_view = None  # likewise (views/screenshots.ScreenshotsView): keeps the game filter
        self.exe_queue: list[str] = []  # games whose executable the user should confirm (after a scan)
        self._failures: list[Job] = []  # failed installs/tests, shown together when the queue is done
-        self.jobs = JobManager(self._on_job)
+        self.jobs = jobs_module.shared()  # one queue per process, shared by every window session
+        self.jobs.subscribe(self._on_job)
+        self._handled_jobs: set[int] = set()  # finished jobs this session has reacted to (pop-ups, refreshes)
+        page.on_close = lambda e: self.jobs.unsubscribe(self._on_job)  # session gone: stop drawing into it
        from .updater import Updater

        self.updater = Updater(self)  # new FramePort releases (sidebar card, Library bar, one-click update)
@@ -63,9 +86,10 @@ class FramePortApp:
        page.window.min_width, page.window.min_height = 1000, 680
        if not page.web:
            # 16:10 sized for the UI scale (the first start used to open too narrow at 125 %: toolbars were cut off);
-            # later starts reopen at the size the window was left at
-            w, h = (library.setting("ui.window") or {}).get("size") or (round(1280 * T.SCALE), round(780 * T.SCALE))
-            page.window.width, page.window.height = max(int(w), 1000), max(int(h), 680)
+            # later starts reopen where the window was left: size, position (GitHub #32: always top left on Windows),
+            # maximized
+            for key, value in window_geometry(library.setting("ui.window"), T.SCALE).items():
+                setattr(page.window, key, value)
            page.window.on_event = self._on_window_event
        page.on_keyboard_event = self._on_key
        if page.web:  # the library's right-click menu; otherwise the browser shows its own
@@ -76,6 +100,7 @@ class FramePortApp:
        self.body = ft.Container(expand=True, padding=ft.Padding(T.S6, T.S5, T.S5, 0))
        self.nav_col = ft.Column(spacing=T.px(2))
        self.conn_card = ft.Container()
+        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)
        sidebar = ft.Container(ft.Column([
@@ -89,6 +114,7 @@ class FramePortApp:
            ft.Container(expand=True),
            self.updater.card,
            self.activity_card,
+            self.power_row,
            self.conn_card,
        ], spacing=T.S2), width=T.px(236), bgcolor=T.SIDEBAR, padding=T.S4,
            border=ft.Border(right=ft.BorderSide(1, T.BORDER)))
@@ -101,15 +127,29 @@ class FramePortApp:
        threading.Thread(target=self._poll, daemon=True).start()
        threading.Thread(target=self._backfill_covers, daemon=True).start()
        self.updater.start()
+        self.run_bg(self._refresh_catalog)  # confirmed game configs from GitHub main (no release needed)

    # ================================================================== shell
    def _on_window_event(self, e) -> None:
-        """Remember the window size (once a resize ends; not while maximized or full screen)."""
-        win = self.page.window
-        if e.type == ft.WindowEventType.RESIZED and not (win.maximized or win.full_screen) and win.width and \
-                win.height:
-            size = [round(win.width), round(win.height)]
-            self.page.run_thread(library.update_setting, "ui.window", lambda v: {**(v or {}), "size": size}, {})
+        """Remember the window's size and position (once a resize/move ends; not while maximized or full screen) and
+        whether it is maximized."""
+        win, change = self.page.window, None
+        if e.type in (ft.WindowEventType.MAXIMIZE, ft.WindowEventType.UNMAXIMIZE):
+            change = {"maximized": e.type == ft.WindowEventType.MAXIMIZE}
+        elif win.maximized or win.full_screen:
+            return
+        elif e.type == ft.WindowEventType.RESIZED and win.width and win.height:
+            change = {"size": [round(win.width), round(win.height)]}
+            if win.left is not None and win.top is not None:  # resizing from the left/top edge moves it too
+                change["pos"] = [round(win.left), round(win.top)]
+        elif e.type in (ft.WindowEventType.MOVED, ft.WindowEventType.CLOSE) and win.left is not None and \
+                win.top is not None:
+            change = {"pos": [round(win.left), round(win.top)]}
+            if e.type == ft.WindowEventType.CLOSE:  # the app is going away: write it now
+                library.update_setting("ui.window", lambda v: {**(v or {}), **change}, {})
+                return
+        if change:
+            self.page.run_thread(library.update_setting, "ui.window", lambda v: {**(v or {}), **change}, {})

    def top_bar(self, heading: str, subtitle: str = "", actions: list[ft.Control] | None = None) -> ft.Control:
        heads = [C.title(heading), C.body(subtitle)] if subtitle else [C.title(heading)]
@@ -179,6 +219,24 @@ class FramePortApp:
                       self._conn_line, self._conn_extra], spacing=1, expand=True),
        ], spacing=T.S3), padding=T.S3, border_radius=T.RADIUS_SM, bgcolor=T.SURFACE, ink=True,
            border=ft.Border.all(1, T.BORDER), on_click=lambda e: self.go("frame"))
+        # the Frame's power: three equal buttons in one bar styled like the cards around it (icon over a label)
+        def power_button(action: str, label: str, icon, tip: str) -> ft.Control:
+            return ft.Container(
+                ft.Column([ft.Icon(icon, size=T.px(17), color=T.TEXT_2),
+                           ft.Text(label, size=T.T_META, color=T.TEXT_2, max_lines=1, no_wrap=True)],
+                          spacing=T.px(2), tight=True, horizontal_alignment=ft.CrossAxisAlignment.CENTER),
+                expand=True, alignment=ft.Alignment.CENTER, padding=ft.Padding(0, T.px(7), 0, T.px(6)),
+                border_radius=T.RADIUS_SM, ink=True, tooltip=C.tip(tip),
+                on_click=lambda e: self.frame_power(action))
+        divider = ft.Container(width=1, height=T.px(26), bgcolor=T.BORDER)
+        self.power_row.content = ft.Container(ft.Row([
+            power_button("sleep", tr("Sleep"), ft.Icons.BEDTIME_OUTLINED, tr("Put the Frame to sleep")),
+            divider,
+            power_button("restart", tr("Restart"), ft.Icons.RESTART_ALT_ROUNDED, tr("Restart the Frame")),
+            ft.Container(width=1, height=T.px(26), bgcolor=T.BORDER),
+            power_button("shutdown", tr("Shut down"), ft.Icons.POWER_SETTINGS_NEW_ROUNDED, tr("Turn the Frame off")),
+        ], spacing=0, vertical_alignment=ft.CrossAxisAlignment.CENTER),
+            bgcolor=T.SURFACE, border=ft.Border.all(1, T.BORDER), border_radius=T.RADIUS_SM, padding=T.px(2))
        self._nav = nav  # last: _refresh_sidebar (also called from job threads) treats it as "all built"

    def _refresh_sidebar(self, update: bool = True) -> None:
@@ -226,6 +284,7 @@ class FramePortApp:
        bat = (self.frame_info or {}).get("battery") if st == "connected" else None
        self._conn_bat.visible = bool(bat)
        self._conn_type.visible = st == "connected"
+        self.power_row.visible = st == "connected"
        if bat:
            from .battery import charging, icon, low

@@ -245,7 +304,7 @@ class FramePortApp:
        else:
            self._conn_extra.visible = False
        if update:
-            C.update(self.nav_col, self.activity_card, self.conn_card)
+            C.update(self.nav_col, self.activity_card, self.power_row, self.conn_card)

    def _saved_name(self) -> str | None:
        from ..frame.connection import saved_targets
@@ -284,6 +343,12 @@ class FramePortApp:
                if self.files_view is None:
                    self.files_view = FilesView(self)
                view = self.files_view.mount(*self.route[1:])
+            elif kind == "screenshots":
+                from .views.screenshots import ScreenshotsView
+
+                if self.screenshots_view is None:
+                    self.screenshots_view = ScreenshotsView(self)
+                view = self.screenshots_view.mount(*self.route[1:])
            elif kind == "settings":
                view = SettingsView(self).build()
            else:
@@ -310,6 +375,9 @@ class FramePortApp:
        elif self.route[0] == "files" and (self.files_view is None or self.files_view.root is None
                                           or self.frame_state != "connected"):
            self.render()  # connected / disconnected: switch between the browser and "connect first"
+        elif self.route[0] == "screenshots" and (self.screenshots_view is None or self.screenshots_view.root is None
+                                                 or self.frame_state != "connected"):
+            self.render()
        else:
            self._refresh_sidebar()

@@ -366,8 +434,8 @@ class FramePortApp:
        self._refresh_sidebar()
        self.activity.refresh()
        self._keep_frame_awake()
-        if job and job.state in ("done", "failed", "cancelled") and job.finished and not getattr(job, "_handled", 0):
-            job._handled = 1
+        if job and job.state in ("done", "failed", "cancelled") and job.finished and id(job) not in self._handled_jobs:
+            self._handled_jobs.add(id(job))
            if job.kind == "app-update" and job.state != "done":
                self.updater.restart = None  # the update didn't get ready: don't quit
            self.updater.on_jobs_changed()  # an update waiting for the queue to empty installs now
@@ -442,7 +510,9 @@ class FramePortApp:
                                       lambda e: self.share_config_dialog(job.package)))
        if summary and summary.get("suggestions") and job.package:
            sugg = summary["suggestions"]
-            out.append(C.primary(tr("Apply the suggested patches and reinstall"), ft.Icons.HEALING_ROUNDED,
+            label = (tr("Try Proton Experimental and reinstall") if sugg == [pipeline.PROTON_TOOL]
+                     else tr("Apply the suggested patches and reinstall"))
+            out.append(C.primary(label, ft.Icons.HEALING_ROUNDED,
                                 lambda e: (pipeline.apply_suggestions(job.package, sugg),
                                            self.install(job.package, getattr(job, "to", "frame")))))
        if job.package and job.state != "running" and library.game(job.package):
@@ -518,7 +588,24 @@ class FramePortApp:
                self._add_then_play(pkg, title)  # e.g. the shortcut step failed during the install
                return
            library.upsert_game(pkg, last_played=time.time())
-            if to == "frame":
+            steam = res.get("steam") or {}
+            if to == "frame" and steam:  # what the Frame's Steam logged about this launch (GitHub #21/#30)
+                if res.get("first_try"):
+                    applog.log.info("Play %s: Steam refused the library entry %s; devkit entry: %s", pkg,
+                                    res["first_try"].get("lines"), res.get("gameid"))
+                applog.log.info("Play %s (%s): Steam %s %s", pkg, res.get("via"), steam.get("result"),
+                                steam.get("lines"))
+            if to == "frame" and res.get("fallback_error"):
+                applog.log.info("Play %s: devkit entry failed: %s", pkg, res["fallback_error"])
+            if to == "frame" and res.get("first_try") and steam.get("result") != "error":
+                # Steam ignored FramePort's library entry: the game was added the way Valve's devkit tool does it
+                self.toast(tr("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.").format(title=title))
+            elif to == "frame" and steam.get("result") == "error":  # 9 = "Game configuration unavailable"
+                self.toast(tr("The Frame's Steam couldn't start {title} (Steam error {code}). Please send a problem "
+                              "report so we can see why.").format(title=title, code=steam.get("code")), error=True,
+                           action=tr("Report a problem"), on_action=lambda e: self.report_problem_dialog(pkg))
+            elif to == "frame":
                self.toast(tr("Starting {title} on the Frame — put the headset on").format(title=title))
            elif res.get("steamvr") is False:
                msg = tr("Starting {title}, but SteamVR isn't running — it may open as a flat window. "
@@ -580,6 +667,7 @@ class FramePortApp:
        if not g:
            return []
        rift = g.get("kind") == "rift"
+        linux = g.get("kind") == "linux"  # installed as it is: nothing to analyze, convert or share as a recipe
        job = self.jobs.busy_with(pkg)
        out: list[tuple | None] = []
        if quick:
@@ -601,12 +689,12 @@ class FramePortApp:
                                lambda e: self.test_game(pkg, "pc")))
                if self.has_game_settings(g):
                    out.append((tr("Game settings…"), ft.Icons.TUNE_ROUNDED, lambda e: self.settings_dialog(pkg)))
-                if on_frame and not rift:
+                if on_frame and not rift and not linux:
                    out.append((tr("Add videos and files…"), ft.Icons.VIDEO_LIBRARY_OUTLINED,
                                lambda e: self.go("files", pkg)))
                if on_frame:
                    out.append((tr("Type on Frame…"), ft.Icons.KEYBOARD_ROUNDED, lambda e: self.type_on_frame()))
-                if not rift:
+                if not rift and not linux:
                    out.append((tr("Analyze again"), ft.Icons.MANAGE_SEARCH_ROUNDED, lambda e: self.reanalyze(pkg)))
                if on_frame:
                    out.append((tr("Uninstall from Frame"), ft.Icons.DELETE_OUTLINE_ROUNDED,
@@ -621,25 +709,38 @@ class FramePortApp:
                            lambda e: (lv.selected.add(pkg), lv.set_select_mode(True))))
        if rift:
            out.append((tr("Change executable…"), ft.Icons.TERMINAL_ROUNDED, lambda e: self.choose_exe(pkg)))
+        if linux and self.linux_programs(g):
+            out.append((tr("Change program…"), ft.Icons.TERMINAL_ROUNDED, lambda e: self.choose_exe(pkg)))
+        if self.frame_state == "connected":
+            out.append((tr("Screenshots"), ft.Icons.PHOTO_LIBRARY_OUTLINED, lambda e: self.go("screenshots", pkg)))
        out.append((tr("Find artwork…"), ft.Icons.IMAGE_SEARCH_ROUNDED, lambda e: self.find_artwork(pkg)))
+        out.append((tr("Use your own artwork…"), ft.Icons.UPLOAD_FILE_ROUNDED, lambda e: self.custom_artwork(pkg)))
        if not job and self.frame_state == "connected" and \
                C.install_state(g, self.frame_info) in ("installed", "outdated"):
            out.append((tr("Update Steam art on Frame"), ft.Icons.WALLPAPER_ROUNDED,
                        lambda e: self.update_steam_art(pkg)))
        out.append((tr("Refresh store details"), ft.Icons.SYNC_ROUNDED, lambda e: self.refresh_details(pkg)))
-        if not job:
+        if not job and not linux:
            out.append((tr("Rebuild only (no install)") if not rift else tr("Check game files"), ft.Icons.BUILD_ROUNDED,
                        lambda e: self.build_game(pkg)))
-        out += [(tr("Reset to suggested recipe"), ft.Icons.RESTART_ALT_ROUNDED,
-                 lambda e: (pipeline.reset_recipe(pkg), self.toast(tr("Recipe reset")), self.refresh_view())),
-                (tr("Save as known-good recipe"), ft.Icons.VERIFIED_ROUNDED, lambda e: self.save_known_good(pkg)),
-                (tr("Share working config…"), ft.Icons.SHARE_ROUNDED, lambda e: self.share_config_dialog(pkg)),
-                (tr("Collect logs"), ft.Icons.FOLDER_ZIP_OUTLINED, lambda e: self.collect_logs(pkg)),
+        if not linux:
+            out += [(tr("Reset to suggested recipe"), ft.Icons.RESTART_ALT_ROUNDED,
+                     lambda e: (pipeline.reset_recipe(pkg), self.toast(tr("Recipe reset")), self.refresh_view())),
+                    (tr("Save as known-good recipe"), ft.Icons.VERIFIED_ROUNDED, lambda e: self.save_known_good(pkg)),
+                    (tr("Share working config…"), ft.Icons.SHARE_ROUNDED, lambda e: self.share_config_dialog(pkg))]
+        out += [(tr("Collect logs"), ft.Icons.FOLDER_ZIP_OUTLINED, lambda e: self.collect_logs(pkg)),
                (tr("Report a problem…"), ft.Icons.BUG_REPORT_OUTLINED, lambda e: self.report_problem_dialog(pkg)),
                None,
                (tr("Remove from library"), ft.Icons.DELETE_OUTLINE_ROUNDED, lambda e: self.remove_from_library(pkg))]
        return out

+    @staticmethod
+    def linux_programs(g: dict) -> list[str]:
+        """The other arm64 programs a Linux app could start with (empty for a lone AppImage/program)."""
+        extra = (g.get("analysis") or {}).get("extra") or {}
+        cands = [] if extra.get("files") else list(extra.get("candidates") or [])
+        return cands if len(cands) > 1 else []
+
    def install(self, pkg: str, to: str = "frame", confirmed: bool = False) -> Job | None:
        if confirmed:
            return self._submit_install(pkg, to)
@@ -1215,8 +1316,8 @@ class FramePortApp:
        """Quest games built with FramePort's adapter have game settings; PC VR games and 2D Android apps don't."""
        if not g:
            return True  # installed on the Frame but not in this library: a Quest game
-        if g.get("kind") == "rift" or not g.get("analysis"):
-            return g.get("kind") != "rift"
+        if g.get("kind") in ("rift", "linux") or not g.get("analysis"):
+            return g.get("kind") not in ("rift", "linux")
        return library.analysis_from_dict(g["analysis"]).vr_kind != "none"

    def settings_dialog(self, package: str) -> None:
@@ -1242,6 +1343,50 @@ class FramePortApp:
            if f.path:
                self.scan(f.path)

+    async def pick_linux_app(self, e=None):
+        """An AppImage or an archive (.zip/.tar.*) with an arm64 Linux app. Any file can be picked: AppImages often
+        have no extension."""
+        from ..analysis import linux
+
+        files = await ft.FilePicker().pick_files(dialog_title=tr("A Linux app for arm64 (AppImage, .zip or .tar.gz)"),
+                                                 allow_multiple=True)
+        for f in files or []:
+            if not f.path:
+                continue
+            if linux.looks_like_linux_app(Path(f.path)):
+                self.add_linux(f.path)
+            else:
+                self.toast(tr("{name} isn't a Linux app (an AppImage, a Linux program or a .zip/.tar archive)")
+                           .format(name=Path(f.path).name), error=True)
+
+    async def pick_linux_folder(self, e=None):
+        path = await ft.FilePicker().get_directory_path(dialog_title=tr("Folder with a Linux app for arm64"))
+        if path:
+            self.add_linux(path)
+
+    def add_linux(self, path: str) -> Job:
+        """Add a native arm64 Linux app (GitHub #31) in the background, then open its page."""
+        name = Path(path).name
+
+        def run(job: Job):
+            job.reporter.stage("Looking at the app")
+            g = pipeline.add_linux_app(path, job.reporter)  # ValueError (e.g. an x86_64 build): the job fails with it
+            pkg = g["package"]
+            try:
+                from ..artwork import thumbs
+
+                thumbs.prewarm(pkg)  # the card's thumbnail of the placeholder cover
+            except Exception:  # noqa: BLE001 - artwork is optional
+                pass
+            library.set_setting("ui.welcome_done", True)
+            self.open_game(pkg)
+            extra = (g.get("analysis") or {}).get("extra") or {}
+            if len(extra.get("candidates") or []) > 1 and not extra.get("files"):  # (the page has "Change…")
+                return tr("Added {title}: it starts with {exe}. Not the right program? Change it on its page.").format(
+                    title=g.get("title"), exe=g.get("exe", "").rsplit("/", 1)[-1])
+            return tr("Added {title}").format(title=g.get("title"))
+        return self.submit(tr("Add {name}").format(name=name), run, None, "task")
+
    def scan_roots(self) -> list[str]:
        """Folders to rescan: the ones scanned before (remembered from now on), else the folders the library's games
        came from (one level up from each game folder)."""
@@ -1249,6 +1394,8 @@ class FramePortApp:
        if not roots:
            found = set()
            for g in library.load().get("games", {}).values():
+                if g.get("kind") == "linux":  # added one by one (its origin may be e.g. Downloads)
+                    continue
                origin = g.get("origin") or (str(Path(g["apk"]).parent) if g.get("apk") else None)
                if origin and Path(origin).parent.exists():
                    found.add(str(Path(origin).parent))
@@ -1318,6 +1465,50 @@ class FramePortApp:
            return tr("{title}: analyzed again").format(title=self._title(pkg))
        self.submit(tr("Analyze {title} again").format(title=self._title(pkg)), run, pkg, "task")

+    def _refresh_catalog(self, force: bool = False) -> int:
+        """New/changed confirmed configs from the repo's main branch; games following the catalog get them (their
+        page then offers Update on Frame). Quiet unless something changed or `force` (Settings → Check now)."""
+        from ..recommend import catalog
+
+        n = catalog.refresh_remote(force=force)
+        if n:
+            library.load()  # re-derives recipes whose catalog entry changed
+            self.refresh_view()
+            self.toast(tr_n("{n} game config was updated", "{n} game configs were updated", n))
+        elif force:
+            self.toast(tr("Game configs are up to date"))
+        return n
+
+    def frame_power(self, action: str, force: bool = False) -> None:
+        """Sleep / restart / shut down the Frame (agent `power`, run a few seconds later so the answer arrives)."""
+        heading = {"sleep": tr("Put the Frame to sleep?"), "restart": tr("Restart the Frame?"),
+                   "shutdown": tr("Shut down the Frame?")}[action]
+        text = {"sleep": tr("The Frame goes to sleep in a few seconds. Wake it with its power button."),
+                "restart": tr("The Frame restarts in a few seconds; FramePort reconnects when it's back."),
+                "shutdown": tr("The Frame turns off in a few seconds. Turn it on again with its power button.")}[action]
+        if force:
+            heading, text = tr("A game is running on the Frame"), tr("It will be closed without saving. Continue?")
+        label = {"sleep": tr("Sleep"), "restart": tr("Restart"), "shutdown": tr("Shut down")}[action]
+
+        def go():
+            def work():
+                target = self.target
+                if not target:
+                    self.toast(tr("The Frame isn't connected"), error=True)
+                    return
+                try:
+                    target.frame.agent("power", action=action, force=force, timeout=30)
+                except AgentFailed as exc:
+                    if "game is running" in str(exc) and not force:
+                        self.page.run_thread(lambda: self.frame_power(action, force=True))
+                        return
+                    raise
+                done = {"sleep": tr("The Frame goes to sleep now."), "restart": tr("The Frame is restarting."),
+                        "shutdown": tr("The Frame is shutting down.")}[action]
+                self.toast(done)
+            self.run_bg(work)
+        C.confirm(self.page, heading, text, label, go, danger=action != "sleep" or force)
+
    def type_on_frame(self) -> None:
        from .views.type_dialog import show_type_dialog

@@ -1342,6 +1533,11 @@ class FramePortApp:

        show_art_dialog(self, pkg)

+    def custom_artwork(self, pkg: str) -> None:
+        from .views.art_dialog import show_custom_art_dialog
+
+        show_custom_art_dialog(self, pkg)
+
    # ================================================================== Frame
    def _startup(self):
        from ..frame.connection import parse_target, saved_targets
@@ -1567,6 +1763,8 @@ class FramePortApp:
                self.frame_info = None
                # reachable, but it doesn't let FramePort in: the Frame page points at the first-time setup
                self._not_paired = isinstance(exc, FrameNotPaired)
+                if not isinstance(exc, (FrameNotPaired, OSError)):  # unexpected: keep the traceback for reports
+                    applog.log.exception("connect to %s failed", target.label)
                if not quiet:
                    self.toast(tr("Couldn't connect: {exc}").format(exc=explain(exc)), error=True)
            if self.route[0] in ("frame", "library", "game", "welcome"):
@@ -49,6 +49,9 @@ def platform(g: dict) -> tuple[str, str, str]:
            return tr("Windows"), tr("Windows game (Proton)"), "platform_windows"
        oculus = extra.get("needs_revive") or extra.get("libovr")
        return tr("PC VR"), tr("PC VR · Oculus") if oculus else tr("PC VR"), "platform_pcvr"
+    if g.get("kind") == "linux":
+        vr = (((g.get("analysis") or {}).get("extra") or {}).get("openxr"))
+        return tr("Linux"), tr("Linux VR app · OpenXR") if vr else tr("Linux app (arm64)"), "platform_linux"
    kind = (((g.get("analysis") or {}).get("extra") or {}).get("vr_kind")) or "quest"
    if kind == "quest":
        return tr("Quest"), tr("Meta Quest"), "platform_quest"
@@ -58,6 +61,26 @@ def platform(g: dict) -> tuple[str, str, str]:
                          "android_xr": "Android XR"}.get(kind, "Android VR"), "platform_android_vr"


+def platform_icon(g: dict) -> str:
+    """The icon for a game's platform (card badge, artwork placeholder)."""
+    return ft.Icons.COMPUTER_ROUNDED if g.get("kind") == "rift" else \
+        ft.Icons.TERMINAL_ROUNDED if g.get("kind") == "linux" else ft.Icons.VIEW_IN_AR_ROUNDED
+
+
+def missing_libraries(game: dict, frame_info: dict | None) -> list[str]:
+    """A Linux app's shared libraries that the Frame lacks (the app won't start): from the Frame's install record when
+    connected, else from the last install FramePort did. Empty when the connected Frame doesn't have the app."""
+    dep = _deployment(game, frame_info)
+    if frame_info is not None and dep is None:
+        return []
+    if dep is not None and "missing_libraries" in dep:
+        return list(dep.get("missing_libraries") or [])
+    installs = [i for i in (game.get("installs") or {}).values() if isinstance(i, dict) and
+                isinstance(i.get("result"), dict)]
+    last = max(installs, key=lambda i: i.get("time") or 0, default=None)
+    return list((last or {}).get("result", {}).get("missing_libraries") or [])
+
+
 def install_state(game: dict, frame_info: dict | None) -> str | None:
    """None when no Frame is connected; else 'installed', 'outdated' (the local build, or the patch settings, differ
    from what the Frame runs) or 'missing'."""
@@ -376,6 +399,56 @@ def menu_items(actions: list[tuple | None]) -> list[ft.PopupMenuItem]:
    return out


+def menu_targets(clicked, selected) -> list:
+    """What a right-click acts on: the whole selection when the clicked item is part of a selection of several (as in
+    a file manager), else just that item. `selected` keeps its order."""
+    selected = list(selected)
+    return selected if clicked in selected and len(selected) > 1 else [clicked]
+
+
+class DragSelect:
+    """Click-and-drag multi-select ("paint" selection) for a grid or list, without knowing where items are on screen.
+
+    The area's GestureDetector calls start() on pan start and end() on pan end; each item calls hover(key, inside)
+    from its hover (enter/exit) event, which Flutter also sends while the mouse button is held. A drag selects every
+    item it passes over, or deselects them when it started on a selected item. No Flet in here (tested directly)."""
+
+    def __init__(self, is_selected, set_selected, can_select=lambda key: True, on_start=None):
+        self.is_selected, self.set_selected, self.can_select = is_selected, set_selected, can_select
+        self.on_start = on_start
+        self.under = None      # the item the pointer is over
+        self.active = False
+        self.mode = True       # select (True) or deselect (False) during this drag
+        self.touched: set = set()
+
+    def hover(self, key, inside: bool) -> None:
+        if inside:
+            self.under = key
+            if self.active:
+                self._apply(key)
+        elif self.under == key:
+            self.under = None
+
+    def start(self, e=None) -> None:
+        if self.on_start:
+            self.on_start()
+        under = self.under if self.under is not None and self.can_select(self.under) else None
+        self.mode = not self.is_selected(under) if under is not None else True
+        self.active, self.touched = True, set()
+        if under is not None:
+            self._apply(under)
+
+    def end(self, e=None) -> None:
+        self.active = False
+
+    def _apply(self, key) -> None:
+        if key in self.touched or not self.can_select(key):
+            return
+        self.touched.add(key)
+        if self.is_selected(key) != self.mode:
+            self.set_selected(key, self.mode)
+
+
 def is_media_player(g: dict) -> bool:
    """A video player (360° layers in its recipe or analysis, e.g. 4XVR): its page offers "Add videos" up front."""
    patches = ((g.get("recipe") or {}).get("patches") or {})
@@ -36,6 +36,13 @@ HELP: dict[str, str] = _Translated({
                        "Android container.",
    "platform_android_vr": "A VR app made for another Android headset. OpenXR apps are translated like Quest games; "
                           "apps built on a headset maker's own SDK (Pico, HTC Wave) can't run on the Frame.",
+    "platform_linux": "A native Linux program built for arm64 (aarch64), like the Frame's own CPU. It's installed "
+                      "unchanged and runs directly on SteamOS (no Android container, no Proton), started from the "
+                      "Frame's Steam library. VR apps use the Frame's OpenXR runtime.",
+    "linux_app": "An AppImage, a folder or a .zip/.tar archive with a Linux program built for arm64 (aarch64). x86_64 "
+                 "builds can't run on the Frame. The app must bring the libraries SteamOS doesn't have.",
+    "appimage": "An AppImage is a Linux app packed into one file. FramePort unpacks it on the Frame once, so it starts "
+                "without FUSE.",
    "select": "Pick several games and install them in one go. FramePort asks every question first, then works through "
              "the queue in the background.",
    "tags": "Your own tags (filled) can be anything you like. Outlined tags are added automatically from the engine, "
@@ -100,6 +100,10 @@ class JobManager:
    def subscribe(self, fn: Callable[[Job | None], None]) -> None:
        self._listeners.append(fn)

+    def unsubscribe(self, fn: Callable[[Job | None], None]) -> None:
+        if fn in self._listeners:
+            self._listeners.remove(fn)
+
    def submit(self, job: Job) -> Job:
        job.reporter.subscribe(lambda ev, j=job: self._event(j, ev))
        with self._cv:
@@ -225,3 +229,18 @@ class JobManager:
            if self.save_logs:
                applog.save_job_log(job.kind, job.package, job.state, job.text())
            self._notify(job, force=True)
+
+
+_shared: JobManager | None = None
+_shared_lock = threading.Lock()
+
+
+def shared() -> JobManager:
+    """The process's one job queue. Flet builds a new app object for every window session (a reconnect after sleep
+    or a reload): with a queue per session, the old session's job kept running unseen and the same game could be
+    built twice at once in the same work folder (both builds then failed)."""
+    global _shared
+    with _shared_lock:
+        if _shared is None:
+            _shared = JobManager()
+        return _shared
@@ -124,6 +124,48 @@ class Updater:
                     C.ghost(tr("Release page"), ft.Icons.OPEN_IN_NEW_ROUNDED, lambda e: page.launch_url(up.page)),
                     C.primary(tr("Update now"), ft.Icons.SYSTEM_UPDATE_ROUNDED, go)]))

+    # ---------------------------------------------------------------- dev builds
+    def install_dev(self) -> None:
+        """Settings → "Install the latest dev build": the rolling `dev` pre-release the maintainer publishes for
+        testing a fix before a release (CI "Run workflow", dev build)."""
+        def work():
+            up = updates.check_dev()
+            if not up:
+                self.app.toast(tr("No dev build is published right now"), error=True)
+                return
+            if up.version == __version__:
+                self.app.toast(tr("You already have the latest dev build ({version})").format(version=up.version))
+                return
+            self.app.page.run_thread(lambda: self._confirm_dev(up))
+        self.app.run_bg(work)
+
+    def _confirm_dev(self, up: updates.Update) -> None:
+        page = self.app.page
+        notes = up.notes.strip() or tr("No notes.")
+
+        def go(e):
+            page.pop_dialog()
+            self.found = up
+            self.install()
+        page.show_dialog(ft.AlertDialog(
+            title=ft.Text(tr("Install dev build {version}?").format(version=up.version), color=T.TEXT,
+                          weight=ft.FontWeight.W_600),
+            bgcolor=T.SURFACE_2,
+            content=ft.Container(ft.Column([
+                C.callout(C.body(tr("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}).").format(version=__version__), T.TEXT), "warn"),
+                ft.Container(ft.Markdown(notes, selectable=True, extension_set=ft.MarkdownExtensionSet.GITHUB_WEB,
+                                         md_style_sheet=_notes_style(),
+                                         on_tap_link=lambda e: page.launch_url(e.data)),
+                             padding=T.S3, border_radius=T.RADIUS_SM, bgcolor=T.SURFACE,
+                             border=ft.Border.all(1, T.BORDER)),
+            ], spacing=T.S3, scroll=ft.ScrollMode.AUTO, tight=True, horizontal_alignment=ft.CrossAxisAlignment.STRETCH),
+                width=T.px(560), height=T.px(min(440, 190 + 26 * len(notes.splitlines())))),
+            actions=[C.ghost(tr("Cancel"), on_click=lambda e: page.pop_dialog()),
+                     C.ghost(tr("Build page"), ft.Icons.OPEN_IN_NEW_ROUNDED, lambda e: page.launch_url(up.page)),
+                     C.primary(tr("Install dev build"), ft.Icons.SCIENCE_OUTLINED, go)]))
+
    # ---------------------------------------------------------------- installing
    def install(self) -> None:
        up = self.found or updates.ready_update_info()
@@ -1,4 +1,5 @@
-"""'Find artwork' — search the Meta/Oculus store (via OculusDB) and Steam, pick a result, or fetch automatically."""
+"""'Find artwork' — search the Meta/Oculus store (via OculusDB) and Steam, pick a result, fetch automatically, or
+choose your own image files."""
 from __future__ import annotations

 from typing import TYPE_CHECKING
@@ -92,6 +93,99 @@ def show_art_dialog(app: FramePortApp, package: str) -> None:
            status, results,
        ], spacing=T.S3, tight=True), width=T.px(660)),
        bgcolor=T.SURFACE_2, shape=ft.RoundedRectangleBorder(radius=T.RADIUS),
-        actions=[C.ghost(tr("Find automatically"), ft.Icons.AUTO_AWESOME_ROUNDED, auto),
+        actions=[C.ghost(tr("Use your own images…"), ft.Icons.UPLOAD_FILE_ROUNDED,
+                         lambda e: (app.page.pop_dialog(), show_custom_art_dialog(app, package))),
+                 C.ghost(tr("Find automatically"), ft.Icons.AUTO_AWESOME_ROUNDED, auto),
                 C.ghost(tr("Close"), on_click=lambda e: app.page.pop_dialog())]))
    search()
+
+
+def custom_slots() -> tuple[tuple[str, str, str], ...]:
+    """(kind, label, the shape Steam shows it in) for each kind of artwork the user can replace."""
+    return (
+        ("portrait", tr("Cover"), tr("tall, 600 × 900")),
+        ("landscape", tr("Wide cover"), tr("920 × 430")),
+        ("hero", tr("Banner"), tr("wide, 1920 × 620")),
+        ("logo", tr("Logo"), tr("transparent PNG")),
+        ("icon", tr("Icon"), tr("square, 256 × 256")),
+    )
+
+
+def show_custom_art_dialog(app: FramePortApp, package: str) -> None:
+    """'Your own images': choose an image file for each kind of artwork (for games whose art can't be found
+    automatically). Missing shapes are composed from the others for Steam, as with store art."""
+    g = library.game(package)
+    grid = ft.Row(wrap=True, spacing=T.S3, run_spacing=T.S3)
+
+    def changed(message: str) -> None:
+        thumbs.prewarm(package)
+        installed = C.install_state(library.game(package), app.frame_info) in ("installed", "outdated")
+        library.upsert_game(package, art_source="custom", **({"steam_art_stale": True} if installed else {}))
+        render()
+        app.refresh_view()
+        if installed:
+            app.toast(tr("{message} The Frame's Steam library still shows the old art.").format(message=message),
+                      action=tr("Update on Frame"), on_action=lambda e: app.update_steam_art(package))
+        else:
+            app.toast(message)
+
+    async def choose(kind: str, label: str) -> None:
+        files = await ft.FilePicker().pick_files(dialog_title=tr("Image for the {label}").format(label=label),
+                                                 allowed_extensions=["png", "jpg", "jpeg", "webp"])
+        path = next((f.path for f in files or [] if f.path), None)
+        if not path:
+            return
+
+        def work():
+            try:
+                sources.apply_custom(package, kind, path)
+            except sources.ArtError as exc:
+                app.toast(str(exc), error=True)
+                return
+            changed(tr("{label} updated for {title}.").format(label=label, title=g.get("title")))
+        app.run_bg(work)
+
+    def remove(kind: str, label: str) -> None:
+        def work():
+            sources.remove_custom(package, kind)
+            changed(tr("{label} removed for {title}.").format(label=label, title=g.get("title")))
+        app.run_bg(work)
+
+    def slot(kind: str, label: str, shape: str) -> ft.Control:
+        art = thumbs.url(package, (kind,), 400)
+        if art and kind in ("logo", "icon"):  # shown whole (a logo is often very wide, an icon small)
+            box = ft.Container(ft.Image(src=art, fit=ft.BoxFit.CONTAIN), height=T.px(110), padding=T.S2,
+                               border_radius=T.px(8), bgcolor=T.SURFACE_3, alignment=ft.Alignment.CENTER)
+        else:
+            box = (C.art_fill(art, radius=T.px(8), height=T.px(110)) if art else
+                   ft.Container(C.meta(tr("None")), height=T.px(110), alignment=ft.Alignment.CENTER,
+                                border_radius=T.px(8), bgcolor=T.SURFACE_3))
+        buttons = [C.ghost(tr("Choose…"), ft.Icons.UPLOAD_FILE_ROUNDED,
+                           lambda e, k=kind, lb=label: app.page.run_task(choose, k, lb))]
+        if art:
+            buttons.append(ft.IconButton(ft.Icons.DELETE_OUTLINE_ROUNDED, icon_size=T.px(18), icon_color=T.TEXT_3,
+                                         tooltip=tr("Remove"), on_click=lambda e, k=kind, lb=label: remove(k, lb)))
+        return ft.Container(ft.Column([
+            box,
+            C.body(label, T.TEXT, size=T.T_META, weight=ft.FontWeight.W_600),
+            C.meta(shape),
+            ft.Row(buttons, spacing=0),
+        ], spacing=T.px(4), tight=True), width=T.px(190), padding=T.S2, border_radius=T.RADIUS_SM,
+            bgcolor=T.SURFACE)
+
+    def render() -> None:
+        grid.controls = [slot(*s) for s in custom_slots()]
+        C.update(grid)
+
+    grid.controls = [slot(*s) for s in custom_slots()]
+    app.page.show_dialog(ft.AlertDialog(
+        title=ft.Text(tr("Your own artwork for {title}").format(title=g.get("title")), weight=ft.FontWeight.W_600),
+        content=ft.Container(ft.Column([
+            C.body(tr("Choose PNG, JPEG or WebP images. Steam fills any missing shape from the ones you choose; "
+                      "FramePort never replaces your images automatically.")),
+            grid,
+        ], spacing=T.S3, tight=True), width=T.px(660)),
+        bgcolor=T.SURFACE_2, shape=ft.RoundedRectangleBorder(radius=T.RADIUS),
+        actions=[C.ghost(tr("Search the stores instead"), ft.Icons.IMAGE_SEARCH_ROUNDED,
+                         lambda e: (app.page.pop_dialog(), show_art_dialog(app, package))),
+                 C.ghost(tr("Close"), on_click=lambda e: app.page.pop_dialog())]))
@@ -2,6 +2,7 @@
 from __future__ import annotations

 from collections.abc import Callable
+from pathlib import Path
 from typing import TYPE_CHECKING

 import flet as ft
@@ -21,11 +22,24 @@ def _size(n: int) -> str:
    return fmt_size(n)


+def _file_size(path: Path) -> int:
+    try:
+        return path.stat().st_size
+    except OSError:
+        return 0
+
+
 def show_exe_dialog(app: FramePortApp, package: str, remaining: int = 0,
                    on_done: Callable[[], None] | None = None) -> None:
    g = library.game(package)
    extra = (g.get("analysis") or {}).get("extra") or {}
-    cands = extra.get("exe_candidates") or [{"path": g.get("exe"), "score": 0, "reasons": [], "size": 0}]
+    linux = g.get("kind") == "linux"
+    if linux:  # a Linux app: its arm64 programs, best guess first
+        root = Path(g.get("game_dir") or ".")
+        cands = [{"path": c, "score": 0, "reasons": [], "size": _file_size(root / c)}
+                 for c in extra.get("candidates") or [g.get("exe")]]
+    else:
+        cands = extra.get("exe_candidates") or [{"path": g.get("exe"), "score": 0, "reasons": [], "size": 0}]
    current = g.get("exe") or cands[0]["path"]
    group = ft.RadioGroup(value=current, content=ft.Column(spacing=T.S2))
    for i, c in enumerate(cands):
@@ -70,8 +84,10 @@ def show_exe_dialog(app: FramePortApp, package: str, remaining: int = 0,

    pick = C.one_choice()
    title = tr("Which program starts {get}?").format(get=g.get('title'))
-    lead = (tr("FramePort found more than one program that could start this game. Pick the one you'd double-click to "
-            "play it. Oculus builds usually work better with Revive than Steam builds."))
+    lead = (tr("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).") if linux else
+            tr("FramePort found more than one program that could start this game. Pick the one you'd double-click to "
+               "play it. Oculus builds usually work better with Revive than Steam builds."))
    app.page.show_dialog(ft.AlertDialog(
        title=ft.Row([ft.Text(title, weight=ft.FontWeight.W_600, expand=True)]
                     + ([C.meta(tr("{remaining} more after this").format(remaining=remaining))] if remaining else [])),
@@ -107,6 +107,15 @@ class FilesView:
                       C.meta("")], horizontal_alignment=ft.CrossAxisAlignment.CENTER, tight=True),
            left=0, right=0, top=0, bottom=0, alignment=ft.Alignment.CENTER, bgcolor=T.soft("#000000", 0.7),
            border_radius=T.RADIUS, border=ft.Border.all(2, T.ACCENT), visible=False)
+        # click and drag across rows to select them (C.DragSelect)
+        self.drag = C.DragSelect(lambda p: p in self.selected, self._toggle,
+                                 can_select=lambda p: any(x.path == p and self._selectable(x) for x in self.entries))
+        # one right-click menu for the listing: filled with the clicked entry's actions (or the folder's) when it opens
+        self.menu = ft.ContextMenu(content=ft.GestureDetector(
+            content=C.card(self.listing, padding=T.px(4), expand=True), expand=True,
+            on_secondary_tap_down=lambda e: self.open_menu(None, e.global_position),
+            on_pan_start=self.drag.start, on_pan_end=self.drag.end),
+            secondary_trigger=None, tertiary_trigger=None, expand=True)
        self.root = None

    # ---------------------------------------------------------------- building
@@ -130,9 +139,10 @@ class FilesView:
                        self.toolbar,
                        ft.Row([self.select_all, ft.Container(self.where, expand=True), self.hidden_switch],
                               vertical_alignment=ft.CrossAxisAlignment.CENTER),
+                        self._drop_area(ft.Stack([self.menu, self.drop_hint], expand=True)),
+                        # below the list (as in the Library): above it, its appearing pushed the rows down in the
+                        # middle of a drag-select
                        self.sel_bar,
-                        self._drop_area(ft.Stack([C.card(self.listing, padding=T.px(4), expand=True),
-                                                  self.drop_hint], expand=True)),
                        self.status,
                    ], spacing=T.S2, expand=True),
                ], spacing=T.S4, expand=True, vertical_alignment=ft.CrossAxisAlignment.STRETCH),
@@ -193,7 +203,7 @@ class FilesView:

        out = []
        for d in (self.app.frame_info or {}).get("installed", []):
-            if d.get("kind") == "pcvr":
+            if d.get("kind") in ("pcvr", "linux"):  # no Android storage
                continue
            g = library.game(d["package"]) or {}
            out.append((d["package"], g.get("title") or d.get("title") or d["package"]))
@@ -304,7 +314,7 @@ class FilesView:
        info = (("folder" if e.is_dir else human(e.size)) + (tr(" · link") if e.link else "")
                + (f" · {when}" if when else ""))
        actions = [C.icon_btn(ft.Icons.DOWNLOAD_ROUNDED, tr("Download to this PC"),
-                              lambda ev, x=e: self.download([x]))]
+                              lambda ev, x=e: self._download_later([x]))]
        if not self._protected(e):
            actions += [C.icon_btn(ft.Icons.DRIVE_FILE_RENAME_OUTLINE_ROUNDED, tr("Rename"),
                                   lambda ev, x=e: self.rename(x)),
@@ -313,14 +323,79 @@ class FilesView:
                            on_change=lambda ev, p=e.path: self._toggle(p, ev.control.value),
                            disabled=self._protected(e))
        self.checks[e.path] = check
-        return ft.Container(
+        row = ft.Container(
            ft.Row([check,
                    ft.Icon(file_icon(e.name, e.is_dir), size=T.px(20), color=T.ACCENT if e.is_dir else T.TEXT_2),
                    ft.Column([C.body(e.name, T.TEXT, weight=ft.FontWeight.W_500, max_lines=1,
                                      overflow=ft.TextOverflow.ELLIPSIS), C.meta(info)], spacing=0, expand=True),
                    *actions], spacing=T.S3),
            padding=ft.Padding(T.S3, T.px(6), T.S2, T.px(6)), border_radius=T.RADIUS_SM, ink=e.is_dir,
-            on_click=(lambda ev, p=e.path: self.cd(p)) if e.is_dir else None)
+            on_click=(lambda ev, p=e.path: self.cd(p)) if e.is_dir else None,
+            on_hover=lambda ev, p=e.path: self.drag.hover(p, ev.data in (True, "true")))
+        return ft.GestureDetector(content=row, on_secondary_tap_down=lambda ev, x=e: self.open_menu(x,
+                                                                                                    ev.global_position))
+
+    # ---------------------------------------------------------------- right-click menu
+    def menu_actions(self, e) -> list[tuple | None]:
+        """[(label, icon, handler) | None] for a right-click on entry `e` (None = on the folder's empty space). With
+        several entries selected and `e` among them, the actions act on the whole selection."""
+        if e is None:
+            return [(tr("Upload files…"), ft.Icons.UPLOAD_FILE_ROUNDED, self.upload_files),
+                    (tr("Upload folder…"), ft.Icons.DRIVE_FOLDER_UPLOAD_ROUNDED, self.upload_folder),
+                    (tr("New folder…"), ft.Icons.CREATE_NEW_FOLDER_OUTLINED, lambda ev: self.new_folder()),
+                    None,
+                    *([(tr("Select all"), ft.Icons.SELECT_ALL_ROUNDED, lambda ev: self._select_all())]
+                      if any(self._selectable(x) for x in self.entries) else []),
+                    (tr("Copy folder path"), ft.Icons.CONTENT_COPY_ROUNDED,
+                     lambda ev: self.app.copy(self._shown_path(self.path))),
+                    (tr("Refresh"), ft.Icons.REFRESH_ROUNDED, lambda ev: self.load())]
+        by_path = {x.path: x for x in self.entries}
+        items = [by_path[p] for p in C.menu_targets(e.path, [x.path for x in self.entries if x.path in self.selected])]
+        several = len(items) > 1
+        deletable = [x for x in items if not self._protected(x)]
+        out: list[tuple | None] = []
+        if not several and e.is_dir:
+            out.append((tr("Open"), ft.Icons.FOLDER_OPEN_ROUNDED, lambda ev: self.cd(e.path)))
+        out.append((tr("Download {n} items to this PC…").format(n=len(items)) if several
+                    else tr("Download to this PC…"), ft.Icons.DOWNLOAD_ROUNDED,
+                    lambda ev: self._download_later(items)))
+        if not several and not self._protected(e):
+            out.append((tr("Rename…"), ft.Icons.DRIVE_FILE_RENAME_OUTLINE_ROUNDED, lambda ev: self.rename(e)))
+        if not several:
+            out.append((tr("Copy path"), ft.Icons.CONTENT_COPY_ROUNDED, lambda ev: self.app.copy(self._shown_path(
+                e.path))))
+        out.append(None)
+        if several:
+            out.append((tr("Clear selection"), ft.Icons.CLOSE_ROUNDED, lambda ev: self._clear_selection()))
+        elif self._selectable(e):
+            on = e.path in self.selected
+            out.append((tr("Deselect") if on else tr("Select"),
+                        ft.Icons.CHECK_BOX_OUTLINE_BLANK_ROUNDED if on else ft.Icons.CHECK_BOX_OUTLINED,
+                        lambda ev: self._toggle(e.path, not on)))
+        if deletable:
+            out += [None, (tr("Delete {n} items…").format(n=len(deletable)) if len(deletable) > 1 else tr("Delete…"),
+                           ft.Icons.DELETE_OUTLINE_ROUNDED, lambda ev: self.delete(deletable))]
+        return out
+
+    def open_menu(self, e, position=None) -> None:
+        if not self.loc:
+            return
+        self.menu.items = C.menu_items(self.menu_actions(e))
+        C.update(self.menu)
+        self.app.page.run_task(self.menu.open, global_position=position)
+
+    def _shown_path(self, path: str) -> str:
+        """The path as games see it (/sdcard/…) where the location has one, else the Frame's own path."""
+        android = (self.loc or {}).get("android")
+        if not android:
+            return path
+        rel = posixpath.relpath(path, self.loc["path"])
+        return android if rel == "." else posixpath.join(android, rel)
+
+    def _download_later(self, items: list) -> None:
+        """Start the (async: it asks for a folder) download from a plain click handler: Flet only awaits handlers
+        that are coroutine functions themselves, not lambdas returning a coroutine."""
+        self.app.page.run_task(self.download, items)

    def cd(self, path: str) -> None:
        self.path = path
@@ -343,6 +418,10 @@ class FilesView:
        self.selected.clear()
        self._render_listing()

+    def _select_all(self) -> None:
+        self.selected = {x.path for x in self.entries if self._selectable(x)}
+        self._render_listing()
+
    def _selectable(self, e) -> bool:
        return not self._protected(e)

@@ -119,7 +119,7 @@ class FrameView:
            size = d.get("apk_size", 0)
            in_lib = pkg in games
            sub = (tr("PC VR · Proton") + (tr(" + Revive") if d.get("revive") else "")) if pcvr else \
-                (C.platform(games[pkg])[0] if in_lib else tr("Quest"))
+                (C.platform(games[pkg])[0] if in_lib else tr("Linux") if d.get("kind") == "linux" else tr("Quest"))
            sub += (tr(" · {value:.1f} GiB").format(value=size / 2**30) if size >= 2**30
                    else tr(" · {value:.0f} MiB").format(value=size / 2**20))
            title = display_title(games[pkg], tw) if in_lib else (d.get("title") or pkg)
@@ -181,7 +181,7 @@ class FrameView:

        pair_box = ft.Column(spacing=T.S3)

-        def pair(e):
+        def pair(e, host: str = ""):
            from ...frame.connection import FrameTarget
            from ...frame.pairing import PairingServer

@@ -190,7 +190,7 @@ class FrameView:

            def on_paired(info):
                app.connect(FrameTarget(info["host"], info["user"], 22, info["name"]))
-            server = app.pairing = PairingServer(on_paired=on_paired).start()
+            server = app.pairing = PairingServer(on_paired=on_paired, host=host).start()
            show_command()

            def check_network():
@@ -210,12 +210,92 @@ class FrameView:
                    show_command()
            app.run_bg(check_network)

+        def usb_explain(e):
+            """The Frame turns its USB network on only in Developer Mode: say how first (Valve's labels on the current
+            Frame OS: Settings → System → Enable Developer Mode), then watch for the cable."""
+            def close():  # this dialog itself: pop_dialog() closes the topmost overlay, which may be a toast
+                dlg.open = False
+                C.update(dlg)
+
+            def go(ev):
+                close()
+                usb_setup(ev)
+            steps = [
+                tr("On the Frame, open Steam's Settings (Steam button → Settings)."),
+                tr("Go to System and turn on \"Enable Developer Mode\". A Developer page appears in Settings; nothing "
+                   "else changes, your games and data stay as they are."),
+                tr("Connect the Frame's USB-C port to this computer with a USB cable (a data cable, not a charge-only "
+                   "one)."),
+            ]
+            dlg = ft.AlertDialog(
+                title=ft.Text(tr("Turn on Developer Mode first"), weight=ft.FontWeight.W_600),
+                content=ft.Container(ft.Column([
+                    C.body(tr("The Frame only offers its USB connection in Developer Mode:"), T.TEXT),
+                    *[ft.Row([ft.Container(ft.Text(str(i), weight=ft.FontWeight.W_700, color=T.ACCENT),
+                                           width=T.px(24), height=T.px(24), border_radius=T.px(12),
+                                           bgcolor=T.ACCENT_SOFT, alignment=ft.Alignment.CENTER),
+                              C.body(text, T.TEXT_2, expand=True)], spacing=T.S3,
+                             vertical_alignment=ft.CrossAxisAlignment.START)
+                      for i, text in enumerate(steps, 1)],
+                    C.meta(tr("FramePort then finds the Frame on the cable by itself.")),
+                ], spacing=T.S3, tight=True), width=T.px(480)),
+                bgcolor=T.SURFACE_2, shape=ft.RoundedRectangleBorder(radius=T.RADIUS),
+                actions=[C.ghost(tr("Cancel"), on_click=lambda ev: close()),
+                         C.primary(tr("Done: look for the cable"), ft.Icons.USB_ROUNDED, go)])
+            app.page.show_dialog(dlg)
+
+        def usb_setup(e):
+            """Setup over a USB-C cable: no Wi-Fi, router, discovery or network firewall involved (the Frame's USB
+            network gives this PC the fixed address 10.86.200.234). The Frame enables its USB network only in
+            Developer Mode, so that comes first."""
+            from ...frame import usb
+            from ...frame.connection import FrameTarget, server_key
+
+            status = ft.Row([ft.ProgressRing(width=T.px(14), height=T.px(14), stroke_width=T.px(2), color=T.ACCENT),
+                             C.meta(tr("Waiting for the cable…"))], spacing=T.S2)
+            pair_box.controls = [
+                C.body(tr("Looking for the Frame on a USB cable (Developer Mode on, USB-C port connected to this "
+                          "computer)."), T.TEXT),
+                status,
+            ]
+            C.update(pair_box)
+            token = object()
+            app._usb_setup = token
+
+            def watch():
+                for _ in range(600):  # up to 20 minutes
+                    if app._usb_setup is not token or app.route[0] != "frame":
+                        return
+                    if usb.PC_USB_IP in usb.pc_usb_addresses(usb.FRAME_USB_IP) and server_key(usb.FRAME_USB_IP,
+                                                                                                timeout=3):
+                        break
+                    time.sleep(2)
+                else:
+                    return
+                status.controls = [ft.Icon(ft.Icons.USB_ROUNDED, size=T.px(16), color=T.OK),
+                                   C.meta(tr("Cable connected."), T.OK)]
+                C.update(status)
+                target = FrameTarget(usb.FRAME_USB_IP, "steamos", 22)
+                try:  # already set up for FramePort: just connect over the cable
+                    from ...frame.connection import Frame
+
+                    Frame(target, None).connect(timeout=10).close()
+                    app.connect(target)
+                    return
+                except Exception:  # noqa: BLE001 - not set up yet: show the setup command for the cable
+                    pass
+                app.page.run_thread(lambda: pair(None, host=usb.PC_USB_IP))
+            app.run_bg(watch)
+
        def show_command(update=True):
            """The setup command of the running pairing server: also when the page is redrawn (connection checks,
            discovery), which used to close it."""
            line = app.pairing.one_liner
+            over_usb = bool(getattr(app.pairing, "host", ""))
            pair_box.controls = [
                C.body(tr("On the Frame: SteamVR dashboard → Launch a program → Desktop, then app menu → System → "
+                          "Konsole, and run (it reaches this computer over the USB cable):") if over_usb else
+                       tr("On the Frame: SteamVR dashboard → Launch a program → Desktop, then app menu → System → "
                          "Konsole, and run:"), T.TEXT),
                ft.Container(ft.Row([ft.Text(line, font_family="monospace", selectable=True, size=T.px(12),
                                             color=T.TEXT, expand=True),
@@ -240,7 +320,7 @@ class FrameView:
                              "there and approve FramePort. That way needs no connection into this computer.")),
                ], spacing=T.S2), "warn"))
            if update:
-                pair_box.update()
+                C.update(pair_box)  # (a redraw of the page may have replaced it)

        if app.pairing and app.pairing.running:
            show_command(update=False)
@@ -288,7 +368,13 @@ class FrameView:
            *([offline] if offline else []),
            step(1, tr("First-time setup"), tr("New Frame? Run one command on it and FramePort does the rest. Did this "
                                               "once already? Your Frame appears under step 2."),
-                 C.primary(tr("Show setup command"), ft.Icons.TERMINAL_ROUNDED, pair), pair_box,
+                 ft.Row([C.primary(tr("Show setup command"), ft.Icons.TERMINAL_ROUNDED, pair),
+                         C.meta(tr("OR"), weight=ft.FontWeight.W_600),
+                         C.secondary(tr("Set up with a USB cable"), ft.Icons.USB_ROUNDED, usb_explain,
+                                     tooltip=tr("No Wi-Fi needed: for networks that block the setup, and faster "
+                                                "game uploads"))], wrap=True, spacing=T.S3,
+                        vertical_alignment=ft.CrossAxisAlignment.CENTER),
+                 pair_box,
                 help="first_time_setup"),
            step(2, tr("Already set up: on your network"), tr("Frames in Developer Mode show up here."), found,
                 help="developer_mode"),
@@ -49,7 +49,7 @@ def should_ask_to_share(g: dict, installed: bool) -> bool:
    """Invite the user to share a recipe the built-in catalog doesn't have yet: an untested Quest/Android game that
    they have installed, launch-tested or played, and haven't shared (or dismissed) already."""
    r = g.get("recipe") or {}
-    if g.get("kind") == "rift" or r.get("status", "unknown") != "unknown" or \
+    if g.get("kind") in ("rift", "linux") or r.get("status", "unknown") != "unknown" or \
            str(r.get("source", "")).startswith("catalog") or g.get("shared_config") or g.get("share_dismissed"):
        return False
    return installed or (g.get("last_test") or {}).get("verdict") == "pass" or bool(g.get("last_played"))
@@ -72,6 +72,7 @@ class GameView:
        self.games = library.games()
        self.twins = twins(self.games)
        self.rift = bool(self.g) and self.g.get("kind") == "rift"
+        self.linux = bool(self.g) and self.g.get("kind") == "linux"  # native arm64 app: installed as it is

    # ---------------------------------------------------------------- hero
    def hero(self) -> ft.Control:
@@ -81,7 +82,8 @@ class GameView:
        a = g["analysis"]
        art = thumbs.url(pkg, ("hero", "landscape", "portrait", "square", "banner"), 1280, wait=False)
        platform = C.platform(g)[1]
-        facts = " · ".join(x for x in (platform, a.get("engine"), a.get("xr")) if x and x != "?")
+        facts = " · ".join(x for x in (platform, *(() if self.linux else (a.get("engine"), a.get("xr"))))
+                           if x and x not in ("?", "none"))
        recipe = g.get("recipe") or {}
        chips = [C.status_chip(recipe.get("status", "unknown"))]
        st = C.install_state(g, app.frame_info)
@@ -93,7 +95,7 @@ class GameView:
        return ft.Container(
            ft.Stack([
                C.art_fill(art, radius=T.px(16), hero=True, left=0, right=0, top=0, bottom=0,
-                           placeholder_icon=ft.Icons.COMPUTER_ROUNDED if self.rift else ft.Icons.VIEW_IN_AR_ROUNDED),
+                           placeholder_icon=C.platform_icon(g)),
                ft.Container(left=0, right=0, top=0, bottom=0, border_radius=T.px(16), gradient=ft.LinearGradient(
                    begin=ft.Alignment.CENTER_LEFT, end=ft.Alignment.CENTER_RIGHT,
                    colors=[T.soft(T.BG, 0.97), T.soft(T.BG, 0.80), T.soft(T.BG, 0.25)], stops=[0.0, 0.45, 1.0])),
@@ -173,7 +175,8 @@ class GameView:
                     tr("Uses the repack's bundled Revive — experimental on the Frame") if rift_repack and not last else
                     tr("Last launch test: {get} · furthest: {value}")
                     .format(get=last.get('verdict'), value=last.get('milestone') or '—') if last
-                     else tr("Runs directly — no Revive needed") if self.rift else "")
+                     else tr("Runs directly — no Revive needed") if self.rift else
+                     tr("Runs natively on SteamOS, started from the Frame's Steam library") if self.linux else "")
        cards.append(self.target_card(
            ft.Icons.VIEW_IN_AR_ROUNDED, tr("Steam Frame"), frame_line, frame_color, frame_sub,
            [C.icon_btn(ft.Icons.SCIENCE_OUTLINED, C.tip(tr("Launch test on the Frame. ") + HELP["launch_test"]),
@@ -212,6 +215,14 @@ class GameView:
        entry = catalog.lookup(pkg)
        out = []
        extra = g["analysis"].get("extra", {})
+        missing = C.missing_libraries(g, self.app.frame_info) if self.linux else []
+        if missing:
+            out.append(C.callout(ft.Column([
+                C.body(tr("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."),
+                       T.TEXT),
+                C.meta(", ".join(missing), T.TEXT_2, selectable=True)], spacing=T.px(4)), "error",
+                ft.Icons.EXTENSION_OFF_ROUNDED))
        if self.rift and g.get("exe_confirmed") is False:
            out.append(C.callout(ft.Row([
                C.body(tr("FramePort picked {value} to start this game, but there are other candidates. "
@@ -395,7 +406,31 @@ class GameView:
        fill()
        return C.section(tr("Tags"), row, subtitle=tr("Use tags to group and filter your library"), help="tags")

+    def linux_summary(self) -> ft.Control:
+        """A Linux app has nothing to patch: what FramePort installs, and how it starts."""
+        g, pkg = self.g, self.package
+        extra = (g.get("analysis") or {}).get("extra") or {}
+        vr = bool(extra.get("openxr"))
+        lead = tr("Installs the app as it is, unpacked on the Frame, with an entry in its Steam library") \
+            if extra.get("appimage") else tr("Installs the app as it is, with an entry in the Frame's Steam library")
+        change = C.ghost(tr("Change…"), ft.Icons.TERMINAL_ROUNDED, lambda e: self.app.choose_exe(pkg)) \
+            if self.app.linux_programs(g) else None
+        rows = [
+            C.kv(tr("Program"), ft.Row([C.body(g.get("exe") or "", T.TEXT, selectable=True)]
+                                       + ([change] if change else []), spacing=T.S2, wrap=True)),
+            C.kv(tr("AppImage"), tr("Yes") if extra.get("appimage") else tr("No"), "appimage"),
+            C.kv(tr("VR (OpenXR)"), tr("Yes: uses the Frame's OpenXR runtime") if vr else
+                 tr("No: a 2D app")),
+            C.kv(tr("Source"), extra.get("source") or g.get("game_dir") or ""),
+        ]
+        return C.section(tr("What FramePort will do"), C.card(ft.Column([
+            ft.Row([ft.Icon(ft.Icons.TERMINAL_ROUNDED, color=T.PC, size=T.px(18)),
+                    C.body(lead, T.TEXT, weight=ft.FontWeight.W_500, expand=True)], spacing=T.S2),
+            *rows], spacing=T.S3)), help="linux_app")
+
    def recipe_summary(self) -> ft.Control:
+        if self.linux:
+            return self.linux_summary()
        recipe = library.recipe_from_dict(self.g["recipe"])
        entry = catalog.lookup(self.package)
        on = [base.get(pid) for pid in recipe.patches if pid in base.REGISTRY or _known(pid)]
@@ -496,6 +531,18 @@ class GameView:
                save(state["recipe"])
            return handler

+        def choose(pid, key):
+            def handler(e):
+                r = state["recipe"]
+                value = e.control.value or ""
+                if value:  # a non-default choice is stored as the patch's parameter
+                    r.patches[pid] = {key: value}
+                    r.reasons[pid] = tr("Chosen by you.")
+                else:
+                    r.patches.pop(pid, None)
+                save(r)
+            return handler
+
        def set_param(pid, key):
            def handler(e):
                r = state["recipe"]
@@ -536,6 +583,22 @@ class GameView:
                        plain_reason(reason, p.default_on)
                    sub.insert(0, C.meta(shown, T.ACCENT))
                extra = None
+                choices = getattr(p, "CHOICES", None)
+                if choices:  # a plain choice instead of a switch + text field (e.g. Proton: Experimental / Stable)
+                    current = recipe.params(p.id).get(p.params[0].key, "") if on else ""
+                    keys = [k for k, _label in choices]
+                    if current not in keys:  # a tool name typed under technical details
+                        choices = (*choices, (current, current))
+                    rows.append(ft.Container(ft.Row([
+                        ft.Column([C.body(tr(p.title), T.TEXT, weight=ft.FontWeight.W_500), *sub],
+                                  spacing=T.px(3), expand=True),
+                        ft.Dropdown(value=current, width=T.px(280), dense=True, border_color=T.BORDER,
+                                    text_size=T.T_BODY,
+                                    options=[ft.DropdownOption(key=k, text=tr(label)) for k, label in choices],
+                                    on_select=choose(p.id, p.params[0].key)),
+                    ], spacing=T.S3), padding=ft.Padding(T.S4, T.px(10), T.S4, T.px(10)), border=ft.Border(
+                        top=ft.BorderSide(1, T.BORDER))))
+                    continue
                if not technical:
                    pass
                elif cat == "adapter":
@@ -596,6 +659,14 @@ class GameView:
    def details(self) -> ft.Control:
        g, a = self.g, self.g["analysis"]
        rows = [C.kv(tr("Package"), g["package"])]
+        if self.linux:
+            rows += [C.kv(tr("Folder"), g.get("game_dir") or ""),
+                     C.kv(tr("Size"), tr("{value:.1f} GiB").format(value=(g.get("data_bytes") or 0) / 2**30)
+                          if (g.get("data_bytes") or 0) >= 2**30 else
+                          tr("{value:.0f} MiB").format(value=(g.get("data_bytes") or 0) / 2**20))]
+            return ft.ExpansionTile(title=C.body(tr("Details"), T.TEXT, weight=ft.FontWeight.W_600), controls=[
+                ft.Container(ft.Column(rows, spacing=T.S2), padding=ft.Padding(T.S4, 0, T.S4, T.S4))],
+                bgcolor=T.SURFACE, collapsed_bgcolor=T.SURFACE)
        if self.rift:
            rows += [C.kv(tr("Folder"), g.get("game_dir") or ""), C.kv(tr("Executable"), g.get("exe") or ""),
                     C.kv(tr("Type"), f"{a['abis'][0]} · {a['graphics']}"),
@@ -623,7 +694,7 @@ class GameView:
        about = self.about()
        body = [self.hero(), *self.notes(), self.where(), *([about] if about else []), self.tags(),
                self.recipe_summary()]
-        if self.advanced:
+        if self.advanced and not self.linux:  # (a Linux app has no patches)
            body.append(self.advanced_panel())
        body.append(self.details())
        app = self.app
@@ -35,7 +35,7 @@ def auto_tags(game: dict) -> list[str]:
    if "patch_force_passthrough" in patches or "adapter.scene_emul" in patches:
        out.append(tr("Mixed reality"))
    out += ((game.get("details") or {}).get("genres") or [])[:4]  # from the store
-    return out
+    return list(dict.fromkeys(out))  # (a Linux app's platform and "engine" are both "Linux")


 def user_tags(game: dict) -> list[str]:
@@ -89,6 +89,26 @@ def location(game: dict, frame_info: dict | None, pc_installs: set[str]) -> set[
    return out


+def platform_matches(game: dict, platform: str) -> bool:
+    """The library's platform filter: all | quest (Android games and apps) | pcvr (PC VR and Windows) | linux."""
+    kind = game.get("kind") or "quest"
+    return platform == "all" or {"quest": kind not in ("rift", "linux"), "pcvr": kind == "rift",
+                                 "linux": kind == "linux"}.get(platform, True)
+
+
+def platform_filter_options(games: list[dict]) -> list[tuple[str, str]]:
+    """The platform filter's choices: only when the library has more than Android games; one per kind present."""
+    kinds = {g.get("kind") or "quest" for g in games}
+    if not kinds & {"rift", "linux"}:
+        return []
+    out = [("all", tr("All")), ("quest", tr("Android"))]
+    if "rift" in kinds:
+        out.append(("pcvr", tr("PC VR")))
+    if "linux" in kinds:
+        out.append(("linux", tr("Linux")))
+    return out
+
+
 def filter_games(games: list[dict], f: dict, frame_info: dict | None = None,
                 pc_installs: set[str] | frozenset = frozenset()) -> list[dict]:
    q = (f.get("q") or "").strip().lower()
@@ -99,8 +119,7 @@ def filter_games(games: list[dict], f: dict, frame_info: dict | None = None,
            continue
        if any(t.lower() not in tags for t in f.get("tags") or []):
            continue
-        rift = g.get("kind") == "rift"
-        if f.get("platform") == "quest" and rift or f.get("platform") == "pcvr" and not rift:
+        if not platform_matches(g, f.get("platform", "all")):
            continue
        if f.get("status", "all") != "all" and (g.get("recipe") or {}).get("status", "unknown") != f["status"]:
            continue
@@ -184,7 +203,14 @@ class LibraryView:
        self.filters = ft.Container()
        self.hint = ft.Container(visible=False)
        # one right-click menu for every card: filled with that game's actions when it opens (open_menu)
-        self.menu = ft.ContextMenu(content=self.grid, secondary_trigger=None, tertiary_trigger=None, expand=True)
+        # click and drag across cards to select them (turns on select mode; C.DragSelect)
+        self.drag = C.DragSelect(lambda pkg: pkg in self.selected,
+                                 lambda pkg, on: self.toggle_selected(pkg) if (pkg in self.selected) != on else None,
+                                 can_select=lambda pkg: pkg in self.cards,
+                                 on_start=lambda: None if self.select_mode else self.set_select_mode(True))
+        self.menu = ft.ContextMenu(content=ft.GestureDetector(content=self.grid, expand=True,
+                                                              on_pan_start=self.drag.start, on_pan_end=self.drag.end),
+                                   secondary_trigger=None, tertiary_trigger=None, expand=True)
        self.body = ft.Container(self.menu, expand=True)
        add = ft.PopupMenuButton(
            content=ft.Container(ft.Row([ft.Icon(ft.Icons.ADD_ROUNDED, color=T.ON_ACCENT, size=T.px(18)),
@@ -198,7 +224,12 @@ class LibraryView:
                   ft.PopupMenuItem(content=ft.Text(tr("Add one game folder…")),
                                    icon=ft.Icons.CREATE_NEW_FOLDER_ROUNDED, on_click=app.pick_game_folder),
                   ft.PopupMenuItem(content=ft.Text(tr("Add an APK file…")), icon=ft.Icons.ANDROID_ROUNDED,
-                                    on_click=app.pick_apk)],
+                                    on_click=app.pick_apk),
+                   ft.PopupMenuItem(),  # divider: native Linux apps (GitHub #31)
+                   ft.PopupMenuItem(content=ft.Text(tr("Add a Linux app (arm64)…")), icon=ft.Icons.TERMINAL_ROUNDED,
+                                    on_click=app.pick_linux_app),
+                   ft.PopupMenuItem(content=ft.Text(tr("Add a Linux app folder…")), icon=ft.Icons.FOLDER_ROUNDED,
+                                    on_click=app.pick_linux_folder)],
            bgcolor=T.SURFACE_2, tooltip="")
        self.rescan_btn = C.secondary(tr("Rescan folders"), ft.Icons.REFRESH_ROUNDED, app.rescan,
                                      tooltip=C.tip(HELP["rescan"]))
@@ -428,14 +459,14 @@ class LibraryView:
        C.update(self.update_all_btn)
        self._update_hint()
        has_rift = any(g.get("kind") == "rift" for g in games)
+        platforms = platform_filter_options(games)
        where = [("all", tr("All")), ("frame", tr("On Frame")), ("none", tr("Not installed"))]
        if has_rift:
            where.insert(2, ("pc", tr("On this PC")))
        # the filters wrap onto a second line in a narrow window; count and sort stay on the right
        left = ft.Row([
            self._seg("where", where),
-            *([self._seg("platform", [("all", tr("All")), ("quest", tr("Android")), ("pcvr", tr("PC VR"))])]
-              if has_rift else []),
+            *([self._seg("platform", platforms)] if platforms else []),
            C.with_help(self._menu_chip("status", tr("Status"), [("all", tr("Any")), ("works", tr("Works")),
                                                                 ("issues", tr("Works with issues")),
                                                                 ("unknown", tr("Untested")),
@@ -530,8 +561,7 @@ class LibraryView:
            badges.append(C.pill(tr("Check exe"), T.WARN, ft.Icons.HELP_OUTLINE_ROUNDED, overlay=True,
                                 tooltip=C.tip(HELP["check_exe"])))
        label, _, help_key = C.platform(g)
-        platform = C.pill(label, T.PC if rift else T.TEXT,
-                          ft.Icons.COMPUTER_ROUNDED if rift else ft.Icons.VIEW_IN_AR_ROUNDED, overlay=True,
+        platform = C.pill(label, T.PC if rift else T.TEXT, C.platform_icon(g), overlay=True,
                          tooltip=C.tip(HELP[help_key]))
        check = ft.Container(ft.Checkbox(value=pkg in self.selected, active_color=T.ACCENT, check_color=T.ON_ACCENT,
                                         on_change=lambda e: self.toggle_selected(pkg)),
@@ -554,7 +584,7 @@ class LibraryView:
        tile = ft.Container(
            ft.Stack([
                C.art_fill(art, left=0, right=0, top=0, bottom=0, opacity=0.5 if dim else 1.0,
-                           placeholder_icon=ft.Icons.COMPUTER_ROUNDED if rift else ft.Icons.VIEW_IN_AR_ROUNDED),
+                           placeholder_icon=C.platform_icon(g)),
                ft.Container(C.bottom_fade(None, 0.92), left=0, right=0, bottom=0, top=T.px(90)),
                # platform + state badges in one row that wraps: on a narrow card "On Frame" covered "Android"
                ft.Container(ft.Row([platform, *badges], spacing=T.px(4), run_spacing=T.px(4), wrap=True),
@@ -571,11 +601,13 @@ class LibraryView:
            border_radius=T.RADIUS, bgcolor=T.SURFACE, border=ft.Border.all(1, T.BORDER), expand=True,
            scale=1.0, animate_scale=ft.Animation(140, ft.AnimationCurve.EASE_OUT),
            shadow=card_shadow(),
-            tooltip=ft.Tooltip(message=tr("Click to open · right-click for quick actions"), wait_duration=1500),
+            tooltip=ft.Tooltip(message=tr("Click to open · right-click for quick actions · drag across cards to "
+                                          "select several"), wait_duration=1500),
            on_click=lambda e: self.toggle_selected(pkg) if self.select_mode else app.open_game(pkg))

        def hover(e):
            on = e.data in (True, "true")
+            self.drag.hover(pkg, on)
            tile.scale = 1.03 if on else 1.0
            tile.border = ft.Border.all(1, T.ACCENT if on else T.BORDER)
            tile.shadow = card_shadow(on)
@@ -0,0 +1,435 @@
+"""Screenshots: the Steam screenshots taken on the Frame, newest first, grouped by day, filterable by game.
+
+The Frame files every headset screenshot under SteamVR; the agent matches them to FramePort games by play session
+(install/screenshots.py). Persistent like the Library: the filter survives switching tabs. Thumbnails are downloaded
+once into the cache and shown by asset URL; cards stream in batches from a background thread. Downloads are jobs.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import flet as ft
+
+from ...artwork import thumbs
+from ...errors import explain
+from ...i18n import tr, tr_n
+from .. import components as C
+from .. import theme as T
+from .files_dialog import human
+
+if TYPE_CHECKING:
+    from ..app import FramePortApp
+
+BATCH = 12
+ALL = "__all__"
+OTHER = "__other__"  # shots of no FramePort game (SteamVR home, Steam games)
+
+
+def day_label(t: float | None, now: float | None = None) -> str:
+    if not t:
+        return tr("Unknown date")
+    now = now or time.time()
+    day = time.strftime("%Y-%m-%d", time.localtime(t))
+    if day == time.strftime("%Y-%m-%d", time.localtime(now)):
+        return tr("Today")
+    if day == time.strftime("%Y-%m-%d", time.localtime(now - 86400)):
+        return tr("Yesterday")
+    return day
+
+
+def group_by_day(shots: list[dict], now: float | None = None) -> list[tuple[str, list[dict]]]:
+    """[(day label, shots)] in the order given (newest first)."""
+    out: list[tuple[str, list[dict]]] = []
+    for s in shots:
+        label = day_label(s.get("time"), now)
+        if out and out[-1][0] == label:
+            out[-1][1].append(s)
+        else:
+            out.append((label, [s]))
+    return out
+
+
+def filter_key(package: str | None) -> str:
+    return ALL if package is None else (package or OTHER)
+
+
+def agent_filter(key: str) -> str | None:
+    """The agent's `package` argument for a dropdown key."""
+    return None if key == ALL else "" if key == OTHER else key
+
+
+class ScreenshotsView:
+    def __init__(self, app: FramePortApp):
+        self.app = app
+        self.filter = ALL
+        self.shots: list[dict] = []
+        self.games: list[dict] = []
+        self.selected: set[str] = set()  # paths
+        self.checks: dict[str, ft.Checkbox] = {}
+        self._gen = 0
+        self._loaded = False
+        self._lock = threading.Lock()
+        self.dropdown = ft.Dropdown(label=tr("Game"), value=ALL, width=T.px(300), dense=True,
+                                    options=[ft.DropdownOption(key=ALL, text=tr("All games"))],
+                                    on_select=lambda e: self.set_filter(e.control.value))
+        self.select_all = ft.Checkbox(value=False, active_color=T.ACCENT, check_color=T.ON_ACCENT,
+                                      tooltip=tr("Select all"), on_change=self._toggle_all)
+        self.toolbar = ft.Row([
+            self.dropdown, self.select_all, ft.Container(expand=True),
+            C.secondary(tr("Download all"), ft.Icons.DOWNLOAD_ROUNDED, self._download_all),
+            C.icon_btn(ft.Icons.REFRESH_ROUNDED, tr("Refresh"), lambda e: self.load()),
+        ], spacing=T.S2, vertical_alignment=ft.CrossAxisAlignment.CENTER)
+        self.sel_label = C.body("", T.TEXT, weight=ft.FontWeight.W_500)
+        self.sel_bar = ft.Container(ft.Row([
+            self.sel_label, ft.Container(expand=True),
+            C.secondary(tr("Download selected"), ft.Icons.DOWNLOAD_ROUNDED, self._download_selected),
+            C.ghost(tr("Delete"), ft.Icons.DELETE_OUTLINE_ROUNDED, lambda e: self.delete(self._chosen())),
+            C.ghost(tr("Clear"), ft.Icons.CLOSE_ROUNDED, lambda e: self._clear_selection()),
+        ], spacing=T.S2), padding=ft.Padding(T.S3, T.px(6), T.S2, T.px(6)), border_radius=T.RADIUS_SM,
+            bgcolor=T.ACCENT_SOFT, visible=False)
+        self.grid = ft.Column(spacing=T.S3, scroll=ft.ScrollMode.AUTO, expand=True)
+        self.status = C.meta("")
+        # one right-click menu for the grid: filled with the clicked screenshot's actions (or the tab's) when it opens
+        # click and drag across screenshots to select them (C.DragSelect)
+        self.drag = C.DragSelect(lambda p: p in self.selected, self._toggle)
+        self.menu = ft.ContextMenu(content=ft.GestureDetector(
+            content=C.card(self.grid, padding=T.S3, expand=True), expand=True,
+            on_secondary_tap_down=lambda e: self.open_menu(None, e.global_position),
+            on_pan_start=self.drag.start, on_pan_end=self.drag.end),
+            secondary_trigger=None, tertiary_trigger=None, expand=True)
+        self.root = None
+
+    # ---------------------------------------------------------------- building
+    def mount(self, package: str | None = None) -> ft.Control:
+        app = self.app
+        heading, sub = tr("Screenshots"), tr("Pictures you took in the headset (Steam screenshots on the Frame)")
+        if not (app.target and app.frame_state == "connected"):
+            self._loaded = False  # load again once connected
+            return ft.Column([
+                app.top_bar(heading, sub),
+                C.empty_state(ft.Icons.PHOTO_LIBRARY_OUTLINED, tr("Connect your Frame first"),
+                              tr("Screenshots on the Frame can be shown once FramePort is connected to it."),
+                              C.primary(tr("Connect"), ft.Icons.LINK_ROUNDED, lambda e: app.go("frame")))], expand=True)
+        if self.root is None:
+            # the selection bar below the grid (as in the Library): above it, it pushed the cards down mid-drag
+            self.root = ft.Column([app.top_bar(heading, sub), self.toolbar, self.menu, self.sel_bar, self.status],
+                                  spacing=T.S3, expand=True, horizontal_alignment=ft.CrossAxisAlignment.STRETCH)
+        if package is not None and filter_key(package) != self.filter:
+            self.filter = filter_key(package)
+            self.dropdown.value = self.filter
+            self.selected.clear()
+            self._loaded = False
+        if not self._loaded:  # later visits keep what was shown (Refresh reloads)
+            self._loaded = True
+            self.load()
+        return self.root
+
+    def set_filter(self, key: str | None) -> None:
+        self.filter = key or ALL
+        self.selected.clear()
+        self.load()
+
+    # ---------------------------------------------------------------- loading (background thread)
+    def load(self) -> None:
+        self._gen += 1
+        self.status.value = tr("Loading…")
+        C.update(self.status)
+        self.app.run_bg(self._load, self._gen, self.filter)
+
+    def _load(self, gen: int, key: str) -> None:
+        from ...install import screenshots
+
+        frame = self.app.target.frame
+        with self._lock:
+            if gen != self._gen:
+                return
+            try:
+                r = screenshots.list_shots(frame, package=agent_filter(key))
+            except Exception as exc:  # noqa: BLE001
+                self.status.value = tr("Couldn't list the screenshots: {exc}").format(exc=explain(exc))
+                C.update(self.status)
+                return
+            if gen != self._gen:
+                return
+            self.shots, self.games = r.get("shots") or [], r.get("games") or []
+            self.selected &= {s["path"] for s in self.shots}
+            self._fill_dropdown()
+            self.checks = {}
+            self.grid.controls = []
+            if not self.shots:
+                empty = C.empty_state(
+                    ft.Icons.PHOTO_CAMERA_OUTLINED, tr("No screenshots yet"),
+                    tr("Take one in the headset with Steam's screenshot shortcut; it shows up here. Screenshots "
+                       "are matched to the FramePort game that was running."))
+                empty.expand, empty.padding = False, T.px(48)  # (expand inside a scrolling column: invalid layout)
+                self.grid.controls = [empty]
+            self._update_selection(render=False)
+            self.status.value = tr_n("{n} screenshot", "{n} screenshots", len(self.shots)) + \
+                ((" · " + human(sum(s.get("size") or 0 for s in self.shots))) if self.shots else "")
+            for c in (self.grid, self.status, self.dropdown):
+                C.update(c)
+            sections: dict[str, ft.Row] = {}
+            index = {s["path"]: i for i, s in enumerate(self.shots)}
+            for start in range(0, len(self.shots), BATCH):
+                if gen != self._gen:
+                    return  # the filter changed or a refresh started: that load takes over
+                batch = self.shots[start:start + BATCH]
+                for s in batch:
+                    try:
+                        screenshots.thumb_path(frame, s)
+                    except Exception:  # noqa: BLE001  (the card shows a placeholder)
+                        pass
+                for label, shots in group_by_day(batch):
+                    row = sections.get(label)
+                    if row is None:
+                        row = sections[label] = ft.Row(spacing=T.S3, run_spacing=T.S3, wrap=True)
+                        self.grid.controls += [C.h2(label), row]
+                    row.controls += [self.card(s, index[s["path"]]) for s in shots]
+                C.update(self.grid)
+
+    def _fill_dropdown(self) -> None:
+        opts = [ft.DropdownOption(key=ALL, text=tr("All games"))]
+        for g in self.games:
+            key = g.get("package") or OTHER
+            title = g.get("title") if g.get("package") else tr("Not from a FramePort game")
+            opts.append(ft.DropdownOption(key=key, text=f"{title} ({g.get('count', 0)})"))
+        if self.filter not in {o.key for o in opts}:  # a game without screenshots (opened from its page)
+            from ...core import library
+
+            pkg = agent_filter(self.filter) or ""
+            opts.append(ft.DropdownOption(key=self.filter, text=(library.game(pkg) or {}).get("title") or pkg))
+        self.dropdown.options = opts  # the agent counts `games` before filtering: the same list for every filter
+        self.dropdown.value = self.filter
+
+    # ---------------------------------------------------------------- cards
+    def _thumb_url(self, s: dict) -> str | None:
+        from ...install import screenshots
+
+        p = screenshots.cached(self.app.target.frame, s, "thumb")
+        return thumbs.asset_url(p) if p else None
+
+    def card(self, s: dict, i: int) -> ft.Control:
+        when = time.strftime("%H:%M", time.localtime(s["time"])) if s.get("time") else ""
+        check = ft.Checkbox(value=s["path"] in self.selected, active_color=T.ACCENT, check_color=T.ON_ACCENT,
+                            on_change=lambda e, p=s["path"]: self._toggle(p, e.control.value))
+        self.checks[s["path"]] = check
+        caption = ft.Container(ft.Row([C.meta(s.get("title") or "", T.TEXT, expand=True, max_lines=1,
+                                              overflow=ft.TextOverflow.ELLIPSIS), C.meta(when, T.TEXT_2)],
+                                      spacing=T.S2),
+                               left=0, right=0, bottom=0, padding=ft.Padding(T.S2, T.px(14), T.S2, T.px(6)),
+                               gradient=ft.LinearGradient(begin=ft.Alignment.TOP_CENTER,
+                                                          end=ft.Alignment.BOTTOM_CENTER,
+                                                          colors=[ft.Colors.TRANSPARENT, T.soft("#000000", 0.8)]),
+                               border_radius=ft.BorderRadius(0, 0, T.RADIUS_SM, T.RADIUS_SM))
+        tile = ft.Container(
+            ft.Stack([C.art_fill(self._thumb_url(s), radius=T.RADIUS_SM, placeholder_icon=ft.Icons.IMAGE_OUTLINED,
+                                 left=0, right=0, top=0, bottom=0),
+                      caption, ft.Container(check, left=0, top=0)]),
+            width=T.px(256), height=T.px(144), border_radius=T.RADIUS_SM, ink=True,
+            tooltip=f"{s.get('title') or ''} · {day_label(s.get('time'))} {when}",
+            on_click=lambda e, i=i: self.viewer(i),
+            on_hover=lambda e, p=s["path"]: self.drag.hover(p, e.data in (True, "true")))
+        return ft.GestureDetector(content=tile, on_secondary_tap_down=lambda e, s=s: self.open_menu(s,
+                                                                                                  e.global_position))
+
+    # ---------------------------------------------------------------- right-click menu
+    def menu_actions(self, s: dict | None) -> list[tuple | None]:
+        """[(label, icon, handler) | None] for a right-click on screenshot `s` (None = on the grid's empty space). With
+        several screenshots selected and `s` among them, the actions act on the whole selection."""
+        if s is None:
+            if not self.shots:
+                return [(tr("Refresh"), ft.Icons.REFRESH_ROUNDED, lambda e: self.load())]
+            return [(tr("Download all ({n})…").format(n=len(self.shots)), ft.Icons.DOWNLOAD_ROUNDED,
+                     lambda e: self._later(self.download, list(self.shots))),
+                    (tr("Select all"), ft.Icons.SELECT_ALL_ROUNDED, lambda e: self._select_all()),
+                    *([(tr("Clear selection"), ft.Icons.CLOSE_ROUNDED, lambda e: self._clear_selection())]
+                      if self.selected else []),
+                    None, (tr("Refresh"), ft.Icons.REFRESH_ROUNDED, lambda e: self.load())]
+        by_path = {x["path"]: x for x in self.shots}
+        shots = [by_path[p] for p in C.menu_targets(s["path"], [x["path"] for x in self.shots
+                                                                if x["path"] in self.selected])]
+        several = len(shots) > 1
+        out: list[tuple | None] = []
+        if not several:
+            out.append((tr("View"), ft.Icons.OPEN_IN_FULL_ROUNDED, lambda e: self.viewer(self.shots.index(s))))
+        out.append((tr("Download {n} screenshots…").format(n=len(shots)) if several else tr("Download…"),
+                    ft.Icons.DOWNLOAD_ROUNDED, lambda e: self._later(self.download, shots)))
+        key = filter_key(s.get("package") or "")
+        if not several and self.filter == ALL and key in {o.key for o in self.dropdown.options}:
+            out.append((tr("Show only this game's screenshots") if s.get("package")
+                        else tr("Show only screenshots not from a FramePort game"),
+                        ft.Icons.FILTER_ALT_OUTLINED, lambda e: self._filter_to(key)))
+        out.append(None)
+        if several:
+            out.append((tr("Clear selection"), ft.Icons.CLOSE_ROUNDED, lambda e: self._clear_selection()))
+        else:
+            on = s["path"] in self.selected
+            out.append((tr("Deselect") if on else tr("Select"),
+                        ft.Icons.CHECK_BOX_OUTLINE_BLANK_ROUNDED if on else ft.Icons.CHECK_BOX_OUTLINED,
+                        lambda e: self._toggle(s["path"], not on)))
+        out += [None, (tr("Delete {n} screenshots…").format(n=len(shots)) if several else tr("Delete…"),
+                       ft.Icons.DELETE_OUTLINE_ROUNDED, lambda e: self.delete(shots))]
+        return out
+
+    def open_menu(self, s: dict | None, position=None) -> None:
+        self.menu.items = C.menu_items(self.menu_actions(s))
+        C.update(self.menu)
+        self.app.page.run_task(self.menu.open, global_position=position)
+
+    def _later(self, coro_fn, *args) -> None:
+        """Run an async action (it asks for a folder) from a plain click handler: Flet only awaits handlers that
+        are coroutine functions themselves."""
+        self.app.page.run_task(coro_fn, *args)
+
+    def _filter_to(self, key: str) -> None:
+        self.dropdown.value = key
+        C.update(self.dropdown)
+        self.set_filter(key)
+
+    # ---------------------------------------------------------------- selection
+    def _toggle(self, path: str, on: bool) -> None:
+        (self.selected.add if on else self.selected.discard)(path)
+        check = self.checks.get(path)
+        if check is not None and check.value != on:
+            check.value = on
+            C.update(check)
+        self._update_selection()
+
+    def _toggle_all(self, e) -> None:
+        on = bool(e.control.value)
+        self.selected = {s["path"] for s in self.shots} if on else set()
+        for check in self.checks.values():
+            if check.value != on:
+                check.value = on
+                C.update(check)
+        self._update_selection()
+
+    def _select_all(self) -> None:
+        self.selected = {s["path"] for s in self.shots}
+        for check in self.checks.values():
+            if not check.value:
+                check.value = True
+                C.update(check)
+        self._update_selection()
+
+    def _clear_selection(self) -> None:
+        self.selected.clear()
+        for check in self.checks.values():
+            if check.value:
+                check.value = False
+                C.update(check)
+        self._update_selection()
+
+    def _update_selection(self, render: bool = True) -> None:
+        n = len(self.selected)
+        size = sum(s.get("size") or 0 for s in self._chosen())
+        self.sel_label.value = tr("{n} selected").format(n=n) + (f" · {human(size)}" if size else "")
+        self.sel_bar.visible = bool(n)
+        self.select_all.value = bool(self.shots) and n == len(self.shots)
+        if render:
+            for c in (self.sel_bar, self.select_all):
+                C.update(c)
+
+    def _chosen(self) -> list[dict]:
+        return [s for s in self.shots if s["path"] in self.selected]
+
+    # ---------------------------------------------------------------- viewer
+    def viewer(self, index: int) -> None:
+        if not self.shots:
+            return
+        page, shots = self.app.page, list(self.shots)
+        state = {"i": index}
+        img = ft.Image(src=self._thumb_url(shots[index]) or "", fit=ft.BoxFit.CONTAIN, width=T.px(1100),
+                       height=T.px(620), border_radius=T.RADIUS_SM)
+        caption = C.body("", T.TEXT, weight=ft.FontWeight.W_500)
+        details = C.meta("")
+
+        def show(delta: int = 0) -> None:
+            state["i"] = (state["i"] + delta) % len(shots)
+            s = shots[state["i"]]
+            img.src = self._thumb_url(s) or img.src
+            caption.value = s.get("title") or ""
+            dims = f"{s['width']}×{s['height']} · " if s.get("width") and s.get("height") else ""
+            when = time.strftime("%Y-%m-%d %H:%M", time.localtime(s["time"])) if s.get("time") else ""
+            details.value = f"{state['i'] + 1} / {len(shots)} · {when} · {dims}{human(s.get('size') or 0)}"
+            C.update(img, caption, details)
+            self.app.run_bg(full, state["i"])
+
+        def full(i: int) -> None:
+            from ...install import screenshots
+
+            try:
+                p = screenshots.image_path(self.app.target.frame, shots[i])
+            except Exception as exc:  # noqa: BLE001
+                details.value += " · " + tr("couldn't load the full image: {exc}").format(exc=explain(exc))
+                C.update(details)
+                return
+            if state["i"] == i:
+                img.src = thumbs.asset_url(p)
+                C.update(img)
+
+        async def download(e):
+            await self.download([shots[state["i"]]])
+
+        def delete(e):
+            page.pop_dialog()
+            self.delete([shots[state["i"]]])
+        page.show_dialog(ft.AlertDialog(
+            content=ft.Container(ft.Column([img, ft.Row([
+                C.icon_btn(ft.Icons.CHEVRON_LEFT_ROUNDED, tr("Previous"), lambda e: show(-1)),
+                ft.Column([caption, details], spacing=0, expand=True),
+                C.icon_btn(ft.Icons.CHEVRON_RIGHT_ROUNDED, tr("Next"), lambda e: show(1)),
+                C.secondary(tr("Download"), ft.Icons.DOWNLOAD_ROUNDED, download),
+                C.icon_btn(ft.Icons.DELETE_OUTLINE_ROUNDED, tr("Delete"), delete),
+                C.ghost(tr("Close"), on_click=lambda e: page.pop_dialog())], spacing=T.S2,
+                vertical_alignment=ft.CrossAxisAlignment.CENTER)], spacing=T.S2, tight=True), width=T.px(1100)),
+            bgcolor=T.BG, shape=ft.RoundedRectangleBorder(radius=T.RADIUS), content_padding=T.S3))
+        show()
+
+    # ---------------------------------------------------------------- actions
+    async def _download_selected(self, e=None):
+        if self.selected:
+            await self.download(self._chosen())
+
+    async def _download_all(self, e=None):
+        if self.shots:
+            await self.download(list(self.shots))
+
+    async def download(self, shots: list[dict]) -> None:
+        folder = await ft.FilePicker().get_directory_path(
+            dialog_title=tr("Save the screenshots to which folder on this PC?"))
+        if not folder:
+            return
+        app = self.app
+
+        def run(job):
+            from ...install import screenshots
+
+            r = screenshots.download(app.target.frame, shots, Path(folder), job.reporter)
+            return tr_n("Downloaded {n} screenshot to {folder}", "Downloaded {n} screenshots to {folder}",
+                        r["files"], folder=r["folder"])
+        app.submit(tr_n("Download {n} screenshot", "Download {n} screenshots", len(shots)), run, None,
+                   kind="tool-frame", open_panel=True)
+
+    def delete(self, shots: list[dict]) -> None:
+        if not shots:
+            return
+
+        def go():
+            def work():
+                from ...install import screenshots
+
+                try:
+                    n = screenshots.delete(self.app.target.frame, shots)
+                    self.app.toast(tr_n("Deleted {n} screenshot", "Deleted {n} screenshots", n))
+                except Exception as exc:  # noqa: BLE001
+                    self.app.toast(explain(exc), error=True)
+                self.selected.difference_update(s["path"] for s in shots)
+                self.load()
+            self.app.run_bg(work)
+        C.confirm(self.app.page, tr_n("Delete {n} screenshot?", "Delete {n} screenshots?", len(shots)),
+                  tr("They are deleted on the Frame and can't be restored. Steam's own screenshot list may still "
+                     "show them until Steam restarts."), tr("Delete"), go, danger=True)
@@ -8,7 +8,7 @@ import flet as ft
 from ... import REPO_URL, __version__, i18n, pipeline
 from ...core.paths import user_data_dir
 from ...errors import explain
-from ...i18n import fmt_size, tr
+from ...i18n import fmt_size, tr, tr_n
 from ...recommend import catalog
 from .. import components as C
 from .. import theme as T
@@ -133,8 +133,38 @@ class SettingsView:
            C.switch(tr("Install updates automatically (downloads in the background, installs when FramePort "
                            "next starts)"), value=bool(library.setting("update.auto_install", False)),
                      on_change=auto_install),
+            ft.Row([C.meta(tr("Asked to test a fix? Dev builds come before the next release."), expand=True),
+                    C.ghost(tr("Install the latest dev build…"), ft.Icons.SCIENCE_OUTLINED,
+                            lambda e: app.updater.install_dev())],
+                   vertical_alignment=ft.CrossAxisAlignment.CENTER),
        ], spacing=T.S3)

+    def catalog_updates(self) -> ft.Control:
+        """Settings → Data: confirmed game configs from GitHub main (recommend/catalog.refresh_remote)."""
+        import time
+
+        from ...core import library
+        from ...recommend import catalog
+
+        app = self.app
+        st = catalog.remote_status()
+        when = time.strftime("%Y-%m-%d %H:%M", time.localtime(st["checked"])) if st["checked"] else tr("never")
+        line = tr("Game configs from GitHub: last checked {when}").format(when=when)
+        if st["skipped"]:
+            line += " · " + tr_n("{n} needs a newer FramePort", "{n} need a newer FramePort", len(st["skipped"]))
+
+        def toggle(e):
+            library.set_setting("catalog.auto_update", bool(e.control.value))
+        return ft.Column([
+            ft.Row([C.meta(line, expand=True),
+                    C.ghost(tr("Check now"), ft.Icons.SYNC_ROUNDED,
+                            lambda e: app.run_bg(lambda: app._refresh_catalog(force=True)))],
+                   vertical_alignment=ft.CrossAxisAlignment.CENTER),
+            C.switch(tr("Update game configs from GitHub automatically (confirmed configs arrive without a "
+                        "FramePort update)"), value=bool(library.setting("catalog.auto_update", True)),
+                     on_change=toggle),
+        ], spacing=T.S2)
+
    def appearance(self) -> ft.Control:
        from ...core import library

@@ -210,6 +240,7 @@ class SettingsView:
                                                       lambda e: app.copy(data))]), "data_folder"),
                C.kv(tr("Catalog"), tr("{len} known-good recipes (bundled, remote and yours)")
                     .format(len=len(catalog.load())), "catalog"),
+                self.catalog_updates(),
            ], spacing=T.S2))),
            # text above, buttons below (side by side, the buttons squeezed the text in a narrow window)
            C.section(tr("Problems and feedback"), C.card(ft.Column([
@@ -38,6 +38,7 @@ _log = logging.getLogger("frameport.updates")

 REPO = REPO_URL.removeprefix("https://github.com/").strip("/")
 LATEST_API = f"https://api.github.com/repos/{REPO}/releases/latest"
+DEV_API = f"https://api.github.com/repos/{REPO}/releases/tags/dev"  # the rolling pre-release CI publishes on demand
 CHECK_EVERY = 6 * 3600          # seconds between automatic checks
 ASSETS = {"win32": "FramePort-windows-x64.zip", "darwin": "FramePort-macos-arm64.zip",
          "linux": "FramePort-linux-x64.tar.gz", "linux-arm64": "FramePort-linux-arm64.tar.gz"}  # never rename
@@ -63,11 +64,15 @@ class Update:

 # ------------------------------------------------------------------------------------------------- versions
 def parse_version(text: str) -> tuple:
-    """(major, minor, patch, final) from "v1.2.3" / "1.2.3-rc1"; pre-releases sort before the final release."""
+    """(major, minor, patch, final, dev) from "v1.2.3" / "1.2.3-rc1" / "1.2.4.dev57": pre-releases and dev builds sort
+    before the final release, dev builds among themselves by build number."""
    m = re.match(r"v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(.*)$", (text or "").strip())
    if not m:
-        return (0, 0, 0, 0)
-    return (int(m.group(1)), int(m.group(2) or 0), int(m.group(3) or 0), 0 if m.group(4).strip() else 1)
+        return (0, 0, 0, 0, 0)
+    rest = m.group(4).strip()
+    dev = re.match(r"[.-]?dev(\d+)", rest)
+    return (int(m.group(1)), int(m.group(2) or 0), int(m.group(3) or 0), 0 if rest else 1,
+            int(dev.group(1)) if dev else 0)


 def is_newer(candidate: str, current: str = __version__) -> bool:
@@ -81,16 +86,24 @@ def platform_asset() -> str | None:
    return ASSETS.get(key)


-def update_from_release(release: dict, asset_name: str | None = None) -> Update | None:
-    """The Update a GitHub "latest release" JSON describes (None for drafts/pre-releases or unusable data)."""
-    if (not isinstance(release, dict) or release.get("draft") or release.get("prerelease")
+def update_from_release(release: dict, asset_name: str | None = None, dev: bool = False) -> Update | None:
+    """The Update a GitHub "latest release" JSON describes (None for drafts/pre-releases or unusable data). dev=True:
+    the rolling `dev` pre-release, whose version comes from its wheel (frameport-0.9.1.dev57-py3-none-any.whl)."""
+    if (not isinstance(release, dict) or release.get("draft") or (release.get("prerelease") and not dev)
            or not release.get("tag_name")):
        return None
    assets = {a.get("name"): a.get("browser_download_url") for a in release.get("assets") or [] if isinstance(a, dict)}
    asset_name = asset_name if asset_name is not None else platform_asset()
-    wheel = next((u for n, u in assets.items() if n and n.endswith(".whl")), None)
+    wheel_name = next((n for n in assets if n and n.endswith(".whl")), None)
+    wheel = assets.get(wheel_name) if wheel_name else None
    tag = release["tag_name"]
-    return Update(version=tag.lstrip("v"), tag=tag, notes=release.get("body") or "", page=release.get("html_url") or "",
+    version = tag.lstrip("v")
+    if dev:
+        m = re.match(r"frameport-([^-]+)-", wheel_name or "")
+        if not m:
+            return None
+        version = m.group(1)
+    return Update(version=version, tag=tag, notes=release.get("body") or "", page=release.get("html_url") or "",
                  asset=asset_name if asset_name in assets else None, asset_url=assets.get(asset_name),
                  sums_url=assets.get(SUMS), wheel_url=wheel, published=release.get("published_at") or "")

@@ -116,6 +129,16 @@ def check(force: bool = False) -> Update | None:
    return up


+def check_dev() -> Update | None:
+    """The latest dev build (Settings → "Install the latest dev build"), or None when none is published or GitHub
+    can't be reached. Returned even when it isn't newer: the caller says so."""
+    try:
+        data = cache.cached_json("app-dev-release.json", DEV_API, max_age=0)
+    except Exception:  # noqa: BLE001
+        return None
+    return update_from_release(data, dev=True) if data else None
+
+
 def refresh_cache() -> None:
    """Fetch the latest release into the cache only (no settings written: safe in a CLI background thread)."""
    try:
@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: GPL-3.0-only
+#define _GNU_SOURCE
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <assert.h>
+#define LOG(...) ((void)0)
+#include "audio_metadata_queue.h"
+static unsigned destroyed;
+static void destroy(void *p) {destroyed++;free(p);}
+static void (*vtable[2])(void*)={NULL,destroy};
+static void *parameter(size_t next_offset,void *next) {
+    unsigned char *p=calloc(1,48);assert(p);
+    memcpy(p,&(void*){vtable},8);memcpy(p+next_offset,&next,8);p[8]=255;
+    return p;
+}
+static void exercise(size_t next_offset) {
+    void *fourth=parameter(next_offset,NULL),*third=parameter(next_offset,fourth);
+    void *second=parameter(next_offset,third),*first=parameter(next_offset,second),*head=first;
+    unsigned char metadata[48]={0},object[120]={0},snapshot[24]={0};
+    memcpy(metadata+8,&first,8);memcpy(metadata+32,&third,8);
+    void *metadata_pointer=metadata;memcpy(object+104,&metadata_pointer,8);
+    uint32_t two=2,one=1;memcpy(object+112,&two,4);
+    void *objects[1]={object},*objects_pointer=objects;
+    memcpy(snapshot,&one,4);memcpy(snapshot+16,&objects_pointer,8);mx_audio_objects=snapshot;
+    unsigned before=destroyed;mx_audio_drain(&head,next_offset);
+    assert(destroyed==before+2 && head==first);
+    void *next;memcpy(&next,(unsigned char*)first+next_offset,8);assert(next==third);
+    memcpy(&next,(unsigned char*)third+next_offset,8);assert(!next);
+    // Audio can still consume and modify the queued metadata in this frame.
+    ((unsigned char*)first)[8]=0;((unsigned char*)third)[8]=0;
+    mx_audio_drain(&head,next_offset);assert(destroyed==before+2);
+    // Once the audio snapshot drops the references, both objects are reclaimed.
+    memset(snapshot,0,4);mx_audio_drain(&head,next_offset);
+    assert(destroyed==before+4 && !head);mx_audio_objects=NULL;
+}
+int main(void) {
+    exercise(40);exercise(24);
+    assert(destroyed==8);
+    // No active frame preserves the original immediate reclamation behavior.
+    void *head=parameter(40,NULL);mx_audio_drain(&head,40);assert(!head && destroyed==9);
+    puts("Queued metadata survives live frame references; mixed queues unlink correctly; retired objects are reclaimed without leaks.");
+}
@@ -0,0 +1,66 @@
+// Test fixture for tests/test_langpack.py: a stand-in for OVRPort's platform loader (libovrplatformloader.so).
+// Like the real one it answers ovr_LanguagePack_GetCurrent/SetCurrent with `return 0` and keeps its own message queue;
+// AssetFile_GetList/StatusById queue one message that carries one "store" asset (id 7).
+// Build: cc -shared -fPIC -O1 fakeloader.c -o libovrplatformloader.so
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+typedef uint64_t u64;
+typedef struct { uint32_t type; u64 req; int err; } fmsg;
+typedef struct { u64 id; char type[16]; char path[32]; } fdet;
+
+static fmsg *q[16];
+static int qn, freed;
+static u64 next_req = 100;
+static fdet store = {7, "store", "/store/a"};
+static int arr_handle;
+
+static u64 post(uint32_t type, int err) {
+    fmsg *m = calloc(1, sizeof *m);
+    m->type = type;
+    m->req = next_req++;
+    m->err = err;
+    q[qn++] = m;
+    return m->req;
+}
+
+u64 ovr_AssetFile_GetList(void) {
+    if (getenv("FAKE_SILENT_LIST")) return next_req++;  // asks, never answers (the case the timeout fallback is for)
+    return post(0x4AFC6F74u, 0);
+}
+u64 ovr_AssetFile_StatusById(u64 id) { return post(0x5D955D38u, id != 7); }
+u64 ovr_LanguagePack_GetCurrent(void) { return 0; }
+u64 ovr_LanguagePack_SetCurrent(const char *tag) { (void)tag; return 0; }
+
+void *ovr_PopMessage(void) {
+    if (!qn) return NULL;
+    fmsg *m = q[0];
+    memmove(q, q + 1, sizeof(q[0]) * (size_t)--qn);
+    return m;
+}
+void ovr_FreeMessage(void *m) { freed++; free(m); }
+uint32_t ovr_Message_GetType(const void *m) { return ((const fmsg *)m)->type; }
+u64 ovr_Message_GetRequestID(const void *m) { return ((const fmsg *)m)->req; }
+_Bool ovr_Message_IsError(const void *m) { return ((const fmsg *)m)->err != 0; }
+void *ovr_Message_GetError(const void *m) { (void)m; return NULL; }
+void *ovr_Message_GetAssetDetails(const void *m) { return ((const fmsg *)m)->err ? NULL : &store; }
+void *ovr_Message_GetAssetDetailsArray(const void *m) { (void)m; return &arr_handle; }
+size_t ovr_AssetDetailsArray_GetSize(const void *a) { (void)a; return 1; }
+void *ovr_AssetDetailsArray_GetElement(const void *a, size_t i) { (void)a; return i == 0 ? &store : NULL; }
+u64 ovr_AssetDetails_GetAssetId(const void *d) { return ((const fdet *)d)->id; }
+const char *ovr_AssetDetails_GetAssetType(const void *d) { return ((const fdet *)d)->type; }
+const char *ovr_AssetDetails_GetDownloadStatus(const void *d) { (void)d; return "available"; }
+const char *ovr_AssetDetails_GetFilepath(const void *d) { return ((const fdet *)d)->path; }
+const char *ovr_AssetDetails_GetIapStatus(const void *d) { (void)d; return "free"; }
+void *ovr_AssetDetails_GetLanguage(const void *d) { (void)d; return NULL; }
+const char *ovr_AssetDetails_GetMetadata(const void *d) { (void)d; return ""; }
+
+// not part of the SDK: lets the test see that our wrapper frees the dispatcher's own message
+int fake_freed(void) { return freed; }
+void fake_late_list(u64 req) {  // the dispatcher answers a GetList after all (late)
+    fmsg *m = calloc(1, sizeof *m);
+    m->type = 0x4AFC6F74u;
+    m->req = req;
+    q[qn++] = m;
+}
@@ -49,6 +49,23 @@ def test_launcher_template(monkeypatch, tmp_path):
    assert subprocess.run(["bash", "-n", str(anchor / "launch.sh")]).returncode == 0


+def test_launcher_repairs_save_folder_permissions(monkeypatch, tmp_path):
+    """SUPERHOT creates its cloud save folder with mode 1700 and quits when it can't write there (Lepton's app
+    writes through the folder's group): the launcher gives every storage folder owner and group write permission."""
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "anchor"
+    anchor.mkdir()
+    a.write_launcher(str(anchor), str(tmp_path / "game"), "com.x.y", "T", 1, "/lepton/lepton", {})
+    fix = next(line for line in (anchor / "launch.sh").read_text().splitlines() if line.startswith("fix_perms()"))
+    saves = tmp_path / "game" / "lepton-data" / "external" / "Android" / "data" / "com.x.y" / "files" / "cloud"
+    saves.mkdir(parents=True)
+    os.chmod(saves, 0o1700)
+    if os.stat(saves).st_mode & 0o777 != 0o700:
+        pytest.skip("filesystem doesn't keep modes")
+    subprocess.run(["bash", "-c", f"app_dir={tmp_path / 'game'}\n{fix}\nfix_perms"], check=True)
+    assert os.stat(saves).st_mode & 0o770 == 0o770
+
+
 def test_cli_protocol(tmp_path):
    p = subprocess.run([sys.executable, str(AGENT), "nope"], capture_output=True, text=True)
    assert p.returncode == 2 and json.loads(p.stdout)["ok"] is False
@@ -86,9 +103,17 @@ def test_cleanup_refuses_outside_paths(monkeypatch, tmp_path):


 # ------------------------------------------------------------------------------------------ PC VR under Proton
-def fake_steam_tools(a, tmp_path):
-    """A Steam library with an ARM64 Proton (needing a runtime) installed, like the Frame's."""
+def fake_steam_tools(a, tmp_path, experimental=False):
+    """A Steam library with an ARM64 Proton (needing a runtime) installed, like the Frame's; experimental=True also
+    installs Proton Experimental (chosen per game; the default is the stable one)."""
    apps = tmp_path / ".local/share/Steam/steamapps"
+    if experimental:
+        (apps / "common/Proton - Experimental (ARM64)").mkdir(parents=True)
+        (apps / "common/Proton - Experimental (ARM64)/toolmanifest.vdf").write_text(
+            '"manifest"\n{\n  "commandline" "/proton %verb%"\n  "require_tool_appid" "4185400"\n}\n')
+        (apps / "appmanifest_4427310.acf").write_text(
+            '"AppState"\n{\n\t"appid"\t\t"4427310"\n\t"name"\t\t"Proton Experimental (ARM64)"\n'
+            '\t"StateFlags"\t\t"4"\n\t"installdir"\t\t"Proton - Experimental (ARM64)"\n}\n')
    (apps / "common/Proton 11.0 (ARM64)").mkdir(parents=True)
    (apps / "common/SteamLinuxRuntime_4-arm64").mkdir(parents=True)
    (apps / "common/Proton 11.0 (ARM64)/toolmanifest.vdf").write_text(
@@ -114,6 +139,8 @@ def test_proton_status_and_command(monkeypatch, tmp_path):
    a = load_agent(monkeypatch, tmp_path)
    apps = fake_steam_tools(a, tmp_path)
    st = a.cmd_proton_status({})
+    assert st["ready"]["name"] == "proton_11-arm64" and st["suggested"]["name"] == "proton_11-arm64"  # stable
+    st = a.cmd_proton_status({"tool": "proton-stable-arm64"})
    assert st["ready"]["name"] == "proton_11-arm64"
    assert [t["name"] for t in st["tools"]] == ["proton_11-arm64", "proton-experimental-arm64"]  # stable first
    cmd = a.compat_command(st["ready"]["dir"])
@@ -129,7 +156,8 @@ def test_install_proton_request_mode(monkeypatch, tmp_path):
    monkeypatch.setattr(a.subprocess, "Popen", lambda args, **k: calls.append(args))
    r = a.cmd_install_proton({"tool": "proton-experimental-arm64"})
    assert r["requested"] == [4427310] and calls == [["steam", "-ifrunning", "steam://install/4427310"]]
-    assert a.cmd_install_proton({})["installed"] is True
+    assert a.cmd_install_proton({"tool": "proton-stable-arm64"})["installed"] is True
+    assert a.cmd_install_proton({})["installed"] is True  # the default: the stable one, already installed


 def test_stub_manifest(monkeypatch, tmp_path):
@@ -144,7 +172,7 @@ def test_stub_manifest(monkeypatch, tmp_path):

 def test_pcvr_install_flow(monkeypatch, tmp_path):
    a = load_agent(monkeypatch, tmp_path)
-    fake_steam_tools(a, tmp_path)
+    fake_steam_tools(a, tmp_path, experimental=True)
    monkeypatch.setattr(a, "pcvr_pids", lambda base: [])
    prep = a.cmd_prepare_pcvr({"package": "rift.space_game", "title": "Space Game"})
    inc = Path(prep["incoming"])
@@ -162,7 +190,7 @@ def test_pcvr_install_flow(monkeypatch, tmp_path):
                 "xrlayer": {"XR_APILAYER_FRAMEPORT_timefix.json": len(layer_json), "libxr_frameport_timefix.so": 3}}
    r = a.cmd_finalize_pcvr({"package": "rift.space_game", "title": "Space Game", "exe": "Space Game.exe",
                             "manifests": manifests, "env": {"PROTON_LOG": "1", "bad key": "x"}, "xr_layer": True})
-    assert r["ok"] and r["proton"] == "proton_11-arm64"
+    assert r["ok"] and r["proton"] == "proton_11-arm64"  # the default: stable, also with Experimental installed
    launch = Path(prep["anchor"]) / "launch.sh"
    text = launch.read_text()
    assert subprocess.run(["bash", "-n", str(launch)]).returncode == 0
@@ -304,7 +332,7 @@ def test_pcvr_launcher_oculus_hmd_helper(monkeypatch, tmp_path):
    import pytest

    a = load_agent(monkeypatch, tmp_path)
-    fake_steam_tools(a, tmp_path)
+    fake_steam_tools(a, tmp_path, experimental=True)
    monkeypatch.setattr(a, "pcvr_pids", lambda base: [])

    def install(pkg, helper=True, revive=True, oculus_hmd=True):
@@ -896,3 +924,384 @@ def test_shortcuts_lost_after_steam_restart(monkeypatch, tmp_path):
    exe, title, start, icon, tag, tags, openvr = a.shortcut_args("com.x.y")
    a.upsert_shortcut(str(cfg / "shortcuts.vdf"), exe, title, start, icon, tag, tags=tags, openvr=openvr)
    assert a.shortcuts_lost(["42"], ["com.x.y"]) == []
+
+
+def test_steam_launch_result_reads_steams_log(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    monkeypatch.setattr(a.time, "sleep", lambda s: None)
+    log = tmp_path / "console_log.txt"
+    old = "[2026-10-04 12:00:00] SteamUI: WARNING: LaunchGameAction: launch error 9 3554078061 LaunchApp AppError_18\n"
+    log.write_text(old)
+    start = log.stat().st_size  # lines from before this launch don't count
+    assert a.steam_launch_result(str(log), start, 3554078061, wait=0)["result"] == "silent"
+    with open(log, "a") as f:  # GitHub #21/#30: Steam's "Game configuration unavailable"
+        f.write("[2026-10-04 12:09:52] SteamUI: WARNING: LaunchGameAction: launch error 9 3554078061 LaunchApp "
+                "AppError_18 \n")
+    got = a.steam_launch_result(str(log), start, 3554078061, wait=0)
+    assert got["result"] == "error" and got["code"] == 9 and got["detail"] == "LaunchApp AppError_18"
+    log.write_text(old + "[2026-10-04 19:12:16] GameAction [AppID 2369265159, ActionID 4] : LaunchApp changed task "
+                         "to CreatingProcess with \"\"\n")
+    assert a.steam_launch_result(str(log), start, 2369265159, wait=0)["result"] == "started"
+
+
+def test_steam_library_report(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "Applications/quest-frame/com.x.y"
+    anchor.mkdir(parents=True)
+    (anchor / "deployment.json").write_text(json.dumps({"package": "com.x.y", "appid": 1, "title": "X", "base": "b"}))
+    cfg = tmp_path / ".local/share/Steam/userdata/42/config"
+    cfg.mkdir(parents=True)
+    exe, title, start, icon, tag, tags, openvr = a.shortcut_args("com.x.y")
+    appid = a.upsert_shortcut(str(cfg / "shortcuts.vdf"), exe, title, start, icon, tag, tags=tags, openvr=openvr)
+    a.upsert_shortcut(str(cfg / "shortcuts.vdf"), '"/usr/bin/other"', "Other", "/", "")
+    logs = tmp_path / ".local/share/Steam/logs"
+    logs.mkdir()
+    (logs / "console_log.txt").write_text(f"noise\n[x] GameAction [AppID {appid}, ActionID 1] : LaunchApp changed "
+                                          "task to Completed\n    path_shortcut: \"/a.desktop\"\n")
+    monkeypatch.setattr(a, "run", lambda cmd, **k: SimpleNamespace(returncode=1, stdout=""))
+    rep, console = a.steam_library_report()
+    acc = rep["accounts"][0]
+    assert acc["shortcuts"] == 2 and acc["exe_dupes"] == 0 and acc["shortcuts_vdf_written"]
+    assert acc["frameport"] == [{"package": "com.x.y", "appid": appid, "title": "X", "start_dir": start,
+                                 "openvr": acc["frameport"][0]["openvr"], "options": acc["frameport"][0]["options"]}]
+    assert f"[AppID {appid}" in console and "noise" not in console and "path_shortcut" not in console
+
+
+def test_steam_launch_result_app_error(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    monkeypatch.setattr(a.time, "sleep", lambda s: None)
+    log = tmp_path / "console_log.txt"
+    log.write_text('[x] GameAction [AppID 3554078061, ActionID 3] : LaunchApp changed task to RequestingLicense\n'
+                   '[x] GameAction [AppID 3554078061, ActionID 3] : LaunchApp failed with AppError_9 with ""\n'
+                   '[x] GameAction [AppID 1234, ActionID 1] : LaunchApp failed with AppError_18 with ""\n')
+    got = a.steam_launch_result(str(log), 0, 3554078061, wait=0)  # GitHub #21: Steam didn't know the shortcut
+    assert got["result"] == "error" and got["code"] == 9
+    assert a.steam_launch_result(str(log), 0, 35540780, wait=0)["result"] == "silent"  # no prefix matches
+
+
+def _fake_steam(a, monkeypatch, tmp_path, appid=2772269798):
+    """Steam's devkit side: answers create/delete requests and writes/removes the shortcut like Steam does."""
+    sent = []
+    vdf = tmp_path / ".local/share/Steam/userdata/42/config/shortcuts.vdf"
+    vdf.parent.mkdir(parents=True, exist_ok=True)
+    (tmp_path / ".steam").mkdir(exist_ok=True)
+    (tmp_path / ".steam/steam.token").write_text("tok")
+    pipe = tmp_path / ".steam/steam.pipe"
+    pipe.write_text("")
+
+    real_open = open
+
+    def fake_open(path, mode="r", *args, **kw):
+        if str(path) == str(pipe) and "w" in mode:
+            class P:
+                def write(self, data):
+                    line = data.decode().strip()
+                    sent.append(line)
+                    from urllib.parse import parse_qs, urlparse
+                    url = urlparse(line.split(" ", 1)[1])
+                    q = parse_qs(url.query)
+                    cmd = url.path.rsplit("/", 1)[-1]
+                    if cmd == "create-shortcut":
+                        gid = q["gameid"][0]
+                        a.upsert_shortcut(str(vdf), f'"{a.DEVKIT_GAMES}/{gid}/launch.sh"', f"Devkit Game: {gid}",
+                                          f"{a.DEVKIT_GAMES}/{gid}", "")
+                        root = a.vdf_decode(vdf.read_bytes())
+                        for v in root["shortcuts"].values():
+                            if v["Exe"].endswith(f'/{gid}/launch.sh"'):
+                                v.update(appid=appid, Devkit=1, DevkitGameID=gid)
+                        vdf.write_bytes(a.vdf_encode(root))
+                    elif cmd == "delete-shortcut":
+                        a.remove_shortcut(str(vdf), f'"{a.DEVKIT_GAMES}/{q["gameid"][0]}/launch.sh"')
+                    real_open(q["response"][0], "w").write("ok")
+
+                def __enter__(self):
+                    return self
+
+                def __exit__(self, *e):
+                    return False
+            return P()
+        return real_open(path, mode, *args, **kw)
+    monkeypatch.setattr(a, "open", fake_open, raising=False)
+    monkeypatch.setattr("builtins.open", fake_open)
+    return sent, vdf
+
+
+def test_devkit_fallback_register_and_unregister(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "Applications/quest-frame/com.camouflaj.manta"
+    (anchor / "artwork").mkdir(parents=True)
+    (anchor / "launch.sh").write_text("#!/bin/sh\n")
+    (anchor / "artwork/portrait.jpg").write_bytes(b"jpg")
+    (anchor / "deployment.json").write_text(json.dumps({"package": "com.camouflaj.manta", "appid": 3554078061,
+                                                        "title": "Batman: Arkham Shadow", "base": str(anchor)}))
+    sent, vdf = _fake_steam(a, monkeypatch, tmp_path)
+    monkeypatch.setattr(a.time, "sleep", lambda s: None)
+    appid = a.devkit_register("com.camouflaj.manta")
+    assert appid == 2772269798 and a.devkit_gameid("com.camouflaj.manta") == "Batman_Arkham_Shadow"
+    assert "create-shortcut" in sent[0] and "gameid=Batman_Arkham_Shadow" in sent[0]  # no spaces in the id
+    dk = tmp_path / "devkit-game"
+    assert json.loads((dk / "Batman_Arkham_Shadow-argv.json").read_text()) == ["launch.sh"]
+    assert os.readlink(dk / "Batman_Arkham_Shadow/launch.sh") == str(anchor / "launch.sh")
+    grid = vdf.parent / "grid"
+    assert (grid / "2772269798p.jpg").exists()  # its art under Steam's new appid
+    assert a.devkit_register("com.camouflaj.manta") == appid  # registering again reuses the same id
+    assert a.devkit_unregister("com.camouflaj.manta")
+    assert not (dk / "Batman_Arkham_Shadow").exists() and not list(grid.iterdir())
+    assert a.devkit_appid("Batman_Arkham_Shadow") is None and not a.devkit_unregister("com.camouflaj.manta")
+    # Steam rejects ids that don't start with a letter (e.g. "4XVR_Video_Player")
+    dep = json.loads((anchor / "deployment.json").read_text())
+    (anchor / "deployment.json").write_text(json.dumps({**dep, "title": "4XVR Video-Player"}))
+    a.devkit_register("com.camouflaj.manta")
+    assert a.devkit_gameid("com.camouflaj.manta") == "Game_4XVR_Video_Player"
+
+
+def test_launch_falls_back_to_devkit_entry(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "Applications/quest-frame/com.x.y"
+    anchor.mkdir(parents=True)
+    (anchor / "deployment.json").write_text(json.dumps({"package": "com.x.y", "appid": 111, "title": "X",
+                                                        "base": str(anchor)}))
+    monkeypatch.setattr(a, "run", lambda cmd, **k: SimpleNamespace(returncode=0, stdout=""))
+    monkeypatch.setattr(a, "shortcut_appid_for", lambda exe: 111)
+    tried, registered = [], {}
+
+    def launch(appid, wait=10):
+        tried.append(appid)
+        return {"result": "error", "code": 9} if appid == 111 else {"result": "started"}
+
+    def register(pkg):
+        registered["id"] = 222
+        return 222
+    monkeypatch.setattr(a, "steam_launch", launch)
+    monkeypatch.setattr(a, "devkit_register", register)
+    monkeypatch.setattr(a, "devkit_gameid", lambda pkg: "X" if registered else None)
+    monkeypatch.setattr(a, "devkit_appid", lambda gid: registered.get("id"))
+    got = a.cmd_launch({"package": "com.x.y"})
+    assert tried == [111, 222] and got["via"] == "devkit" and got["steam"]["result"] == "started"
+    assert got["first_try"]["code"] == 9
+    got = a.cmd_launch({"package": "com.x.y"})  # next time the devkit entry is used right away
+    assert tried[-1] == 222 and got["via"] == "devkit" and "first_try" not in got
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="bash launcher")
+def test_launcher_ends_game_when_its_parent_is_gone(monkeypatch, tmp_path):
+    """GitHub #36: Steam stopping only its reaper left launch.sh + Lepton running; the watchdog stops them."""
+    import signal
+    import time
+
+    a = load_agent(monkeypatch, tmp_path)
+    base, anchor = tmp_path / "base", tmp_path / "anchor"
+    (base / "lepton-app").mkdir(parents=True)
+    anchor.mkdir()
+    marker = tmp_path / "lepton-pid"
+    lepton = tmp_path / "lepton"
+    lepton.write_text(f"#!/bin/bash\necho $$ > {marker}\nexec sleep 300\n")
+    lepton.chmod(0o755)
+    a.write_launcher(str(anchor), str(base), "com.x.y", "X", 123, str(lepton), {})
+    # the reaper stand-in: starts the launcher and waits; then it alone is killed
+    parent = subprocess.Popen(["bash", "-c", f"bash {anchor / 'launch.sh'} & wait"], start_new_session=True)
+    for _ in range(50):
+        if marker.exists() and marker.read_text().strip():
+            break
+        time.sleep(0.1)
+    game = int(marker.read_text())
+    os.kill(parent.pid, signal.SIGKILL)
+    parent.wait()
+    for _ in range(80):  # the watchdog checks every 2 s
+        try:
+            os.kill(game, 0)
+        except ProcessLookupError:
+            break
+        time.sleep(0.1)
+    else:
+        os.killpg(game, signal.SIGKILL)
+        pytest.fail("the game kept running after its parent was gone")
+
+
+def test_upgrade_launchers_adds_watchdog(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "Applications/quest-frame/com.x.y"
+    anchor.mkdir(parents=True)
+    old = f"#!/bin/bash\nfix_perms\n{a.OLD_WATCHDOG}\nexport SteamAppId=1\n"
+    (anchor / "launch.sh").write_text(old)
+    (anchor / "launch.sh").chmod(0o755)
+    assert a.upgrade_launchers() == ["com.x.y"]
+    text = (anchor / "launch.sh").read_text()
+    assert "parent=$PPID" in text and a.OLD_WATCHDOG not in text and os.access(anchor / "launch.sh", os.X_OK)
+    assert a.upgrade_launchers() == []  # once only
+
+
+def test_dashboard_worker_hides_dashboard_after_first_frames(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    monkeypatch.setattr(a.time, "sleep", lambda s: None)
+    log = tmp_path / "launch.log"
+    log.write_text("Lepton starting\n")
+    calls, visible = [], [True, True, False, True]
+
+    def js(expr, timeout=5):
+        calls.append(expr)
+        if expr.endswith("IsDashboardVisible()"):
+            if len(calls) == 1:  # the first frames arrive while it waits
+                pass
+            return visible.pop(0) if visible else False
+        return None
+    monkeypatch.setattr(a, "steam_js", js)
+    clock = iter(range(0, 10000))
+    monkeypatch.setattr(a.time, "time", lambda: next(clock))
+    log.write_text("Lepton starting\nI FrameBridge: pacing: 72.0 fps\n")
+    a.dashboard_worker(str(log), os.getpid(), wait_start=10, window=8)
+    assert calls.count("SteamClient.OpenVR.VROverlay.HideDashboard()") == 3  # at most three times
+
+
+def test_dashboard_worker_starts_at_the_first_submitted_frame(monkeypatch, tmp_path):
+    """Steam's "Resume game" menu opens at the game's first frame (ITR2: 0.3 s after FrameBridge's "new layer:"); the
+    first "pacing:" summary comes ~8 s later, after the player had pressed Resume. The log grows while it waits."""
+    a = load_agent(monkeypatch, tmp_path)
+    log = tmp_path / "launch.log"
+    log.write_text("Lepton starting\nI FrameBridge: xrCreateSwapchain 2016x1728\nI FrameBridge: new la")
+    pieces = ["yer: type=35 swapchain=0x0\n"]  # the marker split across two reads
+
+    def sleep(s):
+        if pieces:
+            with open(log, "a") as f:
+                f.write(pieces.pop(0))
+    monkeypatch.setattr(a.time, "sleep", sleep)
+    clock = iter(range(0, 10000))
+    monkeypatch.setattr(a.time, "time", lambda: next(clock))
+    calls = []
+    monkeypatch.setattr(a, "steam_js", lambda expr, timeout=5: calls.append(expr) or expr.endswith("Visible()"))
+    a.dashboard_worker(str(log), os.getpid(), wait_start=10, window=4)
+    assert "SteamClient.OpenVR.VROverlay.HideDashboard()" in calls
+
+
+def test_dashboard_worker_leaves_a_dashboard_the_player_opened(monkeypatch, tmp_path):
+    """ITR2 (agent 52): the player's controller button opened the dashboard and the worker closed it 60 ms later; the
+    game had paused for it and stayed paused. After a toggle_dashboard_action the worker must stop for good."""
+    a = load_agent(monkeypatch, tmp_path)
+    log, ui = tmp_path / "launch.log", tmp_path / "vrwebhelper_systemui.txt"
+    log.write_text("I FrameBridge: new layer: type=35\n")
+    ui.write_text("| [Dashboard] [ToggleDashboard] toggle_dashboard_action (an earlier session)\n")
+    visible = iter([True, False, False, True, True])
+    calls = []
+
+    def js(expr, timeout=5):
+        calls.append(expr)
+        return next(visible, True) if expr.endswith("Visible()") else None
+    monkeypatch.setattr(a, "steam_js", js)
+    steps = iter(range(10000))
+
+    def sleep(s):
+        if next(steps) == 2:  # the player presses the dashboard button
+            with open(ui, "a") as f:
+                f.write("| [Dashboard] [ToggleDashboard] toggle_dashboard_action bSourceIsVRLinkRemote false\n")
+    monkeypatch.setattr(a.time, "sleep", sleep)
+    clock = iter(range(0, 10000))
+    monkeypatch.setattr(a.time, "time", lambda: next(clock))
+    a.dashboard_worker(str(log), os.getpid(), wait_start=10, window=50, ui_log=str(ui))
+    assert calls.count("SteamClient.OpenVR.VROverlay.HideDashboard()") == 1  # Steam's start-up menu only
+
+
+def test_dashboard_worker_waits_for_vr_frames(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    monkeypatch.setattr(a.time, "sleep", lambda s: None)
+    clock = iter(range(0, 10000))
+    monkeypatch.setattr(a.time, "time", lambda: next(clock))
+    monkeypatch.setattr(a, "steam_js", lambda *x, **k: pytest.fail("no frames yet: must not touch Steam"))
+    log = tmp_path / "launch.log"
+    log.write_text("2D app, no FrameBridge\n")
+    a.dashboard_worker(str(log), os.getpid(), wait_start=5)
+
+
+def test_upgrade_launchers_adds_dashboard_helper(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "Applications/quest-frame/com.x.y"
+    anchor.mkdir(parents=True)
+    (anchor / "launch.sh").write_text(f'{a.OLD_WATCHDOG}\nsetsid lepton start &\nchild=$!\nwait "$child"\n')
+    assert a.upgrade_launchers() == ["com.x.y"]
+    text = (anchor / "launch.sh").read_text()
+    assert "_dashboard_worker" in text and text.index("_dashboard_worker") < text.index('wait "$child"')
+
+
+def test_linux_app_finalize_launcher_and_libraries(monkeypatch, tmp_path):
+    """GitHub #31: an arm64 Linux app (here: a copy of a host ELF) goes to <base>/app with a launcher; the library
+    check runs on the program, uninstall removes it."""
+    import shutil
+
+    a = load_agent(monkeypatch, tmp_path)
+    prep = a.cmd_prepare_linux({"package": "linux.true", "title": "True"})
+    app_in = os.path.join(prep["incoming"], "app", "bin")
+    os.makedirs(app_in)
+    shutil.copy("/bin/true", os.path.join(app_in, "true"))
+    size = os.path.getsize(os.path.join(app_in, "true"))
+    res = a.cmd_finalize_linux({"package": "linux.true", "title": "True", "exe": "bin/true",
+                                "manifests": {"app": {"bin/true": size}}, "openxr": False})
+    assert res["missing_libraries"] == [] and res["moved_files"] == 1
+    dep = a.deployment("linux.true")
+    assert dep["kind"] == "linux" and dep["vr"] is False
+    text = open(os.path.join(prep["anchor"], "launch.sh")).read()
+    assert os.path.join(prep["base"], "app", "bin", "true") in text and "kill -0 $parent" in text
+    assert a.shortcut_args("linux.true")[4] == "Linux app on Frame" and a.shortcut_args("linux.true")[6] is False
+    listed = [g for g in a.cmd_list_installed({})["games"] if g["package"] == "linux.true"]
+    assert listed and listed[0]["apk_present"]
+    monkeypatch.setattr(a, "pcvr_pids", lambda base: [])
+    assert a.cmd_uninstall({"package": "linux.true", "keep_data": False})["removed"]
+    assert not os.path.exists(os.path.join(prep["base"], "app"))
+    with pytest.raises(a.AgentError):
+        a.cmd_finalize_linux({"package": "linux.true", "title": "True", "exe": "../etc/passwd"})
+
+
+def test_appimage_programs_and_missing_libraries(monkeypatch, tmp_path):
+    import shutil
+
+    a = load_agent(monkeypatch, tmp_path)
+    root = tmp_path / "squashfs-root"
+    (root / "usr/bin").mkdir(parents=True)
+    shutil.copy("/bin/true", root / "usr/bin/tool")
+    (root / "AppRun").write_text("#!/bin/sh\n")
+    (root / "AppRun").chmod(0o755)
+    (root / "libfoo.so").write_bytes(b"\x7fELF")
+    assert a.appimage_programs(str(root)) == [str(root / "usr/bin/tool")]  # scripts and libraries skipped
+    assert a.missing_libraries(str(root), [str(root / "usr/bin/tool")]) == []
+
+
+def test_power_schedules_systemctl_in_a_user_timer(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    calls = []
+    monkeypatch.setattr(a, "run", lambda cmd, **k: calls.append(cmd) or SimpleNamespace(returncode=0, stdout="",
+                                                                                         stderr=""))
+    monkeypatch.setattr(a, "game_running", lambda: False)
+    assert a.cmd_power({"action": "restart"}) == {"action": "restart", "in_seconds": 3}
+    assert calls[-1][:2] == ["systemd-run", "--user"] and calls[-1][-2:] == ["systemctl", "reboot"]
+    assert "--on-active=3" in calls[-1]
+    monkeypatch.setattr(a, "game_running", lambda: True)
+    with pytest.raises(a.AgentError, match="game is running"):
+        a.cmd_power({"action": "sleep"})
+    assert a.cmd_power({"action": "sleep", "force": True})["action"] == "sleep"
+    with pytest.raises(a.AgentError):
+        a.cmd_power({"action": "format"})
+
+
+def test_incomplete_deployment_records_dont_break_listing(monkeypatch, tmp_path):
+    """GitHub #40: a deployment.json without "base" made every connection fail with KeyError: 'base'."""
+    a = load_agent(monkeypatch, tmp_path)
+    good = tmp_path / "Applications/quest-frame/com.x.ok"
+    good.mkdir(parents=True)
+    (good / "deployment.json").write_text(json.dumps({"package": "com.x.ok", "appid": 5}))  # no base / title
+    junk = tmp_path / "Applications/quest-frame/other"
+    junk.mkdir(parents=True)
+    (junk / "deployment.json").write_text(json.dumps({"name": "something else"}))
+    games = a.cmd_list_installed({})["games"]
+    assert [g["package"] for g in games] == ["com.x.ok"] and games[0]["base"] == str(good)
+    assert a.deployment("com.x.ok")["base"] == str(good)
+
+
+def test_proton_defaults_to_stable(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    stable = {"name": "proton_11-arm64", "display_name": "Proton 11.0-2 (ARM64)", "aliases": "proton-stable-arm64,"
+              "proton-stable", "experimental": False, "installed": True, "require_installed": True}
+    exp = {"name": "proton-experimental-arm64", "display_name": "Proton Experimental (ARM64)",
+           "aliases": "proton-experimental", "experimental": True, "installed": False, "require_installed": True}
+    assert a.pick_proton([stable, exp])["name"] == "proton_11-arm64"
+    assert a.pick_proton([exp, stable])["name"] == "proton_11-arm64"  # whatever the order
+    assert a.pick_proton([stable, exp], "proton-experimental")["name"] == "proton-experimental-arm64"  # by alias
+    assert a.pick_proton([exp])["name"] == "proton-experimental-arm64"  # only Experimental offered
@@ -0,0 +1,52 @@
+"""Frame.ensure_agent: an older FramePort must not replace a newer agent on the Frame (2026-10-04: an app with agent
+43 put it back over 45 every few seconds, so the newer app's launcher helpers failed)."""
+from frameport.frame import connection
+
+
+def fake_frame(remote_text, monkeypatch, tmp_path, local_version=45):
+    local = tmp_path / "frameport_agent.py"
+    local.write_text(f"#!/usr/bin/env python3\nAGENT_VERSION = {local_version}\n")
+    monkeypatch.setattr(connection, "agent_file", lambda: local)
+    uploads = []
+
+    class SFTP:
+        def open(self, path, mode):
+            class W:
+                def write(self, data):
+                    uploads.append(data)
+
+                def __enter__(self):
+                    return self
+
+                def __exit__(self, *e):
+                    return False
+            return W()
+
+    def run(cmd, **k):
+        if cmd.startswith("sha256sum"):
+            return 0, "0000000000000000\n" + (f"AGENT_VERSION = {remote_text}\n" if remote_text else ""), ""
+        return 0, "", ""
+    class Fake(connection.Frame):
+        sftp = SFTP()
+
+    f = Fake.__new__(Fake)
+    f.__dict__.update(home="/home/steamos", _agent_digest=None, run=run)
+    return f, uploads
+
+
+def test_newer_agent_on_the_frame_is_kept(monkeypatch, tmp_path):
+    f, uploads = fake_frame("46", monkeypatch, tmp_path)
+    f.ensure_agent()
+    assert uploads == []
+
+
+def test_older_or_missing_agent_is_replaced(monkeypatch, tmp_path):
+    for remote in ("43", ""):
+        f, uploads = fake_frame(remote, monkeypatch, tmp_path)
+        f.ensure_agent()
+        assert len(uploads) == 1
+
+
+def test_agent_version_of():
+    assert connection.agent_version_of("x\nAGENT_VERSION = 45\n") == 45
+    assert connection.agent_version_of("nothing") == 0
@@ -312,6 +312,22 @@ def test_picked_art_survives_installs(monkeypatch):
    assert (d / "portrait.png").read_bytes() == png("red")


+
+def test_generated_cover_still_gets_a_steam_placeholder():
+    """The library's generated cover/banner (apps without store art, e.g. WiiCompiled) aren't store art: Steam still
+    gets the placeholder set (it used to get nothing at all, a blank tile in the Frame's library)."""
+    from PIL import Image
+
+    from frameport.artwork import fetch, steam
+
+    pkg = "org.example.generated"
+    d = fetch.artwork_dir(pkg)
+    d.mkdir(parents=True, exist_ok=True)
+    Image.new("RGB", (600, 900)).save(d / "cover.jpg")
+    Image.new("RGB", (920, 430)).save(d / "banner.jpg")
+    art = steam.steam_set(pkg, title="Generated Cover App")
+    assert {"portrait", "landscape", "hero"} <= set(art)
+
 def test_apps_without_store_art_get_a_cover(tmp_path):
    """FramePort's library shows a cover (name + APK icon) for apps no store knows; store art always wins."""
    import zipfile
@@ -355,3 +371,41 @@ def test_converted_copies_are_removed_after_installing(tmp_path, monkeypatch):
    assert pipeline.remove_converted_copies("com.g") == 0
    library.set_setting("build.keep_copies", False)
    assert pipeline.remove_converted_copies("com.g") == 15 and not out.exists()
+
+
+def test_custom_art_replaces_one_kind_and_is_kept(tmp_path):
+    from PIL import Image
+
+    pkg = "com.custom.art"
+    d = fetch.artwork_dir(pkg)
+    (d / "portrait.jpg").write_bytes(png(600, 900))
+    (d / "icon.png").write_bytes(png(128, 128))
+    (d / "cover.jpg").write_bytes(png(600, 900))  # FramePort's generated cover (no store art)
+    src = tmp_path / "mine.png"
+    Image.new("RGB", (1000, 1500), (200, 10, 10)).save(src)
+    out = sources.apply_custom(pkg, "portrait", src)
+    assert out.name == "portrait.jpg" and Image.open(out).size == (1000, 1500)  # no alpha → JPEG
+    assert (d / "icon.png").exists() and not (d / "cover.jpg").exists()  # only that kind is replaced
+    assert (d / fetch.PICKED).read_text() == "custom"  # automatic fetches skip it
+
+    logo = tmp_path / "logo.webp"
+    Image.new("RGBA", (5000, 1000), (0, 0, 0, 0)).save(logo)
+    out = sources.apply_custom(pkg, "logo", logo)
+    assert out.name == "logo.png" and max(Image.open(out).size) == sources.CUSTOM_MAX_PX  # scaled down, PNG
+
+    thumbs.thumb(d / "icon.png", 96)
+    sources.remove_custom(pkg, "icon")
+    assert not list(d.glob("icon.*")) and not list(d.glob("t_icon_*"))
+
+
+@pytest.mark.parametrize("make, why", [
+    (lambda p: p.write_bytes(b"not an image"), "isn't an image"),
+    (lambda p: __import__("PIL.Image").Image.new("RGB", (20, 20)).save(p, "PNG"), "too small"),
+])
+def test_custom_art_rejects_bad_files(tmp_path, make, why):
+    bad = tmp_path / "bad.png"
+    make(bad)
+    with pytest.raises(sources.ArtError, match=why):
+        sources.apply_custom("com.custom.bad", "portrait", bad)
+    with pytest.raises(sources.ArtError):
+        sources.apply_custom("com.custom.bad", "screenshot", bad)
@@ -0,0 +1,19 @@
+"""Exercise metadata retirement with synthetic frames, without game files."""
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+
+def test_audio_metadata_retirement(tmp_path):
+    cc = shutil.which("cc") or shutil.which("gcc") or shutil.which("clang")
+    if not cc:
+        pytest.skip("Native metadata regression test needs a host C compiler")
+    root = Path(__file__).resolve().parents[1]
+    binary = tmp_path / ("audio-metadata-test.exe" if os.name == "nt" else "audio-metadata-test")
+    subprocess.run([cc, "-std=c11", "-Wall", "-Wextra", "-Werror",
+                    "-I", str(root / "native/adapter"),
+                    str(root / "tests/fixtures/src/audio_metadata_test.c"), "-o", str(binary)], check=True)
+    subprocess.run([str(binary)], check=True)
@@ -0,0 +1,73 @@
+"""Confirmed game configs from GitHub main (recommend/catalog.refresh_remote): fetched without a release, skipped when
+they need a newer FramePort."""
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from frameport.recommend import catalog
+
+GOOD = ("package: com.x.good\ntitle: Good\nstatus: works\nframe:\n- frame.unity_text_input\n"
+        "verified:\n  date: '2099-01-01'\n")
+FUTURE_PATCH = "package: com.x.future\ntitle: Future\nstatus: works\nframe:\n- frame.not_yet_released\n"
+FUTURE_FIELD = "package: com.x.field\ntitle: Field\nstatus: works\nlinux_runtime: x\n"
+FUTURE_APP = "package: com.x.app\ntitle: App\nstatus: works\nmin_app: 99.0.0\n"
+
+
+@pytest.fixture
+def github(monkeypatch):
+    files = {"catalog/games/com.x.good.yaml": ("s1", GOOD), "catalog/games/com.x.future.yaml": ("s2", FUTURE_PATCH),
+             "catalog/games/com.x.field.yaml": ("s3", FUTURE_FIELD), "catalog/games/com.x.app.yaml": ("s4", FUTURE_APP),
+             "catalog/triage.yaml": ("s5", "x: 1\n")}
+    calls = []
+
+    def http_get(url, timeout=20, **kw):
+        calls.append(url)
+        if "git/trees" in url:
+            return SimpleNamespace(json=lambda: {"tree": [{"path": p, "type": "blob", "sha": s}
+                                                          for p, (s, _t) in files.items()]})
+        path = url.split("/main/", 1)[1]
+        return SimpleNamespace(text=files[path][1])
+    monkeypatch.setattr(catalog.cache, "http_get", http_get)
+    monkeypatch.delenv("FRAMEPORT_CATALOG_URL", raising=False)
+    monkeypatch.delenv("FRAMEPORT_NO_CATALOG_UPDATE", raising=False)
+    return files, calls
+
+
+def test_remote_configs_are_used_and_newer_app_configs_skipped(github):
+    files, calls = github
+    assert catalog.refresh_remote(force=True) == 0  # the first download: nothing "updated" (no toast)
+    entries = catalog.load(refresh=True)
+    assert entries["com.x.good"].origin == "remote"
+    st = catalog.remote_status()
+    assert set(st["skipped"]) == {"com.x.future", "com.x.field", "com.x.app"}
+    assert "frame.not_yet_released" in st["skipped"]["com.x.future"]
+    assert "com.x.future" not in entries and "com.x.app" not in entries
+    # a second check downloads nothing new (only the file list), and only after 6 h unless forced
+    calls.clear()
+    assert catalog.refresh_remote() == 0 and calls == []
+    assert catalog.refresh_remote(force=True) == 0 and len(calls) == 1
+
+
+def test_changed_and_removed_files(github):
+    files, _ = github
+    catalog.refresh_remote(force=True)
+    files["catalog/games/com.x.good.yaml"] = ("s9", GOOD.replace("status: works", "status: issues"))
+    del files["catalog/games/com.x.app.yaml"]
+    assert catalog.refresh_remote(force=True) == 1
+    assert catalog.load(refresh=True)["com.x.good"].status == "issues"
+    assert not list(catalog.cache.cache_dir().glob("catalog-gh-s4.yaml"))  # removed from main: removed here
+
+
+def test_offline_keeps_the_cache(github, monkeypatch):
+    catalog.refresh_remote(force=True)
+    monkeypatch.setattr(catalog.cache, "http_get", lambda *a, **k: (_ for _ in ()).throw(OSError("offline")))
+    assert catalog.refresh_remote(force=True) == 0
+    assert catalog.load(refresh=True)["com.x.good"].origin == "remote"
+
+
+def test_turned_off(github, monkeypatch):
+    monkeypatch.setenv("FRAMEPORT_NO_CATALOG_UPDATE", "1")
+    assert catalog.refresh_remote(force=True) == 0
+    assert "com.x.good" not in catalog.load(refresh=True)
+    assert json.dumps(catalog.remote_status())  # still reports (never checked)
@@ -0,0 +1,128 @@
+"""Right-click menus in the Files and Screenshots tabs: what they offer, and that a right-click on one of several
+selected items acts on the whole selection (as in a file manager)."""
+from types import SimpleNamespace
+
+from frameport.install.files import Entry
+from frameport.ui import components as C
+from frameport.ui.views.files import FilesView
+from frameport.ui.views.screenshots import ALL, ScreenshotsView
+
+
+class FakeApp(SimpleNamespace):
+    def __init__(self):
+        super().__init__(copied=[], page=SimpleNamespace(run_task=lambda fn, *a, **k: None))
+
+    def copy(self, text):
+        self.copied.append(text)
+
+
+def labels(actions):
+    return [a[0] if a else "—" for a in actions]
+
+
+def test_menu_targets_selection_or_single():
+    assert C.menu_targets("a", ["a", "b"]) == ["a", "b"]
+    assert C.menu_targets("c", ["a", "b"]) == ["c"]  # outside the selection: only the clicked item
+    assert C.menu_targets("a", ["a"]) == ["a"]
+
+
+def files_view():
+    v = FilesView(FakeApp())
+    v.loc = {"id": "videos", "label": "Videos", "path": "/home/x/Videos", "android": "/sdcard/Movies"}
+    v.path = "/home/x/Videos/trips"
+    v.entries = [Entry("clips", "/home/x/Videos/trips/clips", True, 0, 0),
+                 Entry("a.mp4", "/home/x/Videos/trips/a.mp4", False, 10, 0),
+                 Entry("b.mp4", "/home/x/Videos/trips/b.mp4", False, 20, 0)]
+    return v
+
+
+def test_files_menu_single_entry_and_folder_space():
+    v = files_view()
+    folder = labels(v.menu_actions(v.entries[0]))
+    assert folder[:4] == ["Open", "Download to this PC…", "Rename…", "Copy path"]
+    assert "Select" in folder and folder[-1] == "Delete…"
+    actions = v.menu_actions(v.entries[1])
+    assert "Open" not in labels(actions)
+    dict((a[0], a[2]) for a in actions if a)["Copy path"](None)
+    assert v.app.copied == ["/sdcard/Movies/trips/a.mp4"]  # as games see it
+    space = labels(v.menu_actions(None))
+    assert space[:3] == ["Upload files…", "Upload folder…", "New folder…"] and "Refresh" in space
+
+
+def test_files_menu_on_a_selection_acts_on_all_of_it():
+    v = files_view()
+    v.selected = {v.entries[1].path, v.entries[2].path}
+    multi = labels(v.menu_actions(v.entries[2]))
+    assert "Download 2 items to this PC…" in multi and "Delete 2 items…" in multi
+    assert "Rename…" not in multi and "Clear selection" in multi
+    assert "Download to this PC…" in labels(v.menu_actions(v.entries[0]))  # not in the selection: just that one
+
+
+def test_files_menu_keeps_lepton_links_safe():
+    v = files_view()
+    v.loc = {"id": "app:x", "label": "Game", "path": "/base/external", "android": "/sdcard"}
+    v.path = "/base/external"
+    link = Entry("Movies", "/base/external/Movies", True, 0, 0, link=True)
+    v.entries = [link]
+    got = labels(v.menu_actions(link))
+    assert "Rename…" not in got and "Delete…" not in got and "Select" not in got
+
+
+def screenshots_view():
+    v = ScreenshotsView(FakeApp())
+    v.shots = [{"path": f"/s/{i}.jpg", "package": "com.x" if i < 2 else "", "title": "X", "time": 1} for i in range(3)]
+    v._fill_dropdown()
+    return v
+
+
+def test_screenshots_menu():
+    v = screenshots_view()
+    v.games = [{"package": "com.x", "title": "X", "count": 2}, {"package": "", "count": 1}]
+    v._fill_dropdown()
+    one = labels(v.menu_actions(v.shots[0]))
+    assert one[:3] == ["View", "Download…", "Show only this game's screenshots"] and one[-1] == "Delete…"
+    assert "Show only screenshots not from a FramePort game" in labels(v.menu_actions(v.shots[2]))
+    v.filter = "com.x"
+    assert not any("Show only" in x for x in labels(v.menu_actions(v.shots[0])))
+    v.filter = ALL
+    v.selected = {v.shots[0]["path"], v.shots[1]["path"]}
+    multi = labels(v.menu_actions(v.shots[1]))
+    assert "Download 2 screenshots…" in multi and "Delete 2 screenshots…" in multi and "View" not in multi
+    assert labels(v.menu_actions(None))[:2] == ["Download all (3)…", "Select all"]
+
+
+def test_drag_select_paints_a_selection():
+    sel = set()
+    d = C.DragSelect(lambda k: k in sel, lambda k, on: (sel.add if on else sel.discard)(k),
+                     can_select=lambda k: k != "locked")
+    d.hover("a", True)       # just hovering: nothing happens
+    assert sel == set()
+    d.start()                # press on "a" and drag
+    for k in ("b", "locked", "c"):
+        d.hover(k, True)
+    d.hover("b", True)       # passing an item again doesn't flip it back
+    d.end()
+    assert sel == {"a", "b", "c"}
+    d.hover("d", True)       # after the drag: hover only
+    assert "d" not in sel
+
+
+def test_drag_select_from_a_selected_item_deselects():
+    sel = {"a", "b", "c"}
+    d = C.DragSelect(lambda k: k in sel, lambda k, on: (sel.add if on else sel.discard)(k))
+    d.hover("b", True)
+    d.start()
+    d.hover("c", True)
+    d.end()
+    assert sel == {"a"}
+
+
+def test_drag_select_from_empty_space_selects_and_calls_on_start():
+    sel, started = set(), []
+    d = C.DragSelect(lambda k: k in sel, lambda k, on: (sel.add if on else sel.discard)(k),
+                     on_start=lambda: started.append(1))
+    d.hover("a", True)
+    d.hover("a", False)      # left the item: the drag starts on empty space
+    d.start()
+    d.hover("x", True)
+    assert sel == {"x"} and started == [1]
@@ -78,3 +78,17 @@ def test_bundles_contain_the_translations():
    """Both packaging paths ship locales/*.json (flet build packages src/; PyInstaller needs --add-data)."""
    text = (ROOT / "scripts" / "package.py").read_text(encoding="utf-8")
    assert "src/frameport/locales" in text and "frameport/locales" in text
+
+
+def test_tr_n_calls_dont_pass_n_twice():
+    """tr_n formats with n itself: tr_n(..., n, n=n) raises TypeError at runtime (0.9.2 pre-release check)."""
+    import ast
+    from pathlib import Path
+
+    bad = []
+    for path in (Path(__file__).parents[1] / "src/frameport").rglob("*.py"):
+        for node in ast.walk(ast.parse(path.read_text(encoding="utf-8"))):
+            if isinstance(node, ast.Call) and getattr(node.func, "id", None) == "tr_n" and \
+                    any(k.arg == "n" for k in node.keywords):
+                bad.append(f"{path.name}:{node.lineno}")
+    assert not bad, bad
@@ -0,0 +1,416 @@
+"""Language packs (native/langpack + patch frame.langpacks).
+
+The C library is compiled for this host and driven through ctypes against a stand-in for OVRPort's platform loader
+(tests/fixtures/src/fakeloader.c) that went through the real ELF patch (elf.hide_exports): lookups for the hidden
+names no longer find the loader's functions, and the library still reaches them by reading the loader's .dynsym.
+Needs a C compiler on Linux; the device side (bionic) is not covered here."""
+import ctypes as C
+import platform
+import re
+import shutil
+import subprocess
+import time
+import zipfile
+from pathlib import Path
+
+import pytest
+
+from frameport.analysis import elf, langpacks
+from frameport.apk.workspace import ApkWorkspace
+from frameport.core.events import Reporter
+from frameport.core.models import Analysis
+from frameport.patches import base
+from frameport.patches.frame import langpack as patch_mod
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "native/langpack/langpack.c"
+FAKE = Path(__file__).with_name("fixtures") / "src" / "fakeloader.c"
+CC = shutil.which("cc") or shutil.which("gcc") or shutil.which("clang")
+pytestmark = pytest.mark.skipif(not CC or platform.system() != "Linux", reason="needs a C compiler on Linux")
+
+GETLIST, STATUSBYID, GETCURRENT, SETCURRENT = 0x4AFC6F74, 0x5D955D38, 0x1F90F0D5, 0x5B4FBBE0
+VOIDP = C.c_void_p
+
+
+def _analysis(**kw):
+    d = dict(package="com.example.questgame", version="1.0", label="Quest Game", abis=["arm64-v8a"], engine="Unity",
+             xr="OpenXR", graphics="Vulkan (declared in manifest)", direct_vrapi=False, libs=[], launcher_activity=None,
+             has_info_category=True, meta_permissions=[], uses_glad_gl=False, unity_msaa_levels=0,
+             oculus_os_classes=False, is_overport_output=True, debuggable=True, extra={"size": 1})
+    d.update(kw)
+    return Analysis(**d)
+
+
+def _compile(src, out, *extra):
+    subprocess.run([CC, "-shared", "-fPIC", "-O1", "-Wall", "-Wextra", "-Werror", *extra, str(src), "-o", str(out),
+                    "-ldl", "-lpthread"], check=True, capture_output=True)
+
+
+@pytest.fixture(scope="module")
+def built(tmp_path_factory):
+    d = tmp_path_factory.mktemp("langpack-build")
+    _compile(FAKE, d / "fakeloader.so")
+    _compile(SRC, d / "langpack.so", "-fvisibility=hidden")
+    _compile(SRC, d / "langpack_fast.so", "-fvisibility=hidden", "-DFP_LIST_TIMEOUT_MS=100")
+    original = (d / "fakeloader.so").read_bytes()
+    patched, hidden = elf.hide_exports(original, patch_mod.EXPORTS)
+    return {"lib": d / "langpack.so", "fast": d / "langpack_fast.so", "original": original, "patched": patched,
+            "hidden": hidden}
+
+
+def _dlclose(lib):
+    libdl = C.CDLL(None)
+    libdl.dlclose.argtypes = [VOIDP]
+    libdl.dlclose(lib._handle)
+
+
+class Api:
+    """The library under test (`lp`) and the stand-in loader behind it (`loader`)."""
+
+    def __init__(self, lp, loader):
+        self.lp, self.loader = lp, loader
+
+    def f(self, name, res, *args, lib=None):
+        fn = getattr(lib or self.lp, name)
+        fn.restype, fn.argtypes = res, list(args)
+        return fn
+
+    def pop(self):
+        return self.f("ovr_PopMessage", VOIDP)()
+
+    def msg_type(self, m):
+        return self.f("ovr_Message_GetType", C.c_uint32, VOIDP)(m)
+
+    def req_id(self, m):
+        return self.f("ovr_Message_GetRequestID", C.c_uint64, VOIDP)(m)
+
+    def is_error(self, m):
+        return bool(self.f("ovr_Message_IsError", C.c_bool, VOIDP)(m))
+
+    def free(self, m):
+        self.f("ovr_FreeMessage", None, VOIDP)(m)
+
+    def details(self, d):
+        s = lambda name: self.f(name, C.c_char_p, VOIDP)(d)  # noqa: E731
+        lang = self.f("ovr_AssetDetails_GetLanguage", VOIDP, VOIDP)(d)
+        out = {"id": self.f("ovr_AssetDetails_GetAssetId", C.c_uint64, VOIDP)(d),
+               "type": s("ovr_AssetDetails_GetAssetType"), "status": s("ovr_AssetDetails_GetDownloadStatus"),
+               "path": s("ovr_AssetDetails_GetFilepath")}
+        if lang:
+            ls = lambda name: self.f(name, C.c_char_p, VOIDP)(lang)  # noqa: E731
+            out.update(tag=ls("ovr_LanguagePackInfo_GetTag"), en=ls("ovr_LanguagePackInfo_GetEnglishName"),
+                       native=ls("ovr_LanguagePackInfo_GetNativeName"))
+        return out
+
+    def ask(self, name, *args):
+        """Send a request, pop the answer, return (message type, error?, payload getter result)."""
+        argtypes = [C.c_char_p] if args and isinstance(args[0], bytes) else ([C.c_uint64] if args else [])
+        req = self.f(name, C.c_uint64, *argtypes)(*args)
+        m = self.pop()
+        assert m and self.req_id(m) == req
+        return m
+
+
+def _api(built, tmp_path, monkeypatch, which):
+    monkeypatch.delenv("FRAMEPORT_LANGPACK", raising=False)
+    lib = tmp_path / "lib"
+    lib.mkdir()
+    (lib / "libovrplatformloader.so").write_bytes(built["patched"])  # the name the library looks for
+    shutil.copy(built[which], lib / "libfp_langpack.so")
+    loader = C.CDLL(str(lib / "libovrplatformloader.so"))
+    lp = C.CDLL(str(lib / "libfp_langpack.so"))
+    yield Api(lp, loader)
+    _dlclose(lp)
+    _dlclose(loader)
+
+
+@pytest.fixture
+def api(built, tmp_path, monkeypatch):
+    yield from _api(built, tmp_path, monkeypatch, "lib")
+
+
+@pytest.fixture
+def api_fast(built, tmp_path, monkeypatch):  # same library with a 100 ms GetList timeout
+    yield from _api(built, tmp_path, monkeypatch, "fast")
+
+
+@pytest.fixture
+def packs(tmp_path, monkeypatch):
+    root = tmp_path / "obb"
+    (root / "sub").mkdir(parents=True)
+    for rel in ("de.lang", "en-us.lang", "sub/fr.lang", "notes.txt", "x y.lang"):
+        (root / rel).write_bytes(b"data")
+    monkeypatch.setenv("FRAMEPORT_LANGPACK_DIRS", str(root))
+    return root
+
+
+def test_exports_match_the_c_source():
+    text = SRC.read_text()
+    defined = set(re.findall(r"^EXPORT\s+[^;{(]*?\b(ovr_\w+)\s*\(", text, re.M))
+    assert defined == set(patch_mod.EXPORTS)
+    assert len(patch_mod.EXPORTS) == len(defined)
+
+
+def test_hide_exports_keeps_symbols_but_hides_them_from_lookup(built, tmp_path):
+    assert set(built["hidden"]) >= {"ovr_PopMessage", "ovr_LanguagePack_GetCurrent", "ovr_AssetFile_GetList"}
+    assert "fake_freed" not in built["hidden"]
+    d = tmp_path / "orig"
+    d.mkdir()
+    (d / "a.so").write_bytes(built["original"])
+    (d / "b.so").write_bytes(built["patched"])
+    orig, patched = C.CDLL(str(d / "a.so")), C.CDLL(str(d / "b.so"))
+    try:
+        assert orig.ovr_PopMessage and patched.fake_freed  # visible before, others untouched
+        with pytest.raises(AttributeError):
+            patched.ovr_PopMessage  # noqa: B018  hidden: a lookup goes on to the next library
+        # the entries are still defined (the library reads their addresses from .dynsym)
+        assert "ovr_PopMessage" in elf.dyn_symbols(built["patched"], True)
+        assert elf.hide_exports(built["patched"], patch_mod.EXPORTS)[1] == []  # idempotent
+    finally:
+        _dlclose(orig)
+        _dlclose(patched)
+
+
+def test_get_current_without_a_choice_is_an_error_when_several_packs(api, packs):
+    m = api.ask("ovr_LanguagePack_GetCurrent")
+    assert api.msg_type(m) == GETCURRENT and api.is_error(m)
+    err = api.f("ovr_Message_GetError", VOIDP, VOIDP)(m)
+    assert api.f("ovr_Error_GetCode", C.c_int, VOIDP)(err) == 404
+    assert b"no language pack" in api.f("ovr_Error_GetMessage", C.c_char_p, VOIDP)(err)
+    assert not api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m)
+    api.free(m)
+
+
+def test_get_current_by_environment_and_single_pack(api, packs, monkeypatch, tmp_path):
+    monkeypatch.setenv("FRAMEPORT_LANGPACK", "DE")
+    m = api.ask("ovr_LanguagePack_GetCurrent")
+    assert not api.is_error(m)
+    d = api.details(api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m))
+    assert d["type"] == b"language_pack" and d["status"] == b"installed"
+    assert d["path"] == str(packs / "de.lang").encode()
+    assert (d["tag"], d["en"], d["native"]) == (b"de", b"German", b"Deutsch")
+    assert d["id"] >> 48 == 0x4650
+    api.free(m)
+    # exactly one pack and nothing chosen: that one
+    monkeypatch.delenv("FRAMEPORT_LANGPACK")
+    only = tmp_path / "only"
+    only.mkdir()
+    (only / "de.lang").write_bytes(b"x")
+    monkeypatch.setenv("FRAMEPORT_LANGPACK_DIRS", str(only))
+    m = api.ask("ovr_LanguagePack_GetCurrent")
+    assert api.details(api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m))["tag"] == b"de"
+    api.free(m)
+
+
+def test_set_current_then_status_then_get_current(api, packs):
+    m = api.ask("ovr_LanguagePack_SetCurrent", b"de-DE")  # the base language matches
+    assert api.msg_type(m) == SETCURRENT and not api.is_error(m)
+    res = api.f("ovr_Message_GetAssetFileDownloadResult", VOIDP, VOIDP)(m)
+    asset = api.f("ovr_AssetFileDownloadResult_GetAssetId", C.c_uint64, VOIDP)(res)
+    path = api.f("ovr_AssetFileDownloadResult_GetFilepath", C.c_char_p, VOIDP)(res)
+    assert asset and path == str(packs / "de.lang").encode()
+    api.free(m)
+
+    m = api.ask("ovr_AssetFile_StatusById", asset)  # the confirm step of the documented flow
+    assert api.msg_type(m) == STATUSBYID and not api.is_error(m)
+    d = api.details(api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m))
+    assert (d["status"], d["path"], d["id"]) == (b"installed", path, asset)
+    api.free(m)
+
+    m = api.ask("ovr_LanguagePack_GetCurrent")  # the choice sticks
+    assert api.details(api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m))["tag"] == b"de"
+    api.free(m)
+
+    m = api.ask("ovr_AssetFile_StatusById", asset + 1)  # ours by prefix, but unknown
+    assert api.is_error(m)
+    api.free(m)
+
+
+def test_set_current_unknown_pack_is_an_error(api, packs):
+    for tag in (b"xx", b""):
+        m = api.ask("ovr_LanguagePack_SetCurrent", tag)
+        assert api.is_error(m) and not api.f("ovr_Message_GetAssetFileDownloadResult", VOIDP, VOIDP)(m)
+        api.free(m)
+
+
+def test_asset_list_adds_our_packs_to_the_loaders_list(api, packs):
+    req = api.f("ovr_AssetFile_GetList", C.c_uint64)()
+    assert req == 100  # the loader's own request id
+    m = api.pop()
+    assert api.msg_type(m) == GETLIST and api.req_id(m) == req and not api.is_error(m)
+    arr = api.f("ovr_Message_GetAssetDetailsArray", VOIDP, VOIDP)(m)
+    size = api.f("ovr_AssetDetailsArray_GetSize", C.c_size_t, VOIDP)(arr)
+    items = [api.details(api.f("ovr_AssetDetailsArray_GetElement", VOIDP, VOIDP, C.c_size_t)(arr, i))
+             for i in range(size)]
+    assert size == 4
+    ours = [i for i in items if i["type"] == b"language_pack"]
+    assert {i["tag"] for i in ours} == {b"de", b"en-us", b"fr"} and {i["status"] for i in ours} == {b"installed"}
+    store = [i for i in items if i["type"] == b"store"]  # the loader's own entry, served by the loader's accessors
+    assert store == [{"id": 7, "type": b"store", "status": b"available", "path": b"/store/a"}]
+    assert api.f("ovr_AssetDetailsArray_GetElement", VOIDP, VOIDP, C.c_size_t)(arr, 4) is None
+    before = api.loader.fake_freed()
+    api.free(m)  # frees the loader's message behind ours too
+    assert api.loader.fake_freed() == before + 1
+
+
+def _our_metadata(api):
+    api.f("ovr_AssetFile_GetList", C.c_uint64)()
+    m = api.pop()
+    arr = api.f("ovr_Message_GetAssetDetailsArray", VOIDP, VOIDP)(m)
+    get = api.f("ovr_AssetDetailsArray_GetElement", VOIDP, VOIDP, C.c_size_t)
+    out = {api.f("ovr_AssetDetails_GetMetadata", C.c_char_p, VOIDP)(get(arr, i))
+           for i in range(api.f("ovr_AssetDetailsArray_GetSize", C.c_size_t, VOIDP)(arr))
+           if api.f("ovr_AssetDetails_GetAssetType", C.c_char_p, VOIDP)(get(arr, i)) == b"language_pack"}
+    api.free(m)
+    return out
+
+
+def test_metadata_is_empty_without_the_games_version(api, packs, monkeypatch):
+    monkeypatch.delenv("FRAMEPORT_LANGPACK_META", raising=False)
+    assert _our_metadata(api) == {b""}
+
+
+def test_metadata_from_the_environment(api, packs, monkeypatch):
+    monkeypatch.setenv("FRAMEPORT_LANGPACK_META", "2.0.1.77.Quest")
+    assert _our_metadata(api) == {b"2.0.1.77.Quest"}
+
+
+def test_patch_writes_the_games_version_as_the_metadata(built, tmp_path, monkeypatch):
+    monkeypatch.delenv("FRAMEPORT_LANGPACK_META", raising=False)
+    lib = patch_mod.with_metadata(built["lib"].read_bytes(), "1.0.40.356975.Quest")
+    assert len(lib) == built["lib"].stat().st_size and b"1.0.40.356975.Quest" in lib
+    assert patch_mod.with_metadata(lib, "") == lib and patch_mod.with_metadata(b"no marker", "1") == b"no marker"
+    assert patch_mod.with_metadata(lib, "x" * 200) == lib  # too long for the slot: left as it was
+    d = tmp_path / "meta"
+    d.mkdir()
+    (d / "libovrplatformloader.so").write_bytes(built["patched"])
+    (d / "libfp_langpack.so").write_bytes(lib)
+    root = tmp_path / "obb"
+    root.mkdir()
+    (root / "de.lang").write_bytes(b"1")
+    monkeypatch.setenv("FRAMEPORT_LANGPACK_DIRS", str(root))
+    loader, lp = C.CDLL(str(d / "libovrplatformloader.so")), C.CDLL(str(d / "libfp_langpack.so"))
+    try:
+        assert _our_metadata(Api(lp, loader)) == {b"1.0.40.356975.Quest"}
+    finally:
+        _dlclose(lp)
+        _dlclose(loader)
+
+
+def _tags(api):
+    api.f("ovr_AssetFile_GetList", C.c_uint64)()
+    m = api.pop()
+    arr = api.f("ovr_Message_GetAssetDetailsArray", VOIDP, VOIDP)(m)
+    get = api.f("ovr_AssetDetailsArray_GetElement", VOIDP, VOIDP, C.c_size_t)
+    size = api.f("ovr_AssetDetailsArray_GetSize", C.c_size_t, VOIDP)(arr)
+    out = {api.details(get(arr, i)).get("tag") for i in range(size)}
+    api.free(m)
+    out.discard(None)
+    return out
+
+
+def test_packs_can_be_left_out_by_environment_or_file(api, packs, monkeypatch):
+    assert _tags(api) == {b"de", b"en-us", b"fr"}
+    monkeypatch.setenv("FRAMEPORT_LANGPACK_SKIP", "EN-US, x")
+    assert _tags(api) == {b"de", b"fr"}
+    monkeypatch.delenv("FRAMEPORT_LANGPACK_SKIP")
+    (packs / "fp_langpack_skip").write_text("de\nfr\n")
+    assert _tags(api) == {b"en-us"}
+    (packs / "fp_langpack_skip").unlink()
+    assert _tags(api) == {b"de", b"en-us", b"fr"}  # nothing remembered between lists
+
+
+def test_everything_else_reaches_the_loader_unchanged(api, packs):
+    # a status request for the loader's own asset: its message comes back as it is
+    req = api.f("ovr_AssetFile_StatusById", C.c_uint64, C.c_uint64)(7)
+    assert req == 100
+    m = api.pop()
+    assert api.msg_type(m) == STATUSBYID and not api.is_error(m)
+    d = api.details(api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m))
+    assert d["path"] == b"/store/a"
+    api.free(m)
+    assert api.loader.fake_freed() == 1
+    assert api.pop() is None
+
+
+def test_asset_list_without_packs_is_the_loaders_message(api, tmp_path, monkeypatch):
+    monkeypatch.setenv("FRAMEPORT_LANGPACK_DIRS", str(tmp_path / "nothing-here"))
+    api.f("ovr_AssetFile_GetList", C.c_uint64)()
+    m = api.pop()
+    arr = api.f("ovr_Message_GetAssetDetailsArray", VOIDP, VOIDP)(m)
+    assert api.f("ovr_AssetDetailsArray_GetSize", C.c_size_t, VOIDP)(arr) == 1
+    api.free(m)
+    assert api.loader.fake_freed() == 1
+
+
+def test_asset_list_the_loader_never_answers_gets_our_packs_after_the_timeout(api_fast, packs, monkeypatch):
+    monkeypatch.setenv("FAKE_SILENT_LIST", "1")
+    req = api_fast.f("ovr_AssetFile_GetList", C.c_uint64)()
+    assert req == 100
+    assert api_fast.pop() is None  # not overdue yet
+    time.sleep(0.2)
+    m = api_fast.pop()
+    assert m and api_fast.msg_type(m) == GETLIST and api_fast.req_id(m) == req and not api_fast.is_error(m)
+    arr = api_fast.f("ovr_Message_GetAssetDetailsArray", VOIDP, VOIDP)(m)
+    size = api_fast.f("ovr_AssetDetailsArray_GetSize", C.c_size_t, VOIDP)(arr)
+    tags = {api_fast.details(api_fast.f("ovr_AssetDetailsArray_GetElement", VOIDP, VOIDP, C.c_size_t)(arr, i))["tag"]
+            for i in range(size)}
+    assert tags == {b"de", b"en-us", b"fr"}
+    api_fast.free(m)
+    assert api_fast.pop() is None  # answered once
+    before = api_fast.loader.fake_freed()
+    # the dispatcher's answer arrives after all: dropped, not a second answer
+    api_fast.loader.fake_late_list(C.c_uint64(req))
+    assert api_fast.pop() is None
+    assert api_fast.loader.fake_freed() == before + 1
+
+
+def test_find_tags_in_the_data_folder(tmp_path):
+    root = tmp_path / "game"
+    (root / "a" / "b" / "c" / "d").mkdir(parents=True)
+    for rel in ("de.lang", "a/EN-us.LANG", "a/b/c/fr.lang", "a/b/c/d/too-deep.lang", "bad name.lang", "x.txt"):
+        (root / rel).write_bytes(b"1")
+    assert langpacks.find_tags(root) == ["de", "EN-us", "fr"]
+    assert langpacks.find_tags(None) == [] and langpacks.find_tags(tmp_path / "missing") == []
+
+
+def _apk(tmp_path, built):
+    p = tmp_path / "in.apk"
+    with zipfile.ZipFile(p, "w") as z:
+        z.writestr("AndroidManifest.xml", b"manifest")
+        z.writestr("classes.dex", b"dex\n035\0")
+        z.writestr("lib/arm64-v8a/libovrplatformloader.so", built["original"])
+    return p
+
+
+def test_patch_links_the_library_and_hides_the_loaders_functions(built, tmp_path, monkeypatch):
+    monkeypatch.setattr(patch_mod, "artifact", lambda abi, name: b"\x7fELF-langpack")
+    patch = base.get("frame.langpacks")
+    a = _analysis(libs=["libovrplatformloader.so"], extra={"size": 1, "lang_packs": ["de", "en-us"]})
+    assert patch.applies(a)  # the game's data has language packs
+    assert patch.detect(a) is None  # opt-in: never part of a suggested recipe
+    assert not patch.applies(_analysis(libs=["libovrplatformloader.so"]))  # no language packs: nothing to serve
+    assert not patch.applies(_analysis(libs=[], extra={"size": 1, "lang_packs": ["de"]}))  # no platform loader
+    with ApkWorkspace(_apk(tmp_path, built)) as ws:
+        ctx = base.ApkContext(ws, a, {}, Reporter(), {})
+        assert patch.apply(ctx)
+        loader = ws.read_lib("libovrplatformloader.so")
+        assert elf.needed(loader)[0] == "libfp_langpack.so"
+        assert "ovr_PopMessage" in elf.dyn_symbols(loader, True)  # still defined, only no longer global
+        assert ws.read_lib("libfp_langpack.so") == b"\x7fELF-langpack"
+        assert all(ok for _, ok, _ in patch.validate(ctx))
+        assert not patch.apply(base.ApkContext(ws, a, {}, Reporter(), {}))  # applied once is enough
+        assert any("language packs" in n for n in ctx.notes)
+
+
+def test_games_already_in_the_library_get_their_language_packs_after_an_app_update(tmp_path):
+    """lang_packs is read from the data folder (no APK analysis): filled in once for existing entries."""
+    from frameport.core import library
+
+    data = tmp_path / "data"
+    (data / "obb").mkdir(parents=True)
+    (data / "obb" / "de.lang").write_bytes(b"x")
+    g = {"data_dir": str(data), "analysis": {"package": "com.x.y", "extra": {}}}
+    assert library._refresh_data_fields(g, g["analysis"])
+    assert g["analysis"]["extra"]["lang_packs"] == ["de"]
+    assert not library._refresh_data_fields(g, g["analysis"])  # once
@@ -0,0 +1,120 @@
+"""Native arm64 Linux apps (GitHub #31): detection of AppImages, folders and archives."""
+import tarfile
+import zipfile
+
+import pytest
+
+from frameport import pipeline
+from frameport.analysis import linux
+
+
+def elf(machine: int, appimage: bool = False, extra: bytes = b"") -> bytes:
+    head = bytearray(64)
+    head[:4] = b"\x7fELF"
+    head[4], head[5] = 2, 1  # 64-bit, little endian
+    if appimage:
+        head[8:11] = b"AI\x02"
+    head[18:20] = machine.to_bytes(2, "little")
+    return bytes(head) + extra
+
+
+def test_appimage_detection_and_title(tmp_path):
+    p = tmp_path / "Venera-Prime-2.4.2-aarch64.AppImage"
+    p.write_bytes(elf(linux.EM_AARCH64, appimage=True))
+    info = linux.inspect(p)
+    assert info["appimage"] and info["arch_ok"] and info["files"] == [p.name] and info["title"] == "Venera Prime"
+    assert not info["openxr"]
+
+
+def test_x86_64_builds_are_refused(tmp_path):
+    p = tmp_path / "Thing-1.0-x86_64.AppImage"
+    p.write_bytes(elf(linux.EM_X86_64, appimage=True))
+    with pytest.raises(ValueError, match="x86_64"):
+        pipeline.add_linux_app(p)
+
+
+def test_archive_program_ranking_and_openxr(tmp_path):
+    src = tmp_path / "src" / "MatineeVR"
+    (src / "lib").mkdir(parents=True)
+    (src / "MatineeVR").write_bytes(elf(linux.EM_AARCH64))
+    (src / "crashpad_handler").write_bytes(elf(linux.EM_AARCH64))
+    (src / "lib" / "libopenxr_loader.so.1").write_bytes(elf(linux.EM_AARCH64, extra=b"xrCreateInstance"))
+    (src / "data" / "deep").mkdir(parents=True)
+    archive = tmp_path / "MatineeVR-0.8-linux-arm64.tar.gz"
+    with tarfile.open(archive, "w:gz") as t:
+        t.add(src, arcname="MatineeVR")
+    info = linux.inspect(archive)
+    assert info["exe"] == "MatineeVR/MatineeVR" and info["openxr"] and info["arch_ok"]
+    assert linux.inspect(archive)["root"] == info["root"]  # unpacked once
+
+
+def test_bundled_data_libraries_dont_make_an_app_vr(tmp_path):
+    root = tmp_path / "FramePort"
+    (root / "data" / "artifacts" / "arm64-v8a").mkdir(parents=True)
+    (root / "FramePort").write_bytes(elf(linux.EM_AARCH64))
+    (root / "data" / "artifacts" / "arm64-v8a" / "libopenxr_loader.so").write_bytes(b"xrCreateInstance")
+    assert not linux.inspect(root)["openxr"]
+
+
+def test_zip_with_unsafe_paths_is_refused(tmp_path):
+    archive = tmp_path / "bad.zip"
+    with zipfile.ZipFile(archive, "w") as z:
+        z.writestr("../evil", b"x")
+    with pytest.raises(ValueError, match="unsafe"):
+        linux.inspect(archive)
+
+
+def test_add_linux_app_library_entry(tmp_path):
+    p = tmp_path / "Tool-1.2-aarch64.AppImage"
+    p.write_bytes(elf(linux.EM_AARCH64, appimage=True))
+    g = pipeline.add_linux_app(p)
+    assert g["package"] == "linux.tool" and g["kind"] == "linux" and pipeline.is_linux(g)
+    assert g["exe"] == p.name and g["analysis"]["extra"]["appimage"]
+
+
+def test_local_files_of_a_lone_appimage_never_include_its_folder(tmp_path):
+    a, b = tmp_path / "Tool-1.2-aarch64.AppImage", tmp_path / "Other-1.0-aarch64.AppImage"
+    a.write_bytes(elf(linux.EM_AARCH64, appimage=True))
+    b.write_bytes(elf(linux.EM_AARCH64, appimage=True))
+    (tmp_path / "keep.txt").write_text("the user's file")
+    g = pipeline.add_linux_app(a)
+    pipeline.add_linux_app(b)
+    assert g["data_bytes"] == a.stat().st_size
+    assert pipeline.local_game_files(g["package"]) == [a]  # another AppImage in the same folder doesn't block it
+    pipeline.delete_local_files(g["package"])
+    assert not a.exists() and b.exists() and (tmp_path / "keep.txt").exists()
+
+
+def test_change_program_of_a_linux_folder(tmp_path):
+    root = tmp_path / "Matinee"
+    root.mkdir()
+    (root / "Matinee").write_bytes(elf(linux.EM_AARCH64))
+    (root / "helper").write_bytes(elf(linux.EM_AARCH64))
+    g = pipeline.add_linux_app(root)
+    assert g["exe"] == "Matinee" and pipeline.local_game_files(g["package"]) == [root]
+    assert pipeline.set_exe(g["package"], "helper")["exe"] == "helper"
+
+
+def test_linux_recipes_dont_follow_the_catalog(tmp_path, monkeypatch):
+    from frameport.core import library
+
+    p = tmp_path / "Tool-1.2-aarch64.AppImage"
+    p.write_bytes(elf(linux.EM_AARCH64, appimage=True))
+    g = pipeline.add_linux_app(p)
+    monkeypatch.setattr(library, "REFRESH_ON_UPDATE", True)
+    data = library.load()
+    data["settings"]["recipes.app_version"] = "0.0.0"  # as after an app update
+    library._follow_catalog(data)
+    assert data["games"][g["package"]]["recipe"]["as_is"] is True
+
+
+def test_failed_pc_game_on_stable_suggests_experimental_proton():
+    from frameport.core import library
+
+    library.upsert_game("rift.x", kind="rift", recipe={"package": "rift.x", "patches": {}},
+                        installs={"frame": {"result": {"proton": "proton_11-arm64"}}})
+    assert pipeline.proton_alternative_worth_trying("rift.x", "fail")
+    assert not pipeline.proton_alternative_worth_trying("rift.x", "pass")
+    recipe = pipeline.apply_suggestions("rift.x", [pipeline.PROTON_TOOL])
+    assert recipe.patches[pipeline.PROTON_TOOL] == {"tool": "proton-experimental"}
+    assert not pipeline.proton_alternative_worth_trying("rift.x", "fail")  # already on Experimental
@@ -54,6 +54,22 @@ def test_adapter_and_launcher(tmp_path, quest_manifest):
        assert names.count("lib/arm64-v8a/libopenxr_loader_generic.so") == 1


+def test_adapter_refreshes_existing_wrapper(tmp_path, quest_manifest):
+    """Reinstalling an already wrapped APK replaces its adapter with the shipped repair."""
+    from frameport.patches.frame import artifact
+
+    apk = _apk(tmp_path, quest_manifest)
+    with ApkWorkspace(apk) as ws:
+        ws.put(ws.lib("libopenxr_loader_original.so"), b"original-loader")
+        ws.put(ws.lib("libopenxr_loader_generic.so"), b"old-adapter")
+        patch = base.get("frame.adapter")
+        ctx = base.ApkContext(ws, _analysis(), {}, Reporter(), {"frame.adapter": {}})
+        assert patch.apply(ctx)
+        assert ws.read_lib("libopenxr_loader_generic.so") == artifact(ws.abi, "libopenxr_loader_generic.so")
+        assert ws.read_lib("libopenxr_loader_original.so") == b"original-loader"
+        assert not patch.apply(ctx)
+
+
 def test_controller_models_adds_xrshim(tmp_path, quest_manifest):
    from pathlib import Path

@@ -0,0 +1,277 @@
+"""Screenshots tab: the agent's listing (screenshots.vdf + folders, games matched by play session), its delete path
+checks, the launchers' play log, and the PC-side cache/download helpers."""
+import contextlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+
+import pytest
+from test_agent import load_agent
+
+VDF = """"screenshots"
+{
+\t"250820"
+\t{
+\t\t"0"
+\t\t{
+\t\t\t"type"\t\t"1"
+\t\t\t"filename"\t\t"250820/screenshots/20260928184431_1.jpg"
+\t\t\t"thumbnail"\t\t"250820/screenshots/thumbnails/20260928184431_1.jpg"
+\t\t\t"imported"\t\t"1"
+\t\t\t"externalfilename"\t\t"/run/user/1000/Screenshot_Mon_Sep_28_18-44-31_2026.png"
+\t\t\t"width"\t\t"1920"
+\t\t\t"height"\t\t"1080"
+\t\t\t"gameid"\t\t"250820"
+\t\t\t"creation"\t\t"1790635471"
+\t\t}
+\t\t"1"
+\t\t{
+\t\t\t"filename"\t\t"250820/screenshots/20260927100000_1.jpg"
+\t\t\t"creation"\t\t"1790500000"
+\t\t}
+\t\t"2"
+\t\t{
+\t\t\t"filename"\t\t"250820/screenshots/20260101000000_1.jpg"
+\t\t\t"creation"\t\t"1700000000"
+\t\t}
+\t\t"3"
+\t\t{
+\t\t\t"filename"\t\t"../../../../config/escape.jpg"
+\t\t}
+\t}
+}
+"""
+
+
+def make_tree(a, home):
+    user = home / ".local/share/Steam/userdata/123"
+    shots = user / "760/remote/250820/screenshots"
+    (shots / "thumbnails").mkdir(parents=True)
+    (user / "760/screenshots.vdf").write_text(VDF)
+    for name in ("20260928184431_1.jpg", "20260927100000_1.jpg"):
+        (shots / name).write_bytes(b"\xff\xd8" + b"x" * 100)
+    (shots / "thumbnails/20260928184431_1.jpg").write_bytes(b"\xff\xd8thumb")
+    # 20260101000000_1.jpg is listed but deleted; one file isn't in the vdf yet (Steam writes it at exit)
+    (shots / "20260929120000_1.jpg").write_bytes(b"\xff\xd8" + b"y" * 50)
+    (user / "config").mkdir()
+    # a FramePort game installed with its own Steam shortcut + plays.log sessions
+    anchor = home / "Applications/quest-frame/com.x.game"
+    anchor.mkdir(parents=True)
+    (anchor / "deployment.json").write_text(json.dumps({"package": "com.x.game", "title": "X Game",
+                                                        "appid": 3000000001, "base": str(anchor)}))
+    (anchor / "plays.log").write_text("start 1790635000\nend 1790636000\nstart 1790499000\n")
+    other = home / "Applications/quest-frame/com.y.other"
+    other.mkdir(parents=True)
+    (other / "deployment.json").write_text(json.dumps({"package": "com.y.other", "title": "Other", "appid": 5}))
+    (other / "plays.log").write_text("start 1790499500\nend 1790500100\n")
+    # a screenshot filed under a FramePort game's own shortcut appid
+    own = user / "760/remote/3000000001/screenshots"
+    own.mkdir(parents=True)
+    (own / "20260930080000_1.jpg").write_bytes(b"\xff\xd8z")
+    return user
+
+
+def test_kv_parse(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    d = a.kv_parse(VDF)
+    assert d["screenshots"]["250820"]["0"]["creation"] == "1790635471"
+    assert a.kv_parse('"a" { "b" "x\\"y" // c\n "c" { "d" "1"')["a"] == {"b": 'x"y', "c": {"d": "1"}}  # cut off
+    assert a.kv_parse("") == {}
+
+
+def test_list_screenshots_attributes_by_session(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    make_tree(a, tmp_path)
+    r = a.cmd_list_screenshots({})
+    names = [os.path.basename(s["path"]) for s in r["shots"]]
+    assert names == ["20260930080000_1.jpg", "20260929120000_1.jpg", "20260928184431_1.jpg",
+                     "20260927100000_1.jpg"]  # newest first; the deleted and the escaping entry are left out
+    by = {os.path.basename(s["path"]): s for s in r["shots"]}
+    # inside X Game's closed session
+    assert by["20260928184431_1.jpg"]["package"] == "com.x.game"
+    assert by["20260928184431_1.jpg"]["title"] == "X Game" and by["20260928184431_1.jpg"]["width"] == 1920
+    assert by["20260928184431_1.jpg"]["thumb"].endswith("thumbnails/20260928184431_1.jpg")
+    # X Game's open session (no end) was ended by Other's later start, so this one is Other's
+    assert by["20260927100000_1.jpg"]["package"] == "com.y.other"
+    # not in the vdf: timed by its name, outside every session -> SteamVR
+    assert by["20260929120000_1.jpg"]["package"] is None and by["20260929120000_1.jpg"]["title"] == "SteamVR"
+    assert by["20260929120000_1.jpg"]["time"] == int(time.mktime((2026, 9, 29, 12, 0, 0, 0, 0, -1)))
+    assert by["20260929120000_1.jpg"]["thumb"] is None
+    # filed under the game's own shortcut
+    assert by["20260930080000_1.jpg"]["package"] == "com.x.game" and by["20260930080000_1.jpg"]["account"] == "123"
+    assert r["total"] == 4
+    assert {(g["package"], g["count"]) for g in r["games"]} == {("com.x.game", 2), ("com.y.other", 1), (None, 1)}
+    page = a.cmd_list_screenshots({"package": "com.x.game", "offset": 1, "limit": 5})
+    assert page["total"] == 2 and [s["path"] for s in page["shots"]] == [by["20260928184431_1.jpg"]["path"]]
+    assert [s["title"] for s in a.cmd_list_screenshots({"package": ""})["shots"]] == ["SteamVR"]
+
+
+def test_list_screenshots_without_steam(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    assert a.cmd_list_screenshots({}) == {"shots": [], "total": 0, "games": []}
+
+
+def test_open_session_ends_after_a_while(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "Applications/quest-frame/com.x.game"
+    anchor.mkdir(parents=True)
+    (anchor / "plays.log").write_text("start 1000\ngarbage\nend x\n")
+    sessions = a.play_sessions()
+    assert sessions == [(1000, 1000 + a.OPEN_SESSION, "com.x.game")]
+    assert a.session_game(1500, sessions) == "com.x.game" and a.session_game(999, sessions) is None
+    assert a.session_game(1000 + a.OPEN_SESSION + 60, sessions) is None
+
+
+def test_delete_screenshots_only_in_screenshot_folders(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    user = make_tree(a, tmp_path)
+    shots = user / "760/remote/250820/screenshots"
+    target = str(shots / "20260928184431_1.jpg")
+    bad = ["/etc/passwd", str(user / "760/screenshots.vdf"), str(shots / "thumbnails/20260928184431_1.jpg"),
+           str(shots / "../screenshots/20260928184431_1.jpg"), str(shots / "notashot.jpg"), "relative.jpg",
+           str(shots / "20260101000000_1.jpg"), 42]
+    (shots / "notashot.jpg").write_bytes(b"x")
+    for p in bad:
+        with pytest.raises(a.AgentError):
+            a.cmd_delete_screenshots({"paths": [target, p]})
+    assert os.path.exists(target)  # nothing deleted when any path is refused
+    outside = tmp_path / "secret"
+    outside.mkdir()
+    (outside / "20260101000000_1.jpg").write_bytes(b"s")
+    link_dir = user / "760/remote/999/screenshots"
+    link_dir.parent.mkdir(parents=True)
+    link_dir.symlink_to(outside)
+    with pytest.raises(a.AgentError):
+        a.cmd_delete_screenshots({"paths": [str(link_dir / "20260101000000_1.jpg")]})
+    assert (outside / "20260101000000_1.jpg").exists()
+    r = a.cmd_delete_screenshots({"paths": [target]})
+    assert r == {"deleted": [target]}
+    assert not os.path.exists(target) and not (shots / "thumbnails/20260928184431_1.jpg").exists()
+    assert "20260928184431_1.jpg" in (user / "760/screenshots.vdf").read_text()  # Steam's index is left alone
+    assert target not in [s["path"] for s in a.cmd_list_screenshots({})["shots"]]
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="bash launcher")
+def test_launcher_logs_play_sessions(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    base, anchor = tmp_path / "base", tmp_path / "anchor dir"
+    (base / "lepton-app").mkdir(parents=True)
+    anchor.mkdir()
+    lepton = tmp_path / "lepton"
+    lepton.write_text("#!/bin/bash\nexit 0\n")
+    lepton.chmod(0o755)
+    a.write_launcher(str(anchor), str(base), "com.x.y", "X", 123, str(lepton), {"FRAMEPORT_KEEP_DASHBOARD": "1"})
+    env = {**os.environ, "PATH": f"{tmp_path}:{os.environ['PATH']}"}
+    (tmp_path / "podman").write_text("#!/bin/sh\nexit 0\n")
+    (tmp_path / "podman").chmod(0o755)
+    subprocess.run(["bash", str(anchor / "launch.sh")], env=env, timeout=30, capture_output=True)
+    lines = (anchor / "plays.log").read_text().split("\n")
+    assert lines[0].startswith("start ") and lines[1].startswith("end ") and lines[2] == ""
+    assert int(lines[0].split()[1]) <= int(lines[1].split()[1])
+
+
+def test_upgrade_launchers_adds_play_log(monkeypatch, tmp_path):
+    a = load_agent(monkeypatch, tmp_path)
+    root = tmp_path / "Applications/quest-frame"
+    quest, pcvr = root / "com.x.y", root / "rift.z"
+    quest.mkdir(parents=True)
+    pcvr.mkdir(parents=True)
+    a.write_launcher(str(quest), "/b", "com.x.y", "X", 1, "/lepton", {})
+    old = "\n".join(line for line in (quest / "launch.sh").read_text().split("\n") if "plays.log" not in line)
+    (quest / "launch.sh").write_text(old)
+    (pcvr / "launch.sh").write_text('#!/bin/bash\necho hi >"$base/launch.log"\nexec wine game.exe\n')
+    assert sorted(a.upgrade_launchers()) == ["com.x.y", "rift.z"]
+    q = (quest / "launch.sh").read_text()
+    assert q.count("plays.log") == 2 and q.index('"start $(date') < q.index("\nsetsid ")
+    assert '    echo "end $(date +%s)"' in q
+    assert subprocess.run(["bash", "-n", str(quest / "launch.sh")]).returncode == 0
+    p = (pcvr / "launch.sh").read_text()
+    assert p.count("plays.log") == 1 and p.index("plays.log") < p.index("\nexec ")
+    assert a.upgrade_launchers() == []
+
+
+# ------------------------------------------------------------------ PC side
+class FakeSFTP:
+    def __init__(self):
+        self.gets = []
+
+    def get(self, remote, local, callback=None):
+        self.gets.append(remote)
+        shutil.copyfile(remote, local)
+        if callback:
+            callback(os.path.getsize(remote), os.path.getsize(remote))
+
+
+class FakeFrame:
+    def __init__(self, agent_mod):
+        self.sftp = FakeSFTP()
+        self.a = agent_mod
+        self.target = type("T", (), {"host": "10.0.0.5", "name": ""})()
+
+    def agent(self, command, **args):
+        return self.a.COMMANDS[command](args)
+
+
+@pytest.fixture
+def pc(monkeypatch, tmp_path):
+    from frameport.install import installer
+
+    monkeypatch.setattr(installer, "transfer_link", lambda f, r, n: contextlib.nullcontext(f))
+    frame_home = tmp_path / "frame"
+    frame_home.mkdir()
+    a = load_agent(monkeypatch, frame_home)
+    make_tree(a, frame_home)
+    monkeypatch.setenv("FRAMEPORT_HOME", str(tmp_path / "pc"))
+    return FakeFrame(a)
+
+
+def test_pc_cache_and_download(pc, tmp_path):
+    from frameport.core.paths import user_data_dir
+    from frameport.install import screenshots
+
+    r = screenshots.list_shots(pc, package="com.x.game")
+    assert r["total"] == 2
+    shot = next(s for s in r["shots"] if s["thumb"])
+    assert screenshots.cached(pc, shot) is None
+    t = screenshots.thumb_path(pc, shot)
+    assert t.read_bytes() == b"\xff\xd8thumb" and t.is_relative_to(user_data_dir() / "screenshots-cache" / "10.0.0.5")
+    assert screenshots.thumb_path(pc, shot) == t and pc.sftp.gets == [shot["thumb"]]  # downloaded once
+    assert screenshots.cached(pc, shot) == t
+    full = screenshots.image_path(pc, shot)
+    assert full.read_bytes() == open(shot["path"], "rb").read()
+    # without a Steam thumbnail one is made from the full image (here: not an image -> the original is used)
+    no_thumb = next(s for s in r["shots"] if not s["thumb"])
+    assert screenshots.thumb_path(pc, no_thumb).exists()
+    out = tmp_path / "out"
+    got = screenshots.download(pc, r["shots"], out)
+    assert got["files"] == 2 and (out / "X Game" / os.path.basename(shot["path"])).exists()
+    assert screenshots.download(pc, r["shots"], out)["skipped"] == 2  # same size: not copied again
+    assert screenshots.delete(pc, [shot]) == 1 and not os.path.exists(shot["path"])
+    assert screenshots.cached(pc, shot) is None
+
+
+def test_pc_download_cancel(pc, tmp_path):
+    from frameport.core.events import Cancelled, Reporter
+    from frameport.install import screenshots
+
+    rep = Reporter()
+    rep.cancelled.set()
+    with pytest.raises(Cancelled):
+        screenshots.download(pc, screenshots.list_shots(pc)["shots"], tmp_path / "out", rep)
+    assert not list((tmp_path / "out").rglob("*.jpg"))
+
+
+def test_group_by_day():
+    from frameport.ui.views.screenshots import agent_filter, filter_key, group_by_day
+
+    now = time.mktime((2026, 10, 4, 15, 0, 0, 0, 0, -1))
+    shots = [{"time": now - 60}, {"time": now - 3600}, {"time": now - 86400}, {"time": now - 5 * 86400},
+             {"time": None}]
+    groups = group_by_day(shots, now)
+    assert [(label, len(s)) for label, s in groups] == [("Today", 2), ("Yesterday", 1), ("2026-09-29", 1),
+                                                        ("Unknown date", 1)]
+    assert agent_filter(filter_key(None)) is None and agent_filter(filter_key("")) == ""
+    assert agent_filter(filter_key("com.x")) == "com.x"
@@ -125,6 +125,81 @@ def test_untested_games_invite_sharing_their_recipe():
    assert not should_ask_to_share({**g, "kind": "rift"}, True)


+def _linux_app(**extra):
+    return {"package": "linux.tool", "kind": "linux", "title": "Tool", "apk": None, "game_dir": "/apps/tool",
+            "exe": "tool", "recipe": {"status": "unknown", "as_is": True, "overport": False},
+            "analysis": {"engine": "Linux", "xr": "none",
+                         "extra": {"vr_kind": "none", "appimage": False, "openxr": False, "files": None,
+                                   "candidates": ["tool"], **extra}}}
+
+
+def test_linux_app_menus_have_no_conversion_actions(monkeypatch):
+    g = _linux_app()
+    on_frame = {"installed": [{"package": "linux.tool", "kind": "linux"}]}
+    for quick in (True, False):
+        labels = _labels(_app(monkeypatch, g, on_frame).game_actions("linux.tool", quick=quick))
+        for gone in ("Analyze again", "Rebuild only (no install)", "Check game files", "Reset to suggested recipe",
+                     "Save as known-good recipe", "Share working config…", "Game settings…",
+                     "Add videos and files…", "Change program…"):
+            assert gone not in labels, gone
+        assert {"Find artwork…", "Report a problem…", "Collect logs", "Screenshots"} <= set(labels)
+        assert labels[-1] == "Remove from library"
+    quick = _labels(_app(monkeypatch, g, on_frame).game_actions("linux.tool"))
+    assert {"Play on Frame", "Reinstall on Frame", "Launch test on Frame", "Uninstall from Frame"} <= set(quick)
+    several = _linux_app(candidates=["tool", "tool-helper"])
+    assert "Change program…" in _labels(_app(monkeypatch, several, {"installed": []}).game_actions("linux.tool"))
+    lone = _linux_app(candidates=["a", "b"], files=["Tool.AppImage"])  # a lone AppImage: nothing to choose
+    assert "Change program…" not in _labels(_app(monkeypatch, lone, {"installed": []}).game_actions("linux.tool"))
+
+
+def test_linux_apps_install_on_the_frame_only(monkeypatch):
+    g = _linux_app()
+    app = _app(monkeypatch, g, {"installed": []})
+    assert [o[0] for o in app.install_options(g)] == ["Install on Frame"]
+    assert app.quick_action(g) == ("Install on Frame", "install")
+    assert not app.has_game_settings({**g, "analysis": {"extra": {"vr_kind": "openxr", "openxr": True}}})
+    installed = _app(monkeypatch, g, {"installed": [{"package": "linux.tool", "kind": "linux", "recipe": None}]})
+    assert C.install_state(g, installed.frame_info) == "installed"  # no build/recipe record: never "outdated"
+    assert installed.quick_action(g) == ("Play on Frame", "play")
+
+
+def test_linux_platform_badge_filter_and_tags():
+    from frameport.artwork.steam import steam_tags
+    from frameport.ui.views.library import filter_games, platform_filter_options
+
+    g, vr = _linux_app(), _linux_app(openxr=True, vr_kind="openxr")
+    assert C.platform(g)[0] == "Linux" and C.platform(g)[2] == "platform_linux"
+    assert "OpenXR" in C.platform(vr)[1]
+    q = {"package": "com.q", "title": "Q", "recipe": {}}
+    r = {"package": "rift.r", "kind": "rift", "title": "R", "recipe": {}}
+    assert platform_filter_options([q]) == []
+    assert [k for k, _ in platform_filter_options([q, g])] == ["all", "quest", "linux"]
+    assert [k for k, _ in platform_filter_options([q, r, g])] == ["all", "quest", "pcvr", "linux"]
+    games = [q, r, g]
+    pick = {p: [x["package"] for x in filter_games(games, {"platform": p})] for p in ("quest", "pcvr", "linux")}
+    assert pick == {"quest": ["com.q"], "pcvr": ["rift.r"], "linux": ["linux.tool"]}
+    assert steam_tags(g)[:2] == ["Linux app on Frame", "Linux"]
+
+
+def test_linux_missing_libraries_from_the_frame_or_the_last_install():
+    g = _linux_app()
+    assert C.missing_libraries(g, None) == []
+    dep = {"package": "linux.tool", "kind": "linux", "missing_libraries": ["libwebkit2gtk-4.1.so.0"]}
+    assert C.missing_libraries(g, {"installed": [dep]}) == ["libwebkit2gtk-4.1.so.0"]
+    assert C.missing_libraries(g, {"installed": []}) == []  # not on the connected Frame (any more)
+    rec = {**g, "installs": {"old": {"time": 1, "result": {"missing_libraries": ["libold.so"]}},
+                             "new": {"time": 2, "result": {"missing_libraries": ["libgtk-3.so.0"]}}}}
+    assert C.missing_libraries(rec, None) == ["libgtk-3.so.0"]  # offline: the last install's report
+
+
+def test_linux_apps_have_no_twins():
+    from frameport.core.titles import counterparts, twins
+
+    q = {"package": "com.tool", "title": "Tool", "recipe": {}}
+    g = _linux_app()
+    assert twins([q, g]) == set() and counterparts(g, [q, g]) == [] and counterparts(q, [q, g]) == []
+
+
 def test_patch_reasons_in_plain_words():
    from frameport.ui.views.game import plain_reason

@@ -489,3 +489,39 @@ def test_flet_updates_are_serialized():
        assert peak[0] == 1
    finally:
        Session.patch_control = original
+
+
+def test_window_sessions_share_one_job_queue():
+    """Every Flet session (a window reconnect builds a new app object) uses the same queue: a job started in an
+    old session is visible and the next one waits for it, instead of a second build of the same game at once."""
+    from frameport.ui import jobs
+
+    first, second = jobs.shared(), jobs.shared()
+    assert first is second
+    seen = []
+    listener = seen.append
+    first.subscribe(listener)
+    first.unsubscribe(listener)
+    first.unsubscribe(listener)  # twice is harmless
+    assert listener not in first._listeners
+
+
+def test_one_build_per_game_at_a_time():
+    from frameport import pipeline
+
+    assert pipeline._build_lock("com.x.y") is pipeline._build_lock("com.x.y")
+    assert pipeline._build_lock("com.x.y") is not pipeline._build_lock("com.x.z")
+
+
+def test_window_geometry_restores_size_position_and_maximized():
+    from frameport.ui.app import window_geometry
+
+    first = window_geometry(None, 1.25)
+    assert first == {"width": 1600, "height": 975}  # no position: the system places it
+    got = window_geometry({"size": [1400, 900], "pos": [320, 140], "maximized": True}, 1.0)
+    assert got == {"width": 1400, "height": 900, "left": 320, "top": 140, "maximized": True}
+    assert window_geometry({"size": [800, 500]}, 1.0) == {"width": 1000, "height": 680}  # minimum size
+    # a monitor to the left (negative x) is fine; far off or malformed positions are ignored (GitHub #32)
+    assert window_geometry({"pos": [-1800, 50]}, 1.0)["left"] == -1800
+    for bad in ([-20000, 0], [100, -400], [99999, 0], ["a", 1], [1]):
+        assert "left" not in window_geometry({"pos": bad}, 1.0)
@@ -254,3 +254,27 @@ def test_platform_asset_picks_the_arm64_linux_bundle(monkeypatch):
    assert updates.platform_asset() == "FramePort-linux-arm64.tar.gz"
    monkeypatch.setattr(updates.platform, "machine", lambda: "x86_64")
    assert updates.platform_asset() == "FramePort-linux-x64.tar.gz"
+
+
+def test_dev_build_versions_sort_between_releases():
+    import importlib.util
+    from pathlib import Path
+
+    spec = importlib.util.spec_from_file_location("dev_version", Path(__file__).parents[1] / "scripts/dev_version.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    assert mod.dev_version("0.9.0", 57) == "0.9.1.dev57"
+    pv = updates.parse_version
+    assert pv("0.9.0") < pv("0.9.1.dev57") < pv("0.9.1.dev58") < pv("0.9.1")
+    assert updates.is_newer("0.9.1", "0.9.1.dev58") and not updates.is_newer("0.9.0", "0.9.1.dev58")
+
+
+def test_dev_release_is_only_read_on_request():
+    release = {"tag_name": "dev", "prerelease": True, "html_url": "https://example/dev", "body": "try X",
+               "assets": [{"name": "frameport-0.9.1.dev57-py3-none-any.whl", "browser_download_url": "w"},
+                          {"name": "FramePort-windows-x64.zip", "browser_download_url": "z"},
+                          {"name": "SHA256SUMS.txt", "browser_download_url": "s"}]}
+    assert updates.update_from_release(release, "FramePort-windows-x64.zip") is None  # automatic checks skip it
+    up = updates.update_from_release(release, "FramePort-windows-x64.zip", dev=True)
+    assert up.version == "0.9.1.dev57" and up.asset_url == "z" and up.sums_url == "s" and up.notes == "try X"
+    assert updates.update_from_release({**release, "assets": []}, dev=True) is None  # no wheel: no version
@@ -0,0 +1,43 @@
+"""USB cable link check (frame/usb.py): finding this PC's address on the Frame's USB network."""
+from types import SimpleNamespace
+
+from frameport.frame import usb
+
+
+def test_pc_usb_addresses_from_ipconfig(monkeypatch):
+    ipconfig = ("Ethernet adapter Ethernet 3:\n   IPv4 Address. . . . . . . . . . . : 10.86.200.234\n"
+                "Wireless LAN adapter Wi-Fi:\n   IPv4 Address. . . . . . . . . . . : 192.168.1.20\n")
+    monkeypatch.setattr(usb.subprocess, "run",
+                        lambda cmd, **k: SimpleNamespace(stdout=ipconfig if cmd[0] == "ipconfig" else ""))
+    assert usb.pc_usb_addresses("10.86.200.233") == ["10.86.200.234"]
+
+
+def test_pc_usb_addresses_ignores_broadcast(monkeypatch):
+    ip = "7: eth3    inet 10.86.200.234/29 brd 10.86.200.239 scope global eth3\n"
+    monkeypatch.setattr(usb.subprocess, "run", lambda cmd, **k: SimpleNamespace(stdout=ip if cmd[0] == "ip" else ""))
+    assert usb.pc_usb_addresses("10.86.200.233") == ["10.86.200.234"]
+
+
+def test_check_reports_missing_usb_link():
+    frame = SimpleNamespace(agent=lambda cmd, **k: {"present": False})
+    out = usb.check(frame)
+    assert out["notes"] and "usb0" in out["notes"][0]
+
+
+def test_discovered_frames_are_deduplicated_by_host_key():
+    from frameport.frame.discovery import Found, dedupe
+
+    found = [Found("frame", "192.168.1.30", source="devkit", addresses=["frame.local"]),
+             Found("192.168.1.30", "192.168.1.30", source="scan"),
+             Found("My Frame", "10.86.200.233", source="saved"),
+             Found("frame", "10.35.78.1", source="devkit"),
+             Found("other", "192.168.1.40", source="devkit")]
+    keys = {"192.168.1.30": "A", "10.86.200.233": "A", "10.35.78.1": "A", "192.168.1.40": "B"}
+    out = dedupe(found, key_of=lambda f: keys.get(f.host))
+    assert len(out) == 2
+    frame = next(f for f in out if f.host != "192.168.1.40")
+    assert frame.host == "10.86.200.233" and frame.via == "USB"  # the fastest link wins
+    assert frame.source == "devkit" and frame.name == "frame"  # the best-known source/name is kept
+    assert {"192.168.1.30", "10.35.78.1"} <= set(frame.addresses)
+    # an entry whose key can't be read isn't merged away
+    assert len(dedupe([Found("x", "1.2.3.4")], key_of=lambda f: None)) == 1
Author	SHA1	Message	Date
github-actions[bot]	4910440f56	catalog: com.resolutiongames.abvriop.santacruz (from #46 )	2026-10-05 21:57:44 +00:00
spoopyghosty0	44a056095d	Dashboard worker (agent v53) leaves a dashboard the player opened with the controller alone (v52 closed it 60 ms after each press, the game stayed paused); Into The Radius 2: focus_hold up to 2.5 s (the Frame dropped focus for 0.4 s and 1.0 s and Unreal paused each time), notes from the headset test	2026-10-05 15:58:50 -04:00
spoopyghosty0	6037b13e88	Dashboard at game start (agent v52): watch from the game's first submitted frame instead of the first pacing summary, which came ~8 s after Steam's "Resume game" menu (seen with Into The Radius 2); incremental log reads, 0.5 s checks	2026-10-05 15:46:54 -04:00
spoopyghosty0	c3a34ace99	Files, Screenshots and Library: right-click menus (Files and Screenshots; on one of several selected items they act on the whole selection) and click-and-drag multi-select in all three; selection bars moved below the lists so they don't shift items mid-drag; the Files row Download button works again (Flet never awaited it); ui_smoke --gestures drives real mouse drags and right-clicks	2026-10-05 15:43:06 -04:00
spoopyghosty0	05843633a7	Proton: the stable one is the default again (agent v51), Experimental suggested when a PC VR game fails; USB setup: "OR" between the two setup buttons and a Developer Mode pop-up first; tr_n crash in the catalog toast/Settings fixed; no "configs updated" toast on the first download	2026-10-05 14:55:23 -04:00
spoopyghosty0	5198f704e9	Game configs update without a release: installed apps fetch catalog/games from GitHub main every 6 h (one API call + changed files only; background, cache-only loading; Settings → Data: last check, Check now, off switch; `frameport catalog-update`). Configs that need a newer FramePort (unknown patch, adapter setting or field, or min_app above this version) are skipped	2026-10-05 14:31:21 -04:00
spoopyghosty0	eeee7d2b84	Merge pull request #43 from GreySyntax/patch-1 Add missing macOS file entitlement	2026-10-05 14:28:52 -04:00
spoopyghosty0	772c26d91a	Connect with a USB cable: wizard "Set up with a USB cable" (live cable detection; setup command over the cable via the Frame's fixed PC address 10.86.200.234; connects right away when already set up), discovered Frames de-duplicated by SSH host key preferring USB > Frame hotspot > network, USB check fixes. Verified on the device: NCM driver-free on Windows 11, DHCP from the Frame, Frame->PC over the cable, the real setup end to end over USB, 36.9 vs 11.3 MB/s, re-finding a lost address	2026-10-05 14:24:48 -04:00
spoopyghosty0	db0a78ccc3	FAQ: how to lay out games with OBB files (data folder named after the package, one folder per game)	2026-10-05 13:58:43 -04:00
spoopyghosty0	01d764e05c	scripts/usb_autotest.py: one autonomous USB-cable test (Windows adapters/driver/USB class via powershell.exe from WSL, the Frame's gadget units and NetworkManager setup, Frame -> PC over the cable, SSH + upload speed over USB vs Wi-Fi), Markdown report	2026-10-05 13:52:32 -04:00
spoopyghosty0	0c5c1638ed	USB cable link check: agent v50 `usb_link` (usb0 state/addresses, gadget functions, USB speed, DHCP from the Frame, sshd) and `frameport frame usb-check` (this PC's address on it, SSH over the cable with the same host key, upload speed vs the normal link) — for deciding on a USB connection option in the setup wizard	2026-10-05 13:41:41 -04:00
spoopyghosty0	a49cfb0b57	PC VR games default to Proton Experimental (agent v49), with Stable one click away: Customize shows the Proton version as a dropdown, and a launch test that fails on Experimental suggests "Try the stable Proton and reinstall". Installing asks again for the runtime Steam names only after Proton is installed	2026-10-05 13:35:26 -04:00
Jordan	0f975d2233	Add missing macOS file entitlement Without this entitlement the app is unable to show the file picker dialogue.	2026-10-05 16:27:38 +01:00
spoopyghosty0	ccff9ab486	FramePort 0.9.1	2026-10-05 08:42:45 -04:00
spoopyghosty0	f2cf7db507	Dev builds on demand: CI "Run workflow" (dev ticked, optional notes for testers) publishes the rolling `dev` pre-release with version <next patch>.dev<run>; Settings → Updates → "Install the latest dev build…" installs it like an update (automatic checks still ignore it; the next release is offered normally)	2026-10-05 08:30:05 -04:00
spoopyghosty0	2f740bbb41	Agent v48: incomplete deployment records (no base/appid) no longer break every connection with KeyError: 'base' (GitHub #40 ); the app logs unexpected connect errors with their traceback	2026-10-05 08:21:21 -04:00
spoopyghosty0	1462d3d471	FramePort 0.9.0	2026-10-05 00:10:17 -04:00
spoopyghosty0	22d10c1ff0	Merge the Linux apps GUI (Add games entries, Linux badge/filter, game page summary + missing-library warning, Frame-only actions, change program)	2026-10-05 00:09:42 -04:00
spoopyghosty0	8b9657b2e6	Frame power bar in the sidebar: Sleep / Restart / Shut down above the Frame card, each with a confirmation (agent v47 `power`: a user timer runs systemctl, since logind only allows it from the user's units). Restart verified on the device. ui_smoke: configurable port, power confirmation step	2026-10-05 00:07:16 -04:00
spoopyghosty0	bc6f6b7fe2	GUI for native arm64 Linux apps (GitHub #31 ): Add games -> Add a Linux app (arm64)... / folder (background job, opens the page), Linux badge + library platform filter, game page without recipe/patches (program + Change..., AppImage, OpenXR, source; missing-libraries callout), menus without conversion/recipe actions, Frame-only installs, Steam tags "Linux app on Frame"/"Linux", no Quest/Rift twins; safe local-file deletion for lone AppImages; Linux recipes don't follow the catalog; ui_smoke --linux	2026-10-05 00:06:12 -04:00
spoopyghosty0	8f3c8b33ba	README: Screenshots tab section with images	2026-10-04 23:57:22 -04:00
spoopyghosty0	8187c79d17	UI smoke: sample screenshots from the games' store screenshots (docs images of the Screenshots tab)	2026-10-04 23:54:59 -04:00
spoopyghosty0	2ecf7f8624	Merge the Screenshots tab (agent list/delete_screenshots, play-session log for attribution, PC cache + download, GUI tab); agent v46	2026-10-04 23:50:48 -04:00
spoopyghosty0	6200662bc7	Linux apps on the PC side (GitHub #31 ): analysis/linux.py (AppImage/folder/archive, aarch64 check with a clear x86_64 refusal, program ranking, OpenXR detection from the program and its own libraries), library kind "linux", install plan + upload, `frameport add-linux`. Verified end to end on the device (FramePort's arm64 build: upload, art, library check, Steam shortcut, launch test RUNNING, uninstall)	2026-10-04 23:49:42 -04:00
spoopyghosty0	d2c72264be	Screenshots tab: Steam screenshots on the Frame, matched to games by play session Agent v45: list_screenshots (screenshots.vdf + folders, every account; the Frame files headset shots under SteamVR 250820, so launch.sh now logs start/end to <anchor>/plays.log and upgrade_launchers adds it to existing launchers) and delete_screenshots (only images in userdata/<id>/760/remote/<appid>/screenshots, links refused, vdf left to Steam). PC: install/screenshots.py (thumbnail/full-image cache under screenshots-cache/<frame>, cancellable download). GUI: Screenshots nav item (grid by day, game filter, viewer with prev/next, multi-select download/delete), game menu entry; ui_smoke --fake-frame sample shots.	2026-10-04 23:47:08 -04:00
spoopyghosty0	f37f7be9c7	Agent: install arm64 Linux apps (GitHub #31 ; agent v45): prepare/finalize_linux (AppImages extracted once, missing shared libraries reported via ldd of the app's programs), launcher with the exit watchdog, Steam tag "Linux app on Frame", launch test, stop, uninstall. Verified on the device with an AppImage (Venera: libwebkit2gtk missing, reported) and a tar build (FramePort arm64: runs from Steam, Exit game, uninstall). The app no longer replaces a newer agent on the Frame (an older FramePort kept downgrading it)	2026-10-04 23:43:32 -04:00
spoopyghosty0	d05dd27971	Into The Radius 2 recipe: works with issues (flickering textures reported; space warp turned off with hide_space_warp, not yet confirmed in a headset) Closes #35	2026-10-04 23:34:01 -04:00
spoopyghosty0	fd478f4c70	Notes: space warp findings (Into The Radius 2), PR #34 , heuristics evaluation baseline	2026-10-04 23:28:06 -04:00
spoopyghosty0	d834ffac42	Heuristics: suggest AC Nexus's 90 Hz no-AppSW patch whenever it applies; Unreal Engine 5 games with Meta's plugin show hide_space_warp as an option (off) with the flicker hint	2026-10-04 23:27:14 -04:00
spoopyghosty0	3e11175001	Audio metadata fix: look for Meta's audio library at most once a second and stop once a different build was found (it rescanned every loaded library on every xrPollEvent in games without it)	2026-10-04 23:26:41 -04:00
spoopyghosty0	85a11061d0	Merge PR #34 : Meta XR Audio metadata lifetime fix for Batman: Arkham Shadow smoke bombs (Lucas-Mathieu); adapters rebuilt here	2026-10-04 23:26:27 -04:00
spoopyghosty0	e26cb8b0db	FrameBridge hide_space_warp (per game, off by default): hides XR_FB_space_warp and removes space warp info from the eye images; for games whose picture flickers with Application SpaceWarp (Into The Radius 2 under test; OVRPort's patch_disable_space_warp doesn't reach UE5)	2026-10-04 23:22:27 -04:00
spoopyghosty0	208d7bb4dd	Close SteamVR's dashboard once a FramePort game shows its first VR frames (it was open at every start, also over Lepton's 2D launcher): launch.sh starts the agent's dashboard helper, which uses Steam's UI (CEF devtools); existing launchers get it in place (agent v44)	2026-10-04 23:08:41 -04:00
spoopyghosty0	cf1a2c9181	launch.sh ends the game when Steam's reaper is gone (GitHub #36 : Exit game left Lepton running); existing launchers get the watchdog in place (agent v44); PLAYBOOK rows for the Steam library fallback and Exit game	2026-10-04 23:03:02 -04:00
spoopyghosty0	ba9ccc3606	FramePort 0.8.0	2026-10-04 21:39:55 -04:00
spoopyghosty0	83a614d645	Steam library fallback (GitHub #21/#30): when the Frame's Steam doesn't know FramePort's shortcut (Play: AppError_9), the game is added through Steam's devkit interface, live and without a restart, with its art; uninstall/purge remove it. Play reads Steam's AppError lines; diagnostics include Steam's shortcut log and devkit games (agent v43)	2026-10-04 21:38:50 -04:00
spoopyghosty0	5734c1fdee	Use your own artwork: choose an image file for a game's cover, wide cover, banner, logo or icon (game menu, or from Find artwork), checked and stored as the user's pick so automatic fetches keep it	2026-10-04 20:31:09 -04:00
spoopyghosty0	af791a45b4	FramePort 0.7.2	2026-10-04 20:23:58 -04:00
spoopyghosty0	11c8802b07	Remember the window position and maximized state (GitHub #32 ); diagnostics for Steam refusing FramePort's games (GitHub #21/#30): Play reports what Steam's log says about the launch, diagnostics include the Steam library state and Steam's launch log lines (agent v42)	2026-10-04 20:22:47 -04:00
Lucas-Mathieu	70d519a5a9	Fix Meta XR Audio metadata lifetime during Batman smoke effects	2026-10-05 01:50:57 +02:00
spoopyghosty0	4e00c88949	FramePort 0.7.1	2026-10-04 19:24:49 -04:00
spoopyghosty0	1b62d643f3	Notes: language packs verified with Deadpool VR (English dialogue with the patch on)	2026-10-04 19:23:33 -04:00
spoopyghosty0	6bd4eb523f	One job queue per process (Flet builds a new app per window session: an old session's job ran unseen and the same game was built twice at once in one work folder, both failed) and one build per game at a time	2026-10-04 19:23:32 -04:00
spoopyghosty0	d22123c657	Language packs: lint (line length, imports)	2026-10-04 19:23:32 -04:00
spoopyghosty0	0137cd993b	Language packs: ship libfp_langpack.so (built here), drop the dispatcher's late asset-list answer once we answered after the timeout (one answer per request), per-thread skip list, and games already in a library get their packs listed after an app update	2026-10-04 19:23:32 -04:00
yzfsoldier	7b8e7c2c5d	Opt-in frame.langpacks: serve <tag>.lang language packs from the game's files (PR #20 ) Some Quest games ship voice-over languages as <tag>.lang files and ask the Meta Platform SDK for them; overport's platform loader answers with nothing, so every language but the built-in one stays greyed out. libfp_langpack.so answers the language-pack and asset-file calls from the packs already on the device (Metadata = the game's versionName, the /storage/emulated/0 path spelling Unreal uses). Tested in the headset with Deadpool VR (German dialogue), AC Nexus and Asgard's Wrath 2.	2026-10-04 19:23:29 -04:00
spoopyghosty0	990331e5b6	WiiCompiled VR recipe: how to add a game (upload the .wcgame to its Import folder with the Files tab)	2026-10-04 18:32:29 -04:00
spoopyghosty0	56b370f582	WiiCompiled VR recipe: works with issues (no document picker in Lepton: manual .wcgame import; right eye jitters in races, inside the game's own OpenXR path)	2026-10-04 18:29:53 -04:00
spoopyghosty0	ac628cd284	FrameBridge: per-eye diagnostics (eye_debug: submitted vs fresh eye poses, eye-to-eye relation, release timing; also logged to framebridge.log because some games end Lepton's logcat early) and release_wait (wait for the game's GPU work before an image is released; 2 = A/B after 60 s)	2026-10-04 18:24:15 -04:00
spoopyghosty0	c12b2f6992	Steam art: games whose only art is the library's generated cover/banner get the placeholder set again (they got no Steam art at all, e.g. WiiCompiled)	2026-10-04 18:19:03 -04:00
spoopyghosty0	a110e8573f	QuestCraft recipe: works with issues (Java runtime missing on first start; Minecraft's graphics then fail with OpenGL error 1282)	2026-10-04 18:11:37 -04:00
spoopyghosty0	4fdeeaf829	FrameBridge emulates Android video panels (XR_KHR_android_surface_swapchain: I Am Monkey's intro, surface_emul); the launcher repairs save folders without group write (SUPERHOT quit at start, agent v41); SUPERHOT (Quest) and I Am Monkey recipes; Lucky's Tale's out-of-memory diagnosis	2026-10-04 18:07:22 -04:00