@supersoniks/concorde 4.9.98-visual-stack.1 → 5.0.0

package/src/core/components/functional/infer/hugging-face/hf-worker-runtime.ts

@@ -1,381 +0,0 @@
-/**
- * Code exécuté DANS le worker. C'est le seul endroit qui touche Transformers.js.
- *
- * `hfWorkerMain` est volontairement autonome (aucune référence à un import ni
- * à une variable extérieure) : il est sérialisé tel quel (`toString()`) pour
- * construire le worker « blob » du mode `cdn`. Ne pas y utiliser d'import,
- * de helper externe ni de variable de module.
- *
- * Pour un worker construit par l'application (mode `worker`), utiliser
- * `serveHuggingFaceWorker` :
- *
- * ```ts
- * // hf.worker.ts (dans l'application)
- * import * as transformers from "@huggingface/transformers";
- * import { serveHuggingFaceWorker } from "@supersoniks/concorde/core/components/functional/infer/hugging-face/hf-worker-runtime";
- * serveHuggingFaceWorker(transformers);
- * ```
- */
-
-/** Sous-ensemble de Transformers.js utilisé par le worker (typage structurel, sans import). */
-export type HfLibrary = {
-  pipeline: (
-    task: string,
-    model: string,
-    options?: Record<string, unknown>,
-  ) => Promise<unknown>;
-  env: Record<string, unknown> & {
-    backends?: { onnx?: { wasm?: Record<string, unknown> } };
-  };
-  ModelRegistry?: {
-    get_pipeline_files?: (
-      task: string,
-      model: string,
-      options?: Record<string, unknown>,
-    ) => Promise<string[]>;
-    get_file_metadata?: (
-      model: string,
-      file: string,
-      options?: Record<string, unknown>,
-    ) => Promise<{ exists: boolean; size?: number; fromCache?: boolean }>;
-    is_pipeline_cached?: (
-      task: string,
-      model: string,
-      options?: Record<string, unknown>,
-    ) => Promise<boolean>;
-    clear_pipeline_cache?: (
-      task: string,
-      model: string,
-      options?: Record<string, unknown>,
-    ) => Promise<unknown>;
-  };
-  LogLevel?: Record<string, unknown>;
-};
-
-/** Portée minimale d'un worker (évite de dépendre de la lib TS « webworker »). */
-export type HfWorkerScope = {
-  postMessage: (message: unknown, transfer?: Transferable[]) => void;
-  addEventListener: (
-    type: "message",
-    listener: (event: { data: unknown }) => void,
-  ) => void;
-};
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-export function hfWorkerMain(lib: HfLibrary, scope: HfWorkerScope): void {
-  const pipelines = new Map<string, { pipe: any; task: string }>();
-  let queue: Promise<unknown> = Promise.resolve();
-
-  const post = (message: unknown) => scope.postMessage(message);
-  const fail = (id: number, code: string, message: string) =>
-    post({ id, ok: false, error: { code, message } });
-
-  const errorCode = (err: unknown): string => {
-    const text = String((err as any)?.message ?? err).toLowerCase();
-    if ((err as any)?.code) return String((err as any).code);
-    if (text.includes("quota")) return "quota";
-    if (
-      text.includes("failed to fetch") ||
-      text.includes("network") ||
-      text.includes("404") ||
-      text.includes("could not locate")
-    )
-      return "network";
-    return "runtime";
-  };
-
-  const loadOptions = (model: any) => {
-    const opts: Record<string, unknown> = { ...(model.options || {}) };
-    opts.revision = model.revision;
-    return opts;
-  };
-
-  const hasWebGpu = async (): Promise<boolean> => {
-    const gpu = (globalThis as any).navigator?.gpu;
-    if (!gpu || typeof gpu.requestAdapter !== "function") return false;
-    try {
-      return !!(await gpu.requestAdapter());
-    } catch {
-      return false;
-    }
-  };
-
-  const isTensor = (v: any) =>
-    v && typeof v === "object" && typeof v.tolist === "function" && "dims" in v;
-  const isRawImage = (v: any) =>
-    v &&
-    typeof v === "object" &&
-    typeof v.toBlob === "function" &&
-    typeof v.width === "number" &&
-    typeof v.channels === "number";
-
-  const serialize = async (v: any): Promise<any> => {
-    if (isTensor(v)) return v.tolist();
-    if (isRawImage(v)) {
-      const blob = await v.toBlob("image/png");
-      return { width: v.width, height: v.height, channels: v.channels, blob };
-    }
-    if (Array.isArray(v)) return Promise.all(v.map(serialize));
-    if (v instanceof Blob) return v;
-    if (v && typeof v === "object") {
-      const out: Record<string, unknown> = {};
-      for (const k of Object.keys(v)) out[k] = await serialize(v[k]);
-      return out;
-    }
-    return v;
-  };
-
-  /** Retire la dimension « lot » d'un Tensor pour un élément unique. */
-  const unbatch = (v: any) =>
-    Array.isArray(v) && v.length === 1 && Array.isArray(v[0]) ? v[0] : v;
-
-  const handlers: Record<string, (msg: any) => Promise<unknown>> = {
-    async configure({ env }) {
-      const e = lib.env as any;
-      e.allowLocalModels = false;
-      e.allowRemoteModels = true;
-      e.useBrowserCache = true;
-      e.useWasmCache = true;
-      e.cacheKey = env.cacheKey;
-      if (env.remoteHost) e.remoteHost = env.remoteHost;
-      if (env.remotePathTemplate) e.remotePathTemplate = env.remotePathTemplate;
-      if (env.wasmPaths && e.backends?.onnx?.wasm) {
-        let paths = env.wasmPaths;
-        if (typeof paths === "string") {
-          // Même choix de binaire que Transformers.js (build asyncify, sauf
-          // Safari < 26 sans WebGPU), mais sous forme d'objet : c'est la seule
-          // forme que Transformers.js met en cache (Cache API).
-          const base = paths.endsWith("/") ? paths : paths + "/";
-          const ua = String((globalThis as any).navigator?.userAgent ?? "");
-          const safari = /Safari\//.test(ua) && !/Chrome|Chromium|Android/.test(ua);
-          const version = Number((/Version\/(\d+)/.exec(ua) ?? [])[1] ?? 99);
-          const suffix =
-            safari && version < 26 && !(globalThis as any).navigator?.gpu
-              ? ""
-              : ".asyncify";
-          paths = {
-            mjs: `${base}ort-wasm-simd-threaded${suffix}.mjs`,
-            wasm: `${base}ort-wasm-simd-threaded${suffix}.wasm`,
-          };
-        }
-        e.backends.onnx.wasm.wasmPaths = paths;
-      }
-      if (env.logLevel && lib.LogLevel) {
-        const level = (lib.LogLevel as any)[String(env.logLevel).toUpperCase()];
-        if (level !== undefined) e.logLevel = level;
-      }
-      return { version: e.version ?? null };
-    },
-
-    async inspect({ model }) {
-      const registry = lib.ModelRegistry;
-      const opts = loadOptions(model);
-      let cached = false;
-      let totalBytes: number | null = null;
-      try {
-        cached = !!(await registry?.is_pipeline_cached?.(
-          model.task,
-          model.repo,
-          opts,
-        ));
-      } catch {
-        cached = false;
-      }
-      try {
-        const files = await registry?.get_pipeline_files?.(
-          model.task,
-          model.repo,
-          opts,
-        );
-        if (files && registry?.get_file_metadata) {
-          const metas = await Promise.all(
-            files.map((f) =>
-              registry.get_file_metadata!(model.repo, f, {
-                revision: model.revision,
-              }).catch(() => null),
-            ),
-          );
-          const sizes = metas.map((m) => m?.size);
-          if (sizes.every((s) => typeof s === "number")) {
-            totalBytes = (sizes as number[]).reduce((a, b) => a + b, 0);
-          }
-        }
-      } catch {
-        totalBytes = null;
-      }
-      return { cached, totalBytes };
-    },
-
-    async load({ model, devices }) {
-      const existing = pipelines.get(model.alias);
-      if (existing) return { backend: existing.pipe.__backend, loadMs: 0 };
-      const t0 = performance.now();
-      const files: Record<string, { loaded: number; total: number }> = {};
-      const progress_callback = (info: any) => {
-        if (info.status === "progress_total") {
-          post({
-            type: "progress",
-            alias: model.alias,
-            progress: {
-              loadedBytes: info.loaded,
-              totalBytes: info.total,
-              percent: Math.round(info.progress ?? 0),
-            },
-          });
-        } else if (info.status === "progress") {
-          files[info.file] = { loaded: info.loaded, total: info.total };
-          const all = Object.values(files);
-          const loaded = all.reduce((a, f) => a + (f.loaded || 0), 0);
-          const total = all.reduce((a, f) => a + (f.total || 0), 0);
-          post({
-            type: "progress",
-            alias: model.alias,
-            progress: {
-              file: info.file,
-              loadedBytes: loaded,
-              totalBytes: total,
-              percent: total ? Math.round((loaded / total) * 100) : 0,
-            },
-          });
-        }
-      };
-      const errors: string[] = [];
-      for (const device of devices as string[]) {
-        if (device === "webgpu" && !(await hasWebGpu())) {
-          errors.push("webgpu indisponible");
-          continue;
-        }
-        try {
-          const pipe: any = await lib.pipeline(model.task, model.repo, {
-            ...loadOptions(model),
-            device,
-            progress_callback,
-          });
-          pipe.__backend = device;
-          pipelines.set(model.alias, { pipe, task: model.task });
-          return {
-            backend: device,
-            loadMs: Math.round(performance.now() - t0),
-          };
-        } catch (err) {
-          const code = errorCode(err);
-          if (code === "network" || code === "quota") throw err;
-          errors.push(`${device} : ${String((err as any)?.message ?? err)}`);
-        }
-      }
-      const err: any = new Error(
-        `Aucun backend utilisable (${errors.join(" ; ") || "aucun autorisé"}).`,
-      );
-      err.code = "unsupported";
-      throw err;
-    },
-
-    async run({ request }) {
-      const entry = pipelines.get(request.alias);
-      if (!entry) {
-        const err: any = new Error(`Modèle "${request.alias}" non chargé.`);
-        err.code = "runtime";
-        throw err;
-      }
-      const { pipe } = entry;
-      const call = { ...(request.call || {}) };
-      let positional: unknown;
-      if (request.positional) {
-        positional = call[request.positional];
-        delete call[request.positional];
-      }
-      const invoke = (input: unknown) =>
-        request.positional ? pipe(input, positional, call) : pipe(input, call);
-
-      if (request.batch) {
-        const out: unknown[] = [];
-        const size = 32;
-        for (let i = 0; i < request.inputs.length; i += size) {
-          const chunk = request.inputs.slice(i, i + size);
-          const rows = await serialize(await invoke(chunk));
-          out.push(...(Array.isArray(rows) ? rows : [rows]));
-        }
-        return out;
-      }
-      const out: unknown[] = [];
-      for (const input of request.inputs) {
-        const value = await serialize(await invoke(input));
-        out.push(
-          entry.task === "feature-extraction" ||
-            entry.task === "image-feature-extraction"
-            ? unbatch(value)
-            : value,
-        );
-      }
-      return out;
-    },
-
-    async clear({ model }) {
-      const registry = lib.ModelRegistry;
-      if (model) {
-        const entry = pipelines.get(model.alias);
-        pipelines.delete(model.alias);
-        await entry?.pipe?.dispose?.();
-        await registry?.clear_pipeline_cache?.(
-          model.task,
-          model.repo,
-          loadOptions(model),
-        );
-        return true;
-      }
-      for (const entry of pipelines.values()) await entry.pipe?.dispose?.();
-      pipelines.clear();
-      const cacheKey = (lib.env as any).cacheKey;
-      if (cacheKey && typeof caches !== "undefined") await caches.delete(cacheKey);
-      return true;
-    },
-  };
-
-  scope.addEventListener("message", (event) => {
-    const msg: any = event.data;
-    if (!msg || typeof msg.id !== "number" || !handlers[msg.type]) return;
-    // Les requêtes sont traitées une par une : un seul modèle calcule à la fois.
-    queue = queue
-      .then(() => handlers[msg.type](msg))
-      .then(
-        (result) => post({ id: msg.id, ok: true, result }),
-        (err) =>
-          fail(msg.id, errorCode(err), String((err as any)?.message ?? err)),
-      );
-  });
-}
-/* eslint-enable @typescript-eslint/no-explicit-any */
-
-/** À appeler dans un worker construit par l'application (mode `runtime.source = "worker"`). */
-export function serveHuggingFaceWorker(lib: HfLibrary): void {
-  hfWorkerMain(lib, globalThis as unknown as HfWorkerScope);
-}
-
-/**
- * Source d'un worker module autonome qui importe Transformers.js depuis une
- * URL figée (mode `runtime.source = "cdn"`).
- */
-export function buildHfWorkerSource(libraryUrl: string): string {
-  // Les messages reçus pendant l'import du moteur sont mis de côté puis rejoués.
-  return [
-    `const hfWorkerMain = ${hfWorkerMain.toString()};`,
-    `const pending = [];`,
-    `const buffer = (event) => pending.push(event);`,
-    `self.addEventListener("message", buffer);`,
-    `let lib;`,
-    `try {`,
-    `  lib = await import(${JSON.stringify(libraryUrl)});`,
-    `} catch (err) {`,
-    `  self.postMessage({ type: "fatal", message: "Chargement de Transformers.js impossible : " + (err && err.message || err) });`,
-    `  throw err;`,
-    `}`,
-    `self.removeEventListener("message", buffer);`,
-    `hfWorkerMain(lib, {`,
-    `  postMessage: (message, transfer) => self.postMessage(message, transfer),`,
-    `  addEventListener: (type, listener) => {`,
-    `    self.addEventListener(type, listener);`,
-    `    for (const event of pending.splice(0)) listener(event);`,
-    `  },`,
-    `});`,
-  ].join("\n");
-}

