FramePort 0.9.1

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.

.github/workflows/build.yml

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

.gitignore

@@ -19,3 +19,4 @@ CLAUDE.local.md
 # outputs of `frameport report` / `parity` / ruff
 REPORT.md
 .ruff_cache/
+.claude/worktrees/

CLAUDE.md

@@ -21,7 +21,12 @@ 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).
     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
@@ -91,6 +96,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
@@ -498,6 +508,12 @@ DATA/ → external files/WiiCompiledOpenXRVR/DATA, MOD/ → .../RetroRewind6 (de
 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.
+**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).
 **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.
 
@@ -515,6 +531,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

README.md

@@ -28,6 +28,10 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V
   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
@@ -63,6 +67,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

agent/frameport_agent.py

@@ -6,7 +6,7 @@ The PC app uploads this file to ~/.local/share/frameport/agent/ and calls:
 
 Commands: info, prepare, finalize, shortcuts, shortcut_status, launch_test, stop, set_settings, uninstall,
           install_lepton, list_installed, proton_status, install_proton, prepare_pcvr, finalize_pcvr,
-          controller_models.
+          controller_models, list_screenshots, delete_screenshots (and more: see the cmd_* functions).
 Streaming: python3 frameport_agent.py _keyboard   (a virtual keyboard: JSON lines on stdin, see keyboard_session)
 
 Install layout (one Lepton container per game; same as the manual installs from 2026-09):
@@ -35,7 +35,7 @@ import sys
 import time
 import zlib
 
-AGENT_VERSION = 43
+AGENT_VERSION = 48
 HOME = os.path.expanduser("~")
 STEAM = os.path.join(HOME, ".local/share/Steam")
 ANCHORS = os.path.join(HOME, "Applications/quest-frame")
@@ -636,6 +636,12 @@ def ensure_host_fixes():
         with open(CONTAINERS_CONF, "w") as f:
             f.write(text)
         changed.append("podman keyring=false")
+    try:
+        upgraded = upgrade_launchers()
+    except Exception:  # noqa: BLE001
+        upgraded = []
+    if upgraded:
+        changed.append(f"launchers: exit watchdog, dashboard, play log ({len(upgraded)})")
     return changed
 
 
@@ -986,7 +992,9 @@ def shortcut_args(pkg):
     dep = json.load(open(os.path.join(anchor, "deployment.json")))
     icon = next(iter(glob.glob(os.path.join(anchor, "artwork/icon.*"))), "")
     flat = dep.get("vr") is False
-    tag = ("Windows game on Frame" if flat else "PC VR on Frame") if dep.get("kind") == "pcvr" else "Quest on Frame"
+    kind = dep.get("kind")
+    tag = ("Windows game on Frame" if flat else "PC VR on Frame") if kind == "pcvr" else \
+        "Linux app on Frame" if kind == "linux" else "Quest on Frame"
     return f'"{anchor}/launch.sh"', dep["title"], anchor, icon, tag, dep.get("tags") or [], not flat
 
 
@@ -1037,7 +1045,7 @@ def game_running():
     names = run(["podman", "ps", "--format", "{{.Names}}"]).stdout.split()
     if any(n.startswith("lepton-steamlaunch-") for n in names):
         return True
-    return any(pcvr_pids(d["base"]) for d in cmd_list_installed({})["games"] if d.get("kind") == "pcvr")
+    return any(pcvr_pids(d["base"]) for d in cmd_list_installed({})["games"] if d.get("kind") in ("pcvr", "linux"))
 
 
 def shortcuts_worker(payload):
@@ -1155,9 +1163,14 @@ def cmd_shortcut_status(args):
 def deployment(pkg):
     path = os.path.join(ANCHORS, pkg, "deployment.json")
     try:
-        return json.load(open(path))
+        dep = json.load(open(path))
     except (OSError, ValueError):
         return None
+    if not isinstance(dep, dict):
+        return None
+    dep.setdefault("base", os.path.dirname(path))
+    dep.setdefault("title", pkg)
+    return dep
 
 
 def cmd_list_installed(args):
@@ -1167,9 +1180,20 @@ def cmd_list_installed(args):
             dep = json.load(open(dep_path))
         except (OSError, ValueError):
             continue
+        # incomplete records (an interrupted install, another tool's files in this folder) are skipped or completed
+        # instead of failing every connection with a KeyError (GitHub #40)
+        if not isinstance(dep, dict) or not dep.get("package") or not dep.get("appid"):
+            continue
+        dep.setdefault("base", os.path.dirname(dep_path))
+        dep.setdefault("title", dep["package"])
         dep.setdefault("kind", "quest")
         dep["anchor"] = os.path.dirname(dep_path)  # its artwork/ feeds the Steam grid (shortcuts)
-        if dep["kind"] == "pcvr":
+        if dep["kind"] == "linux":
+            exe = os.path.join(dep["base"], "app", dep.get("exe", ""))
+            dep["apk_present"] = os.path.isfile(exe)
+            dep["apk_size"] = sum((dep.get("files") or {}).get("app", {}).values())
+            dep.pop("files", None)
+        elif dep["kind"] == "pcvr":
             exe = os.path.join(dep["base"], "game", dep.get("exe", ""))
             dep["apk_present"] = os.path.isfile(exe)
             dep["apk_size"] = sum((dep.get("files") or {}).get("game", {}).values())
@@ -1552,6 +1576,237 @@ def cmd_list_files(args):
     return {"roots": roots, "missing": missing[:1000], "truncated": truncated, "kind": dep.get("kind", "quest")}
 
 
