Clarify Framey progress text placement

Make DeckySpy system monitoring work on ARM64 Frame

docs/frame-plugin-author.md

@@ -64,7 +64,8 @@ none of these frontend controls has passed a worn-headset check yet.
 | `PanelSection`, rows, buttons, toggles, dropdowns | Local touch-sized controls; disabled controls stay inert during a backend call | Local browser and host unit test |
 | `TextField`, `SliderField`, grouped `Dropdown` options | Native text, range and select controls in the panel; disabled state, numeric slider callback and basic input types | Host unit test; worn VR use unverified |
 | Scrollable panel content | Visible Scroll plugin up/down buttons move the last region reached by a trusted pointer, or the document if that region disappears. Hold either button to repeat; keyboard activation still moves one step. Plugins may use ordinary CSS overflow containers. | Parent/iframe message tests and a real Frame synthetic OpenVR pointer hold; physical controller scroll and hold remain unverified |
-| `Tabs`, `SidebarNavigation`, spinners, dialog/menu wrappers, progress bars | Local tab navigation and ordinary HTML controls; no Steam navigation or controller focus tree | Host tests and catalog frontend smoke checks in local Chromium |
+| `Tabs`, `SidebarNavigation`, spinners, dialog/menu wrappers | Local tab navigation and ordinary HTML controls; no Steam navigation or controller focus tree | Host tests and catalog frontend smoke checks in local Chromium |
+| `ProgressBar`, `ProgressBarItem`, `ProgressBarWithInfo` | Native progress control; `indeterminate` omits its value so it animates as unfinished, and `sOperationText` appears with the bar. Estimated completion time is not shown. | Host contract tests; official plugin progress behavior in worn VR remains unverified. |
 | `SteamUIStore` / `DFL.Router.RunningApps`, `MainRunningApp` | Bounded detached Steam CEF reads while the panel is open; refresh about every two seconds; no MobX observation. Failed reads clear stale context. | Locked real Frame empty-list reads; nonempty local Chromium fixtures. Real running-game selection unverified. |
 | `GameSessions.RegisterForAppLifetimeNotifications` | Actual Steam callbacks, bounded queue and disposable `.unregister()` handle; no events inferred from snapshot changes; lease cleanup after lost panels | Real Frame registration/poll/close; launch/exit, retry, expiry and duplicate tests use explicit fixtures. Real game transitions unverified. |
 | Other `SteamClient` subscriptions | Explicit inert registration methods return disposable handles; no fabricated power/input/game-action events. Mutating Steam/power methods are unavailable. | Host contract tests; safe fallbacks only |

examples/framey-settings/README.md

@@ -14,6 +14,12 @@ action calls the backend, so it reads the persisted setting rather than a
 browser cache. A missing, damaged, or old non-boolean value reads as the
 caller's default;
 the next save atomically replaces the sample's settings file.
+The current file is `{"schema": 1, "enabled": true|false}`. An unversioned
+`{"enabled": true|false}` file from the first sample release still reads, and
+the next save writes schema 1. A file with another explicit schema returns a
+visible read or save error and remains untouched, so downgrading the sample
+cannot erase settings written by a newer version. Add a deliberate migration
+for each future schema instead of changing this guard silently.
 The panel also guards its own read and write calls synchronously. If two
 controller events arrive before React redraws a disabled control, the second
 event is ignored; after the request settles, a new change can be saved.

examples/framey-settings/main.py

@@ -5,26 +5,41 @@ from pathlib import Path
 import tempfile
 import decky
 
+SETTINGS_SCHEMA = 1
+
 
 def settings_file():
     # Decky provides this per-plugin path through its official Python module.
     return Path(decky.DECKY_PLUGIN_SETTINGS_DIR) / 'settings.json'
 
 
