@3sln/trove 0.0.16 → 0.0.18

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',

package/packages/server/src/adapters/worker-tasks.js

@@ -85,6 +85,15 @@ export function createTaskHost(getServer) {
       return { task, alreadyRunning };
     }
 
+    async #beginBackfill(indexerIds, reason) {
+      const server = await this.#boot();
+      const { task, alreadyRunning, done } = await server.beginBackfill({ indexerIds, reason });
+      // Same shape as a reindex: nothing to resume from, so it either finishes in this
+      // object's lifetime or the files stay unindexed until something asks again.
+      if (!alreadyRunning) this.state.waitUntil?.(done.catch(() => null));
+      return { task, alreadyRunning };
+    }
+
     async #beginReindex(reason) {
       const server = await this.#boot();
       const { task, alreadyRunning, done } = await server.beginReindex({ reason });
@@ -102,6 +111,7 @@ export function createTaskHost(getServer) {
       const server = await this.#boot();
       switch (url.pathname) {
         case '/begin':
+          if (body.kind === 'backfill') return json(await this.#beginBackfill(body.indexerIds, body.reason));
           return json(body.kind === 'index'
             ? await this.#beginReindex(body.reason)
             : await this.#beginScan(body.collectionId || 'default', body.reason));
@@ -204,6 +214,7 @@ export function remoteBackground(namespace) {
     background: {
       beginScan: (collectionId, { reason } = {}) => begin({ kind: 'scan', collectionId, reason }),
       beginReindex: ({ reason } = {}) => begin({ kind: 'index', reason }),
+      beginBackfill: ({ indexerIds, reason } = {}) => begin({ kind: 'backfill', indexerIds, reason }),
     },
     maintain: (budgetMs) => stub()
       .fetch('https://trove.tasks/maintain', {

package/packages/server/src/engine/providers/core.js

@@ -39,7 +39,7 @@ import {
   ApiKeyService, CapabilityProvider, ApiKeyCapabilityProvider,
   CollectionService,
   PluginService, PackageStore, StoragePackageStore, SqlitePluginInstallStore,
-  IndexerRuntime, InProcessIndexerRuntime, PluginIndexers,
+  IndexerRuntime, InProcessIndexerRuntime, WorkerLoaderIndexerRuntime, PluginIndexers,
   TaskRegistry, IssueRegistry,
   Vfs, TroveError,
   resolveAuthDiscovery,
@@ -225,6 +225,7 @@ export function coreProviders(config, lifecycleState) {
     backgroundWork: Provider.fromSingleton({
       beginScan: (collectionId, opts) => lifecycleState.background.beginScan(collectionId, opts),
       beginReindex: (opts) => lifecycleState.background.beginReindex(opts),
+      beginBackfill: (opts) => lifecycleState.background.beginBackfill(opts),
     }),
 
     /**
@@ -611,10 +612,16 @@ export function coreProviders(config, lifecycleState) {
 
     // Server indexer sub-packages run through a pluggable runtime. The default is
     // the in-process (trusted) runner; a deployment swaps in an isolate runtime.
-    indexerRuntime: Provider.fromLazySingleton(() =>
-      (config.serverIndexers === false
-        ? null
-        : resolve(config.indexerRuntime, IndexerRuntime, () => new InProcessIndexerRuntime()))),
+    indexerRuntime: Provider.fromLazySingleton(() => {
+      if (config.serverIndexers === false) return null;
+      // `{ loader }` — a Worker Loader binding, which configFromEnv sets when the
+      // deployment declares one. Built here rather than there so core stays the only
+      // place that knows what a runtime is.
+      if (config.indexerRuntime?.loader && !(config.indexerRuntime instanceof IndexerRuntime)) {
+        return new WorkerLoaderIndexerRuntime(config.indexerRuntime);
+      }
+      return resolve(config.indexerRuntime, IndexerRuntime, () => new InProcessIndexerRuntime());
+    }),
 
     plugins: Provider.fromLazySingleton(
       async (deps) => {

package/packages/server/src/index.js

@@ -140,6 +140,47 @@ export async function createServer(config = {}) {
     }
   };
   const startReindex = async (opts) => (await beginReindex(opts)).done;
+
+  /**
+   * Re-run named indexers over the files they match — what a freshly installed plugin
+   * needs, and the reason it is a TASK rather than part of the install.
+   *
+   * Scoped to `indexerIds` rather than rebuilding the drive: installing one plugin should
+   * not re-embed every file for every other indexer. That is also why it does not take
+   * the drive-wide `reindex` claim a full rebuild takes — two different plugins
+   * backfilling at once are doing disjoint work.
+   */
+  const beginBackfill = async ({ indexerIds = [], reason, title } = {}) => {
+    const wanted = indexerIds.filter(Boolean);
+    if (!wanted.length) {
+      return { task: null, alreadyRunning: false, done: Promise.resolve({ indexed: 0 }) };
+    }
+    const begun = tasks.begin(
+      {
+        kind: 'index',
+        title: title || (wanted.length === 1 ? 'Indexing existing files' : `Indexing existing files for ${wanted.length} indexers`),
+        detail: reason || null,
+        unit: 'items',
+        cancellable: true,
+      },
+      async (task) => {
+        let indexed = 0;
+        for (const id of wanted) {
+          const indexer = vfs.indexers.get(id);
+          // A named indexer that is not registered is not an error worth failing the
+          // task over: the usual cause is a deployment that cannot run it, which has
+          // already said so through the plugin-indexers issue.
+          if (!indexer?.match) continue;
+          const r = await vfs.backfillIndexer(indexer, { shouldStop: () => task.cancelled || closing() });
+          indexed += r?.indexed ?? 0;
+          task.progress?.({ done: indexed });
+          if (task.cancelled || closing()) break;
+        }
+        return { indexed };
+      },
+    );
+    return { task: begun.task, alreadyRunning: false, done: begun.done };
+  };
   // Retrying an issue runs the same work as everything else, and reports it the same
   // way. The issue is not cleared here — it is cleared by the indexing that succeeds,
   // so a retry can't report success over a problem that is still there.
@@ -165,10 +206,25 @@ export async function createServer(config = {}) {
   lifecycleState.background = {
     beginScan: config.background?.beginScan || beginScan,
     beginReindex: config.background?.beginReindex || beginReindex,
+    beginBackfill: config.background?.beginBackfill || beginBackfill,
   };
   const routeBeginScan = lifecycleState.background.beginScan;
   const routeBeginReindex = lifecycleState.background.beginReindex;
+  const routeBeginBackfill = lifecycleState.background.beginBackfill;
   issues.handle('scan-collection', (issue) => startScan(issue.retry.collectionId, { reason: 'Retrying after a failed scan' }));
+  // "I have added the binding — try again." Re-activating re-probes, which is the only
+  // honest way to answer: a button that merely dismissed the diagnostic would leave the
+  // drive exactly as unable to index as it was, with nothing saying so.
+  issues.handle('reactivate-indexers', async (issue) => {
+    const record = (await plugins?.installs?.all?.() ?? []).find((r) => r.pluginId === issue.retry.pluginId);
+    if (!record) return { ok: false };
+    await plugins.indexers?.activate(record, { backfill: false });
+    // Registered again? Then catch the existing files up, which is what the install
+    // would have scheduled had the deployment been able to run them at the time.
+    const ids = (record.indexers || []).map((i) => i.id).filter((id) => vfs.indexers.get(id));
+    if (ids.length) await routeBeginBackfill({ indexerIds: ids, reason: 'Retrying after the indexer runtime became available' });
+    return { ok: true };
+  });
   issues.handle('storage-check', (issue) => storageCheck.run({ origin: issue.retry?.origin || config.publicUrl || null }));
   // The one retry that matters most: the user has been told a comment saved and it exists
   // only in memory. The op was raised for years with no handler registered for it — and in
@@ -529,6 +585,7 @@ export async function createServer(config = {}) {
     // inside a Durable Object want. `begin*` goes wherever `config.background` says,
     // which for a front-line Worker isolate is the object rather than itself.
     startScan, startReindex, beginScan: routeBeginScan, beginReindex: routeBeginReindex,
+    beginBackfill: routeBeginBackfill,
     runMaintenance, checkStorage: (opts) => storageCheck.run(opts), rotation, mcp, auth, close };
 }
 
@@ -902,6 +959,17 @@ export function configFromEnv(env = (typeof process !== 'undefined' ? process.en
   // TROVE_SERVER_INDEXERS=0/false refuses server-indexer plugins on this deployment.
   if (env.TROVE_SERVER_INDEXERS === '0' || env.TROVE_SERVER_INDEXERS === 'false') config.serverIndexers = false;
 
+  // A `worker_loaders` binding means this is a Worker that CAN run plugin code, in a
+  // real isolate — so it does, rather than falling back to the in-process runner, which
+  // cannot import a `data:` URL on workerd and fails on every file. Discovered from the
+  // binding rather than configured: a deployment that declared the binding wants it, and
+  // one that did not gets the honest install-time refusal from the probe.
+  //
+  // Any binding name is accepted so the wrangler config can call it what it likes;
+  // TROVE_WORKER_LOADER names it explicitly when there is more than one.
+  const loader = env[env.TROVE_WORKER_LOADER || 'LOADER'] ?? findWorkerLoader(env);
+  if (loader && config.serverIndexers !== false) config.indexerRuntime = { loader };
+
   // Plugin package blob store: defaults to the primary storage backend (prefixed).
   // Point it at a separate bucket/root with TROVE_PACKAGE_STORE (+ its own settings).
   if (env.TROVE_PACKAGE_STORE) {
@@ -955,3 +1023,25 @@ export function configFromEnv(env = (typeof process !== 'undefined' ? process.en
 }
 
 export { createRouter };
+
+/**
+ * A `worker_loaders` binding, found by shape.
+ *
+ * Bindings arrive as an untyped bag and a loader is only identifiable by having `get`
+ * and nothing else — deliberately narrow, because a false positive here would hand
+ * plugin code to whatever object happened to match. Skips the names of bindings that
+ * also expose `get` and are emphatically not loaders (KV, R2, D1, Durable Objects are
+ * declared under their own config keys and reached by name, so a drive that wants this
+ * can always be explicit with TROVE_WORKER_LOADER).
+ */
+function findWorkerLoader(env) {
+  for (const [name, value] of Object.entries(env || {})) {
+    if (!value || typeof value !== 'object') continue;
+    if (typeof value.get !== 'function') continue;
+    // A loader has exactly one method. KV has `put`/`list`, R2 has `head`/`delete`,
+    // a DO namespace has `idFromName`, D1 has `prepare` — all disqualifying.
+    if (value.put || value.list || value.head || value.delete || value.idFromName || value.prepare) continue;
+    if (/loader/i.test(name)) return value;
+  }
+  return null;
+}