@tanstack-ai-browser/webgllm 0.0.0-stage → 0.2.0

package/dist/model-memory.js

@@ -0,0 +1,79 @@
+/**
+ * The memory the page's models take, shared by this project's runtimes
+ * (Transformers.js, WebGL, wllama), each of which loads models in its own
+ * worker. Before a runtime loads a model it claims the memory: other
+ * runtimes' least recently used models are unloaded until everything fits
+ * the budget. A phone can't hold two 1 GB models (an iPhone Safari tab has
+ * 2 GB), and small models still stay loaded side by side.
+ *
+ * The packages each carry this file and share one registry through
+ * globalThis, so they find each other even when bundled apart. Keep the
+ * copies identical (packages/{transformers-js,webgl,wllama}/src).
+ */
+const KEY = Symbol.for("@tanstack-ai-browser/model-memory");
+function registry() {
+    const scope = globalThis;
+    return (scope[KEY] ??= { version: 1, held: new Map() });
+}
+/**
+ * The default budget: 1.5 GB on iOS (a Safari tab gets 2 GB, the page and
+ * Safari take the rest), half the device's memory where the browser says
+ * (Chrome: up to 8 GB), else 4 GB.
+ */
+export function defaultMemoryBudget() {
+    if (typeof navigator === "undefined")
+        return Number.POSITIVE_INFINITY;
+    const { userAgent, maxTouchPoints } = navigator;
+    const ios = /iPhone|iPad|iPod/.test(userAgent) ||
+        (/Macintosh/.test(userAgent) && maxTouchPoints > 1);
+    if (ios)
+        return 1.5e9;
+    const gigabytes = navigator.deviceMemory;
+    return gigabytes ? gigabytes * 0.5e9 : 4e9;
+}
+/**
+ * Sets how many bytes the page's models may take together, across this
+ * project's runtimes, from the next load on; undefined for the default.
+ */
+export function setMemoryBudget(bytes) {
+    registry().budget = bytes;
+}
+/**
+ * Makes room for `owner`'s model of about `bytes`, unloading other runtimes'
+ * models, least recently used first, until it fits the budget (models kept
+ * loaded stay), then records it in place of `owner`'s previous one.
+ * Resolves to false, recording nothing, if `signal` aborted meanwhile.
+ */
+export async function claimMemory(model) {
+    const { signal, ...entry } = model;
+    if (signal?.aborted)
+        return false;
+    const { held, budget } = registry();
+    const limit = budget ?? defaultMemoryBudget();
+    held.delete(entry.owner);
+    const others = [...held.values()].sort((a, b) => a.lastUsed - b.lastUsed);
+    let total = others.reduce((sum, h) => sum + h.bytes, entry.bytes);
+    for (const other of others) {
+        if (total <= limit)
+            break;
+        if (other.keepLoaded)
+            continue;
+        held.delete(other.owner);
+        total -= other.bytes;
+        await other.unload();
+        if (signal?.aborted)
+            return false;
+    }
+    held.set(entry.owner, { ...entry, lastUsed: Date.now() });
+    return true;
+}
+/** Marks `owner`'s model as just used (for least recently used order). */
+export function touchMemory(owner) {
+    const held = registry().held.get(owner);
+    if (held)
+        held.lastUsed = Date.now();
+}
+/** Forgets `owner`'s model, once it's unloaded or failed to load. */
+export function releaseMemory(owner) {
+    registry().held.delete(owner);
+}

package/dist/model-meta.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The models webgllm runs, from its catalog, with what each supports and
+ * its reasoning levels.
+ */
+export { WEBGLLM_CHAT_MODELS, WEBGLLM_MODEL_META, WEBGLLM_MODEL_REASONING } from "./catalog.js";
+export type { WebGllmChatModel, WebGllmModelMeta, WebGllmModelReasoningByName } from "./catalog.js";
+//# sourceMappingURL=model-meta.d.ts.map

