Merge remote-tracking branch 'origin/main' into review/framey-api

# Conflicts:
#	docs/framey-loader.md
#	tests/page/framey_actions.mjs
#	tests/test_framey_panel.py
#	ui/framey-host.js
#	ui/framey_panel.py

docs/decky-frame.md

@@ -57,9 +57,11 @@ change Frame Control owned plugin folders under
 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.
+shows installed plugins and store actions. Its separate Framey iframe now hosts
+compatible API v2 plugin pages, settings, local routes, and panel toasts.
+Steam route patches and system notifications remain unavailable. The panel
+still needs a worn-headset visual and controller check. See the
+[current compatibility table](frame-plugin-author.md#framey-api-v2-compatibility).
 
 ## What was checked on the real headset
 

docs/frame-plugin-author.md

@@ -37,3 +37,26 @@ 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).
+
+## Framey API v2 compatibility
+
+Framey hosts a plugin's frontend in an isolated iframe in the Frame Control
+SteamVR panel. The table describes the current implementation and its tests;
+none of these frontend controls has passed a worn-headset check yet.
+
+| Decky API or UI feature | Framey behavior | Verified in |
+| --- | --- | --- |
+| `definePlugin` with `content`, `titleView` | Renders a React panel and optional title | Local browser with ProtonDB Badges; host unit test |
+| `PanelSection`, rows, buttons, toggles, dropdowns | Local touch-sized controls | Local browser and host unit test |
+| Optional `settings`, `frameyQuickActions` | Separate settings tab; up to eight actions with result text | Host unit test; these fields are Framey additions |
+| `serverAPI.call` / `callable` | Calls only that plugin's Decky Python backend via the headset service | Fake Frame e2e for get/set setting; host unit test |
+| `toaster.toast` | Visible toast inside the plugin panel; `dismiss` and optional `onClick` | Host unit test; no Steam system notification |
+| `routerHook.addRoute` / `removeRoute`, `Navigation.Navigate` / `NavigateBack` | Local routes inside this plugin panel only | Host unit test |
+| `routerHook.addPatch`, global components | No-op; cannot patch Steam routes | Not applicable |
+| Steam library/store patches, CEF tab injection | Unavailable; no matching target in the isolated panel | Frame CEF inspection |
+| `fetchNoCors`, Decky event listeners, file picker, root calls | Unavailable | Not supported by Framey |
+
+Keep routes local to the panel and give every operation a visible result. A
+plugin that calls `Navigation.Navigate('/decky/store')` will not open the
+Frame Control store; only paths registered by that same plugin can navigate.
+Toasts stay inside the panel, so keep essential errors in the plugin UI too.

docs/framey-loader.md

@@ -38,11 +38,11 @@ does not receive Frame Control's UI key. React and ReactDOM are bundled for
 offline use under their MIT licenses in `ui/vendor`.
 
 The host currently supplies sections, rows, buttons, toggles, dropdowns,
-scroll containers, a modal, locale information, and backend calls for the
-plugin that owns the panel. Steam library/store page patches, global Steam UI
-components, Decky route hooks, file pickers, and privileged root methods have
-no VR target. A plugin that depends on them can render only part of its UI or
-show an incompatibility message. A Decky plugin's Python backend still runs as
+scroll containers, a modal, locale information, local panel routes and toasts,
+and backend calls for the plugin that owns the panel. Steam library/store page
+patches, global Steam UI components, file pickers, and privileged root methods
+have no VR target. A plugin that depends on them can render only part of its UI
+or show an incompatibility message. A Decky plugin's Python backend still runs as
 the headset user when Decky loads it, so review third-party code before opting
 in. The panel iframe can make HTTPS requests subject to ordinary browser CORS.
 
@@ -61,6 +61,13 @@ 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.
 