+# ------------------------------------------------------------------------------------------ screenshots
+STEAMVR_APPID = "250820"  # the Frame files every headset screenshot under SteamVR, whatever game was shown
+PLAYS_LOG = "plays.log"  # <anchor>/plays.log: "start <unix>" / "end <unix>" lines written by launch.sh
+OPEN_SESSION = 12 * 3600  # a session without an "end" (Proton launchers exec the game; power loss) lasts at most this
+SESSION_GRACE = 5  # s after "end": the screenshot's time can trail the key press slightly
+SHOT_NAME = re.compile(r"^(\d{14})_\d+\.(jpe?g|png)$", re.I)
+KV_TOKEN = re.compile(r'"((?:[^"\\]|\\.)*)"|([{}])|//[^\n]*|([^\s"{}]+)')
+
+
+def kv_parse(text):
+    """Steam's text KeyValues (screenshots.vdf, ...) as nested dicts. Tolerant: an unbalanced or cut-off file gives
+    what was read so far."""
+    root, stack, key = {}, [], None
+    cur = root
+    for m in KV_TOKEN.finditer(text):
+        quoted, brace, bare = m.groups()
+        if brace == "{":
+            new = {}
+            if key is not None:
+                cur[key] = new
+            stack.append(cur)
+            cur, key = new, None
+        elif brace == "}":
+            if not stack:
+                break
+            cur, key = stack.pop(), None
+        elif quoted is not None or bare is not None:
+            tok = quoted.replace('\\"', '"').replace("\\\\", "\\") if quoted is not None else bare
+            if key is None:
+                key = tok
+            else:
+                cur[key], key = tok, None
+    return root
+
+
+def play_sessions():
+    """[(start, end, package)] from every FramePort game's plays.log, by start time. A start without an end (Proton
+    launchers exec the game, so they log no end; a crash or power loss) lasts until the next game's start (one game
+    runs at a time), at most OPEN_SESSION."""
+    events = []
+    for path in glob.glob(os.path.join(ANCHORS, "*", PLAYS_LOG)):
+        pkg = os.path.basename(os.path.dirname(path))
+        try:
+            lines = open(path, encoding="utf-8", errors="replace").read().splitlines()
+        except OSError:
+            continue
+        for line in lines:
+            parts = line.split()
+            if len(parts) >= 2 and parts[0] in ("start", "end") and parts[1].isdigit():
+                events.append((int(parts[1]), parts[0], pkg))
+    sessions, open_ = [], {}  # open_: pkg -> start
+    for t, kind, pkg in sorted(events):
+        if kind == "start":
+            if pkg in open_:  # an earlier start never ended: it ended by this one
+                sessions.append([open_[pkg], t, pkg])
+            open_[pkg] = t
+        elif pkg in open_:
+            sessions.append([open_.pop(pkg), t, pkg])
+    sessions += [[s, None, pkg] for pkg, s in open_.items()]
+    sessions.sort(key=lambda s: s[0])
+    for i, s in enumerate(sessions):
+        if s[1] is None:
+            later = [x[0] for x in sessions[i + 1:] if x[0] > s[0]]
+            s[1] = min([s[0] + OPEN_SESSION] + later)
+    return [tuple(s) for s in sessions]
+
+
+def session_game(t, sessions):
+    """Package whose play session contains time t (the latest start wins), else None."""
+    hit = None
+    for start, end, pkg in sessions:
+        if start <= t <= end + SESSION_GRACE:
+            hit = pkg
+    return hit
+
+
+def shot_time_from_name(name):
+    m = SHOT_NAME.match(name)
+    if not m:
+        return None
+    try:
+        return int(time.mktime(time.strptime(m[1], "%Y%m%d%H%M%S")))  # Steam names the files in local time
+    except (ValueError, OverflowError):
+        return None
+
+
+def _int(v):
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return None
+
+
+def user_screenshots(user):
+    """Every screenshot file of one Steam account: [{path, thumb, time, width, height, appid}]. screenshots.vdf gives
+    times and sizes; files it doesn't list (Steam writes it at exit) come from the folders, timed by their name."""
+    remote = os.path.join(STEAM, "userdata", user, "760", "remote")
+    shots, seen = [], set()
+
+    def under(rel):
+        p = os.path.normpath(os.path.join(remote, rel)) if isinstance(rel, str) else None
+        return p if p and p.startswith(remote + os.sep) and os.path.isfile(p) else None
+    try:
+        text = open(os.path.join(STEAM, "userdata", user, "760", "screenshots.vdf"), encoding="utf-8",
+                    errors="replace").read()
+    except OSError:
+        text = ""
+    entries = (kv_parse(text).get("screenshots") or {})
+    for game in entries.values() if isinstance(entries, dict) else ():
+        for e in game.values() if isinstance(game, dict) else ():
+            path = under(e.get("filename")) if isinstance(e, dict) else None
+            if not path or path in seen:
+                continue  # deleted (Steam lists it until it rewrites the file)
+            seen.add(path)
+            shots.append({"path": path, "thumb": under(e.get("thumbnail")),
+                          "time": _int(e.get("creation")) or shot_time_from_name(os.path.basename(path)),
+                          "width": _int(e.get("width")), "height": _int(e.get("height")),
+                          "appid": os.path.relpath(path, remote).split(os.sep)[0]})
+    for path in sorted(glob.glob(os.path.join(remote, "*", "screenshots", "*"))):
+        name = os.path.basename(path)
+        if path in seen or not SHOT_NAME.match(name) or not os.path.isfile(path):
+            continue
+        thumb = os.path.join(os.path.dirname(path), "thumbnails", name)
+        shots.append({"path": path, "thumb": thumb if os.path.isfile(thumb) else None,
+                      "time": shot_time_from_name(name) or int(os.path.getmtime(path)), "width": None,
+                      "height": None, "appid": os.path.relpath(path, remote).split(os.sep)[0]})
+    return shots
+
+
+def shortcut_names(user):
+    """{shortcut appid (str): name} of an account's non-Steam shortcuts."""
+    try:
+        data = vdf_decode(open(os.path.join(STEAM, "userdata", user, "config", "shortcuts.vdf"), "rb").read())
+    except (OSError, ValueError, IndexError, struct.error, AgentError):
+        return {}
+    out = {}
+    for e in (data.get("shortcuts") or {}).values():
+        if isinstance(e, dict) and isinstance(e.get("appid"), int):
+            out[str(e["appid"] & 0xFFFFFFFF)] = e.get("AppName") or e.get("appname") or ""
+    return out
+
+
+def cmd_list_screenshots(args):
+    """Steam screenshots on the Frame (every account), newest first: {shots: [{path, thumb, time, width, height, size,
+    account, appid, package, title}], total, games: [{package, title, count}]}. The Frame files every headset
+    screenshot under SteamVR (250820), so those are matched to the FramePort game whose play session (plays.log)
+    contains their time; the rest stay "SteamVR" (package null). args: offset, limit, package (a package, or "" for
+    the shots of no FramePort game); `total` and `games` count before offset/limit."""
+    titles, by_appid = {}, {}
+    for dep_path in glob.glob(os.path.join(ANCHORS, "*/deployment.json")):
+        try:
+            dep = json.load(open(dep_path))
+        except (OSError, ValueError):
+            continue
+        pkg = os.path.basename(os.path.dirname(dep_path))
+        titles[pkg] = dep.get("title") or pkg
+        if dep.get("appid") is not None:
+            by_appid[str(int(dep["appid"]) & 0xFFFFFFFF)] = pkg
+    sessions = play_sessions()
+    shots, names = [], {}
+    for user in steam_users():
+        names.update(shortcut_names(user))
+        for s in user_screenshots(user):
+            pkg = by_appid.get(s["appid"])
+            if pkg is None and s["appid"] == STEAMVR_APPID and s["time"]:
+                pkg = session_game(s["time"], sessions)
+            if pkg:
+                title = titles.get(pkg, pkg)
+            elif s["appid"] == STEAMVR_APPID:
+                title = "SteamVR"
+            else:
+                app = find_app_id(s["appid"]) if s["appid"] not in names else None
+                title = names.get(s["appid"]) or (app or {}).get("name") or f"App {s['appid']}"
+            try:
+                size = os.path.getsize(s["path"])
+            except OSError:
+                continue
+            shots.append({**s, "size": size, "account": user, "package": pkg, "title": title})
+    shots.sort(key=lambda s: (-(s["time"] or 0), s["path"]))
+    games = {}
+    for s in shots:
+        g = games.setdefault(s["package"] or s["title"], {"package": s["package"], "title": s["title"], "count": 0})
+        g["count"] += 1
+    want = args.get("package")
+    if want is not None:
+        shots = [s for s in shots if (s["package"] or "") == want]
+    offset = max(0, int(args.get("offset") or 0))
+    limit = int(args.get("limit") or 0)
+    return {"shots": shots[offset:offset + limit] if limit > 0 else shots[offset:], "total": len(shots),
+            "games": sorted(games.values(), key=lambda g: g["title"].lower())}
+
+
+def screenshot_file(path):
+    """`path` if it is a screenshot image in a Steam account's screenshot folder (userdata/<id>/760/remote/<appid>/
+    screenshots/<name>), else AgentError. Links and '..' are refused: nothing outside those folders can be deleted."""
+    if not isinstance(path, str) or "\0" in path or not path.startswith("/"):
+        raise AgentError(f"not a screenshot: {path!r}")
+    norm = os.path.normpath(path)
+    parts = os.path.relpath(norm, os.path.join(STEAM, "userdata")).split(os.sep)
+    if (norm != path or len(parts) != 6 or not parts[0].isdigit() or parts[1:3] != ["760", "remote"]
+            or not parts[3].isdigit() or parts[4] != "screenshots" or not SHOT_NAME.match(parts[5])):
+        raise AgentError(f"not a screenshot: {path}")
+    if os.path.islink(norm) or not os.path.isfile(norm) or not inside_userdata(os.path.dirname(norm)):
+        raise AgentError(f"not a screenshot file: {path}")
+    return norm
+
+
+def inside_userdata(folder):
+    """The folder, links resolved, is inside Steam's userdata (a linked screenshots folder could point anywhere)."""
+    return os.path.realpath(folder).startswith(os.path.realpath(os.path.join(STEAM, "userdata")) + os.sep)
+
+
+def cmd_delete_screenshots(args):
+    """Delete screenshots (+ their thumbnails); only image files in Steam's screenshot folders (screenshot_file; every
+    path is checked before anything is deleted). screenshots.vdf is left alone: Steam keeps it in memory and rewrites
+    it at exit, so an edit would be lost; Steam drops entries whose file is gone, list_screenshots skips them. Steam's
+    own screenshot list may show the deleted ones until Steam restarts."""
+    paths = [screenshot_file(p) for p in args.get("paths") or []]
+    deleted = []
+    for p in paths:
+        os.unlink(p)
+        deleted.append(p)
+        thumbs = os.path.join(os.path.dirname(p), "thumbnails")
+        if inside_userdata(thumbs):
+            try:
+                os.unlink(os.path.join(thumbs, os.path.basename(p)))
+            except FileNotFoundError:
+                pass
+    return {"deleted": deleted}
+
+
 def cmd_prepare(args):
     """Where to upload, and what the Frame already has (so unchanged data is not re-sent)."""
     pkg = check_pkg(args["package"])
