@3sln/trove 0.0.2

package/packages/web/src/platform/mediaUrls.js

@@ -0,0 +1,137 @@
+// URLs for things that cannot send a header.
+//
+// An `<img src>`, a `<video src>` and `cache.add()` all fetch without our Authorization
+// header, so on a token-authenticated deployment they 401 and the preview shows a
+// fallback. The server can mint a URL that carries its own grant (see
+// docs/design/signed-urls.md); this is the client half.
+//
+// Two things it exists to get right:
+//
+//   BATCHING — a gallery draws hundreds of tiles at once. Per-object signing is right for
+//   scoping and hopeless as one round trip each, so ids asked for in the same tick go out
+//   together.
+//
+//   EXPIRY — a minted URL dies. Callers get `expiresAt` alongside and are expected to
+//   cycle (see ui/media.js); this service will not hand back a URL that is about to
+//   expire, so a caller that re-asks always gets something usable.
+
+// Re-mint at 80% of the remaining life rather than at the end: a URL handed out at 99%
+// of its life is one the caller will be back for almost immediately.
+const FRESH_ENOUGH = 0.8;
+// Ids asked for within this window go out as one request. A frame is 16ms; this is long
+// enough to collect a grid's first paint and short enough not to be felt.
+const BATCH_MS = 20;
+const MAX_BATCH = 200;
+
+export class MediaUrlService {
+  /** @param {{api: object, settings?: object}} deps */
+  constructor({ api, settings = null }) {
+    this.api = api;
+    this.settings = settings;
+    this.cache = new Map(); // `${op}:${id}` -> { url, expiresAt }
+    this._queue = new Map(); // op -> Map(id -> {resolve, reject})
+    this._timer = null;
+  }
+
+  /**
+   * Whether URLs need minting at all.
+   *
+   * With no bearer token the browser authenticates itself — a cookie or a proxy header
+   * rides along on a subresource load — so the plain route URL works, needs no round
+   * trip, and stays stable enough to be a cache key. Minting there would be a cost with
+   * nothing bought. This is the one branch, and it lives here so callers have none.
+   *
+   * `media.signedUrls` overrides the guess: a deployment behind a proxy that still wants
+   * media fetched straight from S3 sets `always`.
+   */
+  get needed() {
+    const mode = this.settings?.get('media.signedUrls');
+    if (mode === 'always') return true;
+    if (mode === 'never') return false;
+    return !!this.api.token?.();
+  }
+
+  /**
+   * A stable identifier for this node's bytes.
+   *
+   * NOT the URL to fetch — a minted one carries a signature and changes every time. The
+   * offline cache keys on this, because a key that changes per mint means `unpin` stops
+   * matching what `pin` stored and the bytes are never reclaimed.
+   */
+  cacheKey(id) {
+    return this.api.downloadUrl(id);
+  }
+
+  /**
+   * A URL for this node's bytes, good for a while.
+   *
+   * @returns {Promise<{url: string, expiresAt: number}>} `expiresAt` is Infinity when
+   *   nothing was minted, so a caller's cycling logic simply never fires.
+   */
+  async url(id, { op = 'media' } = {}) {
+    if (!this.needed) return { url: this.api.downloadUrl(id, { attachment: op === 'download' }), expiresAt: Infinity };
+    const key = `${op}:${id}`;
+    const hit = this.cache.get(key);
+    if (hit && this.#fresh(hit)) return hit;
+    return this.#enqueue(id, op);
+  }
+
+  /** Forget what we hold for a node, so the next ask re-mints. */
+  invalidate(id, op = 'media') {
+    if (id == null) this.cache.clear();
+    else this.cache.delete(`${op}:${id}`);
+  }
+
+  #fresh(entry) {
+    if (entry.expiresAt === Infinity) return true;
+    const life = entry.expiresAt - entry.mintedAt;
+    return Date.now() < entry.mintedAt + life * FRESH_ENOUGH;
+  }
+
+  #enqueue(id, op) {
+    if (!this._queue.has(op)) this._queue.set(op, new Map());
+    const forOp = this._queue.get(op);
+    const existing = forOp.get(id);
+    if (existing) return existing.promise;
+
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
+    forOp.set(id, { resolve, reject, promise });
+
+    // Flush immediately at the cap rather than waiting out the window — a drive view that
+    // asks for a thousand tiles should not hold the first two hundred hostage.
+    if (forOp.size >= MAX_BATCH) this.#flush();
+    else if (!this._timer) this._timer = setTimeout(() => this.#flush(), BATCH_MS);
+    return promise;
+  }
+
+  async #flush() {
+    clearTimeout(this._timer);
+    this._timer = null;
+    const queue = this._queue;
+    this._queue = new Map();
+
+    for (const [op, waiting] of queue) {
+      const ids = [...waiting.keys()];
+      try {
+        const res = await this.api.mintUrls(ids, op);
+        const now = Date.now();
+        for (const [id, w] of waiting) {
+          const got = res.urls?.[id];
+          if (got) {
+            const entry = { url: got.url, expiresAt: got.expiresAt, mintedAt: now };
+            this.cache.set(`${op}:${id}`, entry);
+            w.resolve(entry);
+          } else {
+            // Absent from the answer means this caller may not read it. A rejection, not
+            // a broken URL — the tile shows its icon rather than a broken-image glyph.
+            w.reject(new Error(res.failed?.[id] === 'not_found' ? 'That file is gone' : 'You cannot open that file'));
+          }
+        }
+      } catch (err) {
+        for (const w of waiting.values()) w.reject(err);
+      }
+    }
+  }
+}

