@3sln/trove 0.0.7 → 0.0.9

package/packages/web/src/bl/index.js

@@ -5,64 +5,160 @@
 // dispatch follow-up Actions (the choreographer pattern).
 
 import { Engine, Provider } from '@3sln/ngin';
-import { effect } from '../runtime.js';
-import { ExplorerService, SearchClientService, TransfersService, ApiKeysService } from './services.js';
+import { cell } from '../runtime.js';
+import { registerCoreContext, registerViewportContext } from './context.js';
+import { TransfersService } from './services.js';
+import { explorerState, searchState, apiKeysState, viewState as viewStateSlice, overlayState, workbenchState, rotationState } from './state.js';
+import { NavigationService } from '../platform/navigation.js';
 import { SocialService } from './social.js';
 import { OfflineService } from './offline.js';
 import { ActivityService } from './activity.js';
 import { registerCommands } from './commands.js';
-import { NavigateAction, LoadCollectionsAction, OpenInitialCollectionAction } from './actions.js';
+import { NavigateAction, LoadCollectionsAction, OpenInitialCollectionAction, OpenPluginPanelAction } from './actions.js';
 
 export function createApp(platform) {
-  const explorer = new ExplorerService(platform.settings);
-  const search = new SearchClientService();
-  const apiKeys = new ApiKeysService();
+  // Named slices, not services — see bl/state.js. Each is still its own provider, so a
+  // lease naming `explorer` still says what it touches.
+  const explorer = explorerState(platform.settings);
+  const search = searchState();
+  const apiKeys = apiKeysState();
+  const rotation = rotationState();
   // One place for "what's running" and "what's stuck", covering both sides of the wire.
   const activity = new ActivityService(platform);
+  // What the UI is in the middle of doing — see bl/state.js. A resource, because it
+  // decides what is on screen.
+  const viewState = viewStateSlice();
+  // The shell, split into what it actually is. `workbench` and `overlay` are slices; the
+  // panel stack stays a service, because it mirrors itself into browser history and
+  // persists recents — neither of which a state bag can do. The WorkbenchService that used
+  // to sit over all three was a 17-method delegation facade, and the provider graph could
+  // not see through it: closing a dialog leased the whole shell.
+  const workbench = workbenchState();
+  const overlay = overlayState();
+  const navigation = new NavigationService();
   const transfers = new TransfersService(activity);
-  const social = new SocialService(platform);
+  // Offline first: social queues comment and tag writes through it while disconnected, so
+  // it is a dependency rather than something bolted on afterwards. It used to be assigned
+  // onto `social` after both existed, which reads as optional and is not — a social service
+  // built without it silently drops every offline write.
   const offline = new OfflineService(platform);
-  social.offline = offline; // social queues sidecar ops through offline when disconnected
+  const social = new SocialService(platform, offline);
 
-  const app = { platform, explorer, search, transfers, social, offline, activity, apiKeys, engine: null };
+  const app = { platform, explorer, search, transfers, social, offline, activity, apiKeys, rotation, workbench, overlay, navigation, engine: null };
 
+  // Every resource the engine has, named. The engine's STATE is the state of its
+  // resources, so the single `app` provider this started with made that state one opaque
+  // blob: every query and every action leased the whole world, and a lease that always
+  // covers everything tells you nothing about what a piece of work touches or how long it
+  // needs it.
+  //
+  // `app` is gone. It survived longest as the thing command handlers closed over, and went
+  // when they stopped being closures — see bl/commands.js. Every lease now names what it
+  // touches, and `static deps = ['explorer']` means what it says.
   const engine = new Engine({
-    providers: { app: Provider.fromSingleton(app) },
-  });
-  app.engine = engine;
+    providers: {
+      // Where a live query keeps its subscription — see bl/queries.js. A provider, so it
+      // is per engine; keyed by the query instance, so an entry belongs to exactly one
+      // realization. A query instance is shared (it is interned), so it is the wrong place
+      // to put anything that is true only while it is being watched.
+      appState: Provider.fromSingleton(new Map()),
 
-  registerCommands(app);
+      // The drive.
+      explorer: Provider.fromSingleton(explorer),
+      search: Provider.fromSingleton(search),
+      transfers: Provider.fromSingleton(transfers),
+      social: Provider.fromSingleton(social),
+      offline: Provider.fromSingleton(offline),
+      activity: Provider.fromSingleton(activity),
+      apiKeys: Provider.fromSingleton(apiKeys),
+      rotation: Provider.fromSingleton(rotation),
+      viewState: Provider.fromSingleton(viewState),
 
-  // Wire the plugin panel opener hook to the workbench.
-  platform.openPluginPanel = (pluginId) => platform.workbench.openPluginPanel(pluginId);
+      // The engine itself, for actions that choreograph — dispatching a follow-up rather
+      // than doing the follow-up's work inline. LAZY because the engine does not exist
+      // when its own providers are declared; by the time anything leases this, it does.
+      // ngin's execute context carries a dispatchFeed but no dispatcher, so this is the
+      // seam for it.
+      engine: Provider.fromLazySingleton(async () => engine, () => {}),
 
-  // Project explorer state → context keys in ONE place. These drive when-clauses
-  // (e.g. the Delete keybinding needs `explorer.hasSelection`), and previously only
-  // NavigateAction set them — so selecting a file never flipped hasSelection true and
-  // Delete silently did nothing. Deriving them from the observable keeps them honest.
-  //
-  // `null` when no collection is open, never the string 'default'. A when-clause reading
-  // this is asking which collection is open, and answering with the name of one that may
-  // not exist made every such clause true before the user had chosen anything.
-  platform.context.setMany({ 'explorer.collectionId': null, 'explorer.hasSelection': false });
-  effect(explorer.observe(), (ex) => {
-    platform.context.setMany({
-      'explorer.collectionId': ex.collectionId ?? null,
-      'explorer.hasSelection': (ex.selection?.length || 0) > 0,
-    });
-  });
+      // The shell.
+      workbench: Provider.fromSingleton(workbench),
+      overlay: Provider.fromSingleton(overlay),
+      navigation: Provider.fromSingleton(navigation),
+      settings: Provider.fromSingleton(platform.settings),
+      notifications: Provider.fromSingleton(platform.notifications),
+      context: Provider.fromSingleton(platform.context),
+      commands: Provider.fromSingleton(platform.commands),
+      keybindings: Provider.fromSingleton(platform.keybindings),
+      contributions: Provider.fromSingleton(platform.contributions),
+      viewport: Provider.fromSingleton(platform.viewport),
+      voice: Provider.fromSingleton(platform.voice),
+
+      // The outside world.
+      api: Provider.fromSingleton(platform.api),
 
-  // Load a file's conversation/tags whenever the active viewer panel changes (the
-  // panel stack lives in the navigation sub-service now).
-  let lastTab = null;
-  effect(platform.workbench.observeNav(), (nav) => {
-    if (nav.activeTabId !== lastTab) {
-      lastTab = nav.activeTabId;
-      // Clear the sidecar when no file is active (last tab closed) so a stale
-      // conversation from the previous file doesn't linger.
-      social.loadSidecar(nav.activeFile ? nav.activeFile.id : null);
-    }
+      // What this deployment can do: which storage drivers it offers, whether it can
+      // suggest searches, how transfers reach the bucket.
+      //
+      // A PROVIDER, not an action and not a query holding a promise. Nobody asks for
+      // capabilities — they are ambient facts other things consult in order to decide, so
+      // there is no intent to dispatch and nothing to put on the feed. It was a query that
+      // memoised `api.capabilities()` on its own instance to avoid re-fetching, which is a
+      // cache with no invalidation living inside a view.
+      //
+      // It provides a CELL rather than the value, and the fetch is deliberately not
+      // awaited. Awaiting would make every lease of this block until the server answered,
+      // so a query that merely consults capabilities would be PENDING and the shell would
+      // render nothing until the round trip finished. The cell starts null — "not known
+      // yet", which every reader already treats correctly — and fills in, so anything
+      // watching simply re-projects when the answer lands.
+      //
+      // One fetch for the life of the page, because `fromLazySingleton` memoises on the
+      // creation promise. That is the provider's job, which is where it belongs.
+      // Closes over `platform.api` rather than declaring `{ deps: ['api'] }`: a provider's
+      // deps arrive as the PROVIDER INSTANCES, not as resources, so the dependency form
+      // would hand over something you must `obtain()` and release. Every other provider
+      // here closes over what it needs, and this is the same client either way.
+      capabilities: Provider.fromLazySingleton(
+        async () => {
+          const held = cell(null);
+          platform.api.capabilities().then(
+            (caps) => held.setValue(caps),
+            // A drive whose capabilities cannot be read still works; every reader treats
+            // null as "not known" and falls back. Failing the provider would take the
+            // whole shell down over an optional answer.
+            () => {},
+          );
+          return held;
+        },
+        () => {},
+      ),
+      mediaUrls: Provider.fromSingleton(platform.mediaUrls),
+      plugins: Provider.fromSingleton(platform.plugins),
+    },
   });
+  app.engine = engine;
+
+  // How a command reaches the engine. A command resolves to actions and the CommandService
+  // dispatches them; it is built with the platform, before the engine exists, so the
+  // dispatcher is handed over here.
+  //
+  // This is the boundary, not a shortcut: a keystroke and a plugin's RPC both originate
+  // outside the engine, and one of them has to carry the intent in. Everything past this
+  // point is an action on the feed.
+  platform.commands.dispatch = (action) => engine.dispatch(action);
+  // The same seam for the two other places that originate outside the engine: a docked
+  // plugin frame opening a file, and the plugin RPC asking for its panel.
+  platform.dispatch = (action) => engine.dispatch(action);
+  platform.openPluginPanel = (pluginId) => engine.dispatch(new OpenPluginPanelAction(pluginId));
+
+  registerCommands(app);
+
+  // Every built-in when-clause key, derived from the resource it summarises. Registered
+  // here because this is where those resources exist; see bl/context.js for the list and
+  // for why deriving them is not the same as moving the writes.
+  registerCoreContext(platform.context, { workbench, overlay, navigation, explorer });
+  registerViewportContext(platform.context, platform.viewport);
 
   social.init();
   offline.init();

package/packages/web/src/bl/intern.js

@@ -0,0 +1,129 @@
+// One instance per logical query.
+//
+// ngin shares a live query realization by INSTANCE identity — its controller map is keyed on
+// the object, and neither the class nor the fields are consulted. That is fine for a query
+// with no arguments, which can be a module singleton. It is a trap for a parameterised one:
+// `new MediaUrl('n1')` in two places is two realizations of the same question, so two minted
+// URLs and two leases for one file, and nothing fails to say so.
+//
+// So a parameterised query declares a shared factory and is asked for, not constructed:
+//
+//     class MediaUrl extends ViewQuery {
+//       static of = queryOf(MediaUrl);
+//       constructor(nodeId) { ... }
+//     }
+//
+//     MediaUrl.of('n1')     // same id, same instance, one realization
+//
+// A field holding a factory rather than a base class or a mixin, which is what makes this
+// small: the query keeps whatever base it already had, each factory closes over its own
+// table, and there is no name resolved through a prototype chain for anything to shadow.
+
+/**
+ * Eviction, without a policy to get wrong.
+ *
+ * Entries are weak, and a finalizer sweeps the key once the instance is collected. That is
+ * sound because LIVENESS PINS THE INSTANCE: ngin's controller map is a plain Map holding the
+ * query as a key, deleted only on teardown, so a query with observers is strongly reachable
+ * and cannot be collected. An idle one can be, and re-asking simply builds a fresh instance.
+ *
+ * The alternative — an LRU with a cap — is actively wrong here: evicting a LIVE entry means
+ * the next `of()` mints a second instance while the first is still running, which is the
+ * exact bug this exists to prevent, arriving on a timer.
+ *
+ * (This leans on ngin's default controller map being strong. `hooks.createQueryControllersMap`
+ * could replace it with a weak one; we do not, and a weak one would break this.)
+ */
+const sweeper = new FinalizationRegistry(({ table, key }) => {
+  // Only if it is still the dead entry — a fresh instance may have claimed the key already.
+  if (table.get(key) && !table.get(key).deref()) table.delete(key);
+});
+
+/**
+ * Reject anything a canonical key cannot capture.
+ *
+ * A function stringifies to `undefined` in JSON, so two queries taking different callbacks
+ * would key identically and silently share one realization — the very bug this exists to
+ * prevent, reintroduced by the fix. Fail at the call site instead. A query with arguments
+ * like that passes its own key function and never comes through here.
+ */
+function assertKeyable(value, path) {
+  const t = typeof value;
+  if (value === null || t === 'string' || t === 'number' || t === 'boolean') return;
+  if (t !== 'object') {
+    throw new TypeError(
+      `Query argument ${path} is a ${t}, which cannot be part of a sharing key. ` +
+      'Pass an id and let the query look the thing up, or give queryOf a key function.',
+    );
+  }
+  if (Array.isArray(value)) return value.forEach((v, i) => assertKeyable(v, `${path}[${i}]`));
+  const proto = Object.getPrototypeOf(value);
+  if (proto === Object.prototype || proto === null) {
+    return Object.entries(value).forEach(([k, v]) => assertKeyable(v, `${path}.${k}`));
+  }
+  throw new TypeError(
+    `Query argument ${path} is a ${value.constructor?.name ?? 'non-plain object'}, which ` +
+    'cannot be part of a sharing key. Pass an id and let the query look the thing up, ' +
+    'or give queryOf a key function.',
+  );
+}
+
+/** A canonical string for a value: object keys sorted, so `{a,b}` and `{b,a}` are one key. */
+export function stableKey(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+  if (Array.isArray(value)) return `[${value.map(stableKey).join(',')}]`;
+  return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stableKey(value[k])}`).join(',')}}`;
+}
+
+/** The default key: every argument, in order, canonically. Types count, so 1 and '1' differ. */
+export function keyOfArgs(...args) {
+  args.forEach((a, i) => assertKeyable(a, `#${i}`));
+  return args.map(stableKey).join('|');
+}
+
+/**
+ * A factory returning the shared instance of `Class` for a given argument list.
+ *
+ *     class Thing extends ViewQuery { static of = queryOf(Thing); }
+ *
+ * `key` defaults to the arguments, canonically. Pass one to share more coarsely than the
+ * arguments do — an option that changes how something is displayed but not what is fetched
+ * should not split one realization into two — or to key arguments the default refuses:
+ *
+ *     static of = queryOf(Thing, (nodeId, opts) => nodeId);
+ *
+ * A key rather than a hash plus a comparator: a comparator only earns its complexity when
+ * keys can collide, and a canonical key does not collide.
+ *
+ * The class is captured, so a subclass inheriting this field would build the PARENT —
+ * `Sub.of('x')` returning a `Base` is the sort of wrong that reads as right. The factory is
+ * a plain function rather than an arrow so that `this` is the class it was reached through,
+ * and it refuses to run when that is not the class it was built for. A subclass that wants
+ * sharing declares its own `static of`.
+ *
+ * A detached call — `const of = Thing.of; of('x')` — has no receiver at all, and in a module
+ * `this` is `undefined` rather than the global. That is the ordinary way to pass the factory
+ * around, so it is allowed; only a DIFFERENT class is an error.
+ *
+ * @param {Function} Class the query class, referenced from inside its own body
+ * @param {(...args: any[]) => string} [key]
+ */
+export function queryOf(Class, key = keyOfArgs) {
+  const table = new Map();
+  return function of(...args) {
+    if (this !== undefined && this !== Class) {
+      throw new TypeError(
+        `${this?.name ?? 'A subclass'}.of() would build a ${Class.name}, because \`of\` ` +
+        `captures the class it was declared on. Give ${this?.name ?? 'the subclass'} its own ` +
+        '`static of = queryOf(...)`, or call it on ' + Class.name + ' directly.',
+      );
+    }
+    const k = key(...args);
+    const existing = table.get(k)?.deref();
+    if (existing) return existing;
+    const instance = new Class(...args);
+    table.set(k, new WeakRef(instance));
+    sweeper.register(instance, { table, key: k });
+    return instance;
+  };
+}

