runonweb 0.0.1 → 0.0.2

package/README.md

@@ -106,6 +106,34 @@ cosineSimilarity(embeddings[0], embeddings[1])
 
 Base: all-MiniLM-L6-v2 (Apache-2.0). 384 dims, normalized.
 
+### Text classification: `runonweb/classify`
+
+```ts
+import { Classifier } from 'runonweb/classify'
+
+const classifier = new Classifier() // Kev-0.8B, ~750 MB, WebGPU or WASM
+// new Classifier({ size: 'large' }) // Kev-4B, ~2.7 GB, about 4× slower, more accurate
+const { answers } = await classifier.classify({
+  state: 'Shoes arrived two weeks late and in the wrong size.',
+  questions: {
+    department: { type: 'choice', instructions: 'Which team should handle this?',
+                  criteria: { returns: null, shipping: null, billing: null } },
+    escalate: { type: 'noul', instructions: 'Does this need urgent human attention?' },
+    frustration: { type: 'score', instructions: 'How frustrated is the customer?',
+                   criteria: ['Calm', 'Frustrated', 'Very angry'] },
+  },
+})
+answers.department  // { type: 'choice', choice: 'returns', confidence, probabilities: { returns: 0.50, … } }
+answers.escalate    // { type: 'noul', noul: 0.51 }  p(yes)
+answers.frustration // { type: 'score', score: 1.21, confidence, legend, probabilities }
+
+await classifier.classify(request, { dateFacts: true }) // adds day counts between dates in the state
+```
+
+Base: [Kev-0.8B](https://huggingface.co/jaredpalmer/kev-0.8b) by Jared Palmer (Apache-2.0), a Jev-style decision model: a LoRA and a pointer head on Qwen3.5-0.8B-Base (Apache-2.0). Requests and answers are TypeSafe's System One shapes (`noul` / `choice` / `score`), so the same JSON works against a Kev or Jev server; `noul()`, `choice()` and `score()` build questions like the Python SDK does. Nothing is generated: the text is read once, each question runs as its own row on the text's cache and a pointer head turns it into one probability per option, calibrated with the checkpoint's temperature (`temperature: 1` for raw logits).
+
+runonweb merged the LoRA, exported the backbone with the onnxruntime-genai builder (Gated DeltaNet as `LinearAttention` ops) and quantized it to int4 (Kev-0.8B keeps the DeltaNet layers in int8) (`training/kev-onnx`). WebGPU runs on `onnxruntime-web/webgpu` (the JSEP build only runs 2/4-bit `MatMulNBits`), WASM on `onnxruntime-web/wasm` (the WebGPU build has no CPU `GatherBlockQuantized`). Probabilities differ from the fp32 export by ~0.03 (small) and ~0.04 (large) on average. On sources Kev wasn't trained on, Kev-0.8B scores 0.70 and Kev-4B 0.84 (Jev 0.86); test on your own data.
+
 ### Translation: `runonweb/translate`
 
 ```ts
@@ -124,7 +152,7 @@ const multi = new Translator({ model: 'Xenova/m2m100_418M', from: 'fr', to: 'en'
 
 Base: Mozilla's [Firefox Translations](https://github.com/mozilla/translations) models (MPL-2.0), the same Marian NMT students Firefox ships. 17–44 MB per pair (int8), 106 direct pairs between English and 58 languages; other pairs pivot through English. They run in a Web Worker through the Bergamot WASM runtime (no COOP/COEP headers needed) and are cached in Cache Storage. `PAIRS` lists every pair with architecture, size and COMET score.
 
-Weights come from the runonweb mirror on the Hugging Face Hub by default. To self-host, run `node scripts/translate-models.mjs fetch en-es es-en` (or `--all`) and pass `modelPath` pointing at wherever you upload that folder; the script also copies the runtime so you can pass `runtimePath: '<modelPath>/runtime/'` instead of loading it from jsDelivr. The registry is regenerated from Mozilla's model list with `node scripts/translate-models.mjs registry`.
+Weights come from the runonweb mirror on the Hugging Face Hub ([`midudev/firefox-translations`](https://huggingface.co/midudev/firefox-translations)) by default. To self-host, run `node scripts/translate-models.mjs fetch en-es es-en` (or `--all`) and pass `modelPath` pointing at wherever you upload that folder; the script also copies the runtime so you can pass `runtimePath: '<modelPath>/runtime/'` instead of loading it from jsDelivr. The registry is regenerated from Mozilla's model list with `node scripts/translate-models.mjs registry`.
 
 ### Text-to-speech: `runonweb/tts`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runonweb",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Free browser ML modules: speech, vision, text. Runs locally with WebGPU or WASM.",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,16 @@
       "import": "./src/ocr/sizes.ts",
       "default": "./src/ocr/sizes.ts"
     },
+    "./classify": {
+      "types": "./src/classify/index.ts",
+      "import": "./src/classify/index.ts",
+      "default": "./src/classify/index.ts"
+    },
+    "./classify/sizes": {
+      "types": "./src/classify/sizes.ts",
+      "import": "./src/classify/sizes.ts",
+      "default": "./src/classify/sizes.ts"
+    },
     "./embed": {
       "types": "./src/embed/index.ts",
       "import": "./src/embed/index.ts",
@@ -114,6 +124,9 @@
     "background-removal",
     "ocr",
     "embeddings",
+    "classification",
+    "zero-shot",
+    "kev",
     "translation",
     "tts",
     "emoji",

package/src/classify/index.ts

@@ -0,0 +1,583 @@
+import type { Device, ProgressCallback, ProgressInfo, ResolvedDevice } from '../core/index.ts'
+import { resolveDevice } from '../core/device.ts'
+import { CACHE_NAME } from '../core/cache.ts'
+import {
+  toAnswers,
+  toRecord,
+  validateRequest,
+  withDateFacts,
+  type Answers,
+  type ClassifyRequest,
+  type DecisionRecord,
+  type Question,
+} from './request.ts'
+
+import { CLASSIFY_SIZES, DEFAULT_CLASSIFY_SIZE, type ClassifySize } from './sizes.ts'
+
+export * from './request.ts'
+export { CLASSIFY_SIZES, DEFAULT_CLASSIFY_SIZE, type ClassifySize } from './sizes.ts'
+
+/**
+ * Default weights: Kev-0.8B (Jared Palmer, Apache-2.0), a Jev-style decision model on Qwen3.5-0.8B-Base,
+ * with its LoRA merged in and exported to ONNX by runonweb (`training/kev-onnx`). int4 weights with the
+ * Gated DeltaNet layers in int8, fp32 activations: ~735 MB, the same file on WebGPU and WASM.
+ * `size: 'large'` loads Kev-4B instead.
+ */
+export const DEFAULT_MODEL = CLASSIFY_SIZES[DEFAULT_CLASSIFY_SIZE].model
+
+const ORT_WASM = 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.30.0/dist/'
+
+export type ClassifyOptions = {
+  /** `small` = Kev-0.8B (default), `large` = Kev-4B: more accurate, several times the download and latency. */
+  size?: ClassifySize
+  /** Hugging Face repo id, or folder name under `modelPath`. Overrides `size`. */
+  model?: string
+  /**
+   * Base URL the weights are served from, e.g. `/models/`: files are read from `<modelPath>/<model>/`.
+   * Omit to download `model` from the Hugging Face Hub.
+   */
+  modelPath?: string
+  device?: Device
+  /**
+   * Append the day count between every pair of absolute dates found in the state
+   * ("June 26, 2026 is 8 days before July 4, 2026"). Kev can't subtract dates; it can use a stated count.
+   * Same as Kev's `KEV_DATE_FACTS=1`. Default false.
+   */
+  dateFacts?: boolean
+  /**
+   * Softmax temperature. Defaults to the one fitted for the checkpoint (~2.35 for Kev-0.8B), which
+   * calibrates probabilities without changing any answer. `1` gives the raw logits.
+   */
+  temperature?: number
+  onProgress?: ProgressCallback
+}
+
+/** Per-call overrides of the constructor options. */
+export type ClassifyRunOptions = Pick<ClassifyOptions, 'dateFacts' | 'temperature'>
+
+export type ClassifyResult<Q extends Record<string, Question> = Record<string, Question>> = {
+  model: string
+  answers: Answers<Q>
+  usage: {
+    /** State tokens (counted once) plus every question's tokens. */
+    inputTokens: number
+  }
+  latencyMs: number
+}
+
+/** Layout of `kev.json`, written by `training/kev-onnx/assemble.py`. */
+type KevConfig = {
+  name: string
+  temperature: number
+  hidden_size: number
+  head_dim: number
+  head_file: string
+  /** `data` is one external-data file or several (big models are split under 2 GB per file). */
+  onnx: { model: string; data: string | string[] }
+  tokens: { state: number; question: number; option: number; option_end: number; decide: number }
+  max_state_tokens: number
+  max_row_tokens: number
+  cache: {
+    layer_types: ('linear_attention' | 'full_attention')[]
+    num_key_value_heads: number
+    attention_head_dim: number
+    conv_dim: number
+    conv_kernel: number
+    linear_heads: number
+    linear_key_dim: number
+    linear_value_dim: number
+  }
+}
+
+type Ort = typeof import('onnxruntime-web/webgpu')
+type OrtTensor = import('onnxruntime-web').Tensor
+type OrtSession = import('onnxruntime-web').InferenceSession
+type Tokenizer = { encode: (text: string, opts?: { add_special_tokens?: boolean }) => number[] }
+
+type Encoded = { state: number[]; rows: { ids: number[]; decide: number; options: number[] }[] }
+
+type Runtime = {
+  ort: Ort
+  session: OrtSession
+  tokenizer: Tokenizer
+  config: KevConfig
+  head: { qW: Float32Array; qB: Float32Array; kW: Float32Array; kB: Float32Array }
+  /** Cache inputs for an empty prefix (zero conv/recurrent states, zero-length KV). */
+  empty: Record<string, OrtTensor>
+  /** present.* output name → past.* input name. */
+  pastFor: Map<string, string>
+  device: ResolvedDevice
+}
+
+/**
+ * Typed questions about a text, answered with calibrated probabilities: yes/no (`noul`),
+ * multiple choice (`choice`) and ratings (`score`), all in one request. No text is generated.
+ *
+ * Runs Kev (github.com/jaredpalmer/kev) in the browser. Requests and answers follow TypeSafe's
+ * System One API (`POST /v1/systemone`), so the same JSON works against a Kev or Jev server.
+ *
+ * @example
+ * ```ts
+ * import { Classifier } from 'runonweb/classify'
+ *
+ * const classifier = new Classifier()
+ * await classifier.load()
+ *
+ * const { answers } = await classifier.classify({
+ *   state: 'Shoes arrived two weeks late and in the wrong size.',
+ *   questions: {
+ *     department: { type: 'choice', instructions: 'Which team should handle this?',
+ *                   criteria: { returns: null, shipping: null, billing: null } },
+ *     escalate: { type: 'noul', instructions: 'Does this need urgent human attention?' },
+ *     frustration: { type: 'score', instructions: 'How frustrated is the customer?',
+ *                    criteria: ['Calm', 'Frustrated', 'Very angry'] },
+ *   },
+ * })
+ * answers.department.choice // 'returns'
+ * answers.escalate.noul     // p(yes)
+ * ```
+ */
+export class Classifier {
+  #size: ClassifySize
+  #model: string
+  #modelPath?: string
+  #device: Device
+  #dateFacts: boolean
+  #temperature?: number
+  #onProgress?: ProgressCallback
+  #rt: Runtime | null = null
+  #loading: Promise<void> | null = null
+  #queue: Promise<unknown> = Promise.resolve()
+
+  constructor(options: ClassifyOptions = {}) {
+    this.#size = options.size ?? DEFAULT_CLASSIFY_SIZE
+    this.#model = options.model ?? CLASSIFY_SIZES[this.#size].model
+    this.#modelPath = options.modelPath
+    this.#device = options.device ?? 'auto'
+    this.#dateFacts = options.dateFacts ?? false
+    this.#temperature = options.temperature
+    this.#onProgress = options.onProgress
+  }
+
+  get size(): ClassifySize {
+    return this.#size
+  }
+
+  get device(): ResolvedDevice | null {
+    return this.#rt?.device ?? null
+  }
+
+  /** Calibration temperature in use (the checkpoint's unless overridden). */
+  get temperature(): number | null {
+    return this.#temperature ?? this.#rt?.config.temperature ?? null
+  }
+
+  async load(): Promise<void> {
+    if (this.#rt) return
+    if (this.#loading) return this.#loading
+    this.#loading = (async () => {
+      this.#rt = await loadRuntime(this.#baseUrl(), await resolveDevice(this.#device), this.#onProgress)
+    })()
+    try {
+      await this.#loading
+    } finally {
+      this.#loading = null
+    }
+  }
+
+  /**
+   * Answer every question about `state`. Each question only sees the state and itself;
+   * the state is read once and reused for every question.
+   */
+  async classify<const Q extends Record<string, Question>>(
+    request: ClassifyRequest<Q>,
+    options: ClassifyRunOptions = {}
+  ): Promise<ClassifyResult<Q>> {
+    validateRequest(request)
+    await this.load()
+    const run = this.#queue.then(() => this.#classify(request, options))
+    this.#queue = run.catch(() => undefined)
+    return run
+  }
+
+  async #classify<Q extends Record<string, Question>>(
+    request: ClassifyRequest<Q>,
+    options: ClassifyRunOptions
+  ): Promise<ClassifyResult<Q>> {
+    const rt = this.#rt
+    if (!rt) throw new Error('Classifier was disposed')
+    const t0 = performance.now()
+    this.#onProgress?.({ status: 'classifying' })
+
+    const dates = options.dateFacts ?? this.#dateFacts
+    const req = dates ? { ...request, state: withDateFacts(request.state) } : request
+    const { record, meta } = toRecord(req)
+    const enc = encode(rt, record)
+    const probs = await scoreRows(rt, enc, options.temperature ?? this.#temperature ?? rt.config.temperature)
+
+    this.#onProgress?.({ status: 'done' })
+    return {
+      model: rt.config.name,
+      answers: toAnswers(probs, meta) as Answers<Q>,
+      usage: { inputTokens: enc.state.length + enc.rows.reduce((n, r) => n + r.ids.length, 0) },
+      latencyMs: Math.round(performance.now() - t0),
+    }
+  }
+
+  dispose(): void {
+    const rt = this.#rt
+    this.#rt = null
+    void this.#queue.finally(() => rt?.session.release())
+  }
+
+  #baseUrl(): string {
+    if (this.#modelPath) {
+      const base = new URL(this.#modelPath.replace(/\/?$/, '/'), globalThis.location?.href).href
+      return `${base}${this.#model}/`
+    }
+    return `https://huggingface.co/${this.#model}/resolve/main/`
+  }
+}
+
+/** One-shot helper: load, classify, dispose. Keep a `Classifier` around for more than one call. */
+export async function classify<const Q extends Record<string, Question>>(
+  request: ClassifyRequest<Q>,
+  options?: ClassifyOptions
+): Promise<ClassifyResult<Q>> {
+  const classifier = new Classifier(options)
+  try {
+    return await classifier.classify(request)
+  } finally {
+    classifier.dispose()
+  }
+}
+
+export type { ProgressInfo, Device }
+
+// ---------------------------------------------------------------------------------------------------------------
+// Encoding (kev/model.py `encode`, row form)
+
+/** Caller text can never produce delimiter tokens: `<|name|>` is rewritten to `<¦name¦>` before tokenizing. */
+function userTokens(tok: Tokenizer, text: string): number[] {
+  return tok.encode(text.replace(/<\|([A-Za-z0-9_]+)\|>/g, '<¦$1¦>'), { add_special_tokens: false })
+}
+
+/**
+ * `[<state> …state…]`, then per question one row that continues the state:
+ * `<q> instructions <opt> option </opt> … <decide>`. Delimiters are rarely used Qwen special tokens.
+ */
+function encode(rt: Runtime, record: DecisionRecord): Encoded {
+  const { tokens: T, max_state_tokens, max_row_tokens } = rt.config
+  const state = [T.state, ...userTokens(rt.tokenizer, record.state)]
+  if (state.length > max_state_tokens) {
+    throw new Error(`State is ${state.length} tokens; the limit is ${max_state_tokens} (Kev was trained on up to 384)`)
+  }
+  const rows = record.questions.map((q) => {
+    const ids = [T.question, ...userTokens(rt.tokenizer, q.instr)]
+    const options: number[] = []
+    for (const o of q.options) {
+      ids.push(T.option, ...userTokens(rt.tokenizer, o), T.option_end)
+      options.push(ids.length - 1)
+    }
+    ids.push(T.decide)
+    if (state.length + ids.length > max_row_tokens) {
+      throw new Error(`State plus one question is ${state.length + ids.length} tokens; the limit is ${max_row_tokens}`)
+    }
+    return { ids, decide: ids.length - 1, options }
+  })
+  return { state, rows }
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Inference
+
+/**
+ * onnxruntime-web's WebGPU backend keeps a single global OrtRun slot; overlapping runs from any session
+ * fail with "Session already started". Every run in this module goes through one queue.
+ */
+let ortTurn: Promise<void> = Promise.resolve()
+
+function takeTurn<T>(fn: () => Promise<T>): Promise<T> {
+  const run = ortTurn.then(fn, fn)
+  ortTurn = run.then(
+    () => undefined,
+    () => undefined
+  )
+  return run
+}
+
+function int64(values: ArrayLike<number>, dims: number[], ort: Ort): OrtTensor {
+  const data = new BigInt64Array(values.length)
+  for (let i = 0; i < values.length; i++) data[i] = BigInt(values[i]!)
+  return new ort.Tensor('int64', data, dims)
+}
+
+/** input_ids, attention_mask and the 3-axis (M-RoPE) position ids for `ids` continuing `start` cached tokens. */
+function tokenFeeds(ort: Ort, ids: number[], start: number): Record<string, OrtTensor> {
+  const L = ids.length
+  const pos = new Array<number>(3 * L)
+  for (let a = 0; a < 3; a++) for (let i = 0; i < L; i++) pos[a * L + i] = start + i
+  return {
+    input_ids: int64(ids, [1, L], ort),
+    attention_mask: int64(new Array<number>(start + L).fill(1), [1, start + L], ort),
+    position_ids: int64(pos, [3, 1, L], ort),
+  }
+}
+
+/** Pointer head: `<decide>` vs each `</opt>`, `(k · q) / sqrt(d) / T`, softmax. */
+function readout(rt: Runtime, hidden: Float32Array, row: Encoded['rows'][number], temperature: number): Float64Array {
+  const H = rt.config.hidden_size
+  const D = rt.config.head_dim
+  const project = (W: Float32Array, b: Float32Array, at: number) => {
+    const out = new Float64Array(D)
+    const off = at * H
+    for (let i = 0; i < D; i++) {
+      let s = b[i]!
+      const w = i * H
+      for (let j = 0; j < H; j++) s += W[w + j]! * hidden[off + j]!
+      out[i] = s
+    }
+    return out
+  }
+  const q = project(rt.head.qW, rt.head.qB, row.decide)
+  const scale = 1 / Math.sqrt(D) / temperature
+  const z = row.options.map((at) => {
+    const k = project(rt.head.kW, rt.head.kB, at)
+    let dot = 0
+    for (let i = 0; i < D; i++) dot += k[i]! * q[i]!
+    return dot * scale
+  })
+  const max = Math.max(...z)
+  const e = z.map((v) => Math.exp(v - max))
+  const sum = e.reduce((a, b) => a + b, 0)
+  return Float64Array.from(e, (v) => v / sum)
+}
+
+/** State pass once, then each question's row on the state's cache (exact: rows are independent). */
+async function scoreRows(rt: Runtime, enc: Encoded, temperature: number): Promise<Float64Array[]> {
+  const { ort, session } = rt
+  const Ls = enc.state.length
+  const owned: OrtTensor[] = []
+  const dropOutputs = (out: Record<string, OrtTensor>, keep?: Set<string>) => {
+    for (const [name, t] of Object.entries(out)) if (name !== 'hidden_states' && !keep?.has(name)) disposeTensor(t)
+  }
+  try {
+    const stateOut = await takeTurn(() => session.run({ ...tokenFeeds(ort, enc.state, 0), ...rt.empty }))
+    disposeTensor(stateOut.hidden_states)
+    const past: Record<string, OrtTensor> = {}
+    for (const [present, pastName] of rt.pastFor) {
+      const t = stateOut[present]
+      if (!t) throw new Error(`Model output ${present} is missing`)
+      past[pastName] = t
+      owned.push(t)
+    }
+
+    const probs: Float64Array[] = []
+    for (const row of enc.rows) {
+      const out = await takeTurn(() => session.run({ ...tokenFeeds(ort, row.ids, Ls), ...past }))
+      try {
+        const hidden = (await out.hidden_states!.getData()) as Float32Array
+        probs.push(readout(rt, hidden, row, temperature))
+      } finally {
+        disposeTensor(out.hidden_states)
+        dropOutputs(out)
+      }
+    }
+    return probs
+  } finally {
+    for (const t of owned) disposeTensor(t)
+  }
+}
+
+function disposeTensor(t: OrtTensor | undefined): void {
+  // GPU-resident outputs hold a GPUBuffer until disposed; CPU tensors ignore this.
+  if (t && t.location === 'gpu-buffer') t.dispose()
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Loading
+
+async function loadRuntime(base: string, device: ResolvedDevice, onProgress?: ProgressCallback): Promise<Runtime> {
+  onProgress?.({ status: 'loading', progress: 0 })
+  const config = (await (await fetchCached(`${base}kev.json`)).json()) as KevConfig
+
+  const dataFiles = typeof config.onnx.data === 'string' ? [config.onnx.data] : config.onnx.data
+  const files = [config.onnx.model, config.head_file, 'tokenizer.json', 'tokenizer_config.json', ...dataFiles]
+  const progress = new ProgressTotals(onProgress)
+  const [model, head, tokenizerJson, tokenizerConfig, ...data] = await Promise.all(
+    files.map((file) => fetchBytes(`${base}${file}`, file, progress))
+  )
+
+  const { PreTrainedTokenizer } = await import('@huggingface/transformers')
+  const text = new TextDecoder()
+  const tokenizer = new PreTrainedTokenizer(
+    JSON.parse(text.decode(tokenizerJson)),
+    JSON.parse(text.decode(tokenizerConfig))
+  ) as unknown as Tokenizer
+
+  const D = config.head_dim
+  const H = config.hidden_size
+  const floats = new Float32Array(head!.buffer, head!.byteOffset, head!.byteLength / 4)
+  if (floats.length !== 2 * (D * H + D)) throw new Error('head.bin does not match kev.json')
+  const headW = {
+    qW: floats.subarray(0, D * H),
+    qB: floats.subarray(D * H, D * H + D),
+    kW: floats.subarray(D * H + D, 2 * D * H + D),
+    kB: floats.subarray(2 * D * H + D),
+  }
+
+  onProgress?.({ status: 'initializing' })
+  const { cache } = config
+  const pastFor = new Map<string, string>()
+  cache.layer_types.forEach((type, i) => {
+    if (type === 'full_attention') {
+      for (const kv of ['key', 'value']) pastFor.set(`present.${i}.${kv}`, `past_key_values.${i}.${kv}`)
+    } else {
+      pastFor.set(`present.${i}.conv`, `past.${i}.conv`)
+      pastFor.set(`present.${i}.recurrent`, `past.${i}.recurrent`)
+    }
+  })
+  // Zero conv/recurrent states and zero-length KV: the cache of an empty prefix.
+  const emptyCache = (ort: Ort) => {
+    const empty: Record<string, OrtTensor> = {}
+    const zeros = (dims: number[]) => new ort.Tensor('float32', new Float32Array(dims.reduce((a, b) => a * b)), dims)
+    cache.layer_types.forEach((type, i) => {
+      if (type === 'full_attention') {
+        for (const kv of ['key', 'value']) {
+          empty[`past_key_values.${i}.${kv}`] = zeros([1, cache.num_key_value_heads, 0, cache.attention_head_dim])
+        }
+      } else {
+        empty[`past.${i}.conv`] = zeros([1, cache.conv_dim, cache.conv_kernel])
+        empty[`past.${i}.recurrent`] = zeros([1, cache.linear_heads, cache.linear_key_dim, cache.linear_value_dim])
+      }
+    })
+    return empty
+  }
+
+  // External data is referenced by file name, relative to the .onnx file.
+  const externalData = dataFiles.map((file, i) => ({ path: file.split('/').pop()!, data: data[i]! }))
+  const create = async (ep: ResolvedDevice) => {
+    const ort = await loadOrt(ep)
+    const session = await ort.InferenceSession.create(model!, {
+      executionProviders: [ep],
+      externalData,
+      graphOptimizationLevel: 'all',
+      // Errors only: node-placement warnings ("Some nodes were not assigned…") are expected for shape ops.
+      logSeverityLevel: 3,
+      // Keep the state's cache on the GPU between the state pass and the question rows.
+      ...(ep === 'webgpu'
+        ? { preferredOutputLocation: Object.fromEntries([...pastFor.keys()].map((n) => [n, 'gpu-buffer' as const])) }
+        : {}),
+    })
+    return { ort, session, empty: emptyCache(ort) }
+  }
+
+  let runtime: Awaited<ReturnType<typeof create>>
+  let resolved = device
+  try {
+    runtime = await create(device)
+  } catch (err) {
+    if (device === 'wasm') throw err
+    console.warn('[runonweb/classify] WebGPU session failed, falling back to WASM:', err)
+    resolved = 'wasm'
+    runtime = await create('wasm')
+  }
+
+  onProgress?.({ status: 'ready', progress: 100 })
+  return { ...runtime, tokenizer, config, head: headW, pastFor, device: resolved }
+}
+
+const ortModules = new Map<ResolvedDevice, Promise<Ort>>()
+
+/**
+ * One ONNX Runtime Web build per backend. `onnxruntime-web/webgpu` is the native WebGPU EP: it runs 8-bit
+ * MatMulNBits, which the JSEP build in the default entry rejects, but its CPU side lacks GatherBlockQuantized
+ * (the int4 embeddings). `onnxruntime-web/wasm` has every CPU kernel the model needs.
+ */
+function loadOrt(ep: ResolvedDevice): Promise<Ort> {
+  let mod = ortModules.get(ep)
+  if (!mod) {
+    mod = (ep === 'webgpu' ? import('onnxruntime-web/webgpu') : import('onnxruntime-web/wasm')).then((ort) => {
+      if (typeof document !== 'undefined') ort.env.wasm.wasmPaths = ORT_WASM
+      return ort as Ort
+    })
+    ortModules.set(ep, mod)
+  }
+  return mod
+}
+
+class ProgressTotals {
+  #loaded = new Map<string, number>()
+  #total = new Map<string, number>()
+  #cb?: ProgressCallback
+
+  constructor(cb?: ProgressCallback) {
+    this.#cb = cb
+  }
+
+  update(file: string, loaded: number, total: number) {
+    this.#loaded.set(file, loaded)
+    this.#total.set(file, total)
+    if (!this.#cb) return
+    this.#cb({ status: 'progress', file, loaded, total, progress: total ? (loaded / total) * 100 : undefined })
+    let l = 0
+    let t = 0
+    for (const v of this.#loaded.values()) l += v
+    for (const v of this.#total.values()) t += v
+    if (t) this.#cb({ status: 'progress_total', loaded: l, total: t, progress: (l / t) * 100 })
+  }
+}
+
+async function openCache(): Promise<Cache | null> {
+  if (typeof caches === 'undefined') return null
+  return caches.open(CACHE_NAME).catch(() => null)
+}
+
+async function fetchCached(url: string): Promise<Response> {
+  const cache = await openCache()
+  const hit = await cache?.match(url)
+  if (hit) return hit
+  const res = await fetch(url)
+  if (!res.ok) throw new Error(`Could not load ${url} (${res.status})`)
+  await cache?.put(url, res.clone()).catch(() => undefined)
+  return res
+}
+
+/** Download into one buffer with progress, served from and stored in the shared model cache. */
+async function fetchBytes(url: string, file: string, progress: ProgressTotals): Promise<Uint8Array> {
+  const cache = await openCache()
+  const hit = await cache?.match(url)
+  if (hit) {
+    const bytes = new Uint8Array(await hit.arrayBuffer())
+    progress.update(file, bytes.byteLength, bytes.byteLength)
+    return bytes
+  }
+
+  const res = await fetch(url)
+  if (!res.ok) throw new Error(`Could not load ${file} (${res.status})`)
+  const total = Number(res.headers.get('content-length') ?? 0)
+  let bytes: Uint8Array
+  if (!res.body) {
+    bytes = new Uint8Array(await res.arrayBuffer())
+  } else {
+    const reader = res.body.getReader()
+    let buf = new Uint8Array(total || 1 << 20)
+    let received = 0
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      if (received + value.byteLength > buf.byteLength) {
+        const grown = new Uint8Array(Math.max(buf.byteLength * 2, received + value.byteLength))
+        grown.set(buf.subarray(0, received))
+        buf = grown
+      }
+      buf.set(value, received)
+      received += value.byteLength
+      progress.update(file, received, total || received)
+    }
+    bytes = received === buf.byteLength ? buf : buf.slice(0, received)
+  }
+  progress.update(file, bytes.byteLength, bytes.byteLength)
+  await cache?.put(url, new Response(bytes as BodyInit, { headers: { 'content-length': String(bytes.byteLength) } })).catch(() => undefined)
+  return bytes
+}

package/src/classify/request.ts

@@ -0,0 +1,283 @@
+/**
+ * Request / answer shapes for `runonweb/classify`. They follow TypeSafe's System One contract
+ * (`POST /v1/systemone`), which is also what Kev serves, so a request written for either runs here unchanged.
+ *
+ * Ported from `kev/api.py` (github.com/jaredpalmer/kev, Apache-2.0): same rendering of objects to text,
+ * same option strings, same answer math. Changing any string here changes what the model reads.
+ */
+
+export type JSONContent = string | number | boolean | null | undefined | JSONContent[] | { [key: string]: JSONContent }
+
+/** Yes/no question. The answer is the probability of yes. */
+export type NoulQuestion = {
+  type: 'noul'
+  instructions?: JSONContent
+  /** Optional descriptions of what counts as yes (`true`) and no (`false`). */
+  criteria?: { true?: JSONContent; false?: JSONContent }
+}
+
+/** Pick one option. Keys are the option names; values describe them (or `null`). */
+export type ChoiceQuestion = {
+  type: 'choice'
+  instructions?: JSONContent
+  criteria: Record<string, JSONContent>
+}
+
+/** Rate on an ordered scale. Levels go from lowest to highest. */
+export type ScoreQuestion = {
+  type: 'score'
+  instructions?: JSONContent
+  criteria: JSONContent[]
+}
+
+export type Question = NoulQuestion | ChoiceQuestion | ScoreQuestion
+
+export type ClassifyRequest<Q extends Record<string, Question> = Record<string, Question>> = {
+  /** The text to evaluate. Objects and arrays are rendered as labeled text. */
+  state: JSONContent
+  /** You choose the ids; the model never sees them. Each question only sees the state and itself. */
+  questions: Q
+}
+
+export type NoulAnswer = { type: 'noul'; noul: number }
+
+export type ChoiceAnswer<K extends string = string> = {
+  type: 'choice'
+  choice: K
+  /** `(p_max − 1/K) / (1 − 1/K)`. Not a measured accuracy rate. */
+  confidence: number
+  probabilities: Record<K, number>
+}
+
+export type ScoreAnswer = {
+  type: 'score'
+  /** Expected level index, starting at 0. */
+  score: number
+  /** How concentrated the distribution is around its most likely level. */
+  confidence: number
+  legend: Record<string, string>
+  probabilities: Record<string, number>
+}
+
+export type Answer = NoulAnswer | ChoiceAnswer | ScoreAnswer
+
+export type Answers<Q extends Record<string, Question>> = {
+  [K in keyof Q]: Q[K] extends NoulQuestion
+    ? NoulAnswer
+    : Q[K] extends ChoiceQuestion
+      ? ChoiceAnswer<Extract<keyof Q[K]['criteria'], string>>
+      : ScoreAnswer
+}
+
+export const MAX_OPTIONS = 255
+
+/** Build a yes/no question (same as TypeSafe's `Noul(...)`). */
+export const noul = (instructions: JSONContent, criteria?: NoulQuestion['criteria']): NoulQuestion => ({
+  type: 'noul',
+  instructions,
+  ...(criteria ? { criteria } : {}),
+})
+
+/** Build a multiple-choice question (same as TypeSafe's `Choice(...)`). */
+export const choice = <const C extends Record<string, JSONContent>>(instructions: JSONContent, criteria: C) => ({
+  type: 'choice' as const,
+  instructions,
+  criteria,
+})
+
+/** Build a rating question (same as TypeSafe's `Score(...)`). */
+export const score = (instructions: JSONContent, criteria: JSONContent[]): ScoreQuestion => ({
+  type: 'score',
+  instructions,
+  criteria,
+})
+
+/** A record the encoder reads: state text plus, per question, instruction text and option strings. */
+export type DecisionRecord = {
+  state: string
+  questions: { instr: string; options: string[] }[]
+}
+
+export type QuestionMeta = {
+  id: string
+  type: Question['type']
+  /** Keys probabilities are reported under, in option order. */
+  keys: string[]
+  legend?: Record<string, string>
+}
+
+const isScalar = (v: JSONContent): v is string | number | boolean =>
+  typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean'
+
+/** Python's `str()` for the scalars JSON can carry (Kev renders booleans as `True` / `False`). */
+function pyStr(v: string | number | boolean): string {
+  if (typeof v === 'boolean') return v ? 'True' : 'False'
+  return String(v)
+}
+
+/** Flatten str | object | array into the text the model sees. Field names are kept as labels. */
+export function render(v: JSONContent, indent = 0): string {
+  const pad = '  '.repeat(indent)
+  if (v === null || v === undefined) return ''
+  if (isScalar(v)) return pyStr(v)
+  if (Array.isArray(v)) return v.map((x) => `${pad}- ${render(x, indent + 1).trimStart()}`).join('\n')
+  return Object.entries(v)
+    .map(([k, x]) =>
+      x !== null && typeof x === 'object' ? `${pad}${k}:\n${render(x, indent + 1)}` : `${pad}${k}: ${render(x)}`
+    )
+    .join('\n')
+}
+
+export function optionText(name: string, desc: JSONContent): string {
+  return desc === null || desc === undefined || desc === '' ? name : `${name}: ${render(desc)}`
+}
+
+const MONTHS = 'January|February|March|April|May|June|July|August|September|October|November|December'
+const DATE_RE = new RegExp(`\\b(?:${MONTHS}) \\d{1,2}, \\d{4}\\b|\\b\\d{4}-\\d{2}-\\d{2}\\b`, 'g')
+
+function parseDate(raw: string): number | null {
+  let y: number, m: number, d: number
+  if (raw.includes(',')) {
+    const [month, day, year] = raw.replace(',', '').split(' ')
+    m = MONTHS.split('|').indexOf(month!) + 1
+    d = Number(day)
+    y = Number(year)
+  } else {
+    ;[y, m, d] = raw.split('-').map(Number) as [number, number, number]
+  }
+  const t = Date.UTC(y, m - 1, d)
+  const back = new Date(t)
+  if (back.getUTCFullYear() !== y || back.getUTCMonth() !== m - 1 || back.getUTCDate() !== d) return null
+  return t / 86_400_000
+}
+
+/**
+ * Day counts between every pair of absolute dates in `text` ("August 3, 2026 is 12 days after July 22, 2026.").
+ * Kev can't subtract dates reliably but uses a stated day count. Empty when fewer than two dates are found.
+ */
+export function dateFacts(text: string): string {
+  const found: [string, number][] = []
+  for (const m of text.matchAll(DATE_RE)) {
+    const raw = m[0]
+    const day = parseDate(raw)
+    if (day === null) continue
+    if (!found.some(([r]) => r === raw)) found.push([raw, day])
+  }
+  const facts: string[] = []
+  for (let i = 0; i < found.length; i++) {
+    for (let j = i + 1; j < found.length; j++) {
+      const n = found[j]![1] - found[i]![1]
+      const a = Math.abs(n)
+      facts.push(
+        n
+          ? `${found[j]![0]} is ${a} day${a !== 1 ? 's' : ''} ${n > 0 ? 'after' : 'before'} ${found[i]![0]}.`
+          : `${found[j]![0]} is the same day as ${found[i]![0]}.`
+      )
+    }
+  }
+  return facts.join(' ')
+}
+
+/** State with a `date_facts` field (objects), entry (arrays) or paragraph (text) when two or more dates appear. */
+export function withDateFacts(state: JSONContent): JSONContent {
+  const facts = dateFacts(render(state))
+  if (!facts) return state
+  if (Array.isArray(state)) return [...state, { date_facts: facts }]
+  if (state !== null && typeof state === 'object') return { ...state, date_facts: facts }
+  return `${render(state)}\n\ndate_facts: ${facts}`
+}
+
+function questionKeys(q: Question): string[] {
+  if (q.type === 'choice') return Object.keys(q.criteria)
+  if (q.type === 'noul') return ['false', 'true']
+  return q.criteria.map((_, i) => String(i))
+}
+
+/** Validate a request the way the Kev server does (it answers 422); throws a readable error instead. */
+export function validateRequest(req: ClassifyRequest): void {
+  if (!req || typeof req !== 'object') throw new TypeError('Request must be an object with `state` and `questions`')
+  const entries = Object.entries(req.questions ?? {})
+  if (entries.length === 0) throw new Error('`questions` needs at least one question')
+  for (const [id, q] of entries) {
+    if (!q || typeof q !== 'object') throw new Error(`Question "${id}" must be an object`)
+    if (q.type === 'choice') {
+      const n = Object.keys(q.criteria ?? {}).length
+      if (n < 1 || n > MAX_OPTIONS) throw new Error(`Choice "${id}" needs 1–${MAX_OPTIONS} options in \`criteria\``)
+    } else if (q.type === 'score') {
+      const n = Array.isArray(q.criteria) ? q.criteria.length : 0
+      if (n < 1 || n > MAX_OPTIONS) throw new Error(`Score "${id}" needs 1–${MAX_OPTIONS} levels in \`criteria\``)
+    } else if (q.type !== 'noul') {
+      throw new Error(`Question "${id}" has unknown type "${(q as { type?: string }).type}" (noul | choice | score)`)
+    }
+  }
+}
+
+/** Request → encoder record plus per-question metadata to map probabilities back. */
+export function toRecord(req: ClassifyRequest): { record: DecisionRecord; meta: QuestionMeta[] } {
+  const questions: DecisionRecord['questions'] = []
+  const meta: QuestionMeta[] = []
+  for (const [id, q] of Object.entries(req.questions)) {
+    const m: QuestionMeta = { id, type: q.type, keys: questionKeys(q) }
+    let options: string[]
+    if (q.type === 'noul') {
+      const c = q.criteria ?? {}
+      options = [optionText('no', c.false), optionText('yes', c.true)]
+    } else if (q.type === 'choice') {
+      options = Object.entries(q.criteria).map(([k, v]) => optionText(k, v))
+    } else {
+      options = q.criteria.map((x) => render(x))
+      m.legend = Object.fromEntries(m.keys.map((k, i) => [k, options[i]!]))
+    }
+    questions.push({ instr: render(q.instructions), options })
+    meta.push(m)
+  }
+  return { record: { state: render(req.state), questions }, meta }
+}
+
+const round = (x: number) => Math.round(x * 10_000) / 10_000
+
+export function choiceConfidence(p: ArrayLike<number>): number {
+  const K = p.length
+  return K === 1 ? 1 : (Math.max(...Array.from(p)) - 1 / K) / (1 - 1 / K)
+}
+
+export function scoreConfidence(p: ArrayLike<number>): number {
+  const L = p.length
+  if (L === 1) return 1
+  let mode = 0
+  for (let i = 1; i < L; i++) if (p[i]! > p[mode]!) mode = i
+  let spread = 0
+  for (let i = 0; i < L; i++) spread += p[i]! * Math.abs(i - mode)
+  return 1 - spread / (L - 1)
+}
+
+/** Probabilities per question → System One answers (4-decimal rounding, as served by Kev). */
+export function toAnswers(probs: Float64Array[], meta: QuestionMeta[]): Record<string, Answer> {
+  const out: Record<string, Answer> = {}
+  probs.forEach((p, qi) => {
+    const m = meta[qi]!
+    if (m.type === 'noul') {
+      out[m.id] = { type: 'noul', noul: round(p[1]!) }
+    } else if (m.type === 'choice') {
+      let best = 0
+      for (let i = 1; i < p.length; i++) if (p[i]! > p[best]!) best = i
+      out[m.id] = {
+        type: 'choice',
+        choice: m.keys[best]!,
+        confidence: round(choiceConfidence(p)),
+        probabilities: Object.fromEntries(m.keys.map((k, i) => [k, round(p[i]!)])),
+      }
+    } else {
+      let s = 0
+      for (let i = 0; i < p.length; i++) s += i * p[i]!
+      out[m.id] = {
+        type: 'score',
+        score: round(s),
+        confidence: round(scoreConfidence(p)),
+        legend: m.legend ?? {},
+        probabilities: Object.fromEntries(m.keys.map((k, i) => [k, round(p[i]!)])),
+      }
+    }
+  })
+  return out
+}

package/src/classify/sizes.ts

@@ -0,0 +1,26 @@
+export type ClassifySize = 'small' | 'large'
+
+/** Kev checkpoints packaged for the browser (`training/kev-onnx`). Accuracy is Kev's locked test on sources it never trained on. */
+export const CLASSIFY_SIZES: Record<
+  ClassifySize,
+  { label: string; model: string; base: string; params: string; downloadMB: string; outOfDomain: string }
+> = {
+  small: {
+    label: 'Small',
+    model: 'midudev/kev-0.8b-ONNX',
+    base: 'Kev-0.8B',
+    params: '0.8B',
+    downloadMB: '~750 MB',
+    outOfDomain: '0.70',
+  },
+  large: {
+    label: 'Large',
+    model: 'midudev/kev-4b-ONNX',
+    base: 'Kev-4B',
+    params: '4B',
+    downloadMB: '~2.7 GB',
+    outOfDomain: '0.84',
+  },
+}
+
+export const DEFAULT_CLASSIFY_SIZE: ClassifySize = 'small'

package/src/core/pipeline.ts

@@ -46,6 +46,11 @@ export async function loadPipeline(options: PipelineLoadOptions): Promise<Loaded
   options.onProgress?.({ status: 'loading', progress: 0 })
 
   const { pipeline, env } = await import('@huggingface/transformers')
+  // The threaded WASM build crashes with "memory access out of bounds" when the
+  // page is not cross-origin isolated (no SharedArrayBuffer). It happens at the
+  // end of the first download and a reload works. One thread avoids the spawn.
+  const wasm = env.backends?.onnx?.wasm
+  if (wasm && !globalThis.crossOriginIsolated) wasm.numThreads = 1
   if (options.modelPath) {
     env.allowLocalModels = true
     env.allowRemoteModels = false

package/src/core/progress.ts

@@ -2,6 +2,10 @@ export type ProgressInfo = {
   status: string
   progress?: number
   file?: string
+  /** Bytes received for this file, or for every file when `status` is `progress_total`. */
+  loaded?: number
+  /** Total bytes expected for the same scope as `loaded`. */
+  total?: number
 }
 
 export type ProgressCallback = (info: ProgressInfo) => void
@@ -16,5 +20,7 @@ export function toProgressInfo(data: Record<string, unknown>): ProgressInfo {
         ? (data.loaded / data.total) * 100
         : undefined
   const file = typeof data.file === 'string' ? data.file : undefined
-  return { status, progress, file }
+  const loaded = typeof data.loaded === 'number' ? data.loaded : undefined
+  const total = typeof data.total === 'number' ? data.total : undefined
+  return { status, progress, file, loaded, total }
 }

package/src/emoji/index.ts

@@ -4,16 +4,16 @@ import { loadPipeline } from '../core/pipeline.ts'
 /**
  * Default weights: `text2emoji-tiny`, a 2.4M-parameter T5 trained from scratch for runonweb
  * on the Text2Emoji dataset. 3.9 MB as q8 (encoder 1.7 MB + decoder 2.1 MB), MIT.
- * Trained with `training/text2emoji` in the runonweb repo.
+ * Trained with `training/text2emoji` in the runonweb repo. Published on the Hub as `midudev/text2emoji-tiny`.
  */
-export const DEFAULT_MODEL = 'text2emoji-tiny'
+export const DEFAULT_MODEL = 'midudev/text2emoji-tiny'
 
 export type EmojiOptions = {
   /** Model folder name (under `modelPath`) or Hugging Face repo id. */
   model?: string
   /**
-   * Base URL the weights are served from, e.g. `/models/`. The runonweb site self-hosts them
-   * in `public/models/`. Omit to download `model` from the Hugging Face Hub.
+   * Base URL the weights are served from, e.g. `/models/`: files are read from `<modelPath>/<model>/`.
+   * The runonweb site self-hosts them in `public/models/text2emoji-tiny/`. Omit to download `model` from the Hub.
    */
   modelPath?: string
   device?: Device
@@ -36,7 +36,7 @@ export type EmojiResult = {
  * ```ts
  * import { Emojifier } from 'runonweb/emoji'
  *
- * const emojifier = new Emojifier({ modelPath: '/models/' })
+ * const emojifier = new Emojifier()
  * await emojifier.load()
  * const { text } = await emojifier.emojify('I love pizza and my dog')
  * // "🍕❤️🐶"

package/src/image/index.ts

@@ -85,6 +85,8 @@ function mapLoadProgress(onProgress?: ProgressCallback): (status: Record<string,
       status: component ? `loading ${component}` : 'loading',
       progress: progress * 100,
       file: component,
+      loaded: loaded > 0 ? loaded : undefined,
+      total: total > 0 ? total : undefined,
     })
   }
 }

package/src/ocr/index.ts

@@ -324,7 +324,7 @@ async function fetchCached(
     if (done) break
     chunks.push(value)
     received += value.byteLength
-    onProgress?.({ status: 'progress', progress: (received / total) * 100, file })
+    onProgress?.({ status: 'progress', progress: (received / total) * 100, file, loaded: received, total })
   }
 
   const out = new Uint8Array(received)

package/src/stt/index.ts

@@ -36,6 +36,14 @@ export type TranscribeOptions = {
    * `translate` turns speech into English. Never the default here.
    */
   task?: 'transcribe' | 'translate'
+  /**
+   * Ask Whisper for timestamps. `"segment"` returns each phrase with the model's
+   * start and end, in seconds. `"word"` (or `true`) splits those phrases into
+   * words and keeps them inside the phrase span. This ONNX build has no
+   * cross-attentions, so it cannot time each word on its own. Omit it and
+   * `chunks` is empty.
+   */
+  timestamps?: boolean | 'word' | 'segment'
 }
 
 export type STTAudioInput = Blob | File | string | Float32Array
@@ -117,8 +125,8 @@ export class SpeechToText {
     this.#onProgress?.({ status: 'transcribing' })
 
     const input = await prepareAudio(audio)
-    const duration = input instanceof Float32Array ? input.length / SAMPLE_RATE : 0
     const onPartial = options?.onPartial
+    const timestampMode = resolveTimestamps(options?.timestamps)
     let streamed = ''
 
     const base: Record<string, unknown> = {
@@ -127,15 +135,14 @@ export class SpeechToText {
       // Always transcribe unless asked otherwise. Multilingual Whisper will
       // otherwise slip into "translate to English" when language is unknown.
       task: options?.task ?? 'transcribe',
-      // Word-timestamp mode disables timestamp tokens. Without this, decode
-      // throws "Whisper did not predict an ending timestamp" and the retry
-      // can come back empty after the streamer already showed text.
+      // Without this, a clip that ends mid-word throws and the retry can come
+      // back empty after the streamer already showed text.
       force_full_sequences: false,
     }
     const language = options?.language ?? this.#language
     if (language) base.language = language
 
-    const run = async (returnTimestamps: true | 'word', stream: boolean) => {
+    const run = async (stream: boolean) => {
       const streamer =
         stream && onPartial ? await createStreamer(this.#pipe!, (text) => {
           streamed = text
@@ -143,24 +150,26 @@ export class SpeechToText {
         }) : undefined
       return this.#pipe!(input, {
         ...base,
-        return_timestamps: returnTimestamps,
+        return_timestamps: timestampMode ? true : false,
         ...(streamer ? { streamer } : {}),
       })
     }
 
     let raw: RawResult | RawResult[]
     try {
-      // Segment timestamps + streamer is the reliable path. Word timestamps
-      // need a different generate() return shape and often fail once a streamer
-      // is attached, wiping the final text after a good partial stream.
-      raw = await run(true, true)
+      raw = await run(true)
     } catch {
-      raw = await run(true, false)
+      raw = await run(false)
     }
 
     const parsed = normalizeRaw(raw)
     const text = parsed.text || streamed
-    const chunks = explodeWords(parsed.chunks.length ? parsed.chunks : wordsFromText(text, duration), duration)
+    const chunks =
+      timestampMode === 'word'
+        ? wordsInsideSegments(parsed.chunks)
+        : timestampMode === 'segment'
+          ? parsed.chunks
+          : []
 
     this.#onProgress?.({ status: 'done' })
     return { text, chunks }
@@ -190,6 +199,38 @@ export async function transcribe(
   }
 }
 
+function resolveTimestamps(option: TranscribeOptions['timestamps']): 'word' | 'segment' | false {
+  if (option === true || option === 'word') return 'word'
+  if (option === 'segment') return 'segment'
+  return false
+}
+
+/** Place words inside the phrase span Whisper actually predicted. */
+function wordsInsideSegments(segments: STTChunk[]): STTChunk[] {
+  const words: STTChunk[] = []
+  for (const segment of segments) {
+    const parts = segment.text.trim().split(/\s+/).filter(Boolean)
+    if (!parts.length) continue
+    const start = segment.start
+    const end = Math.max(segment.end, start)
+    if (parts.length === 1) {
+      words.push({ text: parts[0]!, start, end })
+      continue
+    }
+    const weights = parts.map((part) => Math.max(1, part.length))
+    const total = weights.reduce((sum, weight) => sum + weight, 0)
+    const span = end - start
+    let cursor = start
+    parts.forEach((text, i) => {
+      const dur = span * (weights[i]! / total)
+      const next = i === parts.length - 1 ? end : cursor + dur
+      words.push({ text, start: cursor, end: next })
+      cursor = next
+    })
+  }
+  return words
+}
+
 async function createStreamer(pipe: ASRPipeline, onPartial: (text: string) => void) {
   const { WhisperTextStreamer } = await import('@huggingface/transformers')
   let acc = ''
@@ -218,8 +259,8 @@ function parseChunks(raw?: RawChunk[]): STTChunk[] {
   if (!raw?.length) return []
   const chunks: STTChunk[] = []
   for (const item of raw) {
-    const text = (item.text ?? '').replace(/\s+/g, ' ')
-    if (!text.trim()) continue
+    const text = (item.text ?? '').replace(/\s+/g, ' ').trim()
+    if (!text) continue
     const start = item.timestamp?.[0] ?? chunks.at(-1)?.end ?? 0
     const end = item.timestamp?.[1] ?? start
     chunks.push({ text, start, end: end < start ? start : end })
@@ -227,52 +268,6 @@ function parseChunks(raw?: RawChunk[]): STTChunk[] {
   return chunks
 }
 
-function wordsFromText(text: string, duration: number): STTChunk[] {
-  const parts = text.trim().split(/\s+/).filter(Boolean)
-  if (!parts.length) return []
-  const span = Math.max(0.04, (duration || parts.length * 0.35) / parts.length)
-  return parts.map((word, i) => ({
-    text: word,
-    start: i * span,
-    end: (i + 1) * span,
-  }))
-}
-
-/** Split segment chunks into words and align timestamps to the audio duration. */
-function explodeWords(raw: STTChunk[], duration: number): STTChunk[] {
-  const words: STTChunk[] = []
-  for (const chunk of raw) {
-    const parts = chunk.text.trim().split(/\s+/).filter(Boolean)
-    if (!parts.length) continue
-    if (parts.length === 1) {
-      words.push({ text: parts[0]!, start: chunk.start, end: Math.max(chunk.end, chunk.start) })
-      continue
-    }
-    const start = chunk.start
-    const end = Math.max(chunk.end, chunk.start)
-    const span = Math.max(0.04, (end - start || parts.length * 0.35) / parts.length)
-    parts.forEach((word, i) => {
-      words.push({
-        text: word,
-        start: start + i * span,
-        end: start + (i + 1) * span,
-      })
-    })
-  }
-  return alignToDuration(words, duration)
-}
-
-function alignToDuration(chunks: STTChunk[], duration: number): STTChunk[] {
-  if (!chunks.length) return chunks
-  const maxEnd = Math.max(...chunks.map((c) => Math.max(c.end, c.start)))
-  if (maxEnd <= 0.05 && duration > 0) return wordsFromText(chunks.map((c) => c.text).join(' '), duration)
-  if (duration > 0 && (maxEnd > duration * 1.2 || maxEnd < duration * 0.55)) {
-    const scale = duration / maxEnd
-    return chunks.map((c) => ({ ...c, start: c.start * scale, end: Math.max(c.end, c.start) * scale }))
-  }
-  return chunks
-}
-
 export type { ProgressInfo, Device }
 
 async function prepareAudio(audio: STTAudioInput): Promise<Float32Array | string> {

package/src/translate/bergamot.ts

@@ -8,7 +8,7 @@ import { WORKER_SOURCE } from './worker.ts'
  * Hugging Face Hub (MPL-2.0). Layout: `<modelPath><from>-<to>/<file>?rev=<revision>`.
  * Self-host by pointing `modelPath` at a folder produced by `scripts/translate-models.mjs`.
  */
-export const DEFAULT_MODEL_PATH = 'https://huggingface.co/runonweb/firefox-translations/resolve/main/'
+export const DEFAULT_MODEL_PATH = 'https://huggingface.co/midudev/firefox-translations/resolve/main/'
 
 export type BergamotOptions = {
   /** Base URL of the model files. Default: Hugging Face mirror. */
@@ -110,7 +110,13 @@ async function fetchFile(url: string, file: string, onProgress?: ProgressCallbac
   if (!res.ok) throw new Error(`Could not download ${file} (HTTP ${res.status}) from ${url}`)
 
   const buffer = await readWithProgress(res, (loaded, total) => {
-    onProgress?.({ status: 'progress', file, progress: total > 0 ? (loaded / total) * 100 : undefined })
+    onProgress?.({
+      status: 'progress',
+      file,
+      progress: total > 0 ? (loaded / total) * 100 : undefined,
+      loaded,
+      total: total > 0 ? total : undefined,
+    })
   })
 
   if (cache) {

package/src/tts/kitten.ts

@@ -175,7 +175,7 @@ async function fetchCached(url: string, file: string, onProgress?: ProgressCallb
     if (done) break
     chunks.push(value)
     received += value.byteLength
-    onProgress?.({ status: 'progress', progress: (received / total) * 100, file })
+    onProgress?.({ status: 'progress', progress: (received / total) * 100, file, loaded: received, total })
   }
 
   const out = new Uint8Array(received)