package/packages/web/src/platform/navigation.js

@@ -0,0 +1,131 @@
+// NavigationService — the main panel STACK and its browser-history mirror. The base
+// of the stack is the launcher (search); opening a file pushes a viewer panel; back
+// pops. The stack is mirrored into window.history (pushState/popState) so the browser
+// back/forward buttons navigate it. Also owns the "recent files" list. Extracted from
+// WorkbenchService; the workbench coordinates the couplings it can't own (setting the
+// activity to 'home' and closing the modal search when a file opens).
+
+import { cell } from '../runtime.js';
+
+const RECENTS_KEY = 'trove.recents';
+const RECENTS_MAX = 12;
+
+export class NavigationService {
+  constructor(context) {
+    this.context = context;
+    this.state = {
+      stack: [{ kind: 'search' }], // [{kind:'search'}, {kind:'file', id, node, openerId}, …]
+      activeTabId: null, // top file panel id (or null)
+      activeFile: null, // top file panel node (or null)
+      recents: loadRecents(),
+    };
+    this.cell = cell(this.state);
+  }
+
+  observe() {
+    return this.cell;
+  }
+  #set(patch) {
+    this.state = { ...this.state, ...patch };
+    this.cell.setValue(this.state);
+  }
+
+  #top() {
+    return this.state.stack[this.state.stack.length - 1];
+  }
+  /** The active file panel (top of the stack, if it's a file). */
+  activeTab() {
+    const t = this.#top();
+    return t?.kind === 'file' ? t : null; // panel kind, not node kind
+  }
+
+  #applyStack(stack, { history = true } = {}) {
+    const top = stack[stack.length - 1];
+    const file = top && top.kind === 'file' ? top : null;
+    this.#set({ stack, activeTabId: file ? file.id : null, activeFile: file ? file.node : null });
+    this.context.setMany({ 'editor.open': !!file, 'editor.openerId': file?.openerId || '', 'editor.contentType': file?.node.contentType || '' });
+    if (history) this.#pushHistory();
+  }
+
+  /** Reset to the base launcher (used by showHome). */
+  reset() {
+    this.#applyStack([{ kind: 'search' }]);
+  }
+
+  /**
+   * Open a file into the viewer stack. `reset` (used by the modal search) starts a
+   * fresh stack (base search + this file). Opening a file already in the stack
+   * jumps back to it; otherwise it's pushed on top.
+   */
+  openFile(node, openerId, { reset = false } = {}) {
+    const panel = { kind: 'file', id: node.id, node, openerId };
+    let stack;
+    if (reset) {
+      stack = [{ kind: 'search' }, panel];
+    } else {
+      const at = this.state.stack.findIndex((p) => p.kind === 'file' && p.id === node.id);
+      if (at >= 0) {
+        // Already open — jump back to it, but adopt the (possibly new) opener so
+        // reopening with a different one actually switches the viewer.
+        stack = this.state.stack.slice(0, at + 1);
+        stack[at] = panel;
+      } else {
+        stack = [...this.state.stack, panel];
+      }
+    }
+    this.#pushRecent(node);
+    this.#applyStack(stack);
+  }
+  back() {
+    if (this.state.stack.length <= 1) return;
+    try { history.back(); } catch { this.pop(); }
+  }
+  pop() {
+    if (this.state.stack.length > 1) this.#applyStack(this.state.stack.slice(0, -1), { history: false });
+  }
+  closeTab(id) {
+    const stack = this.state.stack.filter((p) => !(p.kind === 'file' && p.id === id));
+    this.#applyStack(stack.length ? stack : [{ kind: 'search' }], { history: false });
+  }
+  updateTabNode(node) {
+    const stack = this.state.stack.map((p) => (p.kind === 'file' && p.id === node.id ? { ...p, node } : p));
+    this.#applyStack(stack, { history: false });
+  }
+
+  // --- history sync ----------------------------------------------------------
+  #pushHistory(replace = false) {
+    const top = this.#top();
+    const n = top?.node;
+    const entry = {
+      troveDepth: this.state.stack.length,
+      node: n ? { id: n.id, name: n.name, contentType: n.contentType, collectionId: n.collectionId } : null,
+      openerId: top?.openerId || null,
+    };
+    try { (replace ? history.replaceState : history.pushState).call(history, entry, ''); } catch { /* no history API */ }
+  }
+  /** Handle a browser back/forward: sync the stack depth (re-open on forward). */
+  onPopState(e) {
+    const s = e?.state || {};
+    const depth = s.troveDepth || 1;
+    if (depth <= this.state.stack.length) {
+      this.#applyStack(this.state.stack.slice(0, depth), { history: false });
+    } else if (s.node) {
+      this.#applyStack([...this.state.stack, { kind: 'file', id: s.node.id, node: s.node, openerId: s.openerId }], { history: false });
+    }
+  }
+
+  #pushRecent(node) {
+    if (!node) return;
+    const entry = { id: node.id, name: node.name, contentType: node.contentType || '', collectionId: node.collectionId };
+    const recents = [entry, ...this.state.recents.filter((r) => r.id !== node.id)].slice(0, RECENTS_MAX);
+    this.#set({ recents });
+    saveRecents(recents);
+  }
+}
+
+function loadRecents() {
+  try { return JSON.parse(localStorage.getItem(RECENTS_KEY)) || []; } catch { return []; }
+}
+function saveRecents(recents) {
+  try { localStorage.setItem(RECENTS_KEY, JSON.stringify(recents)); } catch { /* private mode / no storage */ }
+}