@@ -1603,7 +1858,7 @@ r""" here.
 mkdir -p "$app_dir/lepton-data/external/Android/data/{pkg}/files" """
 r""""$app_dir/lepton-data/external/Android/data/{pkg}/cache" 2>/dev/null || true
 fix_perms
-( while sleep 2 && kill -0 $$ 2>/dev/null; do fix_perms; done ) & permfix=$!
+{watchdog}
 export SteamAppId={appid}
 export STEAM_COMPAT_INSTALL_PATH="$app_dir/lepton-app"
 export STEAM_COMPAT_DATA_PATH="$app_dir/lepton-data"
@@ -1620,21 +1875,84 @@ stop() {{
     kill $permfix 2>/dev/null || true
     [[ -n "$child" ]] && kill -TERM -- "-$child" 2>/dev/null || true
     podman kill "lepton-steamlaunch-$SteamAppId" >/dev/null 2>&1 || true
+    {plays_end}
 }}
 trap stop EXIT
 trap 'exit 130' INT
 trap 'exit 143' TERM
+{plays_start}
 setsid {lepton_q} start >"$app_dir/launch.log" 2>&1 &
 child=$!
+{dashboard}
 wait "$child"
 """)
 
 
+# Every 2 s: repair folder permissions, and end the game when whoever started this launcher is gone. Steam starts it
+# under its "reaper"; when Steam stops only the reaper (seen: SIGTERM to the reaper left launch.sh, Lepton and the
+# container running), the game used to keep running with nothing in Steam to close it (GitHub #36).
+OLD_WATCHDOG = "( while sleep 2 && kill -0 $$ 2>/dev/null; do fix_perms; done ) & permfix=$!"
+# SteamVR's dashboard (Resume game / controller / VR options) is open when a FramePort game starts and has to be closed
+# by hand (also when Lepton shows its Android launcher first). Once the game's first VR frames are logged, the agent
+# closes it through Steam's UI (_dashboard_worker); opt out per game with FRAMEPORT_KEEP_DASHBOARD=1.
+DASHBOARD_LINE = ('[[ -n "${{FRAMEPORT_KEEP_DASHBOARD:-}}" ]] || python3 {agent_q} _dashboard_worker '
+                  '"$app_dir/launch.log" $$ >"$app_dir/dashboard.log" 2>&1 &')
+WATCHDOG = ("parent=$PPID\n"
+            "( while sleep 2 && kill -0 $$ 2>/dev/null; do fix_perms;"
+            " if [[ $parent -gt 1 ]] && ! kill -0 $parent 2>/dev/null; then kill -TERM $$; fi; done ) & permfix=$!")
+
+
+def dashboard_line():
+    return DASHBOARD_LINE.format(agent_q=shlex.quote(os.path.abspath(__file__)))
+
+
+def plays_lines(anchor):
+    """launch.sh lines that log play sessions to <anchor>/plays.log (screenshots are matched to games by time: the
+    Frame files every headset screenshot under SteamVR). Never fail the launcher."""
+    q = shlex.quote(os.path.join(anchor, PLAYS_LOG))
+    return (f'echo "start $(date +%s)" >>{q} 2>/dev/null || true',
+            f'echo "end $(date +%s)" >>{q} 2>/dev/null || true')
+
+
+def upgrade_launchers():
+    """Give launchers written by older agents the parent watchdog, the dashboard closer and the play-session log (in
+    place: a new file, so a running launcher keeps reading the old one). Returns the packages changed."""
+    changed = []
+    for path in glob.glob(os.path.join(ANCHORS, "*/launch.sh")):
+        try:
+            text = open(path).read()
+        except OSError:
+            continue
+        new = text
+        if OLD_WATCHDOG in new and "parent=$PPID" not in new:
+            new = new.replace(OLD_WATCHDOG, WATCHDOG, 1)
+        if "_dashboard_worker" not in new and 'child=$!\nwait "$child"' in new:
+            new = new.replace('child=$!\nwait "$child"', 'child=$!\n' + dashboard_line() + '\nwait "$child"', 1)
+        if PLAYS_LOG not in new:
+            start, end = plays_lines(os.path.dirname(path))
+            if "\nsetsid " in new and "\n    trap - EXIT INT TERM\n" in new:  # Lepton launcher
+                new = new.replace("\nsetsid ", f"\n{start}\nsetsid ", 1)
+                new = new.replace("\n    trap - EXIT INT TERM\n", f"\n    trap - EXIT INT TERM\n    {end}\n", 1)
+            elif "\nexec " in new:  # Proton launcher: exec replaces the shell, so only the start is logged
+                new = new.replace("\nexec ", f"\n{start}\nexec ", 1)
+        if new == text:
+            continue
+        tmp = path + ".tmp"
+        with open(tmp, "w") as f:
+            f.write(new)
+        os.chmod(tmp, os.stat(path).st_mode)
+        os.replace(tmp, path)
+        changed.append(os.path.basename(os.path.dirname(path)))
+    return changed
+
+
 def write_launcher(anchor, base, pkg, title, appid, lepton, env):
     extra = "".join(f"export {k}={shlex.quote(str(v))}\n" for k, v in (env or {}).items()
                     if re.fullmatch(r"[A-Z_][A-Z0-9_]*", k))
     text = LAUNCH_SH.format(title=title.replace("\n", " "), pkg=pkg, base_q=shlex.quote(base), appid=appid,
-                            lepton_q=shlex.quote(lepton), extra_env=extra)
+                            lepton_q=shlex.quote(lepton), extra_env=extra, watchdog=WATCHDOG,
+                            dashboard=dashboard_line(), plays_start=plays_lines(anchor)[0],
+                            plays_end=plays_lines(anchor)[1])
     path = os.path.join(anchor, "launch.sh")
     with open(path + ".tmp", "w") as f:
         f.write(text)
