Keep auto-sync changelog separate from parallel fixes

Merge remote-tracking branch 'origin/main' into t3/fix-autosync-reliability
# Conflicts: # CHANGELOG.md
2026-10-25 08:01:44 +01:00 · 2026-10-25 06:21:39 +00:00 · 2026-10-25 06:20:50 +00:00 · 2026-10-25 06:19:38 +00:00 · 2026-10-25 06:18:28 +00:00 · 2026-10-25 06:15:42 +00:00
32 changed files with 1445 additions and 91 deletions
@@ -2,6 +2,17 @@

 ## Unreleased

+- Skip backup saves and settings reached through a symbolic link anywhere below
+  the home folder, and recheck paths before packing each file. Local synthetic
+  tests cover redirected Proton prefixes and links changed after discovery;
+  concurrent filesystem changes can still race the checks.
+  [Backup layout and limits](docs/backup-and-recovery.md).
+
+- Import a base APK with supported native-library or asset splits from a local
+  Android backup or XAPK/APKS/APKM bundle. Check package and version before
+  install; refuse resource, code and feature splits and device-variant sets.
+  This route has local fixture coverage, not a real split-game headset test.
+
 - Save Steam screenshots under a separate folder for each headset, Steam
  account and game. Equal screenshot filenames no longer overwrite one another;
  existing files in the old flat folder are left in place.
@@ -208,3 +219,8 @@
  shared Wine services are left alone. Verified with local Linux process
  regressions and a 13/13 real Frame smoke run that stopped five test-owned
  Proton process PIDs before removing the Windows test title.
+
+- Keep failed automatic screenshot and clip copies visible after three attempts.
+  **Resume** and **Copy everything now** allow another try without restarting;
+  headset switches cannot use another headset's list or saved-file history.
+  [Copying guide](docs/recording.md).
@@ -298,7 +298,7 @@ Frame's software fits together, all checked against a real headset and labelled
 | [PC in the headset](docs/pc-in-headset.md) | Experimental, Windows only, off until you turn it on: a whole PC screen as a panel in the Frame. Tested in a Windows VM; individual windows need a WGC-enabled build |
 | [Mac in the headset](docs/mac-in-headset.md) | Mac windows and screens as panels in the Frame, with laser and keyboard input |
 | [VR mods and custom songs](docs/mods.md) | UEVR for Unreal games from Frame Control (install, play in VR, remove), the per-game table, Beat Saber blockers |
-| [Decky Loader on Frame](docs/decky-frame.md) · [Frame Control in VR](docs/headset-app.md) · [Frame Control extensions](docs/extensions.md) | Experimental Decky support, a removable headset panel, and the local extension API |
+| [Decky Loader on Frame](docs/decky-frame.md) · [Frame Control in VR](docs/headset-app.md) · [Frame plugin author guide](docs/frame-plugin-author.md) · [Frame Control extensions](docs/extensions.md) | Experimental Decky support, a removable headset panel, and the local extension API |
 | [SSH](docs/ssh.md) · [Streaming](docs/streaming.md) · [Files](docs/file-transfer.md) · [Panels](docs/panels.md) · [Tailscale](docs/tailscale.md) | Topic notes |
 | [Frame Control for iPhone](docs/iphone.md) | The iPhone and iPad app, how it runs the server on the Frame, pairing |
 | [Recovery and OS images](docs/recovery-and-images.md) | Where to download the Frame's OS, what's inside, testing without the headset |