package/packages/web/src/platform/notifications.js

@@ -0,0 +1,50 @@
+// NotificationService — transient toasts + a small log. Everything user-facing
+// that fails routes here so problems are never silent. Reactive: the status/UI
+// watches `observe()`.
+
+import { cell } from '../runtime.js';
+
+let seq = 0;
+
+export class NotificationService {
+  constructor() {
+    this.items = [];
+    this.cell = cell([]);
+  }
+  observe() {
+    return this.cell;
+  }
+  #push(level, message, opts = {}) {
+    const item = {
+      id: ++seq, level, message,
+      actions: opts.actions || null,
+      createdAt: Date.now(),
+      sticky: opts.sticky || level === 'error',
+    };
+    this.items = [...this.items, item];
+    this.cell.setValue(this.items);
+    if (!item.sticky) setTimeout(() => this.dismiss(item.id), opts.timeout ?? 4000);
+    return item.id;
+  }
+  info(m, o) {
+    return this.#push('info', m, o);
+  }
+  success(m, o) {
+    return this.#push('success', m, o);
+  }
+  warn(m, o) {
+    return this.#push('warn', m, o);
+  }
+  error(m, o) {
+    return this.#push('error', m, o);
+  }
+  /** Update a notification in place (e.g. a progress message). */
+  update(id, patch) {
+    this.items = this.items.map((i) => (i.id === id ? { ...i, ...patch } : i));
+    this.cell.setValue(this.items);
+  }
+  dismiss(id) {
+    this.items = this.items.filter((i) => i.id !== id);
+    this.cell.setValue(this.items);
+  }
+}