@@ -2117,6 +2435,7 @@ fi
 mkdir -p "$STEAM_COMPAT_DATA_PATH" "$STEAM_COMPAT_SHADER_PATH"
 cd "$base/game"{workdir}
 echo "FramePort: launching {pkg} with {tool}" >"$base/launch.log"
+{plays_start}
 exec {command} >>"$base/launch.log" 2>&1
 """
 
@@ -2184,7 +2503,7 @@ def write_proton_launcher(anchor, base, pkg, title, appid, tool, exe_rel, revive
         tool=tool["name"], extra_env=extra, workdir=("/" + shlex.quote(workdir)) if workdir else "",
         # Proton sets up VR (vrclient, wineopenxr) only when SteamGameId is set: a flat Windows game goes without
         steam_game_id=f"export SteamGameId={appid}\n" if vr else "",
-        xr_layer=XR_LAYER_ENV if xr_layer else "",
+        xr_layer=XR_LAYER_ENV if xr_layer else "", plays_start=plays_lines(anchor)[0],
         command=" ".join(shlex.quote(a) for a in argv))
     path = os.path.join(anchor, "launch.sh")
     with open(path + ".tmp", "w") as f:
@@ -2314,6 +2633,192 @@ def cmd_finalize_pcvr(args):
     return {"ok": True, "base": base, "appid": appid, "moved_files": moved, "proton": tool["name"]}
 
 
+# ------------------------------------------------------------------------------------------ Linux apps (arm64)
+# Native arm64 Linux programs (AppImages, zip/tar builds) installed from FramePort (GitHub #31): files in
+# <base>/app, AppImages extracted once (no FUSE in Steam's launch environment needed, faster start), a launcher with
+# the same exit watchdog as the Quest launcher, and a Steam shortcut (VR flag for OpenXR apps).
+LINUX_LAUNCH_SH = r"""#!/usr/bin/env bash
+# Steam Frame launcher for {title} ({pkg}), a Linux app. Generated by FramePort.
+set -uo pipefail
+cd {run_dir_q} || {{ echo "App files missing at {run_dir_q}" >&2; exit 1; }}
+export XDG_RUNTIME_DIR="${{XDG_RUNTIME_DIR:-/run/user/$(id -u)}}"
+# Steam passes the display session (gamescope's X/Wayland); headless launches (launch tests) take it from Steam
+if [[ -z "${{DISPLAY:-}}" ]]; then
+    steam_pid=$(pgrep -x steam | head -n1 || true)
+    if [[ -n "$steam_pid" && -r "/proc/$steam_pid/environ" ]]; then
+        while IFS= read -r -d '' kv; do
+            case "$kv" in DISPLAY=*|WAYLAND_DISPLAY=*|GAMESCOPE_WAYLAND_DISPLAY=*|XAUTHORITY=*|XDG_SESSION_TYPE=*)
+                export "$kv";; esac
+        done < "/proc/$steam_pid/environ"
+    fi
+fi
+{extra_env}parent=$PPID
+{exe_q} "$@" >{log_q} 2>&1 &
+child=$!
+trap 'kill -TERM $child 2>/dev/null' INT TERM
+( while sleep 2 && kill -0 $child 2>/dev/null; do
+    if [[ $parent -gt 1 ]] && ! kill -0 $parent 2>/dev/null; then kill -TERM $child; fi; done ) &
+wait $child
+"""
+
+
+def linux_run_target(base, exe_rel, appimage):
+    """(working directory, program) for a Linux app: an extracted AppImage runs its AppRun."""
+    if appimage:  # absolute paths: the agent finds the app's processes by its folder in their command lines
+        root = os.path.join(base, "app", "squashfs-root")
+        return root, os.path.join(root, "AppRun")
+    path = os.path.join(base, "app", exe_rel)
+    return os.path.dirname(path), path
+
+
+def missing_libraries(root, programs):
+    """Shared libraries the app's main programs need (ldd follows their dependencies) that neither the Frame nor the
+    app itself has, with the app's own library folders on LD_LIBRARY_PATH as AppImages' AppRun sets it: e.g.
+    libwebkit2gtk-4.1 for Venera. Only the programs that start, not every bundled module (FramePort's own build
+    ships optional Python modules needing libjvm/libtcl that never load)."""
+    libdirs = set()
+    for dirpath, _dirs, files in os.walk(root):
+        if any(".so" in n for n in files):
+            libdirs.add(dirpath)
+    env = dict(os.environ, LD_LIBRARY_PATH=":".join(sorted(libdirs)))
+    missing = set()
+    for path in programs:
+        p = subprocess.run(["ldd", path], capture_output=True, text=True, env=env, timeout=30)
+        for line in p.stdout.splitlines():
+            if "=> not found" in line:
+                missing.add(line.split("=>")[0].strip())
+    return sorted(missing)
+
+
+def appimage_programs(root):
+    """The ELF programs an extracted AppImage starts: top-level and usr/bin executables (not libraries)."""
+    out = []
+    for d in (root, os.path.join(root, "usr", "bin")):
+        try:
+            names = sorted(os.listdir(d))
+        except OSError:
+            continue
+        for name in names:
+            path = os.path.join(d, name)
+            if ".so" in name or not os.path.isfile(path) or not os.access(path, os.X_OK):
+                continue
+            try:
+                with open(path, "rb") as f:
+                    if f.read(4) == b"\x7fELF":
+                        out.append(path)
+            except OSError:
+                pass
+    return out
+
+
+def cmd_prepare_linux(args):
+    """Where to upload a Linux app, and what the Frame already has (unchanged files aren't re-sent)."""
+    pkg = check_pkg(args["package"])
+    anchor = os.path.join(ANCHORS, pkg)
+    dep = deployment(pkg)
+    base = dep["base"] if dep else anchor
+    appid = dep["appid"] if dep else shortcut_appid(f'"{anchor}/launch.sh"', args["title"])
+    if dep and pcvr_pids(base):
+        raise AgentError(f"{args['title']} is running on the Frame. Close it first.")
+    incoming = os.path.join(base, "incoming")
+    os.makedirs(os.path.join(incoming, "app"), exist_ok=True)
+    existing = {"app": {**tree_manifest(os.path.join(base, "app")), **tree_manifest(os.path.join(incoming, "app"))}}
+    existing["app"] = {k: v for k, v in existing["app"].items() if not k.startswith("squashfs-root/")}
+    st = os.statvfs(base if os.path.exists(base) else HOME)
+    return {"package": pkg, "base": base, "anchor": anchor, "appid": appid, "incoming": incoming,
+            "installed": bool(dep), "existing": existing, "free_bytes": st.f_bavail * st.f_frsize}
+
+
+def cmd_finalize_linux(args):
+    """Move the uploaded app into place (files the new version lacks are deleted), extract an AppImage, check its
+    libraries, write the launcher and deployment.json."""
+    pkg = check_pkg(args["package"])
+    title = args["title"]
+    prep = cmd_prepare_linux({"package": pkg, "title": title})
+    base, anchor, appid, incoming = prep["base"], prep["anchor"], prep["appid"], prep["incoming"]
+    exe_rel = os.path.normpath(args["exe"])
+    if exe_rel.startswith("..") or os.path.isabs(exe_rel):
+        raise AgentError(f"bad program path {args['exe']!r}")
+    app = os.path.join(base, "app")
+    want = (args.get("manifests") or {}).get("app")
+    old = ((deployment(pkg) or {}).get("files") or {}).get("app") or {}
+    moved = 0
+    for rel in tree_manifest(os.path.join(incoming, "app")):
+        dst = os.path.join(app, rel)
+        os.makedirs(os.path.dirname(dst), exist_ok=True)
+        os.replace(os.path.join(incoming, "app", rel), dst)
+        moved += 1
+    if want is not None:
+        for rel in set(old) - set(want):
+            p = os.path.normpath(os.path.join(app, rel))
+            if p.startswith(app + os.sep) and os.path.isfile(p):
+                os.remove(p)
+        have = tree_manifest(app)
+        bad = [k for k, v in want.items() if have.get(k) != v]
+        if bad:
+            raise AgentError(f"{len(bad)} app file(s) missing or incomplete, e.g. {bad[0]}")
+    exe = os.path.join(app, exe_rel)
+    if not os.path.isfile(exe):
+        raise AgentError(f"program {exe_rel} missing after upload")
+    shutil.rmtree(incoming, ignore_errors=True)
+    os.chmod(exe, os.stat(exe).st_mode | 0o111)
+    appimage = bool(args.get("appimage"))
+    if appimage:
+        shutil.rmtree(os.path.join(app, "squashfs-root"), ignore_errors=True)
+        p = subprocess.run([exe, "--appimage-extract"], cwd=app, capture_output=True, text=True, timeout=600)
+        if not os.path.isfile(os.path.join(app, "squashfs-root", "AppRun")):
+            raise AgentError(f"couldn't unpack the AppImage: {(p.stderr or p.stdout).strip()[-300:]}")
+    run_dir, program = linux_run_target(base, exe_rel, appimage)
+    for name in args.get("executables") or []:  # other programs the app starts (archives may lose the x bit)
+        q = os.path.normpath(os.path.join(app, name))
+        if q.startswith(app + os.sep) and os.path.isfile(q):
+            os.chmod(q, os.stat(q).st_mode | 0o111)
+    missing = missing_libraries(app, appimage_programs(run_dir) if appimage else [exe])
+    os.makedirs(anchor, exist_ok=True)
+    extra = "".join(f"export {k}={shlex.quote(str(v))}\n" for k, v in (args.get("env") or {}).items()
+                    if re.fullmatch(r"[A-Z_][A-Z0-9_]*", k))
+    text = LINUX_LAUNCH_SH.format(title=title.replace("\n", " "), pkg=pkg, run_dir_q=shlex.quote(run_dir),
+                                  exe_q=shlex.quote(program), log_q=shlex.quote(os.path.join(base, "launch.log")),
+                                  extra_env=extra)
+    path = os.path.join(anchor, "launch.sh")
+    with open(path + ".tmp", "w") as f:
+        f.write(text)
+    os.chmod(path + ".tmp", 0o755)
+    os.replace(path + ".tmp", path)
+    art_in = os.path.join(base, "incoming-artwork")
+    if os.path.isdir(art_in):
+        shutil.rmtree(os.path.join(anchor, "artwork"), ignore_errors=True)
+        shutil.move(art_in, os.path.join(anchor, "artwork"))
+    vr = bool(args.get("openxr"))
+    dep = {"package": pkg, "kind": "linux", "appid": int(appid), "base": base, "title": title, "exe": exe_rel,
+           "appimage": appimage, "vr": vr, "tags": args.get("tags") or [], "sha256": args.get("exe_sha256"),
+           "missing_libraries": missing, "recipe": args.get("recipe"), "installed_by": "frameport",
+           "files": {"app": want or {}}, "agent_version": AGENT_VERSION, "time": time.time()}
+    with open(os.path.join(anchor, "deployment.json"), "w") as f:
+        json.dump(dep, f, indent=2)
+    return {"ok": True, "base": base, "appid": appid, "moved_files": moved, "missing_libraries": missing}
+
+
+POWER_ACTIONS = {"sleep": "suspend", "restart": "reboot", "shutdown": "poweroff"}
+
+
+def cmd_power(args):
+    """Put the Frame to sleep, restart or shut it down (the app's power button). logind only allows these from the
+    user's own units ("yes"), not an SSH session ("challenge" = a password prompt), so a transient user timer runs
+    systemctl a few seconds later: this command answers first. A running game is refused unless force."""
+    action = args.get("action")
+    if action not in POWER_ACTIONS:
+        raise AgentError(f"unknown power action {action!r}")
+    if game_running() and not args.get("force"):
+        raise AgentError("a game is running on the Frame")
+    delay = max(2, min(int(args.get("delay", 3)), 60))
+    p = run(["systemd-run", "--user", "--collect", "--quiet", f"--unit=frameport-power-{int(time.time())}",
+             f"--on-active={delay}", "systemctl", POWER_ACTIONS[action]])
+    if p.returncode:
+        raise AgentError(f"couldn't {action}: {(p.stderr or p.stdout).strip()[-300:]}")
+    return {"action": action, "in_seconds": delay}
+
+
 AWAKE_UNIT = "frameport-awake"
 
 
@@ -2372,10 +2877,12 @@ def cmd_uninstall(args):
         return {"removed": False}
     base = dep["base"]
     pcvr = dep.get("kind") == "pcvr"
-    if (pcvr_pids(base) if pcvr else container_running(dep["appid"])):
+    linux = dep.get("kind") == "linux"
+    if (pcvr_pids(base) if pcvr or linux else container_running(dep["appid"])):
         raise AgentError("the game is running")
     keep_data = args.get("keep_data", True)
     names = ("game", "revive", "xrlayer", "shadercache", "incoming", "incoming-artwork") if pcvr else \
+        ("app", "incoming", "incoming-artwork", "launch.log") if linux else \
         ("lepton-app", "lepton-shaders", "incoming", "previous-game.apk")
     for name in names:
         p = os.path.join(base, name)
@@ -2411,6 +2918,9 @@ def cmd_stop(args):
         run(["systemctl", "--user", "stop", f"frameport-test-{dep['appid']}"])
         if dep.get("kind") == "pcvr":
             stop_pcvr(dep)
+        elif dep.get("kind") == "linux":
+            for pid in pcvr_pids(dep["base"]):
+                run(["kill", "-TERM", pid])
         else:
             run(["podman", "kill", f"lepton-steamlaunch-{dep['appid']}"])
     return {"stopped": bool(dep)}
@@ -2470,6 +2980,8 @@ def cmd_launch_test(args):
     appid = dep["appid"]
     if dep.get("kind") == "pcvr":
         return launch_test_pcvr(dep, anchor, log, seconds)
+    if dep.get("kind") == "linux":
+        return launch_test_linux(dep, anchor, log, seconds)
     if container_running(appid):
         raise AgentError("the game is already running")
     ensure_host_fixes()
@@ -2508,6 +3020,40 @@ def cmd_launch_test(args):
             "kernel_keys_before": keys, "kernel_keys_after": key_usage()}
 
 