+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.
+
 ## For plugin authors
 
 Publish a normal [Decky store](https://plugins.deckbrew.xyz/) API v2 release
@@ -76,6 +83,17 @@ about Steam Deck hardware. Declare settings defaults so a fresh user service
 can render without pre-existing files. Test your ZIP with the store validator
 and the fake Frame flow before asking users to install it.
 
+An API v2 plugin's normal `content` is its default VR panel. Framey also shows
+an optional `settings` React element under a **Settings** tab and an optional
+`titleView` above it. For one-tap headset controls, return
+`frameyQuickActions: [{label: 'Refresh data', onClick: refreshData}]` from the
+plugin initializer. Framey displays up to eight actions and reports a pending,
+success, or failure state. These descriptor fields are Framey additions; Decky
+ignores them. Use a plugin backend method through `@decky/api` for work needing
+persistent state, and keep a quick action safe to repeat.
+See the [API v2 compatibility table](frame-plugin-author.md#framey-api-v2-compatibility)
+for tested behavior and remaining limits.
+
 The [Frame Control extension API](extensions.md) is an alternative for a
 Frame-specific panel. It needs only a local manifest, HTML, and the read-only
 `status` bridge; it does not need Decky.

tests/page/framey_actions.mjs

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import {readFileSync} from 'node:fs';
+import vm from 'node:vm';
+
+const source=readFileSync(new URL('../../ui/framey-host.js',import.meta.url),'utf8');
+const testSource=source.replace(/\n  start\(\);\n\}\)\(\);\s*$/, '\n  window.__surface=PluginSurface;\n})();');
+assert.notEqual(testSource,source);
+const states=[];
+const React={Fragment:'fragment',Component:class {},createElement:(type,props,...children)=>({type,props:props||{},children}),
+  useState:value=>[value,next=>states.push(next)], useEffect(){},isValidElement:value=>!!value?.type};
+class Element {constructor(){this.children=[];this.textContent='';this.attributes={};}
+  append(...children){this.children.push(...children);}setAttribute(key,value){this.attributes[key]=value;}
+  remove(){this.removed=true;}}
+const elements=new Map();
+const window={React,ReactDOM:{createRoot:()=>({render(){}})},addEventListener(){}};
+const listeners=[];const messages=[];const parent={postMessage:message=>messages.push(message)};
+const context=vm.createContext({window,document:{getElementById:id=>{
+  if(!elements.has(id))elements.set(id,new Element());return elements.get(id);},createElement:()=>new Element()},
+  navigator:{language:'en'}, parent,addEventListener:(type,handler)=>listeners.push({type,handler}),
+  setTimeout:()=>1,clearTimeout(){}});
+vm.runInContext(testSource,context);
+const nodes=(tree,type)=>[...(tree?.type===type?[tree]:[]),...(tree?.children||[]).flatMap(child=>nodes(child,type))];
+let called=0;
+const plugin={content:{type:'content'},settings:{type:'settings'},titleView:{type:'title'},
+  frameyQuickActions:[{label:'Refresh data',onClick:async()=>{called++;return 'Fresh';}},
+    {label:'invalid'},...Array.from({length:9},(_,i)=>({label:`Action ${i}`,onClick:()=>{}}))]};
+const tree=window.__surface({plugin});
+const buttons=nodes(tree,'button');
+assert.equal(buttons.length,9); // Panel, Settings, and seven valid actions inside the first eight entries.
+assert.equal(nodes(tree,'nav')[0].props['aria-label'],'Plugin views');
+assert.equal(nodes(tree,'section')[0].props['aria-label'],'Plugin quick actions');
+assert.equal(nodes(tree,'header').length,1);
+await buttons[2].props.onClick();
+assert.equal(called,1);
+assert.deepEqual(states.slice(-3),[0,'Refresh data…','Fresh',null].slice(-3));
+assert.equal(nodes(window.__surface({plugin:{settings:{type:'settings'}}}),'nav').length,1);
+
+// API v2 backend calls remain request-scoped and errors return to the caller.
+const api=window.__DECKY_SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED_deckyLoaderAPIInit.connect(2,'Test');
+const reply=api.call('get_setting','mode','default');
+assert.equal(messages[0].method,'get_setting');
+assert.deepEqual(Array.from(messages[0].args),['mode','default']);
+listeners.find(x=>x.type==='message').handler({source:parent,data:{type:'framey:reply',id:messages[0].id,result:'dark'}});
+assert.equal(await reply,'dark');
+await assert.rejects(api.call('x;alert(1)'),/Invalid backend method/);
+
+const toast=api.toaster.toast({title:'Saved',body:'Mode updated',duration:4000});
+const toastNode=elements.get('framey-toasts').children[0];
+assert.equal(toastNode.attributes.role,'status');
+assert.equal(toastNode.children[0].textContent,'Saved');
+assert.equal(toastNode.children[1].textContent,'Mode updated');
+toast.dismiss();assert.equal(toastNode.removed,true);
+
+function LocalRoute(){return React.createElement('p',null,'Route content');}
+const undo=api.routerHook.addRoute('/plugin/details',LocalRoute);
+assert.equal(window.DFL.Navigation.Navigate('/plugin/details'),true);
+assert.equal(nodes(window.__surface({plugin}),LocalRoute).length,1);
+assert.equal(window.DFL.Navigation.Navigate('/decky/store'),false);
+undo();assert.equal(window.DFL.Navigation.Navigate('/plugin/details'),false);