package/src/core/components/functional/infer/hugging-face/hugging-face-infer.md

@@ -1,304 +0,0 @@
-# Hugging Face infer
-
-`sonic-hugging-face-infer`: **1 input → Hugging Face model → 1 output** (readonly), computed **in the browser** with [Transformers.js](https://huggingface.co/docs/transformers.js). Data never leaves the device.
-
-The name names the engine: other inference paths (server, browser AI, …) will get their own `sonic-<engine>-infer`, with the same attributes, states, and typed outputs.
-
-- **Lightweight**: the component does not ship the engine. Transformers.js loads on first need, **in a worker**, from a **pinned version**.
-- **Allowlist**: the `model` attribute is an alias declared by the app. An SDUI descriptor cannot load an arbitrary model.
-- **End-to-end typed**: inputs, options, and outputs are derived from Transformers.js types.
-
-## Examples
-
-Each demo stays idle until you click **Try**. The model downloads only after consent.
-
-### Image — `background-removal`
-
-<docs-lit-demo for="docs-hf-cutout-demo"></docs-lit-demo>
-
-### Text — `zero-shot-classification`
-
-<docs-lit-demo for="docs-hf-suggest-demo"></docs-lit-demo>
-
-Image + depth / shader chains: [Visual stack](#docs/_misc/visual-stack.md/visual-stack).
-
-### Other tasks (markup)
-
-Same component, different allowlist alias. Common patterns:
-
-<sonic-code language="html">
-  <template>
-&lt;!-- Semantic search (embeddings) --&gt;
-&lt;sonic-hugging-face-infer
-  model="multilingual-mini"
-  inputProvider="events"
-  outputProvider="search.vectors"
-  options='{"text":"label + edito.sub_title"}'
-  load="idle"
-  persistResults
-&gt;&lt;/sonic-hugging-face-infer&gt;
-
-&lt;!-- Translation FR → EN --&gt;
-&lt;sonic-hugging-face-infer
-  model="fr-en"
-  inputProvider="event.edito.description"
-  outputProvider="event.edito.descriptionEn"
-  load="consent"
-  trigger="demand"
-  triggerProvider="translateClick"
-&gt;&lt;/sonic-hugging-face-infer&gt;
-
-&lt;!-- Dictation (Whisper) --&gt;
-&lt;sonic-hugging-face-infer
-  model="whisper-tiny"
-  inputProvider="voice.clipUrl"
-  outputProvider="voice.transcript"
-  load="consent"
-&gt;&lt;/sonic-hugging-face-infer&gt;
-  </template>
-</sonic-code>
-
-## Installation
-
-### CDN (script + bootstrap)
-
-Load `concorde-hugging-face-infer.bundle.js` after the core, then call `ConcordeHF.configureHuggingFace(…)` once. Details: [CDN addons](#docs/_getting-started/cdn-addons.md/cdn-addons).
-
-### 1. Pin and host the runtime
-
-```bash
-npm i -D --save-exact @huggingface/transformers@4.3.0
-node node_modules/@supersoniks/concorde/scripts/hf-vendor.mjs runtime --out ./cdn/vendor/hf-transformers
-# → ./cdn/vendor/hf-transformers/4.3.0/ transformers.min.js + ONNX Runtime binaries + manifest.json
-```
-
-The script checks that ONNX Runtime binaries are **exactly** those expected by Transformers.js. Serve the folder with `Cache-Control: public, max-age=31536000, immutable`: the path includes the version and never changes. To upgrade: new folder, regression tests, then change `version` / `url` in config. The previous version can stay served.
-
-### 2. Host models (pinned revision)
-
-```bash
-node node_modules/@supersoniks/concorde/scripts/hf-vendor.mjs model Xenova/paraphrase-multilingual-MiniLM-L12-v2 <sha> --dtype q8 --out ./cdn/models
-```
-
-The script prints size (`sizeBytes`) and license for you to verify.
-
-### 3. Configure (once, at startup)
-
-```ts
-import {
-  configureHuggingFace,
-  defineHuggingFaceModels,
-} from "@supersoniks/concorde/hugging-face";
-
-export const hf = configureHuggingFace({
-  runtime: {
-    source: "cdn",
-    version: "4.3.0",
-    url: "https://cdn.example.org/vendor/hf-transformers/4.3.0/transformers.min.js",
-  },
-  remoteHost: "https://cdn.example.org/models/",
-  remotePathTemplate: "{model}/{revision}/",
-  models: defineHuggingFaceModels({
-    "multilingual-mini": {
-      task: "feature-extraction",
-      repo: "Xenova/paraphrase-multilingual-MiniLM-L12-v2",
-      revision: "<sha>",
-      options: { dtype: "q8" },
-      sizeBytes: 118_000_000,
-      license: "apache-2.0",
-      label: "Smart search",
-      defaults: { pooling: "mean", normalize: true },
-    },
-  }),
-  defaults: { load: "first-use", consentAboveMB: 30, allowWasmUpToMB: 50 },
-});
-```
-
-Three ways to supply the runtime (`runtime.source`):
-
-| Source | When | Notes |
-|---|---|---|
-| `cdn` | Recommended | Blob worker that imports the pinned URL. Nothing in the app bundle. CSP: `worker-src blob:`, `script-src` + `connect-src` on the CDN, `'wasm-unsafe-eval'`. |
-| `worker` | App prefers bundling the engine | `createWorker: () => new Worker(new URL("./hf.worker.ts", import.meta.url), { type: "module" })`, and in `hf.worker.ts`: `serveHuggingFaceWorker(await import("@huggingface/transformers"))`. The engine lives only in the worker chunk. |
-| `engine` | Tests, custom transport | Object implementing `HfEngine`. |
-
-## Markup
-
-<sonic-code language="html">
-  <template>
-&lt;sonic-fetch dataProvider="events" endPoint="events?view=essential&ids_season=9"&gt;&lt;/sonic-fetch&gt;
-
-&lt;!-- Catalog: runs when the browser is idle, cached in IndexedDB --&gt;
-&lt;sonic-hugging-face-infer
-  model="multilingual-mini"
-  inputProvider="events"
-  outputProvider="search.vectors"
-  options='{"text":"label + edito.sub_title + categories.title"}'
-  load="idle"
-  persistResults
-&gt;&lt;/sonic-hugging-face-infer&gt;
-
-&lt;!-- Query: on each keystroke (300 ms debounce) --&gt;
-&lt;sonic-hugging-face-infer
-  model="multilingual-mini"
-  inputProvider="searchForm.q"
-  outputProvider="search.query"
-  statusProvider="searchAiStatus"
-  debounce="300"
-&gt;&lt;/sonic-hugging-face-infer&gt;
-  </template>
-</sonic-code>
-
-Ranking combines several inputs (events, vectors, query). With the TypeScript API:
-
-```ts
-derive({
-  inputs: { e: events, v: vectors, q: queryVector },
-  output: results,
-  compute: ({ e, v, q }) => rankBySimilarity(e, v, q, 8),
-});
-```
-
-On the JSONata side, `$cosine(a, b)` and `$rankBySimilarity(items, vectors, query, topN?, minScore?)` are available in `sonic-jsonata` (one input: group data under the same DataProvider).
-
-## Attributes
-
-| Attribute | Role |
-|---|---|
-| `model` | Allowlist alias (required) |
-| `inputProvider` | Input: text, list of texts, list of objects (+ `options.text`), image (URL, data URL, Blob), audio (Float32Array, URL) |
-| `outputProvider` | Output (readonly). List in → **aligned** list out (`null` for unusable items) |
-| `options` | JSON `{"text": …, "call": {…}}`. `text`: paths to concatenate (`"label + edito.sub_title"`, arrays flattened). `call`: pipeline options, validated per task |
-| `load` | `auto` · `idle` · `visible` · `first-use` (default) · `consent` · `manual` |
-| `trigger` | `mutation` (default) · `demand` |
-| `debounce` | Debounce (ms) for `mutation` |
-| `triggerProvider` | `demand` mode: each change on this DataProvider runs inference |
-| `statusProvider` | Where to publish detailed status (see [States](#states)) |
-| `consentProvider` | Truthy or `"accepted"` = consent, `"declined"` = refuse |
-| `emptyValue` | Output when input is empty (JSON, default `null`) |
-| `onInvalid` | Invalid input: `keep` (default, keep last result) or `clear` |
-| `maxItems` · `maxChars` · `timeoutMs` | Limits (defaults from config) |
-| `persistResults` · `resultsTtl` | Cache results in IndexedDB (key = input + model + revision + runtime + options) |
-
-Methods: `run()`, `loadModel()`, `accept()`, `decline()`.
-
-## Model loading
-
-| `load` | Download |
-|---|---|
-| `auto` | As soon as the element connects |
-| `idle` | When the browser is idle |
-| `visible` | When the element enters the viewport |
-| `first-use` | On the first valid input |
-| `consent` | After user consent (asked on first valid input) |
-| `manual` | Only via `loadModel()` |
-
-Guards, regardless of policy: switch to `consent` on data-saver, slow network (2G), or when the model exceeds `consentAboveMB`. A cached model loads without prompting. Choice is stored per alias and revision (`hf.revokeConsent(alias)` to clear). Nothing downloads while the input is empty.
-
-Consent without JavaScript (SDUI):
-
-<sonic-code language="html">
-  <template>
-&lt;sonic-states dataProvider="searchAiStatus" data-path="state"&gt;
-  &lt;template data-value="awaiting-consent"&gt;
-    &lt;div formDataProvider="aiConsent"&gt;
-      Enable smart search? &lt;sonic-value dataProvider="searchAiStatus" key="size.totalMB"&gt;&lt;/sonic-value&gt; MB, once, nothing leaves your device.
-      &lt;sonic-button radio name="accepted" value="accepted"&gt;Enable&lt;/sonic-button&gt;
-    &lt;/div&gt;
-  &lt;/template&gt;
-&lt;/sonic-states&gt;
-&lt;!-- + consentProvider="aiConsent.accepted" on sonic-hugging-face-infer --&gt;
-  </template>
-</sonic-code>
-
-## Triggers
-
-| Case | `load` | `trigger` |
-|---|---|---|
-| Live search | `first-use` | `mutation`, `debounce="300"` |
-| Catalog indexing | `idle` | `mutation` + `persistResults` |
-| Label suggestions (admin) | `first-use` | `demand` (“Suggest” button) |
-| Translate a listing | `consent` | `demand` (“Translate” button) |
-
-## States
-
-`{outputProvider root}/_state_` → `{ status }` (`loading` | `ready` | `error` | `empty`), like `sonic-jsonata`, for `sonic-states`.
-
-Detailed status on `statusProvider`:
-
-| Field | Content |
-|---|---|
-| `state` | `idle` · `empty` · `awaiting-consent` · `declined` · `downloading` · `loading` · `ready` · `running` · `done` · `invalid-input` · `error` · `unsupported` |
-| `size` | `{ totalBytes, totalMB, fromCache }` — known **before** download |
-| `progress` | `{ loadedBytes, totalBytes, percent, file }` while downloading |
-| `backend` | `webgpu` or `wasm` |
-| `skipped` · `warnings` | Skipped items, truncated texts |
-| `timings` | `{ loadMs, lastRunMs }` |
-| `fromResultsCache` | Result served from cache |
-| `error` | `{ code, message }` — `invalid-input`, `too-large`, `not-allowed`, `quota`, `timeout`, `network`, `runtime` |
-
-## Empty or invalid inputs
-
-- Empty (`null`, `""`, `[]`, missing DataProvider) → `empty`, output `emptyValue`, **no download**.
-- Wrong type (number, object without `options.text`, unknown option) → `invalid-input` with a precise message. No silent coercion.
-- Partially valid list → aligned output, `null` for skipped items, `skipped` count.
-- Too large → `too-large` (`maxItems`); overlong text → truncated (`maxChars`) and warned.
-
-## WebGPU and WASM
-
-ONNX Runtime is a WASM binary in every case (≈ 27 MB, ≈ 6.6 MB compressed for 1.31), including WebGPU: it downloads with the first model from your CDN, then is cached. It is not part of the component.
-
-What you control: CPU (WASM) execution when WebGPU is missing. Allowed per model (`devices`) and only under `allowWasmUpToMB`. Beyond that → `unsupported`; the page keeps working without the model.
-
-## TypeScript
-
-`configureHuggingFace` returns an API typed by the allowlist:
-
-```ts
-const events = new DataProviderKey<EventEssential[]>("events");
-const vectors = new DataProviderKey<(number[] | null)[] | null>("eventVectors");
-
-hf.infer({
-  model: "multilingual-mini",                // union of declared aliases
-  input: events,
-  text: (e) => [e.label, e.edito?.sub_title].filter(Boolean).join(" — "), // typed on EventEssential
-  output: vectors,                           // error if type does not match the task
-  load: "idle",
-  persistResults: true,
-});
-
-// One-shot run (adapter for derive)
-const v = await hf.run("multilingual-mini", "a funny show"); // number[] | null
-const t = await hf.run("multilingual-mini", "funny", { pooling: "none" }); // number[][] | null
-```
-
-- Input, option, and output types are **derived** from Transformers.js signatures (`import type` only): a version bump that changes a signature fails compilation, not production.
-- An option from another task, an unknown alias, or a mistyped output are compile errors.
-- For SDUI, `options.call` is validated at runtime with a per-task schema; `hfCallOptionsJsonSchema(task)` exposes it as JSON Schema (MCP catalog). An SDUI descriptor can only set **call** options within bounds; repo, revision, dtype, and device stay in config.
-
-Cleanup: `hf.clearModel(alias)`, `hf.clearAll()` (models, WASM, and results).
-
-## Tasks and light models
-
-Supported tasks: `feature-extraction`, `text-classification`, `zero-shot-classification`, `translation`, `token-classification`, `fill-mask`, `question-answering`, `image-classification`, `zero-shot-image-classification`, `object-detection`, `zero-shot-object-detection`, `image-feature-extraction`, `image-segmentation`, `depth-estimation`, `background-removal`, `image-to-text`, `audio-classification`, `automatic-speech-recognition`. No free-form LLM (`text-generation`, etc.).
-
-Indicative sizes (quantized); verify with `hf-vendor.mjs` before allowlisting, including license:
-
-| Task | Model | Size | Example |
-|---|---|---|---|
-| `background-removal` (general) | `onnx-community/ISNet-ONNX` | ≈ 44 MB | [Image demo](#image--background-removal) |
-| `zero-shot-classification` | `Xenova/mobilebert-uncased-mnli` | ≈ 25 MB | [Text demo](#text--zero-shot-classification) |
-| `depth-estimation` | `Xenova/depth-anything-small-hf` | ≈ 27 MB | [Visual stack](#docs/_misc/visual-stack.md/visual-stack) |
-| `object-detection` | `Xenova/yolos-tiny` | ≈ 8 MB | — |
-| `image-to-text` | `Xenova/vit-gpt2-image-captioning` | ≈ 246 MB | — |
-| `token-classification` | `Xenova/bert-base-NER` | ≈ 109 MB | — |
-| `background-removal` (portraits) | `Xenova/modnet` | ≈ 7 MB | Human portraits only |
-| `image-segmentation` | `Xenova/segformer-b0-finetuned-ade-512-512` | ≈ 4 MB | Regions (sky, water…) |
-| `feature-extraction` | `Xenova/paraphrase-multilingual-MiniLM-L12-v2` | ≈ 120 MB | Intent / semantic search |
-| `translation` | `Xenova/opus-mt-fr-en` | ≈ 75 MB | FR → EN listings |
-| `automatic-speech-recognition` | `onnx-community/whisper-tiny.en` | ≈ 41 MB | Dictation / voice search |
-| `fill-mask` | `Xenova/albert-base-v2` | ≈ 12 MB | Complete `[MASK]` |
-
-Produced images (cutout, depth, segmentation) come out as `{ width, height, channels, blob, url }` (PNG). `url` is an ObjectURL attached on the main thread at publish time — chainable into `sonic-shader` / `sonic-jsonata` (`$mediaUrl`) without app glue. Images are not stored in IndexedDB.
-
-End-to-end (depth + shader / Harris) : [Visual stack](#docs/_misc/visual-stack.md/visual-stack).