Merge remote-tracking branch 'origin/main' into release/v0.4.47

Load Shotty official backend with a scoped Python shim

app/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "frame-control",
-  "version": "0.4.46",
+  "version": "0.4.47",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "frame-control",
-      "version": "0.4.46",
+      "version": "0.4.47",
       "license": "MIT",
       "devDependencies": {
         "electron": "^44.4.5",

app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frame-control",
   "productName": "Frame Control",
-  "version": "0.4.46",
+  "version": "0.4.47",
   "description": "Desktop app for managing a Valve Steam Frame over SSH",
   "private": true,
   "main": "main.js",

docs/evidence/framey-audit-chunk-route-2026-10-26.md

@@ -0,0 +1,32 @@
+# Chunked Framey frontend audit route, 26 October 2026
+
+The local 116-plugin Chromium audit served chunked modules at a route that
+omitted the store receipt, while the production panel requested
+`/framey/module/<id>/<receipt>/<file>`. The audit parsed that receipt as part
+of the file path and returned 404. This made its result for chunked frontends
+weaker than the separate targeted panel checks.
+
+The audit now accepts the production URL shape only when the plugin ID,
+receipt and JavaScript path are valid, the receipt equals the catalog SHA-256,
+and the cached archive bytes match that SHA-256. Invalid IDs, receipts, paths
+and changed archive bytes fail before the module is served. The production
+Framey panel and installer are unchanged.
+
+## Exact archived browser check
+
+Pinned official Deck Shelves 2.0.0 (store ID 135, SHA-256
+`b566280ad38fd3ecd584b5b46a855f301539eb9a86063834c64b7045f7063f91`)
+ran through the repaired audit in an opaque Chromium iframe. Its entry module
+and all eight JavaScript chunks returned HTTP 200 at receipt-bound URLs. The
+frontend reported ready and called `get_settings`; the audit denied that
+backend call and a Steam library read. Plugin network access remained blocked
+by the audit policy. The previous
+catalog browser observation had failed to resolve `./chunks/...` from a blob
+URL. This check verifies the current audit route and frontend initializer,
+not the official backend or a live shelf.
+
+The focused route regression covers entry and chunk reads plus wrong receipt,
+path traversal, malformed ID and changed archive bytes. The catalog's
+**4 works / 50 partial / 51 broken / 11 N/A** statuses are unchanged. Deck
+Shelves remains partial; installed settings, home-shelf behavior, worn VR and
+physical controller input remain unverified.

docs/evidence/framey-deck-shelves-browser-2026-10-26.md

@@ -4,7 +4,17 @@ The exact official Deck Shelves 2.0.0 archive (store ID 135, SHA-256 `b566280ad3
 
 Framey now serves JavaScript files from the managed plugin's `dist` directory using hierarchical module URLs. Its opaque `allow-scripts` iframe still has no Frame UI key. Local Chromium received HTTP 200 for the entry and eight chunks, reported the initializer ready, and rendered the settings panel with “Enable shelves on Home,” “Create default shelves,” “Behavior,” and “Shelves.” The browser audit denied the attempted `get_settings` backend call, Steam library read and plugin network access. No backend method executed.
 
-The catalog moves this exact version from broken to **partial** for visible local settings only. The plugin's main feature injects shelves into Steam Home; Framey has no verified Steam Home patch target. Settings writes, official backend behavior, real Frame module serving, wearer-visible VR, and physical controller input remain unverified. The [compatibility table](../framey-compatibility.md) and store views retain these limits.
+The catalog moves this exact version from broken to **partial** for visible local settings. The plugin's main feature injects shelves into Steam Home; Framey has no verified Steam Home patch target. Actual Decky RPC, real Frame settings, wearer-visible VR, and physical controller input remain unverified. The [compatibility table](../framey-compatibility.md) and store views retain these limits.
+
+## Isolated official backend settings check
+
+I verified the same archive digest before loading its unchanged `Deck-Shelves/main.py` in local Python. A stub `decky` module supplied only a logger; `DECKY_PLUGIN_SETTINGS_DIR` and `DECKY_HOME` pointed inside a temporary directory. No Decky service, headset, Steam API, or network call was involved. Calling `_main`, `get_settings`, and `set_settings` returned the default disabled state, saved one shelf named `Local Test`, and returned that shelf from a fresh `Plugin` instance. The temporary directory was removed after the check.
+
+```json
+{"archiveSha256":"b566280ad38fd3ecd584b5b46a855f301539eb9a86063834c64b7045f7063f91","defaultEnabled":false,"defaultShelves":0,"saveResult":true,"reopenedEnabled":true,"reopenedShelfTitle":"Local Test","settingsFileExists":true}
+```
+
+This proves only the archive's Python settings logic under those local conditions. It does not prove that Decky 3.3.0 can dispatch these methods on the ARM64 Frame, that the opaque panel can save settings through the production bridge, or that a shelf appears on Steam Home or in VR.
 
 ## Exact source real Frame gates
 

docs/evidence/framey-game-theme-music-2026-10-26.md

@@ -0,0 +1,7 @@
+# Game Theme Music local panel check, 26 October 2026
+
+The exact official Game Theme Music 1.7.1-1 archive (store ID 52, SHA-256 `9ce293ab4db212c03c6b96dfbc5e4d92e874d33387463f53223773921f75a80e`) passed the existing fake Frame install/remove audit. Its prior local Chromium run stopped before initialization with `Cannot read properties of null (reading 'type')`: the frontend dereferenced the result of `DFL.fakeRenderComponent` while looking for Steam's Library Context Menu.
+
+Framey's isolated host now returns an inert local component type from that lookup. The patch API remains a no-op and does not expose or modify a Steam React tree. In the repository's opaque Chromium audit, the unchanged archive reported initializer ready and rendered a Settings view containing Music Volume, Default Muted, Use yt-dlp, Invidious Instance, Download Music, Overrides and Extras. The audit observed a `get_setting` request, but denied the backend call. It also denied plugin network requests; a YouTube/Invidious fetch failed as expected. The bounded root-text observation came from the test iframe and contained only these public UI labels.
+
+The catalog therefore moves this digest from **broken** to **partial** for the visible local settings panel. No theme was played or injected into a Steam game page. Music search, playback, downloads, settings persistence, live ARM64 backend behavior, wearer-visible VR and physical controller input remain unverified. The earlier failed browser observation remains in the canonical JSON alongside this follow-up so the change in evidence is explicit.

docs/evidence/framey-shotty-python-2026-10-26.md

@@ -0,0 +1,9 @@
+# Shotty Python compatibility, 26 October 2026
+
+The exact official Shotty 0.1.0 archive (store ID 53, SHA-256 `ab7f6618b264a0cb766525e788cef6c3e1478c0fef98a701225e5e8af441e2fe`) imports `click.get_app_dir` at startup but never calls it. The archive includes an empty `py_modules` directory and no `click` package. A prior actual Decky 3.3.0 amd64 backend check stopped at `ModuleNotFoundError: click`; its local frontend separately starts with Framey's read-only Steam library snapshot.
+
+Frame Control now writes a small Linux `click.get_app_dir` compatibility module into **only this exact digest's** managed `Shotty/py_modules` folder during staging. Decky Loader adds each plugin's `py_modules` folder to that plugin's Python search path. The staging transaction records `shotty-click-app-dir` in the receipt and removes the whole staged folder on failure. A different Shotty digest receives no module. The official ZIP bytes and their verified hash remain unchanged.
+
+An isolated transaction test installed the pinned archive, imported its unchanged `main.py` using the staged module, and called its `aggregate_all` method with a synthetic Steam screenshot under a temporary `HOME`. It copied one fixture image into that temporary home's `Pictures/Screenshots/Local Test Game` folder; reopening the copied bytes matched the source. Removal deleted the managed folder. A second synthetic Shotty archive with another digest installed without the module. The test neither started the plugin's continuous screenshot rescuer nor touched a person's Steam library or screenshots.
+
+This supports **partial** compatibility for the local frontend and a narrow backend copy path. Actual Decky 3.3.0 ARM64 plugin startup, gamescope screenshot rescue, real screenshot aggregation, VR panel visibility, and physical controller use remain unverified. No headset lock was acquired or headset state changed for this check.

docs/evidence/v0447-candidate-2026-10-26.md

@@ -0,0 +1,46 @@
+# v0.4.47 candidate gate, 26 October 2026
+
+This candidate contains Game Theme Music's locally rendered Settings view
+(#330) and a digest-scoped Python import module for the official Shotty 0.1.0
+archive (#331). The 116-plugin table is **4 works / 52 partial / 49 broken /
+11 N/A**. Game Theme Music is partial for its local Settings view; its
+backend, network and playback were denied in that audit. Shotty is partial
+for its local frontend and synthetic screenshot copy in isolated Python;
+actual ARM64 Decky startup and live screenshot rescue are unverified.
+
+## Locked Frame candidate smoke
+
+At 14:18 UTC, source commit `1f5b37a7552880b40868617ef22398fcd39b3f5d`
+ran `scripts/frame-smoke.sh` on the real Frame. The script acquired its unique
+owner in `/tmp/frame-test.lock` before reading status. Locked preflight found
+SteamVR activity **3** (standby), proximity raw **3.0625**, and battery
+**100%** on Frame OS 0.5.6 build `20261022.6153909`. Owned ARM64 and
+Windows/Proton test titles installed, launched, and were removed. The
+optional x86_64 title installed and was removed; launch was **skipped**
+because Steam Linux Runtime 4 was absent. The result was **12 passed /
+1 skipped / 0 failed**. Cleanup passed and the command exited 0, including
+release of its owned lock. Detailed results stay private in
+`tests/smoke/results/2026-10-26T141812Z-20261022.6153909.json`.
+
+No wearer was confirmed. The interactive worn-check script was not run;
+the smoke did not wake the headset or test the Framey panel. Game Theme
+Music playback, Shotty live rescue, wearer-visible official-plugin UI,
+physical controllers, keyboard and optical comfort remain unverified.
+The hourly shared-lock worn check remains enabled.
+
+## Publication boundary
+
+At 14:23 UTC, the exact version-bumped candidate commit
+`e07fa155928d1609304e317d15e0c4ef4a977579` ran the same token-locked
+`scripts/frame-smoke.sh`.
+Preflight again found activity **3** (standby), proximity raw **3.0625** and
+battery **100%**. The result was **12 passed / 1 optional x86 launch skipped /
+0 failed**. Owned cleanup passed and the command exited 0 after releasing its
+lock. Its private result is
+`tests/smoke/results/2026-10-26T142321Z-20261022.6153909.json`.
+This paragraph is the only change after that smoke.
+
+PR #331's combined-head CI, green release-PR and post-merge CI, tagged
+installer builds, all ten installer digests with `SHA256SUMS`, independent
+package checks, publisher dry run, and public `update.json` readback remain
+required.

docs/framey-compatibility.md

@@ -4,7 +4,7 @@ Snapshot: 2026-10-26T06:10:58.537029+00:00; 116 current visible official plugins
 
 This table and both store views use [`ui/framey-compatibility.json`](../ui/framey-compatibility.json). Results apply only to the exact store ID, version and SHA-256. A changed digest/version is **unverified**. Regenerate this document with `python3 scripts/framey-compatibility-doc.py`; use `--check` in review.
 
-**Works: 4 · Partial: 50 · Broken: 51 · N/A: 11.**
+**Works: 4 · Partial: 52 · Broken: 49 · N/A: 11.**
 
 - **Works** requires verified useful plugin behavior with its real backend. Read the reason for the verified scope and remaining limits; it does not imply worn-VR verification.
 - **Partial** means only a subset or a local fixture scope was verified, often just frontend/settings initialization. The remaining backend/device functionality is unverified; read the reason for the exact scope.
@@ -67,8 +67,8 @@ The API column shows manifest / actual bundled frontend API. Many manifests say
 | 48: Quick Launch 1.2.1 | legacy / legacy | broken | This plugin needs root and is not supported by the Frame user service. | static archive, local browser, fake-Frame |
 | 49: Decky Cloud Save 1.4.2 | legacy / legacy | broken | Unsafe plugin archive member. | static archive, local browser, fake-Frame |
 | 50: Storage Cleaner 1.4.0 | 1 / 2 | partial | Empty-data panel rendered; cleanup was deliberately not run because it can remove local data. | static archive, local browser, fake-Frame |
-| 52: Game Theme Music 1.7.1-1 | 1 / 2 | broken | Frontend audit failed: Cannot read properties of null (reading 'type'). | static archive, local browser, fake-Frame |
-| 53: Shotty 0.1.0 | legacy / legacy | broken | Library snapshot fixes the frontend allApps crash. Actual published Decky 3.3.0 amd64 backend fails importing click.get_app_dir (ModuleNotFoundError); the archive does not bundle click. Screenshot aggregation/rescue was not run. | static archive, local browser, fake-Frame, real Frame SSH |
+| 52: Game Theme Music 1.7.1-1 | 1 / 2 | partial | An inert local component lets the exact frontend initialize and render its Settings view in opaque Chromium. Backend get_setting and plugin network were denied in the audit; Steam game-page theme injection has no verified target in Framey. Music search, playback, downloads, settings persistence and worn VR remain unverified. | static archive, local browser, fake-Frame |
+| 53: Shotty 0.1.0 | legacy / legacy | partial | The frontend starts with the read-only Frame library snapshot. Frame Control adds a digest-scoped click.get_app_dir compatibility module to the managed install; the exact backend then imports and copies a synthetic Steam screenshot into a temporary Pictures folder in isolated Python. Actual Decky 3.3.0 ARM64 loading, live screenshots/rescue, in-VR panel and physical controller use remain unverified. | static archive, local browser, fake-Frame, real Frame SSH, isolated Python backend |
 | 56: MangoPeel 0.0.7 | 1 / 2 | partial | Initializer succeeds; gamescope/MangoHud actions and backend are unverified. | static archive, local browser, fake-Frame |
 | 58: Volume Boost 0.0.7 | legacy / legacy | works | Default-sink controls pass in local Chromium through real Decky 3.3.0 ARM64: linked slider/keyboard and numeric writes, separate channels, re-link and reopen, with independent Pulse readback including 125%/150% while muted. Exact original volume/mute restored. Audible output, Bluetooth sinks and worn VR unverified. | static archive, local browser, fake-Frame, isolated Linux backend, real Frame SSH |
 | 59: Web Browser 1.4.3 | legacy / legacy | broken | The exact frontend now initializes with a null Steam React-root lookup. The browser itself still requires Steam GamepadUI CDP injection and a backend WebSocket unavailable in Framey; no working browser tab was verified. | static archive, local browser, fake-Frame, focused local browser |
@@ -142,7 +142,7 @@ The API column shows manifest / actual bundled frontend API. Many manifests say
 | 132: SuggestMe 1.5.3 | 1 / 2 | partial | Initializer succeeds; recommendation backend and Steam library data unverified. | static archive, local browser, fake-Frame |
 | 133: Non-Steam Badges 0.1.0 | 1 / 2 | partial | Initializer succeeds; Non-Steam game badges have no supported Steam page injection target. | static archive, local browser, fake-Frame |
 | 134: Deck Progress Tracker 1.3.6 | 1 / 2 | partial | Initializer succeeds; Steam game/library statistics and page patches unverified. | static archive, local browser, fake-Frame |
-| 135: Deck Shelves 2.0.0 | 1 / 1 | partial | The exact chunked frontend now initializes and renders Deck Shelves settings in an opaque local Chromium panel. Backend calls were denied; Home-screen shelf injection has no verified Steam UI target in Framey. Settings writes, real backend behavior and worn VR are unverified. | static archive, local browser, fake-Frame |
+| 135: Deck Shelves 2.0.0 | 1 / 1 | partial | The exact chunked frontend renders settings in opaque local Chromium. The official Python backend saved a shelf and returned it after reopen with a stub Decky module and temporary settings directory. Actual Decky RPC, real Frame settings, Steam Home shelf injection and worn VR remain unverified. | static archive, local browser, fake-Frame, isolated Python backend |
 | 136: Decky-Clipper 1.0.2 | 1 / 2 | broken | Plugin contains a non-ARM64 Linux binary: Decky-Clipper/bin/gstreamer-1.0/libgstproxy.so. | static archive, local browser, fake-Frame |
 | 137: Decky Proton Launch 0.9.0 | 1 / 2 | partial | Initializer succeeds; Proton wrapper installation and launch changes were not run. | static archive, local browser, fake-Frame |
 | 138: Docky 1.4.13 | legacy / legacy | broken | This plugin needs root and is not supported by the Frame user service. | static archive, local browser, fake-Frame |

scripts/framey-audit-browser.py

@@ -11,6 +11,7 @@ import io
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 import json
 from pathlib import Path
+import re
 import sys
 from unittest.mock import patch
 import zipfile
@@ -27,6 +28,10 @@ for(const key of ['error','warn']){const original=console[key];console[key]=(...
   report(key,args.map(String).join(' '));original(...args);};}
 window.fetch=()=>Promise.reject(Error('Audit blocks plugin network'));
 window.WebSocket=class{constructor(){throw Error('Audit blocks WebSocket');}};
+addEventListener('message', event=>{
+  if(event.source!==parent||event.data?.type!=='audit:inspect')return;
+  parent.postMessage({type:'audit:snapshot',text:(document.getElementById('framey-root')?.innerText||'').slice(0,2000)},'*');
+});
 </script>'''
 
 
@@ -41,6 +46,27 @@ def render_panel(record, data):
         return framey_panel.panel(record['id']).replace(
             b'<script id="framey-bundle"', PRELUDE.encode()+b'<script id="framey-bundle"')
 
+
+def read_module_asset(path, records, cache):
+    """Serve the same receipt-bound module URL shape as the installed panel."""
+    prefix = '/framey/module/'
+    if not path.startswith(prefix):
+        raise ValueError('Invalid module path')
+    parts = path[len(prefix):].split('/', 2)
+    if len(parts) != 3 or not re.fullmatch(r'[1-9][0-9]*', parts[0]):
+        raise ValueError('Invalid plugin ID')
+    plugin_id, receipt, name = parts
+    if not framey_panel.RECEIPT.fullmatch(receipt) or not framey_panel.MODULE_PATH.fullmatch(name):
+        raise ValueError('Invalid module receipt or path')
+    record = records[int(plugin_id)]
+    if receipt != record['sha256']:
+        raise ValueError('Plugin receipt changed')
+    data = (cache/(receipt+'.zip')).read_bytes()
+    if hashlib.sha256(data).hexdigest() != receipt:
+        raise ValueError('Archive hash mismatch')
+    with zipfile.ZipFile(io.BytesIO(data)) as archive:
+        return archive.read(record['folder']+'/dist/'+name)
+
 PAGE = '''<!doctype html><meta charset=utf-8><title>Framey catalog frontend audit</title>
 <h1>Framey catalog frontend audit</h1>
 <p>Exact archived frontend code runs in an opaque iframe. All backend calls and network requests are denied.
@@ -54,6 +80,7 @@ addEventListener('message',event=>{
   if(event.source!==panel.contentWindow||!active)return;
   const data=event.data;
   if(data.type==='audit:log'&&active.logs.length<8)active.logs.push({kind:data.kind,message:data.message.split('\\n')[0].slice(0,400)});
+  if(data.type==='audit:snapshot')active.rootText=String(data.text).slice(0,2000);
   if(data.type==='framey:error')active.error=String(data.message).slice(0,500);
   if(data.type==='framey:ready')active.ready=true;
   if(data.type==='framey:events')event.source.postMessage({type:'framey:reply',id:data.id,result:{events:[],cursor:0}},'*');
@@ -71,10 +98,15 @@ window.runAudit=async(ids,settleMs=1200)=>{
   if(!Number.isInteger(settleMs)||settleMs<1200||settleMs>10000)throw Error('Invalid audit settle time');
   if(running)throw Error('Audit already running');running=true;run.disabled=true;
   try{for(const plugin of plugins.filter(plugin=>!ids||ids.includes(plugin.id))){
-    active={id:plugin.id,name:plugin.name,ready:false,error:null,logs:[],methods:[],
+    active={id:plugin.id,name:plugin.name,ready:false,error:null,logs:[],methods:[],rootText:'',
       library:librarySnapshot?'snapshot replay':'unavailable',running:runningSnapshot?'snapshot replay':'unavailable'};
     progress.textContent=plugin.id+' '+plugin.name;panel.src='/panel/'+plugin.id;
-    await new Promise(resolve=>setTimeout(resolve,settleMs));results.push(active);active=null;
+    await new Promise(resolve=>setTimeout(resolve,settleMs));
+    // Detached Steam snapshots may contain personal library data. Keep text
+    // observations out of reports that replay either snapshot.
+    if(!librarySnapshot&&!runningSnapshot)panel.contentWindow.postMessage({type:'audit:inspect'},'*');
+    await new Promise(resolve=>setTimeout(resolve,80));
+    results.push(active);active=null;
     panel.src='about:blank';await new Promise(resolve=>setTimeout(resolve,30));
   }}finally{running=false;run.disabled=false;progress.textContent='Done: '+results.length;}
   return results;
@@ -134,15 +166,7 @@ def main():
                     return
             elif path.startswith('/framey/module/'):
                 try:
-                    plugin_id, name = path.removeprefix('/framey/module/').split('/', 1)
-                    if not framey_panel.MODULE_PATH.fullmatch(name):
-                        raise ValueError('Invalid module path')
-                    record = records[int(plugin_id)]
-                    data = (args.cache/(record['sha256']+'.zip')).read_bytes()
-                    if hashlib.sha256(data).hexdigest() != record['sha256']:
-                        raise ValueError('Archive hash mismatch')
-                    with zipfile.ZipFile(io.BytesIO(data)) as archive:
-                        body = archive.read(record['folder']+'/dist/'+name)
+                    body = read_module_asset(path, records, args.cache)
                     content_type = 'text/javascript; charset=utf-8'
                     module_asset = True
                 except (KeyError, ValueError, OSError, zipfile.BadZipFile):

tests/e2e/test_framey.py

@@ -192,6 +192,10 @@ u=h/'.config/systemd/user/frame-control-decky.service'; u.parent.mkdir(parents=T
                     self.assertEqual(
                         ssh(f'sha256sum {installed}/dist/{chunk}').split()[0],
                         hashlib.sha256(expected_chunk).hexdigest())
+                if plugin['id'] == 53:
+                    self.assertEqual(ssh(f'test -f {installed}/py_modules/click.py && echo yes').strip(), 'yes')
+                    receipt = json.loads(ssh(f'cat {installed}/.frame-control-store.json'))
+                    self.assertEqual(receipt['compatShims'], ['shotty-click-app-dir'])
                 job = finished(ok('POST', '/api/decky/plugin',
                                   {'action':'remove','id':plugin['id'],'acknowledged':True}))
                 self.assertFalse(job.get('error'), job)

tests/framey_official.py

@@ -17,6 +17,8 @@ PLUGINS = (
      'folder': 'hltb-for-deck', 'sha256': 'bd54a23b0b8ec0798aa590e5be236522a593529d7680e77fb888e2971bf3d558'},
     {'id': 36, 'name': 'SteamGridDB', 'version': '1.8.1', 'api_version': 1,
      'folder': 'decky-steamgriddb', 'sha256': 'e84f5b1f111af8862b06218479491fbf61036e1bfd9f16f93f9901e9b9ebc5e0'},
+    {'id': 53, 'name': 'Shotty', 'version': '0.1.0', 'api_version': 'legacy',
+     'folder': 'Shotty', 'sha256': 'ab7f6618b264a0cb766525e788cef6c3e1478c0fef98a701225e5e8af441e2fe'},
     {'id': 63, 'name': 'Free Loader', 'version': '1.6.0', 'api_version': 1,
      'folder': 'free-loader', 'sha256': '05208aee6f6ba824391d8ddc81b1168b2599a9711e7528cdaa789f6cc710b42a'},
     {'id': 135, 'name': 'Deck Shelves', 'version': '2.0.0', 'api_version': 1,

tests/page/framey_actions.mjs

@@ -29,6 +29,10 @@ vm.runInContext(testSource,context);
 // No Steam React tree exists inside the isolated Framey iframe.
 assert.equal(window.DFL.getReactRoot({}),null);
 assert.equal(window.DFL.findInReactTree(window.DFL.getReactRoot(null),()=>true),null);
+const inertSteamComponent=window.DFL.fakeRenderComponent(undefined).type;
+assert.equal(inertSteamComponent.name,'MissingSteamComponent');
+assert.equal(window.DFL.fakeRenderComponent(undefined).type,inertSteamComponent);
+assert.equal(typeof window.DFL.afterPatch(inertSteamComponent.prototype,'render',()=>{}).unpatch,'function');
 // Official @decky/rollup bundles use the automatic JSX runtime, including keyed lists.
 const jsx=window.SP_JSX.jsx('p',{id:'message',children:'Saved'},'message-key');
 assert.equal(jsx.type,'p');

tests/test_frame_decky_store.py

@@ -121,14 +121,14 @@ class StoreTransaction(unittest.TestCase):
         self.folder = home / '.local/share/frame-control/decky/plugins/Example'
         self.folder.parent.mkdir(parents=True)
 
-    def apply(self, action, data=None, expected='-'):
+    def apply(self, action, data=None, expected='-', plugin_id=42, folder='Example', version='1.0'):
         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', expected],
+            return subprocess.run([sys.executable, '-', action, token, str(plugin_id), digest, folder, version, expected],
                                   input=frame_decky_store.APPLY, text=True, capture_output=True,
                                   env=self.env, timeout=15)
         finally:
@@ -161,6 +161,59 @@ class StoreTransaction(unittest.TestCase):
         self.assertNotEqual(result.returncode, 0)
         self.assertTrue(external.exists())
 
+    def test_exact_shotty_archive_gets_isolated_click_import(self):
+        from framey_official import PLUGINS, archive as official_archive
+        plugin = next(p for p in PLUGINS if p['id'] == 53)
+        data = official_archive(plugin)
+        self.assertEqual(hashlib.sha256(data).hexdigest(), plugin['sha256'])
+        shotty = self.folder.parent / plugin['folder']
+        args = {'plugin_id': plugin['id'], 'folder': plugin['folder'], 'version': plugin['version']}
+        result = self.apply('install', data, **args)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        receipt = json.loads((shotty / '.frame-control-store.json').read_text())
+        self.assertEqual(receipt['sha256'], plugin['sha256'])
+        self.assertEqual(receipt['compatShims'], ['shotty-click-app-dir'])
+        compat = shotty / 'py_modules/click.py'
+        self.assertTrue(compat.is_file())
+        source = '''import asyncio, importlib.util, logging, sys, types
+from pathlib import Path
+folder = Path(sys.argv[1])
+sys.path.insert(0, str(folder/'py_modules'))
+decky = types.ModuleType('decky_plugin')
+decky.logger = logging.getLogger('shotty-test')
+decky.DECKY_PLUGIN_DIR = str(folder)
+sys.modules['decky_plugin'] = decky
+spec = importlib.util.spec_from_file_location('shotty', folder/'main.py')
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+assert module.Plugin.__name__ == 'Plugin'
+from click import get_app_dir
+assert get_app_dir('Shotty') == str(Path.home()/'.config/Shotty')
+photo = Path.home()/'.local/share/Steam/userdata/100/760/remote/42/screenshots/test.jpg'
+photo.parent.mkdir(parents=True)
+photo.write_bytes(b'local screenshot fixture')
+plugin = module.Plugin()
+assert asyncio.run(plugin.aggregate_all([[42, 'Local Test Game']])) == 1
+copied = Path.home()/'Pictures/Screenshots/Local Test Game/test.jpg'
+assert copied.read_bytes() == b'local screenshot fixture'
+'''
+        imported = subprocess.run([sys.executable, '-c', source, str(shotty)],
+                                  capture_output=True, text=True,
+                                  env={**self.env, 'XDG_CONFIG_HOME': str(Path(self.tmp.name)/'.config')}, timeout=10)
+        self.assertEqual(imported.returncode, 0, imported.stderr)
+        result = self.apply('remove', expected=plugin['sha256'], **args)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertFalse(shotty.exists())
+        stream = io.BytesIO()
+        with zipfile.ZipFile(stream, 'w') as bundle:
+            bundle.writestr('Shotty/plugin.json', json.dumps({'name': 'Shotty', 'flags': []}))
+            bundle.writestr('Shotty/dist/index.js', 'export default {};' + ' ' * 1200)
+        other = stream.getvalue()
+        result = self.apply('install', other, **args)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertFalse((shotty / 'py_modules/click.py').exists())
+        self.assertNotIn('compatShims', json.loads((shotty / '.frame-control-store.json').read_text()))
+
     def test_installed_script_entrypoints_execute_without_zip_exec_bits(self):
         data, _ = archive(extra=('Example/scripts/start.py',
                                  b'#!/bin/sh\nprintf "Framey script: %s\\n" "$1"\n'))

tests/test_framey_audit_browser.py

@@ -5,6 +5,7 @@ import hashlib
 import importlib.util
 import io
 from pathlib import Path
+import tempfile
 import unittest
 import zipfile
 
@@ -21,6 +22,7 @@ class ReceiptBoundAudit(unittest.TestCase):
         stream = io.BytesIO()
         with zipfile.ZipFile(stream, 'w') as archive:
             archive.writestr('Example/dist/index.js', bundle)
+            archive.writestr('Example/dist/chunks/frontend.js', b'export const ready = true;')
         data = stream.getvalue()
         digest = hashlib.sha256(data).hexdigest()
         record = {'id':42, 'folder':'Example', 'sha256':digest}
@@ -30,3 +32,20 @@ class ReceiptBoundAudit(unittest.TestCase):
         self.assertIn(b'const report=(kind,message)', page)
         with self.assertRaisesRegex(ValueError, 'hash mismatch'):
             audit.render_panel({**record, 'sha256':'0'*64}, data)
+
+        with tempfile.TemporaryDirectory() as directory:
+            cache = Path(directory)
+            (cache/(digest+'.zip')).write_bytes(data)
+            records = {42:record}
+            route = f'/framey/module/42/{digest}/'
+            self.assertEqual(audit.read_module_asset(route+'index.js', records, cache), bundle)
+            self.assertEqual(audit.read_module_asset(route+'chunks/frontend.js', records, cache),
+                             b'export const ready = true;')
+            for bad in (f'/framey/module/42/{"0"*64}/index.js',
+                        route+'chunks/../frontend.js', route+'other.json',
+                        f'/framey/module/042/{digest}/index.js'):
+                with self.subTest(bad=bad), self.assertRaises((ValueError, KeyError)):
+                    audit.read_module_asset(bad, records, cache)
+            (cache/(digest+'.zip')).write_bytes(data+b'changed')
+            with self.assertRaisesRegex(ValueError, 'hash mismatch'):
+                audit.read_module_asset(route+'index.js', records, cache)

ui/frame_decky_store.py

@@ -208,6 +208,26 @@ try:
                     entry.chmod(entry.stat().st_mode|0o100)
             unpacked=stage/folder
             if not unpacked.is_dir(): raise RuntimeError('Missing plugin folder')
+            compat_shims=[]
+            # Shotty 0.1.0 imports click.get_app_dir but never calls it. Its
+            # official ZIP omits click and Decky's bundled Python lacks it.
+            # Supply the Linux function only inside this exact plugin's
+            # py_modules path; other plugins keep their original imports.
+            if int(plugin_id)==53 and digest=='ab7f6618b264a0cb766525e788cef6c3e1478c0fef98a701225e5e8af441e2fe' and folder=='Shotty':
+                compat=unpacked/'py_modules/click.py'
+                if compat.exists(): raise RuntimeError('Shotty compatibility module collides with archive')
+                compat.parent.mkdir(parents=True,exist_ok=True)
+                compat.write_text(
+                    '"""Frame Control Linux compatibility for Shotty 0.1.0."""\n'
+                    'import os\n'
+                    'def get_app_dir(app_name, roaming=True, force_posix=False):\n'
+                    '    if not isinstance(app_name, str) or not app_name:\n'
+                    '        raise ValueError("app_name must be a nonempty string")\n'
+                    '    base = os.environ.get("XDG_CONFIG_HOME")\n'
+                    '    if not base or not os.path.isabs(base):\n'
+                    '        base = os.path.join(os.path.expanduser("~"), ".config")\n'
+                    '    return os.path.join(base, app_name)\n',encoding='utf-8')
+                compat_shims.append('shotty-click-app-dir')
             # Recheck under the transaction lock. Another store operation may
             # have installed a colliding name while this archive downloaded.
             proposed_name=json.loads((unpacked/'plugin.json').read_text()).get('name')
@@ -221,7 +241,9 @@ try:
                     if isinstance(peer_data,dict) and peer_data.get('name')==proposed_name:
                         raise RuntimeError('A different plugin with this name is already installed')
                 except (OSError,ValueError,UnicodeError): continue
-            (unpacked/marker).write_text(json.dumps({'storeId':int(plugin_id),'sha256':digest,'version':version})+'\n')
+            record={'storeId':int(plugin_id),'sha256':digest,'version':version}
+            if compat_shims: record['compatShims']=compat_shims
+            (unpacked/marker).write_text(json.dumps(record)+'\n')
     # Stop even a failed unit before removal to cancel any pending auto-restart.
     if running or action=='remove': service('stop','frame-control-decky.service')
     try:

ui/framey-compatibility.json

@@ -3795,8 +3795,8 @@
         "https://github.com/SteamDeckHomebrew/decky-loader",
         "https://github.com/yt-dlp/yt-dlp"
       ],
-      "status": "broken",
-      "reason": "Frontend audit failed: Cannot read properties of null (reading 'type').",
+      "status": "partial",
+      "reason": "An inert local component lets the exact frontend initialize and render its Settings view in opaque Chromium. Backend get_setting and plugin network were denied in the audit; Steam game-page theme injection has no verified target in Framey. Music search, playback, downloads, settings persistence and worn VR remain unverified.",
       "blockInstall": false,
       "verification": [
         "static archive",
@@ -3829,6 +3829,13 @@
         "sha256": "9ce293ab4db212c03c6b96dfbc5e4d92e874d33387463f53223773921f75a80e",
         "archiveValidation": "accepted",
         "result": "installed-removed"
+      },
+      "renderFollowUp": {
+        "evidence": "docs/evidence/framey-game-theme-music-2026-10-26.md",
+        "mode": "exact archive in opaque local Chromium; backend and network denied",
+        "frontendReady": true,
+        "settingsRendered": true,
+        "steamGamePagePatched": false
       }
     },
     {
@@ -3875,14 +3882,15 @@
       "sourceURLs": [
         "https://github.com/safijari/Shotty"
       ],
-      "status": "broken",
-      "reason": "Library snapshot fixes the frontend allApps crash. Actual published Decky 3.3.0 amd64 backend fails importing click.get_app_dir (ModuleNotFoundError); the archive does not bundle click. Screenshot aggregation/rescue was not run.",
+      "status": "partial",
+      "reason": "The frontend starts with the read-only Frame library snapshot. Frame Control adds a digest-scoped click.get_app_dir compatibility module to the managed install; the exact backend then imports and copies a synthetic Steam screenshot into a temporary Pictures folder in isolated Python. Actual Decky 3.3.0 ARM64 loading, live screenshots/rescue, in-VR panel and physical controller use remain unverified.",
       "blockInstall": false,
       "verification": [
         "static archive",
         "local browser",
         "fake-Frame",
-        "real Frame SSH"
+        "real Frame SSH",
+        "isolated Python backend"
       ],
       "browser": {
         "id": 53,
@@ -3913,6 +3921,13 @@
         "evidence": "docs/evidence/framey-library-context-2026-10-26.json",
         "mode": "real Frame read-only CEF projection; local Chromium snapshot replay; scoped actual amd64 backends",
         "frontendReady": true
+      },
+      "backendFollowUp": {
+        "evidence": "docs/evidence/framey-shotty-python-2026-10-26.md",
+        "mode": "exact archive managed transaction and isolated Python import/copy with temporary HOME",
+        "compatShim": "shotty-click-app-dir",
+        "syntheticScreenshotCopied": true,
+        "actualDeckyArm64": false
       }
     },
     {
@@ -12061,12 +12076,13 @@
         "https://github.com/sponsors/santojon"
       ],
       "status": "partial",
-      "reason": "The exact chunked frontend now initializes and renders Deck Shelves settings in an opaque local Chromium panel. Backend calls were denied; Home-screen shelf injection has no verified Steam UI target in Framey. Settings writes, real backend behavior and worn VR are unverified.",
+      "reason": "The exact chunked frontend renders settings in opaque local Chromium. The official Python backend saved a shelf and returned it after reopen with a stub Decky module and temporary settings directory. Actual Decky RPC, real Frame settings, Steam Home shelf injection and worn VR remain unverified.",
       "blockInstall": false,
       "verification": [
         "static archive",
         "local browser",
-        "fake-Frame"
+        "fake-Frame",
+        "isolated Python backend"
       ],
       "browser": {
         "id": 135,
@@ -12101,6 +12117,13 @@
         "mode": "exact archive in opaque local Chromium; backend and network denied",
         "frontendReady": true,
         "settingsRendered": true
+      },
+      "backendFollowUp": {
+        "evidence": "docs/evidence/framey-deck-shelves-browser-2026-10-26.md",
+        "mode": "exact archive Python with stub Decky module and temporary settings directory",
+        "defaultSettingsRead": true,
+        "shelfSaveReopen": true,
+        "actualDeckyRpc": false
       }
     },
     {

ui/framey-host.js

@@ -390,6 +390,7 @@
     addPatch:()=>()=>{}, removePatch:()=>{}, addGlobalComponent:()=>{}, removeGlobalComponent:()=>{},
   };
   const noPatch = () => {const undo=()=>{};undo.unpatch=undo;return undo;};
+  class MissingSteamComponent {}
   const showModal = element => {
     let resolveClosed;
     const ClosedPromise = new Promise(resolve=>{resolveClosed=resolve;});
@@ -509,7 +510,11 @@
       for(const classes of classModules.values())
         for(const name of Object.keys(classes)) if(classes[name]===token)return name;
     },
-    findSP:()=>null, fakeRenderComponent:()=>null,
+    findSP:()=>null,
+    // Some legacy panels dereference the type of a Steam-only component before
+    // installing a patch. Give them an inert local type; no Steam tree is
+    // rendered or patched in this isolated iframe.
+    fakeRenderComponent:()=>({type:MissingSteamComponent}),
     appDetailsClasses: {}, appDetailsHeaderClasses: {},
     useParams: () => currentParams,
   };