package/dist/model-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-meta.d.ts","sourceRoot":"","sources":["../src/model-meta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAC/F,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAA"}

package/dist/model-meta.js

@@ -0,0 +1,5 @@
+/**
+ * The models webgllm runs, from its catalog, with what each supports and
+ * its reasoning levels.
+ */
+export { WEBGLLM_CHAT_MODELS, WEBGLLM_MODEL_META, WEBGLLM_MODEL_REASONING } from "./catalog.js";

package/dist/models.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The one `WebGLLM` instance every adapter and helper here shares, and the
+ * page-side state around it: which models are ready or downloading, and
+ * its place in the memory registry this project's runtimes share
+ * (model-memory.ts), so a WebGL model and a Transformers.js or wllama one
+ * make room for each other.
+ */
+import { WebGLLM } from "webgllm";
+import type { WebGllmChatModel } from "./catalog.js";
+/**
+ * Where a model stands in this browser, with the Prompt API's values
+ * (`LanguageModel.availability()`): "unavailable" (it can't run here),
+ * "downloadable" (it can, once downloaded), "downloading" (a download of it
+ * is in progress in this page) or "available" (on the device: no download
+ * needed).
+ */
+export type Availability = "unavailable" | "downloadable" | "downloading" | "available";
+/** A download's progress, from 0 to 1. */
+export type DownloadProgressCallback = (progress: number) => void;
+/**
+ * The shared instance. Each claim its workers make (an estimate before a
+ * load, the measured textures after, each growth of the attention cache)
+ * goes to the registry first, which makes room across runtimes before the
+ * worker allocates. webgllm's own budget holds its models to the same limit
+ * and orders them among themselves. webgllm reads `memoryBudget` from its
+ * options at each claim, so the getter follows `setMemoryBudget`.
+ */
+export declare const webgllm: WebGLLM;
+/**
+ * Whether the engine runs in this browser (WebGL 2 with float render
+ * targets, in a worker), checked once: webgllm's check makes a WebGL
+ * context, and the answer doesn't change during a page's life.
+ */
+export declare function engineRuns(): boolean;
+/** Forgets `engineRuns`'s answer (for tests that swap the engine's check). */
+export declare function forgetEngineCheck(): void;
+/**
+ * Where `model` stands for chats of up to `contextLength` tokens (as
+ * requested: undefined for the model's own), as the Prompt API's
+ * `LanguageModel.availability()` says it: "unavailable" where the engine
+ * can't run (WebGL 2 with float render targets, in a worker; not on a
+ * server) or the model isn't in webgllm's catalog, "downloading" while this
+ * page downloads it, "available" when it's loaded for that context or
+ * every file it loads is in webgllm's storage (`models.downloaded`, which
+ * reads the Origin Private File System only), else "downloadable". No
+ * worker, no network.
+ */
+export declare function availability(model: WebGllmChatModel, contextLength?: number): Promise<Availability>;
+/**
+ * Sets how many bytes the page's models may take together, across this
+ * project's runtimes, from the next load on; undefined for the default.
+ */
+export declare function setMemoryBudget(bytes: number | undefined): void;
+/**
+ * Keeps `model` loaded when another model (of this runtime or of
+ * Transformers.js or wllama) loads past the memory budget; by default the
+ * least recently used goes. Applies from the model's next load.
+ */
+export declare function setKeepLoaded(model: WebGllmChatModel, keep: boolean): void;
+/**
+ * Loads a model ahead of time (downloading it the first time) for chats of
+ * up to `contextLength` tokens: the model's own context length by default.
+ * A different context length loads the model again. Other models stay
+ * loaded while they fit the memory budget. `onDownloadProgress` hears the
+ * download's progress, 0 to 1, then 1 once the model is ready (at once if
+ * it already is).
+ */
+export declare function loadModel(model: WebGllmChatModel, options?: {
+    contextLength?: number;
+    onDownloadProgress?: DownloadProgressCallback;
+    /**
+     * Stops this caller's wait: it rejects at once with an AbortError and
+     * hears no more progress. webgllm shares one load between its callers
+     * (a chat's included) and cancels it, leaving the model unloaded, when
+     * the last one leaves.
+     */
+    signal?: AbortSignal;
+}): Promise<void>;
+/**
+ * The model loaded for `contextLength` (as requested), loading it if it
+ * isn't: what each adapter call waits for before its request.
+ */
+export declare function ensureModel(model: WebGllmChatModel, contextLength: number | undefined, signal?: AbortSignal, onDownloadProgress?: DownloadProgressCallback, 
+/** Tell `onDownloadProgress` 1 at once if the model is ready already. */
+reportReady?: boolean): Promise<void>;
+/** Marks `model` as just used, for least recently used order across runtimes. */
+export declare function touchModel(model: WebGllmChatModel): void;
+/**
+ * Unloads `model`, or every model, freeing its GPU memory; a running
+ * generation of it fails. Never rejects (callers often don't wait for it).
+ */
+export declare function unloadModel(model?: WebGllmChatModel): Promise<void>;
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAMjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAQpD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB,aAAa,GACb,cAAc,GACd,aAAa,GACb,WAAW,CAAA;AAEf,0CAA0C;AAC1C,MAAM,MAAM,wBAAwB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;AAUjE;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,SAgBlB,CAAA;AAIF;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAGpC;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,SAEhC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,gBAAgB,EACvB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,YAAY,CAAC,CAYvB;AAKD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,QAExD;AAiDD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,OAAO,QAGnE;AAmCD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE;IACP,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,kBAAkB,CAAC,EAAE,wBAAwB,CAAA;IAC7C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;CAChB,GACL,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,EACvB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,MAAM,CAAC,EAAE,WAAW,EACpB,kBAAkB,CAAC,EAAE,wBAAwB;AAC7C,yEAAyE;AACzE,WAAW,UAAQ,GAClB,OAAO,CAAC,IAAI,CAAC,CAef;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,KAAK,EAAE,gBAAgB,QAEjD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnE"}

