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

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

docs/framey-loader.md

@@ -83,6 +83,15 @@ 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.
+
 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,29 @@
+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)]};
+const window={React,ReactDOM:{createRoot:()=>({render(){}})},addEventListener(){}};
+const context=vm.createContext({window,document:{getElementById:()=>({})},navigator:{language:'en'},
+  parent:{postMessage(){}},addEventListener(){},setTimeout(){},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);

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)

ui/framey-host.js

@@ -72,6 +72,36 @@
     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 [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),
+      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, 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),
@@ -95,8 +125,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,7 +59,7 @@ 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>
 <script id="framey-bundle" type="application/json">''' + encoded + '''</script>