Prepare Frame Control 0.4.33 (#235)

* Prepare Frame Control 0.4.33

* Record Framey sample and Decky recovery limits

---------

Co-authored-by: SAPHID <saphid@users.noreply.github.com>

app/package-lock.json

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

app/package.json

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

docs/current-support-matrix.md

@@ -1,6 +1,6 @@
 # What we have tested
 
-Current for Frame Control **v0.4.32**, 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.33**, 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 |
 |---|---|---|---|---|
@@ -23,7 +23,7 @@ Current for Frame Control **v0.4.32**, 25 October 2026. “Real Frame + physical
 | 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) |
 | Experimental Frame Control SteamVR panel | Real Frame OS 0.5.6 installed its user service, registered an overlay, served authenticated live status and a read-only extension, saved a screenshot and short MP4, and removed owned resources | No | Headset was unworn in standby: overlay reported `not_visible`, stereo capture was dark; wearer-visible pixels and controller input are unverified. The new large read-only status screen has browser layout and packaging checks only | 25 Oct, v0.4.29 device check and v0.4.31 status screen: [PR #198](https://github.com/saphid/frame-control/pull/198), [PR #201](https://github.com/saphid/frame-control/pull/201), [PR #220](https://github.com/saphid/frame-control/pull/220), [panel guide](headset-app.md) |
-| Experimental Decky Loader manager | Real Frame OS 0.5.6 ARM64 user-service install, status, update and remove completed; seven official-store plugin backends loaded, and ProtonDB Badges completed managed store install/update/remove | No | Plugin pages, settings, routes, toasts and controller input in VR remain unverified; some plugins need root, x86_64 binaries or Deck-specific hardware | 25 Oct, v0.4.31: [PR #208](https://github.com/saphid/frame-control/pull/208), [compatibility table](decky-frame.md) |
-| Experimental Framey VR plugin panels and store | No live real-Frame panel test | No | ProtonDB Badges settings rendered and sent a setting call in local Chromium. The fake Frame and CI exercised the store search, install progress, quick actions, settings, local routes and toasts. Wearer-visible pixels, controller input and live settings persistence remain unverified | 25 Oct, v0.4.32: [#223](https://github.com/saphid/frame-control/pull/223), [#224](https://github.com/saphid/frame-control/pull/224), [#225](https://github.com/saphid/frame-control/pull/225), [#226](https://github.com/saphid/frame-control/pull/226), [#227](https://github.com/saphid/frame-control/pull/227), [browser/fake Frame evidence](evidence/framey-browser-2026-10-25.md), [guide](framey-loader.md) |
+| Experimental Decky Loader manager | Real Frame OS 0.5.6 ARM64 user-service install, status, update and remove completed; seven official-store plugin backends loaded, and ProtonDB Badges completed managed store install/update/remove | No | v0.4.33 shared transaction lock and stopped-loader plugin removal have Linux and CI tests, but no live recovery test on the Frame. Plugin pages, settings, routes, toasts and controller input in VR remain unverified; some plugins need root, x86_64 binaries or Deck-specific hardware | 25 Oct, v0.4.31 hardware and v0.4.33 tests: [PR #208](https://github.com/saphid/frame-control/pull/208), [PR #230](https://github.com/saphid/frame-control/pull/230), [PR #234](https://github.com/saphid/frame-control/pull/234), [compatibility table](decky-frame.md) |
+| Experimental Framey VR plugin panels and store | No live real-Frame panel test | No | ProtonDB Badges settings rendered and sent a setting call in local Chromium. Fake Frame tests cover setting read/write through update and reinstall; page tests cover the official JSX runtime, stale job recovery and an author sample bundle. The sample is not published in the store. Wearer-visible pixels, controller input and live settings persistence remain unverified | 25 Oct, v0.4.32–0.4.33: [#223](https://github.com/saphid/frame-control/pull/223), [#224](https://github.com/saphid/frame-control/pull/224), [#225](https://github.com/saphid/frame-control/pull/225), [#226](https://github.com/saphid/frame-control/pull/226), [#227](https://github.com/saphid/frame-control/pull/227), [#229](https://github.com/saphid/frame-control/pull/229), [#231](https://github.com/saphid/frame-control/pull/231), [#232](https://github.com/saphid/frame-control/pull/232), [#233](https://github.com/saphid/frame-control/pull/233), [browser/fake Frame evidence](evidence/framey-browser-2026-10-25.md), [guide](framey-loader.md) |
 
 Release notes must preserve these limits until a newer recorded check changes them. When a feature is retested, add its date, exact app/Frame version, host type and proof here. The older [v0.3.1 matrix](support-matrix.html) is a historical snapshot and does not describe current coverage.

docs/framey-loader.md

@@ -65,14 +65,18 @@ Search matches names, authors, and descriptions. Filters show non-root plugins
 or installed plugins, and Previous/Next buttons browse 20 results per page.
 The root label is a compatibility warning; other APIs are checked only when a
 plugin is opened. The store still needs the managed Decky user service running
-before its Install or Update buttons are enabled.
+before its Install or Update buttons are enabled. If a plugin prevents Decky
+from starting, Remove remains available for Frame Control-owned plugins while
+the managed service is stopped; it does not restart the service.
 
 Install, Update, and Remove show the current job stage in the headset panel.
 The store verifies each downloaded archive and the headset applies it with a
 rollback if Decky cannot start. The panel remembers the current job ID for this
 browser session, so **Check result** can resume polling after a navigation or
 temporary connection error. Refresh the installed list before starting another
-operation after an error.
+operation after an error. If Frame Control restarts, it cannot recover the old
+job result. The panel clears that job ID and asks you to refresh the installed
+list before making another change.
 
 ## For plugin authors
 

tests/page/framey_store.mjs

@@ -60,6 +60,16 @@ assert.equal(el('deckyJobStatus').textContent,'Installed Plugin 2');
 assert.equal(el('deckyJobProgress').value,100);
 assert.equal(el('deckyJobCheck').hidden,true);
 assert.equal(session.has('frameyPluginJob'),false);
+// A stopped Decky service must still offer recovery by removing its owned plugin.
+ctx.mockApi=async path => path==='/api/decky' ?
+  {managed:true,running:false,plugins:[{storeId:2,name:'Plugin 2',version:'1.0'}]} :
+  Promise.reject(Error(`unexpected ${path}`));
+vm.runInContext('api=mockApi',ctx);
+await vm.runInContext('refreshDecky()',ctx);
+assert.equal(el('deckyInstalled').children[0].children[2].disabled,false);
+el('deckySearch').value='';el('deckyStoreFilter').value='all';
+vm.runInContext('showDeckyStore()',ctx);
+assert.equal(el('deckyStoreList').children[1].children[1].disabled,true);
 ctx.mockApi=async path => {
   if(path==='/api/decky/plugin')return {job:'job-2'};
   if(path.startsWith('/api/job'))return {done:true,error:'archive digest mismatch'};
@@ -70,3 +80,17 @@ vm.runInContext('api=mockApi',ctx);
 await vm.runInContext('deckyChange("update",{id:2,name:"Plugin 2"})',ctx);
 assert.match(el('deckyJobStatus').textContent,/Error: archive digest mismatch/);
 assert.equal(session.has('frameyPluginJob'),false);
+
+// A saved job does not survive a server restart. Clear it instead of offering
+// Check result forever for an ID that the new server cannot know.
+session.set('frameyPluginJob',JSON.stringify({job:'old-job',action:'install',name:'Plugin 2'}));
+ctx.mockApi=async path => {
+  if(path.startsWith('/api/job'))throw Error('no such job (the app may have restarted)');
+  if(path==='/api/decky')return {running:true,plugins:[]};
+  throw Error(`unexpected ${path}`);
+};
+vm.runInContext('api=mockApi',ctx);
+await vm.runInContext('checkDeckyJob()',ctx);
+assert.match(el('deckyJobStatus').textContent,/app restarted and lost this job result/);
+assert.equal(el('deckyJobCheck').hidden,true);
+assert.equal(session.has('frameyPluginJob'),false);

tests/test_frame_decky_store.py

@@ -112,6 +112,18 @@ class StoreTransaction(unittest.TestCase):
         self.assertNotEqual(result.returncode, 0)
         self.assertTrue(external.exists())
 
+    def test_remove_while_service_is_stopped_does_not_restart_it(self):
+        data, _ = archive()
+        self.assertEqual(self.apply('install', data).returncode, 0)
+        fake = Path(self.tmp.name) / 'systemctl'
+        fake.write_text('#!/bin/sh\nif [ "$2" = is-active ]; then exit 1; fi\n'
+                        'echo "$*" >> "$HOME/service-calls"\nexit 0\n')
+        result = self.apply('remove')
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertFalse(self.folder.exists())
+        self.assertEqual((Path(self.tmp.name) / 'service-calls').read_text().splitlines(),
+                         ['--user stop frame-control-decky.service'])
+
     def test_shared_lock_rejects_plugin_and_loader_changes(self):
         import fcntl
 
@@ -136,6 +148,30 @@ class StoreTransaction(unittest.TestCase):
 
 
 class StoreHost(unittest.TestCase):
+    def test_stopped_managed_service_allows_removing_owned_plugin(self):
+        state = {'managed': True, 'running': False, 'plugins':
+                 [{'storeId': 42, 'folder': 'Example', 'name': 'Example', 'version': '1.0'}]}
+        calls = []
+        with patch.object(frame_decky_store.frame_decky, 'status', return_value=state), \
+             patch.object(frame_decky_store, 'catalog') as network:
+            result = frame_decky_store.change(lambda command, **kwargs: calls.append(command) or '{}',
+                                               'remove', 42)
+        self.assertEqual(result, {})
+        self.assertEqual(len(calls), 1)
+        network.assert_not_called()
+
+    def test_renamed_store_plugin_cannot_be_installed_twice(self):
+        state = {'managed': True, 'running': True, 'plugins':
+                 [{'storeId': 42, 'folder': 'OldFolder', 'name': 'Old Name', 'version': '1.0'}]}
+        catalog = [{'id': 42, 'name': 'New Name', 'root': False, 'sha256': 'a' * 64, 'version': '2.0'}]
+        with patch.object(frame_decky_store.frame_decky, 'status', return_value=state), \
+             patch.object(frame_decky_store, 'catalog', return_value=catalog) as network, \
+             patch.object(frame_decky_store.urllib.request, 'urlopen', side_effect=AssertionError('No download expected')):
+            with self.assertRaisesRegex(ValueError, 'already installed'):
+                frame_decky_store.change(lambda *args, **kwargs: self.fail('No headset write expected'),
+                                         'install', 42)
+            network.assert_not_called()
+
     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'}]}

ui/frame_decky_store.py

@@ -151,7 +151,8 @@ try:
             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')
+    # 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:
         if action!='install': target.rename(backup)
         if action!='remove': (stage/folder).rename(target)
@@ -176,9 +177,13 @@ def change(ssh, action, plugin_id, report=lambda stage, percent=None: None):
         raise ValueError('Choose a valid store plugin action')
     report('Checking installed plugins', 5)
     state = frame_decky.status(ssh)
-    if not state['managed'] or not state['running']:
-        raise ValueError('Start Frame Control managed Decky before changing plugins')
+    if not state['managed']:
+        raise ValueError('Install Frame Control managed Decky before changing plugins')
+    if action != 'remove' and not state['running']:
+        raise ValueError('Start Frame Control managed Decky before installing or updating plugins')
     installed = [p for p in state['plugins'] if p.get('storeId') == plugin_id]
+    if action == 'install' and installed:
+        raise ValueError('This store plugin is already installed; use Update or Remove')
     if action == 'remove':
         if len(installed) != 1:
             raise ValueError('Only an installed Frame Control store plugin can be removed')

ui/headset.html

@@ -105,7 +105,9 @@ async function refreshGames(){const list=byId('games');try{const data=await api(
   }catch(error){list.textContent=error.message;}}
 let deckyState=null, deckyStore=[], deckyStoreIndex=0, activeFrameyId=null, deckyBusy=false;
 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.';
+  byId('deckyState').textContent=deckyState.running?'Decky loader is running. Backend loading is not a VR menu check.':
+    deckyState.managed?'Decky is stopped. You can remove a managed plugin to recover, then start Decky from Frame Control on your computer.':
+    '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);
@@ -148,7 +150,15 @@ function deckyJobView(title,message,percent,failed=false){
 }
 async function followDeckyJob(job,action,name){
   for(let n=0;n<180;n++){
-    const progress=await api(`/api/job?id=${encodeURIComponent(job)}`);
+    let progress;
+    try{progress=await api(`/api/job?id=${encodeURIComponent(job)}`);}
+    catch(error){
+      if(/no such job/i.test(error.message)){
+        sessionStorage.removeItem('frameyPluginJob');
+        throw Error('The app restarted and lost this job result. Refresh installed plugins to see what changed.');
+      }
+      throw error;
+    }
     if(progress.done){if(progress.error){sessionStorage.removeItem('frameyPluginJob');throw Error(progress.error);}
       deckyJobView(`${action} ${name}`,progress.message||`${action} complete`,100);return;}
     deckyJobView(`${action} ${name}`,progress.stage||'Waiting for Frame…',progress.percent);
@@ -168,7 +178,7 @@ async function deckyChange(action,plugin){if(deckyBusy||!confirm(`${action} ${pl
   finally{deckyBusy=false;await refreshDecky();}
 }
 async function checkDeckyJob(){let saved;try{saved=JSON.parse(sessionStorage.getItem('frameyPluginJob')||'null');}catch(_){saved=null;}
-  if(!saved||typeof saved.job!=='string')return;
+  if(!saved||typeof saved.job!=='string'){sessionStorage.removeItem('frameyPluginJob');return;}
   deckyBusy=true;byId('deckyJobCheck').hidden=true;
   try{await followDeckyJob(saved.job,saved.action,saved.name);sessionStorage.removeItem('frameyPluginJob');}
   catch(error){deckyJobView(`${saved.action} ${saved.name}`,`Error: ${error.message}`,null,true);}

ui/index.html

@@ -2202,7 +2202,7 @@ async function loadDecky() {
       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.disabled=!d.managed||!$('deckyAck').checked;
       remove.onclick=()=>changeDeckyPlugin('remove',{id:plugin.storeId,name:plugin.name});
       row.append(label,remove);managedList.append(row);}
     deckyButtons();
@@ -2236,7 +2236,7 @@ function showDeckyStore() {
       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.disabled=!deckyInfo?.managed || !$('deckyAck').checked;
         remove.onclick=()=>changeDeckyPlugin('remove',plugin);row.append(remove);}
     }
     list.append(row);
@@ -2255,7 +2255,7 @@ function deckyButtons() {
   $('deckyRemove').disabled = !ack || !deckyInfo?.managed;
 }
 $('deckyAck').onchange = () => { deckyButtons(); showDeckyStore();
-  for(const button of $('deckyManagedList').querySelectorAll('button'))button.disabled=!$('deckyAck').checked||!deckyInfo?.running; };
+  for(const button of $('deckyManagedList').querySelectorAll('button'))button.disabled=!$('deckyAck').checked||!deckyInfo?.managed; };
 $('deckyRefresh').onclick = loadDecky;
 $('deckyStoreRefresh').onclick = loadDeckyStore;
 $('deckyStoreSearch').oninput = showDeckyStore;