package/dist/models.js

@@ -0,0 +1,274 @@
+/**
+ * The one `WebGLLM` instance every adapter and helper here shares, and the
+ * page-side state around it: which models are ready or downloading, and
+ * its place in the memory registry this project's runtimes share
+ * (model-memory.ts), so a WebGL model and a Transformers.js or wllama one
+ * make room for each other.
+ */
+import { WebGLLM } from "webgllm";
+import { defaultMemoryBudget } from "webgllm/advanced";
+import { WEBGLLM_MODEL_META } from "./catalog.js";
+import { claimMemory, releaseMemory, setMemoryBudget as setRegistryBudget, touchMemory } from "./model-memory.js";
+/** The registry's budget (set by any runtime's setMemoryBudget), else the device's. */
+function registryBudget() {
+    // Read straight from the shared registry (see model-memory.ts), whose
+    // copies in the other packages can set it too.
+    const scope = globalThis;
+    return scope[Symbol.for("@tanstack-ai-browser/model-memory")]?.budget ?? defaultMemoryBudget();
+}
+/**
+ * The shared instance. Each claim its workers make (an estimate before a
+ * load, the measured textures after, each growth of the attention cache)
+ * goes to the registry first, which makes room across runtimes before the
+ * worker allocates. webgllm's own budget holds its models to the same limit
+ * and orders them among themselves. webgllm reads `memoryBudget` from its
+ * options at each claim, so the getter follows `setMemoryBudget`.
+ */
+export const webgllm = new WebGLLM({
+    get memoryBudget() {
+        return registryBudget();
+    },
+    onMemoryClaim: async ({ model, bytes, signal }) => {
+        await claimMemory({
+            owner: owner(model),
+            model,
+            bytes,
+            keepLoaded: keepLoaded.has(model),
+            unload: () => evict(model)
+        });
+        // Unloaded while the registry made room: its "unload" event has already
+        // released it, so hold nothing for it.
+        if (signal.aborted)
+            releaseMemory(owner(model));
+    }
+});
+let engineSupported;
+/**
+ * Whether the engine runs in this browser (WebGL 2 with float render
+ * targets, in a worker), checked once: webgllm's check makes a WebGL
+ * context, and the answer doesn't change during a page's life.
+ */
+export function engineRuns() {
+    engineSupported ??= WebGLLM.isSupported();
+    return engineSupported;
+}
+/** Forgets `engineRuns`'s answer (for tests that swap the engine's check). */
+export function forgetEngineCheck() {
+    engineSupported = undefined;
+}
+/**
+ * Where `model` stands for chats of up to `contextLength` tokens (as
+ * requested: undefined for the model's own), as the Prompt API's
+ * `LanguageModel.availability()` says it: "unavailable" where the engine
+ * can't run (WebGL 2 with float render targets, in a worker; not on a
+ * server) or the model isn't in webgllm's catalog, "downloading" while this
+ * page downloads it, "available" when it's loaded for that context or
+ * every file it loads is in webgllm's storage (`models.downloaded`, which
+ * reads the Origin Private File System only), else "downloadable". No
+ * worker, no network.
+ */
+export async function availability(model, contextLength) {
+    if (!(model in WEBGLLM_MODEL_META) || !engineRuns())
+        return "unavailable";
+    if (downloading.has(model))
+        return "downloading";
+    if (isLoadedFor(model, contextLength))
+        return "available";
+    let stored = false;
+    try {
+        stored = await webgllm.models.downloaded(model);
+    }
+    catch {
+        // Storage that can't be read: a load downloads it.
+    }
+    if (downloading.has(model))
+        return "downloading";
+    return stored ? "available" : "downloadable";
+}
+/** Models whose files are downloading in this page. */
+const downloading = new Set();
+/**
+ * Sets how many bytes the page's models may take together, across this
+ * project's runtimes, from the next load on; undefined for the default.
+ */
+export function setMemoryBudget(bytes) {
+    setRegistryBudget(bytes);
+}
+/** Models loaded and ready, whatever loaded them. */
+const ready = new Set();
+/**
+ * Each loading model's callers' download progress callbacks, until it
+ * settles, with how many waiting callers use each: a callback is called
+ * once per report, and stays while any caller using it waits.
+ */
+const listeners = new Map();
+function call(listener, progress) {
+    try {
+        listener(progress);
+    }
+    catch (error) {
+        console.error(error);
+    }
+}
+/** Calls `model`'s progress callbacks; once it's ready, forgets them. */
+function report(model, progress, settled = false) {
+    const waiting = listeners.get(model);
+    if (!waiting)
+        return;
+    if (settled)
+        listeners.delete(model);
+    for (const listener of [...waiting.keys()])
+        call(listener, progress);
+}
+/** Adds a waiting caller's progress callback to `model`'s load. */
+function listen(model, listener) {
+    if (!listener)
+        return;
+    let waiting = listeners.get(model);
+    if (!waiting)
+        listeners.set(model, (waiting = new Map()));
+    waiting.set(listener, (waiting.get(listener) ?? 0) + 1);
+}
+/** Removes one waiting caller's progress callback: other callers using it keep it. */
+function unlisten(model, listener) {
+    const waiting = listener && listeners.get(model);
+    if (!waiting)
+        return;
+    const count = (waiting.get(listener) ?? 0) - 1;
+    if (count > 0)
+        waiting.set(listener, count);
+    else
+        waiting.delete(listener);
+    if (waiting.size === 0)
+        listeners.delete(model);
+}
+/** Models never unloaded to make room for another (see setKeepLoaded). */
+const keepLoaded = new Set();
+/**
+ * Keeps `model` loaded when another model (of this runtime or of
+ * Transformers.js or wllama) loads past the memory budget; by default the
+ * least recently used goes. Applies from the model's next load.
+ */
+export function setKeepLoaded(model, keep) {
+    if (keep)
+        keepLoaded.add(model);
+    else
+        keepLoaded.delete(model);
+}
+/** A model's name in the registry: webgllm holds several models, each its own entry. */
+const owner = (model) => `webgllm:${model}`;
+/** The context each ready model was loaded for, as requested (undefined: the model's own). */
+const loadedFor = new Map();
+/** Whether `model` is ready for `contextLength` (as requested): what a chat needs, and no load. */
+const isLoadedFor = (model, contextLength) => ready.has(model) && loadedFor.has(model) && loadedFor.get(model) === contextLength;
+/** The registry unloads `model` to make room for another runtime's (or another webgllm model). */
+function evict(model) {
+    // webgllm's "unload" event then marks it idle and releases its claim.
+    return webgllm.unloadModel(model).catch(() => undefined);
+}
+/**
+ * Loads `model` for `contextLength`. Its memory is claimed from the worker
+ * (see onMemoryClaim) and released at its "unload" event, and its state
+ * here follows webgllm's events (see below), not this function. Nothing is awaited
+ * before webgllm takes the load, so an unloadModel() from here on reaches it.
+ * A caller that gives up releases nothing: webgllm shares one load between
+ * its callers and unloads (releasing it) only when the last one leaves.
+ */
+async function load(model, contextLength, signal) {
+    await webgllm.loadModel(model, {
+        ...(contextLength !== undefined && { contextLength }),
+        keepLoaded: keepLoaded.has(model),
+        ...(signal && { signal })
+    });
+    loadedFor.set(model, contextLength);
+}
+/**
+ * Loads a model ahead of time (downloading it the first time) for chats of
+ * up to `contextLength` tokens: the model's own context length by default.
+ * A different context length loads the model again. Other models stay
+ * loaded while they fit the memory budget. `onDownloadProgress` hears the
+ * download's progress, 0 to 1, then 1 once the model is ready (at once if
+ * it already is).
+ */
+export function loadModel(model, options = {}) {
+    const { contextLength, onDownloadProgress, signal } = options;
+    const promise = (async () => {
+        try {
+            await ensureModel(model, contextLength, signal, onDownloadProgress, true);
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new DOMException("The model load was aborted.", "AbortError");
+            throw error;
+        }
+    })();
+    // Callers may leave it: an unawaited failure isn't an unhandled rejection.
+    promise.catch(() => undefined);
+    return promise;
+}
+/**
+ * The model loaded for `contextLength` (as requested), loading it if it
+ * isn't: what each adapter call waits for before its request.
+ */
+export async function ensureModel(model, contextLength, signal, onDownloadProgress, 
+/** Tell `onDownloadProgress` 1 at once if the model is ready already. */
+reportReady = false) {
+    signal?.throwIfAborted();
+    if (isLoadedFor(model, contextLength)) {
+        touchMemory(owner(model));
+        if (reportReady && onDownloadProgress)
+            call(onDownloadProgress, 1);
+        return;
+    }
+    listen(model, onDownloadProgress);
+    try {
+        await load(model, contextLength, signal);
+    }
+    catch (error) {
+        // This caller is done waiting; others keep theirs.
+        unlisten(model, onDownloadProgress);
+        throw error;
+    }
+}
+/** Marks `model` as just used, for least recently used order across runtimes. */
+export function touchModel(model) {
+    touchMemory(owner(model));
+}
+/**
+ * Unloads `model`, or every model, freeing its GPU memory; a running
+ * generation of it fails. Never rejects (callers often don't wait for it).
+ */
+export function unloadModel(model) {
+    return webgllm.unloadModel(model).catch(() => undefined);
+}
+/**
+ * A download's share of the way, 0 to 1, from webgllm's progress (which
+ * spans downloading, 0 to 0.9, and reading the files into the GPU).
+ */
+const downloadShare = ({ progress, loadedBytes, totalBytes }) => totalBytes ? Math.min((loadedBytes ?? 0) / totalBytes, 1) : Math.min(progress / 0.9, 1);
+// webgllm only dispatches events for models in its catalog. The state here
+// follows webgllm's lifecycle events, whatever started the load (loadModel,
+// a completion loading on demand) or the unload (unloadModel, room for
+// another model, a crash).
+webgllm.addEventListener("progress", (progress) => {
+    if (progress.phase !== "download" || progress.cached)
+        return;
+    downloading.add(progress.model);
+    report(progress.model, downloadShare(progress));
+});
+webgllm.addEventListener("load", ({ model }) => {
+    downloading.delete(model);
+    ready.add(model);
+    touchMemory(owner(model));
+    report(model, 1, true);
+});
+webgllm.addEventListener("error", ({ model }) => {
+    downloading.delete(model);
+    ready.delete(model);
+});
+webgllm.addEventListener("unload", ({ model }) => {
+    downloading.delete(model);
+    ready.delete(model);
+    loadedFor.delete(model);
+    releaseMemory(owner(model));
+});

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@tanstack-ai-browser/webgllm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "TanStack AI adapter for webgllm: LFM3, LFM2.5 and Qwen3.5 in the browser on WebGL 2, for devices without WebGPU",
+  "license": "MIT",
+  "author": "daveycodez",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daveycodez/tanstack-ai-browser.git",
+    "directory": "packages/webgllm"
+  },
+  "homepage": "https://github.com/daveycodez/tanstack-ai-browser/tree/main/packages/webgllm#readme",
+  "bugs": "https://github.com/daveycodez/tanstack-ai-browser/issues",
+  "keywords": [
+    "tanstack-ai",
+    "tanstack",
+    "ai",
+    "llm",
+    "webgllm",
+    "webgl",
+    "webgl2",
+    "lfm3",
+    "qwen3.5",
+    "browser",
+    "local-ai"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@tanstack-ai-browser/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "nx": {
+    "name": "webgllm"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "^1.0.0"
+  },
+  "dependencies": {
+    "@tanstack/openai-base": "^1.0.4",
+    "webgllm": "^0.3.4"
+  },
+  "devDependencies": {
+    "@huggingface/transformers": "4.3.2",
+    "@tanstack/ai": "1.4.0",
+    "esbuild": "0.28.2"
+  },
+  "scripts": {
+    "test": "node scripts/test.mjs"
+  }
 }