package/packages/web/src/platform/overlay.js

@@ -0,0 +1,81 @@
+// OverlayService — the shell's transient overlays: the command palette, modal
+// dialogs, the right-click context menu, and the plugin popup panel. Extracted from
+// WorkbenchService (which kept ~10 concerns); these four are independent of the panel
+// stack, so they own their own state + subject. The workbench holds one and delegates,
+// coordinating only the Esc/close-topmost ordering (which also spans the stack).
+
+import { cell } from '../runtime.js';
+
+export class OverlayService {
+  constructor(context) {
+    this.context = context;
+    this.state = {
+      palette: null, // { mode: 'commands'|'files', query, index } when open
+      dialog: null,
+      contextMenu: null,
+      pluginPanel: null,
+    };
+    this.cell = cell(this.state);
+  }
+
+  observe() {
+    return this.cell;
+  }
+  #set(patch) {
+    this.state = { ...this.state, ...patch };
+    this.cell.setValue(this.state);
+  }
+
+  // --- command palette -------------------------------------------------------
+  openPalette(mode = 'commands', query = '') {
+    this.#set({ palette: { mode, query, index: 0 } });
+    this.context.set('palette.open', true);
+  }
+  setPaletteQuery(query) {
+    if (this.state.palette) this.#set({ palette: { ...this.state.palette, query, index: 0 } });
+  }
+  movePalette(delta, count) {
+    if (!this.state.palette || !count) return;
+    this.#set({ palette: { ...this.state.palette, index: wrapIndex(this.state.palette.index, delta, count) } });
+  }
+  setPaletteIndex(index) {
+    if (this.state.palette) this.#set({ palette: { ...this.state.palette, index } });
+  }
+  closePalette() {
+    this.#set({ palette: null });
+    this.context.set('palette.open', false);
+  }
+
+  // --- dialog ----------------------------------------------------------------
+  showDialog(dialog) {
+    this.#set({ dialog });
+  }
+  /** Merge a patch into the open dialog's state (reactive dialogs, e.g. the chooser). */
+  updateDialog(patch) {
+    if (this.state.dialog) this.#set({ dialog: { ...this.state.dialog, ...patch } });
+  }
+  closeDialog() {
+    this.#set({ dialog: null });
+  }
+
+  // --- context menu ----------------------------------------------------------
+  showContextMenu(x, y, items) {
+    this.#set({ contextMenu: { x, y, items } });
+  }
+  closeContextMenu() {
+    this.#set({ contextMenu: null });
+  }
+
+  // --- plugin popup panel ----------------------------------------------------
+  openPluginPanel(pluginId) {
+    this.#set({ pluginPanel: pluginId });
+  }
+  closePluginPanel() {
+    this.#set({ pluginPanel: null });
+  }
+}
+
+/** Wrap a list cursor by `delta` within `[0, count)` (shared by the palette + launcher). */
+export function wrapIndex(index, delta, count) {
+  return (index + delta + count) % count;
+}