@@ -1,12 +1,12 @@
 {
  "name": "frame-control",
-  "version": "0.4.29",
+  "version": "0.4.30",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "frame-control",
-      "version": "0.4.29",
+      "version": "0.4.30",
      "license": "MIT",
      "devDependencies": {
        "electron": "^44.4.5",
@@ -1,7 +1,7 @@
 {
  "name": "frame-control",
  "productName": "Frame Control",
-  "version": "0.4.29",
+  "version": "0.4.30",
  "description": "Desktop app for managing a Valve Steam Frame over SSH",
  "private": true,
  "main": "main.js",
@@ -4,7 +4,7 @@ A SideQuest backup can contain a small APK and much larger `main.…obb` and
 `patch.…obb` files. All of them belong to the same game. Installing only the APK
 can leave the game unable to start because its assets are missing.

-In **Add / Install → Import Android game** (or **Apps → Browse → Import Android game**), choose the APK and its OBB files together.
+In **Add / Install → Import Android game** (or **Apps → Browse → Import Android game**), choose the base APK, any supported splits, and its OBB files together.
 You can also drop them anywhere in the window. In the desktop app, dropping the
 APK alone finds matching OBB files beside it; dropping a folder containing the
 APK and OBBs also works. Browsers can read only the files you explicitly choose.
@@ -37,9 +37,13 @@ are discarded after use or cancellation; abandoned imports expire after an hour
 when the importer is next used, and dead-server staging folders are swept at
 startup.

-This flow handles one ordinary APK and standard OBB files for one game at a time.
-Split APKs, XAPK/APKS archives, nested Android/data folders and private save
-archives need their own import handling. PC ZIP/folder/EXE imports keep their
+This flow handles one base APK, supported native-library or asset splits, and
+standard OBB files for one game at a time. It checks the package and version in
+each split manifest before touching the headset. The existing Quest merger
+rejects resource, code and feature splits and sets with multiple device
+variants. A merged APK is re-signed; that can affect a game's licence or login.
+XAPK/APKS/APKM archives use the same checks. Nested Android/data folders and
+private save archives remain unsupported. PC ZIP/folder/EXE imports keep their
 existing route. Quest USB and Meta library imports keep their existing workflow.

 Validation covers actual APK parsing, the three-file backup layout, package
@@ -55,3 +59,5 @@ released, and the battery remained at 99%. See [device evidence](evidence/androi
 The headset was unworn; this checks transfer and persistence, not rendering,
 Resident Evil 4 gameplay, or a game that exits before data can be copied. This
 flow does not change APK compatibility or remove licence checks.
+The supported-split backup route was checked with generated local fixtures and
+existing merger tests, not a real split game on the Frame.
@@ -436,13 +436,13 @@ permissions remain unverified. They do not change APK install or launch behavior
 ## Local APK/OBB backups and Android bundles

 In **Android apps → Import Android game → Choose game files…** (or **Send to Frame**), choose one
-standalone APK and its matching `main.<version>.<package>.obb` and/or
+base APK, any supported splits, and its matching `main.<version>.<package>.obb` and/or
 `patch.<version>.<package>.obb` files together. The desktop app also discovers
 matching OBB files beside a lone selected APK. Browser uploads use only the
 files you selected. Installed apps can receive OBB-only imports.

 You can instead select **one `.xapk`, `.apks`, or `.apkm` archive** containing
-one standalone APK and optional matching OBBs. These extensions describe
+one base APK, optional supported splits and matching OBBs. These extensions describe
 containers, not a guarantee that their contents are supported. OBBs may be
 at the archive root, under `<package>/`, or under `Android/obb/<package>/`;
 one enclosing backup folder is allowed. Known manifest/icon/signature
@@ -450,7 +450,7 @@ sidecars are ignored; the APK manifest determines the package. Unknown files,
 unsafe paths, links, encrypted entries, duplicate paths (including case
 collisions), more than 4,096 entries, or more than 16 GiB unpacked are refused.
 Staging also keeps 64 MiB of free disk space. Payloads still have the regular
-one-APK/99-OBB limit. Ordinary `.zip` files keep the PC-title import route;
+100-file/99-OBB limit. Ordinary `.zip` files keep the PC-title import route;
 extract an Android ZIP yourself and select its APK/OBBs.

 The importer previews the app and files before **Import game & data**.
@@ -463,12 +463,14 @@ data setup. Uploaded and extracted staging is removed on cancellation,
 inspection failure, or job completion/failure; abandoned imports expire
 through the existing one-hour staging lifecycle. Original local files stay intact.

-**Limits:** this backup importer refuses multiple APKs, split-only APKs and
-bases marked as requiring splits. It does not select device variants or restore
-`Android/data`, private app data, saves, or entitlements. For the separate
-restricted native-library/asset split workflow see
-[Quest split APKs](quest-import.md#split-apks) and the CLI above. Resource,
-code and feature splits are not supported by that merger.
+**Limits:** this backup importer requires exactly one base APK. For split sets,
+each split must identify the same package and version, and pass the existing
+[Quest split merger](quest-import.md#split-apks). It refuses resource, code and
+feature splits and does not choose among device variants. Merging re-signs the
+APK, which can affect licences. It does not restore `Android/data`, private app
+data, saves or entitlements. These split imports have local fixture and merger
+tests, but no real split game has been installed with this backup route on the
+Frame.

 For issue #102, the RE4 report only establishes that an APK attempt failed.
 Missing OBBs are a hypothesis; the edition/build, exact files, failing step,
@@ -100,7 +100,21 @@ copy one by hand if you need it.
 - Steam Cloud's own folders (`userdata/<account>/<appid>`), shader caches and
  screenshots (**Tools → Capture & Live** saves those to Pictures).
 - Android apps themselves, their OBB files and shared storage (`/sdcard`).
- Symbolic links (never followed), and single files over 2 GiB.
+- Symbolic links, including any ancestor below the home folder of a selected
+  save or settings path, and single files over 2 GiB. Discovery checks each
+  component, and packing checks it again before opening each file.
+
+Steam backups use the normal `~/.local/share/Steam` directory tree. A separate
+`~/.steam/steam` alias does not affect this route. A library, Proton prefix or
+Wine save folder redirected by a symlink below the home folder is skipped,
+even if its target is inside home; it is not resolved and backed up elsewhere.
+The home folder itself is trusted and may use the host's normal path aliases.
+
+These are path checks, not a filesystem snapshot: a concurrent rename or link
+replacement between a check and a read can still race it. Close games and
+avoid moving or relinking these folders during backup. This fix rejects links
+already present when checked, including ones introduced after discovery; it
+does not provide atomic protection against concurrent filesystem changes.

 Backups aren't encrypted. Game folders can still hold a launcher's login, and
 Android app data can hold an app's, so keep backups private.
@@ -192,11 +206,18 @@ If the button can't help, or the headset isn't reachable:
 `tests/test_backup.py` runs the headset-side script (`ui/frame_backup_remote.py`)
 for real against a folder laid out like the Frame's home, with only SSH faked:
 which paths are picked, that sign-in files and keys never are (also inside game
-folders), links never followed, the manifest and its checksums, restore checks
+folders), links in save/settings roots and their ancestors refused, the manifest
+and its checksums, restore checks
 after a reset (game not installed, no Proton folders yet, not signed in), that a
 restore replaces only its own files and keeps the old ones, unsafe archives
 (`..`, absolute paths, links, other games' folders) writing nothing, backup
 names that try to leave the backups folder, and the exact Game Mode command.
+Synthetic symlink fixtures cover every component of a Proton save root below
+home, including `compatdata/<appid>` and `steamuser/AppData`, plus directory
+and file links introduced between discovery and packing. Ordinary Proton and
+non-Steam saves, Linux saves, controller layouts, reference settings and home
+aliases still pack with their original bytes. These are local fixture checks;
+this path fix has not been tested on a headset.
 `tests/e2e/test_recovery_kit.py` backs up a Proton save from the fake Frame through
 the server, deletes it and restores it. Neither involves a real headset.

@@ -1,6 +1,6 @@
 # What we have tested

-Current for Frame Control **v0.4.29**, 25 October 2026. “Real Frame + physical PC” means an actual headset and a non-virtual computer. “VM only” means a Windows virtual machine, sometimes connected to the real Frame. A CI test or a simulated device is **not** a physical hardware test. The date/version column is the last relevant check, not a promise that every new release was retested on that platform. See each link for the exact procedure and limits.
+Current for Frame Control **v0.4.30**, 25 October 2026. “Real Frame + physical PC” means an actual headset and a non-virtual computer. “VM only” means a Windows virtual machine, sometimes connected to the real Frame. A CI test or a simulated device is **not** a physical hardware test. The date/version column is the last relevant check, not a promise that every new release was retested on that platform. See each link for the exact procedure and limits.

 | Feature | Real Frame + physical PC tested | VM only | Untested or limited | Last check and proof |
 |---|---|---|---|---|
@@ -17,6 +17,7 @@ Current for Frame Control **v0.4.29**, 25 October 2026. “Real Frame + physical
 | Switch PC windows | No physical Windows PC test | No real VM-to-Frame Alt+Tab check recorded | Explicit chord is covered by tests; actual window focus, keyboard layouts and controller interaction are unverified | 25 Oct, v0.4.24: [PR #181](https://github.com/saphid/frame-control/pull/181), [PC guide](pc-in-headset.md) |
 | Keyboard and trackpad from Frame Control | A Linux PC sent a click and ASCII keys to a temporary focused window on the real Frame | No | Worn-headset interaction, Unicode delivery and pixel-accurate pointing | 24 Oct, v0.4.19: [received-event log](evidence/pad-gamescope-2026-10-24.md), [PR #66](https://github.com/saphid/frame-control/pull/66) |
 | Backup and restore after reset | Same-headset backup, no-op save restore and Return to Game Mode checks | No | Restore **after a factory reset**, replacement restore and Android data restore have not been tested on a headset. No headset reset was done | 24 Oct, v0.4.17: [backup guide](backup-and-recovery.md), [Return to Game Mode log](evidence/return-game-mode-packaged-2026-10-24.json) |
+| Android game backup import | F-Droid Basic APK with synthetic main and patch OBBs installed, transferred and read back on a real Frame | No | v0.4.30 restricted split-APK backup route has generated-fixture and existing merger tests only; no real split game or RE4 gameplay test | 20 Oct OBB headset check; 25 Oct, v0.4.30 split fixtures: [OBB device evidence](evidence/android-import/device.json), [split PR #206](https://github.com/saphid/frame-control/pull/206), [guide](android-backups.md) |
 | Passthrough in recordings | No active-passthrough mirror check | No | Standby frame was uniform; whether visible room pixels enter `/dev/video99` is **unknown**. Raw cameras are never captured by Frame Control | 25 Oct, v0.4.21: [headset log](evidence/round3-headset-2026-10-25.md), [recording guide](recording.md#does-record-include-passthrough) |
 | Open at login | No Frame needed; Linux autostart file toggled on a physical Linux host with an isolated config directory | No | A full login session and physical Windows/macOS host login have not been checked; OS API calls were unit tested | 25 Oct, v0.4.26: [PR #189](https://github.com/saphid/frame-control/pull/189) |
 | Local Frame Control extensions | Example panel displayed live Frame status in a browser preview; the real Frame served a read-only example in the experimental headset panel | No | No wearer-visible extension view; third-party extensions and physical Windows/macOS extension folders untested | 25 Oct, v0.4.29: [PR #194](https://github.com/saphid/frame-control/pull/194), [PR #201](https://github.com/saphid/frame-control/pull/201), [extension guide](extensions.md) |
@@ -7,6 +7,57 @@ verified. Frame Control therefore labels its user-service manager experimental.
 ProtonDB Badges loaded in the backend and Gamepad UI plugin registry, but its
 VR user interface has not been seen or used.

+## Official store plugin audit, 2026-10-25
+
+On a real Frame with Frame OS 0.5.6 build `20261022.6153909`, SteamVR 2.18.2
+reported `activity_level` 3 (standby). The battery was 99% before and after.
+The test downloaded the official store's current archives, checked each SHA-256
+against store metadata, and inspected their manifests and binaries. For seven
+non-root candidates, the removable user-service loader started each plugin in
+turn. It stopped between plugins. Logs showed `Loaded <name>` for all seven.
+The service and test folders were removed after the run; the owned shared lock
+was released. **A load message is not proof that a plugin's page, settings, or
+action works in VR.** No plugin was tried by a wearer.
+
+| Official store plugin (tested version) | Result | Evidence and limit |
+| --- | --- | --- |
+| ProtonDB Badges 1.3.4 | Partial | ARM64 backend loaded. Earlier 1.1.0 also registered in the shared Gamepad UI; badges in the VR shell were not seen. |
+| CSS Loader 2.1.3 | Partial | Backend loaded; one `SyntaxWarning`. Theme controls and CSS application in VR were not checked. |
+| SteamGridDB 1.8.1 | Partial | Backend loaded. Artwork selection and its UI were not checked. |
+| Animation Changer 1.3.2 | Partial | Backend loaded. Boot animation replacement was not attempted. |
+| Storage Cleaner 1.4.0 | Partial | Backend loaded. No files were cleaned; no UI check. |
+| HLTB for Deck 2.0.12 | Partial | Passive plugin loaded. Game page content in VR was not checked. |
+| Bluetooth 3.1.1 | Partial | Backend logged `Bluetooth plugin loaded`. Pairing and VR controls were not checked. |
+| PowerTools 2.0.3 | Not applicable | Manifest asks for root; archive includes x86_64 Ryzen binaries and targets Steam Deck hardware. The Frame user service blocks it. |
+| Audio Loader 1.6.1 | Not applicable | Manifest asks for `_root`; the Frame user service blocks it. |
+| Wine Cellar 0.2.1 | Broken on ARM64 | Archive includes an x86_64 backend binary. The store installer blocks it before execution. |
+| MagicPods 2.0.21 | Broken on ARM64 | Archive includes an x86_64 `magicpodscore` binary. The store installer blocks it before execution. |
+| Decky Recorder | Not in current official store | No matching plugin appeared in the official store list on this date; no archive was installed. Frame Control's own headset panel has a separate recorder. |
+
+The table reflects the tested versions only. Other releases can change their
+files or behavior. The official store's digest checks the archive in transit;
+it does not certify plugin code. Plugins run with the headset user's access.
+For a new plugin, follow the [Frame plugin and extension guide](frame-plugin-author.md).
+
+The new store transaction was also exercised on the same real Frame:
+**managed loader install → ProtonDB Badges 1.3.4 store install → status →
+store update → store remove → managed loader remove**. Status reported the
+managed store ID and version while the plugin was installed. The service
+remained active after each store change. The battery was 99% before and after.
+The test removed its plugin folder, loader, and owned lock. This validates the
+store file and service path over SSH, not a visible VR plugin page.
+
+Frame Control's desktop app and opt-in headset panel now show official store
+entries. Install, update, and remove need an explicit confirmation. They only
+change Frame Control owned plugin folders under
+`~/.local/share/frame-control/decky/plugins`. The installer checks the store
+hash and archive paths, blocks root plugins and non-ARM64 binaries, and rolls
+back an update if the service restart fails. The current VR shell does not
+provide Decky's Steam Deck Quick Access Menu. Frame Control's headset panel
+shows installed plugins and store actions, but plugin pages, settings, routes,
+and Decky toasts are **not** available there yet. The panel itself still needs
+a worn-headset visual and controller check.
+
 ## What was checked on the real headset

 The headset was SteamOS `0.5.6`, `VARIANT_ID=vr`, build `20261022.6153909`,
@@ -86,8 +137,8 @@ its published SHA-256 digest, and checks the ELF architecture. It installs a
 officially supported. Plugins that require root, assume `~/homebrew`, or rely
 on Steam Deck hardware may fail even if the loader runs. Frame Control lists
 plugins already present in its managed folder and the upstream `~/homebrew`
-folder; it does not install plugins while their Frame UI and compatibility
-are unverified.
+folder. The opt-in store manager installs compatible archives only into its
+own folder. It cannot make Steam Deck QAM plugin pages visible in Frame VR.

 The latest tested release was
 [Decky 3.3.0](https://github.com/SteamDeckHomebrew/decky-loader/releases/tag/v3.3.0),
@@ -103,6 +154,9 @@ notice, check the acknowledgement box, and choose **Install**. **Update**
 downloads and verifies the latest ARM64 release again. **Remove managed
 Decky** disables and removes only Frame Control's user service and binary.
 It preserves plugin files and settings so unrelated user data is not deleted.
+Open **Official plugin store** to review a plugin, then confirm each install,
+update, or remove. Root and x86-only plugins are blocked. The manager only
+removes plugin folders that it installed; it leaves other Decky folders alone.
 Restart Steam or the headset to clear the frontend already injected into its
 current web helper process. No action wipes the headset.

@@ -0,0 +1,79 @@
+# Auto-sync retry and headset-selection reliability
+
+Date: 25 October 2026. Base: `d79efb4`, Frame Control v0.4.30.
+Issue: [#214](https://github.com/saphid/frame-control/issues/214).
+Environment: Linux x86_64, Python 3.12.3, Node 24.15.0.
+
+## Reproduced problems
+
+The existing 19 auto-sync tests passed on the base revision. Added regressions
+failed before the implementation: an exhausted clip lost its error, explicit
+retry did not recover failed screenshots or clips, and switches around listing
+or copying continued the old pass. The original callback interface also had no
+way to carry the tick's captured device into the server list reservation.
+
+The final fake-source tests exercise these boundaries:
+
+- Fail screenshots or clips three times, keep checking without further copy
+  attempts, and retain the source error plus an explicit retry instruction.
+- Recover the source and use either Resume or Copy everything now without
+  restarting. Successful copies stay deduplicated; Resume retains the ledger
+  even after a local file is deleted. Copy everything now retains its documented
+  ability to restore deleted files and include older media.
+- Reset an exhausted budget while the source still fails: another three
+  attempts are allowed, rather than unlimited background attempts.
+- Save an exhausted item by hand and clear its stale failure on the next list.
+- Switch after tick captures A, during a list, after screenshot bookkeeping,
+  between media kinds, before a transfer, or before transfer bookkeeping.
+  Interrupted passes do not mark the other headset's IDs or continue copying.
+- Switch to B exactly at callback entry through the production `_sync_list`
+  adapter. `working(A)` refuses before calling the source list, leaving both
+  ledgers and copy callbacks untouched. The same production reservation blocks
+  a device switch during a list and rejects stale screenshot/clip transfers.
+- Execute the production Settings renderer in Node: Resume is available for
+  copy errors and disk-full pauses, and hidden for a healthy state.
+
+## Implementation boundary
+
+Each list callback now receives the captured device, like the copy callbacks.
+The existing server `working(meant)` mechanism checks that intended headset
+under `_work_lock` while reserving work; `devices_post` uses the same lock to
+refuse switches during that work. The worker also checks for interruption
+around lists and transfers. No new device lock or clip destination logic is
+introduced. The server diff is confined to `_sync_list`.
+
+The failed-attempt and error maps are in-memory and reset on explicit retry or
+restart. The successful-copy ledger and settings persistence retain their
+existing format. Disk-full pauses, offline backoff, clip settling and the
+three-attempt limit remain covered by the original tests.
+
+## Checks
+
+- `python3 -m unittest discover -s tests -p test_autosync.py -v`: 33 passed.
+- `python3 -m unittest discover -s tests -p test_shot_copy.py -v`: 2 passed.
+- `python3 -m unittest discover -s tests -p test_clips.py -v`: 34 passed,
+  including local ffmpeg coverage.
+- `python3 -m unittest discover -s tests -p test_service_regressions.py -v`:
+  36 passed.
+- `python3 -m unittest discover -s tests -p test_page_scripts.py -v`: 5 passed.
+- `node --test site/test/*.test.mjs`: 2 test files passed.
+- `python3 -m py_compile ui/frame_autosync.py ui/server.py tests/test_autosync.py`
+  and `git diff --check`: passed.
+
+- `python3 -m unittest discover -s tests -v`: 1,525 tests run in 184.876
+  seconds, passed with 16 skips. Ran with sandbox escalation for loopback
+  sockets; test isolation still used throwaway app/SSH data and mocked headset
+  transport. Final output:
+
+  ```text
+  Ran 1525 tests in 184.876s
+  OK (skipped=16)
+  ```
+
+## Limits and handoff
+
+All new regressions use fake sources and mocked transport; they do not prove
+real-headset transfer or UI rendering. No headset was accessed: its shared test
+lock was held by another task. The Docker fake-Frame end-to-end suite and
+Windows/macOS runs were not performed locally. The coordinator owns review and
+merge; this task does not release, change PR #113, or publish announcements.
@@ -34,11 +34,19 @@ The manifest ID must match the folder name:
  "id": "your-id",
  "name": "Your feature",
  "version": "1.0.0",
+  "apiVersion": 1,
  "description": "What the panel does.",
  "entry": "index.html"
 }
 ```

+`apiVersion` selects the Frame Control bridge contract, independently of your
+extension's own `version`. This app supports integer `1`; a missing field means
+`1` for existing extensions. Unsupported versions appear as errors on Refresh,
+and their assets are not served. Declare it in new extensions so a future API
+change can fail clearly instead of running incompatible code. The runtime
+`capabilities` reply below reports the bridge version too.
+
 Put JavaScript in a separate `.js` file. Supported assets are HTML, JS, CSS,
 JSON, PNG, JPEG, GIF, WebP and SVG, all in the extension's top-level folder.
 Nested paths and symlinks are not served. No file may exceed 5 MiB. The panel
@@ -0,0 +1,34 @@
+# Write a plugin for Frame
+
+There are two paths. Choose the one that matches your feature.
+
+## Frame Control extension
+
+Use a Frame Control extension for a panel, status view, or guide that does not
+need to change the headset. Put `extension.json` and `index.html` in one folder
+under `~/.local/share/frame-control/extensions`. The opt-in headset panel lists
+the folder and opens it in a sandboxed iframe. The version 1 bridge has only
+`capabilities` and read-only `status`. It cannot call Steam, change settings,
+or run privileged code. See [the extension API](extensions.md) and its example.
+
+## Decky plugin
+
+Use a Decky plugin only if you need Decky's backend or Gamepad UI integration.
+Build an official-format ZIP with one top-level folder, `plugin.json`, and a
+frontend bundle in `dist/index.js`. A Python `main.py` backend is optional.
+Test on ARM64. If you ship an ELF helper, build it for AArch64 (ELF machine
+183). Avoid root, `sudo`, Steam Deck TDP controls, fixed x86 binaries, and
+paths under `/etc`. Frame Control's managed loader is a normal user service;
+it blocks root plugins and x86 archives. Keep data under your plugin folder or
+the user's home directory, and provide a removal path.
+
+The current Frame SteamVR shell does not expose Decky's Steam Deck Quick Access
+Menu. A backend `Loaded` log only proves backend startup. Test any frontend
+page, setting, notification, route, and controller input while wearing a Frame
+before describing it as working in VR. Until a QAM bridge is verified, a Frame
+Control extension is the practical route for a visible read-only VR panel.
+
+To test safely, use a separate Frame Control managed Decky install, verify the
+ZIP digest from the official store, install one plugin at a time, and inspect
+`journalctl --user -u frame-control-decky.service`. Remove only your own
+plugin folder when you finish. See the current [compatibility table](decky-frame.md).
@@ -28,6 +28,14 @@ It offers the version 1 read-only `capabilities` and `status` bridge from
 [the extension guide](extensions.md). Installing an extension still means
 copying its folder to the Frame; the panel does not download third-party code.

+The panel also lists Decky plugins and can install, update, or remove compatible
+plugins from the official store when the opt-in managed loader is running.
+Each change asks for confirmation. The Frame VR shell does not show Decky's
+Steam Deck Quick Access Menu, so Decky plugin pages, settings, routes, and
+toasts are not available in this panel yet. The [compatibility table](decky-frame.md)
+separates backend loading from VR use. Authors can use the
+[Frame plugin and extension guide](frame-plugin-author.md).
+
 The per-run UI key is passed in the URL fragment, removed from the address bar after load,
 and sent in the `X-Frame-UI` header. The key is absent from the HTTP request
 line and server log. The usual host/origin and anti-framing checks still apply.
@@ -1,10 +1,29 @@
 # Open questions and on-device checks

-Research as of 2026-09-25, eight days after the Frame's retail release
-(2026-09-18). Most first-party detail comes from Valve's Steamworks developer
-pages. Searches of Reddit and the Steam forums turned up **almost no
-end-user reports** about SSH, desktop streaming, or macOS. Treat that as
-"not documented yet", not "doesn't work".
+The September sections below record early checks after the Frame's retail
+release (2026-09-18). They are a historical test log, not a current setup
+guide. For current connection steps, see [SteamOS October 2026
+compatibility](steamos-2026-10-compat.md). For the charge-limit result, see
+[charge-limit.md](charge-limit.md).
+
+## Current Frame OS 0.5.6 status (2026-10-25)
+
+- `frame.local` no longer resolves on the checked 0.5.6 beta build
+  (`20261022.6153909`). Avahi was active but did not publish addresses. The
+  configured Tailscale SSH alias worked. Frame Control can use a saved IP on
+  the same network after verifying the pinned SSH key, or a manual IP/SSH
+  alias. Same-LAN fallback scanning was **not** tested on this Tailscale route.
+  See the [live compatibility check](evidence/steamos-compat-live-2026-10-25.md).
+- Read-only checks on that build found no SteamOS Manager
+  `BatteryChargeLimit1` interface or `charge_control_*` attribute. The vendor
+  charging switches are root-owned and managed by Valve's charger service.
+  No charging control was written. An 80% limit is **not supported** by Frame
+  Control; see [charge-limit.md](charge-limit.md) and the
+  [headset check](evidence/round3-headset-2026-10-25.md).
+- Active passthrough in the recording mirror remains **unknown**: the only
+  captured mirror frame was uniform while the headset was unworn in standby.
+  A worn, active passthrough check is still needed; see the
+  [headset check](evidence/round3-headset-2026-10-25.md).

 ## Verified on device (2026-09-25)

@@ -14,7 +33,9 @@ build 20260922.6101926, kernel 6.18, aarch64):
 - **1–2.** Developer Mode + Set User Password gave working SSH with no terminal
  steps. `sshd` is enabled and active. The user is `steamos` (in `wheel`) and
  the hostname is `frame`.
- **3.** `frame.local` resolves from the Mac; `avahi-daemon` is active.
+- **3.** `frame.local` resolved from the Mac on the September build;
+  `avahi-daemon` was active. This result does not apply to the checked 0.5.6
+  beta build; see the current status above.
 - **5.** `/etc/ssh/sshd_config` has `Include /etc/ssh/sshd_config.d/*.conf`.
  The existing drop-ins are `20-systemd-userdb.conf` and `99-archlinux.conf`, so
  `01-frame-keys-only.conf` would sort first as intended. (`--harden` itself
@@ -148,9 +169,9 @@ check in the headset:
 Can an 80% charge limit be set over SSH or adb? **Not safely yet.** SteamOS
 Manager's `BatteryChargeLimit1` (the interface Steam's own setting uses) has
 no backend in the Frame's device config, and the battery node is a
-`max1720x` fuel gauge with no `charge_control_end_threshold`. Research and
-read-only headset checks are in [charge-limit.md](charge-limit.md). Not tested
-on a headset.
+`max1720x` fuel gauge with no `charge_control_end_threshold`. Read-only checks
+on the real Frame confirmed this on 0.5.6 beta; no charge setting was written.
+See [charge-limit.md](charge-limit.md).

 ## Unconfirmed claims made in these docs

@@ -137,10 +137,19 @@ case was tested with separate fake sources, not two real same-name screenshots.
 - **When this computer is full** (under 512 MB free, or a copy runs out of
  space) it pauses and says so in Settings and above the lists. Free some space
  and press **Resume**.
- **With several headsets** it copies from the one you're connected to.
+- **When one file keeps failing** it tries at most three times, then leaves
+  the problem visible in Settings. Fix the source problem and press **Resume**
+  to allow another three attempts without restarting Frame Control. **Copy
+  everything now** also resets failed attempts and includes older files.
+  Resume keeps the history of successful copies, so it does not recopy them.
+- **With several headsets** each check and copy belongs to the headset selected
+  when the check began. Switching between lists or copies stops that pass;
+  another headset's saved files cannot become part of its copy history.

 Settings shows when it last checked, how many files it last copied and when,
 and the last problem it had. The screenshot and clip lists say when it's on.
+Retry and switch handling have offline regression coverage with fake sources;
+see the [test record](evidence/autosync-reliability-2026-10-25.md).

 ## For developers

@@ -12,6 +12,21 @@ A fourth, a SteamOS VM, may come later ([issue #6](https://github.com/saphid/ste

 ## Unit tests

+Automatic screenshot and clip copying has offline coverage in
+`tests/test_autosync.py`:
+
+```sh
+python3 -m unittest discover -s tests -p test_autosync.py -v
+```
+
+Fake sources exercise the three-attempt limit, visible exhausted errors,
+Resume/Copy everything now recovery, successful-copy deduplication, disk-full
+pauses and headset changes around lists and transfers. Server tests use the
+production `working(meant)` reservation and listing/copy adapters; a Node test
+executes the Settings renderer to check that Resume is available after an error.
+These tests use no headset. See the
+[auto-sync reliability test record](evidence/autosync-reliability-2026-10-25.md).
+
 The gamescope keyboard/trackpad route has focused suites in `test_input.py`,
 `test_touch.py` and `test_service_regressions.py`. They cover pad translation,
 ASCII/modifier keys, Unicode queuing/retries, stale panel targets, release
@@ -2,6 +2,7 @@
  "id": "headset-glance",
  "name": "Headset Glance",
  "version": "1.0.0",
+  "apiVersion": 1,
  "description": "Shows a small read-only summary of the connected Steam Frame.",
  "entry": "index.html"
 }
@@ -16,6 +16,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'ui'))
 import frame_android_import as backup
 import server
 from apk_fixtures import apk, manifest
+from test_quest import apk_bytes

 PKG = 'com.Armature.VR4'
 META = {'package': PKG, 'label': PKG, 'version': '', 'version_code': 210,
@@ -66,6 +67,41 @@ class BackupTests(unittest.TestCase):
        with self.assertRaisesRegex(backup.android.FrameError, 'unique names'):
            backup.inspect([str(self.apk), str(self.obb[0]), str(duplicate)])

+    def test_supported_split_set_uses_manifest_base_and_existing_merge_path(self):
+        base = self.root / 'not-named-base.apk'
+        base.write_bytes(apk_bytes(PKG, split_required=True, version_code=210))
+        split = self.root / 'arm64.apk'
+        split.write_bytes(apk_bytes(PKG, split='config.arm64_v8a', version_code=210,
+                                    files={'lib/arm64-v8a/libgame.so': b'game'}))
+        plan = backup.inspect([str(split), str(base)])
+        self.assertEqual(plan['apk'], base)
+        self.assertEqual(plan['splits'], [split])
+        self.assertEqual(backup.public(plan)['splits'], ['arm64.apk'])
+        with patch.object(backup.quest, '_running', return_value=False), \
+                patch.object(backup.android, 'read_meta', return_value=None), \
+                patch.object(backup.android, 'install', return_value=META) as install:
+            backup.install(plan)
+        self.assertEqual(install.call_args.kwargs['splits'], [str(split)])
+
+    def test_split_mismatch_and_unsupported_resource_fail_before_frame_access(self):
+        base = self.root / 'base.apk'
+        base.write_bytes(apk_bytes(PKG, split_required=True, version_code=210))
+        split = self.root / 'split.apk'
+        with patch.object(backup.android, 'ssh') as ssh:
+            split.write_bytes(apk_bytes(PKG, split='config.arm64_v8a', version_code=211,
+                                        files={'lib/arm64-v8a/libgame.so': b'game'}))
+            with self.assertRaisesRegex(backup.android.FrameError, 'version cannot be verified'):
+                backup.inspect([str(base), str(split)])
+            split.write_bytes(apk_bytes(PKG, split='config.xxhdpi', version_code=210,
+                                        files={'res/drawable/icon.png': b'png'}))
+            with self.assertRaisesRegex(backup.android.FrameError, 'screen-density or language resources'):
+                backup.inspect([str(base), str(split)])
+            split.write_bytes(apk_bytes(PKG, split='config.x86_64', version_code=210,
+                                        files={'lib/x86_64/libgame.so': b'game'}))
+            with self.assertRaisesRegex(backup.android.FrameError, 'another device'):
+                backup.inspect([str(base), str(split)])
+        ssh.assert_not_called()
+
    def test_obb_only_repairs_existing_game_and_requests_apk_when_not_installed(self):
        with patch.object(backup.android, 'read_meta', return_value=None):
            with self.assertRaisesRegex(backup.android.FrameError, 'Add its APK'):
@@ -204,6 +240,21 @@ class BundleTests(unittest.TestCase):
                self.assertTrue(all(not Path(p).exists() for p in folders))
                self.assertTrue(source.exists())

+    def test_bundle_with_supported_split_uses_same_preview_and_cleanup(self):
+        source = self.bundle({
+            'base.apk': apk_bytes(PKG, split_required=True, version_code=210),
+            'config.arm64.apk': apk_bytes(PKG, split='config.arm64_v8a', version_code=210,
+                                          files={'lib/arm64-v8a/libgame.so': b'game'}),
+        }, suffix='.apks')
+        with patch.object(backup.android, 'ssh') as ssh:
+            read = server.android_backup({'action': 'inspect', 'paths': [str(source)]})
+        ssh.assert_not_called()
+        self.assertEqual(read['plan']['apk'], 'base.apk')
+        self.assertEqual(read['plan']['splits'], ['config.arm64.apk'])
+        folders = list(server._android_backups[read['token']]['dirs'])
+        server.android_backup({'action': 'discard', 'token': read['token']})
+        self.assertTrue(all(not Path(p).exists() for p in folders))
+
    def test_browser_upload_bundle_is_staged_and_removed_with_extraction(self):
        source = self.bundle()
        token = server.android_backup({'action': 'begin'})['token']
@@ -221,7 +272,7 @@ class BundleTests(unittest.TestCase):

    def test_reject_layouts_before_any_headset_access_and_cleanup_failed_stage(self):
        cases = [
-            ({'base.apk': self.apk.read_bytes(), 'split.apk': self.apk.read_bytes()}, 'Split APK'),
+            ({'base.apk': self.apk.read_bytes(), 'split.apk': self.apk.read_bytes()}, 'exactly one base'),
            ({'base.apk': self.apk.read_bytes(), f'Android/data/{PKG}/save': b'private'}, 'restore'),
            ({'base.apk': self.apk.read_bytes(), 'main.1.org.other.game.obb': b'wrong'}, 'does not belong'),
            ({'base.apk': self.apk.read_bytes(), '../outside.obb': b'bad'}, 'unsafe'),
@@ -229,7 +280,7 @@ class BundleTests(unittest.TestCase):
            ({'base.apk': self.apk.read_bytes(), 'CON.apk': b'bad'}, 'unsafe'),
            ({'base.apk': self.apk.read_bytes(), 'other.exe': b'bad'}, 'Unsupported'),
            ({'base.apk': self.apk.read_bytes(), 'BASE.apk': b'bad'}, 'duplicate'),
-            ({'manifest.json': b'{}'}, 'standalone APK'),
+            ({'manifest.json': b'{}'}, 'base APK'),
        ]
        for entries, message in cases:
            with self.subTest(message=message), patch.object(backup.android, 'ssh') as ssh:
@@ -277,7 +328,8 @@ class BundleTests(unittest.TestCase):
                                    ('x' * len('isSplitRequired')).encode('utf-16-le'))
            self.apk.write_bytes(apk({'AndroidManifest.xml': data}))
            with self.subTest(attrs=attrs):
-                with self.assertRaisesRegex(backup.android.FrameError, 'needs split APKs'):
+                message = 'exactly one base' if attrs.get('split') else 'needs split APKs'
+                with self.assertRaisesRegex(backup.android.FrameError, message):
                    backup.inspect([str(self.apk)])

    def test_bundle_install_uses_existing_queue_and_cleans_after_failure(self):
@@ -7,11 +7,13 @@ import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import errno
 import json
 import shutil
+import subprocess
 import sys
 import tempfile
 import threading
 import unittest
 from pathlib import Path
+from unittest import mock

 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "ui"))
 import frame_autosync as fa  # noqa: E402
@@ -35,13 +37,15 @@ class FakeFrame:
        self.device, self.busy, self.down = "frame-a", False, False
        self.save_error = self.export_error = None

-    def list_shots(self):
+    def list_shots(self, device):
+        assert device == self.device
        self.calls.append("list_shots")
        if self.down:
            raise RuntimeError("ssh: connect to host frame port 22: Connection timed out")
        return {"shots": list(self.shots)}

-    def list_clips(self):
+    def list_clips(self, device):
+        assert device == self.device
        self.calls.append("list_clips")
        if self.down:
            raise RuntimeError("ssh: connect to host frame port 22: Connection timed out")
@@ -263,6 +267,134 @@ class AutoSyncTest(unittest.TestCase):
        for _ in range(fa.TRIES + 2):
            self.sync.tick()
        self.assertEqual(self.frame.calls.count("export_clip"), fa.TRIES)
+        self.assertIn("ffmpeg couldn't join", self.sync.state()["error"] or "")
+        self.assertIn("Resume", self.sync.state()["error"] or "")
+
+    def test_explicit_retry_recovers_without_recopying_successful_items(self):
+        for kind in ("shots", "clips"):
+            for action in ("resume", "copy_all"):
+                with self.subTest(kind=kind, action=action):
+                    self.frame = FakeFrame()
+                    f = self.frame
+                    sync = self.make()
+                    sync.update({"screenshots": True, "clips": True})
+                    f.shots, f.clips = [shot(1, NOW + 5)], [clip(1, NOW + 5)]
+                    error_attr = "save_error" if kind == "shots" else "export_error"
+                    copy_call = "save_shots" if kind == "shots" else "export_clip"
+                    setattr(f, error_attr, RuntimeError("source not ready"))
+                    for _ in range(fa.TRIES + 2):
+                        sync.tick()
+                    self.assertEqual(f.calls.count(copy_call), fa.TRIES)
+                    self.assertIn("source not ready", sync.state()["error"] or "")
+                    setattr(f, error_attr, None)
+                    sync.tick()  # recovery alone must not create unlimited automatic retries
+                    self.assertEqual(f.calls.count(copy_call), fa.TRIES)
+                    getattr(sync, action)()
+                    sync.tick()
+                    self.assertEqual(f.saved, [("frame-a", [shot(1, 0)["id"]])])
+                    self.assertEqual(f.exported, [("frame-a", clip(1, 0)["id"])])
+                    self.assertIsNone(sync.state()["error"])
+                    # Resume preserves the per-headset ledger even if a local file was deleted.
+                    for item in f.shots + f.clips:
+                        item["saved"] = False
+                    sync.resume()
+                    sync.tick()
+                    self.assertEqual((len(f.saved), len(f.exported)), (1, 1))
+                    self.sync.path.unlink(missing_ok=True)
+
+    def test_explicit_retry_is_still_bounded(self):
+        self.sync.update({"clips": True})
+        self.frame.clips = [clip(1, NOW + 5)]
+        self.frame.export_error = RuntimeError("bad source")
+        for action in ("resume", "copy_all"):
+            for _ in range(fa.TRIES + 2):
+                self.sync.tick()
+            before = self.frame.calls.count("export_clip")
+            getattr(self.sync, action)()
+            for _ in range(fa.TRIES + 2):
+                self.sync.tick()
+            self.assertEqual(self.frame.calls.count("export_clip") - before, fa.TRIES)
+            self.assertIn("bad source", self.sync.state()["error"] or "")
+
+    def test_failed_item_saved_by_hand_clears_error(self):
+        self.sync.update({"clips": True})
+        self.frame.clips = [clip(1, NOW + 5)]
+        self.frame.export_error = RuntimeError("bad source")
+        for _ in range(fa.TRIES + 1):
+            self.sync.tick()
+        self.frame.clips[0]["saved"] = True
+        self.sync.tick()
+        self.assertIsNone(self.sync.state()["error"])
+        self.assertIn(clip(1, 0)["id"], self.sync._synced("frame-a", "clips"))
+
+    def test_switch_after_capture_does_not_list_the_new_headset(self):
+        self.sync.update({"screenshots": True, "clips": True})
+        def switched():
+            self.frame.device = "frame-b"
+            return False
+        self.sync.busy = switched  # tick has already captured frame-a
+        self.assertEqual(self.sync.tick(), fa.BUSY_WAIT)
+        self.assertEqual(self.frame.calls, [])
+
+    def test_list_callbacks_receive_the_captured_device(self):
+        self.sync.update({"screenshots": True, "clips": True})
+        self.sync.list_shots = mock.Mock(return_value={"shots": []})
+        self.sync.list_clips = mock.Mock(return_value={"clips": []})
+        self.sync.tick()
+        self.sync.list_shots.assert_called_once_with("frame-a")
+        self.sync.list_clips.assert_called_once_with("frame-a")
+
+    def test_switch_during_listing_does_not_mark_or_copy_its_results(self):
+        for kind, item in (("shots", shot(1, NOW + 5)), ("clips", clip(1, NOW + 5))):
+            with self.subTest(kind=kind):
+                self.frame.device = "frame-a"
+                self.sync.update({"screenshots": kind == "shots", "clips": kind == "clips"})
+                def listing(*_args):
+                    self.frame.device = "frame-b"
+                    return {kind: [dict(item, saved=True), dict(item, id="uncopied", saved=False)]}
+                setattr(self.sync, "list_" + kind, listing)
+                self.assertEqual(self.sync.tick(), fa.BUSY_WAIT)
+                self.assertEqual(self.sync._synced("frame-a", kind), set())
+                self.assertEqual(self.sync._synced("frame-b", kind), set())
+                self.assertEqual((self.frame.saved, self.frame.exported), ([], []))
+
+    def test_switch_between_kinds_does_not_read_clips_or_mark_transfer(self):
+        self.sync.update({"screenshots": True, "clips": True})
+        self.frame.shots = [shot(1, NOW + 5)]
+        self.frame.clips = [clip(1, NOW + 5, saved=True)]
+        save = self.sync.save_shots
+        def then_switch(device, ids):
+            save(device, ids)
+            self.frame.device = "frame-b"
+        self.sync.save_shots = then_switch
+        self.assertEqual(self.sync.tick(), fa.BUSY_WAIT)
+        self.assertNotIn("list_clips", self.frame.calls)
+        self.assertEqual(self.sync._synced("frame-a", "clips"), set())
+        self.assertEqual(self.sync._synced("frame-a", "shots"), set())
+
+    def test_switch_after_bookkeeping_stops_before_next_kind(self):
+        self.sync.update({"screenshots": True, "clips": True})
+        self.frame.shots = [shot(1, NOW + 5, saved=True)]
+        mark = self.sync._mark
+        def then_switch(device, kind, ids):
+            mark(device, kind, ids)
+            self.frame.device = "frame-b"
+        self.sync._mark = then_switch
+        self.assertEqual(self.sync.tick(), fa.BUSY_WAIT)
+        self.assertNotIn("list_clips", self.frame.calls)
+
+    def test_switch_before_transfer_does_not_copy(self):
+        for kind, item in (("shots", shot(1, NOW + 5)), ("clips", clip(1, NOW + 5))):
+            with self.subTest(kind=kind):
+                self.frame.device = "frame-a"
+                self.sync.update({"screenshots": kind == "shots", "clips": kind == "clips"})
+                setattr(self.frame, kind, [item])
+                def switched_space(_folder):
+                    self.frame.device = "frame-b"
+                    return 100 * GB
+                self.sync.space = switched_space
+                self.assertEqual(self.sync.tick(), fa.BUSY_WAIT)
+                self.assertEqual((self.frame.saved, self.frame.exported), ([], []))

    def test_worker_stops(self):
        stop = threading.Event()
@@ -275,6 +407,75 @@ class AutoSyncTest(unittest.TestCase):


 class Server(unittest.TestCase):
+    def test_switch_at_list_callback_entry_does_not_read_or_mark_the_new_headset(self):
+        import server
+        with tempfile.TemporaryDirectory() as folder:
+            for kind in ("shots", "clips"):
+                with self.subTest(kind=kind):
+                    active = {"id": "frame-a"}
+                    link = mock.Mock()
+                    link.active_device.side_effect = lambda: dict(active)
+                    listing = mock.Mock(return_value={kind: [
+                        shot(1, NOW + 5, saved=True) if kind == "shots" else clip(1, NOW + 5, saved=True)]})
+                    def switch_then_list(device):
+                        active["id"] = "frame-b"
+                        return server._sync_list(listing)(device)
+                    with mock.patch.object(server, "LINK", link), mock.patch.object(server, "_work", [0]):
+                        sync = fa.AutoSync(switch_then_list, mock.Mock(), switch_then_list, mock.Mock(),
+                                           lambda: active["id"], lambda: False,
+                                           path=Path(folder) / (kind + ".json"), clock=lambda: NOW)
+                        sync.update({"screenshots": kind == "shots", "clips": kind == "clips"})
+                        sync.tick()
+                        listing.assert_not_called()
+                        sync.save_shots.assert_not_called()
+                        sync.export_clip.assert_not_called()
+                        self.assertEqual(sync._synced("frame-a", kind), set())
+                        self.assertEqual(sync._synced("frame-b", kind), set())
+                        self.assertIn("switched headsets", sync.state()["error"])
+                        self.assertEqual(server._work[0], 0)
+
+    def test_listing_rejects_switch_before_reserving_work(self):
+        import server
+        link = mock.Mock()
+        link.active_device.return_value = {"id": "frame-b"}
+        listing = mock.Mock(return_value={"shots": [shot(1, NOW, saved=True)]})
+        with mock.patch.object(server, "LINK", link), mock.patch.object(server, "_work", [0]):
+            with self.assertRaisesRegex(server.Failure, "switched headsets"):
+                server._sync_list(listing)("frame-a")
+            listing.assert_not_called()
+            self.assertEqual(server._work[0], 0)
+
+    def test_listing_reserves_work_on_the_captured_device(self):
+        import server
+        link = mock.Mock()
+        link.active_device.return_value = {"id": "frame-a", "name": "Frame A"}
+        def listing():
+            self.assertGreater(server._work[0], 0)
+            with self.assertRaises(server.Failure):
+                server.devices_post({"action": "use", "id": "frame-b"})
+            return {"shots": []}
+        with mock.patch.object(server, "LINK", link), \
+                mock.patch.object(server, "PRIVATE", False), mock.patch.object(server, "_work", [0]):
+            self.assertEqual(server._sync_list(listing)("frame-a"), {"shots": []})
+            self.assertEqual(server._work[0], 0)
+
+    def test_copy_rejects_switch_after_listing(self):
+        import server
+        link = mock.Mock()
+        link.active_device.return_value = {"id": "frame-a"}
+        with mock.patch.object(server, "LINK", link), mock.patch.object(server, "_work", [0]), \
+                mock.patch.object(server, "save_shots") as save, \
+                mock.patch.object(server.frame_clips, "export_clip") as export:
+            server._sync_list(lambda: {"shots": []})("frame-a")
+            link.active_device.return_value = {"id": "frame-b"}
+            for copy in (lambda: server._sync_shots("frame-a", [shot(1, NOW)["id"]]),
+                         lambda: server._sync_clip("frame-a", clip(1, NOW)["id"])):
+                with self.assertRaisesRegex(server.Failure, "switched headsets"):
+                    copy()
+            save.assert_not_called()
+            export.assert_not_called()
+            self.assertEqual(server._work[0], 0)
+
    def test_route_and_settings(self):
        import server
        self.assertIn("/api/autosync", server.POST)
@@ -287,5 +488,29 @@ class Server(unittest.TestCase):
                server.auto_sync({"action": "now"})  # nothing connected


+@unittest.skipUnless(shutil.which("node"), "Node exercises the Settings renderer")
+class Settings(unittest.TestCase):
+    def test_resume_is_available_after_a_copy_error(self):
+        page = (Path(__file__).resolve().parents[1] / "ui/index.html").read_text(encoding="utf-8")
+        script = page.split("const autoSync =", 1)[1].split("async function loadAutoSync", 1)[0]
+        harness = r'''
+const assert = require('node:assert/strict');
+const nodes = {};
+const $ = id => nodes[id] ||= {};
+const HOST = {mobile: false};
+const esc = value => value;
+'''
+        checks = r'''
+for (const state of [{error: 'Could not copy clip'}, {paused: 'Disk full'}, {}]) {
+  renderAutoSync(state);
+  assert.equal($('syncResume').hidden, !(state.error || state.paused));
+  if (state.error) assert.match($('syncStatus').textContent, /Could not copy clip/);
+}
+'''
+        result = subprocess.run(["node", "-e", harness + "const autoSync =" + script + checks],
+                                capture_output=True, text=True, timeout=10)
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+
 if __name__ == "__main__":
    unittest.main()
@@ -113,6 +113,108 @@ class Remote(unittest.TestCase):
        os.symlink(str(outside), str(base / 'linked-file'))
        self.assertFalse([f for f in self.files('saves:1234') if 'linked' in f])

+    def packed(self, part):
+        out = io.BytesIO()
+        remote.pack(part, out)
+        out.seek(0)
+        with tarfile.open(fileobj=out, mode='r:gz') as archive:
+            return {m.name: archive.extractfile(m).read() for m in archive}
+
+    @unittest.skipIf(os.name == 'nt', 'symlinks need privileges on Windows')
+    def test_backup_rejects_every_ancestor_of_a_save_root(self):
+        save = USER % 1234 + '/AppData/Roaming/Game/fixture.dat'
+        # Each component below HOME, including the selected root itself.
+        components = (USER % 1234 + '/AppData/Roaming').split('/')
+        for end in range(1, len(components) + 1):
+            ancestor = '/'.join(components[:end])
+            with self.subTest(ancestor=ancestor), tempfile.TemporaryDirectory() as tmp:
+                home = Path(tmp) / 'home'
+                manifest(home, 1234, 'Synthetic game')
+                path = write(home, save, b'synthetic fixture')
+                linked = home / ancestor
+                outside = Path(tmp) / 'outside/.ssh'
+                outside.parent.mkdir()
+                linked.rename(outside)
+                linked.symlink_to(outside, target_is_directory=True)
+                # Only synthetic bytes: the lexical archive path hides .ssh.
+                self.assertEqual(path.read_bytes(), b'synthetic fixture')
+                with patch.object(remote, 'HOME', home):
+                    self.assertEqual(self.files('saves:1234'), [])
+                    self.assertNotIn('saves:1234', [p['id'] for p in remote.plan()['parts']])
+                    self.assertEqual(self.packed('saves:1234'), {})
+
+    @unittest.skipIf(os.name == 'nt', 'symlinks need privileges on Windows')
+    def test_pack_rechecks_links_changed_after_discovery(self):
+        save = USER % 1234 + '/Documents/Game/fixture.dat'
+        for ancestor in (remote.COMPAT + '/1234', USER % 1234 + '/Documents', save):
+            with self.subTest(ancestor=ancestor), tempfile.TemporaryDirectory() as tmp:
+                home = Path(tmp) / 'home'
+                write(home, save, b'original save')
+                linked = home / ancestor
+                outside = Path(tmp) / 'outside/.ssh'
+                outside.parent.mkdir()
+                part_files = remote.part_files
+
+                def discover_then_link(part):
+                    result = part_files(part)
+                    self.assertEqual(result[0], [(save, len(b'original save'))])
+                    linked.rename(outside)
+                    linked.symlink_to(outside, target_is_directory=outside.is_dir())
+                    (home / save).write_bytes(b'synthetic redirected bytes')
+                    return result
+
+                with patch.object(remote, 'HOME', home), \
+                        patch.object(remote, 'part_files', side_effect=discover_then_link):
+                    self.assertEqual(self.packed('saves:1234'), {})
+
+    def test_legitimate_steam_layout_and_reference_files_still_pack(self):
+        frame_home(self.home)
+        manifest(self.home, 2800000002, 'Synthetic non-Steam game')
+        save = USER % 2800000002 + '/Saved Games/fixture.dat'
+        write(self.home, save, b'non-Steam save')
+        controller = STEAM + '/steamapps/common/Steam Controller Configs/555/config/layout.vdf'
+        write(self.home, controller, b'controller layout')
+        for part in ('saves:1234', 'saves:2800000002', 'saves:linux',
+                     'settings:steam', 'settings:system'):
+            with self.subTest(part=part):
+                expected = {rel: (self.home / rel).read_bytes() for rel in self.files(part)}
+                self.assertTrue(expected)
+                self.assertEqual(self.packed(part), expected)
+        self.assertEqual(self.packed('saves:2800000002'), {save: b'non-Steam save'})
+        self.assertIn(controller, self.packed('settings:steam'))
+
+    @unittest.skipIf(os.name == 'nt', 'symlinks need privileges on Windows')
+    def test_settings_discovery_and_manifest_reads_reject_links(self):
+        frame_home(self.home)
+        for ancestor, part in (('.config', 'settings:system'),
+                               (STEAM + '/userdata', 'settings:steam')):
+            with self.subTest(ancestor=ancestor):
+                linked = self.home / ancestor
+                moved = linked.with_name(linked.name + '-original')
+                linked.rename(moved)
+                linked.symlink_to(moved, target_is_directory=True)
+                self.assertEqual(self.files(part), [])
+                self.assertEqual(self.packed(part), {})
+                if part == 'settings:steam':
+                    self.assertEqual(remote.accounts(), [])
+        appmanifest = self.home / STEAM / 'steamapps/appmanifest_1234.acf'
+        moved = appmanifest.with_suffix('.original')
+        appmanifest.rename(moved)
+        appmanifest.symlink_to(moved)
+        with patch.object(Path, 'read_text', side_effect=AssertionError('must not read a link')):
+            self.assertIsNone(remote.game_name('1234'))
+
+    @unittest.skipIf(os.name == 'nt', 'symlinks need privileges on Windows')
+    def test_home_alias_and_unused_steam_alias_preserve_normal_backups(self):
+        frame_home(self.home)
+        alias = self.home / 'home-alias'
+        alias.symlink_to(self.home, target_is_directory=True)
+        (self.home / '.steam/steam').symlink_to(self.home / STEAM, target_is_directory=True)
+        expected = self.packed('saves:1234')
+        with patch.object(remote, 'HOME', alias):
+            self.assertEqual(self.packed('saves:1234'), expected)
+            self.assertEqual(remote.game_name('1234'), 'Test Game')
+
    def test_big_files_are_listed_as_skipped(self):
        frame_home(self.home)
        with patch.object(remote, 'MAX_FILE', 3):
@@ -0,0 +1,107 @@
+"""Extension compatibility and filesystem boundaries, without running plugin code."""
+import sandbox  # noqa: F401
+import json
+import shutil
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'ui'))
+import frame_extensions
+
+
+class ExtensionFiles(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.root = Path(self.tmp.name) / 'extensions'
+        self.root.mkdir()
+        self.patch = patch.object(frame_extensions, 'root', return_value=self.root)
+        self.patch.start()
+        self.addCleanup(self.patch.stop)
+
+    def extension(self, name='test-panel', **fields):
+        folder = self.root / name
+        folder.mkdir(exist_ok=True)
+        manifest = {'id': name, 'name': 'Test panel', 'version': '1.0.0',
+                    'description': 'A read-only panel', 'entry': 'index.html', **fields}
+        (folder / 'manifest.json').write_text(json.dumps(manifest), encoding='utf-8')
+        (folder / 'index.html').write_text('<script src="main.js"></script>', encoding='utf-8')
+        (folder / 'main.js').write_text('/* extension code */', encoding='utf-8')
+        return folder
+
+    def test_existing_and_explicit_v1_manifests_are_compatible(self):
+        self.extension('legacy')
+        self.extension('explicit', apiVersion=1)
+        result = frame_extensions.list_extensions()
+        self.assertEqual(result['errors'], [])
+        self.assertEqual([(x['id'], x['apiVersion']) for x in result['extensions']],
+                         [('explicit', 1), ('legacy', 1)])
+        self.assertEqual(frame_extensions.asset('explicit', 'main.js'),
+                         (b'/* extension code */', 'text/javascript; charset=utf-8'))
+
+    def test_unsupported_or_malformed_api_cannot_be_loaded_directly(self):
+        for version in (2, 0, -1, '1', None, True, 1.0, [], {}):
+            with self.subTest(apiVersion=version):
+                self.extension(apiVersion=version)
+                result = frame_extensions.list_extensions()
+                self.assertEqual(result['extensions'], [])
+                self.assertIn('unsupported apiVersion', result['errors'][0]['error'])
+                with self.assertRaisesRegex(ValueError, 'unsupported apiVersion'):
+                    frame_extensions.asset('test-panel', 'index.html')
+
+    def test_one_incompatible_extension_does_not_hide_compatible_panels(self):
+        self.extension('future', apiVersion=2)
+        self.extension('working', apiVersion=1)
+        result = frame_extensions.list_extensions()
+        self.assertEqual([x['id'] for x in result['extensions']], ['working'])
+        self.assertEqual(result['errors'][0]['folder'], 'future')
+
+    def test_sample_is_discoverable_and_its_assets_are_served(self):
+        source = Path(__file__).resolve().parents[1] / 'examples/extensions/headset-glance'
+        shutil.copytree(source, self.root / source.name)
+        result = frame_extensions.list_extensions()
+        self.assertEqual(result['errors'], [])
+        self.assertEqual(result['extensions'][0]['id'], source.name)
+        for asset in ('index.html', 'main.js', 'style.css'):
+            self.assertEqual(frame_extensions.asset(source.name, asset)[0],
+                             (source / asset).read_bytes())
+
+    def test_private_nested_and_traversal_paths_are_rejected(self):
+        self.extension()
+        for name in ('manifest.json', '../outside.js', 'sub/main.js', '.hidden.js'):
+            with self.subTest(name=name), self.assertRaises(FileNotFoundError):
+                frame_extensions.asset('test-panel', name)
+        with self.assertRaises(FileNotFoundError):
+            frame_extensions.asset('../test-panel', 'main.js')
+
+    def test_oversized_assets_are_not_read(self):
+        folder = self.extension()
+        with (folder / 'large.js').open('wb') as output:
+            output.truncate(5 * 1024 * 1024 + 1)
+        with self.assertRaises(FileNotFoundError):
+            frame_extensions.asset('test-panel', 'large.js')
+
+    def test_symlinks_cannot_expose_files_outside_a_panel(self):
+        folder = self.extension()
+        outside = Path(self.tmp.name) / 'outside.js'
+        outside.write_text('private file', encoding='utf-8')
+        try:
+            (folder / 'escape.js').symlink_to(outside)
+            (self.root / 'alias').symlink_to(folder, target_is_directory=True)
+        except OSError:
+            self.skipTest('symlinks unavailable for this user')
+        with self.assertRaises(FileNotFoundError):
+            frame_extensions.asset('test-panel', 'escape.js')
+        with self.assertRaises(ValueError):
+            frame_extensions.asset('alias', 'main.js')
+        (folder / 'manifest.json').unlink()
+        (folder / 'manifest.json').symlink_to(outside)
+        with self.assertRaises(ValueError):
+            frame_extensions.asset('test-panel', 'main.js')
+
+
+if __name__ == '__main__':
+    unittest.main()
@@ -0,0 +1,128 @@
+"""Official Decky store transport and owned plugin transaction."""
+import sandbox  # noqa: F401
+import hashlib
+import io
+import json
+import os
+from pathlib import Path
+import secrets
+import subprocess
+import sys
+import tempfile
+import unittest
+from unittest.mock import patch
+import zipfile
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / 'ui'))
+import frame_decky_store
+
+
+def archive(flags=(), extra=None):
+    stream = io.BytesIO()
+    with zipfile.ZipFile(stream, 'w') as bundle:
+        bundle.writestr('Example/plugin.json', json.dumps({'name': 'Example', 'flags': list(flags)}))
+        bundle.writestr('Example/dist/index.js', 'export default {};' + ' ' * 1200)
+        if extra:
+            bundle.writestr(*extra)
+    data = stream.getvalue()
+    return data, hashlib.sha256(data).hexdigest()
+
+
+class ArchiveTests(unittest.TestCase):
+    def test_catalog_selects_valid_visible_latest_versions(self):
+        records = [{'id': 42, 'name': 'Example', 'visible': True, 'versions':
+                    [{'name': '1.0', 'hash': 'a' * 64}], 'tags': []},
+                   {'id': 43, 'name': 'Hidden', 'visible': False, 'versions':
+                    [{'name': '1.0', 'hash': 'b' * 64}]},
+                   {'id': 44, 'name': 'Unsafe', 'visible': True, 'versions':
+                    [{'name': '1.0; touch /tmp/bad', 'hash': 'c' * 64}]}]
+        with patch.object(frame_decky_store.urllib.request, 'urlopen', return_value=io.BytesIO(json.dumps(records).encode())):
+            self.assertEqual([p['id'] for p in frame_decky_store.catalog()], [42])
+
+    def test_accepts_hashed_non_root_archive(self):
+        data, digest = archive()
+        self.assertEqual(frame_decky_store.archive_info(data, digest, 'Example'), 'Example')
+        with self.assertRaisesRegex(ValueError, 'SHA-256'):
+            frame_decky_store.archive_info(data, '0' * 64, 'Example')
+
+    def test_rejects_root_x86_and_escape(self):
+        for data in (archive(flags=['root'])[0],
+                     archive(extra=('Example/bin/helper', b'\x7fELF' + b'\x00' * 14 + (62).to_bytes(2, 'little')))[0],
+                     archive(extra=('../outside', b'oops'))[0]):
+            with self.subTest(data=hashlib.sha256(data).hexdigest()[:8]):
+                with self.assertRaises(ValueError):
+                    frame_decky_store.archive_info(data, hashlib.sha256(data).hexdigest(), 'Example')
+
+
+@unittest.skipIf(os.name == 'nt', 'remote plugin transaction runs on Linux')
+class StoreTransaction(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        home = Path(self.tmp.name)
+        unit = home / '.config/systemd/user/frame-control-decky.service'
+        unit.parent.mkdir(parents=True)
+        unit.write_text('[Service]\n')
+        fake = home / 'systemctl'
+        fake.write_text('#!/bin/sh\nif [ "$2" = is-active ]; then exit 0; fi\nexit 0\n')
+        fake.chmod(0o700)
+        self.env = {**os.environ, 'HOME': self.tmp.name,
+                    'PATH': self.tmp.name + os.pathsep + os.environ['PATH']}
+        self.folder = home / '.local/share/frame-control/decky/plugins/Example'
+        self.folder.parent.mkdir(parents=True)
+
+    def apply(self, action, data=None):
+        token = secrets.token_hex(12)
+        source = Path('/tmp/frame-control-decky-plugin-' + token)
+        if data is not None:
+            source.write_bytes(data)
+        digest = hashlib.sha256(data or b'').hexdigest()
+        try:
+            return subprocess.run([sys.executable, '-', action, token, '42', digest, 'Example', '1.0'],
+                                  input=frame_decky_store.APPLY, text=True, capture_output=True,
+                                  env=self.env, timeout=15)
+        finally:
+            source.unlink(missing_ok=True)
+
+    def test_install_update_remove_only_owned_folder(self):
+        first, _ = archive()
+        result = self.apply('install', first)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(json.loads((self.folder / '.frame-control-store.json').read_text())['storeId'], 42)
+        second, _ = archive(extra=('Example/data.txt', 'new'))
+        result = self.apply('update', second)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual((self.folder / 'data.txt').read_text(), 'new')
+        result = self.apply('remove')
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertFalse(self.folder.exists())
+        self.folder.mkdir()
+        (self.folder / 'plugin.json').write_text('{}')
+        result = self.apply('remove')
+        self.assertNotEqual(result.returncode, 0)
+        self.assertTrue(self.folder.exists())
+        external = Path(self.tmp.name) / 'other-plugin'
+        external.mkdir()
+        (external / '.frame-control-store.json').write_text('{"storeId":42}')
+        for item in self.folder.iterdir(): item.unlink()
+        self.folder.rmdir()
+        self.folder.symlink_to(external, target_is_directory=True)
+        result = self.apply('remove')
+        self.assertNotEqual(result.returncode, 0)
+        self.assertTrue(external.exists())
+
+
+class StoreHost(unittest.TestCase):
+    def test_owned_plugin_can_be_removed_without_store_network(self):
+        state = {'managed': True, 'running': True, 'plugins':
+                 [{'storeId': 42, 'folder': 'Example', 'name': 'Example', 'version': '1.0'}]}
+        def ssh(command, **kwargs):
+            return '{}'
+        with patch.object(frame_decky_store.frame_decky, 'status', return_value=state), \
+             patch.object(frame_decky_store, 'catalog') as network:
+            frame_decky_store.change(ssh, 'remove', 42)
+            network.assert_not_called()
+
+
+if __name__ == '__main__':
+    unittest.main()
@@ -126,6 +126,24 @@ class ServerGuards(unittest.TestCase):
        self.assertEqual(code, 400)
        self.assertIn('experimental', body['error'])

+    def test_incompatible_extension_is_reported_and_assets_are_unavailable(self):
+        folder = Path(os.environ['FRAME_CONTROL_DATA_DIR']) / 'extensions' / 'future-panel'
+        folder.mkdir(parents=True, exist_ok=True)
+        (folder / 'manifest.json').write_text(json.dumps({'id': 'future-panel', 'name': 'Future',
+            'version': '1.0', 'description': 'Requires a newer API', 'apiVersion': 2}))
+        (folder / 'index.html').write_text('<p>Incompatible panel</p>')
+        try:
+            self.assertEqual(self.request('GET', '/api/extensions')[0], 403)
+            code, _, body = self.request('GET', '/api/extensions', headers={'X-Frame-UI': '1'})
+            self.assertEqual(code, 200)
+            data = json.loads(body)
+            self.assertNotIn('future-panel', [x['id'] for x in data['extensions']])
+            self.assertTrue(any(x['folder'] == 'future-panel' and 'apiVersion' in x['error']
+                                for x in data['errors']))
+            self.assertEqual(self.request('GET', '/extension/future-panel/index.html')[0], 404)
+        finally:
+            shutil.rmtree(folder)
+
    def test_headset_page_and_install_acknowledgement(self):
        code, _, body = self.request('GET', '/headset')
        self.assertEqual(code, 200)
@@ -131,10 +131,30 @@ def unpack_bundle(path, root):
        raise android.FrameError('Could not read Android bundle: ' + str(error)) from error
    paths = [str(local) for local, _, _, _ in entries]
    if not any(Path(p).suffix.lower() == '.apk' for p in paths):
-        raise android.FrameError('Android bundles must contain one standalone APK and optional OBB files.')
+        raise android.FrameError('Android bundles must contain a base APK and optional supported splits or OBB files.')
    return paths


+def _apk_identity(path):
+    """Use the manifest, not the filename, to identify a base or split APK."""
+    try:
+        with zipfile.ZipFile(path) as archive:
+            elements = frame_apk.manifest_elements(
+                frame_apk._read(archive, 'AndroidManifest.xml', frame_apk.MAX_MANIFEST))
+        attrs = next((attrs for tag, attrs in elements if tag == 'manifest'), {})
+        package = (attrs.get('package') or (None, None, None))[2]
+        split = (attrs.get('split') or (None, None, None))[2]
+        code = (attrs.get('versionCode') or (None, None, None))[1]
+        major = (attrs.get('versionCodeMajor') or (None, 0, None))[1]
+        if not package or not android.PKG_RE.fullmatch(package):
+            raise android.FrameError(f'{path.name}: no valid package in APK manifest')
+        return package, split, (major, code) if code is not None else None
+    except (zipfile.BadZipFile, frame_apk.ApkError, OSError, UnicodeError,
+            ValueError, RuntimeError, EOFError, zlib.error, struct.error,
+            IndexError) as error:
+        raise android.FrameError(f'Could not read APK manifest in {path.name}: {error}') from error
+
+
 def _check_standalone(path):
    try:
        with zipfile.ZipFile(path) as archive:
@@ -168,19 +188,41 @@ def inspect(paths, discover=False):
        if path.suffix.lower() not in ('.apk', '.obb') or not path.is_file() or path.stat().st_size == 0:
            raise android.FrameError(f'{path.name}: choose a nonempty APK or .obb game-data file.')
    apks = [p for p in files if p.suffix.lower() == '.apk']
-    if len(apks) > 1:
-        raise android.FrameError('Choose one game at a time. Split APK backups are not supported by this importer.')
-    apk = apks[0] if apks else None
+    apk, splits = None, []
+    if apks:
+        identities = [(p, *_apk_identity(p)) for p in apks]
+        bases = [p for p, _, split, _ in identities if not split]
+        if len(bases) != 1:
+            raise android.FrameError('Choose one game at a time: exactly one base APK is required.')
+        apk = bases[0]
+        package, version = next((pkg, code) for p, pkg, _, code in identities if p == apk)
+        split_names = set()
+        for path, pkg, split, code in identities:
+            if path == apk:
+                continue
+            if pkg != package or split in split_names:
+                raise android.FrameError('Split APKs must have the same package and distinct split names.')
+            if version is None or code is None or code != version:
+                raise android.FrameError('Split APK version cannot be verified against the base APK.')
+            split_names.add(split)
+            splits.append(path)
    if apk:
-        _check_standalone(apk)
+        if not splits:
+            _check_standalone(apk)
        info = android.apk_info(str(apk))
-        try:
-            android.check_installable(info)
-        except android.FrameError as error:
-            error.apk = {'package': info['package'], 'version_code': info.get('version_code'),
-                         'blocker': str(error)}
-            raise
-        checked = quest.inspect(info['package'], str(apk))
+        if not splits:
+            try:
+                android.check_installable(info)
+            except android.FrameError as error:
+                error.apk = {'package': info['package'], 'version_code': info.get('version_code'),
+                             'blocker': str(error)}
+                raise
+        if splits:
+            added = android.split_entries(str(apk), [str(p) for p in splits])
+            if any(name.startswith('lib/') and not name.startswith('lib/arm64-v8a/') for name in added):
+                raise android.FrameError('This split set includes native libraries for another device. '
+                                         'Choose only the arm64-v8a split for the Frame.')
+        checked = quest.inspect(info['package'], str(apk), [str(p) for p in splits])
        pkg = checked['package']
        if discover and len(files) == 1:
            files.extend(p for p in sorted(apk.parent.iterdir())
@@ -213,13 +255,14 @@ def inspect(paths, discover=False):
        if not path.is_file() or not path.stat().st_size or path.name in names:
            raise android.FrameError(f'{path.name}: game-data files must be nonempty and have unique names.')
        names.add(path.name)
-    return {'apk': apk, 'obb': obb, 'checked': checked,
+    return {'apk': apk, 'splits': splits, 'obb': obb, 'checked': checked,
            'signatures': {str(p): (p.stat().st_size, p.stat().st_mtime_ns) for p in [*apks, *obb]}}


 def public(plan):
    checked = plan['checked']
    return {**checked, 'apk': plan['apk'].name if plan['apk'] else None,
+            'splits': [p.name for p in plan['splits']],
            'obb': [{'name': p.name, 'size': p.stat().st_size} for p in plan['obb']],
            'size': sum(size for size, _ in plan['signatures'].values())}

@@ -243,7 +286,8 @@ def install(plan, display='auto', progress=None):
            quest._check_downgrade(android.read_meta(pkg), checked, False)
            report('Installing the game app', 15)
            meta = android.install(str(plan['apk']), source=plan['apk'].name,
-                                   flatscreen=None if display == 'auto' else display == 'flat')
+                                   flatscreen=None if display == 'auto' else display == 'flat',
+                                   splits=[str(p) for p in plan['splits']])
        else:
            meta = android._meta_or_fail(pkg)
        if not plan['obb']:
@@ -16,9 +16,9 @@ saved Steam clips to ~/Videos/SteamFrame.
 - When the headset can't be reached it waits longer each time, up to MAX_BACKOFF.

 The server supplies how to reach the headset, so this can be tested without one:
-  list_shots() -> {"shots": [{"id", "time", "saved"}...]}
+  list_shots(device) -> {"shots": [{"id", "time", "saved"}...]}
  save_shots(device, ids) copies those screenshots here
-  list_clips() -> {"clips": [{"id", "kind", "time", "idle", "saved"}...]}
+  list_clips(device) -> {"clips": [{"id", "kind", "time", "idle", "saved"}...]}
  export_clip(device, id) exports one clip here
  device() -> the connected headset's id, or None
  busy() -> True while other work runs on the headset (installs, jobs, a recording)
@@ -41,7 +41,7 @@ SETTLE = 30  # a clip written to within this many seconds is still being recorde
 MIN_FREE = 512 * 1024**2  # pause below this much free space on this computer
 KEEP = 5000  # copied ids remembered per headset and kind
 BATCH = 100  # screenshots per copy
-TRIES = 3  # an item that fails this often is left until the app restarts
+TRIES = 3  # failed attempts per item until Resume, Copy everything now, or restart
 KINDS = ("shots", "clips")


@@ -86,6 +86,7 @@ class AutoSync:
        self._running = False
        self._backoff = 0
        self._tries = {}  # (device, id) -> failed attempts this run
+        self._failures = {}  # last error for each failed item, including exhausted retries
        self._errors = []  # this pass's, for the page
        self._s = self._load()

@@ -143,13 +144,19 @@ class AutoSync:
        """Copy everything on the headset that isn't on this computer, once (also resumes)."""
        with self._lock:
            self._all, self._s["paused"] = True, None
+            self._tries.clear()
+            self._failures.clear()
+            self._s["error"] = None
            self._save()
+        self._backoff = 0
        self._wake.set()
        return self.state()

    def resume(self):
        with self._lock:
            self._s["paused"], self._s["error"] = None, None
+            self._tries.clear()
+            self._failures.clear()
            self._save()
        self._backoff = 0
        self._wake.set()
@@ -215,6 +222,9 @@ class AutoSync:

    def _mark(self, device, kind, ids):
        with self._lock:
+            for item in ids:
+                self._tries.pop((device, item), None)
+                self._failures.pop((device, item), None)
            per = self._s["synced"].setdefault(device, {})
            have = per.get(kind, [])
            new = [i for i in ids if i not in set(have)]
@@ -233,24 +243,46 @@ class AutoSync:
                           "then press Resume.")
        if self.offline(error):
            raise error
-        key = (device, item)
-        self._tries[key] = self._tries.get(key, 0) + 1
-        self._errors.append(f"Couldn't copy {item.rsplit('/', 1)[-1]}: {error}")
+        with self._lock:
+            key = (device, item)
+            self._tries[key] = self._tries.get(key, 0) + 1
+            message = f"Couldn't copy {item.rsplit('/', 1)[-1]}: {error}"
+            if self._tries[key] >= TRIES:
+                message += ". Automatic retries stopped. Press Resume to try again."
+            self._failures[key] = message
+            self._errors.append(message)
+
+    def _retry_allowed(self, device, item):
+        with self._lock:
+            key = (device, item)
+            if self._tries.get(key, 0) < TRIES:
+                return True
+            self._errors.append(self._failures[key])
+            return False
+
+    def _interrupted(self, device):
+        return self.busy() or self.device() != device

    def _pass(self, device, shots, clips, since):
        """-> (copied, clips still being written, finished without stopping for other work)."""
        copied = waiting = 0
        if shots:
-            listing = self.list_shots()["shots"]
+            if self._interrupted(device):
+                return copied, waiting, False
+            listing = self.list_shots(device)["shots"]
+            if self._interrupted(device):
+                return copied, waiting, False
            done = self._synced(device, "shots")
            self._mark(device, "shots", [s["id"] for s in listing if s.get("saved")])
            todo = [s["id"] for s in sorted(listing, key=lambda s: s["time"])
                    if not s.get("saved") and (since is None or (s["time"] >= since and s["id"] not in done))
-                    and self._tries.get((device, s["id"]), 0) < TRIES]
+                    and self._retry_allowed(device, s["id"])]
            for i in range(0, len(todo), BATCH):
-                if self.busy():
+                if self._interrupted(device):
                    return copied, waiting, False
                self._room(self.shots_folder)
+                if self._interrupted(device):
+                    return copied, waiting, False
                batch = todo[i:i + BATCH]
                try:
                    self.save_shots(device, batch)
@@ -258,28 +290,40 @@ class AutoSync:
                    for item in batch:
                        self._failed(device, item, e)
                    continue
+                if self.device() != device:
+                    return copied, waiting, False
                self._mark(device, "shots", batch)
                copied += len(batch)
        if clips:
-            listing = [c for c in self.list_clips()["clips"] if c.get("kind") == "clip"]
+            if self._interrupted(device):
+                return copied, waiting, False
+            listing = [c for c in self.list_clips(device)["clips"] if c.get("kind") == "clip"]
+            if self._interrupted(device):
+                return copied, waiting, False
            done = self._synced(device, "clips")
            self._mark(device, "clips", [c["id"] for c in listing if c.get("saved")])
            for c in sorted(listing, key=lambda c: c["time"]):
-                if c.get("saved") or self._tries.get((device, c["id"]), 0) >= TRIES:
+                if c.get("saved"):
                    continue
                if since is not None and (c["time"] < since or c["id"] in done):
                    continue
+                if not self._retry_allowed(device, c["id"]):
+                    continue
                if c.get("idle") is None or c["idle"] < SETTLE:
                    waiting += 1  # still being written: copied on a later look
                    continue
-                if self.busy():
+                if self._interrupted(device):
                    return copied, waiting, False
                self._room(self.clips_folder)
+                if self._interrupted(device):
+                    return copied, waiting, False
                try:
                    self.export_clip(device, c["id"])
                except Exception as e:
                    self._failed(device, c["id"], e)
                    continue
+                if self.device() != device:
+                    return copied, waiting, False
                self._mark(device, "clips", [c["id"]])
                copied += 1
        return copied, waiting, True
@@ -19,6 +19,7 @@ import os
 from pathlib import Path, PurePosixPath
 import re
 import shutil
+import stat
 import subprocess
 import sys
 import tarfile
@@ -88,28 +89,57 @@ def _under(rel, root):
    return rel == root or rel.startswith(root + '/')


+def _backup_stat(rel):
+    """lstat a backup path only if every component below trusted HOME is link-free.
+
+    Rechecked at discovery and before reads; not atomic against concurrent renames.
+    HOME itself may use the host's normal home/temp-directory aliases.
+    """
+    if not safe_rel(rel):
+        return None
+    path = HOME
+    try:
+        for component in rel.split('/'):
+            path = path / component
+            st = path.lstat()
+            if stat.S_ISLNK(st.st_mode):
+                return None
+        return st
+    except OSError:
+        return None
+
+
+def _backup_dir(rel):
+    st = _backup_stat(rel)
+    return st is not None and stat.S_ISDIR(st.st_mode)
+
+
 def _walk(rel_root, skip=()):
    """Regular files under HOME/rel_root, never following links: [(rel, size)], [skipped]."""
    files, skipped = [], []
    base = HOME / rel_root
-    if base.is_symlink() or not base.is_dir():
-        if base.is_file() and not base.is_symlink():
-            return [(rel_root, base.stat().st_size)], skipped
+    st = _backup_stat(rel_root)
+    if st is None or is_secret(rel_root):
+        return files, skipped
+    if stat.S_ISREG(st.st_mode):
+        if st.st_size > MAX_FILE:
+            skipped.append({'path': rel_root, 'reason': 'over 2 GiB'})
+            return files, skipped
+        return [(rel_root, st.st_size)], skipped
+    if not stat.S_ISDIR(st.st_mode):
        return files, skipped
    for top, dirs, names in os.walk(str(base)):
        rel_top = PurePosixPath(rel_root, *Path(top).relative_to(base).parts).as_posix()
-        dirs[:] = sorted(d for d in dirs if not os.path.islink(os.path.join(top, d)) and
+        if not _backup_dir(rel_top):
+            dirs[:] = []
+            continue
+        dirs[:] = sorted(d for d in dirs if _backup_dir(rel_top + '/' + d) and
                         not any(_under(rel_top + '/' + d, s) for s in skip) and
                         not is_secret(rel_top + '/' + d + '/x'))
        for name in sorted(names):
-            path, rel = os.path.join(top, name), rel_top + '/' + name
-            if os.path.islink(path) or is_secret(rel):
-                continue
-            try:
-                st = os.lstat(path)
-            except OSError:
-                continue
-            if not os.path.isfile(path):
+            rel = rel_top + '/' + name
+            st = _backup_stat(rel)
+            if st is None or not stat.S_ISREG(st.st_mode) or is_secret(rel):
                continue
            if st.st_size > MAX_FILE:
                skipped.append({'path': rel, 'reason': 'over 2 GiB'})
@@ -124,26 +154,34 @@ def _manifest_field(text, key):


 def game_name(appid):
+    rel = '%s/steamapps/appmanifest_%s.acf' % (STEAM, appid)
+    st = _backup_stat(rel)
+    if st is None or not stat.S_ISREG(st.st_mode):
+        return None
    try:
-        text = (HOME / STEAM / 'steamapps' / ('appmanifest_%s.acf' % appid)).read_text(errors='replace')
+        text = (HOME / rel).read_text(errors='replace')
    except OSError:
        return None
    return _manifest_field(text, 'name')


 def accounts():
-    root = HOME / STEAM / 'userdata'
+    rel = STEAM + '/userdata'
+    if not _backup_dir(rel):
+        return []
    try:
-        return sorted(p.name for p in root.iterdir() if p.name.isdigit() and p.is_dir()
-                      and not p.is_symlink() and p.name != '0')
+        return sorted(p.name for p in (HOME / rel).iterdir() if p.name.isdigit() and
+                      p.name != '0' and _backup_dir(rel + '/' + p.name))
    except OSError:
        return []


 def _prefixes():
+    if not _backup_dir(COMPAT):
+        return []
    try:
        return sorted((p.name for p in (HOME / COMPAT).iterdir()
-                       if p.name.isdigit() and (p / PREFIX_USER).is_dir()), key=int)
+                       if p.name.isdigit() and _backup_dir(COMPAT + '/' + p.name + '/' + PREFIX_USER)), key=int)
    except OSError:
        return []

@@ -244,9 +282,14 @@ def pack(part, output):
    with tarfile.open(fileobj=output, mode='w|gz') as archive:
        for rel, _ in files:
            path = HOME / rel
+            st = _backup_stat(rel)
+            if st is None or not stat.S_ISREG(st.st_mode) or is_secret(rel):
+                continue
            try:
                with open(str(path), 'rb') as src:
                    st = os.fstat(src.fileno())
+                    if not stat.S_ISREG(st.st_mode) or st.st_size > MAX_FILE:
+                        continue
                    member = tarfile.TarInfo(rel)
                    member.size, member.mtime, member.mode = st.st_size, int(st.st_mtime), st.st_mode & 0o755
                    archive.addfile(member, src)
@@ -31,8 +31,14 @@ def plugins(folder):
            if info.is_symlink() or not info.is_file() or info.stat().st_size > 16384: continue
            try:
                data = json.loads(info.read_text())
+                marker = child / '.frame-control-store.json'
+                try:
+                    owned = json.loads(marker.read_text()) if marker.is_file() and not marker.is_symlink() else {}
+                except (OSError, ValueError): owned = {}
                found.append({'folder': child.name, 'name': str(data.get('name', child.name))[:80],
-                              'author': str(data.get('author', ''))[:80]})
+                              'author': str(data.get('author', ''))[:80],
+                              'storeId': owned.get('storeId') if isinstance(owned.get('storeId'), int) else None,
+                              'version': str(owned.get('version', ''))[:40]})
            except (ValueError, OSError, UnicodeError): pass
    return found
 os_release = {}
@@ -0,0 +1,197 @@
+"""Verified official-store archives for the opt-in Frame Decky user service.
+
+Only Frame Control owned plugin folders can be updated or removed. The store
+digest validates transport, not plugin trust; store plugins run as the user.
+"""
+import hashlib
+import io
+import json
+import re
+import secrets
+import urllib.request
+import zipfile
+
+import frame_decky
+
+
+STORE_URL = 'https://plugins.deckbrew.xyz/plugins'
+CDN = 'https://cdn.tzatzikiweeb.moe/file/steam-deck-homebrew/versions/'
+MAX_STORE = 4 * 1024 * 1024
+MAX_ZIP = 50 * 1024 * 1024
+MAX_UNPACKED = 150 * 1024 * 1024
+SAFE_FOLDER = re.compile(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\Z')
+SHA = re.compile(r'[0-9a-f]{64}\Z')
+VERSION = re.compile(r'[A-Za-z0-9][A-Za-z0-9._+\-]{0,39}\Z')
+
+
+def catalog():
+    request = urllib.request.Request(STORE_URL, headers={'User-Agent': 'Frame-Control'})
+    with urllib.request.urlopen(request, timeout=15) as response:
+        raw = response.read(MAX_STORE + 1)
+    if len(raw) > MAX_STORE:
+        raise ValueError('Decky store response is too large')
+    records = json.loads(raw)
+    if not isinstance(records, list):
+        raise ValueError('Invalid Decky store response')
+    result = []
+    for item in records:
+        if not isinstance(item, dict) or item.get('visible') is False:
+            continue
+        versions = item.get('versions')
+        if type(item.get('id')) is not int or item['id'] <= 0 or not isinstance(item.get('name'), str) or not isinstance(versions, list):
+            continue
+        latest = next((v for v in versions if isinstance(v, dict) and isinstance(v.get('name'), str)
+                       and VERSION.fullmatch(v['name']) and isinstance(v.get('hash'), str) and SHA.fullmatch(v['hash'])), None)
+        if not latest:
+            continue
+        tags = item.get('tags') if isinstance(item.get('tags'), list) else []
+        result.append({'id': item['id'], 'name': item['name'][:100],
+                       'description': str(item.get('description') or '')[:300],
+                       'version': latest['name'][:40], 'sha256': latest['hash'],
+                       'root': 'root' in tags})
+    return result
+
+
+def archive_info(data, expected_hash, expected_name):
+    if not 1024 < len(data) <= MAX_ZIP or hashlib.sha256(data).hexdigest() != expected_hash:
+        raise ValueError('Plugin archive size or SHA-256 did not match the store')
+    with zipfile.ZipFile(io.BytesIO(data)) as archive:
+        files = archive.infolist()
+        if not files or len(files) > 3000 or sum(f.file_size for f in files) > MAX_UNPACKED:
+            raise ValueError('Plugin archive exceeds the file or size limit')
+        names = [f.filename for f in files]
+        manifests = [n for n in names if n.count('/') == 1 and n.endswith('/plugin.json')]
+        if len(manifests) != 1:
+            raise ValueError('Plugin archive needs one top-level manifest')
+        folder = manifests[0].split('/')[0]
+        if not SAFE_FOLDER.fullmatch(folder):
+            raise ValueError('Invalid plugin folder')
+        for entry in files:
+            name = entry.filename
+            mode = entry.external_attr >> 16
+            if ('\\' in name or name.startswith('/') or '..' in name.split('/') or
+                name.split('/')[0] != folder or entry.file_size > 30 * 1024 * 1024 or
+                mode & 0o170000 == 0o120000):
+                raise ValueError('Unsafe plugin archive member')
+            if entry.is_dir():
+                continue
+            with archive.open(entry) as source:
+                header = source.read(20)
+            if header[:4] == b'\x7fELF' and int.from_bytes(header[18:20], 'little') != 183:
+                raise ValueError('Plugin contains a non-ARM64 Linux binary: ' + name)
+            if header[:2] == b'MZ':
+                raise ValueError('Plugin contains a Windows binary: ' + name)
+        manifest = json.loads(archive.read(manifests[0]))
+        if manifest.get('name') != expected_name:
+            raise ValueError('Plugin name differs from the official store')
+        flags = manifest.get('flags', [])
+        if not isinstance(flags, list) or not all(isinstance(flag, str) for flag in flags):
+            raise ValueError('Invalid plugin flags')
+        if 'root' in flags or '_root' in flags:
+            raise ValueError('This plugin needs root and is not supported by the Frame user service')
+        return folder
+
+
+APPLY = r'''
+import hashlib,json,pathlib,shutil,subprocess,sys,zipfile
+action,token,plugin_id,digest,folder,version = sys.argv[1:]
+base=pathlib.Path.home()/'.local/share/frame-control/decky/plugins'
+unit=pathlib.Path.home()/'.config/systemd/user/frame-control-decky.service'
+target=base/folder
+archive=pathlib.Path('/tmp/frame-control-decky-plugin-'+token)
+stage=base/('.frame-control-stage-'+token)
+backup=base/('.frame-control-old-'+token)
+marker='.frame-control-store.json'
+def owned():
+    if target.is_symlink() or not target.is_dir(): return False
+    try: return json.loads((target/marker).read_text()).get('storeId') == int(plugin_id)
+    except (OSError,ValueError): return False
+def service(*args):
+    p=subprocess.run(['systemctl','--user',*args],capture_output=True,text=True,timeout=25)
+    if p.returncode: raise RuntimeError((p.stderr or p.stdout).strip()[-400:] or 'Decky service failed')
+if not unit.is_file(): raise RuntimeError('Install Frame Control managed Decky first')
+if action not in ('install','update','remove'): raise RuntimeError('Invalid plugin action')
+if action=='install' and (target.exists() or target.is_symlink()): raise RuntimeError('Plugin folder already exists')
+if action in ('update','remove') and not owned(): raise RuntimeError('Only a Frame Control store plugin can be changed')
+running=subprocess.run(['systemctl','--user','is-active','--quiet','frame-control-decky.service']).returncode==0
+try:
+    if action!='remove':
+        data=archive.read_bytes()
+        if not 1024<len(data)<=50*1024*1024 or hashlib.sha256(data).hexdigest()!=digest:
+            raise RuntimeError('Plugin archive digest mismatch on Frame')
+        with zipfile.ZipFile(archive) as z:
+            files=z.infolist()
+            if not files or len(files)>3000 or sum(f.file_size for f in files)>150*1024*1024:
+                raise RuntimeError('Plugin archive too large')
+            if any(f.filename.split('/')[0]!=folder or f.filename.startswith('/') or
+                   '..' in f.filename.split('/') or '\\' in f.filename or
+                   f.file_size>30*1024*1024 or f.external_attr>>16&0o170000==0o120000 for f in files):
+                raise RuntimeError('Unsafe plugin archive')
+            stage.mkdir(mode=0o700)
+            z.extractall(stage)
+            unpacked=stage/folder
+            if not unpacked.is_dir(): raise RuntimeError('Missing plugin folder')
+            (unpacked/marker).write_text(json.dumps({'storeId':int(plugin_id),'sha256':digest,'version':version})+'\n')
+    if running: service('stop','frame-control-decky.service')
+    try:
+        if action!='install': target.rename(backup)
+        if action!='remove': (stage/folder).rename(target)
+        if running: service('start','frame-control-decky.service')
+    except Exception:
+        if target.exists(): shutil.rmtree(target)
+        if backup.exists(): backup.rename(target)
+        if running: subprocess.run(['systemctl','--user','start','frame-control-decky.service'],timeout=25)
+        raise
+    if backup.exists(): shutil.rmtree(backup)
+    past={'install':'Installed','update':'Updated','remove':'Removed'}[action]
+    print(json.dumps({'message':f'{past} {folder}. Plugin UI in VR is not yet verified.'}))
+finally:
+    archive.unlink(missing_ok=True)
+    if stage.exists(): shutil.rmtree(stage)
+'''
+
+
+def change(ssh, action, plugin_id):
+    if action not in ('install', 'update', 'remove') or type(plugin_id) is not int or plugin_id <= 0:
+        raise ValueError('Choose a valid store plugin action')
+    state = frame_decky.status(ssh)
+    if not state['managed'] or not state['running']:
+        raise ValueError('Start Frame Control managed Decky before changing plugins')
+    installed = [p for p in state['plugins'] if p.get('storeId') == plugin_id]
+    if action == 'remove':
+        if len(installed) != 1:
+            raise ValueError('Only an installed Frame Control store plugin can be removed')
+        folder = installed[0]['folder']
+        plugin = {'sha256': '0' * 64, 'version': 'removed'}
+    else:
+        plugin = next((item for item in catalog() if item['id'] == plugin_id), None)
+        if not plugin:
+            raise ValueError('Plugin is not in the official Decky store')
+        if plugin['root']:
+            raise ValueError('Root plugins are not supported by the Frame user service')
+        existing_name = [p for p in state['plugins'] if p.get('name') == plugin['name']]
+        if action == 'install' and existing_name:
+            raise ValueError('A plugin with this name is already installed')
+        if action == 'update' and len(installed) != 1:
+            raise ValueError('Only an installed Frame Control store plugin can be updated')
+    data = None
+    if action != 'remove':
+        url = CDN + plugin['sha256'] + '.zip'
+        with urllib.request.urlopen(urllib.request.Request(url, headers={'User-Agent': 'Frame-Control'}), timeout=35) as response:
+            data = response.read(MAX_ZIP + 1)
+        folder = archive_info(data, plugin['sha256'], plugin['name'])
+        if action == 'update' and installed[0]['folder'] != folder:
+            raise ValueError('The store changed its plugin folder; remove the old version before installing')
+    if not SAFE_FOLDER.fullmatch(folder):
+        raise ValueError('Unsafe installed plugin folder')
+    token = secrets.token_hex(12)
+    remote = '/tmp/frame-control-decky-plugin-' + token
+    try:
+        if data is not None:
+            ssh('umask 077; cat > ' + remote, stdin=data, text=False, timeout=120)
+        return json.loads(ssh(f'python3 - {action} {token} {plugin_id} {plugin["sha256"]} {folder} {plugin["version"]}',
+                              stdin=APPLY, timeout=90))
+    finally:
+        if data is not None:
+            try: ssh('rm -f ' + remote, timeout=10)
+            except Exception: pass
@@ -7,6 +7,7 @@ import frame_host


 ID = re.compile(r"[a-z][a-z0-9-]{0,39}\Z")
+API_VERSION = 1
 ASSET = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*\Z")
 TYPES = {".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8",
         ".css": "text/css; charset=utf-8", ".json": "application/json",
@@ -27,6 +28,11 @@ def _manifest(folder):
    data = json.loads(manifest.read_text(encoding="utf-8"))
    if not isinstance(data, dict) or data.get("id") != folder.name:
        raise ValueError("manifest id must match its folder")
+    # Older manifests predate this field and use bridge v1. Check again when
+    # serving assets, so an incompatible panel cannot bypass discovery.
+    api_version = data.get("apiVersion", 1)
+    if type(api_version) is not int or api_version != API_VERSION:
+        raise ValueError(f"unsupported apiVersion; this app supports {API_VERSION}")
    for key, limit in (("name", 80), ("version", 40), ("description", 240)):
        value = data.get(key)
        if not isinstance(value, str) or not value.strip() or len(value) > limit:
@@ -34,7 +40,8 @@ def _manifest(folder):
    entry = data.get("entry", "index.html")
    if entry != "index.html" or (folder / entry).is_symlink() or not (folder / entry).is_file():
        raise ValueError("entry must be a regular index.html")
-    return {key: data[key] for key in ("id", "name", "version", "description")}
+    return {**{key: data[key] for key in ("id", "name", "version", "description")},
+            "apiVersion": api_version}


 def list_extensions():
@@ -27,6 +27,10 @@ iframe{display:block;width:100%;height:560px;background:#0d1925;border:1px solid
 <p id="actionStatus" role="status" aria-live="polite"></p>
 <h2>Running games</h2><div class="row"><button id="gamesRefresh" class="secondary">Refresh games</button></div>
 <div id="games" class="stack" style="margin-top:12px">Loading…</div>
+<h2>Decky plugins</h2><p>Manage official store plugins here. Their backend can run on Frame, but Decky's Steam Deck Quick Access Menu is absent from this VR shell. Plugin pages, settings, routes, and toasts are not yet available in this panel.</p>
+<div class="row"><button id="deckyRefresh" class="secondary">Refresh plugins</button><button id="deckyStoreLoad" class="secondary">Open official store</button></div>
+<p id="deckyState" role="status"></p><div id="deckyInstalled" class="stack"></div>
+<div id="deckyStorePanel" hidden><label>Find a plugin <input id="deckySearch" type="search" placeholder="Search Decky store"></label><div id="deckyStoreList" class="stack"></div></div>
 <h2>Extensions</h2><p>Local additions run only when opened in the isolated panel below. They can read status but cannot change headset settings through the extension API.</p>
 <div class="row"><button id="extensionsRefresh" class="secondary">Refresh extensions</button><span id="extensionsFolder"><small></small></span></div>
 <div id="extensions" class="stack" style="margin-top:12px">Loading…</div>
@@ -61,6 +65,34 @@ async function refreshGames(){const list=byId('games');try{const data=await api(
      catch(error){byId('actionStatus').textContent=error.message;quit.disabled=false;}};
    row.append(name,quit);list.append(row);}if(!data.running.length)list.textContent='No games are running.';
  }catch(error){list.textContent=error.message;}}
+let deckyState=null, deckyStore=[];
+async function refreshDecky(){try{deckyState=await api('/api/decky');
+  byId('deckyState').textContent=deckyState.running?'Decky loader is running. Backend loading is not a VR menu check.':'Decky is not running. Install it from Frame Control on your computer.';
+  const list=byId('deckyInstalled');list.replaceChildren();
+  for(const plugin of deckyState.plugins||[]){const row=document.createElement('div');row.className='block';
+    const name=document.createElement('strong');name.textContent=`${plugin.name} ${plugin.version||''}`;row.append(name);
+    if(plugin.storeId){const button=document.createElement('button');button.className='danger';button.textContent='Remove';
+      button.onclick=()=>deckyChange('remove',{id:plugin.storeId,name:plugin.name});row.append(button);}
+    list.append(row);}if(!deckyState.plugins?.length)list.textContent='No managed plugins installed.';
+  showDeckyStore();}catch(error){byId('deckyState').textContent=error.message;}}
+async function loadDeckyStore(){try{const data=await api('/api/decky/store');deckyStore=data.plugins;
+  byId('deckyStorePanel').hidden=false;showDeckyStore();}catch(error){byId('deckyState').textContent=error.message;}}
+function showDeckyStore(){const list=byId('deckyStoreList');list.replaceChildren();
+  const q=byId('deckySearch').value.trim().toLowerCase();
+  for(const plugin of deckyStore.filter(p=>!q||`${p.name} ${p.description}`.toLowerCase().includes(q)).slice(0,30)){
+    const row=document.createElement('div');row.className='block game';
+    const label=document.createElement('span');label.textContent=`${plugin.name} ${plugin.version} · ${plugin.description}`;
+    const button=document.createElement('button');button.textContent='Install';
+    const installed=(deckyState?.plugins||[]).find(p=>p.storeId===plugin.id);
+    if(installed)button.textContent=installed.version===plugin.version?'Reinstall':'Update';
+    button.disabled=!deckyState?.running||plugin.root;
+    if(plugin.root)label.textContent+=' · Needs root; not supported on Frame';
+    button.onclick=()=>deckyChange(installed?'update':'install',plugin);row.append(label,button);list.append(row);}}
+async function deckyChange(action,plugin){if(!confirm(`${action} ${plugin.name}? Store plugins run code as your Frame user.`))return;
+  byId('deckyState').textContent=`${action} ${plugin.name}…`;
+  try{const job=await api('/api/decky/plugin',{action,id:plugin.id,acknowledged:true});
+    byId('deckyState').textContent=job.message||'Request queued. Refresh after it finishes.';
+    setTimeout(refreshDecky,5000);}catch(error){byId('deckyState').textContent=error.message;}}
 async function refreshRecord(){try{const data=await api('/api/record');
  byId('record').textContent=['recording','starting'].includes(data.state)?'Stop recording':'Start recording';
  byId('record').disabled=recordBusy||['stopping','saving'].includes(data.state);
@@ -84,6 +116,7 @@ async function refreshExtensions(){const list=byId('extensions');try{const data=
  }catch(error){list.textContent=error.message;}}
 byId('refresh').onclick=refresh;byId('gameMode').onclick=()=>act('game-mode');byId('screenshot').onclick=()=>act('screenshot');
 byId('gamesRefresh').onclick=refreshGames;byId('record').onclick=toggleRecord;byId('extensionsRefresh').onclick=refreshExtensions;
+byId('deckyRefresh').onclick=refreshDecky;byId('deckyStoreLoad').onclick=loadDeckyStore;byId('deckySearch').oninput=showDeckyStore;
 byId('extensionClose').onclick=()=>{activeExtension=null;byId('extensionFrame').removeAttribute('src');byId('extensionPanel').hidden=true;};
 window.addEventListener('message',event=>{if(!activeExtension||event.source!==byId('extensionFrame').contentWindow)return;
  const request=event.data;if(!request||request.type!=='frame-control:request'||!Number.isSafeInteger(request.id))return;
@@ -92,6 +125,6 @@ window.addEventListener('message',event=>{if(!activeExtension||event.source!==by
    os:{version:latestStatus?.os?.version||null,build:latestStatus?.os?.build||null},
    battery:{percent:latestStatus?.battery?.percent??null},steamvr:!!latestStatus?.services?.steamvr};
  else return;event.source.postMessage({type:'frame-control:response',id:request.id,value},'*');});
-refresh();refreshGames();refreshRecord();refreshExtensions();
+refresh();refreshGames();refreshRecord();refreshExtensions();refreshDecky();
 setInterval(()=>{if(!document.hidden){refresh();refreshRecord();}},15000);
 </script></body></html>
@@ -1373,7 +1373,7 @@
      <div class="store-owned" id="storeOwned">
      <section class="panel" id="androidBackup">
        <div class="shelf-head"><h2>Import Android game</h2></div>
-        <p class="sub">Have a backup? Choose the game's APK and all its .obb files together, or one XAPK/APKS/APKM bundle containing a standalone APK. Split sets and Android/data restore are not supported here.
+        <p class="sub">Have a backup? Choose the game's base APK, supported native-library or asset splits, and all its .obb files together, or one XAPK/APKS/APKM bundle. Resource, code and feature splits and Android/data restore are not supported here.
          Frame Control installs the app and puts its data in the right place.</p>
        <button class="action small" id="androidBackupChoose">Choose game files…</button>
        <input type="file" id="androidBackupInput" accept=".apk,.obb,.xapk,.apks,.apkm" multiple hidden>
@@ -1453,9 +1453,15 @@
    <p class="sub">Experimental. Decky's ARM64 backend can start on Frame OS, but its plugin menu has not been verified in the VR shell. Some Decky plugins need root and will not work with this user service.</p>
    <div id="deckyState" class="sub">Checking…</div>
    <div id="deckyPlugins" class="hint"></div>
+    <div id="deckyManagedList" class="stack"></div>
    <label class="popt"><input type="checkbox" id="deckyAck"> I understand that the VR menu and individual plugins may not work. Install only if I want to test Decky.</label>
    <div class="row" style="margin-top:10px"><button class="small action" id="deckyInstall" disabled>Install</button><button class="small" id="deckyUpdate" disabled>Update</button><button class="small danger" id="deckyRemove" disabled>Remove managed Decky</button></div>
    <div class="hint">Install and update download Decky's official ARM64 release and verify its published SHA-256. Frame Control uses a removable user service and does not change the root filesystem. Remove keeps plugin files.</div>
+    <h3>Official plugin store</h3>
+    <p class="sub">Plugins run code as your Frame user. Store installs are opt-in and only work with the managed loader. Root plugins and x86-only archives are blocked. A loaded backend does not prove its VR page works.</p>
+    <label>Find a plugin <input id="deckyStoreSearch" type="search" placeholder="Search store"></label>
+    <div class="row"><button class="small" id="deckyStoreRefresh">Load store</button></div>
+    <div id="deckyStoreState" class="hint"></div><div id="deckyStoreList" class="stack"></div>
  </section>
  <section class="panel" id="headsetPanel">
    <div class="shelf-head"><h2>Frame Control in VR</h2><span class="spacer"></span><button class="small" id="headsetRefresh">Refresh</button></div>
@@ -1916,7 +1922,7 @@
 </main>
 </div>
 <div class="dropzone" id="dropzone" hidden><div><b>Drop to send to the Frame</b>
-  <span class="sub">Android backups: drop an APK with its OBB files, or one XAPK/APKS/APKM bundle (standalone APK only).
+  <span class="sub">Android backups: drop a base APK with supported splits and OBB files, or one XAPK/APKS/APKM bundle.
  Other files go to <code>~/Downloads</code>;
  a game's <code>.zip</code>, folder or <code>.exe</code> becomes a Steam library title.</span></div></div>

@@ -2175,14 +2181,62 @@ $('extensionClose').onclick = () => {
  $('extensionPanel').hidden = true;
 };
 let deckyInfo = null;
+let deckyCatalog = [];
 async function loadDecky() {
  try {
    const d = deckyInfo = await api('/api/decky');
    $('deckyState').textContent = `${d.frameOS || 'Unknown'} ${d.variant || ''} · ${d.arch} · CEF ${d.cef ? 'ready' : 'unavailable'} · ${d.managed ? `managed Decky ${d.version || ''} ${d.running ? 'running' : 'stopped'}` : d.upstreamInstall ? 'upstream Decky installation found' : 'Decky not installed'}`;
    const plugins = [...d.plugins.map(x => `${x.name} (managed)`), ...d.upstreamPlugins.map(x => `${x.name} (upstream)`)];
    $('deckyPlugins').textContent = plugins.length ? `Installed plugins: ${plugins.join(', ')}` : 'No Decky plugins found.';
+    const managedList=$('deckyManagedList');managedList.replaceChildren();
+    for(const plugin of d.plugins||[]){if(!plugin.storeId)continue;
+      const row=document.createElement('div');row.className='hint';
+      const label=document.createElement('span');label.textContent=`${plugin.name} ${plugin.version||''}`;
+      const remove=document.createElement('button');remove.className='small danger';remove.textContent='Remove plugin';
+      remove.disabled=!d.running||!$('deckyAck').checked;
+      remove.onclick=()=>changeDeckyPlugin('remove',{id:plugin.storeId,name:plugin.name});
+      row.append(label,remove);managedList.append(row);}
    deckyButtons();
-  } catch (error) { deckyInfo = null; $('deckyState').textContent = error.message; deckyButtons(); }
+    showDeckyStore();
+  } catch (error) { deckyInfo = null; $('deckyState').textContent = error.message; deckyButtons(); showDeckyStore(); }
+}
+async function loadDeckyStore() {
+  $('deckyStoreState').textContent = 'Loading the official store…';
+  try { deckyCatalog = (await api('/api/decky/store')).plugins;
+    $('deckyStoreState').textContent = `${deckyCatalog.length} plugins in the official store. Select a plugin to install it.`;
+    showDeckyStore();
+  } catch(error) { $('deckyStoreState').textContent = error.message; }
+}
+function showDeckyStore() {
+  const list = $('deckyStoreList'); list.replaceChildren();
+  const query = $('deckyStoreSearch').value.trim().toLowerCase();
+  const installed = [...(deckyInfo?.plugins||[]), ...(deckyInfo?.upstreamPlugins||[])];
+  for (const plugin of deckyCatalog.filter(p => !query || `${p.name} ${p.description}`.toLowerCase().includes(query)).slice(0, 40)) {
+    const row = document.createElement('div'); row.className = 'hint';
+    const title = document.createElement('strong'); title.textContent = `${plugin.name} · ${plugin.version}`;
+    const description = document.createElement('span'); description.textContent = ` ${plugin.description}`;
+    const entry = installed.find(p => p.storeId === plugin.id);
+    const unmanaged = installed.some(p => p.name === plugin.name && p.storeId !== plugin.id);
+    const reason = plugin.root ? 'Needs root; not supported by the Frame user service.' : unmanaged ? 'Existing plugin is not managed by Frame Control.' : '';
+    row.append(title, description);
+    if (reason) { const note=document.createElement('small'); note.textContent=` ${reason}`; row.append(note); }
+    else {
+      const button=document.createElement('button'); button.className='small';
+      button.textContent=entry ? (entry.version===plugin.version?'Reinstall':'Update') : 'Install';
+      button.disabled=!deckyInfo?.managed || !deckyInfo?.running || !$('deckyAck').checked;
+      button.onclick=()=>changeDeckyPlugin(entry?'update':'install',plugin);
+      row.append(button);
+      if(entry){const remove=document.createElement('button');remove.className='small danger';remove.textContent='Remove';
+        remove.disabled=!deckyInfo?.managed || !deckyInfo?.running || !$('deckyAck').checked;
+        remove.onclick=()=>changeDeckyPlugin('remove',plugin);row.append(remove);}
+    }
+    list.append(row);
+  }
+}
+async function changeDeckyPlugin(action, plugin) {
+  if (!$('deckyAck').checked || !confirm(`${action} ${plugin.name}? This official store plugin runs code as your Frame user.`)) return;
+  try { await runJob(`${action} ${plugin.name}`, 'decky-plugin', () => api('/api/decky/plugin', {action,id:plugin.id,acknowledged:true}));
+    await loadDecky(); showDeckyStore(); } catch(error) { $('deckyStoreState').textContent=error.message; }
 }
 function deckyButtons() {
  const ready = !!deckyInfo && deckyInfo.arch === 'aarch64' && deckyInfo.variant === 'vr' && deckyInfo.cef && !deckyInfo.upstreamInstall;
@@ -2191,8 +2245,11 @@ function deckyButtons() {
  $('deckyUpdate').disabled = !ack || !ready || !deckyInfo.managed;
  $('deckyRemove').disabled = !ack || !deckyInfo?.managed;
 }
-$('deckyAck').onchange = deckyButtons;
+$('deckyAck').onchange = () => { deckyButtons(); showDeckyStore();
+  for(const button of $('deckyManagedList').querySelectorAll('button'))button.disabled=!$('deckyAck').checked||!deckyInfo?.running; };
 $('deckyRefresh').onclick = loadDecky;
+$('deckyStoreRefresh').onclick = loadDeckyStore;
+$('deckyStoreSearch').oninput = showDeckyStore;
 for (const action of ['Install', 'Update', 'Remove']) {
  $(`decky${action}`).onclick = async () => {
    if (!$('deckyAck').checked || !deckyInfo) return;
@@ -3980,7 +4037,8 @@ async function importAndroidFiles(files, dev, probe = false) {
    if (!dlg.open) return true;
    const plan = read.plan;
    $("androidImportName").textContent = `${plan.label}${plan.version ? " · " + plan.version : ""}`;
-    $("androidImportFiles").innerHTML = (plan.apk ? `<div class="sub">Game app</div><div>${esc(plan.apk)}</div>`
+    $("androidImportFiles").innerHTML = (plan.apk ? `<div class="sub">Game app</div><div>${esc(plan.apk)}</div>` +
+      (plan.splits || []).map(f => `<div>${esc(f)} <span class="sub">split APK</span></div>`).join("")
      : `<div class="sub">Game app already installed</div>`) +
      `<div class="sub" style="margin-top:12px">Game data · ${plan.obb.length} file${plan.obb.length === 1 ? "" : "s"}</div>` +
      plan.obb.map(f => `<div>${esc(f.name)} <span class="sub">${gb(f.size)}</span></div>`).join("");
@@ -5552,7 +5610,7 @@ const syncWhen = t => new Date(t * 1000).toLocaleString([], { dateStyle: "medium
 function renderAutoSync(s) {
  autoSync.s = s;
  $("syncShots").checked = s.screenshots; $("syncClips").checked = s.clips;
-  $("syncResume").hidden = !s.paused;
+  $("syncResume").hidden = !(s.paused || s.error);
  const on = s.screenshots || s.clips, lines = [];
  if (s.paused) lines.push(s.paused);
  else if (s.error) lines.push(`Last problem: ${s.error}`);
@@ -80,6 +80,7 @@ import frame_wired_doctor  # noqa: E402
 import frame_compat_db  # noqa: E402
 import frame_extensions  # noqa: E402
 import frame_decky  # noqa: E402
+import frame_decky_store  # noqa: E402
 import frame_headset  # noqa: E402

 frame_host.trust_bundled_cas()
@@ -561,6 +562,17 @@ def decky(body):
    return start_job("Decky Loader " + action, lambda: frame_decky.change(ssh, action))


+def decky_plugin(body):
+    action = body.get('action')
+    plugin_id = body.get('id')
+    if action not in ('install', 'update', 'remove') or type(plugin_id) is not int:
+        raise Failure('Choose an official store plugin and action', 400)
+    if body.get('acknowledged') is not True:
+        raise Failure('Confirm that store plugins run code as your Frame user', 400)
+    return start_job('Decky plugin ' + action,
+                     lambda: frame_decky_store.change(ssh, action, plugin_id))
+
+
 def headset_action(body):
    if LOCAL:
        raise Failure("Manage the headset panel from Frame Control on your computer", 400)
@@ -957,8 +969,8 @@ def _sync_clip(device, clip_id):


 def _sync_list(listing):
-    def run():
-        with working(_sync_device()):
+    def run(device):
+        with working(device):
            return listing()
    return run

@@ -3397,6 +3409,7 @@ POST = {
    "/api/power": power_action,
    "/api/android/backup": android_backup, "/api/backup": backup_action,
    "/api/decky": decky,
+    "/api/decky/plugin": decky_plugin,
    "/api/headset": headset_action,
    "/api/headset/quick": headset_quick,
    "/api/vr": vr,
@@ -3604,6 +3617,8 @@ class Handler(BaseHTTPRequestHandler):
                self.send_json(frame_extensions.list_extensions())
            elif path == "/api/decky":
                self.send_json(frame_decky.status(ssh))
+            elif path == "/api/decky/store":
+                self.send_json({'plugins': frame_decky_store.catalog()})
            elif path == "/api/headset":
                if LOCAL:
                    raise Failure("Manage this panel from Frame Control on your computer", 400)
Author	SHA1	Message	Date
SAPHID	af2bb178d5	Keep auto-sync changelog separate from parallel fixes	2026-10-25 06:21:39 +00:00
SAPHID	b1f1880736	Merge remote-tracking branch 'origin/main' into t3/fix-autosync-reliability # Conflicts: # CHANGELOG.md	2026-10-25 06:20:50 +00:00
Alex SouthwellandSAPHID	da34d94009	Skip backup paths with symlinked ancestors (#215 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-25 06:19:38 +00:00
SAPHID	338726d581	Read auto-sync Settings fixture as UTF-8 on Windows	2026-10-25 06:18:28 +00:00
Alex SouthwellandSAPHID	234b0a1814	Add managed Decky store and Frame plugin compatibility audit (#208 ) * Add managed Decky store plugins and Frame compatibility audit * Reject malformed flags and linked plugin folders --------- Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-25 06:15:42 +00:00
Alex SouthwellandSAPHID	7a8e919546	Validate extension bridge API versions before loading panels (#209 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-25 06:13:55 +00:00
SAPHID	32727fc6e5	Fix auto-sync retry recovery and headset-bound listings	2026-10-25 06:11:09 +00:00
Alex SouthwellandSAPHID	d79efb4730	Bump Frame Control to 0.4.30 (#207 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-25 05:39:30 +00:00
Alex SouthwellandSAPHID	95643b7ea0	Support restricted split APKs in Android backup import (#206 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-25 05:29:21 +00:00
Alex SouthwellandSAPHID	9dab523af9	docs: distinguish current Frame OS checks from September notes (#205 ) Co-authored-by: SAPHID <saphid@users.noreply.github.com>	2026-10-25 05:13:12 +00:00