Merge shipped HLTB support into Bluetooth compatibility

Extend Framey shim for HLTB settings panel

docs/decky-frame.md

@@ -44,22 +44,23 @@ For a new plugin, follow the [Frame plugin and extension guide](frame-plugin-aut
 
 ### Which of these plugins can open a Framey panel?
 
-The separate Framey panel accepts a Frame Control store install only when its
-`plugin.json` declares `api_version: 2` and it has `dist/index.js`. A backend
-load does not bypass this frontend check. We downloaded the 11 versions above
+The separate Framey panel accepts a Frame Control store install when its
+`plugin.json` declares API v1 or v2 and it has a modern Decky frontend bundle
+in `dist/index.js`. A backend load does not bypass this frontend check. We downloaded the 11 versions above
 again on 25 October 2026 and matched every ZIP's SHA-256 to the official store
 catalogue. All 11 had a frontend bundle, but their manifests differed:
 
 | Manifest in the checked archive | Plugins | Framey panel result |
 | --- | --- | --- |
 | API v2 | ProtonDB Badges 1.3.4 | Eligible; settings rendered in local Chromium. No worn VR check. |
-| API v1 | Bluetooth 3.1.1, HLTB for Deck 2.0.12, SteamGridDB 1.8.1, Storage Cleaner 1.4.0, Wine Cellar 0.2.1, MagicPods 2.0.21 | Framey refuses these frontends. Wine Cellar and MagicPods also fail the ARM64 archive check. |
+| API v1 | Bluetooth 3.1.1, HLTB for Deck 2.0.12, SteamGridDB 1.8.1, Storage Cleaner 1.4.0, Wine Cellar 0.2.1, MagicPods 2.0.21 | Storage Cleaner rendered its empty-data panel in local Chromium. HLTB started and built a settings view in a local host test; its Steam game page patches have no target. Other panels remain untested. Wine Cellar and MagicPods fail the ARM64 archive check. None has a worn VR result. |
 | No `api_version` field | CSS Loader 2.1.3, Animation Changer 1.3.2, Audio Loader 1.6.1, PowerTools 2.0.3 | Framey refuses these frontends. Audio Loader and PowerTools also request root. |
 
 The [archive audit record](evidence/framey-official-archive-audit-2026-10-25.json)
 has each store ID, exact version, SHA-256, manifest field, and bundle check.
-This is a static PC inspection. It does not show that any plugin is visible or
-usable in the headset. The earlier real Frame backend checks in the table above
+The archive audit itself is static PC inspection. Later local host and fake
+Frame tests cover the Storage Cleaner and HLTB cases noted above; none shows
+that a plugin is visible or usable in the headset. The earlier real Frame backend checks in the table above
 remain the only device evidence for these versions. A new store version needs a
 new check because its manifest and binaries can change.
 
@@ -83,7 +84,7 @@ API v2 pages and API v1 bundles that use Decky's modern frontend initializer,
 with settings, local routes, and panel toasts where supported.
 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).