+def launch_test_linux(dep, anchor, log, seconds):
+    """Start a Linux app headless (the launcher borrows Steam's display) and see whether it stays up."""
+    base, appid = dep["base"], dep["appid"]
+    if pcvr_pids(os.path.join(base, "app")):
+        raise AgentError("the app is already running")
+    unit = f"frameport-test-{appid}"
+    run(["systemctl", "--user", "reset-failed", unit])
+    start = time.time()
+    p = run(["systemd-run", "--user", "--quiet", f"--unit={unit}", "--property=RemainAfterExit=no",
+             os.path.join(anchor, "launch.sh")])
+    if p.returncode:
+        raise AgentError("could not start the launcher: " + p.stderr[-300:])
+    state, seen = "RUNNING", False
+    while time.time() - start < seconds:
+        time.sleep(2)
+        seen = seen or bool(pcvr_pids(os.path.join(base, "app")))
+        if run(["systemctl", "--user", "is-active", "--quiet", unit]).returncode:
+            state = "EXITED" if seen else "NEVER_STARTED"
+            break
+    elapsed = round(time.time() - start)
+    run(["systemctl", "--user", "stop", unit])
+    for pid in pcvr_pids(os.path.join(base, "app")):
+        run(["kill", "-TERM", pid])
+    combined = os.path.join(base, "launch-test.log")
+    text = open(log, errors="replace").read()[-400000:] if os.path.exists(log) else ""
+    missing = dep.get("missing_libraries") or []
+    with open(combined, "w") as f:
+        if missing:
+            f.write("FramePort: libraries missing on the Frame: " + ", ".join(missing) + "\n")
+        f.write(text)
+    return {"state": state, "elapsed": elapsed, "log": combined, "log_size": os.path.getsize(combined),
+            "kind": "linux", "game_process": seen, "missing_libraries": missing}
+
+
 def launch_test_pcvr(dep, anchor, log, seconds):
     base, appid = dep["base"], dep["appid"]
     if pcvr_pids(base):