package/packages/web/src/platform/pluginClientDb.js

@@ -0,0 +1,132 @@
+// Client-side plugin storage: an on-device SQLite database per scope, run in the
+// HOST with sql.js (wasm) and persisted to IndexedDB. The sandboxed iframe can't
+// touch IndexedDB (opaque origin), so — like everything else — the host holds the
+// store and the plugin reaches it over RPC. It exposes the SAME async
+// SqliteDatabase surface as the server side, so ctx.storage.*.client mirrors
+// .server. Lazy: the wasm only loads the first time a plugin uses client storage.
+
+let sqlPromise = null;
+function loadSql() {
+  // locateFile points at the wasm we serve at the app root (build copies it; dev &
+  // test serve it via middleware). Only fetched on first use. On failure we clear
+  // the cached promise so a later attempt can retry rather than wedging forever.
+  if (!sqlPromise) {
+    sqlPromise = import('sql.js')
+      .then((m) => (m.default || m)({ locateFile: () => '/sql-wasm.wasm' }))
+      .catch((err) => { sqlPromise = null; throw err; });
+  }
+  return sqlPromise;
+}
+
+// --- IndexedDB blob persistence (host origin) --------------------------------
+
+const IDB = 'trove-plugin-clientdb';
+const STORE = 'dbs';
+
+function openIdb() {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(IDB, 1);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(STORE)) db.createObjectStore(STORE);
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+function idbOp(mode, fn) {
+  return openIdb().then((db) => new Promise((resolve, reject) => {
+    const t = db.transaction(STORE, mode);
+    let out;
+    Promise.resolve(fn(t.objectStore(STORE))).then((r) => (out = r));
+    t.oncomplete = () => { db.close(); resolve(out); };
+    t.onerror = () => { db.close(); reject(t.error); };
+  }));
+}
+const reqP = (r) => new Promise((res, rej) => { r.onsuccess = () => res(r.result); r.onerror = () => rej(r.error); });
+const loadBytes = (key) => idbOp('readonly', (s) => reqP(s.get(key)));
+const saveBytes = (key, bytes) => idbOp('readwrite', (s) => s.put(bytes, key));
+const dropBytes = (key) => idbOp('readwrite', (s) => s.delete(key));
+
+// --- a single scoped database (conforms to SqliteDatabase) -------------------
+
+class ClientDatabase {
+  constructor(key, db) {
+    this.key = key;
+    this.db = db;
+    this._saveTimer = null;
+  }
+  // Debounce persistence: export the whole (small, per-scope) db to IndexedDB
+  // shortly after the last write.
+  //
+  // The write already returned `{ok:true}` to the plugin by the time this runs, so a
+  // failure here is data the plugin believes it saved and hasn't. Nothing can be
+  // returned to it any more — but it must at least be visible, not swallowed.
+  #dirty() {
+    clearTimeout(this._saveTimer);
+    this._saveTimer = setTimeout(() => {
+      this.flush().catch((err) => {
+        console.error(`persisting plugin storage "${this.key}" failed`, err);
+        this.onError?.(err, this.key);
+      });
+    }, 150);
+  }
+  async flush() {
+    clearTimeout(this._saveTimer);
+    this._saveTimer = null;
+    await saveBytes(this.key, this.db.export());
+  }
+  async exec(sql) { this.db.exec(sql); this.#dirty(); return { ok: true }; }
+  async run(sql, ...params) { this.db.run(sql, params); this.#dirty(); return { ok: true }; }
+  async get(sql, ...params) {
+    const stmt = this.db.prepare(sql);
+    try { stmt.bind(params); return stmt.step() ? stmt.getAsObject() : null; }
+    finally { stmt.free(); }
+  }
+  async all(sql, ...params) {
+    const stmt = this.db.prepare(sql);
+    const out = [];
+    try { stmt.bind(params); while (stmt.step()) out.push(stmt.getAsObject()); }
+    finally { stmt.free(); }
+    return out;
+  }
+  async batch(statements = []) {
+    this.db.run('BEGIN');
+    try {
+      for (const { sql, params = [] } of statements) this.db.run(sql, params);
+      this.db.run('COMMIT');
+    } catch (err) {
+      try { this.db.run('ROLLBACK'); } catch { /* already rolled back */ }
+      throw err;
+    }
+    this.#dirty();
+    return { ok: true };
+  }
+  close() { clearTimeout(this._saveTimer); this.db.close(); }
+}
+
+// --- the pool ----------------------------------------------------------------
+
+export class ClientSqlProvider {
+  constructor({ onError } = {}) { this._pool = new Map(); this.onError = onError || null; }
+
+  async obtain(key) {
+    let db = this._pool.get(key);
+    if (!db) {
+      const SQL = await loadSql();
+      const bytes = await loadBytes(key);
+      db = new ClientDatabase(key, new SQL.Database(bytes || undefined));
+      db.onError = this.onError;
+      this._pool.set(key, db);
+    }
+    return db;
+  }
+
+  /** Drop a scope's database. Throws if the bytes can't be deleted — the caller
+   *  (uninstall) reports leftover on-device data rather than claiming a clean wipe. */
+  async drop(key) {
+    const db = this._pool.get(key);
+    if (db) { db.close(); this._pool.delete(key); }
+    await dropBytes(key);
+  }
+}

package/packages/web/src/platform/pluginDock.js

@@ -0,0 +1,141 @@
+// FrameDock — where a plugin frame's iframe is *shown*, and the floating dock (PiP).
+//
+// A frame's iframe is created once and stays a child of <body> for its life — we
+// NEVER re-parent it, because moving an <iframe> in the DOM reloads its document (per
+// the HTML spec) and would kill the running plugin + its MessagePort. To show a frame
+// "inside" a panel/viewer/dock we float it as a position:fixed overlay whose inset
+// tracks the target element's box (`place`), recomputed on intersection/resize/scroll
+// rather than every animation frame — the viewer area only moves on layout changes,
+// so this stays idle when nothing shifts.
+//
+// The dock is the single floating mini-player a viewer becomes when you navigate away
+// (video → PiP, audio → mini transport), if the viewer opted in via `dock.enable`.
+
+export class FrameDock {
+  /**
+   * @param {object} deps
+   * @param {(frame:object)=>void} deps.destroyFrame  tear a frame down for good
+   * @param {(node:object, openerId:string)=>void} deps.openFile  reopen the docked file
+   * @param {()=>void} [deps.onChange]  notify listeners (the dock affects plugin state)
+   */
+  constructor({ destroyFrame, openFile, onChange } = {}) {
+    this.destroyFrame = destroyFrame;
+    this.openFile = openFile;
+    this.onChange = onChange || (() => {});
+    this.docked = null; // the frame currently in the dock
+    this.el = null; // the dock's DOM host (created lazily)
+  }
+
+  // --- placement -------------------------------------------------------------
+
+  /** Float `frame`'s iframe over `targetEl` and keep its inset aligned. */
+  place(frame, targetEl, z, radius = '') {
+    this.stopPlace(frame);
+    const f = frame.iframe;
+    f.style.cssText = `position:fixed;border:0;visibility:visible;display:block;background:transparent;z-index:${z};margin:0;padding:0;border-radius:${radius};`;
+    const sync = () => {
+      const r = targetEl.getBoundingClientRect();
+      const shown = r.width > 0 && r.height > 0 && document.contains(targetEl);
+      f.style.left = `${r.left}px`;
+      f.style.top = `${r.top}px`;
+      f.style.width = `${r.width}px`;
+      f.style.height = `${r.height}px`;
+      f.style.visibility = shown ? 'visible' : 'hidden';
+    };
+    sync();
+    const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(sync) : null;
+    ro?.observe(targetEl);
+    if (document.body) ro?.observe(document.body);
+    const io = typeof IntersectionObserver !== 'undefined' ? new IntersectionObserver(sync, { threshold: [0, 1] }) : null;
+    io?.observe(targetEl);
+    window.addEventListener('scroll', sync, true);
+    window.addEventListener('resize', sync);
+    frame.place = {
+      target: targetEl,
+      stop: () => {
+        ro?.disconnect();
+        io?.disconnect();
+        window.removeEventListener('scroll', sync, true);
+        window.removeEventListener('resize', sync);
+      },
+    };
+  }
+
+  stopPlace(frame) {
+    if (frame.place) { frame.place.stop(); frame.place = null; }
+  }
+
+  /** Stop tracking and park the iframe offscreen (kept alive, just not shown). */
+  hide(frame) {
+    this.stopPlace(frame);
+    frame.iframe.style.cssText = 'position:fixed;left:0;top:0;width:0;height:0;border:0;visibility:hidden;';
+  }
+
+  /** Frame teardown hook: stop placement and drop the dock if this frame was in it. */
+  releaseFrame(frame) {
+    this.stopPlace(frame);
+    if (this.docked === frame) { this.docked = null; this.#hideEl(); }
+  }
+
+  // --- dock ------------------------------------------------------------------
+
+  #hideEl() {
+    if (this.el) this.el.style.display = 'none';
+  }
+
+  /** Float a viewer frame as the single floating dock, sized by its declared minimums. */
+  dock(frame) {
+    if (this.docked && this.docked !== frame) this.closeDock(this.docked);
+    const min = frame.dock?.minSize || { width: 300, height: 90 };
+    const el = this.#dockEl();
+    el.style.width = `${clampDim(min.width, 200, 480)}px`;
+    el.style.height = `${clampDim(min.height, 56, 360) + 26}px`; // + header
+    el.querySelector('.vd-title').textContent = frame.node?.name || (frame.record.manifest.displayName || frame.record.manifest.name);
+    el.style.display = 'flex';
+    // Round the frame's bottom corners to match the dock's rounded body.
+    this.place(frame, el.querySelector('.vd-body'), 61, '0 0 11px 11px');
+    this.docked = frame;
+    frame.channel?.emit('dock:state', { docked: true });
+    this.onChange();
+  }
+
+  /** Un-dock without destroying — used when a docked frame is re-adopted into a viewer. */
+  undock(frame) {
+    this.#hideEl();
+    if (this.docked === frame) this.docked = null;
+    frame.channel?.emit('dock:state', { docked: false });
+  }
+
+  /** Dismiss the dock: the user closed it, or the viewer disabled docking. The frame
+   *  is done, so tear it down. */
+  closeDock(frame) {
+    this.#hideEl();
+    if (this.docked === frame) this.docked = null;
+    frame.channel?.emit('dock:state', { docked: false, closed: true });
+    this.destroyFrame?.(frame);
+    this.onChange();
+  }
+
+  #dockEl() {
+    if (this.el) return this.el;
+    const el = document.createElement('div');
+    el.className = 'viewer-dock';
+    el.innerHTML = '<div class="vd-bar"><span class="vd-title"></span><button class="vd-expand" title="Reopen">↗</button><button class="vd-close" title="Close">✕</button></div><div class="vd-body"></div>';
+    el.querySelector('.vd-expand').addEventListener('click', () => {
+      const frame = this.docked;
+      if (frame?.node) this.openFile?.(frame.node, frame.openerId);
+    });
+    el.querySelector('.vd-close').addEventListener('click', () => {
+      if (this.docked) this.closeDock(this.docked);
+    });
+    document.body.appendChild(el);
+    this.el = el;
+    return el;
+  }
+}
+
+// Clamp a viewer-declared dock dimension into a sane host range (defaulting to the
+// low bound when the viewer gives nothing).
+function clampDim(v, lo, hi) {
+  return Math.max(lo, Math.min(hi, v || lo));
+}