@3sln/trove 0.0.2

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

@@ -0,0 +1,306 @@
+// ActivityService — the client's answer to "what is going on, and what is stuck".
+//
+// It holds two lists that look similar and mean different things, and keeping them
+// distinct is the whole design:
+//
+//   TASKS   work happening now. Ephemeral. A task disappears when it finishes (after a
+//           moment on screen) and when the process running it stops. That is correct:
+//           the work stopped too.
+//   ISSUES  a standing problem left behind by something that already failed. Durable on
+//           the server. It stays until the thing it complains about actually works —
+//           not until it is acknowledged, and not until a reload.
+//
+// WHY ONE SERVICE FOR BOTH SIDES. Work happens in two places — an upload runs in this
+// browser, a reindex runs on the server — and a user does not care which. So this holds
+// one list, with each task tagged by where it lives:
+//
+//   local   started here, driven here. The owner (TransfersService) reports progress
+//           directly, and cancelling calls a function.
+//   server  a read-only MIRROR of the server's registry. Nothing here drives it;
+//           cancelling posts, and the next poll shows the result. Treating a mirror as
+//           writable is how two sources of truth get invented.
+//
+// WHY POLLING. There is no streaming transport in this server, and adding SSE through
+// three runtime adapters to move a progress bar is not a trade worth making yet. So:
+// poll fast (1s) only while something is running, drop to nothing when the drive is
+// idle, and re-check when the tab regains focus. At rest this costs one request when
+// the app loads. If a real-time channel ever exists, only `#poll` changes.
+
+import { cell } from '../runtime.js';
+
+const ACTIVE_MS = 1000; // while something is running, we want a live-feeling bar
+const IDLE_MS = 60_000; // otherwise just enough to notice a task someone else started
+
+export class ActivityService {
+  constructor(platform) {
+    this.platform = platform;
+    this.api = platform.api;
+    this.state = {
+      tasks: [], // merged: local first, then the server mirror
+      issues: [],
+      issuesLoading: false,
+      // A load failure is state, not a shrug: "no problems" and "we couldn't ask" look
+      // identical on screen unless one of them says so. TWO fields, not one, because
+      // these are independent requests — a tasks poll that succeeds must not erase the
+      // news that the issues poll failed, which is exactly the bug one shared field
+      // produced.
+      tasksError: null,
+      issuesError: null,
+      open: false, // the activity panel
+    };
+    this.cell = cell(this.state);
+    this._local = new Map(); // id -> local task (this browser owns these)
+    this._server = [];
+    this._timer = null;
+    this._pollMs = null;
+  }
+
+  observe() {
+    return this.cell;
+  }
+  #set(patch) {
+    this.state = { ...this.state, ...patch };
+    this.cell.setValue(this.state);
+  }
+  #merge() {
+    this.#set({ tasks: [...this._local.values(), ...this._server] });
+  }
+
+  // --- local tasks -----------------------------------------------------------
+
+  /**
+   * Register work happening in this browser. Returns a handle with the same shape the
+   * server's registry hands its callers, so code that reports progress doesn't need to
+   * know which side it is running on.
+   *
+   * @param {{title: string, kind?: string, detail?: string, total?: number|null,
+   *          unit?: string, onCancel?: () => void}} spec
+   */
+  start(spec = {}) {
+    const id = spec.id || `local_${Math.random().toString(36).slice(2, 10)}`;
+    const task = {
+      id,
+      source: 'local',
+      kind: spec.kind || 'general',
+      title: spec.title || 'Working',
+      detail: spec.detail ?? null,
+      status: 'running',
+      done: 0,
+      // No total means indeterminate, and that is a legitimate answer. A caller that
+      // doesn't know how much work there is must not invent a number: a progress bar
+      // that lies is worse than a spinner that admits it doesn't know.
+      total: spec.total ?? null,
+      unit: spec.unit || null,
+      cancellable: !!spec.onCancel,
+      startedAt: Date.now(),
+      endedAt: null,
+      error: null,
+    };
+    this._local.set(id, task);
+    this._cancels ||= new Map();
+    if (spec.onCancel) this._cancels.set(id, spec.onCancel);
+    this.#merge();
+    this.#schedule();
+
+    const patch = (p) => {
+      const cur = this._local.get(id);
+      if (!cur || cur.status !== 'running') return; // finished tasks are final
+      this._local.set(id, { ...cur, ...p });
+      this.#merge();
+    };
+    return {
+      id,
+      progress: (p = {}) => patch({
+        done: p.done ?? this._local.get(id)?.done ?? 0,
+        total: p.total === undefined ? this._local.get(id)?.total : p.total,
+        unit: p.unit ?? this._local.get(id)?.unit,
+        detail: p.detail ?? this._local.get(id)?.detail,
+      }),
+      succeed: (detail) => { patch({ status: 'done', endedAt: Date.now(), detail: detail ?? this._local.get(id)?.detail }); this.#expire(id); },
+      fail: (err) => { patch({ status: 'failed', endedAt: Date.now(), error: err?.message || String(err || 'failed') }); },
+      cancel: () => { patch({ status: 'cancelled', endedAt: Date.now() }); this.#expire(id); },
+    };
+  }
+
+  /** A finished task lingers briefly so it is seen to finish, then goes. */
+  #expire(id, after = 5000) {
+    setTimeout(() => {
+      this._local.delete(id);
+      this._cancels?.delete(id);
+      this.#merge();
+    }, after);
+  }
+
+  async cancel(id) {
+    const local = this._local.get(id);
+    if (local) {
+      this._cancels?.get(id)?.();
+      return;
+    }
+    // A server task is a mirror: ask, then let the next poll tell the truth.
+    try {
+      await this.api.cancelTask(id);
+      await this.refreshTasks();
+    } catch (err) {
+      this.#set({ tasksError: err.message });
+    }
+  }
+
+  dismiss(id) {
+    if (this._local.delete(id)) { this.#merge(); return; }
+    this.api.dismissTask(id).catch(() => {});
+    this._server = this._server.filter((t) => t.id !== id);
+    this.#merge();
+  }
+
+  // --- server mirror + issues ------------------------------------------------
+
+  async init() {
+    await this.refresh();
+    this.#schedule();
+    // Coming back to the tab is the moment a stale list is most obvious.
+    window.addEventListener('focus', () => this.refresh());
+  }
+
+  async refresh() {
+    await Promise.all([this.refreshTasks(), this.refreshIssues()]);
+  }
+
+  async refreshTasks() {
+    const wasRunning = this.running.length > 0;
+    try {
+      const { tasks } = await this.api.tasks();
+      this._server = (tasks || []).map((t) => ({ ...t, source: 'server' }));
+      this.#set({ tasksError: null });
+      this.#merge();
+    } catch (err) {
+      // Offline or a server that doesn't have the endpoint: stop claiming to know.
+      this._server = [];
+      this.#set({ tasksError: err.message });
+      this.#merge();
+    }
+    // The moment work STOPS is the moment an issue is most likely to have been fixed,
+    // so re-read them then. Without this, a retry that succeeds in 50 ms leaves the
+    // problem on screen until the next idle poll — up to a minute of the user being
+    // told something is broken that isn't.
+    if (wasRunning && !this.running.length) this.refreshIssues();
+    this.#schedule();
+  }
+
+  async refreshIssues() {
+    this.#set({ issuesLoading: true });
+    try {
+      const { issues } = await this.api.issues();
+      this.#set({ issues: issues || [], issuesLoading: false, issuesError: null });
+    } catch (err) {
+      // Deliberately NOT clearing `issues`: the last known list is better than an empty
+      // one that reads as "nothing is wrong".
+      this.#set({ issuesLoading: false, issuesError: err.message });
+    }
+  }
+
+  async retryIssue(id) {
+    try {
+      await this.api.retryIssue(id);
+      // The fix runs as a task; adopt it now so the click visibly did something, and
+      // let the poll clear the issue when the work actually succeeds. The retry may
+      // finish faster than a poll interval, so re-read the issues directly too — a
+      // Retry button that leaves the problem sitting there reads as a broken button.
+      await this.refreshTasks();
+      // A retry can finish faster than one poll interval — in which case there is no
+      // running→idle transition to notice and the fixed problem would sit on screen
+      // until the next idle poll. A couple of bounded follow-ups cover that window
+      // without turning this into a busy loop.
+      this.#followUp();
+      this.platform.notifications?.info?.('Retrying — watch its progress in Activity');
+    } catch (err) {
+      this.platform.notifications?.error?.(`Couldn't retry: ${err.message}`);
+    }
+  }
+
+  async dismissIssue(id) {
+    const before = this.state.issues;
+    this.#set({ issues: before.filter((i) => i.id !== id) });
+    try {
+      await this.api.dismissIssue(id);
+    } catch (err) {
+      this.#set({ issues: before }); // put it back rather than pretend
+      this.platform.notifications?.error?.(`Couldn't dismiss: ${err.message}`);
+    }
+  }
+
+  /** Two bounded re-reads after an action that may have resolved something. */
+  #followUp() {
+    for (const ms of [400, 1500]) {
+      const t = setTimeout(() => { this.refreshTasks(); this.refreshIssues(); }, ms);
+      t?.unref?.();
+    }
+  }
+
+  /** Rebuild the whole search index. Surfaced as a command; reports as a task. */
+  async rebuildIndex() {
+    try {
+      const res = await this.api.reindex();
+      await this.refreshTasks();
+      this.togglePanel(true);
+      if (res.alreadyRunning) this.platform.notifications?.info?.('A rebuild is already running');
+      return res;
+    } catch (err) {
+      this.platform.notifications?.error?.(`Couldn't rebuild the index: ${err.message}`);
+      throw err;
+    }
+  }
+
+  /**
+   * Reconcile a collection with its object store — the way a drive notices files added,
+   * replaced, or removed by anything that isn't Trove. Reports as a task, like a rebuild.
+   */
+  async scanCollection(collectionId) {
+    try {
+      const res = await this.api.scanCollection(collectionId);
+      await this.refreshTasks();
+      this.togglePanel(true);
+      if (res.alreadyRunning) this.platform.notifications?.info?.('A scan of this collection is already running');
+      this.#followUp();
+      return res;
+    } catch (err) {
+      this.platform.notifications?.error?.(`Couldn't scan “${collectionId}”: ${err.message}`);
+      throw err;
+    }
+  }
+
+  togglePanel(open) {
+    this.#set({ open: open ?? !this.state.open });
+    if (this.state.open) this.refresh();
+  }
+
+  get running() {
+    return this.state.tasks.filter((t) => t.status === 'running');
+  }
+
+  /**
+   * Poll fast while something is running, slowly otherwise. Rescheduled rather than
+   * fixed, so an idle drive costs one request a minute and a running rebuild feels
+   * live — without a second transport to maintain.
+   */
+  #schedule() {
+    const want = this.running.length ? ACTIVE_MS : IDLE_MS;
+    if (this._timer && this._pollMs === want) return;
+    clearTimeout(this._timer);
+    this._pollMs = want;
+    this._timer = setTimeout(() => {
+      this._timer = null;
+      this.refreshTasks().then(() => {
+        // Issues change when tasks end, so re-read them then rather than on their own
+        // clock — a retry that fixed something should stop being listed promptly.
+        if (!this.running.length) this.refreshIssues();
+      });
+    }, want);
+    this._timer?.unref?.();
+  }
+
+  dispose() {
+    clearTimeout(this._timer);
+    this._timer = null;
+  }
+}

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