@@ -2733,7 +3279,8 @@ def cmd_purge(args):
     Proton self-test prefix, timefix layer). Runs detached (Steam is closed while shortcuts.vdf changes); poll
     purge_status. Proton/Lepton stay installed (they're Steam apps) and the podman keyring fix stays (harmless)."""
     games = cmd_list_installed({})["games"]
-    if any((pcvr_pids(d["base"]) if d.get("kind") == "pcvr" else container_running(d["appid"])) for d in games):
+    if any((pcvr_pids(d["base"]) if d.get("kind") in ("pcvr", "linux") else container_running(d["appid"]))
+           for d in games):
         raise AgentError("a FramePort game is running on the Frame; close it first")
     status = os.path.join(HOME, ".cache/frameport-purge.json")
     os.makedirs(os.path.dirname(status), exist_ok=True)
@@ -2976,6 +3523,85 @@ def keyboard_session(stdin, stdout, keyboard=None):
     return 0
 
 
+def steam_js(expression, timeout=5):
+    """Evaluate JavaScript in Steam's UI (SharedJSContext) through its CEF devtools port (127.0.0.1:8080, SteamOS
+    starts Steam with -cef-enable-debugging); returns the value. A minimal websocket client (stdlib only)."""
+    import base64
+    import socket
+    import urllib.request
+
+    targets = json.load(urllib.request.urlopen("http://127.0.0.1:8080/json", timeout=timeout))
+    url = next(t["webSocketDebuggerUrl"] for t in targets if t.get("title") == "SharedJSContext")
+    path = url.split("127.0.0.1:8080", 1)[1]
+    with socket.create_connection(("127.0.0.1", 8080), timeout=timeout) as sock:
+        key = base64.b64encode(os.urandom(16)).decode()
+        sock.sendall((f"GET {path} HTTP/1.1\r\nHost: 127.0.0.1:8080\r\nUpgrade: websocket\r\n"
+                      f"Connection: Upgrade\r\nSec-WebSocket-Key: {key}\r\nSec-WebSocket-Version: 13\r\n\r\n").encode())
+        head = b""
+        while b"\r\n\r\n" not in head:
+            chunk = sock.recv(1)
+            if not chunk:
+                raise AgentError("Steam's devtools closed the connection")
+            head += chunk
+        data = json.dumps({"id": 1, "method": "Runtime.evaluate",
+                           "params": {"expression": expression, "awaitPromise": True,
+                                      "returnByValue": True}}).encode()
+        mask, n = os.urandom(4), len(data)
+        size = bytes([0x80 | n]) if n < 126 else bytes([0x80 | 126]) + struct.pack(">H", n)
+        sock.sendall(b"\x81" + size + mask + bytes(b ^ mask[i % 4] for i, b in enumerate(data)))
+
+        def exact(k):
+            buf = b""
+            while len(buf) < k:
+                chunk = sock.recv(k - len(buf))
+                if not chunk:
+                    raise AgentError("Steam's devtools closed the connection")
+                buf += chunk
+            return buf
+        while True:
+            _b1, b2 = exact(2)
+            k = b2 & 0x7F
+            k = struct.unpack(">H", exact(2))[0] if k == 126 else struct.unpack(">Q", exact(8))[0] if k == 127 else k
+            msg = json.loads(exact(k).decode("utf-8", "replace") or "{}")
+            if msg.get("id") == 1:
+                res = (msg.get("result") or {}).get("result") or {}
+                return res.get("value")
+
+
+def dashboard_worker(log, parent, wait_start=240, window=25):
+    """Close SteamVR's dashboard once the game's first VR frames are logged (FrameBridge's "pacing:" line), checking
+    for `window` seconds after that (Steam can open it a moment later; at most 3 times). Ends with the launcher."""
+    def alive():
+        try:
+            os.kill(int(parent), 0)
+            return True
+        except (OSError, ValueError):
+            return False
+    deadline = time.time() + wait_start
+    while time.time() < deadline and alive():
+        try:
+            with open(log, "rb") as f:
+                if b"FrameBridge: pacing:" in f.read():
+                    break
+        except OSError:
+            pass
+        time.sleep(1)
+    else:
+        print("no VR frames logged; dashboard left as it is")
+        return
+    hidden, end = 0, time.time() + window
+    while time.time() < end and hidden < 3 and alive():
+        try:
+            if steam_js("SteamClient.OpenVR.VROverlay.IsDashboardVisible()"):
+                steam_js("SteamClient.OpenVR.VROverlay.HideDashboard()")
+                hidden += 1
+                print(f"{time.strftime('%H:%M:%S')} dashboard hidden")
+        except Exception as exc:  # noqa: BLE001 (no devtools port, Steam restarting: leave it)
+            print(f"steam ui: {exc}")
+            return
+        time.sleep(1)
+
+
 COMMANDS = {n[4:]: f for n, f in globals().items() if n.startswith("cmd_")}
 
 
@@ -2991,6 +3617,9 @@ def main():
     if len(sys.argv) >= 3 and sys.argv[1] == "_xr_probe":
         xr_probe(sys.argv[2])
         return 0
+    if len(sys.argv) >= 4 and sys.argv[1] == "_dashboard_worker":
+        dashboard_worker(sys.argv[2], sys.argv[3])
+        return 0
     if len(sys.argv) >= 3 and sys.argv[1] == "_tools_worker":
         tools_worker(sys.argv[2])
         return 0

artifacts/SHA256SUMS

@@ -3,10 +3,10 @@ a5b03bb7ae5d953d7ded2bf117b0a19c57fae604f16f54310847f8e89593dde6  ./arm64-v8a/li
 6d2b9f8cea2f2cf33b8ff30d29a2f3d9c4d55549260a867168a24e44abada021  ./arm64-v8a/libfp_vk.so
 8e00552d1ab90f82749db3caad4f773351fa8a28edcc5ea5cbd1b31c434ff32a  ./arm64-v8a/libframe_xrshim.so
 3dfcb0f2bec47857bcecc7261c58e076d872d4649718c40850f29e10c75477dd  ./arm64-v8a/libglshim.so
-507bb1c62168da9335a5883ec264aabed2ce09d04b6524e67be504a273473f8d  ./arm64-v8a/libopenxr_loader_generic.so
+3e05bb8561c7fd8787b3120739b3ce66c68badb5b00571bd50ae7e6c1f159274  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
 32525cd0a9ee3d9993d8871cd6905bdcf22cde4f4ba28f5db6434ce7d6554758  ./arm64-v8a/libvrapi.so
-11b7019c6a8d3b2f0f89cf23011f84bbbcb8e907f0935978e1df675339abbb6e  ./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

catalog/games/com.CMGames.IntoTheRadius2.yaml

@@ -0,0 +1,20 @@
+package: com.CMGames.IntoTheRadius2
+title: Into The Radius 2
+status: issues
+notes: Flickering textures were reported; space warp is turned off to address them (not yet confirmed in a headset).
+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.
+tested_version: 1.2.4
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+adapter:
+  equirect_emul: 1
+  hide_space_warp: 1
+verified:
+  date: '2026-10-04'
+  issue: 35
+updated: '2026-10-04'
+source_hint: Into The Radius 2

docs/AUDIO_METADATA.md

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

docs/GAMES.md

@@ -54,6 +54,7 @@ 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. |
+| Into The Radius 2 | Quest | ⚠️ Works with issues | Flickering textures were reported; space warp is turned off to address them (not yet confirmed in a headset). |
 | 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). |

