@3sln/trove 0.0.7 → 0.0.9

package/packages/web/src/ui/compositions/workbench.js

@@ -1,17 +1,22 @@
-// Root composition. Assembles the `ui` helper (stable for the app's life),
-// zips every reactive slice the shell needs into one snapshot, and renders the
-// full workbench from it. Components stay pure — they receive (state, ui) and
-// either call ui.exec(commandId) or ui.go(action). This is the only module that
-// knows about every service at once.
+// Root composition. Assembles the `ui` helper (stable for the app's life), zips every
+// query the shell reads into one snapshot, and renders the workbench from it.
+//
+// Components are pure: they receive (state, ui) and dispatch. This module knows about
+// every QUERY at once — which is a different thing from what it used to know, when it
+// held the bag of services every component reached through.
 
-import { dd, cell, derive, constant } from '../../runtime.js';
-import { NavigateAction } from '../../bl/actions.js';
+import { dd, derive, constant, watch } from '../../runtime.js';
+import { region } from '../region.js';
+import { watchQuery } from '../../bl/watchQuery.js';
+import * as q from '../../bl/queries.js';
+import { CloseSearchModalAction, ExecCommandAction, NavigateAction } from '../../bl/actions.js';
 import activityBar from '../components/activityBar.js';
 import statusBar from '../components/statusBar.js';
 import launcher from '../components/launcher.js';
 import settingsView from '../components/settingsView.js';
 import collectionGate from '../components/collectionGate.js';
 import pluginsView from '../components/pluginsView.js';
+import adminView from '../components/adminView.js';
 import editorArea from '../components/editorArea.js';
 import commandPalette from '../components/commandPalette.js';
 import { dialog, contextMenu, toasts, transferTray, pluginPanel } from '../components/overlays.js';
@@ -21,89 +26,192 @@ import { phoneTopBar, phoneBottomBar, phoneSheet } from '../components/phoneChro
 
 const { alias, div } = dd;
 