+[current compatibility table](frame-plugin-author.md#framey-decky-api-compatibility).
 
 ## What was checked on the real headset
 

docs/evidence/framey-bluetooth-fixture-2026-10-25.md

@@ -0,0 +1,16 @@
+# Bluetooth 3.1.1 compatibility fixture, 25 October 2026
+
+The unmodified official Decky store archive for Bluetooth 3.1.1 (store ID 18,
+SHA-256 `f07f7b74f31da15b5e3a8234a3f00faa01365b56b8f496aca7bb79120be7b8a5`)
+passes Frame Control's archive rules. The fake Frame e2e harness installed it
+through the store API, verified the managed receipt and frontend bytes, then
+removed it. An earlier real Frame check recorded the backend's `Bluetooth
+plugin loaded` line while SteamVR was in standby.
+
+In a local Node host test, its official frontend starts and builds an initial
+panel tree. Framey supplies empty Steam token maps and readable English
+fallbacks for the three Bluetooth labels that lack plugin-owned fallbacks.
+The test leaves React effects and click
+handlers inert and sends no backend calls. It does not inspect paired devices,
+change Bluetooth state, exercise a controller, or prove the panel is visible in
+VR. No worn-headset check has passed for this plugin.

docs/frame-plugin-author.md

@@ -68,6 +68,7 @@ none of these frontend controls has passed a worn-headset check yet.
 | `localStorage` | Synchronous, per-plugin cache backed by the Frame Control panel origin. Up to 64 keys, 64 KiB per value and 128 KiB total; `clear()` removes only this plugin's cache. Falls back to memory if panel storage is denied. | Parent/iframe round-trip and reopen in the local host test; real headset persistence remains unverified. |
 | `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 |
+| `findModuleChild`, `Navigation.CloseSideMenus` | Steam module lookup returns `null`; close returns to this plugin's main panel | Pinned HLTB for Deck 2.0.12 entry point and shallow settings view in local host test. Steam library patch and live HLTB search remain unverified. |
 | 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 |
 
@@ -85,3 +86,9 @@ The Framey `localStorage` bridge is for disposable frontend caches, including
 the cache read attempted by Steam Status 1.2.3. It does not expose another
 plugin's cache or the Frame Control UI key. A real Steam Status panel reopen
 and a worn-headset settings check are still needed.
+
+HLTB for Deck 2.0.12 demonstrates the limit of the panel shim: its official
+bundle can start and produce a settings view with Framey's Steam module lookup
+stub, but its game page and context menu patches have no Steam target in the
+isolated panel. The tests do not call its HLTB network search or Python backend.
+Do not claim game length badges work in VR from this result.

tests/fixtures/framey-official/README.md

@@ -10,11 +10,20 @@ from a local fixture so CI does not depend on the store being online.
 | `14.zip` | ProtonDB Badges | 1.3.4 | `90a3453ac02709cad64096e7539fd8141fa56f99ae3441fc24a4990dc9684358` |
 | `123.zip` | Steam Status | 1.2.3 | `9053308e04a74f44745b45b9f4f50af3673348d367e7b14bacc5677de707ac4e` |
 | `50.zip` | Storage Cleaner | 1.4.0 | `1afa1a6f129c5d419de0e0bf0f6db8d8e50385a5659179346e996031ea372591` |
+| `18.zip` | Bluetooth | 3.1.1 | `f07f7b74f31da15b5e3a8234a3f00faa01365b56b8f496aca7bb79120be7b8a5` |
+| `26.zip` | HLTB for Deck | 2.0.12 | `bd54a23b0b8ec0798aa590e5be236522a593529d7680e77fb888e2971bf3d558` |
 
 The matching source projects are
 [ProtonDB Badges](https://github.com/bschelst/protondb-decky),
-[Steam Status](https://github.com/bschelst/steamstatus-decky), and
-[Storage Cleaner](https://github.com/mcarlucci/decky-storage-cleaner).
+[Steam Status](https://github.com/bschelst/steamstatus-decky),
+[Storage Cleaner](https://github.com/mcarlucci/decky-storage-cleaner),
+[Bluetooth](https://github.com/Outpox/Bluetooth), and
+[HLTB for Deck](https://github.com/morwy/hltb-for-deck).
 The test verifies the ZIP digest, archive policy, API v1/v2 manifest, installed
-frontend bytes, managed store receipt, and removal. It does **not** run their
-Python backends or prove their JavaScript panels render in the VR shell.
+frontend bytes, managed store receipt, and removal. Separate local host tests
+start Bluetooth's frontend and its initial panel without running effects or
+actions, and start HLTB's frontend and shallow settings view with a stub Steam
+module lookup. They do **not** run plugin Python backends, Bluetooth actions,
+HLTB searches, or prove JavaScript panels render in the VR shell. The
+Bluetooth result and limits are in
+[the fixture evidence](../../../docs/evidence/framey-bluetooth-fixture-2026-10-25.md).

tests/framey_official.py

@@ -10,6 +10,10 @@ PLUGINS = (
      'folder': 'steamstatus-decky', 'sha256': '9053308e04a74f44745b45b9f4f50af3673348d367e7b14bacc5677de707ac4e'},
     {'id': 50, 'name': 'Storage Cleaner', 'version': '1.4.0', 'api_version': 1,
      'folder': 'decky-storage-cleaner', 'sha256': '1afa1a6f129c5d419de0e0bf0f6db8d8e50385a5659179346e996031ea372591'},
+    {'id': 18, 'name': 'Bluetooth', 'version': '3.1.1', 'api_version': 1,
+     'folder': 'Bluetooth', 'sha256': 'f07f7b74f31da15b5e3a8234a3f00faa01365b56b8f496aca7bb79120be7b8a5'},
+    {'id': 26, 'name': 'HLTB for Deck', 'version': '2.0.12', 'api_version': 1,
+     'folder': 'hltb-for-deck', 'sha256': 'bd54a23b0b8ec0798aa590e5be236522a593529d7680e77fb888e2971bf3d558'},
 )
 
 

tests/page/framey_actions.mjs

@@ -107,4 +107,7 @@ 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);
+assert.equal(window.DFL.findModuleChild(()=>true),null);
+window.DFL.Navigation.CloseSideMenus();
+assert.equal(nodes(window.__surface({plugin}),LocalRoute).length,0);
 undo();assert.equal(window.DFL.Navigation.Navigate('/plugin/details'),false);

tests/page/framey_bluetooth.mjs

@@ -0,0 +1,43 @@
+// Start the unmodified official Bluetooth frontend and build its initial UI.
+// Effects and click handlers are inert: no Bluetooth/backend operation runs.
+import assert from 'node:assert/strict';
+import {readFileSync} from 'node:fs';
+import vm from 'node:vm';
+
+const bundle=readFileSync(process.argv[2],'utf8');
+const official=bundle.replace(/export \{ index as default \};\s*\/\/# sourceMappingURL=index.js.map\s*$/,
+  'window.__official = index;');
+assert.notEqual(official,bundle);
+const source=readFileSync(new URL('../../ui/framey-host.js',import.meta.url),'utf8');
+const host=source.replace(/\n  start\(\);\n\}\)\(\);\s*$/, '\n})();');
+assert.notEqual(host,source);
+const react=new Proxy({Fragment:'fragment',Component:class {},
+  createElement:(type,props,...children)=>({type,props,children}),
+  createContext:value=>({Provider:()=>{},Consumer:()=>{},_currentValue:value}),
+  useState:value=>[value,()=>{}],useReducer:(_,value)=>[value,()=>{}],
+  useEffect(){},useRef:value=>({current:value}),useMemo:fn=>fn(),
+  useCallback:fn=>fn,forwardRef:fn=>fn,memo:fn=>fn},
+  {get:(target,key)=>target[key]??(()=>{})});
+const window={React:react,ReactDOM:{createRoot:()=>({render(){}})},location:{hash:''}};
+const elements=new Map();
+const messages=[];
+const context=vm.createContext({window,navigator:{language:'en'},parent:{postMessage:message=>messages.push(message)},
+  document:{getElementById:id=>{if(!elements.has(id))elements.set(id,{});return elements.get(id);}},
+  addEventListener(){},setTimeout:()=>1,clearTimeout(){},console,URL,Blob});
+vm.runInContext(host,context);
+context.DFL=window.DFL;
+context.SP_REACT=window.SP_REACT;
+context.SP_JSX=window.SP_JSX;
+context.LocalizationManager=window.LocalizationManager;
+assert.equal(window.LocalizationManager.m_mapTokens.size,0);
+assert.equal(window.LocalizationManager.m_mapFallbackTokens.get('Settings_Bluetooth_Devices'),'Devices');
+vm.runInContext(official,context,{timeout:2000});
+const plugin=window.__official();
+assert.equal(plugin.content?.type?.name,'Content');
+const panel=plugin.content.type();
+assert.equal(panel.type,'div');
+const text=JSON.stringify(panel);
+assert.match(text,/Bluetooth/);
+assert.match(text,/Devices/); // Readable fallback when Steam tokens are absent.
+assert.doesNotMatch(text,/Settings_Bluetooth_Devices/);
+assert.equal(messages.filter(message=>message.type==='framey:call').length,0);

tests/page/framey_hltb.mjs

@@ -0,0 +1,57 @@
+// Execute the pinned official HLTB frontend's entry point with Framey's API.
+// This checks module startup only; it never makes network or backend calls.
+import assert from 'node:assert/strict';
+import {readFileSync} from 'node:fs';
+import {inflateRawSync} from 'node:zlib';
+import vm from 'node:vm';
+
+const host=readFileSync(new URL('../../ui/framey-host.js',import.meta.url),'utf8');
+const hostTest=host.replace(/\n  start\(\);\n\}\)\(\);\s*$/, '\n})();');
+assert.notEqual(hostTest,host);
+const zip=readFileSync(new URL('../fixtures/framey-official/26.zip',import.meta.url));
+const eocd=zip.lastIndexOf(Buffer.from([0x50,0x4b,0x05,0x06]));
+assert.ok(eocd>0);
+let offset=zip.readUInt32LE(eocd+16),bundle;
+for(let i=0;i<zip.readUInt16LE(eocd+10);i++){
+  assert.equal(zip.readUInt32LE(offset),0x02014b50);
+  const nameLength=zip.readUInt16LE(offset+28),extraLength=zip.readUInt16LE(offset+30);
+  const commentLength=zip.readUInt16LE(offset+32);
+  const name=zip.subarray(offset+46,offset+46+nameLength).toString();
+  if(name==='hltb-for-deck/dist/index.js'){
+    const local=zip.readUInt32LE(offset+42);
+    assert.equal(zip.readUInt32LE(local),0x04034b50);
+    const start=local+30+zip.readUInt16LE(local+26)+zip.readUInt16LE(local+28);
+    const compressed=zip.subarray(start,start+zip.readUInt32LE(offset+20));
+    bundle=(zip.readUInt16LE(offset+10)===8?inflateRawSync(compressed):compressed).toString();
+  }
+  offset+=46+nameLength+extraLength+commentLength;
+}
+assert.ok(bundle);
+const official=bundle.replace(/export \{ index as default \};\s*\/\/# sourceMappingURL=index.js.map\s*$/,
+  'window.__official = index;');
+assert.notEqual(official,bundle);
+const react=new Proxy({Fragment:'fragment',Component:class {},
+  createElement:(type,props,...children)=>({type,props,children}),
+  createContext:value=>({Provider:()=>{},Consumer:()=>{},_currentValue:value}),
+  forwardRef:fn=>fn,memo:fn=>fn,useState:value=>[value,()=>{}],
+  useContext:ctx=>ctx?._currentValue,useMemo:fn=>fn(),useCallback:fn=>fn,
+  useRef:value=>({current:value}),useEffect(){}},
+  {get:(target,key)=>target[key]??(()=>{})});
+const window={React:react,ReactDOM:{createRoot:()=>({render(){}})},location:{hash:''}};
+const elements=new Map();
+const context=vm.createContext({window,navigator:{language:'en'},parent:{postMessage(){}},
+  document:{getElementById:id=>{if(!elements.has(id))elements.set(id,{});return elements.get(id);}},
+  addEventListener(){},setTimeout:()=>1,clearTimeout(){},console,URL,Blob});
+vm.runInContext(hostTest,context);
+context.DFL=window.DFL;
+context.SP_REACT=window.SP_REACT;
+context.SP_JSX=window.SP_JSX;
+vm.runInContext(official,context,{timeout:2000});
+const plugin=window.__official();
+assert.equal(typeof window.DFL.findModuleChild,'function');
+assert.equal(window.DFL.findModuleChild(()=>{}),null); // Steam has no matching module in the VR panel.
+assert.equal(plugin.content?.type?.name,'QuickAccessView');
+const panel=plugin.content.type();
+assert.ok(panel?.type); // Read-only settings render with empty local data.
+assert.equal(typeof plugin.onDismount,'function');
+plugin.onDismount();

tests/test_framey_official.py

@@ -5,6 +5,8 @@ import hashlib
 import json
 from pathlib import Path
 import re
+import shutil
+import subprocess
 import sys
 import tempfile
 import unittest
@@ -19,6 +21,23 @@ from framey_official import PLUGINS, archive
 
 
 class OfficialBundles(unittest.TestCase):
+    @unittest.skipUnless(shutil.which('node'), 'Node is needed for the official frontend check')
+    def test_bluetooth_initial_panel_uses_safe_token_fallback(self):
+        with zipfile.ZipFile(io.BytesIO(archive(next(p for p in PLUGINS if p['id'] == 18)))) as bundle:
+            with tempfile.TemporaryDirectory() as folder:
+                frontend = Path(folder) / 'index.js'
+                frontend.write_bytes(bundle.read('Bluetooth/dist/index.js'))
+                script = Path(__file__).parent / 'page/framey_bluetooth.mjs'
+                result = subprocess.run(['node', str(script), str(frontend)],
+                                        capture_output=True, text=True, timeout=10)
+        self.assertEqual(result.returncode, 0, result.stderr)
+
+    @unittest.skipUnless(shutil.which('node'), 'Node is needed for the official frontend check')
+    def test_hltb_frontend_starts_with_framey_module_stub(self):
+        script = Path(__file__).parent / 'page/framey_hltb.mjs'
+        result = subprocess.run(['node', str(script)], capture_output=True, text=True, timeout=10)
+        self.assertEqual(result.returncode, 0, result.stderr)
+
     def test_pinned_store_archives_install_and_pack_into_framey_panel(self):
         with tempfile.TemporaryDirectory() as root:
             plugins = Path(root)

tests/test_framey_panel.py

@@ -1,4 +1,4 @@
-"""Framey hosts only store-owned API v2 frontends and scopes backend calls."""
+"""Framey hosts store-owned modern Decky frontends and scopes backend calls."""
 import sandbox  # noqa: F401
 import gzip
 import http.client

ui/framey-host.js

@@ -11,7 +11,14 @@
       : R.createElement(type, elementProps);
   };
   window.SP_JSX = {jsx, jsxs:jsx, Fragment:R.Fragment};
-  window.LocalizationManager = {m_rgLocalesToUse:[navigator.language || 'en']};
+  // Steam normally fills these token maps. Official plugins can safely use
+  // their own fallback strings when the isolated panel has no Steam tokens.
+  window.LocalizationManager = {m_rgLocalesToUse:[navigator.language || 'en'],
+    m_mapTokens:new Map(), m_mapFallbackTokens:new Map([
+      ['Settings_Bluetooth_Connected','Connected'],
+      ['Settings_Bluetooth_NotConnected','Not connected'],
+      ['Settings_Bluetooth_Devices','Devices'],
+    ])};
   const root = document.getElementById('framey-root');
   const error = document.getElementById('framey-error');
   const toastRoot = document.getElementById('framey-toasts');
@@ -155,13 +162,13 @@
     Focusable: passthrough('div'), ScrollPanel: passthrough('div'), ScrollPanelGroup: passthrough('div'),
     DialogButton: passthrough('button'), DialogButtonPrimary: passthrough('button'), ConfirmModal,
     staticClasses: {Title:'framey-title'},
-    Navigation: {Navigate:navigate, NavigateBack:()=>navigate(null),
+    Navigation: {Navigate:navigate, NavigateBack:()=>navigate(null), CloseSideMenus:()=>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.
     afterPatch: () => () => {}, createReactTreePatcher: () => () => {},
-    findInReactTree: () => null, findModuleExport: () => null,
+    findInReactTree: () => null, findModuleExport: () => null, findModuleChild: () => null,
     appDetailsClasses: {}, appDetailsHeaderClasses: {},
     useParams: () => ({}),
   };