@@ -0,0 +1,274 @@
+// Register the workbench's built-in commands. Commands are the single entry
+// point for every action — palette, keybindings, buttons, and menus all call
+// `commands.execute(id)`. Handlers here dispatch ngin Actions for anything that
+// touches data, and poke the reactive shell services for pure-UI toggles.
+
+import {
+  NavigateAction, RefreshAction, DeleteAction, RenameAction,
+  UploadFilesAction, OpenFileAction, CreateCollectionAction, LoadMoreAction, TrashAction,
+  SearchAction,
+} from './actions.js';
+import { beginInstallFromFile, beginInstallFromUrl } from './pluginInstall.js';
+import { troveUri } from '@3sln/trove/core/links.js';
+
+export function registerCommands(app) {
+  const { platform, engine, explorer } = app;
+  const { commands, workbench } = platform;
+  const go = (a) => engine.dispatch(a);
+
+  const cmd = (id, title, handler, extra = {}) => commands.register({ id, title, handler, ...extra });
+
+  // --- navigation / views ----------------------------------------------------
+  cmd('workbench.showCommandPalette', 'Show All Commands', () => workbench.openPalette('commands'), { category: 'View', icon: 'command' });
+  cmd('workbench.quickOpen', 'Go to File…', () => workbench.openPalette('files'), { category: 'File', icon: 'search' });
+  cmd('workbench.view.home', 'Go Home (search & browse)', () => workbench.showHome(), { category: 'View', icon: 'search' });
+  cmd('workbench.view.plugins', 'Show Plugins', () => workbench.setActivity('plugins'), { category: 'View' });
+  cmd('workbench.openSettings', 'Open Settings', () => workbench.setActivity('settings'), { category: 'Preferences', icon: 'gear' });
+  cmd('workbench.closeOverlays', 'Close', () => workbench.closeOverlays(), { palette: false });
+
+  // Speak to search.
+  //
+  // On a TV this is mostly NOT about recognising anything: a remote's mic dictates into
+  // whatever text field the platform keyboard is attached to, and is swallowed by the
+  // system assistant when there isn't one. So the command's first job is to put the
+  // search field on screen and focused, which is a feature on every TV whether or not
+  // the browser can transcribe. Where it can — on-device only, see platform/voice.js —
+  // it also starts listening and types what it hears.
+  cmd('search.voice', 'Search by Voice', async () => {
+    await platform.voice.run({
+      onText: (text, { final }) => {
+        if (!text) return;
+        workbench.setLaunchQuery(text);
+        // Interim results keep the box in step with the speaker; only the settled
+        // transcript is worth a round trip to the server.
+        if (final) go(new SearchAction(text));
+      },
+    });
+  }, { category: 'View', icon: 'search' });
+
+  // --- background work + standing problems -----------------------------------
+  cmd('workbench.showActivity', 'Show Activity (running work & problems)',
+    () => app.activity.togglePanel(true), { category: 'View', icon: 'refresh' });
+  // The manual scan the drive had no way to ask for. Reports as a task rather than
+  // blocking, because on a large drive it takes minutes.
+  cmd('workbench.rebuildIndex', 'Rebuild Search Index',
+    () => app.activity.rebuildIndex().catch(() => {}), { category: 'View', icon: 'refresh' });
+  // Trove is not the only thing that can write to the bucket. This is how files added,
+  // replaced, or removed by something else get picked up.
+  cmd('workbench.scanCollection', 'Scan Collection for Outside Changes',
+    () => app.activity.scanCollection(explorer.state.collectionId || 'default').catch(() => {}),
+    { category: 'Explorer', icon: 'refresh' });
+
+  // --- explorer --------------------------------------------------------------
+  cmd('explorer.refresh', 'Refresh', () => go(new RefreshAction()), { category: 'Explorer', icon: 'refresh' });
+  cmd('explorer.loadMore', 'Show More Items', () => go(new LoadMoreAction()), { palette: false });
+  cmd('explorer.upload', 'Upload Files…', () => {
+    pickFiles((files) => files.length && go(new UploadFilesAction(files, explorer.state.collectionId)));
+  }, { category: 'Explorer', icon: 'upload' });
+
+  // Copy the item's trove: link, which is how one item references another in markdown.
+  // "Nothing is selected" is a real answer, and it has to be said out loud: these used
+  // to return silently, which is indistinguishable from a broken command.
+  const subject = (fallbackNode) => {
+    const node = fallbackNode || explorer.selectedNodes()[0] || workbench.activeTab()?.node;
+    if (!node) platform.notifications.info('Pick a file first — highlight one in the list, or open it.');
+    return node;
+  };
+
+  cmd('explorer.copyLink', 'Copy Link to Item', async () => {
+    const node = subject();
+    if (!node) return;
+    const uri = troveUri(node);
+    try {
+      await navigator.clipboard.writeText(uri);
+      platform.notifications.success(`Copied ${uri}`);
+    } catch {
+      // Clipboard access can be denied; showing the link is still useful.
+      platform.notifications.info(uri, { sticky: true });
+    }
+  }, { category: 'Explorer', icon: 'link' });
+
+  cmd('explorer.rename', 'Rename', () => {
+    const node = subject();
+    if (!node) return;
+    workbench.showDialog({
+      kind: 'prompt', title: 'Rename', label: 'New name', value: node.name, confirmLabel: 'Rename',
+      onSubmit: (name) => {
+        workbench.closeDialog();
+        if (name?.trim() && name !== node.name) go(new RenameAction(node.id, name.trim()));
+      },
+    });
+  }, { category: 'Explorer' });
+
+  cmd('explorer.delete', 'Delete', () => {
+    const nodes = explorer.selectedNodes();
+    const fallback = nodes.length ? null : workbench.activeTab()?.node;
+    if (fallback) nodes.push(fallback); // deleting the file you have open is the obvious intent
+    if (!nodes.length) {
+      platform.notifications.info('Pick a file first — highlight one in the list, or open it.');
+      return;
+    }
+    const doDelete = () => go(new DeleteAction(nodes.map((n) => n.id)));
+    if (platform.settings.get('explorer.confirmDelete')) {
+      workbench.showDialog({
+        kind: 'confirm', title: `Move ${nodes.length} item${nodes.length > 1 ? 's' : ''} to the trash?`,
+        // Say what actually happens. Telling someone a file will be "permanently
+        // deleted" when it goes to the trash trains them to fear a safe action; the
+        // reverse — promising recovery that doesn't exist — is worse.
+        body: nodes.length === 1
+          ? `"${nodes[0].name}" leaves the drive but is kept, and can be restored from the trash.`
+          : 'They leave the drive but are kept, and can be restored from the trash.',
+        confirmLabel: 'Move to trash',
+        onConfirm: () => {
+          workbench.closeDialog();
+          doDelete();
+        },
+      });
+    } else doDelete();
+  }, { category: 'Explorer', icon: 'trash' });
+
+  cmd('explorer.showTrash', 'Show Trash', () => {
+    go(new TrashAction('list'));
+    workbench.showHome();
+  }, { category: 'Explorer', icon: 'trash' });
+  cmd('explorer.hideTrash', 'Hide Trash', () => go(new TrashAction('hide')), { palette: false });
+  cmd('explorer.restore', 'Restore from Trash', (id) => id && go(new TrashAction('restore', id)), { palette: false });
+  cmd('explorer.purgeOne', 'Delete Forever', (id) => id && go(new TrashAction('purge', id)), { palette: false });
+  cmd('explorer.emptyTrash', 'Empty Trash', () => {
+    workbench.showDialog({
+      kind: 'confirm', title: 'Empty the trash?',
+      body: 'Everything in the trash will be destroyed. This cannot be undone.',
+      danger: true, confirmLabel: 'Delete forever',
+      onConfirm: () => { workbench.closeDialog(); go(new TrashAction('empty')); },
+    });
+  }, { category: 'Explorer', icon: 'trash' });
+
+  cmd('explorer.open', 'Open', (node) => go(new OpenFileAction(node || explorer.selectedNodes()[0])), { palette: false });
+  cmd('explorer.download', 'Download', async (node) => {
+    const target = node || explorer.selectedNodes()[0] || workbench.activeTab()?.node;
+    if (!target?.id) return;
+    try {
+      const { url, revoke } = await platform.api.download(target.id, target.name);
+      triggerDownload(url, target.name);
+      // A blob URL pins the bytes until it is released; the click has already happened
+      // by the time this runs.
+      if (revoke) setTimeout(() => URL.revokeObjectURL(url), 60_000);
+    } catch (err) {
+      platform.notifications.error(`Couldn't download ${target.name}: ${err.message}`);
+    }
+  }, { category: 'Explorer', icon: 'download' });
+
+  // --- offline ---------------------------------------------------------------
+  cmd('offline.pin', 'Make Available Offline', (node) => {
+    const target = node || explorer.selectedNodes()[0] || workbench.activeTab()?.node;
+    if (target?.id) app.offline.pin(target);
+  }, { category: 'Offline', icon: 'download' });
+  cmd('offline.unpin', 'Remove from Offline', (node) => {
+    const target = node || explorer.selectedNodes()[0] || workbench.activeTab()?.node;
+    if (target) app.offline.unpin(target.id);
+  }, { palette: false });
+
+  // --- collections -----------------------------------------------------------
+  // The menu of "where else could I be". Shared by the palette command and the status
+  // bar's collection segment, so both offer the same list.
+  const collectionMenu = () => {
+    const current = explorer.state.collectionId || 'default';
+    const items = (explorer.state.collections || []).map((c) => ({
+      label: c.name || c.id,
+      icon: c.id === current ? 'check' : 'files',
+      run: () => commands.execute('collections.switch', c.id),
+    }));
+    if (explorer.state.canCreateCollection) {
+      if (items.length) items.push({ sep: true });
+      items.push({ label: 'New collection…', icon: 'plus', run: () => commands.execute('collections.create') });
+    }
+    return items;
+  };
+  app.collectionMenu = collectionMenu;
+
+  // `NavigateAction` takes a single collectionId. This passed ('/', cid) — a leftover
+  // from a path+collection signature — so every switch navigated to a collection
+  // literally named "/" and failed to load. It was also unreachable: no caller, and
+  // hidden from the palette.
+  cmd('collections.switch', 'Switch Collection…', (cid) => {
+    if (cid) {
+      go(new NavigateAction(cid));
+      workbench.showHome();
+      return;
+    }
+    // From the palette or a keybinding there is no pointer to anchor a menu to.
+    const items = collectionMenu();
+    if (!items.length) return platform.notifications.info('This drive has one collection.');
+    const w = typeof window === 'undefined' ? 800 : window.innerWidth;
+    workbench.showContextMenu(Math.max(12, Math.round(w / 2) - 110), 120, items);
+  }, { category: 'Collections', icon: 'files' });
+  cmd('collections.create', 'New Collection…', () => {
+    workbench.showDialog({
+      kind: 'collection', title: 'New collection',
+      onSubmit: (record) => {
+        workbench.closeDialog();
+        if (record) go(new CreateCollectionAction(record));
+      },
+    });
+  }, { category: 'Collections', icon: 'files' });
+
+  // --- conversations & notifications -----------------------------------------
+  // The details panel is a view OF a file. With nothing open there is nothing for it to
+  // show, and flipping the flag silently was indistinguishable from a broken command.
+  cmd('workbench.toggleInfoPanel', 'Toggle Details & Conversation', () => {
+    if (!workbench.activeTab()) {
+      platform.notifications.info('Open a file to see its details and conversation.');
+      return;
+    }
+    workbench.toggleInfoPanel();
+  }, { category: 'View', icon: 'info' });
+  cmd('notifications.show', 'Show Notifications', () => app.social.toggleInbox(true), { category: 'View' });
+  cmd('notifications.enablePush', 'Enable Push Notifications', () => app.social.enablePush(), { category: 'Notifications' });
+
+  // --- plugins ---------------------------------------------------------------
+  cmd('plugins.installFromUrl', 'Install Plugin from URL…', () => {
+    workbench.showDialog({
+      kind: 'prompt', title: 'Install plugin from URL', label: 'Plugin package (.zip) URL',
+      placeholder: 'https://example.com/plugin.zip', confirmLabel: 'Fetch',
+      onSubmit: (url) => { workbench.closeDialog(); if (url?.trim()) beginInstallFromUrl(app, url.trim()); },
+    });
+  }, { category: 'Plugins', icon: 'plug' });
+  cmd('plugins.installFromFile', 'Install Plugin from File…', () => {
+    pickZip((file) => file && beginInstallFromFile(app, file));
+  }, { category: 'Plugins', icon: 'plug' });
+}
+
+// --- helpers ----------------------------------------------------------------
+
+// Open a native file picker. The hidden <input> is removed on selection AND on
+// cancel — cancelling fires no `change`, so we also clean up on the next window
+// focus (which the OS dialog returns) to avoid leaking a growing pile of inputs.
+function pick(cb, configure) {
+  const input = document.createElement('input');
+  input.type = 'file';
+  configure(input);
+  input.style.display = 'none';
+  document.body.appendChild(input);
+  const cleanup = () => { input.remove(); window.removeEventListener('focus', onFocus); };
+  const onFocus = () => setTimeout(() => { if (!input.files.length) cleanup(); }, 300);
+  input.addEventListener('change', () => { cb(input.files); cleanup(); }, { once: true });
+  window.addEventListener('focus', onFocus);
+  input.click();
+}
+function pickFiles(cb) {
+  pick((files) => cb(files), (input) => { input.multiple = true; });
+}
+function pickZip(cb) {
+  pick((files) => cb(files[0]), (input) => { input.accept = '.zip,application/zip'; });
+}
+
+function triggerDownload(url, name) {
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = name || '';
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+}
+
+export { pickFiles, triggerDownload };

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