+def read_settings():
+    try:
+        stored = json.loads(settings_file().read_text(encoding='utf-8'))
+    except (FileNotFoundError, json.JSONDecodeError, UnicodeDecodeError):
+        return {}
+    if not isinstance(stored, dict):
+        return {}
+    # The first sample release wrote {"enabled": bool} without a schema.
+    # Keep reading it; the next save writes the current format.
+    schema = stored.get('schema', SETTINGS_SCHEMA)
+    if type(schema) is not int or schema != SETTINGS_SCHEMA:
+        raise ValueError('Settings were written by an unsupported sample version')
+    return stored
+
+
 class Plugin:
     async def get_setting(self, key: str, default=False):
         if key != 'enabled':
             raise ValueError('Unknown setting')
-        try:
-            stored = json.loads(settings_file().read_text(encoding='utf-8'))
-        except (FileNotFoundError, json.JSONDecodeError, UnicodeDecodeError):
-            return default
-        value = stored.get(key) if isinstance(stored, dict) else None
+        value = read_settings().get(key)
         return value if type(value) is bool else default
 
     async def set_setting(self, key: str, value: bool):
         if key != 'enabled' or type(value) is not bool:
             raise ValueError('Expected an enabled boolean')
+        # Refuse to erase settings from a newer plugin after a downgrade.
+        read_settings()
         target = settings_file()
         target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
         temporary = None
@@ -32,7 +47,7 @@ class Plugin:
             with tempfile.NamedTemporaryFile('w', encoding='utf-8', dir=target.parent,
                                              prefix='.settings-', delete=False) as output:
                 temporary = Path(output.name)
-                json.dump({'enabled': value}, output)
+                json.dump({'schema': SETTINGS_SCHEMA, 'enabled': value}, output)
                 output.write('\n')
             temporary.chmod(0o600)
             os.replace(temporary, target)

tests/page/framey_actions.mjs

@@ -253,6 +253,14 @@ nodes(tabs,'button')[2].props.onClick();
 assert.deepEqual(tabChanges,['one']);
 assert.equal(window.DFL.Spinner({}).props.role,'status');
 assert.equal(window.DFL.ProgressBar({nProgress:120}).props.value,100);
+assert.equal(window.DFL.ProgressBar({nProgress:40,indeterminate:true}).props.value,undefined,
+  'an indeterminate progress element must omit its value');
+assert.equal(window.DFL.ProgressBarItem({nProgress:35}).props.value,35);
+const progressInfo=window.DFL.ProgressBarWithInfo({indeterminate:true,
+  sOperationText:'Downloading plugin'});
+assert.equal(nodes(progressInfo,'progress')[0].props.value,undefined);
+assert.equal(nodes(progressInfo,'small')[0].props.role,'status');
+assert.equal(nodes(progressInfo,'small')[0].children[0],'Downloading plugin');
 assert.equal(window.DFL.joinClassNames('one',null,'two'),'one two');
 let eventCount=0;
 const unsubscribe=window.SteamClient.GameSessions.RegisterForAppLifetimeNotifications(()=>eventCount++);

tests/test_framey_sample.py

@@ -1,6 +1,7 @@
 """The author example stores settings as a normal Decky user plugin."""
 import asyncio
 import importlib.util
+import json
 from pathlib import Path
 import subprocess
 import sys
@@ -36,7 +37,8 @@ class SamplePlugin(unittest.TestCase):
             self.assertTrue(asyncio.run(first.set_setting('enabled', True)))
             second = backend(folder)
             self.assertTrue(asyncio.run(second.get_setting('enabled', False)))
-            self.assertTrue((Path(folder) / 'settings.json').is_file())
+            self.assertEqual(json.loads((Path(folder) / 'settings.json').read_text()),
+                             {'schema': 1, 'enabled': True})
 
     def test_backend_rejects_unknown_keys_and_non_boolean_values(self):
         with tempfile.TemporaryDirectory() as folder:
@@ -57,6 +59,43 @@ class SamplePlugin(unittest.TestCase):
             self.assertTrue(asyncio.run(plugin.set_setting('enabled', True)))
             self.assertTrue(asyncio.run(backend(folder).get_setting('enabled', False)))
 