package/src/adapter.test.ts

@@ -0,0 +1,100 @@
+/**
+ * The adapter's runtime methods over webgllm: availability, create with
+ * its download progress, destroy, and the catalog's reasoning data.
+ */
+import assert from "node:assert/strict"
+import { beforeEach, test } from "node:test"
+import { WebGLLM } from "webgllm"
+import type { LoadProgress } from "webgllm"
+
+import { webgllmText } from "./adapter.js"
+import { WEBGLLM_MODEL_REASONING } from "./catalog.js"
+import { fake, MODEL } from "./fake-webgllm.test.js"
+
+// Node has no WebGL 2: the engine counts as supported here (unavailable.test.ts has the other case).
+;(WebGLLM as unknown as { isSupported: () => boolean }).isSupported = () => true
+beforeEach(() => fake.reset())
+
+const download = (loadedBytes: number, extra: Partial<LoadProgress> = {}): LoadProgress =>
+  ({ model: MODEL, phase: "download", progress: (loadedBytes / 100) * 0.9, loadedBytes, totalBytes: 100, cached: false, ...extra }) as LoadProgress
+
+test("availability: downloadable, downloading during a download, available once loaded or stored", async () => {
+  const adapter = webgllmText(MODEL)
+  assert.equal(await adapter.availability(), "downloadable")
+  let release!: () => void
+  fake.loadGate = new Promise((resolve) => (release = resolve))
+  fake.progress = [download(40)]
+  const loading = adapter.create()
+  await new Promise((resolve) => setTimeout(resolve, 0))
+  assert.equal(await adapter.availability(), "downloading")
+  release()
+  await loading
+  assert.equal(await adapter.availability(), "available")
+  await adapter.destroy()
+  assert.equal(await adapter.availability(), "downloadable")
+  fake.stored.add(MODEL)
+  assert.equal(await adapter.availability(), "available")
+})
+
+test("create loads for the adapter's context length; progress (the download's share, then 1) reaches both callbacks", async () => {
+  const own: Array<number> = []
+  const theirs: Array<number> = []
+  fake.progress = [download(50), download(50, { cached: true }), download(100)]
+  const adapter = webgllmText(MODEL, { contextLength: 2048, onDownloadProgress: (p) => own.push(p) })
+  assert.equal(await adapter.create({ onDownloadProgress: (p) => theirs.push(p) }), adapter)
+  assert.equal(fake.loads.at(-1)?.options.contextLength, 2048)
+  assert.deepEqual(own, [0.5, 1, 1])
+  assert.deepEqual(theirs, [0.5, 1, 1])
+})
+
+test("create rejects when the load fails or its signal aborts, and is safe to leave unawaited", async () => {
+  fake.loadError = new Error("No room for the model.")
+  await assert.rejects(webgllmText(MODEL).create(), /No room/)
+  fake.loadError = undefined
+  fake.loadGate = new Promise(() => undefined)
+  const controller = new AbortController()
+  const pending = webgllmText(MODEL).create({ signal: controller.signal })
+  controller.abort()
+  await assert.rejects(pending)
+  void webgllmText(MODEL).create({ signal: AbortSignal.abort() })
+})
+
+test("destroy unloads the model and never rejects", async () => {
+  await webgllmText(MODEL).create()
+  await webgllmText(MODEL).destroy()
+  assert.deepEqual(fake.unloads, [MODEL])
+  assert.equal(fake.loaded.has(MODEL), false)
+})
+
+test("WEBGLLM_MODEL_REASONING has every model, in TanStack's shape", () => {
+  const reasoning = WEBGLLM_MODEL_REASONING[MODEL]
+  assert.ok(reasoning)
+  assert.equal(reasoning.levels.high, "high")
+  assert.equal(reasoning.levels.off, "none")
+  assert.equal(reasoning.budget, true)
+})
+
+// Compile-time: each model's reasoning is exact (typecheck fails if it widens again).
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false
+const exact = <T extends true>(_: T) => undefined
+type Thinkers = keyof import("./catalog.js").WebGllmModelReasoningByName
+exact<Equal<Thinkers,
+  | "LiquidAI/LFM3-1.7B-GGUF"
+  | "onnx-community/LFM3-1.7B-ONNX"
+  | "LiquidAI/LFM2.5-1.2B-Thinking-ONNX"
+  | "LiquidAI/LFM2.5-1.2B-Thinking-GGUF"
+  | "LiquidAI/LFM3-VL-2B-GGUF"
+  | "LiquidAI/LFM3-VL-2B-ONNX"
+  | "unsloth/Qwen3.5-2B-GGUF"
+  | "onnx-community/Qwen3.5-2B-ONNX">>(true)
+
+test("a worker of your own has a WebGLLM of its own, shared by the adapters given it", async () => {
+  const worker = { postMessage: () => undefined, addEventListener: () => undefined, removeEventListener: () => undefined } as unknown as Worker
+  type WithEngine = { engine: { webgllm: unknown } }
+  const first = webgllmText(MODEL, { worker }) as unknown as WithEngine
+  const second = webgllmText(MODEL, { worker }) as unknown as WithEngine
+  const page = webgllmText(MODEL) as unknown as WithEngine
+  assert.equal(first.engine.webgllm, second.engine.webgllm)
+  assert.notEqual(first.engine.webgllm, page.engine.webgllm)
+  assert.ok(first.engine.webgllm instanceof WebGLLM)
+})