docs/INSTALL.md

@@ -110,6 +110,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,6 +136,20 @@ 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.
@@ -167,6 +185,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 |

docs/PLAYBOOK.md

@@ -15,6 +15,8 @@ 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) |
@@ -53,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 |

native/README.md

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

native/adapter/audio_metadata.h

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

native/adapter/audio_metadata_queue.h

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

native/adapter/frame_adapter.c

@@ -69,6 +69,7 @@ static void fb_log(const char *fmt, ...) {
     funlockfile(log_file);
 }
 #define LOG(...) fb_log(__VA_ARGS__)
+#include "audio_metadata.h"
 
 static void *loader;
 static PFN_xrGetInstanceProcAddr next_gipa;
@@ -82,6 +83,9 @@ 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;
@@ -129,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;
@@ -204,6 +209,7 @@ static void initialize(void) {
         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);
@@ -269,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");
@@ -305,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;
 }
 
@@ -769,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) {
@@ -1056,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.
@@ -1179,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;
@@ -1196,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;
     }

pyproject.toml

@@ -82,7 +82,7 @@ module = "main"
 [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"]

scripts/dev_version.py

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

scripts/ui_smoke.py

@@ -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)
 
 
@@ -158,7 +254,10 @@ def main() -> int:
                     help="open the install questions for these games, then click each dialog's main button twice "
                          "(a double click must not duplicate dialogs); nothing is installed")
     ap.add_argument("--docs", action="store_true", help="only the screens used in the docs (Library, --game, Frame)")
+    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,7 +268,8 @@ 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)))
@@ -188,7 +288,22 @@ 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"))))
+    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.install_questions:
         queued: list[str] = []
 

src/frameport/_version.py

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

src/frameport/analysis/linux.py

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

src/frameport/artwork/steam.py

@@ -299,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"
@@ -315,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]

src/frameport/cli.py

@@ -227,6 +227,19 @@ 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("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."""

src/frameport/core/library.py

@@ -58,6 +58,8 @@ 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":
@@ -223,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.")

src/frameport/core/titles.py

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

src/frameport/diag/bundle.py

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

src/frameport/diag/issue.py

@@ -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 '?'})"

src/frameport/frame/connection.py

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

src/frameport/install/installer.py

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

src/frameport/install/screenshots.py

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