package/packages/web/src/bl/launcher.js

@@ -0,0 +1,251 @@
+// What the launcher is showing.
+//
+// This was ~100 lines inside the launcher COMPONENT, deciding — mid-render, where nothing
+// else could see it — which nodes are on screen, what each heading says, whether "All
+// items" is a lie because another page is waiting, and what the empty state should read
+// when a load FAILED as against when the drive is genuinely empty. Every one of those is a
+// question about engine state.
+//
+// It also made a smaller thing impossible: `pickView` needs the nodes on screen, and while
+// they were assembled in a render they looked like render-layer data. They are not — they
+// come from the explorer and search resources. Deriving them here is what lets the choice
+// of view become engine state too.
+//
+// Groups are DATA. A header control is `{ icon, label, title, actions }`, not a button —
+// the launcher used to put a rendered vnode in `group.action`, which is the same
+// carrying-a-handle problem that menu items had before they carried `actions`.
+
+import { parseTagQuery, filterLabel } from './tagQuery.js';
+import {
+  ExecCommandAction, CloseSearchModalAction, OpenFileAction, SearchAction, FilterAction,
+  SetLaunchQueryAction,
+} from './actions.js';
+
+/** Which mode the typed query puts the launcher in. */
+export function launcherMode(query) {
+  const q = query || '';
+  return q.startsWith('!') ? 'command' : q.includes('#') ? 'filter' : 'search';
+}
+
+const iconFor = (node) => {
+  const t = node?.contentType || '';
+  if (t.startsWith('image/')) return 'file-image';
+  if (t.startsWith('audio/')) return 'file-audio';
+  if (t.startsWith('video/')) return 'file-video';
+  return 'file-text';
+};
+
+/**
+ * Everything you can do to a file, as descriptions.
+ *
+ * `pinned` and `keys` are resolved by the caller because both are questions about engine
+ * state: whether THIS file is already available offline, and what the shortcut for a
+ * command actually is on this machine. Hardcoding "⌘⇧L" told a Windows user about a key
+ * they do not have, and told everyone the default even after they had rebound it.
+ */
+export function fileMenuOf(node, { pinned = false, keys = {} } = {}) {
+  const kbd = (id) => keys[id] || undefined;
+  return [
+    { label: 'Open', icon: 'file-text', actions: [new ExecCommandAction('explorer.open', node)] },
+    { label: 'Download', icon: 'download', actions: [new ExecCommandAction('explorer.download', node)] },
+    // Labelled by destination rather than by format: one goes in a document, the other
+    // goes to a person.
+    { label: 'Copy shareable link', icon: 'link', actions: [new ExecCommandAction('explorer.copyShareLink')] },
+    { label: 'Copy trove: link', icon: 'link', kbd: kbd('explorer.copyLink'), actions: [new ExecCommandAction('explorer.copyLink')] },
+    { sep: true },
+    { label: 'Rename…', actions: [new ExecCommandAction('explorer.rename')] },
+    pinned
+      ? { label: 'Remove from offline', icon: 'close', actions: [new ExecCommandAction('offline.unpin', node)] }
+      : { label: 'Make available offline', icon: 'download', actions: [new ExecCommandAction('offline.pin', node)] },
+    { sep: true },
+    { label: 'Move to trash', icon: 'trash', danger: true, kbd: kbd('explorer.delete'), actions: [new ExecCommandAction('explorer.delete')] },
+  ];
+}
+
+/** What you can do to something already in the trash. */
+export function trashMenuOf(node) {
+  return [
+    { label: 'Restore', icon: 'refresh', actions: [new ExecCommandAction('explorer.restore', node.id)] },
+    { sep: true },
+    { label: 'Delete forever', icon: 'trash', danger: true, actions: [new ExecCommandAction('explorer.purgeOne', node.id)] },
+  ];
+}
+
+/**
+ * One row for a file.
+ *
+ * `menu` stays a thunk. A drive can have hundreds of rows on screen and almost none of
+ * their menus are ever opened, so building them all would be work nobody asked for — and a
+ * pure function deferring pure work is data as much as the array it would have returned.
+ */
+function fileItem(node, { modal, pinnedIds, keys }) {
+  return {
+    icon: iconFor(node),
+    title: node.name,
+    detail: node.contentType || '',
+    node,
+    // From the modal search, `reset` starts a fresh viewer stack; then close it.
+    actions: [
+      new OpenFileAction(node, { reset: !!modal }),
+      ...(modal ? [new CloseSearchModalAction()] : []),
+    ],
+    menu: () => fileMenuOf(node, { pinned: pinnedIds.has(node.id), keys }),
+  };
+}
+
+/**
+ * The groups on screen.
+ *
+ * @param {object} s the slices this reads, already plain
+ * @param {boolean} modal whether this is the double-shift overlay rather than the home
+ *   screen — the one input that is genuinely about which INSTANCE is rendering, since both
+ *   are on screen at once when the overlay is up
+ */
+export function launcherGroupsOf(s, modal = false) {
+  const { ex = {}, se = {}, nav = {}, query = '', commandMatches = [], pinnedIds = new Set(), keys = {} } = s;
+  const mode = launcherMode(query);
+  const row = (node) => fileItem(node, { modal, pinnedIds, keys });
+  const closeModal = modal ? [new CloseSearchModalAction()] : [];
+
+  if (mode === 'command') {
+    return [{
+      id: 'commands',
+      title: 'Commands',
+      items: commandMatches.map((c) => ({
+        icon: 'command', title: c.title, detail: c.category, badge: 'command',
+        actions: [new ExecCommandAction(c.id), ...closeModal],
+      })),
+      empty: 'No matching commands.',
+    }];
+  }
+
+  const { text, filters } = parseTagQuery(query);
+  const nodes = (se.results || []).map((r) => r.node);
+  const err = se.error;
+  // A one-click retry so a transient search/filter failure isn't a dead end.
+  const retry = (actions) => (err ? [{ icon: 'refresh', label: 'Retry', title: 'Retry', actions }] : []);
+
+  // Drive-wide tag/property filter (server-side), optionally narrowed by free text.
+  if (filters.length) {
+    const label = filters.map(filterLabel).join(' ') + (text.trim() ? ` · "${text.trim()}"` : '');
+    return [{
+      id: 'filtered',
+      title: se.loading ? 'Filtering…' : err ? 'Filter failed' : 'Filtered',
+      // Shown as typed: a tag is a value, not a heading.
+      verbatim: se.loading || err ? null : label,
+      controls: retry([new FilterAction(filters, text)]),
+      items: nodes.map(row),
+      empty: se.loading ? 'Filtering…' : err ? `Couldn’t filter: ${err}` : 'No files match those filters.',
+    }];
+  }
+
+  // Free-text search.
+  if (text.trim()) {
+    return [{
+      id: 'results',
+      title: se.loading ? 'Searching…' : err ? 'Search failed' : 'Results',
+      controls: retry([new SearchAction(query)]),
+      items: nodes.map(row),
+      empty: se.loading ? 'Searching…' : err ? `Couldn’t search: ${err}` : 'No files match.',
+    }];
+  }
+
+  // Home: recents, then everything in the collection. There is nothing to descend into —
+  // this is the "show me everything" fallback for when search isn't the answer.
+  const groups = [];
+  const recents = (nav.recents || []).map(row);
+  if (recents.length) groups.push({ id: 'recent', title: 'Recent', items: recents });
+
+  const shown = (ex.items || []).length;
+  // `stats` is the collection; `items` is the page. When the server didn't report stats we
+  // only know the page — and saying "500" while a next page exists is a claim about the
+  // drive that is false, so say "500+" instead.
+  const knownTotal = ex.stats?.items ?? null;
+  const total = knownTotal ?? shown;
+  const totalLabel = knownTotal != null ? knownTotal.toLocaleString() : `${shown.toLocaleString()}+`;
+  const items = (ex.items || []).map(row);
+  // A partial list must not be titled "All items" — that is a claim about the drive, and on
+  // a collection bigger than one page it is false. Say what is on screen, and offer the rest
+  // rather than leaving it unreachable.
+  if (ex.nextCursor) {
+    items.push({
+      icon: 'refresh',
+      title: ex.loadingMore ? 'Loading…'
+        : knownTotal != null ? `Show more (${(knownTotal - shown).toLocaleString()} more)` : 'Show more',
+      detail: 'or search to jump straight to something',
+      actions: [new ExecCommandAction('explorer.loadMore')],
+    });
+  }
+
+  // The trash, when it has been opened. Not shown by default: it is a place you go to
+  // recover a mistake, not part of browsing the drive.
+  if (ex.trash) {
+    groups.push({
+      id: 'trash',
+      // One line, not two: a header reading "0 items" above a body reading "the trash is
+      // empty" is the same sentence twice, permanently parked above the drive.
+      title: ex.trash.length
+        ? `Trash · ${ex.trash.length} item${ex.trash.length === 1 ? '' : 's'}`
+        : 'Trash',
+      controls: [
+        ...(ex.trash.length
+          ? [{ icon: 'trash', label: 'Empty trash', title: 'Destroy everything in the trash', actions: [new ExecCommandAction('explorer.emptyTrash')] }]
+          : []),
+        // The way back out. Opening the trash used to be one-way until a page reload.
+        { icon: 'close', label: 'Close', title: 'Hide the trash', actions: [new ExecCommandAction('explorer.hideTrash')] },
+      ],
+      items: (ex.trash || []).map((n) => ({
+        icon: 'trash',
+        title: n.name,
+        detail: `deleted ${new Date(n.deletedAt).toLocaleString()} — restore`,
+        actions: [new ExecCommandAction('explorer.restore', n.id)],
+        menu: () => trashMenuOf(n),
+      })),
+      empty: 'The trash is empty.',
+    });
+  }
+
+  groups.push({
+    id: 'all',
+    title: ex.nextCursor ? `All items · showing ${shown.toLocaleString()} of ${totalLabel}` : 'All items',
+    // The empty state told people to upload a file, and on desktop and TV there was nothing
+    // anywhere that would let them. (Phone has the + in its bottom bar.)
+    controls: modal ? [] : [{ icon: 'upload', label: 'Upload', title: 'Upload files to this collection', actions: [new ExecCommandAction('explorer.upload')] }],
+    items,
+    // Don't show a false "empty" when the load actually FAILED (e.g. server unreachable) —
+    // say so, so the user knows to retry rather than believing the collection is empty. (A
+    // toast also fires, but the persistent state must be honest.)
+    empty: ex.loading ? 'Loading…' : ex.error ? `Couldn’t load this collection: ${ex.error}` : 'Nothing here yet — upload a file to get started.',
+  });
+  return groups;
+}
+
+/**
+ * The suggestions shown when a search came back with nothing.
+ *
+ * Two halves, both settled by the `launcherContent` query: whether an offer applies at all
+ * — a search ran, it succeeded, it found nothing — and what to suggest, which the server
+ * decides and reaches the engine through the `capabilities` resource. Each example carries
+ * the actions that run it, so the component only draws them.
+ */
+export function searchHelpOf({ eligible = false, caps = null } = {}) {
+  if (!eligible) return null;
+  const p = caps?.searchPrompt;
+  if (!p?.hint && !p?.examples?.length) return null;
+  return {
+    hint: p.hint || null,
+    examples: (p.examples || []).map((ex) => {
+      const { text, filters } = parseTagQuery(ex.query);
+      return {
+        query: ex.query,
+        label: ex.label || null,
+        // Running an example is the same two steps as typing it: put it in the box, then
+        // ask whichever of search or filter that spelling means.
+        actions: [
+          new SetLaunchQueryAction(ex.query),
+          filters.length ? new FilterAction(filters, text) : new SearchAction(text),
+        ],
+      };
+    }),
+  };
+}

package/packages/web/src/bl/links.js

@@ -29,7 +29,7 @@ export async function openTroveLink(ui, uri, { from } = {}) {
   try {
     const res = await ui.platform.api.stat(uri);
     if (!res?.node) throw new Error('not found');
-    ui.go(new OpenFileAction(res.node));
+    ui.engine.dispatch(new OpenFileAction(res.node));
     return res.node;
   } catch (err) {
     notify.warn(describeBrokenLink(ref, err, from));