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

package/src/audio.ts

@@ -0,0 +1,79 @@
+/**
+ * Audio as llama.cpp reads it. Its multimodal library decodes WAV, MP3 and
+ * FLAC files itself, and resamples them to the model's rate. Anything else
+ * a browser records or plays (Opus in WebM or Ogg, AAC in MP4) is decoded
+ * here, with Web Audio, and handed over as WAV.
+ */
+
+/** The rate other formats are decoded at: the audio encoders' own, so llama.cpp resamples nothing. */
+const SAMPLE_RATE = 16000
+
+/** Whether `bytes` holds `text` (ASCII) at `at`. */
+const holds = (bytes: Uint8Array, at: number, text: string) =>
+  [...text].every((character, i) => bytes[at + i] === character.charCodeAt(0))
+
+/** Whether `data` is a WAV, FLAC or MP3 file, by how it starts: the files llama.cpp decodes. */
+export function decodesInLlama(data: ArrayBuffer): boolean {
+  const bytes = new Uint8Array(data, 0, Math.min(data.byteLength, 12))
+  if (bytes.length < 4) return false
+  if (holds(bytes, 0, "RIFF") && holds(bytes, 8, "WAVE")) return true
+  if (holds(bytes, 0, "fLaC")) return true
+  // An MP3 that opens with an ID3 tag, or with a frame: 11 sync bits, then
+  // Layer III (AAC's ADTS frames open the same way, as layer 0).
+  if (holds(bytes, 0, "ID3")) return true
+  const [first = 0, second = 0] = bytes
+  return first === 0xff && (second & 0xe0) === 0xe0 && (second & 0x06) === 0x02
+}
+
+/** Mono samples, each from -1 to 1, as a 16-bit PCM WAV file. */
+export function wavFile(samples: Float32Array, sampleRate: number): ArrayBuffer {
+  const size = samples.length * 2
+  const file = new DataView(new ArrayBuffer(44 + size))
+  const text = (at: number, value: string) => {
+    for (let i = 0; i < value.length; i++) file.setUint8(at + i, value.charCodeAt(i))
+  }
+  text(0, "RIFF")
+  file.setUint32(4, 36 + size, true)
+  text(8, "WAVE")
+  text(12, "fmt ")
+  file.setUint32(16, 16, true)
+  // PCM, one channel, 2 bytes a sample.
+  file.setUint16(20, 1, true)
+  file.setUint16(22, 1, true)
+  file.setUint32(24, sampleRate, true)
+  file.setUint32(28, sampleRate * 2, true)
+  file.setUint16(32, 2, true)
+  file.setUint16(34, 16, true)
+  text(36, "data")
+  file.setUint32(40, size, true)
+  samples.forEach((value, i) => {
+    const sample = Math.max(-1, Math.min(1, value))
+    file.setInt16(44 + i * 2, Math.round(sample < 0 ? sample * 0x8000 : sample * 0x7fff), true)
+  })
+  return file.buffer
+}
+
+/**
+ * An audio file's bytes as llama.cpp can decode them: as they are for WAV,
+ * MP3 and FLAC, else decoded by the browser and written as mono WAV.
+ */
+export async function llamaAudio(data: ArrayBuffer): Promise<ArrayBuffer> {
+  if (decodesInLlama(data)) return data
+  if (typeof OfflineAudioContext === "undefined") {
+    throw new Error("This audio isn't WAV, MP3 or FLAC, and there's no Web Audio here to decode it.")
+  }
+  let decoded: AudioBuffer
+  try {
+    // A copy: decoding detaches the buffer it's given.
+    decoded = await new OfflineAudioContext(1, 1, SAMPLE_RATE).decodeAudioData(data.slice(0))
+  } catch {
+    throw new Error("The browser couldn't decode this audio. WAV, MP3 and FLAC always work.")
+  }
+  const mono = new Float32Array(decoded.length)
+  for (let channel = 0; channel < decoded.numberOfChannels; channel++) {
+    decoded.getChannelData(channel).forEach((sample, i) => {
+      mono[i] = (mono[i] ?? 0) + sample / decoded.numberOfChannels
+    })
+  }
+  return wavFile(mono, decoded.sampleRate)
+}