src/frameport/locales/template.json

@@ -51,9 +51,12 @@
  "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.": "",
@@ -66,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…": "",
@@ -76,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.": "",
@@ -92,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.": "",
@@ -104,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": "",
@@ -115,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}": "",
@@ -124,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).": "",
@@ -139,6 +152,7 @@
  "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": "",
  "Can't reach your Frame. Make sure it's on, awake and on the same network, then try again.": "",
  "Can't run": "",
  "Cancel": "",
@@ -149,10 +163,12 @@
  "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": "",
@@ -204,7 +220,9 @@
  "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}": "",
@@ -222,8 +240,17 @@
  "Declares Meta's permissions some mixed-reality games ask for, so they don't stop.": "",
  "Delete": "",
  "Delete {names}?": "",
+ "Delete {n} screenshot?": [
+  "",
+  ""
+ ],
+ "Deleted {n} screenshot": [
+  "",
+  ""
+ ],
  "Deletes the rollback copies kept from each game's previous install and leftover uploads. The games and saves stay.": "",
  "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": "",
@@ -236,14 +263,24 @@
  "done": "",
  "Done": "",
  "Download": "",
+ "Download all": "",
+ "Download selected": "",
  "Download to this PC": "",
  "Download to which folder on this PC?": "",
  "Download {name}": "",
+ "Download {n} screenshot": [
+  "",
+  ""
+ ],
  "Downloaded when first needed": "",
  "Downloaded {n} file to {folder}": [
   "",
   ""
  ],
+ "Downloaded {n} screenshot to {folder}": [
+  "",
+  ""
+ ],
  "Downloading…": "",
  "Downloads": "",
  "Draws each eye separately; try it when one eye shows a grey or broken picture.": "",
@@ -297,6 +334,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).": "",
@@ -317,6 +355,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": "",
@@ -345,6 +384,7 @@
  "From the tested recipe for this game": "",
  "From the {src}": "",
  "Full launch log": "",
+ "Game": "",
  "Game arguments (select SteamVR / OpenXR)": "",
  "Game config files": "",
  "Game launch capacity": "",
@@ -376,6 +416,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.": "",
@@ -395,6 +436,8 @@
  "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": "",
@@ -404,6 +447,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": "",
@@ -415,6 +459,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.": "",
@@ -424,6 +470,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.": "",
@@ -471,6 +519,9 @@
  "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.": "",
@@ -518,22 +569,28 @@
  "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: 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": "",
@@ -614,6 +671,7 @@
  "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": "",
@@ -629,6 +687,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).": "",
@@ -637,6 +696,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)": "",
@@ -708,7 +769,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.": "",
@@ -722,12 +786,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})": "",
@@ -739,6 +805,8 @@
  "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": "",
@@ -781,6 +849,8 @@
  "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": "",
@@ -790,6 +860,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.": "",
@@ -840,6 +911,7 @@
  "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": "",
@@ -851,10 +923,16 @@
  "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 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.": "",
@@ -875,6 +953,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).": "",
@@ -893,6 +972,7 @@
  "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.": "",
@@ -903,6 +983,8 @@
  "Try again": "",
  "Try now": "",
  "Turn off only for games you play with your hands instead of controllers.": "",
+ "Turn off space warp": "",
+ "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": "",
@@ -935,6 +1017,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": "",
@@ -984,6 +1067,7 @@
  "Videos": "",
  "Videos, documents, mods and saves on your Steam Frame": "",
  "View screenshot": "",
+ "VR (OpenXR)": "",
  "VrApi → OpenXR adapter (OVRPort)": "",
  "VrApi → OpenXR bridge": "",
  "Vulkan shader fixes": "",
@@ -1025,6 +1109,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)": "",
@@ -1059,6 +1147,7 @@
  "{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": [
   "",
   ""
@@ -1092,6 +1181,10 @@
   "",
   ""
  ],
+ "{n} screenshot": [
+  "",
+  ""
+ ],
  "{n} selected": "",
  "{n} setting changed from the default": [
   "",
@@ -1110,6 +1203,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})": "",

src/frameport/patches/overport.py

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

src/frameport/patches/settings.py

@@ -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)."),
@@ -206,7 +210,8 @@ 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",
+        "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")},
 }
 
@@ -236,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})

src/frameport/pipeline.py

@@ -254,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"])
@@ -273,6 +279,75 @@ 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}")
@@ -414,6 +489,8 @@ def _build_lock(package: str) -> 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:
@@ -436,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
@@ -478,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()
@@ -492,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)."""
@@ -499,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()

src/frameport/targets/base.py

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

src/frameport/targets/frame_lepton.py

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

src/frameport/ui/app.py

@@ -30,7 +30,9 @@ 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
 
 
@@ -67,6 +69,7 @@ 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 = jobs_module.shared()  # one queue per process, shared by every window session
@@ -97,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([
@@ -110,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)))
@@ -213,6 +218,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:
@@ -260,6 +283,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
 
@@ -279,7 +303,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
@@ -318,6 +342,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:
@@ -344,6 +374,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()
 
@@ -631,6 +664,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:
@@ -652,12 +686,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,
@@ -672,6 +706,10 @@ 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 \
@@ -679,19 +717,27 @@ class FramePortApp:
             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)
@@ -1267,8 +1313,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:
@@ -1294,6 +1340,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)."""
@@ -1301,6 +1391,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))
@@ -1370,6 +1462,36 @@ 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 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
 
@@ -1624,6 +1746,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"):

src/frameport/ui/components.py

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

src/frameport/ui/help.py

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

src/frameport/ui/updater.py

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

src/frameport/ui/views/exe_dialog.py

@@ -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 [])),

src/frameport/ui/views/files.py

@@ -193,7 +193,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"]))

src/frameport/ui/views/frame.py

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

src/frameport/ui/views/game.py

@@ -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)]
@@ -596,6 +631,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 +666,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

src/frameport/ui/views/library.py

@@ -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
@@ -198,7 +217,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 +452,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 +554,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 +577,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),

src/frameport/ui/views/screenshots.py

@@ -0,0 +1,362 @@
+"""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("")
+        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:
+            self.root = ft.Column([app.top_bar(heading, sub), self.toolbar, self.sel_bar,
+                                   C.card(self.grid, padding=T.S3, expand=True), 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))
+        return 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))
+
+    # ---------------------------------------------------------------- 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 _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)

src/frameport/ui/views/settings.py

@@ -133,6 +133,10 @@ 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 appearance(self) -> ft.Control:

src/frameport/updates.py

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

tests/fixtures/src/audio_metadata_test.c

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

tests/test_agent.py

@@ -1070,3 +1070,167 @@ def test_launch_falls_back_to_devkit_entry(monkeypatch, tmp_path):
     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_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)

tests/test_agent_deploy.py

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

tests/test_audio_metadata.py

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

tests/test_linux_apps.py

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

tests/test_patches.py

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

tests/test_screenshots.py

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

tests/test_ui_help.py

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

tests/test_updates.py

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