eddie-jekyll 0.4.1 → 0.4.2

data/assets/eddie-worker.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 // Generated by widget/build.sh from widget/src/worker.js and widget/src/lib/*.js; edit those instead.
 "use strict";
+const EDDIE_ASSET_VERSION = "c0fdc503e01a";
 const EddieLib = {};
 // SPDX-License-Identifier: GPL-3.0-only
 
@@ -20,6 +21,17 @@ const EddieLib = {};
 
   const HF_HOST = "https://huggingface.co";
 
+  /**
+   * `?v=` of the runtime assets (widget, workers, wasm, glue, service
+   * workers): a hash of the files that produced them, stamped into every
+   * bundle by widget/build.sh. Deliberately not the index's version, which
+   * changes on every content rebuild and so re-downloaded the whole engine
+   * on every deploy; see "Script tag" in widget/README.md. null outside a
+   * bundle (the Node tests), which just means no `?v=`.
+   */
+  const ASSET_VERSION =
+    typeof EDDIE_ASSET_VERSION === "string" && EDDIE_ASSET_VERSION ? EDDIE_ASSET_VERSION : null;
+
   /** Directory of an absolute URL, without query or hash, with a trailing slash. */
   function baseUrlOf(href) {
     const u = new URL(href);
@@ -87,6 +99,7 @@ const EddieLib = {};
 
   return {
     HF_HOST,
+    ASSET_VERSION,
     baseUrlOf,
     versionOf,
     withVersion,
@@ -101,8 +114,9 @@ const EddieLib = {};
 
 // SPDX-License-Identifier: GPL-3.0-only
 
-// Dense-lane selection, download sizes, consent copy and degraded-arm notices.
-// Pure functions over the index manifest (see src/manifest.rs).
+// Dense-lane selection and download sizes. Pure functions over the index
+// manifest (see src/manifest.rs). The consent and notice copy lives in
+// copy.js so the widget bundle does not carry the engine-side lane logic.
 
 (function (factory) {
   const api = factory();
@@ -170,6 +184,45 @@ const EddieLib = {};
     return /\.(safetensors|bin|pt|gguf|onnx)$/i.test(String(file));
   }
 
+  /** Site-relative directory the lane's model files live in (`eddie index --bundle-model`), or null for HuggingFace. */
+  function laneBaseUrl(lane) {
+    const b = lane && lane.runtime && lane.runtime.base_url;
+    return typeof b === "string" && b.trim() ? b.trim() : null;
+  }
+
+  /** Where the lane's files are downloaded from: "site" (bundled next to the index) or "huggingface". */
+  function laneOrigin(lane) {
+    return laneBaseUrl(lane) ? "site" : "huggingface";
+  }
+
+  /** Absolute URL of a site-bundled model file, resolved against the index URL (no version parameter yet). */
+  function siteModelUrl(lane, file, indexUrl) {
+    const base = laneBaseUrl(lane);
+    if (!base) return null;
+    return new URL(base.replace(/\/?$/, "/") + String(file).replace(/^\//, ""), indexUrl).href;
+  }
+
+  /**
+   * Name a lane's file is cached under (see urls.js cacheKey): a bundled f16
+   * copy and the HuggingFace original differ, so site files get their own
+   * prefix and never collide with a repo download of the same name.
+   */
+  function laneFileName(lane, file) {
+    return laneBaseUrl(lane) ? "@site/" + file : String(file);
+  }
+
+  /** The sidecar entry that holds `scope`'s section of `laneId`, or null when the section is in the core file. */
+  function sidecarFor(manifest, scope, laneId) {
+    const list = manifest && Array.isArray(manifest.sidecars) ? manifest.sidecars : [];
+    return list.find((s) => s.scope === scope && s.lane === laneId) || null;
+  }
+
+  /** Bytes of the sidecar file(s) a lane's chunk vectors need, counted once per file. */
+  function laneSidecarBytes(manifest, laneId) {
+    const side = sidecarFor(manifest, "chunks", laneId);
+    return side && Number.isFinite(Number(side.bytes)) ? Number(side.bytes) : 0;
+  }
+
   /**
    * Why the WASM loader (init_dense_wasm) cannot run a wasm-candle lane, or
    * null when it can: it accepts BERT-family lanes with config.json,
@@ -197,6 +250,11 @@ const EddieLib = {};
     const lanes = (manifest && Array.isArray(manifest.dense)) ? manifest.dense : [];
     const runtime = (opts && opts.denseRuntime) || "auto";
     const hasWebGpu = !!(opts && opts.hasWebGpu);
+    // A pinned lane id (the visitor picked one in the settings panel, or the
+    // site set data-dense-lane): the choice narrows to that lane, and if it
+    // is not runnable here the result is no dense arm rather than a silently
+    // different model.
+    const pinned = (opts && opts.laneId) ? String(opts.laneId) : null;
     const webgpu = lanes.filter(isWebGpuLane);
     const skipped = [];
     const wasm = lanes.filter(isWasmLane).filter((lane) => {
@@ -207,6 +265,9 @@ const EddieLib = {};
     if (lanes.length === 0) {
       return { candidates: [], skipped, reason: "index has no dense lane" };
     }
+    if (runtime === "off") {
+      return { candidates: [], skipped, reason: "dense search is turned off" };
+    }
     let candidates;
     if (runtime === "wasm") {
       candidates = wasm;
@@ -215,9 +276,11 @@ const EddieLib = {};
     } else {
       candidates = hasWebGpu ? webgpu.concat(wasm) : wasm;
     }
+    if (pinned) candidates = candidates.filter((lane) => lane.id === pinned);
     let reason = null;
     if (candidates.length === 0) {
-      if (runtime === "wasm") reason = skipped.length ? "no wasm-candle lane the WASM loader can run" : "index has no wasm-candle lane";
+      if (pinned) reason = `lane ${pinned} cannot run here`;
+      else if (runtime === "wasm") reason = skipped.length ? "no wasm-candle lane the WASM loader can run" : "index has no wasm-candle lane";
       else if (!hasWebGpu && webgpu.length && !wasm.length) reason = "no WebGPU adapter";
       else if (runtime === "webgpu" && !hasWebGpu) reason = "no WebGPU adapter";
       else if (runtime === "webgpu") reason = "index has no webgpu-onnx lane";
@@ -232,12 +295,70 @@ const EddieLib = {};
     return runtime.dtype || "fp32";
   }
 
-  /** Approximate bytes a lane downloads on first use, or null when unknown. */
+  /** The exact byte count the manifest declares for a bundled model (`runtime.bytes`), or null. */
+  function laneDeclaredBytes(lane) {
+    const declared = lane && lane.runtime ? Number(lane.runtime.bytes) : NaN;
+    return Number.isFinite(declared) && declared > 0 ? declared : null;
+  }
+
+  /**
+   * Bytes a lane downloads on first use, or null when unknown: the exact
+   * count the manifest carries for a bundled model (`runtime.bytes`, written
+   * by `eddie index --bundle-model`), else the table estimate for known
+   * HuggingFace repos. The table describes the f32 originals; a bundled f16
+   * copy without `runtime.bytes` should be measured instead (the engine
+   * HEADs the files), never estimated from the table.
+   */
   function laneDownloadBytes(lane) {
+    const declared = laneDeclaredBytes(lane);
+    if (declared != null) return declared;
     const repo = (laneRepo(lane) || "").toLowerCase();
     return Object.prototype.hasOwnProperty.call(DOWNLOAD_SIZES, repo) ? DOWNLOAD_SIZES[repo] : null;
   }
 
+  return {
+    DEFAULT_WASM_FILES,
+    DOWNLOAD_SIZES,
+    laneKind,
+    isWasmLane,
+    isWebGpuLane,
+    laneRepo,
+    laneRevision,
+    laneFiles,
+    isWeightsFile,
+    laneBaseUrl,
+    laneOrigin,
+    siteModelUrl,
+    laneFileName,
+    sidecarFor,
+    laneSidecarBytes,
+    wasmLaneProblem,
+    chooseDenseLanes,
+    pickDtype,
+    laneDeclaredBytes,
+    laneDownloadBytes,
+  };
+});
+
+// SPDX-License-Identifier: GPL-3.0-only
+
+// User-facing copy shared by the widget and the search engine: byte
+// formatting, the download consent card and the degraded-arm notices.
+// Split out of lanes.js so the widget bundle carries only this, not the
+// engine-side lane selection.
+
+(function (factory) {
+  const api = factory();
+  if (typeof module === "object" && module && module.exports) {
+    module.exports = api;
+  } else if (typeof EddieLib === "object" && EddieLib) {
+    Object.assign(EddieLib, api);
+  } else {
+    globalThis.EddieLib = Object.assign(globalThis.EddieLib || {}, api);
+  }
+})(function () {
+  "use strict";
+
   function formatBytes(n) {
     if (n == null || !Number.isFinite(n)) return "unknown size";
     if (n >= 1e9) {
@@ -251,16 +372,21 @@ const EddieLib = {};
 
   /**
    * Consent card copy for a model download. `consentText` (site override) may
-   * contain `{size}` and `{model}` placeholders.
+   * contain `{size}`, `{model}` and `{origin}` placeholders.
+   *   sizeBytes    model download (null when unknown)
+   *   origin       "site" | "huggingface" (where the model is fetched from)
+   *   sidecarBytes index vectors fetched from the site for this lane (0 when in the core index)
    */
   function consentCopy(opts) {
     const size = formatBytes(opts.sizeBytes);
     const model = opts.model || "the search model";
+    const origin = opts.origin === "site" ? "this site" : "huggingface.co";
     if (opts.consentText) {
-      return opts.consentText.replace(/\{size\}/g, size).replace(/\{model\}/g, model);
+      return opts.consentText.replace(/\{size\}/g, size).replace(/\{model\}/g, model).replace(/\{origin\}/g, origin);
     }
-    const sized = opts.sizeBytes == null ? "a one-time download (size unknown)" : `a one-time ${size} download`;
-    let text = `Semantic search runs a language model in your browser. That needs ${sized} of ${model}, kept in your browser's cache for next time.`;
+    const sized = opts.sizeBytes == null ? `a one-time download (size unknown) from ${origin}` : `a one-time ${size} download from ${origin}`;
+    const side = opts.sidecarBytes > 0 ? `, plus ${formatBytes(opts.sidecarBytes)} of index vectors from this site` : "";
+    let text = `Semantic search runs ${model} in your browser. That needs ${sized}${side}, kept in your browser's cache for next time.`;
     if (opts.saveData) {
       text = "Data saver is on. " + text;
     }
@@ -271,8 +397,15 @@ const EddieLib = {};
    * Drop degraded notes that describe the index design rather than a failure
    * (an index without a dense lane or sparse arm is not "degraded").
    */
+  /**
+   * Drop the "degraded" entries that describe how the index or the visitor
+   * chose to run, not something going wrong: an index built without a lane,
+   * and a visitor who picked keyword-only search in the settings panel.
+   */
   function filterDesignDegraded(degraded) {
-    return (degraded || []).filter((d) => !/index has no (dense lane|sparse arm)/.test(d));
+    return (degraded || []).filter(
+      (d) => !/index has no (dense lane|sparse arm)|dense search is turned off/.test(d)
+    );
   }
 
   /** Human notice when a semantic arm is missing, or null when nothing to say. */
@@ -290,19 +423,6 @@ const EddieLib = {};
   }
 
   return {
-    DEFAULT_WASM_FILES,
-    DOWNLOAD_SIZES,
-    laneKind,
-    isWasmLane,
-    isWebGpuLane,
-    laneRepo,
-    laneRevision,
-    laneFiles,
-    isWeightsFile,
-    wasmLaneProblem,
-    chooseDenseLanes,
-    pickDtype,
-    laneDownloadBytes,
     formatBytes,
     consentCopy,
     filterDesignDegraded,
@@ -349,8 +469,14 @@ const EddieLib = {};
   }
 
   async function readBody(response, onProgress) {
-    const lenHeader = response.headers && response.headers.get ? response.headers.get("Content-Length") : null;
-    const total = lenHeader && /^\d+$/.test(lenHeader) && Number(lenHeader) > 0 ? Number(lenHeader) : null;
+    const headers = response.headers && response.headers.get ? response.headers : null;
+    const lenHeader = headers ? headers.get("Content-Length") : null;
+    // A compressed response (Content-Encoding: br/gzip) announces the wire
+    // size while the stream yields decoded bytes: the announced total is
+    // neither a buffer size nor a progress denominator then.
+    const encoding = headers ? String(headers.get("Content-Encoding") || "").trim().toLowerCase() : "";
+    const encoded = encoding !== "" && encoding !== "identity";
+    const total = !encoded && lenHeader && /^\d+$/.test(lenHeader) && Number(lenHeader) > 0 ? Number(lenHeader) : null;
     if (onProgress) onProgress(0, total);
     if (!response.body || typeof response.body.getReader !== "function") {
       const buf = new Uint8Array(await response.arrayBuffer());
@@ -466,702 +592,1129 @@ const EddieLib = {};
 
 // SPDX-License-Identifier: GPL-3.0-only
 
-// Eddie search worker (classic worker).
+// Eddie search engine, host-independent.
+//
+// Everything the search worker does (manifest, lane choice, downloads with
+// timeouts and retry, IndexedDB cache, sidecars, sparse tokenizer, the
+// transformers.js WebGPU lane, the WASM calls and the consent handshake)
+// lives here, behind an `env` the host supplies:
+//
+//   createSearchEngine({
+//     post(message)                 broadcast sink: status and ready events
+//     loadWasm(baseUrl, variant)
+//                                   -> Promise of the wasm-bindgen API object;
+//                                   variant is "lite" (always first) or
+//                                   "dense" (only when a wasm-candle lane is
+//                                   about to run); a host without the dense
+//                                   module rejects and the lane degrades
+//     loadTransformers()            -> Promise of the transformers.js module
+//     canRunWebGpuLane              false when this host cannot run webgpu-onnx lanes
+//     navigator, indexedDB          optional overrides (tests)
+//   })
+//
+// Lite first: the lite module (no model code, a quarter of the dense one
+// after brotli) answers keyword and sparse queries at once. When a visitor
+// accepts a CPU dense lane the dense module is loaded and the index, its
+// attached sidecars and the sparse tokenizer are handed over to it; the
+// bytes are kept only while that hand-over may still happen.
 //
-// widget/build.sh concatenates widget/src/lib/*.js ahead of this file, so the
-// pure helpers are available as `EddieLib`. The WASM glue is loaded with
-// importScripts; transformers.js (WebGPU dense lane) with a dynamic import().
+// `engine.handle(msg, reply)` dispatches one protocol message; `reply` is
+// the sink for that message's own answers (search_result, cache_result,
+// error with requestId ...). In a dedicated worker `post` and `reply` are
+// both `self.postMessage`; in the service worker `reply` is the requesting
+// page's port and `post` fans out to every connected page.
 //
-// Protocol (main thread -> worker):
-//   init        {indexUrl, baseUrl, version?, denseRuntime?, consent?}
-//   cache_check {requestId}
-//   search      {requestId, query, topK?, mode?, evidence?, qa?}
-//   page        {requestId, url}
-//   chunk       {requestId, id}
-//   qa          {requestId, query, k?}
-// (worker -> main thread):
-//   status        {state, ...}   loading_wasm | loading_index | index_ready |
-//                                consent_required | downloading_model |
-//                                loading_model | error
-//   ready         {lanes, lane, arms, degraded, manifest}
-//   cache_result  {requestId, cached, lane, sizeBytes}
-//   search_result {requestId, results, arms, degraded, mode, qa?}
-//   page_result   {requestId, page}
-//   chunk_result  {requestId, chunk}
-//   qa_result     {requestId, hits}
-//   error         {requestId?, message, fatal?, unsupported?}
+// The message shapes are documented in widget/README.md ("Worker protocol").
 
-"use strict";
+(function (factory) {
+  const api = factory();
+  if (typeof module === "object" && module && module.exports) {
+    module.exports = api;
+  } else if (typeof EddieLib === "object" && EddieLib) {
+    Object.assign(EddieLib, api);
+  } else {
+    globalThis.EddieLib = Object.assign(globalThis.EddieLib || {}, api);
+  }
+})(function () {
+  "use strict";
 
-const IDB_NAME = "eddie-models";
-const IDB_VERSION = 2;
-const IDB_FILES = "files";
-const IDB_META = "meta";
-const TRANSFORMERS_URL = "https://cdn.jsdelivr.net/npm/@huggingface/transformers@4.2.0";
-const PROGRESS_INTERVAL_MS = 80;
+  const IDB_NAME = "eddie-models";
+  const IDB_VERSION = 2;
+  const IDB_FILES = "files";
+  const IDB_META = "meta";
+  const PROGRESS_INTERVAL_MS = 80;
+  const NOT_LOADED = "index not loaded yet";
 
-const lib = EddieLib;
+  /** What a wasm-bindgen API object can do; older glue without capabilities() is the full build. */
+  function wasmCapabilities(api) {
+    if (api && typeof api.capabilities === "function") {
+      try {
+        const c = JSON.parse(api.capabilities());
+        return { dense_wasm: !!c.dense_wasm, sparse: c.sparse !== false, version: c.version || null };
+      } catch (_) {
+        // fall through to feature detection
+      }
+    }
+    return { dense_wasm: !!(api && typeof api.init_dense_wasm === "function"), sparse: true, version: null };
+  }
 
-const state = {
-  phase: "idle", // idle | loading | awaiting_consent | ready | error | dead
-  initRunning: false,
-  rerun: false,
-  baseUrl: "",
-  version: null,
-  indexUrl: null,
-  denseRuntime: "auto",
-  consent: Object.create(null), // lane id -> true
-  wasmReady: false,
-  indexLoaded: false,
-  manifest: null,
-  candidates: [],
-  candidateReason: null,
-  laneIndex: 0,
-  dense: null, // { lane, kind: "wasm" | "webgpu", embed? }
-  sparse: false,
-  degraded: [],
-  gpu: null, // { adapter, hasF16, maxBufferSize } | false
-  db: undefined, // IDBDatabase | null (unavailable)
-};
+  function createSearchEngine(env) {
+    const lib = typeof EddieLib === "object" && EddieLib ? EddieLib : env.lib;
+    const post = env.post;
+    const nav = env.navigator !== undefined ? env.navigator : globalThis.navigator;
+    const idb = env.indexedDB !== undefined ? env.indexedDB : globalThis.indexedDB;
+    const canRunWebGpuLane = env.canRunWebGpuLane !== false;
+
+    let wasm = null; // wasm-bindgen API object once loaded (lite, then dense after a hand-over)
+    let caps = null; // wasmCapabilities(wasm)
+
+    const state = {
+      phase: "idle", // idle | loading | awaiting_consent | awaiting_tier | ready | error | dead
+      initRunning: false,
+      rerun: false,
+      baseUrl: "",
+      version: null,
+      indexUrl: null,
+      loadedIndexUrl: null,
+      denseRuntime: "auto",
+      laneId: null, // visitor-pinned dense lane (settings panel), or null
+      consent: Object.create(null), // lane id -> true
+      wasmReady: false,
+      indexLoaded: false,
+      manifest: null,
+      // Bytes kept for the lite -> dense hand-over (dropped once it is done or impossible).
+      indexBytes: null,
+      sparseBytes: null,
+      sidecarBytes: Object.create(null), // file -> Uint8Array
+      attachedSidecars: [], // file names attached to the current module
+      candidates: [],
+      candidateReason: null,
+      hostSkipped: [], // webgpu-onnx lane ids this host cannot run
+      laneIndex: 0,
+      dense: null, // { lane, kind: "wasm" | "webgpu", embed? }
+      sparse: false,
+      degraded: [],
+      gpu: null, // { adapter, hasF16, maxBufferSize } | false
+      db: undefined, // IDBDatabase | null (unavailable)
+      siteSizes: Object.create(null), // lane id -> measured bundled download bytes
+    };
+
+    // -- dispatch ---------------------------------------------------------
+
+    function handle(msg, reply) {
+      const m = msg || {};
+      const out = reply || post;
+      switch (m.type) {
+        case "init":
+          return handleInit(m, out);
+        case "cache_check":
+          return handleCacheCheck(m, out);
+        case "cache_clear":
+          return handleCacheClear(m, out);
+        case "search":
+          return handleSearch(m, out);
+        case "page":
+          return handleLookup(m, out, "page_result", "page", () => wasm.page(String(m.url)));
+        case "chunk":
+          return handleLookup(m, out, "chunk_result", "chunk", () => wasm.chunk(Number(m.id)));
+        case "qa":
+          return handleQa(m, out);
+        default:
+          postError(out, m.requestId, `unknown message type ${String(m.type)}`);
+          return Promise.resolve();
+      }
+    }
 
-self.onmessage = function (e) {
-  const msg = e.data || {};
-  switch (msg.type) {
-    case "init":
-      handleInit(msg);
-      break;
-    case "cache_check":
-      handleCacheCheck(msg);
-      break;
-    case "search":
-      handleSearch(msg);
-      break;
-    case "page":
-      handleLookup(msg, "page_result", "page", () => wasm_bindgen.page(String(msg.url)));
-      break;
-    case "chunk":
-      handleLookup(msg, "chunk_result", "chunk", () => wasm_bindgen.chunk(Number(msg.id)));
-      break;
-    case "qa":
-      handleQa(msg);
-      break;
-    default:
-      postError(msg.requestId, `unknown message type ${String(msg.type)}`);
-  }
-};
+    /**
+     * The degraded list as reported to the host: design choices dropped
+     * (copy.js), and the dense arm's entries dropped entirely when the
+     * visitor turned the dense arm off -- they asked for keyword and sparse,
+     * so nothing is missing.
+     */
+    function reportedDegraded(list) {
+      const filtered = lib.filterDesignDegraded(unique(list));
+      if (state.denseRuntime !== "off") return filtered;
+      return filtered.filter((d) => !String(d).startsWith("dense:"));
+    }
 
-// -- init ---------------------------------------------------------------
+    /** Snapshot for the service worker's `state` reply. */
+    function snapshot() {
+      return {
+        phase: state.phase,
+        indexUrl: state.loadedIndexUrl,
+        version: state.version,
+        indexLoaded: state.indexLoaded,
+        lane: state.dense ? state.dense.lane.id : null,
+        runtime: state.dense ? state.dense.kind : null,
+        arms: state.indexLoaded ? { dense: !!state.dense, sparse: state.sparse, bm25: true } : null,
+        degraded: reportedDegraded(state.degraded),
+        manifest: state.manifest ? manifestSummary() : null,
+        lanes: laneList(),
+        hostSkippedLanes: state.hostSkipped.slice(),
+        wasm: caps ? (caps.dense_wasm ? "dense" : "lite") : null,
+      };
+    }
 
-function handleInit(msg) {
-  if (state.phase === "dead") {
-    postError(null, "search engine crashed; reload the page to retry", true);
-    return;
-  }
-  if (msg.indexUrl) state.indexUrl = String(msg.indexUrl);
-  if (msg.baseUrl != null) state.baseUrl = String(msg.baseUrl);
-  if (msg.version != null) state.version = msg.version ? String(msg.version) : null;
-  if (msg.denseRuntime) state.denseRuntime = String(msg.denseRuntime);
-  if (msg.consent === true) {
-    const lane = currentCandidate();
-    if (lane) state.consent[lane.id] = true;
-    if (msg.consentLane) state.consent[String(msg.consentLane)] = true;
-  }
-  runInit();
-}
+    // -- init ---------------------------------------------------------------
 
-async function runInit() {
-  if (state.initRunning) {
-    state.rerun = true;
-    return;
-  }
-  state.initRunning = true;
-  try {
-    state.phase = "loading";
-    await ensureWasm();
-    await ensureIndex();
-    await ensureDb();
-    await ensureGpu();
-    await ensureSparse();
-    const outcome = await ensureDense();
-    if (outcome === "consent") {
-      state.phase = "awaiting_consent";
-      return;
-    }
-    state.phase = "ready";
-    postReady();
-    evictStaleFiles();
-  } catch (err) {
-    state.phase = isFatal(err) ? "dead" : "error";
-    postStatus("error", {
-      message: describe(err),
-      fatal: isFatal(err),
-      unsupported: isUnsupported(err),
-    });
-  } finally {
-    state.initRunning = false;
-    if (state.rerun) {
-      state.rerun = false;
-      runInit();
+    function handleInit(msg, reply) {
+      if (state.phase === "dead") {
+        postError(reply, null, "search engine crashed; reload the page to retry", true);
+        return Promise.resolve();
+      }
+      if (msg.indexUrl) state.indexUrl = String(msg.indexUrl);
+      if (msg.baseUrl != null) state.baseUrl = String(msg.baseUrl);
+      if (msg.version != null) state.version = msg.version ? String(msg.version) : null;
+      const wasRuntime = state.denseRuntime;
+      const wasLane = state.laneId;
+      if (msg.denseRuntime) state.denseRuntime = String(msg.denseRuntime);
+      if (msg.laneId !== undefined) state.laneId = msg.laneId ? String(msg.laneId) : null;
+      if (state.denseRuntime !== wasRuntime || state.laneId !== wasLane) resetDenseSelection();
+      if (msg.consent === true) {
+        const lane = currentCandidate();
+        if (lane) state.consent[lane.id] = true;
+        if (msg.consentLane) state.consent[String(msg.consentLane)] = true;
+      }
+      return runInit();
     }
-  }
-}
 
-async function ensureWasm() {
-  if (state.wasmReady) return;
-  postStatus("loading_wasm");
-  if (typeof WebAssembly !== "object") {
-    throw unsupported("This browser can't run WebAssembly.");
-  }
-  try {
-    importScripts(lib.assetUrl(state.baseUrl, "eddie-wasm.js", state.version));
-    await wasm_bindgen({ module_or_path: lib.assetUrl(state.baseUrl, "eddie.wasm", state.version) });
-  } catch (err) {
-    if (err instanceof WebAssembly.CompileError || err instanceof WebAssembly.LinkError) {
-      throw unsupported("This browser can't run the search engine (WebAssembly SIMD is required).");
-    }
-    throw err;
-  }
-  state.wasmReady = true;
-}
+    async function runInit() {
+      if (state.initRunning) {
+        state.rerun = true;
+        return;
+      }
+      state.initRunning = true;
+      try {
+        state.phase = "loading";
+        await ensureWasm();
+        await ensureIndex();
+        await ensureDb();
+        await ensureGpu();
+        chooseLanes();
+        await ensureSparse();
+        const outcome = await ensureDense();
+        if (outcome === "consent") {
+          state.phase = "awaiting_consent";
+          return;
+        }
+        if (outcome === "tier") {
+          state.phase = "awaiting_tier";
+          return;
+        }
+        releaseHandoverBytes();
+        state.phase = "ready";
+        postReady();
+        evictStaleFiles();
+      } catch (err) {
+        state.phase = isFatal(err) ? "dead" : "error";
+        postStatus("error", {
+          message: describe(err),
+          fatal: isFatal(err),
+          unsupported: isUnsupported(err),
+        });
+      } finally {
+        state.initRunning = false;
+        if (state.rerun) {
+          state.rerun = false;
+          runInit();
+        }
+      }
+    }
 
-async function ensureIndex() {
-  if (state.indexLoaded) return;
-  if (!state.indexUrl) throw new Error("init: indexUrl is required");
-  postStatus("loading_index", { progress: null });
-  let last = 0;
-  const bytes = await lib.fetchBytes(state.indexUrl, {
-    timeoutMs: 180000,
-    onProgress: (loaded, total) => {
-      const now = Date.now();
-      if (total && now - last < PROGRESS_INTERVAL_MS && loaded !== total) return;
-      last = now;
-      postStatus("loading_index", { progress: total ? loaded / total : null, loaded, total });
-    },
-  });
-  state.manifest = JSON.parse(wasm_bindgen.manifest(bytes));
-  wasm_bindgen.init_index(bytes);
-  state.indexLoaded = true;
-  state.dense = null;
-  state.sparse = false;
-  state.degraded = [];
-  state.laneIndex = 0;
-  postStatus("index_ready", { manifest: manifestSummary(), lanes: laneList() });
-}
+    async function loadWasmVariant(variant) {
+      if (typeof WebAssembly !== "object") {
+        throw unsupported("This browser can't run WebAssembly.");
+      }
+      let api;
+      try {
+        api = await env.loadWasm(state.baseUrl, variant);
+      } catch (err) {
+        if (typeof WebAssembly === "object" && (err instanceof WebAssembly.CompileError || err instanceof WebAssembly.LinkError)) {
+          throw unsupported("This browser can't run the search engine (WebAssembly SIMD is required).");
+        }
+        throw err;
+      }
+      if (!api || typeof api.search !== "function") {
+        throw new Error(`loadWasm(${variant}) did not return the Eddie WASM API`);
+      }
+      return api;
+    }
+
+    async function ensureWasm() {
+      if (state.wasmReady) return;
+      postStatus("loading_wasm", { variant: "lite" });
+      wasm = await loadWasmVariant("lite");
+      caps = wasmCapabilities(wasm);
+      state.wasmReady = true;
+    }
 
-async function ensureGpu() {
-  if (state.gpu !== null) return;
-  state.gpu = false;
-  try {
-    if (state.denseRuntime !== "wasm" && self.navigator && navigator.gpu && typeof navigator.gpu.requestAdapter === "function") {
-      const adapter = await navigator.gpu.requestAdapter();
-      if (adapter) {
-        state.gpu = {
-          adapter,
-          hasF16: !!(adapter.features && adapter.features.has("shader-f16")),
-          maxBufferSize: adapter.limits ? adapter.limits.maxBufferSize : 0,
-        };
+    /**
+     * Hand the loaded index over to the dense module (candle embedder) when
+     * the running one cannot embed. Everything the lite module was given is
+     * given again: index bytes, attached sidecars, a fetched sparse tokenizer.
+     */
+    async function ensureDenseWasm() {
+      if (caps && caps.dense_wasm) return;
+      if (!state.indexBytes) throw new Error("dense hand-over: index bytes were released");
+      postStatus("loading_wasm", { variant: "dense" });
+      const dense = await loadWasmVariant("dense");
+      const dcaps = wasmCapabilities(dense);
+      if (!dcaps.dense_wasm) throw new Error("eddie-dense.wasm has no CPU embedder (capabilities.dense_wasm is false)");
+      dense.init_index(state.indexBytes);
+      for (const file of state.attachedSidecars) {
+        if (state.sidecarBytes[file]) dense.attach_sidecar(state.sidecarBytes[file]);
       }
+      if (state.sparse && state.sparseBytes) dense.init_sparse_tokenizer(state.sparseBytes);
+      wasm = dense;
+      caps = dcaps;
     }
-  } catch (err) {
-    console.warn("eddie: WebGPU adapter probe failed", err);
-    state.gpu = false;
-  }
-  const choice = lib.chooseDenseLanes(state.manifest, {
-    denseRuntime: state.denseRuntime,
-    hasWebGpu: !!state.gpu,
-  });
-  state.candidates = choice.candidates;
-  state.candidateReason = choice.reason;
-  for (const { lane, reason } of choice.skipped) {
-    console.warn(`eddie: dense lane ${lane.id} skipped: ${reason}`);
-    state.degraded.push(`dense: lane ${lane.id} skipped: ${reason}`);
-  }
-}
 
-async function ensureSparse() {
-  if (state.sparse) return;
-  const spec = state.manifest && state.manifest.sparse;
-  if (!spec) return;
-  if (state.degraded.some((d) => d.startsWith("sparse:"))) return;
-  try {
-    const repo = spec.tokenizer || spec.model;
-    const rev = spec.revision || "main";
-    let bytes = await getModelFile(repo, rev, "tokenizer.json", "sparse");
-    let ok = await lib.verifySha256(bytes, spec.vocab_hash);
-    if (!ok && bytes.fromCache) {
-      await idbDelete(lib.cacheKey(repo, rev, "tokenizer.json"));
-      bytes = await getModelFile(repo, rev, "tokenizer.json", "sparse", { noCache: true });
-      ok = await lib.verifySha256(bytes, spec.vocab_hash);
-    }
-    if (!ok) {
-      throw new Error("tokenizer.json SHA-256 does not match the index's vocab_hash");
-    }
-    wasm_bindgen.init_sparse_tokenizer(bytes);
-    state.sparse = true;
-  } catch (err) {
-    if (isFatal(err)) throw err;
-    console.warn("eddie: sparse arm unavailable", err);
-    state.degraded.push(`sparse: ${describe(err)}`);
-  }
-}
+    /** A wasm-candle lane could still ask for the dense module later. */
+    function handoverPossible() {
+      if (!caps || caps.dense_wasm || state.dense) return false;
+      return state.candidates.slice(state.laneIndex).some((lane) => lib.isWasmLane(lane));
+    }
 
-/** Returns "ok" (a lane is loaded), "consent" (waiting for the visitor) or "none". */
-async function ensureDense() {
-  if (state.dense) return "ok";
-  for (; state.laneIndex < state.candidates.length; state.laneIndex++) {
-    const lane = state.candidates[state.laneIndex];
-    try {
-      const cached = await laneCached(lane);
-      if (!cached && !state.consent[lane.id]) {
-        postStatus("consent_required", {
-          lane: laneSummary(lane),
-          sizeBytes: lib.laneDownloadBytes(lane),
-          saveData: !!(self.navigator && navigator.connection && navigator.connection.saveData),
-        });
-        return "consent";
+    function releaseHandoverBytes() {
+      if (handoverPossible()) return;
+      state.indexBytes = null;
+      state.sparseBytes = null;
+      state.sidecarBytes = Object.create(null);
+    }
+
+    async function ensureIndex() {
+      if (!state.indexUrl) throw new Error("init: indexUrl is required");
+      if (state.indexLoaded && state.loadedIndexUrl === state.indexUrl) return;
+      postStatus("loading_index", { progress: null });
+      let last = 0;
+      const bytes = await lib.fetchBytes(state.indexUrl, {
+        fetch: env.fetch,
+        timeoutMs: 180000,
+        onProgress: (loaded, total) => {
+          const now = Date.now();
+          if (total && now - last < PROGRESS_INTERVAL_MS && loaded !== total) return;
+          last = now;
+          postStatus("loading_index", { progress: total ? loaded / total : null, loaded, total });
+        },
+      });
+      state.manifest = JSON.parse(wasm.manifest(bytes));
+      wasm.init_index(bytes);
+      state.indexBytes = bytes;
+      state.indexLoaded = true;
+      state.loadedIndexUrl = state.indexUrl;
+      state.dense = null;
+      state.sparse = false;
+      state.sparseBytes = null;
+      state.sidecarBytes = Object.create(null);
+      state.attachedSidecars = [];
+      state.degraded = [];
+      state.hostSkipped = [];
+      state.laneIndex = 0;
+      state.gpu = null;
+      state.siteSizes = Object.create(null);
+      postStatus("index_ready", { manifest: manifestSummary(), lanes: laneList(), hostSkippedLanes: state.hostSkipped.slice() });
+    }
+
+    async function ensureGpu() {
+      if (state.gpu !== null) return;
+      state.gpu = false;
+      try {
+        if (state.denseRuntime !== "wasm" && nav && nav.gpu && typeof nav.gpu.requestAdapter === "function") {
+          const adapter = await nav.gpu.requestAdapter();
+          if (adapter) {
+            state.gpu = {
+              adapter,
+              hasF16: !!(adapter.features && adapter.features.has("shader-f16")),
+              maxBufferSize: adapter.limits ? adapter.limits.maxBufferSize : 0,
+            };
+          }
+        }
+      } catch (err) {
+        console.warn("eddie: WebGPU adapter probe failed", err);
+        state.gpu = false;
       }
-      if (lib.isWasmLane(lane)) {
-        await loadWasmLane(lane);
-      } else {
-        await loadWebGpuLane(lane);
+    }
+
+    /**
+     * Pick the dense lanes to try, in order. Runs on every init, not just the
+     * first: the visitor can change `denseRuntime` or pin a lane from the
+     * settings panel at any time, and the answer has to change with it.
+     */
+    function chooseLanes() {
+      const choice = lib.chooseDenseLanes(state.manifest, {
+        denseRuntime: state.denseRuntime,
+        laneId: state.laneId,
+        hasWebGpu: !!state.gpu && canRunWebGpuLane,
+      });
+      state.candidates = choice.candidates;
+      state.candidateReason = choice.reason;
+      if (!canRunWebGpuLane) {
+        state.hostSkipped = (state.manifest.dense || []).filter(lib.isWebGpuLane).map((l) => l.id);
+      }
+      for (const { lane, reason } of choice.skipped) {
+        console.warn(`eddie: dense lane ${lane.id} skipped: ${reason}`);
+        state.degraded.push(`dense: lane ${lane.id} skipped: ${reason}`);
       }
-      return "ok";
-    } catch (err) {
-      if (isFatal(err)) throw err;
-      console.warn(`eddie: dense lane ${lane.id} failed`, err);
-      state.degraded.push(`dense: lane ${lane.id} failed: ${describe(err)}`);
     }
-  }
-  if (state.candidates.length === 0 && state.candidateReason && (state.manifest.dense || []).length > 0) {
-    if (!state.degraded.some((d) => d.startsWith("dense:"))) {
-      state.degraded.push(`dense: ${state.candidateReason}`);
+
+    /**
+     * Forget which dense lane is running so the next init picks again. Called
+     * when the visitor changes the lane or turns the dense arm off.
+     */
+    function resetDenseSelection() {
+      state.dense = null;
+      state.laneIndex = 0;
+      state.degraded = state.degraded.filter((d) => !String(d).startsWith("dense:"));
+      // The hand-over bytes are dropped once no wasm-candle lane is in play
+      // (releaseHandoverBytes). A visitor who then picks the CPU lane needs
+      // them back: re-read the index, which is an immutable-cached fetch.
+      if (!state.indexBytes && !(caps && caps.dense_wasm)) {
+        state.indexLoaded = false;
+      }
     }
-  }
-  return "none";
-}
 
-async function loadWasmLane(lane) {
-  const repo = lib.laneRepo(lane);
-  const rev = lib.laneRevision(lane);
-  const files = lib.laneFiles(lane);
-  const loaded = {};
-  for (const file of files) {
-    loaded[file] = await getModelFile(repo, rev, file, lane.id);
-  }
-  postStatus("loading_model", { lane: laneSummary(lane) });
-  const config = loaded["config.json"];
-  const tokenizer = loaded["tokenizer.json"];
-  const weights = files.map((f) => loaded[f]).find((b, i) => lib.isWeightsFile(files[i]));
-  if (!config || !tokenizer || !weights) {
-    throw new Error(`lane ${lane.id}: runtime.files must include config.json, tokenizer.json and a weights file`);
-  }
-  wasm_bindgen.init_dense_wasm(lane.id, config, tokenizer, weights);
-  state.dense = { lane, kind: "wasm" };
-}
+    /**
+     * The sparse arm: nothing to fetch when the index embeds its vocabulary
+     * (`sparse_ready()` after init_index); otherwise tokenizer.json from the
+     * repo the manifest names, checked against `vocab_hash`.
+     */
+    async function ensureSparse() {
+      if (state.sparse) return;
+      const spec = state.manifest && state.manifest.sparse;
+      if (!spec) return;
+      if (state.degraded.some((d) => d.startsWith("sparse:"))) return;
+      try {
+        if (typeof wasm.sparse_ready === "function" && wasm.sparse_ready()) {
+          state.sparse = true;
+          return;
+        }
+        const repo = spec.tokenizer || spec.model;
+        const rev = spec.revision || "main";
+        let bytes = await getModelFile(repo, rev, "tokenizer.json", "sparse");
+        let ok = await lib.verifySha256(bytes, spec.vocab_hash, env.subtle);
+        if (!ok && bytes.fromCache) {
+          await idbDelete(lib.cacheKey(repo, rev, "tokenizer.json"));
+          bytes = await getModelFile(repo, rev, "tokenizer.json", "sparse", { noCache: true });
+          ok = await lib.verifySha256(bytes, spec.vocab_hash, env.subtle);
+        }
+        if (!ok) {
+          throw new Error("tokenizer.json SHA-256 does not match the index's vocab_hash");
+        }
+        wasm.init_sparse_tokenizer(bytes);
+        state.sparse = true;
+        state.sparseBytes = bytes;
+      } catch (err) {
+        if (isFatal(err)) throw err;
+        console.warn("eddie: sparse arm unavailable", err);
+        state.degraded.push(`sparse: ${describe(err)}`);
+      }
+    }
 
-async function loadWebGpuLane(lane) {
-  const runtime = lane.runtime;
-  postStatus("loading_model", { lane: laneSummary(lane), file: "transformers.js" });
-  const tf = await import(TRANSFORMERS_URL);
-  if (state.db && tf.env) {
-    // Keep the ONNX files in the same IndexedDB store as the wasm lanes: the
-    // Cache API rejects multi-hundred-MB entries on some profiles, and one
-    // store means one eviction policy (evictStaleFiles) and one consent check.
-    tf.env.useCustomCache = true;
-    tf.env.customCache = transformersCache();
-  }
-  const dtype = lib.pickDtype(runtime, state.gpu && state.gpu.hasF16);
-  let last = 0;
-  const extractor = await tf.pipeline("feature-extraction", runtime.repo, {
-    device: "webgpu",
-    dtype,
-    revision: lib.laneRevision(lane),
-    progress_callback: (p) => {
-      if (!p || p.status !== "progress") return;
-      const now = Date.now();
-      if (now - last < PROGRESS_INTERVAL_MS && p.progress < 100) return;
-      last = now;
-      postStatus("downloading_model", {
+    /** Returns "ok" (a lane is loaded), "consent" (waiting for the visitor) or "none". */
+    async function ensureDense() {
+      if (state.dense) return "ok";
+      for (; state.laneIndex < state.candidates.length; state.laneIndex++) {
+        const lane = state.candidates[state.laneIndex];
+        try {
+          const cached = await laneCached(lane);
+          if (!cached && !state.consent[lane.id]) {
+            postStatus("consent_required", Object.assign(await consentDetails(lane), {
+              lanes: laneList(),
+              hostSkippedLanes: state.hostSkipped.slice(),
+            }));
+            return "consent";
+          }
+          await ensureSidecar(lane, "chunks");
+          if (lib.isWasmLane(lane)) {
+            await loadWasmLane(lane);
+          } else {
+            await loadWebGpuLane(lane);
+          }
+          return "ok";
+        } catch (err) {
+          if (isFatal(err)) throw err;
+          if (err && err.eddieTier) {
+            // This host lacks the runtime, another tier has it: let the
+            // widget move the search there and init again.
+            postStatus("tier_required", { tier: String(err.eddieTier), lane: laneSummary(lane), message: describe(err) });
+            return "tier";
+          }
+          console.warn(`eddie: dense lane ${lane.id} failed`, err);
+          state.degraded.push(`dense: lane ${lane.id} failed: ${describe(err)}`);
+        }
+      }
+      if (state.candidates.length === 0 && state.candidateReason && (state.manifest.dense || []).length > 0) {
+        if (!state.degraded.some((d) => d.startsWith("dense:"))) {
+          state.degraded.push(`dense: ${state.candidateReason}`);
+        }
+      }
+      return "none";
+    }
+
+    /** What the consent card needs: the lane, the real download size and where it comes from. */
+    async function consentDetails(lane) {
+      return {
         lane: laneSummary(lane),
-        file: p.file || p.name || "",
-        progress: typeof p.progress === "number" ? p.progress / 100 : null,
-        loaded: p.loaded,
-        total: p.total,
+        sizeBytes: await laneDownloadBytes(lane),
+        origin: lib.laneOrigin(lane),
+        sidecarBytes: lib.laneSidecarBytes(state.manifest, lane.id),
+        saveData: !!(nav && nav.connection && nav.connection.saveData),
+      };
+    }
+
+    /**
+     * Download size of a lane: the byte count the manifest declares
+     * (`runtime.bytes` on a bundled lane) or the table estimate; for a
+     * site-bundled wasm lane whose manifest predates `runtime.bytes`, the
+     * Content-Length of its files (one HEAD per file, same origin), or null
+     * when the server does not say.
+     */
+    async function laneDownloadBytes(lane) {
+      const declared = lib.laneDeclaredBytes(lane);
+      if (declared != null) return declared;
+      // The table estimates describe the HuggingFace originals; a bundled
+      // f16 copy is half that, so measure it rather than estimate.
+      if (lib.laneOrigin(lane) !== "site" || !lib.isWasmLane(lane)) return lib.laneDownloadBytes(lane);
+      if (state.siteSizes[lane.id] !== undefined) return state.siteSizes[lane.id];
+      const doFetch = env.fetch || globalThis.fetch;
+      let total = 0;
+      try {
+        for (const file of lib.laneFiles(lane)) {
+          const res = await doFetch(laneFileUrl(lane, file), { method: "HEAD" });
+          const len = res && res.ok && res.headers && res.headers.get ? Number(res.headers.get("Content-Length")) : NaN;
+          if (!Number.isFinite(len) || len <= 0) {
+            total = null;
+            break;
+          }
+          total += len;
+        }
+      } catch (_) {
+        total = null;
+      }
+      state.siteSizes[lane.id] = total;
+      return total;
+    }
+
+    /** `manifest.sidecars` file for (`scope`, lane), fetched next to the index and attached once. */
+    async function ensureSidecar(lane, scope) {
+      const side = lib.sidecarFor(state.manifest, scope, lane.id);
+      if (!side) return false;
+      if (state.attachedSidecars.includes(side.file)) return true;
+      const url = lib.withVersion(new URL(side.file, state.indexUrl).href, state.version);
+      let last = 0;
+      postStatus("loading_sidecar", { lane: laneSummary(lane), file: side.file, progress: null, loaded: 0, total: side.bytes || null });
+      const bytes = await lib.fetchBytes(url, {
+        fetch: env.fetch,
+        timeoutMs: 180000,
+        onProgress: (loaded, total) => {
+          const now = Date.now();
+          if (total && now - last < PROGRESS_INTERVAL_MS && loaded !== total) return;
+          last = now;
+          postStatus("loading_sidecar", { lane: laneSummary(lane), file: side.file, progress: total ? loaded / total : null, loaded, total });
+        },
       });
-    },
-  });
-  postStatus("loading_model", { lane: laneSummary(lane) });
-  const pooling = runtime.pooling || "mean";
-  const embed = async (text) => {
-    const prefixed = (lane.query_prefix || "") + text;
-    const out = await extractor(prefixed, { pooling, normalize: lane.normalize !== false });
-    const data = out.data instanceof Float32Array ? out.data : Float32Array.from(out.data);
-    if (typeof out.dispose === "function") out.dispose();
-    if (data.length !== lane.dim) {
-      throw new Error(`lane ${lane.id}: model produced ${data.length}-d vectors but the index stores ${lane.dim}-d`);
-    }
-    for (let i = 0; i < data.length; i++) {
-      if (!Number.isFinite(data[i])) {
-        throw new Error(`lane ${lane.id}: model produced a non-finite value at dimension ${i}`);
+      if (typeof wasm.attach_sidecar !== "function") {
+        throw new Error("this WASM build cannot attach sidecars (rebuild the widget)");
       }
+      wasm.attach_sidecar(bytes);
+      state.attachedSidecars.push(side.file);
+      if (handoverPossible()) state.sidecarBytes[side.file] = bytes;
+      return true;
     }
-    return data;
-  };
-  await embed("warm up");
-  state.dense = { lane, kind: "webgpu", embed, dtype };
-  await idbMetaPut(webGpuMarker(lane, dtype), Date.now());
-}
 
-function postReady() {
-  self.postMessage({
-    type: "ready",
-    lanes: laneList(),
-    lane: state.dense ? state.dense.lane.id : null,
-    runtime: state.dense ? state.dense.kind : null,
-    arms: { dense: !!state.dense, sparse: state.sparse, bm25: true },
-    degraded: lib.filterDesignDegraded(unique(state.degraded)),
-    manifest: manifestSummary(),
-  });
-}
+    function laneFileUrl(lane, file) {
+      const site = lib.siteModelUrl(lane, file, state.indexUrl);
+      if (site) return lib.withVersion(site, state.version);
+      return lib.hfFileUrl(lib.laneRepo(lane), lib.laneRevision(lane), file);
+    }
 
-// -- cache check --------------------------------------------------------
-
-async function handleCacheCheck(msg) {
-  try {
-    await ensureWasm();
-    await ensureIndex();
-    await ensureDb();
-    await ensureGpu();
-    const lane = currentCandidate();
-    const cached = lane ? await laneCached(lane) : true;
-    self.postMessage({
-      type: "cache_result",
-      requestId: msg.requestId,
-      cached,
-      lane: lane ? laneSummary(lane) : null,
-      sizeBytes: lane ? lib.laneDownloadBytes(lane) : 0,
-    });
-  } catch (err) {
-    postError(msg.requestId, describe(err), isFatal(err));
-  }
-}
+    async function loadWasmLane(lane) {
+      const repo = lib.laneRepo(lane);
+      const rev = lib.laneRevision(lane);
+      const files = lib.laneFiles(lane);
+      const loaded = {};
+      for (const file of files) {
+        loaded[file] = await getModelFile(repo, rev, file, lane.id, { url: laneFileUrl(lane, file), name: lib.laneFileName(lane, file) });
+      }
+      await ensureDenseWasm();
+      postStatus("loading_model", { lane: laneSummary(lane) });
+      const config = loaded["config.json"];
+      const tokenizer = loaded["tokenizer.json"];
+      const weightsName = files.find((f) => lib.isWeightsFile(f));
+      const weights = weightsName ? loaded[weightsName] : undefined;
+      if (!config || !tokenizer || !weights) {
+        throw new Error(`lane ${lane.id}: runtime.files must include config.json, tokenizer.json and a weights file`);
+      }
+      wasm.init_dense_wasm(lane.id, config, tokenizer, weights);
+      state.dense = { lane, kind: "wasm" };
+    }
+
+    async function loadWebGpuLane(lane) {
+      const runtime = lane.runtime;
+      postStatus("loading_model", { lane: laneSummary(lane), file: "transformers.js" });
+      const tf = await env.loadTransformers();
+      if (state.db && tf.env) {
+        // Keep the ONNX files in the same IndexedDB store as the wasm lanes: the
+        // Cache API rejects multi-hundred-MB entries on some profiles, and one
+        // store means one eviction policy (evictStaleFiles) and one consent check.
+        tf.env.useCustomCache = true;
+        tf.env.customCache = transformersCache();
+      }
+      if (tf.env) configureModelSource(tf.env, lane);
+      if (env.configureTransformers) env.configureTransformers(tf);
+      const dtype = lib.pickDtype(runtime, state.gpu && state.gpu.hasF16);
+      let last = 0;
+      const extractor = await tf.pipeline("feature-extraction", runtime.repo, {
+        device: "webgpu",
+        dtype,
+        revision: lib.laneRevision(lane),
+        progress_callback: (p) => {
+          if (!p || p.status !== "progress") return;
+          const now = Date.now();
+          if (now - last < PROGRESS_INTERVAL_MS && p.progress < 100) return;
+          last = now;
+          postStatus("downloading_model", {
+            lane: laneSummary(lane),
+            file: p.file || p.name || "",
+            progress: typeof p.progress === "number" ? p.progress / 100 : null,
+            loaded: p.loaded,
+            total: p.total,
+          });
+        },
+      });
+      postStatus("loading_model", { lane: laneSummary(lane) });
+      const pooling = runtime.pooling || "mean";
+      const embed = async (text) => {
+        const prefixed = (lane.query_prefix || "") + text;
+        const out = await extractor(prefixed, { pooling, normalize: lane.normalize !== false });
+        const data = out.data instanceof Float32Array ? out.data : Float32Array.from(out.data);
+        if (typeof out.dispose === "function") out.dispose();
+        if (data.length !== lane.dim) {
+          throw new Error(`lane ${lane.id}: model produced ${data.length}-d vectors but the index stores ${lane.dim}-d`);
+        }
+        for (let i = 0; i < data.length; i++) {
+          if (!Number.isFinite(data[i])) {
+            throw new Error(`lane ${lane.id}: model produced a non-finite value at dimension ${i}`);
+          }
+        }
+        return data;
+      };
+      await embed("warm up");
+      state.dense = { lane, kind: "webgpu", embed, dtype };
+      await idbMetaPut(webGpuMarker(lane, dtype), Date.now());
+    }
 
-async function laneCached(lane) {
-  if (lib.isWasmLane(lane)) {
-    if (!state.db) return false;
-    const repo = lib.laneRepo(lane);
-    const rev = lib.laneRevision(lane);
-    for (const file of lib.laneFiles(lane)) {
-      if (!(await idbHas(lib.cacheKey(repo, rev, file)))) return false;
+    /**
+     * Point transformers.js at the site-hosted copy of a webgpu-onnx repo
+     * when the manifest gives one (`runtime.base_url`, relative to the index
+     * URL; the directory mirrors the repo's file layout: config.json,
+     * tokenizer.json, onnx/model_q4.onnx ...). transformers.js joins
+     * remoteHost, remotePathTemplate and the file name with "/"; "." as the
+     * template keeps the model id out of the path and the URL parser folds
+     * the "./" away. Without a base_url the defaults (huggingface.co) are
+     * restored, since these settings are global to the module.
+     */
+    function configureModelSource(tfEnv, lane) {
+      const base = lib.siteModelUrl(lane, "", state.indexUrl);
+      if (base) {
+        tfEnv.allowRemoteModels = true;
+        tfEnv.remoteHost = base;
+        tfEnv.remotePathTemplate = ".";
+      } else {
+        tfEnv.remoteHost = "https://huggingface.co/";
+        tfEnv.remotePathTemplate = "{model}/resolve/{revision}/";
+      }
     }
-    return true;
-  }
-  const dtype = lib.pickDtype(lane.runtime, state.gpu && state.gpu.hasF16);
-  return !!(await idbMetaGet(webGpuMarker(lane, dtype)));
-}
 
-function webGpuMarker(lane, dtype) {
-  return `webgpu:${lane.runtime.repo}@${lib.laneRevision(lane)}#${dtype}`;
-}
+    function readyMessage() {
+      return {
+        type: "ready",
+        lanes: laneList(),
+        lane: state.dense ? state.dense.lane.id : null,
+        runtime: state.dense ? state.dense.kind : null,
+        arms: { dense: !!state.dense, sparse: state.sparse, bm25: true },
+        degraded: reportedDegraded(state.degraded),
+        manifest: manifestSummary(),
+        hostSkippedLanes: state.hostSkipped.slice(),
+        wasm: caps && caps.dense_wasm ? "dense" : "lite",
+      };
+    }
 
-// -- queries ------------------------------------------------------------
-
-/**
- * Query vector from the WebGPU lane, or nothing (the WASM lane embeds inside
- * search()). An embedding failure degrades the dense arm for this query
- * instead of failing the search; `note` carries the reason.
- */
-async function queryVector(query, mode) {
-  if (!state.dense || state.dense.kind !== "webgpu") return { laneId: null, vec: null, note: null };
-  if (mode !== "hybrid" && mode !== "dense") return { laneId: null, vec: null, note: null };
-  try {
-    const vec = await state.dense.embed(query);
-    return { laneId: state.dense.lane.id, vec, note: null };
-  } catch (err) {
-    console.warn(`eddie: dense lane ${state.dense.lane.id} query embedding failed`, err);
-    return { laneId: null, vec: null, note: `dense: embedding failed for lane ${state.dense.lane.id}: ${describe(err)}` };
-  }
-}
+    function postReady() {
+      post(readyMessage());
+    }
 
-async function handleSearch(msg) {
-  const requestId = msg.requestId;
-  try {
-    requireIndex();
-    const query = String(msg.query || "").trim();
-    if (!query) throw new Error("search: empty query");
-    const mode = msg.mode || "hybrid";
-    const topK = Number(msg.topK) > 0 ? Number(msg.topK) : 8;
-    const { laneId, vec, note } = await queryVector(query, mode);
-    const res = JSON.parse(wasm_bindgen.search(query, topK, mode, laneId, vec));
-    if (note) res.degraded = (res.degraded || []).concat([note]);
-    const results = res.results || [];
-    if (msg.evidence) {
-      for (const r of results) {
-        try {
-          r.text = JSON.parse(wasm_bindgen.chunk(r.chunk)).text;
-        } catch (_) {
-          r.text = r.snippet;
+    // -- cache check --------------------------------------------------------
+
+    async function handleCacheCheck(msg, reply) {
+      try {
+        if (state.phase === "dead") throw fatal("search engine crashed; reload to retry");
+        if (msg.indexUrl) state.indexUrl = String(msg.indexUrl);
+        if (msg.baseUrl != null) state.baseUrl = String(msg.baseUrl);
+        if (msg.version != null) state.version = msg.version ? String(msg.version) : null;
+        if (msg.denseRuntime) state.denseRuntime = String(msg.denseRuntime);
+        if (msg.laneId !== undefined) state.laneId = msg.laneId ? String(msg.laneId) : null;
+        await ensureWasm();
+        await ensureIndex();
+        await ensureDb();
+        await ensureGpu();
+        chooseLanes();
+        const lane = currentCandidate();
+        const cached = lane ? await laneCached(lane) : true;
+        reply({
+          type: "cache_result",
+          requestId: msg.requestId,
+          cached,
+          lanes: laneList(),
+          lane: lane ? laneSummary(lane) : null,
+          sizeBytes: lane ? await laneDownloadBytes(lane) : 0,
+          origin: lane ? lib.laneOrigin(lane) : null,
+          sidecarBytes: lane ? lib.laneSidecarBytes(state.manifest, lane.id) : 0,
+          hostSkippedLanes: state.hostSkipped.slice(),
+          phase: state.phase,
+        });
+      } catch (err) {
+        if (isFatal(err)) state.phase = "dead";
+        postError(reply, msg.requestId, describe(err), isFatal(err));
+      }
+    }
+
+    /**
+     * Delete every cached model file. The engine keeps whatever it has
+     * already loaded into memory for this session; the files come back on the
+     * next visit that needs them.
+     */
+    async function handleCacheClear(msg, reply) {
+      let freedBytes = 0;
+      try {
+        await ensureDb();
+        const keys = (await idbRequest(IDB_FILES, "readonly", (s) => s.getAllKeys())) || [];
+        for (const key of keys) {
+          const value = await idbGet(key);
+          freedBytes += value ? (typeof value.size === "number" ? value.size : value.byteLength || 0) : 0;
+          await idbDelete(key);
         }
+        const metaKeys = (await idbRequest(IDB_META, "readonly", (s) => s.getAllKeys())) || [];
+        for (const key of metaKeys) {
+          await idbRequest(IDB_META, "readwrite", (s) => s.delete(key));
+        }
+      } catch (err) {
+        console.warn("eddie: could not clear the model cache", err);
       }
+      reply({ type: "cache_clear_result", requestId: msg.requestId, freedBytes });
     }
-    let qa = undefined;
-    if (msg.qa && Number(msg.qa) > 0 && hasSection("qa") && (vec || !laneId)) {
-      qa = JSON.parse(wasm_bindgen.qa_lookup(query, laneId, vec, Number(msg.qa)));
-    }
-    self.postMessage({
-      type: "search_result",
-      requestId,
-      results,
-      arms: res.arms,
-      degraded: lib.filterDesignDegraded(unique((res.degraded || []).concat(state.degraded))),
-      mode: res.mode,
-      lane: res.dense_lane || null,
-      qa,
-    });
-  } catch (err) {
-    failRequest(requestId, err);
-  }
-}
 
-function handleLookup(msg, type, key, fn) {
-  try {
-    requireIndex();
-    self.postMessage({ type, requestId: msg.requestId, [key]: JSON.parse(fn()) });
-  } catch (err) {
-    failRequest(msg.requestId, err);
-  }
-}
+    async function laneCached(lane) {
+      if (lib.isWasmLane(lane)) {
+        if (!state.db) return false;
+        const repo = lib.laneRepo(lane);
+        const rev = lib.laneRevision(lane);
+        for (const file of lib.laneFiles(lane)) {
+          if (!(await idbHas(lib.cacheKey(repo, rev, lib.laneFileName(lane, file))))) return false;
+        }
+        return true;
+      }
+      const dtype = lib.pickDtype(lane.runtime, state.gpu && state.gpu.hasF16);
+      return !!(await idbMetaGet(webGpuMarker(lane, dtype)));
+    }
 
-async function handleQa(msg) {
-  try {
-    requireIndex();
-    const query = String(msg.query || "").trim();
-    const k = Number(msg.k) > 0 ? Number(msg.k) : 3;
-    if (!query || !hasSection("qa")) {
-      self.postMessage({ type: "qa_result", requestId: msg.requestId, hits: [] });
-      return;
-    }
-    const { laneId, vec } = await queryVector(query, "dense");
-    const hits = JSON.parse(wasm_bindgen.qa_lookup(query, laneId, vec, k));
-    self.postMessage({ type: "qa_result", requestId: msg.requestId, hits });
-  } catch (err) {
-    failRequest(msg.requestId, err);
-  }
-}
+    function webGpuMarker(lane, dtype) {
+      return `webgpu:${lane.runtime.repo}@${lib.laneRevision(lane)}#${dtype}`;
+    }
 
-function failRequest(requestId, err) {
-  if (isFatal(err)) {
-    // A trapped panic leaves the WASM instance unusable; never re-enter it.
-    state.phase = "dead";
-    postError(requestId, "search engine crashed: " + describe(err), true);
-    return;
-  }
-  postError(requestId, describe(err), false);
-}
+    // -- queries ------------------------------------------------------------
 
-function requireIndex() {
-  if (state.phase === "dead") throw fatal("search engine crashed; reload to retry");
-  if (!state.indexLoaded) throw new Error("index not loaded yet");
-}
+    /**
+     * Query vector from the WebGPU lane, or nothing (the WASM lane embeds inside
+     * search()). An embedding failure degrades the dense arm for this query
+     * instead of failing the search; `note` carries the reason.
+     */
+    async function queryVector(query, mode) {
+      if (!state.dense || state.dense.kind !== "webgpu") return { laneId: null, vec: null, note: null };
+      if (mode !== "hybrid" && mode !== "dense") return { laneId: null, vec: null, note: null };
+      try {
+        const vec = await state.dense.embed(query);
+        return { laneId: state.dense.lane.id, vec, note: null };
+      } catch (err) {
+        console.warn(`eddie: dense lane ${state.dense.lane.id} query embedding failed`, err);
+        return { laneId: null, vec: null, note: `dense: embedding failed for lane ${state.dense.lane.id}: ${describe(err)}` };
+      }
+    }
 
-function hasSection(name) {
-  return !!(state.manifest && Array.isArray(state.manifest.sections) && state.manifest.sections.includes(name));
-}
+    /**
+     * The qa-scope vectors of the active lane live in a sidecar the first QA
+     * lookup fetches (never before: most searches never show the FAQ card).
+     * A failed fetch leaves the lexical ranking in place.
+     */
+    async function ensureQaVectors() {
+      if (!state.dense || !hasSection("qa")) return;
+      try {
+        await ensureSidecar(state.dense.lane, "qa");
+      } catch (err) {
+        if (isFatal(err)) throw err;
+        console.warn("eddie: qa sidecar unavailable; FAQ ranking is lexical", err);
+      }
+    }
+
+    async function handleSearch(msg, reply) {
+      const requestId = msg.requestId;
+      try {
+        requireIndex();
+        const query = String(msg.query || "").trim();
+        if (!query) throw new Error("search: empty query");
+        const mode = msg.mode || "hybrid";
+        const topK = Number(msg.topK) > 0 ? Number(msg.topK) : 8;
+        const { laneId, vec, note } = await queryVector(query, mode);
+        const res = JSON.parse(wasm.search(query, topK, mode, laneId, vec));
+        if (note) res.degraded = (res.degraded || []).concat([note]);
+        const results = res.results || [];
+        if (msg.evidence) {
+          for (const r of results) {
+            try {
+              r.text = JSON.parse(wasm.chunk(r.chunk)).text;
+            } catch (_) {
+              r.text = r.snippet;
+            }
+          }
+        }
+        let qa = undefined;
+        if (msg.qa && Number(msg.qa) > 0 && hasSection("qa") && (vec || !laneId)) {
+          await ensureQaVectors();
+          qa = JSON.parse(wasm.qa_lookup(query, laneId, vec, Number(msg.qa)));
+        }
+        reply({
+          type: "search_result",
+          requestId,
+          results,
+          arms: res.arms,
+          degraded: reportedDegraded((res.degraded || []).concat(state.degraded)),
+          mode: res.mode,
+          lane: res.dense_lane || null,
+          qa,
+        });
+      } catch (err) {
+        failRequest(reply, requestId, err);
+      }
+    }
+
+    function handleLookup(msg, reply, type, key, fn) {
+      try {
+        requireIndex();
+        reply({ type, requestId: msg.requestId, [key]: JSON.parse(fn()) });
+      } catch (err) {
+        failRequest(reply, msg.requestId, err);
+      }
+      return Promise.resolve();
+    }
+
+    async function handleQa(msg, reply) {
+      try {
+        requireIndex();
+        const query = String(msg.query || "").trim();
+        const k = Number(msg.k) > 0 ? Number(msg.k) : 3;
+        if (!query || !hasSection("qa")) {
+          reply({ type: "qa_result", requestId: msg.requestId, hits: [] });
+          return;
+        }
+        await ensureQaVectors();
+        const { laneId, vec } = await queryVector(query, "dense");
+        const hits = JSON.parse(wasm.qa_lookup(query, laneId, vec, k));
+        reply({ type: "qa_result", requestId: msg.requestId, hits });
+      } catch (err) {
+        failRequest(reply, msg.requestId, err);
+      }
+    }
+
+    function failRequest(reply, requestId, err) {
+      if (isFatal(err)) {
+        // A trapped panic leaves the WASM instance unusable; never re-enter it.
+        state.phase = "dead";
+        postError(reply, requestId, "search engine crashed: " + describe(err), true);
+        return;
+      }
+      postError(reply, requestId, describe(err), false);
+    }
 
-// -- model files --------------------------------------------------------
+    function requireIndex() {
+      if (state.phase === "dead") throw fatal("search engine crashed; reload to retry");
+      if (!state.indexLoaded) throw new Error(NOT_LOADED);
+    }
 
-async function getModelFile(repo, rev, file, laneId, opts) {
-  const key = lib.cacheKey(repo, rev, file);
-  if (!(opts && opts.noCache)) {
-    const cached = await idbGet(key);
-    if (cached) {
-      const bytes = new Uint8Array(cached);
-      bytes.fromCache = true;
+    function hasSection(name) {
+      return !!(state.manifest && Array.isArray(state.manifest.sections) && state.manifest.sections.includes(name));
+    }
+
+    // -- model files --------------------------------------------------------
+
+    /**
+     * A model file from the IndexedDB cache or the network. `opts.url` and
+     * `opts.name` override the HuggingFace URL and cache name (site-bundled
+     * files); `opts.noCache` skips the cache read.
+     */
+    async function getModelFile(repo, rev, file, laneId, opts) {
+      const o = opts || {};
+      const key = lib.cacheKey(repo, rev, o.name || file);
+      if (!o.noCache) {
+        const cached = await idbGet(key);
+        if (cached) {
+          const bytes = new Uint8Array(cached);
+          bytes.fromCache = true;
+          return bytes;
+        }
+      }
+      const url = o.url || lib.hfFileUrl(repo, rev, file);
+      let last = 0;
+      postStatus("downloading_model", { lane: laneId, file, progress: null, loaded: 0, total: null });
+      const bytes = await lib.fetchBytes(url, {
+        fetch: env.fetch,
+        timeoutMs: lib.timeoutForFile(file),
+        retries: 1,
+        backoffMs: 1500,
+        onProgress: (loaded, total) => {
+          const now = Date.now();
+          if (now - last < PROGRESS_INTERVAL_MS && !(total && loaded === total)) return;
+          last = now;
+          postStatus("downloading_model", { lane: laneId, file, progress: total ? loaded / total : null, loaded, total });
+        },
+      });
+      await idbPut(key, bytes.buffer);
       return bytes;
     }
-  }
-  const url = lib.hfFileUrl(repo, rev, file);
-  let last = 0;
-  postStatus("downloading_model", { lane: laneId, file, progress: null, loaded: 0, total: null });
-  const bytes = await lib.fetchBytes(url, {
-    timeoutMs: lib.timeoutForFile(file),
-    retries: 1,
-    backoffMs: 1500,
-    onProgress: (loaded, total) => {
-      const now = Date.now();
-      if (now - last < PROGRESS_INTERVAL_MS && !(total && loaded === total)) return;
-      last = now;
-      postStatus("downloading_model", { lane: laneId, file, progress: total ? loaded / total : null, loaded, total });
-    },
-  });
-  await idbPut(key, bytes.buffer);
-  return bytes;
-}
 
-// -- IndexedDB (best effort: any failure only logs) --------------------
-
-async function ensureDb() {
-  if (state.db !== undefined) return;
-  state.db = null;
-  if (typeof indexedDB === "undefined") return;
-  try {
-    state.db = await new Promise((resolve, reject) => {
-      const req = indexedDB.open(IDB_NAME, IDB_VERSION);
-      req.onupgradeneeded = () => {
-        const db = req.result;
-        if (!db.objectStoreNames.contains(IDB_FILES)) db.createObjectStore(IDB_FILES);
-        if (!db.objectStoreNames.contains(IDB_META)) db.createObjectStore(IDB_META);
+    // -- IndexedDB (best effort: any failure only logs) --------------------
+
+    async function ensureDb() {
+      if (state.db !== undefined) return;
+      state.db = null;
+      if (!idb) return;
+      try {
+        state.db = await new Promise((resolve, reject) => {
+          const req = idb.open(IDB_NAME, IDB_VERSION);
+          req.onupgradeneeded = () => {
+            const db = req.result;
+            if (!db.objectStoreNames.contains(IDB_FILES)) db.createObjectStore(IDB_FILES);
+            if (!db.objectStoreNames.contains(IDB_META)) db.createObjectStore(IDB_META);
+          };
+          req.onsuccess = () => resolve(req.result);
+          req.onerror = () => reject(req.error || new Error("indexedDB.open failed"));
+          req.onblocked = () => reject(new Error("indexedDB.open blocked"));
+        });
+      } catch (err) {
+        console.warn("eddie: model cache unavailable; files will be re-downloaded next visit", err);
+        state.db = null;
+      }
+    }
+
+    function idbRequest(store, mode, fn) {
+      if (!state.db) return Promise.resolve(undefined);
+      return new Promise((resolve) => {
+        try {
+          const tx = state.db.transaction(store, mode);
+          const req = fn(tx.objectStore(store));
+          req.onsuccess = () => resolve(req.result);
+          req.onerror = () => {
+            console.warn("eddie: model cache operation failed", req.error);
+            resolve(undefined);
+          };
+        } catch (err) {
+          console.warn("eddie: model cache operation failed", err);
+          resolve(undefined);
+        }
+      });
+    }
+
+    const idbGet = (key) => idbRequest(IDB_FILES, "readonly", (s) => s.get(key));
+    const idbHas = async (key) => (await idbRequest(IDB_FILES, "readonly", (s) => s.getKey(key))) !== undefined;
+    const idbPut = (key, value) => idbRequest(IDB_FILES, "readwrite", (s) => s.put(value, key));
+    const idbDelete = (key) => idbRequest(IDB_FILES, "readwrite", (s) => s.delete(key));
+    const idbMetaGet = (key) => idbRequest(IDB_META, "readonly", (s) => s.get(key));
+    const idbMetaPut = (key, value) => idbRequest(IDB_META, "readwrite", (s) => s.put(value, key));
+
+    /**
+     * transformers.js cache (`env.customCache`) over the model-file store.
+     * transformers.js calls `match`/`put` with string keys: the HuggingFace URL
+     * for remote files (mapped onto the repo@revision/file scheme) or a local
+     * model path (never stored, so `match` misses and the URL key is tried next).
+     */
+    function transformersCache() {
+      const keyOf = (req) => {
+        const url = typeof req === "string" ? req : req && req.url ? req.url : String(req);
+        return lib.cacheKeyFromUrl(url) || "url:" + url;
       };
-      req.onsuccess = () => resolve(req.result);
-      req.onerror = () => reject(req.error || new Error("indexedDB.open failed"));
-      req.onblocked = () => reject(new Error("indexedDB.open blocked"));
-    });
-  } catch (err) {
-    console.warn("eddie: model cache unavailable; files will be re-downloaded next visit", err);
-    state.db = null;
-  }
-}
+      return {
+        async match(req) {
+          const stored = await idbGet(keyOf(req));
+          if (!stored) return undefined;
+          const size = typeof stored.size === "number" ? stored.size : stored.byteLength;
+          return new Response(stored, { headers: { "Content-Length": String(size) } });
+        },
+        async put(req, response) {
+          const blob = await response.blob();
+          await idbPut(keyOf(req), blob);
+        },
+      };
+    }
+
+    /** Delete cached files that belong to models this index no longer references. */
+    async function evictStaleFiles() {
+      if (!state.db || !state.manifest) return;
+      const keep = ["url:"];
+      for (const lane of state.manifest.dense || []) {
+        keep.push(`${lib.laneRepo(lane)}@${lib.laneRevision(lane)}/`);
+      }
+      if (state.manifest.sparse) {
+        const s = state.manifest.sparse;
+        keep.push(`${s.tokenizer || s.model}@${s.revision || "main"}/`);
+      }
+      const keys = await idbRequest(IDB_FILES, "readonly", (s) => s.getAllKeys());
+      for (const key of keys || []) {
+        if (typeof key === "string" && !keep.some((p) => key.startsWith(p))) {
+          console.info("eddie: evicting cached model file", key);
+          await idbDelete(key);
+        }
+      }
+    }
+
+    // -- helpers ------------------------------------------------------------
 
-function idbRequest(store, mode, fn) {
-  if (!state.db) return Promise.resolve(undefined);
-  return new Promise((resolve) => {
-    try {
-      const tx = state.db.transaction(store, mode);
-      const req = fn(tx.objectStore(store));
-      req.onsuccess = () => resolve(req.result);
-      req.onerror = () => {
-        console.warn("eddie: model cache operation failed", req.error);
-        resolve(undefined);
+    function currentCandidate() {
+      return state.candidates[state.laneIndex] || null;
+    }
+
+    function laneSummary(lane) {
+      return {
+        id: lane.id,
+        model: lane.model,
+        kind: lane.runtime ? lane.runtime.kind : null,
+        repo: lib.laneRepo(lane),
+        dim: lane.dim,
+        origin: lib.laneOrigin(lane),
       };
-    } catch (err) {
-      console.warn("eddie: model cache operation failed", err);
-      resolve(undefined);
     }
-  });
-}
 
-const idbGet = (key) => idbRequest(IDB_FILES, "readonly", (s) => s.get(key));
-const idbHas = async (key) => (await idbRequest(IDB_FILES, "readonly", (s) => s.getKey(key))) !== undefined;
-const idbPut = (key, value) => idbRequest(IDB_FILES, "readwrite", (s) => s.put(value, key));
-const idbDelete = (key) => idbRequest(IDB_FILES, "readwrite", (s) => s.delete(key));
-const idbMetaGet = (key) => idbRequest(IDB_META, "readonly", (s) => s.get(key));
-const idbMetaPut = (key, value) => idbRequest(IDB_META, "readwrite", (s) => s.put(value, key));
-
-/**
- * transformers.js cache (`env.customCache`) over the model-file store.
- * transformers.js calls `match`/`put` with string keys: the HuggingFace URL
- * for remote files (mapped onto the repo@revision/file scheme) or a local
- * model path (never stored, so `match` misses and the URL key is tried next).
- */
-function transformersCache() {
-  const keyOf = (req) => {
-    const url = typeof req === "string" ? req : req && req.url ? req.url : String(req);
-    return lib.cacheKeyFromUrl(url) || "url:" + url;
-  };
-  return {
-    async match(req) {
-      const stored = await idbGet(keyOf(req));
-      if (!stored) return undefined;
-      const size = typeof stored.size === "number" ? stored.size : stored.byteLength;
-      return new Response(stored, { headers: { "Content-Length": String(size) } });
-    },
-    async put(req, response) {
-      const blob = await response.blob();
-      await idbPut(keyOf(req), blob);
-    },
-  };
-}
+    function laneList() {
+      return (state.manifest && state.manifest.dense ? state.manifest.dense : []).map(laneSummary);
+    }
 
-/** Delete cached files that belong to models this index no longer references. */
-async function evictStaleFiles() {
-  if (!state.db || !state.manifest) return;
-  const keep = ["url:"];
-  for (const lane of state.manifest.dense || []) {
-    keep.push(`${lib.laneRepo(lane)}@${lib.laneRevision(lane)}/`);
+    function manifestSummary() {
+      const m = state.manifest || {};
+      return {
+        format: m.format,
+        eddie: m.eddie,
+        chunks: m.chunks,
+        pages: m.pages,
+        sections: m.sections || [],
+        sparse: !!m.sparse,
+        sidecars: Array.isArray(m.sidecars) ? m.sidecars.length : 0,
+      };
+    }
+
+    function postStatus(stateName, extra) {
+      post(Object.assign({ type: "status", state: stateName }, extra || {}));
+    }
+
+    function postError(reply, requestId, message, isFatalErr, isUnsupportedErr) {
+      reply({ type: "error", requestId: requestId == null ? undefined : requestId, message, fatal: !!isFatalErr, unsupported: !!isUnsupportedErr });
+    }
+
+    return {
+      handle,
+      state: snapshot,
+      readyMessage,
+      get phase() {
+        return state.phase;
+      },
+    };
   }
-  if (state.manifest.sparse) {
-    const s = state.manifest.sparse;
-    keep.push(`${s.tokenizer || s.model}@${s.revision || "main"}/`);
+
+  function unique(list) {
+    return Array.from(new Set(list));
   }
-  const keys = await idbRequest(IDB_FILES, "readonly", (s) => s.getAllKeys());
-  for (const key of keys || []) {
-    if (typeof key === "string" && !keep.some((p) => key.startsWith(p))) {
-      console.info("eddie: evicting cached model file", key);
-      await idbDelete(key);
-    }
+
+  function describe(err) {
+    if (err == null) return "unknown error";
+    if (typeof err === "string") return err;
+    if (err.message) return err.message;
+    return String(err);
   }
-}
 
-// -- helpers ------------------------------------------------------------
+  function unsupported(message) {
+    const e = new Error(message);
+    e.eddieUnsupported = true;
+    e.eddieFatal = true;
+    return e;
+  }
 
-function currentCandidate() {
-  return state.candidates[state.laneIndex] || null;
-}
+  function fatal(message) {
+    const e = new Error(message);
+    e.eddieFatal = true;
+    return e;
+  }
 
-function laneSummary(lane) {
-  return {
-    id: lane.id,
-    model: lane.model,
-    kind: lane.runtime ? lane.runtime.kind : null,
-    repo: lib.laneRepo(lane),
-    dim: lane.dim,
-  };
-}
+  function isUnsupported(err) {
+    return !!(err && err.eddieUnsupported);
+  }
 
-function laneList() {
-  return (state.manifest && state.manifest.dense ? state.manifest.dense : []).map(laneSummary);
-}
+  function isFatal(err) {
+    if (!err) return false;
+    if (err.eddieFatal) return true;
+    return typeof WebAssembly === "object" && err instanceof WebAssembly.RuntimeError;
+  }
 
-function manifestSummary() {
-  const m = state.manifest || {};
-  return {
-    format: m.format,
-    eddie: m.eddie,
-    chunks: m.chunks,
-    pages: m.pages,
-    sections: m.sections || [],
-    sparse: !!m.sparse,
-  };
-}
+  /** True for the engine's "not initialised" replies (the client re-runs init). */
+  function isNotLoadedMessage(message) {
+    return typeof message === "string" && message.indexOf(NOT_LOADED) === 0;
+  }
 
-function unique(list) {
-  return Array.from(new Set(list));
-}
+  return { createSearchEngine, wasmCapabilities, NOT_LOADED, isNotLoadedMessage };
+});
 
-function postStatus(stateName, extra) {
-  self.postMessage(Object.assign({ type: "status", state: stateName }, extra || {}));
-}
+// SPDX-License-Identifier: GPL-3.0-only
 
-function postError(requestId, message, isFatalErr, isUnsupported) {
-  self.postMessage({ type: "error", requestId: requestId == null ? undefined : requestId, message, fatal: !!isFatalErr, unsupported: !!isUnsupported });
-}
+// Eddie search worker (classic dedicated worker): the fallback host when the
+// service worker (eddie-sw.js) is unavailable, and the same protocol either
+// way. The engine itself is widget/src/lib/search-engine.js; this file only
+// binds it to a dedicated worker: the WASM glue comes in through
+// importScripts (no-modules builds: eddie-lite.js first, eddie-dense.js only
+// when a CPU dense lane is about to run) and transformers.js through a
+// dynamic import(). widget/build.sh concatenates widget/src/lib/*.js ahead
+// of this file, so the helpers are available as `EddieLib`.
+//
+// Protocol: see widget/README.md ("Worker protocol").
 
-function describe(err) {
-  if (err == null) return "unknown error";
-  if (typeof err === "string") return err;
-  if (err.message) return err.message;
-  return String(err);
-}
+"use strict";
 
-function unsupported(message) {
-  const e = new Error(message);
-  e.eddieUnsupported = true;
-  e.eddieFatal = true;
-  return e;
-}
+const TRANSFORMERS_URL = "https://cdn.jsdelivr.net/npm/@huggingface/transformers@4.2.0";
 
-function fatal(message) {
-  const e = new Error(message);
-  e.eddieFatal = true;
-  return e;
-}
+const lib = EddieLib;
 
-function isUnsupported(err) {
-  return !!(err && err.eddieUnsupported);
+const loaded = {}; // variant -> Promise of the wasm-bindgen API object
+
+function loadVariant(baseUrl, variant) {
+  if (variant !== "lite" && variant !== "dense") throw new Error(`unknown wasm variant ${String(variant)}`);
+  if (!loaded[variant]) {
+    loaded[variant] = (async () => {
+      importScripts(lib.assetUrl(baseUrl, `eddie-${variant}.js`, lib.ASSET_VERSION));
+      // eddie-dense.js is renamed by build.sh so both glues can share this
+      // global scope (a second `let wasm_bindgen` would be a SyntaxError).
+      const api = variant === "dense" ? wasm_bindgen_dense : wasm_bindgen;
+      await api({ module_or_path: lib.assetUrl(baseUrl, `eddie-${variant}.wasm`, lib.ASSET_VERSION) });
+      return api;
+    })();
+    loaded[variant].catch(() => {
+      delete loaded[variant]; // a failed fetch may be retried
+    });
+  }
+  return loaded[variant];
 }
 
-function isFatal(err) {
-  if (!err) return false;
-  if (err.eddieFatal) return true;
-  return typeof WebAssembly === "object" && err instanceof WebAssembly.RuntimeError;
-}
+const engine = lib.createSearchEngine({
+  post: (message) => self.postMessage(message),
+  loadWasm: (baseUrl, variant) => loadVariant(baseUrl, variant || "lite"),
+  loadTransformers: () => import(TRANSFORMERS_URL),
+  canRunWebGpuLane: true,
+});
+
+self.onmessage = function (e) {
+  engine.handle(e.data || {}, (message) => self.postMessage(message));
+};