@3sln/trove 0.0.17 → 0.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3sln/trove",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "type": "module",
   "description": "Trove — a self-hostable, plugin-extensible Google Drive. Semantic search, pluggable storage (S3 / filesystem / NAS), and a VS Code-style contribution system with sandboxed plugins.",
   "repository": {

package/packages/core/src/plugins/runtime.js

@@ -80,10 +80,7 @@ export class InProcessIndexerRuntime extends IndexerRuntime {
     if (!p) {
       const code = spec.files?.[spec.entry];
       if (!code) return Promise.reject(TroveError.invalid(`Indexer "${spec.id}" is missing its entry "${spec.entry}"`));
-      // base64 data URL — percent-encoded JS confuses some runtimes' data: loader
-      // (they fall back to a text module), whereas base64 imports reliably.
-      const url = 'data:text/javascript;base64,' + bytesToBase64(code);
-      p = import(/* @vite-ignore */ url).then((mod) => {
+      p = importModule(code).then((mod) => {
         const fn = mod.default || mod.index;
         if (typeof fn !== 'function') throw TroveError.invalid(`Indexer "${spec.id}" has no default/index export`);
         return fn;
@@ -103,7 +100,14 @@ export class InProcessIndexerRuntime extends IndexerRuntime {
    * and will not change while the process lives.
    */
   async probe() {
-    this._probe ||= import(/* @vite-ignore */ 'data:text/javascript;base64,' + btoa('export default 1'))
+    // A REALISTICALLY SIZED module, not `export default 1`. The tiny version answered a
+    // question nobody was asking: Bun imports a small data: URL happily and refuses one
+    // over ~1.5 KB with ENAMETOOLONG, so a 12-byte probe passed and every real indexer —
+    // the audiobook one is 34 KB — failed per file. That is the same silent shape this
+    // probe exists to prevent, so it now loads something the size of a real entry.
+    const padding = 'x'.repeat(PROBE_BYTES);
+    const code = new TextEncoder().encode(`export default 1; //${padding}`);
+    this._probe ||= importModule(code)
       .then(() => ({ ok: true }))
       .catch((err) => ({
         ok: false,
@@ -124,6 +128,58 @@ export class InProcessIndexerRuntime extends IndexerRuntime {
   }
 }
 
+/**
+ * How big a module the probe pretends to load. Larger than any plausible bundled indexer
+ * entry (the audiobook one is 34 KB), because the failure being detected is a SIZE limit
+ * and a probe under it proves nothing.
+ */
+export const PROBE_BYTES = 64 * 1024;
+
+/**
+ * Import a module from bytes, on whichever runtime this is.
+ *
+ * The two schemes are exactly complementary, which is why both are here:
+ *
+ *   data:   Node takes it at any size (2.6 MB tested). Bun refuses over ~1.5 KB with
+ *           `NameTooLong` — it resolves the URL as a path, so ENAMETOOLONG.
+ *   blob:   Bun takes it at any size. Node's ESM loader supports exactly `file:`, `data:`
+ *           and `node:`, so it throws ERR_UNSUPPORTED_ESM_URL_SCHEME.
+ *
+ * data: first because it needs no cleanup and the same bytes give the same URL, so the
+ * engine's module cache makes a re-import free. An object URL is a live registry entry
+ * that leaks until revoked, which is the only reason it is the fallback rather than the
+ * default.
+ *
+ * Neither works on workerd. That is what `WorkerLoaderIndexerRuntime` is for, and what
+ * `probe()` reports when it is missing.
+ */
+async function importModule(code) {
+  // base64 rather than percent-encoded: some runtimes' data: loader treats
+  // percent-encoded JS as a text module instead of code.
+  try {
+    return await import(/* @vite-ignore */ 'data:text/javascript;base64,' + bytesToBase64(code));
+  } catch (dataErr) {
+    if (typeof URL.createObjectURL !== 'function' || typeof Blob !== 'function') throw dataErr;
+    let url;
+    try {
+      url = URL.createObjectURL(new Blob([code], { type: 'text/javascript' }));
+    } catch {
+      throw dataErr; // report the data: failure — it is the one that describes the runtime
+    }
+    try {
+      return await import(/* @vite-ignore */ url);
+    } catch {
+      throw dataErr;
+    } finally {
+      // Safe here and only here: an ESM module is fully instantiated by the time the
+      // import resolves, and `#load` caches the promise so this URL is never resolved
+      // again. Without it every indexer would pin its own source in memory for the life
+      // of the process.
+      URL.revokeObjectURL?.(url);
+    }
+  }
+}
+
 function bytesToBase64(bytes) {
   let bin = '';
   const CHUNK = 0x8000;

package/packages/core/src/sidecar/document.js

@@ -22,7 +22,7 @@
 export const SIDECAR_VERSION = 1;
 
 export function emptyDoc(nodeId) {
-  return { v: SIDECAR_VERSION, nodeId, clock: 0, tags: {}, comments: {}, subscribers: {} };
+  return { v: SIDECAR_VERSION, nodeId, clock: 0, tags: {}, comments: {}, subscribers: {}, data: {} };
 }
 
 // A stamp orders and tie-breaks a write. Higher clock wins; equal clock → higher
@@ -101,6 +101,53 @@ export function removeTag(doc, name, { actor, at } = {}) {
   if (newer(s, cur)) doc.tags[name] = { present: false, value: cur?.value, ...s };
 }
 
+/**
+ * A plugin's own key/value data for this item.
+ *
+ * SCOPED, and the scope is not the plugin's to choose: the caller passes the plugin id it
+ * has already authenticated, exactly as `/api/index/:indexerId` does for contributions.
+ * Two plugins writing `position` to the same book are writing two different things, and a
+ * flat namespace would make one silently overwrite the other.
+ *
+ * Same LWW register as a tag, for the same reason: a listener finishes a chapter on their
+ * phone and opens the book on a laptop that has been offline for a day. Both wrote. The
+ * later write wins, and `newer` breaks a tie the same total, deterministic way it does
+ * everywhere else in this document — so both devices converge on the same answer without
+ * either having to be authoritative.
+ */
+export function setData(doc, scope, key, value, { actor, at } = {}) {
+  if (!scope || !key) return null;
+  doc.data ||= {};
+  doc.data[scope] ||= {};
+  const s = stamp(doc, actor, at);
+  const cur = doc.data[scope][key];
+  if (newer(s, cur)) doc.data[scope][key] = { present: true, value, ...s };
+  return doc.data[scope][key];
+}
+
+/**
+ * Forget one key. A TOMBSTONE rather than a delete, because a delete that removed the
+ * entry would be silently undone by any replica that still had the old value — the
+ * absence has to be a fact with a stamp, or it cannot win a merge.
+ */
+export function removeData(doc, scope, key, { actor, at } = {}) {
+  if (!scope || !key) return;
+  doc.data ||= {};
+  doc.data[scope] ||= {};
+  const s = stamp(doc, actor, at);
+  const cur = doc.data[scope][key];
+  if (newer(s, cur)) doc.data[scope][key] = { present: false, value: cur?.value, ...s };
+}
+
+/** What a plugin sees of its own scope: present keys, values only. */
+export function dataOf(doc, scope) {
+  const out = {};
+  for (const [key, cell] of Object.entries(doc?.data?.[scope] || {})) {
+    if (cell?.present) out[key] = cell.value;
+  }
+  return out;
+}
+
 export function subscribe(doc, userId, { muted = false, actor, at } = {}) {
   if (!userId) return;
   const s = stamp(doc, actor ?? userId, at);
@@ -119,7 +166,7 @@ export function unsubscribe(doc, userId, { actor, at } = {}) {
 export function mergeDoc(a, b) {
   if (!a) return structuredCloneSafe(b);
   if (!b) return structuredCloneSafe(a);
-  const out = { v: SIDECAR_VERSION, nodeId: a.nodeId || b.nodeId, clock: Math.max(a.clock || 0, b.clock || 0), tags: {}, comments: {}, subscribers: {} };
+  const out = { v: SIDECAR_VERSION, nodeId: a.nodeId || b.nodeId, clock: Math.max(a.clock || 0, b.clock || 0), tags: {}, comments: {}, subscribers: {}, data: {} };
 
   for (const key of union(a.tags, b.tags)) out.tags[key] = pick(a.tags[key], b.tags[key]);
   // Documents written before the register was removed still carry one, and a merge that
@@ -131,6 +178,17 @@ export function mergeDoc(a, b) {
   }
   for (const key of union(a.subscribers, b.subscribers)) out.subscribers[key] = pick(a.subscribers[key], b.subscribers[key]);
 
+  // Data is a map of maps — scope, then key — so it merges a level deeper than the rest.
+  // Merged per KEY rather than per scope: two devices that each wrote a different key in
+  // the same scope must end up with both, and picking a whole scope would drop one.
+  out.data = {};
+  for (const scope of union(a.data, b.data)) {
+    out.data[scope] = {};
+    for (const key of union(a.data?.[scope], b.data?.[scope])) {
+      out.data[scope][key] = pick(a.data?.[scope]?.[key], b.data?.[scope]?.[key]);
+    }
+  }
+
   for (const id of union(a.comments, b.comments)) {
     out.comments[id] = mergeComment(a.comments[id], b.comments[id]);
   }

package/packages/core/src/sidecar/index.js

@@ -8,7 +8,7 @@ import { SidecarStore } from './store.js';
 import { SidecarManager } from './manager.js';
 import {
   addComment, editComment, deleteComment, react, setTag, removeTag,
-  subscribe, unsubscribe, viewDoc, extractMentions,
+  subscribe, unsubscribe, viewDoc, extractMentions, setData, removeData, dataOf,
 } from './document.js';
 import { newId } from '../util.js';
 import { TroveError } from '../errors.js';
@@ -115,6 +115,33 @@ export class SidecarService {
     return this.view(nodeId);
   }
 
+  // --- per-plugin item data --------------------------------------------------
+  //
+  // A viewer's state about an ITEM, which is neither a contribution nor a setting. A
+  // contribution is derived from the file and is rewritten whenever it is re-indexed; a
+  // setting is per-device, and a listening position that does not follow you to your phone
+  // is the one people notice missing. This is the third thing, and the sidecar is where it
+  // belongs because the sidecar is already a per-item CRDT.
+  //
+  // `scope` is passed in by the caller and is NOT the plugin's to choose — the route
+  // derives it from the plugin it has already authenticated, the same way
+  // `/api/index/:indexerId` derives a contributor namespace.
+
+  async setData(nodeId, scope, key, value, principal) {
+    await this.manager.mutate(nodeId, (doc) => setData(doc, scope, key, value, { actor: principal?.id }));
+    return { ok: true };
+  }
+
+  async removeData(nodeId, scope, key, principal) {
+    await this.manager.mutate(nodeId, (doc) => removeData(doc, scope, key, { actor: principal?.id }));
+    return { ok: true };
+  }
+
+  /** One scope's present keys. Never another scope's — see `dataOf`. */
+  async data(nodeId, scope) {
+    return dataOf(await this.manager.get(nodeId), scope);
+  }
+
   // --- subscriptions ---------------------------------------------------------
 
   async subscribe(nodeId, principal, muted = false) {

package/packages/plugin-sdk/src/browser.js

@@ -14,12 +14,140 @@
   // protocol.js — this file is injected as text and cannot import it, so
   // protocol.test.js asserts the two stay in step.
   const SDK_PROTOCOL_VERSION = '1.0';
+
+  // --- events -----------------------------------------------------------------
+  //
+  // Every hook here used to be one assignment — `onDeactivate = fn`, `onDock = fn`,
+  // `mediaHandlers[action] = fn`. Register twice and the first silently vanished, with
+  // nothing to report it: the symptom is a timer or an object URL outliving its viewer,
+  // noticed much later as a leak. The audiobook player was losing one of two teardowns
+  // exactly that way.
+  //
+  // So the SDK's nodes are EventTargets and handlers are listeners. Registrations
+  // accumulate, removal is `removeEventListener`, and a plugin can compose without
+  // knowing what else is listening.
+  //
+  // Inlined rather than imported because this file is injected as TEXT into a sandboxed
+  // frame and has no module loader — see the header.
+  //
+  // Two things a plain CustomEvent cannot express, both needed:
+  //
+  //   waitUntil(p)    The host awaits some of these. `opener:open` must not resolve until
+  //                   the viewer has drawn, or "Opening…" is hidden over a blank frame.
+  //   respondWith(v)  A command has a return value that crosses back over the port. First
+  //                   answer wins; a second is a bug in the plugin, not something to pick
+  //                   between silently.
+  class TroveEvent extends Event {
+    constructor(type, detail) {
+      super(type, { cancelable: true });
+      this.detail = detail;
+      this._waits = [];
+      this._answered = false;
+      this._answer = undefined;
+    }
+    waitUntil(p) { this._waits.push(Promise.resolve(p)); }
+    respondWith(value) {
+      if (this._answered) return;
+      this._answered = true;
+      this._answer = value;
+      if (value && typeof value.then === 'function') this._waits.push(Promise.resolve(value).then((v) => { this._answer = v; }));
+    }
+  }
+
+  /**
+   * Dispatch, then wait for every `waitUntil`, then answer.
+   *
+   * A listener that throws is reported and does not stop the others — dispatch is where
+   * resources are released, and one bad handler must not strand the rest.
+   */
+  async function fire(target, type, detail) {
+    const ev = new TroveEvent(type, detail);
+    target.dispatchEvent(ev);
+    for (const r of await Promise.allSettled(ev._waits)) {
+      if (r.status === 'rejected') console.error('[trove] a "' + type + '" handler failed', r.reason);
+    }
+    return ev._answer;
+  }
+
+  /**
+   * An EventTarget that knows what is listening.
+   *
+   * The host needs that: it is how the manifest reports which commands a plugin actually
+   * implements, and how media claims an OS control on the first listener and releases it
+   * on the last.
+   */
+  function makeTarget(onFirst, onLast) {
+    const counts = new Map();
+    const target = new EventTarget();
+    const add = target.addEventListener.bind(target);
+    const remove = target.removeEventListener.bind(target);
+    target.types = () => [...counts.entries()].filter(([, n]) => n > 0).map(([t]) => t);
+    target.listening = (type) => (counts.get(type) || 0) > 0;
+    target.addEventListener = (type, fn, opts) => {
+      const n = (counts.get(type) || 0) + 1;
+      counts.set(type, n);
+      if (n === 1 && onFirst) onFirst(type);
+      return add(type, fn, opts);
+    };
+    target.removeEventListener = (type, fn, opts) => {
+      const n = Math.max(0, (counts.get(type) || 0) - 1);
+      counts.set(type, n);
+      if (n === 0 && onLast) onLast(type);
+      return remove(type, fn, opts);
+    };
+    return target;
+  }
+
+  /**
+   * `onThing(fn)` written over `addEventListener`.
+   *
+   * Kept because it reads well for the common case and is what every existing plugin
+   * says. What changed is that it no longer REPLACES: two calls mean two listeners, and
+   * it returns a disposer. A handler that returns a promise keeps the host waiting; one
+   * that returns a value answers.
+   */
+  function hook(target, type, args = (e) => [e.detail]) {
+    return (fn) => {
+      if (typeof fn !== 'function') return () => {};
+      const listener = (e) => {
+        // GUARDED here rather than relying on the host's EventTarget to isolate a throw.
+        // Browsers do report an uncaught listener error and carry on, but that is not
+        // uniform — Bun stops dispatch — and teardown is the one place where "the rest
+        // still ran" has to be a guarantee rather than a hope.
+        let out;
+        try {
+          out = fn(...args(e));
+        } catch (err) {
+          console.error('[trove] a "' + e.type + '" handler threw', err);
+          return;
+        }
+        if (out && typeof out.then === 'function') e.waitUntil(out);
+        if (out !== undefined) e.respondWith(out);
+      };
+      target.addEventListener(type, listener);
+      return () => target.removeEventListener(type, listener);
+    };
+  }
   let port = null, manifest = null, capabilities = [], storageScopes = {}, online = true, seq = 0, role = 'primary';
   const pending = new Map();
-  const commandHandlers = new Map();
-  const openerHandlers = new Map();
-  let onConnectivity = null, onDeactivate = null, onSettingsChange = null, onDock = null;
-  const mediaHandlers = {}; // action -> handler, for OS media-session controls
+  // EVERY hook is an EventTarget registration — see above for why. `ctx` itself is
+  // the target for lifecycle and connectivity; commands, openers and media each get their
+  // own so an event type can be a command name or an action without colliding.
+  const bus = makeTarget();                // deactivate | connectivity | settingschange | dockchange
+  const commandTarget = makeTarget();      // type = the command's short name
+  const openerTarget = makeTarget();       // type = the opener's name, or '*'
+  // Media tells the HOST which actions to claim from the OS, so registration is observed:
+  // the first listener for an action claims it, the last one to go releases it.
+  const mediaTarget = makeTarget(
+    (action) => { call('media:action', { action, on: true }).catch(() => {}); },
+    (action) => { call('media:action', { action, on: false }).catch(() => {}); },
+  );
+  // A LIST. It was one slot — `onDeactivate = fn` — so a second registration silently
+  // discarded the first, and the plugin that lost one had no way to notice: the symptom
+  // is a timer or an object URL that outlives the viewer. The audiobook player has two
+  // teardowns (a download poller and the transport), which is not exotic; anything with
+  // more than one resource has more than one.
+
 
   const now = () => { try { return Date.now(); } catch { return 0; } };
 
@@ -65,7 +193,13 @@
     constructor(id, { size = 0, type = '', etag = null, start = 0, end = null } = {}) {
       super();
       this.id = id;
-      this.type = type;
+      // `_type`, and a getter below. `Blob.prototype.type` is an accessor with no setter,
+      // so `this.type = …` THROWS in strict mode — which every module is. That one line
+      // meant `ctx.files.blob()` rejected on construction for every plugin that ever
+      // called it: no cover art, no container parsing, no streaming, and an error message
+      // ("Cannot set property type of #<Blob> which has only a getter") that never left
+      // the sandboxed frame it was thrown in.
+      this._type = type;
       this.etag = etag;
       // A window on the source. `size` is this window's length, which is what makes
       // `slice()` of a slice behave the way a caller expects.
@@ -74,6 +208,7 @@
     }
 
     get size() { return Math.max(0, this._end - this._start); }
+    get type() { return this._type; }
 
     /**
      * A window on the same source. No bytes move and none need to exist yet.
@@ -160,7 +295,7 @@
     return {
       domain: manifest && manifest.domain, name: manifest && manifest.name,
       online, role, ts: now(),
-      handlers: [...commandHandlers.keys()],
+      handlers: commandTarget.types(),
     };
   }
   const announce = () => port && emit('manifest', buildManifest());
@@ -185,30 +320,32 @@
 
   function dispatch(method, params) {
     if (method === 'command:execute') {
-      const h = commandHandlers.get(params.id);
-      // Throw, like `opener:open` two lines down. Resolving `undefined` for an id with
-      // no handler told the host the command had RUN when nothing had.
-      if (!h) throw new Error(`No handler registered for command "${params.id}"`);
-      return h(...(params.args || []));
+      // Throw rather than resolve `undefined` for an id nobody implements: that told the
+      // host the command had RUN when nothing had.
+      if (!commandTarget.listening(params.id)) throw new Error(`No handler registered for command "${params.id}"`);
+      return fire(commandTarget, params.id, { args: params.args || [] });
     }
     if (method === 'opener:open') {
       // An opener frame boots at that opener's entry module and runs exactly one
       // opener, so an unkeyed onOpen(fn) handler is the normal case.
-      const f = openerHandlers.get(params.openerId) || openerHandlers.get('*');
-      if (!f) throw new Error('no opener ' + params.openerId);
-      return f(params.file, params.context);
+      const type = openerTarget.listening(params.openerId) ? params.openerId
+        : openerTarget.listening('*') ? '*' : null;
+      if (!type) throw new Error('no opener ' + params.openerId);
+      // AWAITED, and that is what `waitUntil` is for: `opener:open` must not resolve until
+      // the viewer has drawn, or the host hides "Opening…" over a blank frame.
+      return fire(openerTarget, type, { file: params.file, context: params.context, openerId: params.openerId });
     }
     if (method === 'manifest') return buildManifest();
     throw new Error('Unknown host call ' + method);
   }
   async function dispatchEvent(method, params) {
-    if (method === 'deactivate') return onDeactivate && onDeactivate();
-    if (method === 'connectivity') { online = !!params.online; try { onConnectivity && (await onConnectivity({ online })); } catch (e) { console.error(e); } announce(); }
-    if (method === 'settings:changed') { try { onSettingsChange && onSettingsChange(params.key, params.value); } catch (e) { console.error(e); } }
+    if (method === 'deactivate') return fire(bus, 'deactivate', {});
+    if (method === 'connectivity') { online = !!params.online; await fire(bus, 'connectivity', { online }); announce(); }
+    if (method === 'settings:changed') return fire(bus, 'settingschange', { key: params.key, value: params.value });
     // The OS/host fired a media transport control (play/pause/next/seek…).
-    if (method === 'media:action') { try { mediaHandlers[params.action] && mediaHandlers[params.action](params); } catch (e) { console.error(e); } }
+    if (method === 'media:action') return fire(mediaTarget, params.action, params);
     // The host docked or undocked this viewer (see ctx.dock).
-    if (method === 'dock:state') { try { onDock && onDock(params); } catch (e) { console.error(e); } }
+    if (method === 'dock:state') return fire(bus, 'dockchange', params);
   }
 
   function requireCap(cap) { if (!capabilities.includes(cap)) throw new Error('Plugin lacks capability "' + cap + '"'); }
@@ -263,7 +400,10 @@
       // for what it declared, addressed by id.
       commands: {
         /** Implement a command this plugin's manifest declares, by its short name. */
-        handle(name, handler) { commandHandlers.set(name, handler); return this; },
+        /** Implement a command this plugin's manifest declares, by its short name. */
+        handle(name, handler) { hook(commandTarget, name, (e) => e.detail.args)(handler); return this; },
+        addEventListener: (...a) => commandTarget.addEventListener(...a),
+        removeEventListener: (...a) => commandTarget.removeEventListener(...a),
         /**
          * Run a command. Its OWN commands by short name; anyone else's by full address
          * (a built-in like 'explorer.download', or a `trove+contrib:` URI) — and only
@@ -275,9 +415,13 @@
        *  optional — an opener frame runs exactly one opener. */
       onOpen(idOrHandler, maybeHandler) {
         const [id, handler] = typeof idOrHandler === 'function' ? ['*', idOrHandler] : [idOrHandler, maybeHandler];
-        openerHandlers.set(id, handler);
+        // A handler returning a promise keeps the host waiting — which is what holds
+        // "Opening…" on screen until the viewer has actually drawn. See `hook`.
+        hook(openerTarget, id, (e) => [e.detail.file, e.detail.context])(handler);
         return this;
       },
+      /** The opener target, for `addEventListener('*', e => e.waitUntil(…))`. */
+      openers: openerTarget,
       // NOTE: there is no onIndex(). Indexers run on the SERVER (in its isolate
       // runtime), not in this sandbox — indexing has to happen once per upload for the
       // drive, not in whichever tab is open. An indexer's entry module is plain ESM
@@ -328,7 +472,21 @@
         setMetadata: (m) => (requireCap('media'), call('media:metadata', m || {})),
         setPlaybackState: (state) => (requireCap('media'), call('media:playbackState', { state })),
         setPositionState: (p) => (requireCap('media'), call('media:position', p || {})),
-        setActionHandler: (action, handler) => { requireCap('media'); if (handler) mediaHandlers[action] = handler; else delete mediaHandlers[action]; return call('media:action', { action, on: !!handler }); },
+        /**
+         * @deprecated use `ctx.media.addEventListener(action, …)`.
+         *
+         * Additive now, and the RPC that claims the OS control moves with it: the first
+         * listener for an action claims it, the last one to go releases it. Passing null
+         * removes nothing in particular, so it is a no-op rather than a silent surprise.
+         */
+        setActionHandler: (action, handler) => {
+          requireCap('media');
+          if (!handler) return Promise.resolve({ ok: true });
+          hook(mediaTarget, action)(handler);
+          return Promise.resolve({ ok: true });
+        },
+        addEventListener: (...a) => (requireCap('media'), mediaTarget.addEventListener(...a)),
+        removeEventListener: (...a) => mediaTarget.removeEventListener(...a),
         clear: () => call('media:clear', {}),
       },
       // Dock — register this viewer to persist as a small floating frame when the
@@ -339,7 +497,10 @@
         enable: (opts) => (requireCap('dock'), call('dock:enable', opts || {})),
         disable: () => (requireCap('dock'), call('dock:disable', {})),
         close: () => call('dock:close', {}),
-        onChange: (fn) => { onDock = fn; },
+        /** @deprecated use `ctx.addEventListener('dockchange', …)`. Now additive. */
+        onChange: hook(bus, 'dockchange'),
+        addEventListener: (...a) => bus.addEventListener(...a),
+        removeEventListener: (...a) => bus.removeEventListener(...a),
       },
       // Network — there is no direct fetch in the sandbox; the host performs the
       // request, but ONLY to endpoints declared in the manifest's `network` list
@@ -394,6 +555,61 @@
          */
         mediaUrl: (id, opts) => (requireCap('files'), call('files:mediaUrl', Object.assign({ id }, opts))),
 
+        /**
+         * A file's own key/value data, for THIS plugin.
+         *
+         * The third kind of state a viewer has, and the one there was nowhere to put. A
+         * contribution is derived from the file and is rewritten whenever it is
+         * re-indexed. A setting is per-device, so a listening position kept there does
+         * not follow you to your phone — which is the moment people notice. This is the
+         * other thing: state about a user's use of an item.
+         *
+         * ONE INTERFACE, and it deliberately does not say where the bytes are. A write
+         * lands locally at once and reaches the server when there is a server to reach;
+         * a read is the merge of both. Two devices that each wrote while apart converge,
+         * later write winning, because the sidecar underneath is a CRDT — see
+         * core/sidecar/document.js.
+         *
+         * Scoped to this plugin by the HOST, from the plugin it authenticated. There is
+         * no parameter for the scope because there is no version of this where a plugin
+         * chooses whose data it is writing.
+         */
+        data: (id) => ({
+          all: () => (requireCap('files'), call('items:data:get', { id })),
+          get: async (key) => (requireCap('files'), (await call('items:data:get', { id }))[key]),
+          set: (key, value) => (requireCap('files'), call('items:data:set', { id, key, value })),
+          remove: (key) => (requireCap('files'), call('items:data:remove', { id, key })),
+        }),
+
+        /**
+         * Is the whole file already in this browser?
+         *
+         * Cheap — it reads bookkeeping, not bytes — so ask it before deciding what to
+         * draw. `{ local, loaded, total, ratio, filling }`: enough to show a progress
+         * bar for a download already under way instead of offering to start it again.
+         */
+        hasLocal: (id) => (requireCap('files'), call('files:hasLocal', { id })),
+
+        /**
+         * The whole file as a Blob, or null when it is not stored locally.
+         *
+         * THE WAY MEDIA WORKS IN HERE. This frame's CSP is `connect-src 'none'` and
+         * `media-src blob: data:` — deliberately, so a plugin cannot reach the network
+         * and cannot be an exfiltration side-channel. An `<audio src="https://…">` is
+         * therefore blocked outright, and no amount of URL minting changes that. A Blob
+         * is allowed, so a downloaded file plays by being handed over.
+         *
+         * Null when the file is incomplete rather than a partial Blob: half an MP4 is
+         * not a shorter MP4, and a caller handed one would fail like a decoder bug
+         * instead of like a missing download. Pair it with `offline.start` and
+         * `hasLocal` to get from "not here" to "here".
+         */
+        localBlob: async (id) => {
+          requireCap('files');
+          const { blob } = await call('files:localBlob', { id });
+          return blob || null;
+        },
+
         /**
          * Keeping a file, which is a DIFFERENT act from reading one.
          *
@@ -434,11 +650,26 @@
         get: (key) => call('settings:get', { key }),
         getSecret: (key) => call('settings:getSecret', { key }),
         set: (key, value) => call('settings:set', { key, value }),
-        onChange: (fn) => { onSettingsChange = fn; },
+        /** @deprecated use `ctx.addEventListener('settingschange', …)`. Now additive. */
+        onChange: hook(bus, 'settingschange', (e) => [e.detail.key, e.detail.value]),
       },
-      onConnectivity: (fn) => { onConnectivity = fn; },
+      /** @deprecated use `ctx.addEventListener('connectivity', …)`. Now additive. */
+      onConnectivity: hook(bus, 'connectivity'),
       announce,
-      onDeactivate: (fn) => { onDeactivate = fn; },
+      /**
+       * @deprecated use `ctx.addEventListener('deactivate', …)`.
+       *
+       * Kept, and now additive: registering twice used to discard the first, which is
+       * how a viewer ended up leaking one of its two teardowns. Returns a disposer.
+       */
+      onDeactivate: hook(bus, 'deactivate'),
+
+      // The bus itself. `deactivate`, `connectivity`, `settingschange`, `dockchange` —
+      // and every one of them composes, which the `onX` forms above now do too because
+      // they are written over this.
+      addEventListener: (...a) => bus.addEventListener(...a),
+      removeEventListener: (...a) => bus.removeEventListener(...a),
+      dispatchEvent: (...a) => bus.dispatchEvent(...a),
     };
   }
 

package/packages/plugin-sdk/src/protocol.js

@@ -49,6 +49,15 @@ export const METHODS = {
     bytes: 'files:bytes',
     // A minted URL for a media element. See pluginRpc.js for why this one host URL crosses.
     mediaUrl: 'files:mediaUrl',
+    // Is the whole file here, and can I have it? The pair a viewer needs because the
+    // frame's CSP forbids loading media from a URL — see pluginFrames.js.
+    // A file's own key/value data for this plugin — local-first, merged with the
+    // server opportunistically. See platform/itemData.js.
+    dataGet: 'items:data:get',
+    dataSet: 'items:data:set',
+    dataRemove: 'items:data:remove',
+    hasLocal: 'files:hasLocal',
+    localBlob: 'files:localBlob',
     offline: {
       start: 'files:offline:start', status: 'files:offline:status',
       cancel: 'files:offline:cancel', remove: 'files:offline:remove',