+    def test_legacy_boolean_survives_restart_and_migrates_on_save(self):
+        with tempfile.TemporaryDirectory() as folder:
+            path = Path(folder) / 'settings.json'
+            path.write_text('{"enabled": true}\n')
+            self.assertTrue(asyncio.run(backend(folder).get_setting('enabled', False)))
+            self.assertEqual(json.loads(path.read_text()), {'enabled': True},
+                             'Reading must not rewrite a user setting')
+            self.assertTrue(asyncio.run(backend(folder).set_setting('enabled', False)))
+            self.assertEqual(json.loads(path.read_text()), {'schema': 1, 'enabled': False})
+            self.assertFalse(asyncio.run(backend(folder).get_setting('enabled', True)))
+
+    def test_newer_schema_is_preserved_on_read_and_save(self):
+        with tempfile.TemporaryDirectory() as folder:
+            path = Path(folder) / 'settings.json'
+            original = '{"schema": 2, "enabled": true, "future": "keep"}\n'
+            path.write_text(original)
+            plugin = backend(folder)
+            with self.assertRaisesRegex(ValueError, 'unsupported sample version'):
+                asyncio.run(plugin.get_setting('enabled', False))
+            with self.assertRaisesRegex(ValueError, 'unsupported sample version'):
+                asyncio.run(plugin.set_setting('enabled', False))
+            self.assertEqual(path.read_text(), original)
+            self.assertEqual(list(Path(folder).glob('.settings-*')), [])
+
+    def test_failed_atomic_replace_keeps_previous_setting(self):
+        with tempfile.TemporaryDirectory() as folder:
+            path = Path(folder) / 'settings.json'
+            plugin = backend(folder)
+            self.assertTrue(asyncio.run(plugin.set_setting('enabled', True)))
+            previous = path.read_bytes()
+            with patch('os.replace', side_effect=OSError('storage unavailable')):
+                with self.assertRaisesRegex(OSError, 'storage unavailable'):
+                    asyncio.run(plugin.set_setting('enabled', False))
+            self.assertEqual(path.read_bytes(), previous)
+            self.assertEqual(list(Path(folder).glob('.settings-*')), [])
+            self.assertTrue(asyncio.run(backend(folder).get_setting('enabled', False)))
+
 
 if __name__ == '__main__':
     unittest.main()

ui/framey-host.js

@@ -278,8 +278,10 @@
     title && R.createElement('h2', null, title), R.createElement(Tabs, {
       tabs:pages.filter(page=>page.visible!==false).map((page,index)=>({
         id:page.route || String(index), title:page.title, content:page.content}))}));
-  const ProgressBar = ({nProgress=0, value, max=100}) => R.createElement('progress', {
-    value:Math.max(0,Math.min(max,Number(value ?? nProgress)||0)), max});
+  const ProgressBar = ({nProgress=0, value, max=100, indeterminate=false}) => R.createElement('progress', {
+    value:indeterminate ? undefined : Math.max(0,Math.min(max,Number(value ?? nProgress)||0)), max});
+  const ProgressBarWithInfo = ({sOperationText, ...props}) => R.createElement('div', null,
+    ProgressBar(props), sOperationText == null ? null : R.createElement('small', {role:'status'}, sOperationText));
   const MenuItem = ({children, disabled, bDisabled, onClick, onSelected}) =>
     R.createElement('button', {type:'button',disabled:!!(disabled || bDisabled),
       onClick:event=>{if(!disabled && !bDisabled)(onClick || onSelected)?.(event);}}, children);
@@ -484,7 +486,7 @@
     DialogControlsSectionHeader:passthrough('h3'), ModalRoot:passthrough('section'),
     ModalPosition:passthrough('div'),
     Menu:passthrough('div'), MenuGroup:passthrough('section'), MenuItem,
-    ProgressBar, ProgressBarWithInfo:ProgressBar,
+    ProgressBar, ProgressBarItem:ProgressBar, ProgressBarWithInfo,
     gamepadDialogClasses:{}, quickAccessMenuClasses:{}, gamepadTabbedPageClasses:{},
     gamepadSliderClasses:{}, gamepadContextMenuClasses:{}, scrollPanelClasses:{},
     quickAccessControlsClasses:{}, mainMenuAppRunningClasses:{}, libraryAssetImageClasses:{},