@@ -0,0 +1,49 @@
+// One place that knows how to classify a file by type — extension extraction and a
+// single format table. Previously the ext/mime lists were re-derived (and drifted)
+// across openers.extOf, contributions.matchesSelector, iconForNode, and offline.isTexty;
+// now the icon shown, the "is this text?" decision, and the type label all agree.
+
+/** The extension (".pdf") for a node, lowercased, or '' if none. */
+export function extOf(node) {
+  const name = (node?.name || '').toLowerCase();
+  return name.includes('.') ? name.slice(name.lastIndexOf('.')) : '';
+}
+
+// Category → { mime: prefixes/exact it matches, ext: extensions }. Order matters:
+// kindOf checks these top-down.
+const CATEGORIES = [
+  { kind: 'audio', icon: 'file-audio', mime: ['audio/'], ext: ['.mp3', '.flac', '.wav', '.opus', '.ogg', '.m4a', '.m4b'] },
+  { kind: 'image', icon: 'file-image', mime: ['image/'], ext: ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.avif'] },
+  { kind: 'video', icon: 'file-video', mime: ['video/'], ext: ['.mp4', '.webm', '.mkv', '.mov'] },
+  {
+    kind: 'text', icon: 'file-text', mime: ['text/', 'application/json'],
+    ext: ['.txt', '.md', '.markdown', '.json', '.js', '.mjs', '.ts', '.jsx', '.tsx', '.css', '.html',
+      '.xml', '.yaml', '.yml', '.toml', '.ini', '.log', '.csv', '.py', '.rb', '.go', '.rs', '.sh', '.c', '.h', '.cpp', '.java'],
+  },
+];
+
+function matchesCategory(cat, ext, ct) {
+  if (cat.ext.includes(ext)) return true;
+  // A mime entry ending in '/' is a prefix (audio/), otherwise an exact type.
+  return cat.mime.some((m) => (m.endsWith('/') ? ct.startsWith(m) : ct === m));
+}
+
+/** Classify an item → 'audio'|'image'|'video'|'text'|'file'. */
+export function kindOf(node) {
+  const ext = extOf(node);
+  const ct = node?.contentType || '';
+  for (const cat of CATEGORIES) if (matchesCategory(cat, ext, ct)) return cat.kind;
+  return 'file';
+}
+
+const ICONS = { ...Object.fromEntries(CATEGORIES.map((c) => [c.kind, c.icon])), file: 'file' };
+
+/** The icon name for a node, derived from its kind. */
+export function iconForKind(node) {
+  return ICONS[kindOf(node)] || 'file';
+}
+
+/** Whether a node holds indexable text (drives offline text extraction). */
+export function isTexty(node) {
+  return kindOf(node) === 'text';
+}