package/src/catalog.ts

@@ -0,0 +1,399 @@
+/**
+ * The models this package knows: GGUF files on Hugging Face that run on the
+ * CPU with wllama, with what each supports, the sampling from its card, and
+ * how it writes tool calls.
+ */
+import type { ModelReasoning } from "@tanstack/ai"
+import type { ModelReasoningCapability } from "@tanstack/ai/adapter-internals"
+
+/**
+ * Sampling settings from a model's card, in llama.cpp's request fields (the
+ * names `modelOptions` takes): used unless a call's `modelOptions` sets them.
+ */
+export type Sampling = {
+  temperature: number
+  /** Left out where the card names none: llama.cpp's default. */
+  top_k?: number
+  /** llama.cpp's repetition penalty (`--repeat-penalty`). */
+  repeat_penalty: number
+  /** Nucleus sampling: the likeliest tokens up to this probability. */
+  top_p?: number
+  /** Drops tokens less likely than this share of the likeliest one's odds. */
+  min_p?: number
+  /** Lowers the odds of tokens that have appeared at all. */
+  presence_penalty?: number
+}
+
+export type WllamaModelMeta = {
+  /** The Hugging Face repository the GGUF file is in. */
+  name: string
+  /** The GGUF file in the repository. */
+  file: string
+  /** The projector's GGUF file in the repository, for a model that reads images or audio. */
+  mmproj?: string
+  supports: {
+    /** Text, and images or audio for a model whose projector reads them. */
+    input: ReadonlyArray<"text" | "image" | "audio">
+    output: ReadonlyArray<"text">
+    capabilities: ReadonlyArray<"tools" | "thinking">
+  }
+  /** Parameter count. */
+  size: string
+  /** Reasoning levels for `chat({ reasoning })`, read from the chat template. */
+  reasoning?: ModelReasoning
+  /** Sampling from the model card, used unless `modelOptions` overrides it. */
+  sampling: Sampling
+  /** The card's sampling while the chat template thinks, where it differs. */
+  thinkingSampling?: Sampling
+}
+
+// Reasoning shapes, each level's value being the chat template's
+// `enable_thinking`. LFM3's template takes it (thinking by default), and
+// Qwen3.5's (thinking off by default); LFM2.5 Thinking always thinks and
+// takes no switch.
+const THINKING_SWITCH = {
+  levels: { off: "false", high: "true" },
+  budget: true
+} as const
+const ALWAYS_THINKS = { levels: { high: "true" }, budget: true } as const
+
+const TOOLS_AND_THINKING = {
+  input: ["text"],
+  output: ["text"],
+  capabilities: ["tools", "thinking"]
+} as const
+const TOOLS = {
+  input: ["text"],
+  output: ["text"],
+  capabilities: ["tools"]
+} as const
+const IMAGES_AND_TOOLS = {
+  input: ["text", "image"],
+  output: ["text"],
+  capabilities: ["tools"]
+} as const
+const IMAGES_TOOLS_AND_THINKING = {
+  input: ["text", "image"],
+  output: ["text"],
+  capabilities: ["tools", "thinking"]
+} as const
+const AUDIO_AND_TOOLS = {
+  input: ["text", "audio"],
+  output: ["text"],
+  capabilities: ["tools"]
+} as const
+const IMAGES_AUDIO_AND_TOOLS = {
+  input: ["text", "image", "audio"],
+  output: ["text"],
+  capabilities: ["tools"]
+} as const
+const AUDIO = {
+  input: ["text", "audio"],
+  output: ["text"],
+  capabilities: []
+} as const
+
+/** LFM3's card: `--temp 0.1 --top-k 50 --repeat-penalty 1.1`. */
+const LFM3_SAMPLING = {
+  temperature: 0.1,
+  top_k: 50,
+  repeat_penalty: 1.1
+} as const satisfies Sampling
+/** The cards' llama.cpp settings: `--temp 0.1 --top-k 50 --repeat-penalty 1.05`. */
+const LFM2_5_SAMPLING = {
+  temperature: 0.1,
+  top_k: 50,
+  repeat_penalty: 1.05
+} as const satisfies Sampling
+/** LFM2.5-VL 450M's and 1.6B's cards: `--temp 0.1 --min-p 0.15 --repeat-penalty 1.05`. */
+const LFM2_5_VL_SAMPLING = {
+  temperature: 0.1,
+  min_p: 0.15,
+  repeat_penalty: 1.05
+} as const satisfies Sampling
+/** LFM2.5-VL 3B's card: `--temp 0.2 --top-k 50 --repeat-penalty 1.0`. */
+const LFM2_5_VL_3B_SAMPLING = {
+  temperature: 0.2,
+  top_k: 50,
+  repeat_penalty: 1
+} as const satisfies Sampling
+/** LFM2.5 Thinking's card: `--temp 0.05 --top-k 50 --repeat-penalty 1.05`. */
+const LFM2_5_THINKING_SAMPLING = {
+  temperature: 0.05,
+  top_k: 50,
+  repeat_penalty: 1.05
+} as const satisfies Sampling
+
+/** The audio models' cards: greedy decoding (`--temp 0`) for text. */
+const GREEDY_SAMPLING = {
+  temperature: 0,
+  repeat_penalty: 1
+} as const satisfies Sampling
+
+/** Qwen3.5's card, text tasks without thinking (its default). */
+const QWEN_3_5_SAMPLING = {
+  temperature: 1,
+  top_k: 20,
+  top_p: 1,
+  min_p: 0,
+  presence_penalty: 2,
+  repeat_penalty: 1
+} as const satisfies Sampling
+/** Qwen3.5's card, text tasks with thinking. */
+const QWEN_3_5_THINKING_SAMPLING = { ...QWEN_3_5_SAMPLING, top_p: 0.95, presence_penalty: 1.5 } as const satisfies Sampling
+
+// Liquid's models are Q4_K_M: in wllama's WebAssembly build it reads
+// prompts and writes tokens about three times as fast as Q4_0 (llama.cpp
+// has no WebAssembly SIMD kernel for Q4_0 to match its Q4_K one), and
+// faster than Q5_K_M, Q6_K and Q8_0, at 5% more size than Q4_0. LFM2.5
+// 1.2B on an M3 Ultra, 24 threads: Q4_K_M 231 prompt tokens/s and 112
+// tokens/s, Q4_0 (Liquid's QAD build too) 65 and 45.
+
+/**
+ * Liquid AI's LFM3 1.7B, from its official GGUF repository: thinks by
+ * default, or answers straight away with reasoning off. It needs wllama
+ * 3.13's llama.cpp, the first published with its architecture.
+ */
+const LFM3_1_7B = {
+  name: "LiquidAI/LFM3-1.7B-GGUF",
+  file: "LFM3-1.7B-Q4_K_M.gguf",
+  supports: TOOLS_AND_THINKING,
+  size: "1.7b",
+  reasoning: THINKING_SWITCH,
+  sampling: LFM3_SAMPLING
+} as const satisfies WllamaModelMeta
+
+// The vision models load with their projector in Q8_0, the smallest Liquid
+// publishes: it reads an image as the F16 one does in a third to half the size.
+
+/**
+ * LFM3-VL 2B: LFM3 with a vision encoder, from Liquid's GGUF repository.
+ * Thinks by default, as LFM3 does. 1.10 GB, and a 203 MB projector.
+ */
+const LFM3_VL_2B = {
+  name: "LiquidAI/LFM3-VL-2B-GGUF",
+  file: "LFM3-VL-2B-Q4_K_M.gguf",
+  mmproj: "mmproj-LFM3-VL-2B-Q8_0.gguf",
+  supports: IMAGES_TOOLS_AND_THINKING,
+  size: "2b",
+  reasoning: THINKING_SWITCH,
+  sampling: LFM3_SAMPLING
+} as const satisfies WllamaModelMeta
+
+/** LFM2.5-VL 3B, from Liquid's GGUF repository: 1.67 GB, and a 583 MB projector. */
+const LFM2_5_VL_3B = {
+  name: "LiquidAI/LFM2.5-VL-3B-GGUF",
+  file: "LFM2.5-VL-3B-Q4_K_M.gguf",
+  mmproj: "mmproj-LFM2.5-VL-3B-Q8_0.gguf",
+  supports: IMAGES_AND_TOOLS,
+  size: "3b",
+  sampling: LFM2_5_VL_3B_SAMPLING
+} as const satisfies WllamaModelMeta
+
+/** LFM2.5-VL 1.6B, from Liquid's GGUF repository: 731 MB, and a 583 MB projector. */
+const LFM2_5_VL_1_6B = {
+  name: "LiquidAI/LFM2.5-VL-1.6B-GGUF",
+  file: "LFM2.5-VL-1.6B-Q4_K_M.gguf",
+  mmproj: "mmproj-LFM2.5-VL-1.6b-Q8_0.gguf",
+  supports: IMAGES_AND_TOOLS,
+  size: "1.6b",
+  sampling: LFM2_5_VL_SAMPLING
+} as const satisfies WllamaModelMeta
+
+/** LFM2.5-VL 450M, from Liquid's GGUF repository: 229 MB, and a 103 MB projector. */
+const LFM2_5_VL_450M = {
+  name: "LiquidAI/LFM2.5-VL-450M-GGUF",
+  file: "LFM2.5-VL-450M-Q4_K_M.gguf",
+  mmproj: "mmproj-LFM2.5-VL-450m-Q8_0.gguf",
+  supports: IMAGES_AND_TOOLS,
+  size: "450m",
+  sampling: LFM2_5_VL_SAMPLING
+} as const satisfies WllamaModelMeta
+
+// The audio models answer in text here: their speech output needs
+// llama.cpp's speech APIs, which this adapter doesn't call. Their projector
+// is the audio encoder (and, for LFM3-Omni, the vision encoder too), in
+// Q8_0, as their cards pair it with the Q4_K_M model.
+
+/**
+ * LFM3-Omni 2B: reads images and audio (speech, or other sound) in one
+ * model, from Liquid's GGUF repository. It doesn't reason: every answer
+ * opens with an empty thinking block. 1.10 GB, and a 507 MB projector.
+ */
+const LFM3_OMNI_2B = {
+  name: "LiquidAI/LFM3-Omni-2B-GGUF",
+  file: "LFM3-Omni-2B-Q4_K_M.gguf",
+  mmproj: "mmproj-LFM3-Omni-2B-Q8_0.gguf",
+  supports: IMAGES_AUDIO_AND_TOOLS,
+  size: "2b",
+  sampling: GREEDY_SAMPLING
+} as const satisfies WllamaModelMeta
+
+/**
+ * LFM3-Audio 2B: reads audio (transcribes and translates speech in 18
+ * languages, answers questions about a recording, calls tools from a
+ * spoken request), from Liquid's GGUF repository. 1.10 GB, and a 304 MB
+ * projector.
+ */
+const LFM3_AUDIO_2B = {
+  name: "LiquidAI/LFM3-Audio-2B-GGUF",
+  file: "LFM3-Audio-2B-Q4_K_M.gguf",
+  mmproj: "mmproj-LFM3-Audio-2B-Q8_0.gguf",
+  supports: AUDIO_AND_TOOLS,
+  size: "2b",
+  sampling: GREEDY_SAMPLING
+} as const satisfies WllamaModelMeta
+
+/**
+ * LFM2.5-Audio 1.5B: reads audio, in English, from Liquid's GGUF
+ * repository, which has no Q4_K_M: Q4_0, 696 MB, and a 220 MB projector.
+ * It calls no tools: told of tools, it answers that none of them can hear
+ * a recording, so it's best sent none.
+ */
+const LFM2_5_AUDIO_1_5B = {
+  name: "LiquidAI/LFM2.5-Audio-1.5B-GGUF",
+  file: "LFM2.5-Audio-1.5B-Q4_0.gguf",
+  mmproj: "mmproj-LFM2.5-Audio-1.5B-Q4_0.gguf",
+  supports: AUDIO,
+  size: "1.5b",
+  sampling: GREEDY_SAMPLING
+} as const satisfies WllamaModelMeta
+
+/** Liquid AI's LFM2.5 1.2B Instruct, from its official GGUF repository. */
+const LFM2_5_1_2B = {
+  name: "LiquidAI/LFM2.5-1.2B-Instruct-GGUF",
+  file: "LFM2.5-1.2B-Instruct-Q4_K_M.gguf",
+  supports: TOOLS,
+  size: "1.2b",
+  sampling: LFM2_5_SAMPLING
+} as const satisfies WllamaModelMeta
+
+/** LFM2.5 1.2B Thinking: thinks before every answer. */
+const LFM2_5_1_2B_THINKING = {
+  name: "LiquidAI/LFM2.5-1.2B-Thinking-GGUF",
+  file: "LFM2.5-1.2B-Thinking-Q4_K_M.gguf",
+  supports: TOOLS_AND_THINKING,
+  size: "1.2b",
+  reasoning: ALWAYS_THINKS,
+  sampling: LFM2_5_THINKING_SAMPLING
+} as const satisfies WllamaModelMeta
+
+/**
+ * LFM2.5 350M: the smallest and quickest, for short answers, extraction and
+ * tool calls rather than knowledge or code.
+ */
+const LFM2_5_350M = {
+  name: "LiquidAI/LFM2.5-350M-GGUF",
+  file: "LFM2.5-350M-Q4_K_M.gguf",
+  supports: TOOLS,
+  size: "350m",
+  sampling: LFM2_5_SAMPLING
+} as const satisfies WllamaModelMeta
+
+/**
+ * Qwen3.5 2B, in Unsloth's GGUF build (Qwen publishes none): linear-attention
+ * layers with a full-attention layer every fourth, so the attention cache
+ * stays small. Thinking is off unless turned on. Q4_K_M, as Liquid's: 1.28
+ * GB.
+ */
+const QWEN_3_5_2B = {
+  name: "unsloth/Qwen3.5-2B-GGUF",
+  file: "Qwen3.5-2B-Q4_K_M.gguf",
+  supports: TOOLS_AND_THINKING,
+  size: "2b",
+  reasoning: THINKING_SWITCH,
+  sampling: QWEN_3_5_SAMPLING,
+  thinkingSampling: QWEN_3_5_THINKING_SAMPLING
+} as const satisfies WllamaModelMeta
+
+export const WLLAMA_CHAT_MODELS = [
+  LFM3_1_7B.name,
+  LFM3_VL_2B.name,
+  LFM2_5_VL_3B.name,
+  LFM2_5_VL_1_6B.name,
+  LFM2_5_VL_450M.name,
+  LFM3_OMNI_2B.name,
+  LFM3_AUDIO_2B.name,
+  LFM2_5_AUDIO_1_5B.name,
+  LFM2_5_1_2B.name,
+  LFM2_5_1_2B_THINKING.name,
+  LFM2_5_350M.name,
+  QWEN_3_5_2B.name
+] as const
+
+/** A model this package lists. */
+export type WllamaChatModel = (typeof WLLAMA_CHAT_MODELS)[number]
+
+/** Each listed model's metadata, by name. */
+export const WLLAMA_MODEL_META: Readonly<
+  Record<WllamaChatModel, WllamaModelMeta>
+> = {
+  [LFM3_1_7B.name]: LFM3_1_7B,
+  [LFM3_VL_2B.name]: LFM3_VL_2B,
+  [LFM2_5_VL_3B.name]: LFM2_5_VL_3B,
+  [LFM2_5_VL_1_6B.name]: LFM2_5_VL_1_6B,
+  [LFM2_5_VL_450M.name]: LFM2_5_VL_450M,
+  [LFM3_OMNI_2B.name]: LFM3_OMNI_2B,
+  [LFM3_AUDIO_2B.name]: LFM3_AUDIO_2B,
+  [LFM2_5_AUDIO_1_5B.name]: LFM2_5_AUDIO_1_5B,
+  [LFM2_5_1_2B.name]: LFM2_5_1_2B,
+  [LFM2_5_1_2B_THINKING.name]: LFM2_5_1_2B_THINKING,
+  [LFM2_5_350M.name]: LFM2_5_350M,
+  [QWEN_3_5_2B.name]: QWEN_3_5_2B
+}
+
+const WLLAMA_REASONING = {
+  [LFM3_1_7B.name]: LFM3_1_7B.reasoning,
+  [LFM3_VL_2B.name]: LFM3_VL_2B.reasoning,
+  [LFM2_5_1_2B_THINKING.name]: LFM2_5_1_2B_THINKING.reasoning,
+  [QWEN_3_5_2B.name]: QWEN_3_5_2B.reasoning
+} as const
+
+/** The reasoning levels of each listed model that reasons. */
+export type WllamaModelReasoningByName = {
+  [K in keyof typeof WLLAMA_REASONING]: ModelReasoningCapability<
+    (typeof WLLAMA_REASONING)[K]
+  >
+}
+
+/**
+ * Reasoning data of each listed model that reasons, for
+ * `supportedReasoningLevels()`. A model missing here doesn't reason.
+ */
+export const WLLAMA_MODEL_REASONING: Readonly<Record<string, ModelReasoning>> =
+  WLLAMA_REASONING
+
+/** A listed model's metadata. */
+export const modelMeta = (model: WllamaChatModel): WllamaModelMeta =>
+  WLLAMA_MODEL_META[model]
+
+/** A model the catalog lists, a GGUF file's URL, or a GGUF file on Hugging Face as `owner/repo/file.gguf`. */
+export type WllamaModel = WllamaChatModel | (string & {})
+
+/** Whether the catalog lists `model`. */
+export const listed = (model: string): model is WllamaChatModel =>
+  Object.prototype.hasOwnProperty.call(WLLAMA_MODEL_META, model)
+
+/** Where a listed model's projector downloads from; none for a model that reads text only. */
+export const mmprojUrl = (model: WllamaModel) => {
+  if (!listed(model)) return undefined
+  const { name, mmproj } = modelMeta(model)
+  return mmproj && `https://huggingface.co/${name}/resolve/main/${mmproj}`
+}
+
+/**
+ * Where a model's GGUF file downloads from: a listed model's file, or the
+ * named one, at its latest version (main) on Hugging Face.
+ */
+export const modelUrl = (model: WllamaModel) => {
+  if (listed(model)) {
+    const { name, file } = modelMeta(model)
+    return `https://huggingface.co/${name}/resolve/main/${file}`
+  }
+  if (/^https?:\/\//.test(model)) return model
+  const [owner, repo, ...path] = model.split("/")
+  if (!owner || !repo || path.length === 0 || !model.endsWith(".gguf")) {
+    throw new Error(`${model} isn't a model this package lists: name its GGUF file, as "owner/repo/file.gguf" or a URL.`)
+  }
+  return `https://huggingface.co/${owner}/${repo}/resolve/main/${path.join("/")}`
+}

package/src/client.ts

@@ -0,0 +1,195 @@
+/**
+ * The page's side of wllama: llama.cpp compiled to WebAssembly, which runs
+ * in wllama's own Web Worker. One model at a time: loading another frees
+ * the previous one. wllama downloads models to the Origin Private File
+ * System once, and loads them from there afterwards.
+ *
+ * wllama is the official `@wllama/wllama` package, unmodified, used through
+ * its public API. Its package has no `exports` and its `main` names a file
+ * it doesn't ship, so its built ES module is imported by path.
+ */
+import { LoggerWithoutDebug, ModelManager, Wllama } from "@wllama/wllama/esm/index.js"
+import type { WllamaCompat } from "@wllama/wllama/esm/index.js"
+
+import { mmprojUrl, modelUrl } from "./catalog.js"
+import type { WllamaModel } from "./catalog.js"
+
+/**
+ * Where a model stands in this browser, with the Prompt API's values
+ * (`LanguageModel.availability()`).
+ */
+export type Availability = "unavailable" | "downloadable" | "downloading" | "available"
+
+/** A download's progress, from 0 to 1. */
+export type DownloadProgressCallback = (progress: number) => void
+
+/** What a model loads with. A load with other settings loads the model again. */
+export type LoadSettings = {
+  /** Most tokens a chat may hold; undefined for the model's training context. */
+  contextLength?: number
+  /** Where wllama's WebAssembly file is served (`WLLAMA_WASM_URL` by default). */
+  wasmUrl?: string
+  /** wllama's compat build, for browsers without JSPI (Safari), passed to `Wllama.setCompat`. */
+  compat?: WllamaCompat
+  /** CPU threads; wllama's default otherwise. */
+  threads?: number
+  /** `false` to run on the CPU only. */
+  gpu?: boolean
+  /** wllama's and llama.cpp's logs, in the console. */
+  debug?: boolean
+}
+
+/** The version of `@wllama/wllama` this package depends on. */
+export const WLLAMA_VERSION = "3.13.0"
+
+/**
+ * wllama's WebAssembly file on jsDelivr, for `WLLAMA_VERSION`: the URL of
+ * wllama's own `WasmFromCDN`. It has to match wllama's JavaScript, so it's
+ * the same version.
+ */
+export const WLLAMA_WASM_URL = `https://cdn.jsdelivr.net/npm/@wllama/wllama@${WLLAMA_VERSION}/esm/wasm/wllama.wasm`
+
+/** The model wllama holds (or is loading). */
+let loaded: {
+  model: WllamaModel
+  key: string
+  wllama: Wllama
+  promise: Promise<Wllama>
+  ready: boolean
+  /** Stops its download. */
+  abort: AbortController
+  /** The waiting callers' progress callbacks. */
+  listeners: Set<DownloadProgressCallback>
+} | null = null
+
+/** Models whose file is downloading in this page. */
+const downloading = new Set<WllamaModel>()
+
+/** Waits for `promise` until `signal` aborts; the load goes on. */
+const abortable = <T>(promise: Promise<T>, signal: AbortSignal | undefined) =>
+  signal
+    ? Promise.race([
+        promise,
+        new Promise<never>((_, reject) => {
+          if (signal.aborted) reject(signal.reason)
+          signal.addEventListener("abort", () => reject(signal.reason), { once: true })
+        })
+      ])
+    : promise
+
+/** Ends of unloaded wllamas, in turn: a new load starts once the previous one has ended. */
+let teardown: Promise<void> = Promise.resolve()
+
+/** Frees the loaded model, stopping its download. Given a model, only if it's the one loaded. */
+export async function unloadModel(model?: WllamaModel) {
+  const current = loaded
+  if (!current || (model !== undefined && current.model !== model)) return
+  loaded = null
+  downloading.delete(current.model)
+  current.abort.abort()
+  teardown = teardown.then(() => current.wllama.exit()).catch(() => undefined)
+  await teardown
+}
+
+/**
+ * The model, loaded with `settings` (downloading it the first time), in
+ * place of any other. `onDownloadProgress` hears the download, 0 to 1,
+ * then 1 once the model is ready. Aborting `signal` stops this caller's
+ * wait; `unloadModel` stops the load.
+ */
+export async function loadModel(
+  model: WllamaModel,
+  settings: LoadSettings,
+  { onDownloadProgress, signal }: { onDownloadProgress?: DownloadProgressCallback; signal?: AbortSignal } = {}
+): Promise<Wllama> {
+  signal?.throwIfAborted()
+  // A name that isn't a model throws here, before anything is unloaded.
+  const url = modelUrl(model)
+  const projector = mmprojUrl(model)
+  const key = JSON.stringify(settings)
+  if (loaded?.model !== model || loaded.key !== key) {
+    // Published at once, so a call meanwhile shares this load.
+    void unloadModel()
+    const wllama = new Wllama(
+      { default: settings.wasmUrl ?? WLLAMA_WASM_URL },
+      { logger: settings.debug ? console : LoggerWithoutDebug, suppressNativeLog: !settings.debug }
+    )
+    if (settings.compat) wllama.setCompat(settings.compat)
+    const abort = new AbortController()
+    // This caller's callback first: wllama may report progress at once.
+    const listeners = new Set<DownloadProgressCallback>(onDownloadProgress ? [onDownloadProgress] : [])
+    const promise = teardown
+      .then(() => {
+        abort.signal.throwIfAborted()
+        return wllama.loadModelFromUrl(projector ? { url, mmprojUrl: projector } : url, {
+          signal: abort.signal,
+          progressCallback: ({ loaded: bytes, total }) => {
+            // A model in storage reports its whole size once, without downloading.
+            if (!total || bytes >= total) return
+            downloading.add(model)
+            for (const listener of listeners) listener(bytes / total)
+          },
+          // 0: llama.cpp's "the model's training context" (wllama's default is 1,024).
+          n_ctx: settings.contextLength ?? 0,
+          // The whole context in sliding-window layers' cache (LFM3's), so a
+          // follow-up reuses what was read before.
+          swa_full: true,
+          ...(settings.gpu === false && { n_gpu_layers: 0 }),
+          ...(settings.threads && { n_threads: settings.threads })
+        })
+      })
+      .then(() => {
+        // Unloaded meanwhile: a load that ends anyway (from storage) is stale.
+        abort.signal.throwIfAborted()
+        return wllama
+      })
+      .finally(() => downloading.delete(model))
+    const current = { model, key, wllama, promise, ready: false, abort, listeners }
+    loaded = current
+    promise.then(
+      () => {
+        current.ready = true
+      },
+      () => {
+        if (loaded === current) void unloadModel(model)
+      }
+    )
+  }
+  const current = loaded
+  if (onDownloadProgress) current.listeners.add(onDownloadProgress)
+  try {
+    const wllama = await abortable(current.promise, signal)
+    onDownloadProgress?.(1)
+    return wllama
+  } finally {
+    if (onDownloadProgress) current.listeners.delete(onDownloadProgress)
+  }
+}
+
+/** wllama's model storage, read from the page (the Origin Private File System). */
+let storage: ModelManager | undefined
+
+/**
+ * Where `model` stands in this browser, with the Prompt API's values:
+ * "unavailable" where wllama can't run (no WebAssembly, Web Worker or
+ * Origin Private File System), "downloading" while this page downloads it,
+ * "available" when it's loaded or its file is in wllama's storage, else
+ * "downloadable". It reads storage only.
+ */
+export async function availability(model: WllamaModel): Promise<Availability> {
+  const runs =
+    typeof WebAssembly !== "undefined" &&
+    typeof Worker !== "undefined" &&
+    typeof navigator !== "undefined" &&
+    typeof navigator.storage?.getDirectory === "function"
+  if (!runs) return "unavailable"
+  if (downloading.has(model)) return "downloading"
+  if (loaded?.model === model && loaded.ready) return "available"
+  try {
+    storage ??= new ModelManager()
+    const saved = await storage.getModels()
+    return saved.some((m) => m.url === modelUrl(model)) ? "available" : "downloadable"
+  } catch {
+    return "downloadable"
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * TanStack AI adapter for GGUF models that run in the browser with wllama
+ * (llama.cpp in WebAssembly). The model catalog (model-meta.ts) is exported
+ * here too.
+ */
+export { wllamaText, WllamaTextAdapter } from "./adapter.js"
+export type { WllamaConfig, WllamaTextModelOptions } from "./adapter.js"
+export type { Availability, DownloadProgressCallback } from "./client.js"
+export type { WllamaModel } from "./catalog.js"
+export { WLLAMA_CHAT_MODELS, WLLAMA_MODEL_META, WLLAMA_MODEL_REASONING } from "./catalog.js"
+export type { WllamaChatModel, WllamaModelMeta, WllamaModelReasoningByName } from "./catalog.js"