tests/page/framey_store.mjs

@@ -9,13 +9,16 @@ class Element {
   append(...nodes) {this.children.push(...nodes);}
   replaceChildren(...nodes) {this.children=nodes; this.textContent='';}
   scrollIntoView() {}
+  removeAttribute(name) {delete this[name];}
 }
 const elements = new Map();
 elements.set('deckyStoreFilter',Object.assign(new Element('deckyStoreFilter'),{value:'all'}));
 const document = {getElementById(id) {if(!elements.has(id)) elements.set(id,new Element(id)); return elements.get(id);},
   createElement() {return new Element();}, hidden:false};
+const session = new Map();
 const ctx = vm.createContext({document, location:{hash:'',pathname:'/'},
-  sessionStorage:{getItem:()=>'',setItem(){}}, history:{replaceState(){}},
+  sessionStorage:{getItem:key=>session.get(key)||'',setItem:(key,value)=>session.set(key,value),removeItem:key=>session.delete(key)},
+  history:{replaceState(){}}, confirm:()=>true,
   window:{addEventListener(){}}, setInterval(){}, setTimeout(){},
   fetch(){throw Error('No network expected');}, console});
 vm.runInContext(script,ctx);
@@ -43,3 +46,27 @@ el('deckyStoreFilter').value='compatible'; el('deckyStoreFilter').onchange();
 assert.equal(el('deckyStoreSummary').textContent,'42 plugins found');
 el('deckySearch').value='no matching plugin'; el('deckySearch').oninput();
 assert.equal(el('deckyStoreList').textContent,'No plugins match this search.');
+
+// The page polls the actual job endpoint and keeps a separate visible result.
+ctx.mockApi=async path => {
+  if(path==='/api/decky/plugin')return {job:'job-1'};
+  if(path.startsWith('/api/job'))return {done:true,message:'Installed Plugin 2'};
+  if(path==='/api/decky')return {running:true,plugins:[{storeId:2,name:'Plugin 2',version:'1.0'}]};
+  throw Error(`unexpected ${path}`);
+};
+vm.runInContext('api=mockApi',ctx);
+await vm.runInContext('deckyChange("install",{id:2,name:"Plugin 2"})',ctx);
+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);
+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'};
+  if(path==='/api/decky')return {running:true,plugins:[]};
+  throw Error(`unexpected ${path}`);
+};
+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);

tests/test_frame_decky_store.py

@@ -118,10 +118,12 @@ class StoreHost(unittest.TestCase):
                  [{'storeId': 42, 'folder': 'Example', 'name': 'Example', 'version': '1.0'}]}
         def ssh(command, **kwargs):
             return '{}'
+        progress = []
         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)
+            frame_decky_store.change(ssh, 'remove', 42, lambda stage, percent: progress.append((stage, percent)))
             network.assert_not_called()
+        self.assertEqual(progress, [('Checking installed plugins', 5), ('Removing plugin on Frame', 80)])
 
 
 if __name__ == '__main__':

tests/test_framey_panel.py

@@ -25,6 +25,11 @@ class Panel(unittest.TestCase):
                                 capture_output=True, text=True, timeout=10)
         self.assertEqual(result.returncode, 0, result.stderr)
 
+    def test_plugin_quick_actions_and_settings(self):
+        result = subprocess.run(['node', str(Path(__file__).parent/'page/framey_actions.mjs')],
+                                capture_output=True, text=True, timeout=10)
+        self.assertEqual(result.returncode, 0, result.stderr)
+
     def setUp(self):
         tmp = tempfile.TemporaryDirectory()
         self.addCleanup(tmp.cleanup)