-export default function workbench({ engine, app, platform, plugins }) {
-  // A counter rather than a timestamp: a cell drops a write of the value it already
-  // holds, and two `rerender()` calls in the same millisecond would have compared equal.
-  const bump = cell(0);
+export default function workbench({ engine, platform }) {
+  // What a component is handed, and it is nearly nothing now.
+  //
+  // `engine` is the thing components talk to: `dispatch` for an action, `query` for a
+  // question. It was removed once for being unreferenced, which was true and backwards —
+  // nothing referenced it precisely BECAUSE `go` and `exec` stood in for it, and `exec`
+  // called the command service directly, so every menu item, keybinding and palette entry
+  // a person triggered was invisible to the engine.
+  //
+  // Both are gone. `go(action)` was `engine.dispatch(action)` with a shorter name, and a
+  // shorter name for the one door is how the door stops being obvious. Call sites say
+  // `ui.engine.dispatch(new SomeAction(...))` now: longer, and it names what happens.
+  //
+  // `platform` is still passed, for four uses that are genuinely imperative: two plugin
+  // iframe mounts, the media URL machinery, and the opener lookup in openers/index.js —
+  // which stays because an opener may resolve to a plugin iframe rather than to a render
+  // function, and mounting one is an effect, not a view.
+  //
+  // Note what is NOT a reason: carrying a function. A query hands over the view renderers
+  // (see the `views` query) because a renderer is pure — it builds a vnode from what it is
+  // given. The rule is about SIDE EFFECTS escaping through a callable, not about callables.
+  //
+  // See docs/tickets/009. `app` used to be here too — the whole bag of services — and is
+  // gone: nothing in `ui/` reads a service directly any more.
   const ui = {
-    engine, app, platform,
-    go: (action) => engine.dispatch(action),
-    exec: (id, ...args) => platform.commands.execute(id, ...args),
-    rerender: () => bump.update((n) => n + 1),
-    uninstallPlugin: (id) => plugins?.uninstall(id),
+    engine, platform,
+    // Rendering a cell is a UI concern, not a platform subsystem to reach through.
+    watch,
   };
 
-  const { watch } = platform.reactive;
   // One derived snapshot of every slice the shell reads. `derive` invalidates when any
   // of them does and recomputes once on the next read, so fifteen changes in a frame
   // still cost one render.
   const combined = derive(
+    // EVERY input is a query. Half of these used to read the service cell directly, which
+    // looked equivalent and was not: a query may PROJECT, and the projection is where
+    // `offline.pinnedIds` and `voice.canListen` come from. Reading the raw cell got the
+    // service's state without them, so a pinned file's menu still offered to pin it and the
+    // microphone button never appeared — silently, because an undefined field just reads as
+    // false. Going through the engine uniformly is what makes "the same slice" mean the
+    // same thing everywhere.
     [
-      platform.workbench.observe(),
-      platform.workbench.observeOverlay(),
-      platform.workbench.observeNav(),
-      app.explorer.observe(),
-      app.search.observe(),
-      app.apiKeys.observe(),
-      app.transfers.observe(),
-      platform.notifications.observe(),
-      platform.context.observe(),
-      platform.settings.observe(),
-      platform.plugins.observe() ?? constant([]),
-      platform.contributions.observeType('statusItem'),
-      app.social.observe(),
-      app.offline.observe(),
-      app.activity.observe(),
-      platform.viewport.observe(),
-      platform.voice.observe(),
-      bump,
+      watchQuery(engine, q.workbench),
+      watchQuery(engine, q.overlay),
+      watchQuery(engine, q.navigation),
+      watchQuery(engine, q.explorer),
+      watchQuery(engine, q.search),
+      watchQuery(engine, q.context),
+      watchQuery(engine, q.settings),
+      watchQuery(engine, q.offline),
+      watchQuery(engine, q.viewport),
+      watchQuery(engine, q.voice),
+      // What the UI is in the middle of doing — see bl/viewState.js.
+      watchQuery(engine, q.viewState),
+      // What the server can do. Its resource hands out a cell that starts null and fills
+      // in, so this is a normal value while the request is in flight rather than turning
+      // the whole snapshot PENDING and blanking the shell.
+      watchQuery(engine, q.capabilities),
+      // Command id -> its shortcut label, for anything that shows one next to an action.
+      watchQuery(engine, q.commandKeys),
+      // What the launcher shows, twice: the home screen and the double-shift overlay are
+      // both mounted when the overlay is up, and they differ in what picking a row does —
+      // the overlay resets the viewer stack and then dismisses itself. That is the only
+      // input that is about which INSTANCE is rendering, so it is the query's one
+      // parameter, and interning means at most two live realizations.
+      watchQuery(engine, q.launcherContent(false)),
+      watchQuery(engine, q.launcherContent(true)),
+      // How results can be drawn, and every opener that could run. Both used to be worked
+      // out mid-render from `platform` — three registry reads that nothing invalidated on,
+      // so the launcher and the viewer nav only kept up because this snapshot is coarse
+      // enough to redraw them anyway. As a query the dependency is declared, which is what
+      // makes it safe to give either of them a region later.
+      watchQuery(engine, q.views),
+      watchQuery(engine, q.openers),
     ],
-    // `_bump` is IN the snapshot, unlike before. `watch` skips a render whose value is
-    // shallow-equal to the last one, so a forced re-render that left no trace in the
-    // object would be discarded as "nothing changed" — which is the opposite of what
-    // asking for one means.
-    (wb, overlay, nav, ex, se, keys, tr, notif, ctx, settings, pluginList, statusItems, so, off, act, vp, voice, _bump) =>
-      ({ wb, overlay, nav, ex, se, keys, tr, notif, ctx, settings, plugins: pluginList, statusItems, so, off, act, vp, voice, _bump }),
+    // No `_bump` any more. It existed to defeat `watch`'s shallow-equality check for a
+    // forced re-render that left no trace in the snapshot — a counter smuggled into the
+    // state to get past an optimisation designed to skip pointless renders. With the state
+    // that needed it in a cell, every render has a reason again.
+    (wb, overlay, nav, ex, se, ctx, settings, off, vp, voice, view, caps, commandKeys,
+      content, modalContent, views, openers) =>
+      ({ wb, overlay, nav, ex, se, ctx, settings, off, vp, voice, view, caps, commandKeys,
+        content, modalContent, views, openers }),
   );
 
-  return alias(() => watch(combined, (state) => view(state, ui)));
+  // The chrome, subscribed to what it reads instead of to everything.
+  //
+  // These four render the same facts in different shapes — `statusFacts` is shared between
+  // them — so they share a query set. Splitting them out is what takes `tr` off the main
+  // snapshot: an upload progress tick used to invalidate the one watch that builds the whole
+  // shell, so moving one number in the transfer tray reconstructed every row of the file
+  // list beneath it. Now it reaches the chrome and the tray, and nothing else.
+  const chrome = {
+    ex: q.explorer, tr: q.transfers, act: q.activity, off: q.offline,
+    so: q.social, wb: q.workbench, statusItems: q.statusItems, caps: q.capabilities,
+    // The numbers and the one-line verdict both shells report. Derived by the query rather
+    // than by the status bar and imported from there by the phone chrome, which is what it
+    // was — a business-layer derivation living in a component. See bl/status.js.
+    facts: q.statusFacts,
+  };
+  // A query boots asynchronously — it awaits a container lease first — so a region is
+  // PENDING for the first frame or two and `watch` renders its placeholder. For a bar with
+  // a fixed height that has to be an empty bar rather than nothing, or the layout jumps
+  // once on load and settles.
+  const regions = {
+    statusBar: region(engine, chrome, (s) => statusBar(s, ui), { placeholder: () => div({ className: 'statusbar' }) }),
+    phoneTopBar: region(engine, chrome, (s) => phoneTopBar(s, ui), { placeholder: () => div({ className: 'phonebar top' }) }),
+    phoneBottomBar: region(engine, chrome, (s) => phoneBottomBar(s, ui), { placeholder: () => div({ className: 'phonebar bottom' }) }),
+    // Both render nothing when there is nothing to show, so an absent first frame is what
+    // they would have drawn anyway.
+    phoneSheet: region(engine, chrome, (s) => phoneSheet(s, ui)),
+    transferTray: region(engine, { tr: q.transfers }, (s) => transferTray(s, ui)),
+    // Both read one slice each, and both change often enough to matter: a toast arriving
+    // or auto-dismissing used to rebuild the entire shell — including every row of the
+    // file list — to add a line in the corner.
+    toasts: region(engine, { notif: q.notifications }, (s) => toasts(s, ui)),
+    activityPanel: region(engine, { act: q.activity }, (s) => activityPanel(s, ui)),
+    // Screens that are usually NOT on screen. Their state still invalidated the shell from
+    // wherever they were: minting an API key or a plugin reporting in rebuilt the file
+    // list. Each reads a couple of slices, so each is a cheap region.
+    settingsView: region(engine, {
+      settings: q.settings, settingsGroups: q.settingsGroups, keys: q.apiKeys,
+      caps: q.capabilities, ex: q.explorer, assoc: q.openerAssociations,
+    }, (s) => settingsView(s, ui)),
+    pluginsView: region(engine, { plugins: q.plugins, settings: q.settings },
+      (s) => pluginsView(s, ui)),
+    // Gathers what already exists rather than fetching anything new — see adminView.js.
+    adminView: region(engine, {
+      caps: q.capabilities, ex: q.explorer, plugins: q.plugins, act: q.activity, so: q.social,
+    }, (s) => adminView(s, ui)),
+    infoPanel: region(engine, { so: q.social, off: q.offline, nav: q.navigation },
+      (s) => infoPanel(s, ui)),
+    // The rail. It renders the notification bell and the identity chip, both of which read
+    // the social slice — which is how `so` was still reaching the shell after infoPanel
+    // moved out. Missed by looking at infoPanel alone; the bell is imported INTO the bar
+    // from social.js, so a grep for the component name does not find it.
+    activityBar: region(engine, { wb: q.workbench, plugins: q.plugins, so: q.social },
+      (s) => activityBar(s, ui)),
+    // The palette is the first thing to read a composed view rather than a service's state:
+    // `commands` arrives with keybinding labels resolved and availability decided, so the
+    // component stopped asking the keybinding and command services anything mid-render.
+    // `matches` is the list already ranked against what has been typed — the palette does
+    // no scoring of its own any more. See bl/match.js for why there was more than one.
+    commandPalette: region(engine, { overlay: q.overlay, se: q.search, matches: q.paletteMatches },
+      (s) => commandPalette(s, ui)),
+  };
+
+  return alias(() => watch(combined, (state) => view(state, ui, regions)));
 }
 
-function view(state, ui) {
+function view(state, ui, regions) {
   const mode = state.vp?.mode || 'desktop';
   const phone = mode === 'phone';
   return div({ className: `shell ${mode} ${state.settings['workbench.density'] === 'compact' ? 'compact' : ''}` },
     // On a phone the rail becomes a bottom bar and the status bar folds behind one icon
     // in a top bar — see phoneChrome. Everything between them is identical, which is the
     // point: only the chrome changes shape, not the app.
-    phone ? phoneTopBar(state, ui) : null,
+    phone ? regions.phoneTopBar() : null,
     div({ className: 'body' },
-      phone ? null : activityBar(state, ui),
-      mainArea(state, ui),
+      phone ? null : regions.activityBar(),
+      mainArea(state, ui, regions),
     ),
-    phone ? phoneBottomBar(state, ui) : statusBar(state, ui),
-    phone ? phoneSheet(state, ui) : null,
+    phone ? regions.phoneBottomBar() : regions.statusBar(),
+    phone ? regions.phoneSheet() : null,
     // Overlays.
     searchModal(state, ui),
-    commandPalette(state, ui),
+    regions.commandPalette(),
     dialog(state, ui),
     contextMenu(state, ui),
     pluginPanel(state, ui),
-    toasts(state, ui),
-    transferTray(state, ui),
-    activityPanel(state, ui),
+    regions.toasts(),
+    regions.transferTray(),
+    regions.activityPanel(),
   );
 }
 
-function mainArea(state, ui) {
+function mainArea(state, ui, regions) {
   // Before a collection is known there is nothing to draw: every scoped request names one
   // in its path, so a file list, a search box and an Upload button would all be lying.
   // Settings stays reachable — an admin with no collections still needs to get at it.
   if (state.ex?.gate && state.wb.activity !== 'settings') return collectionGate(state, ui);
 
   switch (state.wb.activity) {
-    case 'settings': return settingsView(state, ui);
-    case 'plugins': return pluginsView(state, ui);
+    case 'settings': return regions.settingsView();
+    case 'plugins': return regions.pluginsView();
+    case 'admin': return regions.adminView();
     default: {
       // Home: the top of the panel stack — the launcher (base search) or, once a
       // file is open, its opener full-width (optionally split with the info panel).
@@ -113,8 +221,8 @@ function mainArea(state, ui) {
       // details panel takes the whole panel instead — it has its own close button, so
       // there is still a way back to the file.
       return state.vp?.mode === 'phone'
-        ? infoPanel(state, ui)
-        : div({ className: 'editor-split' }, editorArea(state, ui), infoPanel(state, ui));
+        ? regions.infoPanel()
+        : div({ className: 'editor-split' }, editorArea(state, ui), regions.infoPanel());
     }
   }
 }
@@ -124,7 +232,7 @@ function mainArea(state, ui) {
 function searchModal(state, ui) {
   if (!state.wb.searchModal) return div();
   return div({ className: 'search-modal' },
-    div({ className: 'scrim' }).on({ click: () => ui.platform.workbench.closeSearchModal() }),
+    div({ className: 'scrim' }).on({ click: () => ui.engine.dispatch(new CloseSearchModalAction()) }),
     div({ className: 'search-modal-panel' }, launcher(state, ui, { modal: true })),
   );
 }

package/packages/web/src/ui/region.js

@@ -0,0 +1,53 @@
+// A region: one part of the shell, subscribed to only the queries it reads.
+//
+// The workbench is a single `watch` over a `derive` of eighteen cells, so any change to any
+// of them rebuilds the whole VDOM — activity bar, status bar, every overlay, the file list.
+// dodo reconciles, so the DOM update stays small; the REBUILD does not. An upload progress
+// tick reconstructs all 500 rows of a file list to move one number in the transfer tray.
+//
+// A region fixes that by narrowing the subscription instead of the render: it watches the
+// queries it actually reads, and a change to anything else never reaches it. That also makes
+// the dependency legible — the region's queries are its argument list, rather than something
+// you infer by reading which snapshot keys the body touches.
+//
+// The teardown matters as much as the render. A region that leaves the tree drops its
+// watchers; dodo disconnects the cells; ngin kills the query realizations, releasing their
+// leases and whatever they held open. That is what makes a query the right home for
+// something like a minted media URL — alive while a region is looking at it, gone when it
+// stops — with no component writing cleanup.
+//
+// See docs/tickets/009.
+
+import { dd, watch, derive } from '../runtime.js';
+import { watchQuery } from '../bl/watchQuery.js';
+
+/**
+ * @param {object} engine
+ * @param {Record<string, object>} queries name → SHARED query instance (see bl/queries.js)
+ * @param {(state: Record<string, any>) => any} build the region's view; close over `ui`
+ * @param {{placeholder?: () => any, error?: (err: Error) => any}} [opts]
+ * @returns {() => any} a component, built ONCE — see below for why that matters
+ */
+export function region(engine, queries, build, opts) {
+  const names = Object.keys(queries);
+  // Resolved at composition, not per render. `watchQuery` caches per (engine, query) so
+  // these would be the same cells either way, but doing it here says the subscription
+  // belongs to the region rather than being re-established on every pass.
+  const cells = names.map((name) => watchQuery(engine, queries[name]));
+  // `derive` coalesces: several of these changing in one frame still costs one render.
+  const combined = derive(cells, (...values) =>
+    Object.fromEntries(names.map((name, i) => [name, values[i]])));
+
+  // ONE alias function, and one options object, for the life of the app.
+  //
+  // dodo identifies an alias by the FUNCTION: "swapping the alias function ... is a
+  // different component, and reusing the state would skip the old one's detach and the new
+  // one's attach". So `alias(...)` built inside the render would detach and re-attach the
+  // watch — dropping the subscription, killing the query realization and booting a fresh
+  // one — on every pass of the parent. That is the precise opposite of what a region is
+  // for, and it would have looked like it worked.
+  //
+  // `build` and `opts` are hoisted for the same reason one level down: `watch` compares its
+  // arguments, and a builder closure rebuilt per render is a new argument every time.
+  return dd.alias(() => watch(combined, build, opts));
+}

package/packages/web/src/workbench.js

@@ -29,7 +29,7 @@
 import { dd, effect } from './runtime.js';
 import { createPlatform } from './platform/index.js';
 import { createApp } from './bl/index.js';
-import { NavigateAction, UploadFilesAction, OpenInitialCollectionAction } from './bl/actions.js';
+import { NavigateAction, UploadFilesAction, OpenInitialCollectionAction, OpenSearchModalAction, OpenInPanelAction } from './bl/actions.js';
 import { parsePackage } from './platform/pluginPackage.js';
 import workbenchComposition from './ui/compositions/workbench.js';
 import { registerBuiltinOpeners } from './ui/components/openers/index.js';
@@ -75,10 +75,8 @@ export function createWorkbench({
   // restore any that were installed on this device, then run.
   platform.plugins.restore();
 
-  const plugins = { uninstall: (id) => platform.plugins.uninstall(id) };
-
   // --- mount ----------------------------------------------------------------
-  const App = workbenchComposition({ engine, app, platform, plugins });
+  const App = workbenchComposition({ engine, platform });
   dd.reconcile(root, [App()]);
 
   // --- theme ----------------------------------------------------------------
@@ -103,8 +101,10 @@ export function createWorkbench({
   platform.keybindings.install(window);
 
   // --- viewer stack ↔ browser history ---------------------------------------
-  window.addEventListener('popstate', (e) => platform.workbench.onPopState(e));
-  installDoubleShift(platform);
+  // Browser back/forward. The panel stack is the only thing that mirrors itself into
+  // history, so this reaches it directly rather than through a shell object.
+  window.addEventListener('popstate', (e) => app.navigation.onPopState(e));
+  installDoubleShift(engine);
 
   // --- service worker (offline shell + pinned files + push) -----------------
   if (serviceWorker && 'serviceWorker' in navigator) {
@@ -116,12 +116,11 @@ export function createWorkbench({
   // --- initial load ---------------------------------------------------------
   (async () => {
     try {
-      platform.capabilities = await platform.api.capabilities();
-      // What the server can do is read straight off `platform`, not held in a store, so
-      // nothing invalidated when it arrived. Re-pushing the same state object will not
-      // do it either: a cell compares with Object.is and drops a write of what it
-      // already holds. Saying "this changed under you" is the store's job.
-      platform.workbench.touch(); // the status bar reads capabilities
+      // What the server can do is an engine query now — see bl/queries.js. It used to be
+      // assigned onto `platform` here and followed by `workbench.touch()`, a poke at an
+      // unrelated store purely to make the shell redraw, because writing a plain field
+      // invalidates nothing. The query has somewhere for the value to arrive, so the fetch
+      // belongs to it and this no longer has to announce it.
     } catch (err) {
       platform.notifications.error(`Cannot reach the Trove server: ${err.message}`);
     }
@@ -165,12 +164,12 @@ function register(platform, type, list) {
 
 // Double-shift → modal search overlay (Raycast-style). Two Shift presses within 400ms,
 // with no other key between, open it.
-function installDoubleShift(platform) {
+function installDoubleShift(engine) {
   let lastShift = 0;
   window.addEventListener('keydown', (e) => {
     if (e.key === 'Shift' && !e.repeat) {
       const now = Date.now();
-      if (now - lastShift < 400) { platform.workbench.openSearchModal(); lastShift = 0; }
+      if (now - lastShift < 400) { engine.dispatch(new OpenSearchModalAction()); lastShift = 0; }
       else lastShift = now;
     } else if (e.key !== 'Shift') {
       lastShift = 0;
@@ -200,6 +199,9 @@ function installDragAndDrop(engine, app) {
     e.preventDefault();
     dragDepth = 0;
     document.body.classList.remove('dragging-file');
-    engine.dispatch(new UploadFilesAction(e.dataTransfer.files, app.explorer.state.collectionId));
+    // No collection named: UploadFilesAction resolves the open one itself and refuses
+    // visibly when there isn't one. Reading it here only to hand it straight back was the
+    // drop target knowing where files go, which is the action's business.
+    engine.dispatch(new UploadFilesAction(e.dataTransfer.files));
   });
 }