2 Commits

Include renames

Author	SHA1	Message	Date
topkoa	254e26bb3a	feat(panes): mirrorGlobal, manifest-declared panes, and the plugin docs ... Three things a plugin needs before it can actually use panes. ## mirrorGlobal — the camera-director problem The 3D highways read their free camera from a plain global, `window.__h3dCamCtl` (highway_3d/FREECAM_BRIDGE.md), once per frame in _resolveFreeCam(). A camera panel in the main window just writes that object and the camera moves. A panel in a POP-OUT window cannot: window.__h3dCamCtl there is a different object in a different realm, and writing it moves nothing. So a pane declares one field — `mirrorGlobal: '__h3dCamCtl'` — and pane-mirror.js (main realm, where the renderers live) copies that pane's state onto the global whenever it changes. highway_3d, keys_highway_3d and drum_highway_3d are NOT modified and do not know panes exist. The rule that makes it work: MUTATE THE OBJECT, NEVER REPLACE IT. A renderer may be holding the reference, and swapping in a new object would leave it reading an orphan. Keys the pane doesn't set are left alone rather than deleted — the global may carry a renderer's own bookkeeping. Closing the pane deliberately leaves the global as-is: closing the camera panel should not snap the camera back to a default, which is exactly what happens today (nobody clears __h3dCamCtl). ## Manifest-declared panes "panes": [{ "id": "camera_director", "title": "Camera Director", "script": "panes/camera.js", "mirrorGlobal": "__h3dCamCtl" }] Declaring a pane beats calling panes.register() from screen.js because it becomes openable FROM THE RAIL OR THE TRAY WITHOUT THE PLUGIN'S SCREEN EVER HAVING BEEN VISITED — core registers a stub from the manifest and fetches the script only when the user opens it. A pane you can only reach by first navigating to the screen it was meant to replace is not much of a pane. The script sets `window.feedBackPane_<id> = { mount, unmount }`, mirroring the existing window.feedBackViz_<id> convention, and the SAME file is what a pop-out window loads in its own realm. `script` is validated as a relpath under the plugin's src/ and served through the sandboxed /api/plugins/<id>/src/ route — the containment rule `styles` already has for assets/. Traversal, absolute paths, drive letters, backslashes and non-.js are rejected; a bad entry is dropped with a warning rather than failing the whole plugin, because one malformed pane should not cost the user a working plugin. Note the projection is written TWICE — _nav_entry() and the /api/plugins route re-project independently — so panes had to be added to both, plus the pending branch (a pane can be opened while its plugin is still installing deps; the script is fetched on open, not at discovery). ## docs/plugin-panes.md The contract, and the one rule it all hangs on: mount(root, ctx) runs in a realm that may not have the app in it. Everything comes through ctx, or the pane works docked and silently dies popped out. Verified: manifest validation rejects ../.., C:\, non-.js, dupes and missing fields while passing a good entry; /api/plugins projects panes[] for all 20 plugins. mirrorGlobal mutates the global IN PLACE — a reference held the way _resolveFreeCam holds it sees the change, and a renderer's own field on that object survives — both for a local write and for a write arriving over the channel from a pop-out realm. pytest: 2401 passed, 8 failed — all 8 reproduce on a clean main (including the one in tests/test_plugins.py) and are unrelated. Signed-off-by: topkoa <topkoa@gmail.com>	2026-07-12 17:38:05 -04:00
topkoa	fefb9051a4	feat(panes): pop-out windows — the pane realm, hub, and remote transport ... A pane can now leave the main window entirely. Same `mount(root, ctx)`, same file, different JS realm — which is what the ctx-only contract in the previous commit was for. ## A purpose-built document, not the app shell with a flag on it `GET /pane` serves static/panes/pane.html: the bridge, the runtime, and the pane's own script. No highway, no library, no v3 shell, no <audio>, no Tailwind. The splitscreen follower takes the other road — it reloads the whole app at `/?ssFollower=1` and hides what it doesn't want — and pays for it with an anti-flash block that must run before any script parses (index.html), bail-outs in app.js and shell.js, and ~40 lines of CSS hiding core elements by id. It loads the entire app to throw it away. A pane window has nothing to throw away, so it boots in milliseconds and there is nothing to flash. The cost is that `window.feedBack` in a pane realm is a deliberate, documented SUBSET. The runtime installs exactly what a pane is promised — `panes.register`, and the no-op chip/dock calls a shared script may make at load — so a pane reaching for something it was never given fails loudly at authoring time instead of subtly at runtime. ## The channel BroadcastChannel('feedback-panes'), same origin. This works only because Electron's setWindowOpenHandler returns `action: 'allow'` for same-origin URLs: `deny` would push the window to the system browser, a different Chromium instance, where BroadcastChannel cannot reach it and the pane would silently never sync. That flag is load-bearing. hello -> snapshot resync-on-open, always. The snapshot is the only way the pane realm learns anything. state main is authoritative. A pane's write is a REQUEST; main applies it and echoes to every realm, so a losing write self-corrects instead of splitting brain. rpc / rpc:reply ctx.call() -> the capability bus, with a 10s deadline. Without one, a main window that died mid-call leaves the pane's promise pending forever. event allowlisted bus events, JSON-safe. A CustomEvent carrying a DOM node (highway:canvas-replaced does) would throw on postMessage and take the channel down for everyone, so detail is round-tripped through JSON. stream one coalesced message per pane per frame, OVERWRITING anything not yet flushed. Queueing would build a backlog: Chromium throttles a backgrounded window, and the main window is exactly what's backgrounded while the user looks at the pane. sub / unsub refcounts the main-realm sampler. bye both directions. ## The follower clock The pane extrapolates between broadcasts: anchor + observedRate * elapsed, capped at 2s. observedRate is learned from the broadcasts themselves (dt/dwall) so it tracks the speed slider without being told about it, and seeks/pauses are excluded from the fit — a jump is not a tempo. Capping it means a dead main window decays into a frozen clock rather than one that confidently runs away. This is splitscreen's hard-won trick, generalized: panes just call ctx.playhead(). ## Failure modes, all of them - Main window closes -> `bye {main-closed}` and the pane says so plainly, rather than showing a frozen playhead that looks live. The host also closes its windows outright; a pane that cannot be fed should not be on screen. - Pane window X'd or crashed -> a `closed` poll reaps it (a crashed renderer never sends `bye`), the pane closes, and the chip's dialog comes back. Without this the user's dialog stays hidden with no way back. - Popup blocked -> a toast, and we bail BEFORE the manager records anything, so the caller's dialog stays exactly where it was. - Nobody answers `hello` in 5s -> the window says so instead of spinning. - A pane with no `script` is a closure in this realm and cannot honestly cross a window boundary. The window host declines it (canHost) and the router falls back to the dock. - A browser blocks window.open() outside a user gesture, so a popped-out pane cannot be auto-restored on page load — it would only ever produce a "blocked" toast. Such a pane comes back in the DOCK, and the chip pops it out again on the next click. (autoRestore: false. The desktop host will set it true.) Hosts may now declare `remote: true`, meaning the pane's mount() runs in another realm: the manager then owns only the authoritative state store and never calls mount() itself. That is the seam the Electron BrowserWindow + tray host drops into next, with no change here. Verified: popped Now Playing and Mixer into real windows. The pane realm has no window.highway, no capability bus and no <audio>, yet the Mixer renders its faders via ctx.call('audio-mix','list-faders') across the channel — and dragging that fader IN THE PANE WINDOW moved the main window's song volume to 55 and persisted it. Closing the pane window un-hid the mixer dialog, removed the stub and restored the chip, while the other pane window stayed open. Signed-off-by: topkoa <topkoa@gmail.com>	2026-07-12 17:03:21 -04:00