@@ -42,6 +47,7 @@ class Panel(unittest.TestCase):
         page = framey_panel.panel(14).decode()
         self.assertIn('framey-bundle', page)
         self.assertIn('/framey-runtime/host.js', page)
+        self.assertIn('framey-toasts', page)
         self.assertNotIn('X-Frame-UI', page)
         self.assertNotIn('SP_REACT.createElement', page)  # bundled code is base64, not executable HTML.
         with self.assertRaises(FileNotFoundError):

ui/frame_decky_store.py

@@ -162,9 +162,10 @@ finally:
 '''
 
 
-def change(ssh, action, plugin_id):
+def change(ssh, action, plugin_id, report=lambda stage, percent=None: None):
     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')
+    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')
@@ -175,6 +176,7 @@ def change(ssh, action, plugin_id):
         folder = installed[0]['folder']
         plugin = {'sha256': '0' * 64, 'version': 'removed'}
     else:
+        report('Reading official store', 15)
         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')
@@ -187,9 +189,11 @@ def change(ssh, action, plugin_id):
             raise ValueError('Only an installed Frame Control store plugin can be updated')
     data = None
     if action != 'remove':
+        report('Downloading plugin archive', 30)
         url = _urls()[1] + 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)
+        report('Verifying plugin archive', 50)
         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')
@@ -199,7 +203,9 @@ def change(ssh, action, plugin_id):
     remote = '/tmp/frame-control-decky-plugin-' + token
     try:
         if data is not None:
+            report('Sending archive to Frame', 65)
             ssh('umask 077; cat > ' + remote, stdin=data, text=False, timeout=120)
+        report({'install':'Installing', 'update':'Updating', 'remove':'Removing'}[action] + ' plugin on Frame', 80)
         return json.loads(ssh(f'python3 - {action} {token} {plugin_id} {plugin["sha256"]} {folder} {plugin["version"]}',
                               stdin=APPLY, timeout=90))
     finally:

ui/framey-host.js

@@ -6,7 +6,11 @@
   window.LocalizationManager = {m_rgLocalesToUse:[navigator.language || 'en']};
   const root = document.getElementById('framey-root');
   const error = document.getElementById('framey-error');
+  const toastRoot = document.getElementById('framey-toasts');
   const pending = new Map();
+  const routes = new Map();
+  const routeListeners = new Set();
+  let currentRoute = null;
   let nextId = 0;
   let plugin;
 
@@ -48,13 +52,32 @@
     R.createElement('button', {type:'button', onClick:()=>{onOK?.(); closeModal();}}, strOKButtonText || 'Close'));
   const modalRoot = window.ReactDOM.createRoot(document.getElementById('framey-modal'));
   const closeModal = () => modalRoot.render(null);
+  function navigate(path) {
+    if (path !== null && (!/^\/[A-Za-z0-9/_-]{1,120}$/.test(path) || !routes.has(path))) return false;
+    currentRoute = path;
+    for (const listener of routeListeners) listener(path);
+    return true;
+  }
+  const routerHook = {
+    addRoute(path, component) {
+      if (!/^\/[A-Za-z0-9/_-]{1,120}$/.test(path) ||
+          (typeof component !== 'function' && !R.isValidElement(component)))
+        throw Error('Framey route needs a local path and React component');
+      routes.set(path, component);
+      return () => {routes.delete(path); if(currentRoute === path) navigate(null);};
+    },
+    removeRoute(path) {routes.delete(path); if(currentRoute === path) navigate(null);},
+    // Steam routes and global components have no equivalent in the isolated panel.
+    addPatch:()=>()=>{}, removePatch:()=>{}, addGlobalComponent:()=>{}, removeGlobalComponent:()=>{},
+  };
   const DFL = window.DFL = {
     definePlugin: init => init,
     PanelSection, PanelSectionRow: passthrough('div'), Field, ToggleField, DropdownItem, ButtonItem,
     Focusable: passthrough('div'), ScrollPanel: passthrough('div'), ScrollPanelGroup: passthrough('div'),
     DialogButton: passthrough('button'), ConfirmModal,
     staticClasses: {Title:'framey-title'},
-    Navigation: {NavigateToExternalWeb: url => { if (/^https:\/\//.test(url)) window.open(url, '_blank', 'noopener'); }},
+    Navigation: {Navigate:navigate, NavigateBack:()=>navigate(null),
+      NavigateToExternalWeb: url => { if (/^https:\/\//.test(url)) window.open(url, '_blank', 'noopener'); }},
     showModal: element => modalRoot.render(R.createElement('section', null,
       R.createElement('button', {onClick:closeModal}, 'Close'), element)),
     // Steam app, library, and store patches have no target inside this panel.
@@ -64,21 +87,72 @@
     useParams: () => ({}),
   };
   DFL.DialogButton.render = () => ({type: DFL.DialogButton});
-  const noRoute = {addPatch:()=>()=>{}, removePatch:()=>{}, addGlobalComponent:()=>{}, removeGlobalComponent:()=>{}};
-  const toaster = {toast: ({title, body}) => { error.textContent = [title, body].filter(Boolean).join(': '); }};
+  const toaster = {toast: ({title, body, duration, showToast=true, onClick}={}) => {
+    const data = {title, body};
+    if (!showToast) return {data, dismiss(){}};
+    const item = document.createElement('section');
+    item.setAttribute('role','status');
+    const heading = document.createElement('strong'); heading.textContent = String(title || 'Plugin notice');
+    const detail = document.createElement('p'); detail.textContent = String(body || '');
+    const close = document.createElement('button'); close.type='button'; close.textContent='Dismiss';
+    const dismiss = () => {item.remove(); clearTimeout(timer);};
+    close.onclick=dismiss; item.append(heading, detail, close);
+    if (typeof onClick === 'function') {
+      const open = document.createElement('button'); open.type='button'; open.textContent='Open';
+      open.onclick=()=>{onClick(); dismiss();}; item.append(open);
+    }
+    toastRoot.append(item);
+    const timer = setTimeout(dismiss, Math.min(30000,Math.max(3000,Number(duration)||5000)));
+    return {data,dismiss};
+  }};
   class PanelBoundary extends R.Component {
     constructor(props) { super(props); this.state = {failure:null}; }
     static getDerivedStateFromError(failure) { return {failure}; }
     render() { return this.state.failure ? R.createElement('p', null,
       `This Decky panel is not compatible with Framey: ${this.state.failure.message}`) : this.props.children; }
   }
+  function PluginSurface({plugin}) {
+    const [view, setView] = R.useState(plugin.content ? 'panel' : 'settings');
+    const [route, setRoute] = R.useState(currentRoute);
+    R.useEffect(() => {routeListeners.add(setRoute); return () => routeListeners.delete(setRoute);}, []);
+    const [running, setRunning] = R.useState(null);
+    const [message, setMessage] = R.useState('');
+    const actions = Array.isArray(plugin.frameyQuickActions) ? plugin.frameyQuickActions.slice(0, 8)
+      .filter(action => action && typeof action.label === 'string' && action.label.length <= 80 &&
+        typeof action.onClick === 'function') : [];
+    async function runAction(action, index) {
+      if (running !== null) return;
+      setRunning(index); setMessage(`${action.label}…`);
+      try {
+        const result = await action.onClick();
+        setMessage(typeof result === 'string' && result.length < 200 ? result : `${action.label} done`);
+      } catch (failure) { setMessage(`${action.label} failed: ${failure.message || failure}`); }
+      finally { setRunning(null); }
+    }
+    return R.createElement(R.Fragment, null,
+      plugin.titleView && R.createElement('header', null, plugin.titleView),
+      route && R.createElement('button', {type:'button', onClick:()=>navigate(null)}, 'Back to plugin'),
+      plugin.settings && R.createElement('nav', {'aria-label':'Plugin views'},
+        R.createElement('button', {type:'button', 'aria-current':view === 'panel' ? 'page' : undefined,
+          onClick:()=>setView('panel')}, 'Panel'),
+        R.createElement('button', {type:'button', 'aria-current':view === 'settings' ? 'page' : undefined,
+          onClick:()=>setView('settings')}, 'Settings')),
+      actions.length > 0 && R.createElement('section', {'aria-label':'Plugin quick actions'},
+        R.createElement('h2', null, 'Quick actions'),
+        ...actions.map((action, index) => R.createElement('button', {key:index, type:'button',
+          disabled:running !== null, onClick:()=>runAction(action,index)}, action.label))),
+      message && R.createElement('p', {role:'status'}, message),
+      R.createElement('div', null, route ? (typeof routes.get(route) === 'function' ?
+        R.createElement(routes.get(route)) : routes.get(route)) :
+        (view === 'settings' ? plugin.settings : plugin.content)));
+  }
   window.__DECKY_SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED_deckyLoaderAPIInit = {
     connect: (version, name) => ({
       _version: Math.min(version, 2),
       call: (method, ...args) => ask(method, args),
       callable: method => (...args) => ask(method, args),
       addEventListener: () => {}, removeEventListener: () => {},
-      routerHook:noRoute, toaster,
+      routerHook, toaster,
       fetchNoCors: () => Promise.reject(Error('Decky proxy fetch is unavailable in Framey')),
       executeInTab: () => Promise.reject(Error('Steam tab injection is unavailable in Framey')),
       injectCssIntoTab: () => Promise.reject(Error('Steam tab injection is unavailable in Framey')),
@@ -95,8 +169,9 @@
       try { module = await import(url); } finally { URL.revokeObjectURL(url); }
       if (typeof module.default !== 'function') throw Error('The Decky frontend has no plugin entry point');
       plugin = await module.default();
-      if (!plugin?.content) throw Error('The Decky plugin has no panel to display');
-      window.ReactDOM.createRoot(root).render(R.createElement(PanelBoundary, null, plugin.content));
+      if (!plugin?.content && !plugin?.settings) throw Error('The Decky plugin has no panel to display');
+      window.ReactDOM.createRoot(root).render(R.createElement(PanelBoundary, null,
+        R.createElement(PluginSurface, {plugin})));
       parent.postMessage({type:'framey:ready'}, '*');
     } catch (failure) {
       error.textContent = `This Decky panel is not compatible with Framey: ${failure.message}`;

ui/framey_panel.py

@@ -59,9 +59,9 @@ def panel(plugin_id):
     return ('''<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
 <title>Framey plugin</title><style>body{font:21px/1.4 system-ui;background:#0d1925;color:#f3f7fa;margin:0;padding:20px}
 button,select,input{font:inherit;min-height:52px;background:#23618c;color:#fff;border:1px solid #72baf0;border-radius:9px;padding:8px}
-button:focus-visible,select:focus-visible,input:focus-visible{outline:4px solid #f8d370}section{padding:12px;margin:12px 0;background:#1b3042;border-radius:10px}
+button:focus-visible,select:focus-visible,input:focus-visible{outline:4px solid #f8d370}button{margin:4px 8px 4px 0}button:disabled{opacity:.55}section{padding:12px;margin:12px 0;background:#1b3042;border-radius:10px}
 label{display:grid;gap:6px;margin:10px 0}small{color:#b9c9d6}</style>
-<p id="framey-error" role="status"></p><div id="framey-root"></div><div id="framey-modal"></div>
+<p id="framey-error" role="status"></p><div id="framey-toasts" aria-live="polite"></div><div id="framey-root"></div><div id="framey-modal"></div>
 <script id="framey-bundle" type="application/json">''' + encoded + '''</script>
 <script src="/framey-runtime/react.js"></script><script src="/framey-runtime/react-dom.js"></script>
 <script src="/framey-runtime/host.js"></script></html>''').encode()

ui/headset.html

@@ -46,6 +46,9 @@ iframe{display:block;width:100%;height:560px;background:#0d1925;border:1px solid
 <h2>Decky plugins</h2><p>Manage official store plugins here. Decky's Quick Access Menu is absent from this VR shell. Framey can show compatible plugin panels and settings below; Steam library and store page patches are unavailable.</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="deckyJobPanel" class="block" hidden style="margin:14px 0"><strong id="deckyJobTitle"></strong>
+  <p id="deckyJobStatus" role="status" aria-live="polite"></p><progress id="deckyJobProgress" max="100"></progress>
+  <div class="row"><button id="deckyJobCheck" class="secondary" hidden>Check result</button></div></div>
 <div id="deckyStorePanel" hidden><div class="row" style="margin:16px 0"><label>Find a plugin <input id="deckySearch" type="search" placeholder="Name, author or description"></label>
   <label>Show <select id="deckyStoreFilter"><option value="all">All plugins</option><option value="compatible">Without root requirement</option><option value="installed">Installed plugins</option></select></label></div>
   <p id="deckyStoreSummary" role="status" aria-live="polite"></p><div id="deckyStoreList" class="stack"></div>
@@ -100,7 +103,7 @@ 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=[], deckyStoreIndex=0, activeFrameyId=null;
+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.';
   const list=byId('deckyInstalled');list.replaceChildren();
@@ -109,7 +112,7 @@ async function refreshDecky(){try{deckyState=await api('/api/decky');
     if(plugin.storeId){const open=document.createElement('button');open.className='secondary';open.textContent='Open panel';
       open.onclick=()=>openFrameyPanel(plugin.storeId,plugin.name);row.append(open);
       const button=document.createElement('button');button.className='danger';button.textContent='Remove';
-      button.onclick=()=>deckyChange('remove',{id:plugin.storeId,name:plugin.name});row.append(button);}
+      button.disabled=deckyBusy;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(){byId('deckyStorePanel').hidden=false;
@@ -134,18 +137,43 @@ function showDeckyStore(){const list=byId('deckyStoreList');list.replaceChildren
     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;
+    button.disabled=deckyBusy||!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});
-    if(job.job){let completed=false;for(let n=0;n<180;n++){await new Promise(resolve=>setTimeout(resolve,1000));
-      const progress=await api(`/api/job?id=${encodeURIComponent(job.job)}`);
-      byId('deckyState').textContent=progress.stage||progress.message||`${action} ${plugin.name}…`;
-      if(progress.done){if(progress.error)throw Error(progress.error);completed=true;break;}}
-      if(!completed)throw Error('The operation is still running. Refresh plugins to check its result.');}
-    await refreshDecky();}catch(error){byId('deckyState').textContent=error.message;}}
+function deckyJobView(title,message,percent,failed=false){
+  byId('deckyJobPanel').hidden=false;byId('deckyJobTitle').textContent=title;
+  byId('deckyJobStatus').textContent=message;
+  const bar=byId('deckyJobProgress');if(Number.isFinite(percent))bar.value=percent;else bar.removeAttribute('value');
+  byId('deckyJobCheck').hidden=!failed||!sessionStorage.getItem('frameyPluginJob');
+}
+async function followDeckyJob(job,action,name){
+  for(let n=0;n<180;n++){
+    const progress=await api(`/api/job?id=${encodeURIComponent(job)}`);
+    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);
+    await new Promise(resolve=>setTimeout(resolve,1000));
+  }
+  throw Error('Still working. Use Check result to reconnect to this job.');
+}
+async function deckyChange(action,plugin){if(deckyBusy||!confirm(`${action} ${plugin.name}? Store plugins run code as your Frame user.`))return;
+  deckyBusy=true;showDeckyStore();
+  deckyJobView(`${action} ${plugin.name}`,'Starting…',0);
+  try{const started=await api('/api/decky/plugin',{action,id:plugin.id,acknowledged:true});
+    if(!started.job)throw Error('The server did not return a job ID');
+    sessionStorage.setItem('frameyPluginJob',JSON.stringify({job:started.job,action,name:plugin.name}));
+    await followDeckyJob(started.job,action,plugin.name);
+    sessionStorage.removeItem('frameyPluginJob');
+  }catch(error){deckyJobView(`${action} ${plugin.name}`,`Error: ${error.message}`,null,true);}
+  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;
+  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);}
+  finally{deckyBusy=false;await refreshDecky();}}
+byId('deckyJobCheck').onclick=checkDeckyJob;
 function openFrameyPanel(id,name){
   if(!(deckyState?.plugins||[]).some(p=>p.storeId===id))return;
   activeFrameyId=id;byId('frameyTitle').textContent=name;
@@ -212,5 +240,6 @@ window.addEventListener('message',event=>{if(!activeExtension||event.source!==by
     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();refreshDecky();
+checkDeckyJob();
 setInterval(()=>{if(!document.hidden){refresh();refreshRecord();}},15000);
 </script></body></html>

ui/server.py

@@ -572,7 +572,7 @@ def decky_plugin(body):
     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))
+                     lambda report: frame_decky_store.change(ssh, action, plugin_id, report), progress=True)
 
 
 def framey_method_action(body):